Agent Workflows

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.

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.

// 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:

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.

Tip

Always move the task to “Doing” before starting work. This prevents other agents from picking up the same task.

Example: completion comment

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

<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:

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.

Build coordinator

A separate coordinator agent handles integration:

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”.

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

Note

Task descriptions and comments must use HTML, not Markdown. Use <p>, <ul>, <li>, <code>, and <strong> tags.