# Agent Workflows

Patterns for AI agents working with Hypertask tasks.

import { Aside, Steps, Tabs, TabItem } from '@astrojs/starlight/components';

This guide covers the recommended patterns for AI agents that use Hypertask as their task management backend. Follow these workflows to keep your boards organized and your team informed.

## Picking up work

When an agent session starts, it should find the highest-priority available work.

<Steps>

1. **Check the inbox** -- call `hypertask_inbox_list` to see if any tasks were assigned or moved back for rework.
2. **List tasks** -- call `hypertask_list_tasks` with the target `board_id` to see all open tasks, filtered by section (e.g., "Todo" or "Backlog").
3. **Pick the highest priority** -- select the task with the highest priority (`urgent` > `high` > `medium` > `low`). If priorities are equal, pick the oldest task.

</Steps>

```
// Example: list open tasks on board 15, sorted by priority
hypertask_list_tasks({
  board_id: 15,
  section: "Todo",
  assigned_to: "me"
})
```

## Working on a task

Once you have picked a task, follow this lifecycle:

<Steps>

1. **Move to "Doing"** -- immediately call `hypertask_update_task` to move the task to your in-progress section. This signals to other agents and humans that the task is claimed.

2. **Read the full context** -- call `hypertask_get_tasks` to get the task description, then `hypertask_get_comments_for_task` to read any discussion or feedback.

3. **Do the work** -- complete whatever the task requires. If the task was moved back from Review, check the latest comment for rejection feedback.

4. **Add a completion comment** -- call `hypertask_add_comment_to_task` with a detailed HTML summary of what was done, what files were changed, and any gotchas.

5. **Move to "Review"** -- call `hypertask_update_task` to move the task to the review section.

</Steps>

<Aside type="tip">
Always move the task to "Doing" **before** starting work. This prevents other agents from picking up the same task.
</Aside>

### Example: completion comment

Comments use HTML, not Markdown. Here is a well-structured completion comment:

```html
<p>Implemented the user avatar component.</p>
<ul>
  <li>Added <code>Avatar.tsx</code> with size variants (sm, md, lg)</li>
  <li>Integrated with the user profile API</li>
  <li>Added fallback to initials when no photo is available</li>
</ul>
<p>Ready for review.</p>
```

## Creating tasks

Use `hypertask_create_task` when you need to break work into subtasks or log follow-up items.

```
hypertask_create_task({
  project_id: 15,
  title: "Add error handling to upload endpoint",
  description: "<p>The upload endpoint returns 500 on invalid file types. Add validation and return 400 with a descriptive error message.</p>",
  priority: "high"
})
```

Required fields are `project_id` and `title`. The description should be HTML.

## Searching tasks

Hypertask uses Typesense for full-text search across all tasks you have access to. Use `hypertask_search_tasks` when you need to find a task by keyword, check for duplicates before creating a new task, or locate related work.

```
hypertask_search_tasks({
  query: "upload validation",
  board_id: 15,
  limit: 10
})
```

The search covers task titles and descriptions. Results are ranked by relevance.

## Multi-agent coordination

When multiple agents work on the same project, use this pattern to avoid conflicts:

### Worker agents

Each worker agent operates independently:

<Steps>

1. Claim a ticket by moving it to "Doing".
2. Complete the work.
3. Add a detailed completion comment.
4. Move the task to "Review".
5. Stop. Do not deploy or push.

</Steps>

### Build coordinator

A separate coordinator agent handles integration:

<Steps>

1. Monitor the "Review" section for completed tasks.
2. Pull the latest code.
3. Run tests and verify the changes.
4. Bump the version, commit, push, and deploy.
5. Move the task to "Done".

</Steps>

This separation ensures that only one agent handles deployments, preventing conflicts and broken builds.

## Best practices

| Practice | Why |
|----------|-----|
| Always move to "Doing" before starting | Prevents duplicate work by other agents |
| Use HTML in comments and descriptions | Markdown is not rendered -- HTML is the native format |
| Check inbox at the start of each session | Catches assigned tasks and rework requests |
| Add detailed completion comments | Helps reviewers (human or agent) understand what changed |
| Check for existing tasks before creating | Use `hypertask_search_tasks` to avoid duplicates |
| Include file paths and version numbers in comments | Makes it easy to trace changes back to the code |

<Aside type="note">
Task descriptions and comments must use **HTML**, not Markdown. Use `<p>`, `<ul>`, `<li>`, `<code>`, and `<strong>` tags.
</Aside>