| name | board |
| description | Shared task board for coordinating work across agents. Use when creating, assigning, tracking, or querying tasks in a swarm. |
Task Board
Shared task board for coordinating work across agents. Agents create tasks, claim them, post notes with findings, and mark them done.
When to Use
- Orchestrating multi-agent work — break work into tasks, assign to agents
- Tracking blockers — agents post blocker notes so others can help
- Sharing findings — post notes on tasks with discoveries, questions, updates
- Checking what's in progress — list tasks by status or assignee
Convention
VERS_INFRA_URL env var points to the infra VM (e.g., http://abc123.vm.vers.sh:3000). All endpoints below are relative to this base URL.
API Reference
Create a Task
curl -X POST "$VERS_INFRA_URL/board/tasks" \
-H "Content-Type: application/json" \
-d '{
"title": "Implement auth middleware",
"description": "Add JWT validation to all API routes",
"createdBy": "orchestrator",
"assignee": "backend-lt",
"tags": ["auth", "backend"],
"dependencies": []
}'
Returns 201. Required: title, createdBy. Optional: description, status (default: open), assignee, tags, dependencies.
List Tasks
curl "$VERS_INFRA_URL/board/tasks"
curl "$VERS_INFRA_URL/board/tasks?status=in_progress"
curl "$VERS_INFRA_URL/board/tasks?assignee=backend-lt"
curl "$VERS_INFRA_URL/board/tasks?tag=auth"
Returns { tasks: [...], count: N }. Sorted newest first. Valid statuses: open, in_progress, blocked, done.
Get a Task
curl "$VERS_INFRA_URL/board/tasks/01ABC123..."
Update a Task
curl -X PATCH "$VERS_INFRA_URL/board/tasks/01ABC123..." \
-H "Content-Type: application/json" \
-d '{"status": "in_progress", "assignee": "backend-lt"}'
Updatable: title, description, status, assignee (set null to unassign), tags, dependencies.
Delete a Task
curl -X DELETE "$VERS_INFRA_URL/board/tasks/01ABC123..."
Add a Note
curl -X POST "$VERS_INFRA_URL/board/tasks/01ABC123.../notes" \
-H "Content-Type: application/json" \
-d '{
"author": "backend-lt",
"content": "Found the root cause — missing CORS header in preflight",
"type": "finding"
}'
Returns 201. Required: author, content, type. Valid types: finding, blocker, question, update.
Get Notes
curl "$VERS_INFRA_URL/board/tasks/01ABC123.../notes"
Returns { notes: [...], count: N }.
Common Patterns
Agent Claims a Task
curl "$VERS_INFRA_URL/board/tasks?status=open&assignee=my-agent"
curl -X PATCH "$VERS_INFRA_URL/board/tasks/$TASK_ID" \
-H "Content-Type: application/json" \
-d '{"status": "in_progress", "assignee": "my-agent"}'
Report a Blocker
curl -X POST "$VERS_INFRA_URL/board/tasks/$TASK_ID/notes" \
-H "Content-Type: application/json" \
-d '{"author": "my-agent", "content": "Cannot proceed — DB credentials missing from env", "type": "blocker"}'
curl -X PATCH "$VERS_INFRA_URL/board/tasks/$TASK_ID" \
-H "Content-Type: application/json" \
-d '{"status": "blocked"}'
Complete a Task
curl -X POST "$VERS_INFRA_URL/board/tasks/$TASK_ID/notes" \
-H "Content-Type: application/json" \
-d '{"author": "my-agent", "content": "Auth middleware implemented and tested", "type": "update"}'
curl -X PATCH "$VERS_INFRA_URL/board/tasks/$TASK_ID" \
-H "Content-Type: application/json" \
-d '{"status": "done"}'
Board Update Protocol for LTs
Lieutenants follow a strict protocol for board updates. The board is the source of truth — if the board is stale, the orchestrator can't coordinate.
On task assignment
Set status to in_progress and assign yourself immediately. Don't start work silently.
curl -X PATCH "$VERS_INFRA_URL/board/tasks/$TASK_ID" \
-H "Content-Type: application/json" \
-d '{"status": "in_progress", "assignee": "my-lt-name"}'
While working
Add notes as things happen — findings, decisions, blockers. Don't batch them.
curl -X POST "$VERS_INFRA_URL/board/tasks/$TASK_ID/notes" \
-H "Content-Type: application/json" \
-d '{"author": "my-lt-name", "content": "Auth tokens expire after 1h, not 24h as documented", "type": "finding"}'
curl -X POST "$VERS_INFRA_URL/board/tasks/$TASK_ID/notes" \
-H "Content-Type: application/json" \
-d '{"author": "my-lt-name", "content": "Using SQLite instead of JSONL — need row-level revocation", "type": "update"}'
When blocked
Set status to blocked with a note explaining what's wrong and what you need.
curl -X POST "$VERS_INFRA_URL/board/tasks/$TASK_ID/notes" \
-H "Content-Type: application/json" \
-d '{"author": "my-lt-name", "content": "Cannot SSH to infra VM — no key access. Need orchestrator to deploy.", "type": "blocker"}'
curl -X PATCH "$VERS_INFRA_URL/board/tasks/$TASK_ID" \
-H "Content-Type: application/json" \
-d '{"status": "blocked"}'
When done
Set status to in_review and add a summary note with: what changed, branch name, test results.
curl -X POST "$VERS_INFRA_URL/board/tasks/$TASK_ID/notes" \
-H "Content-Type: application/json" \
-d '{"author": "my-lt-name", "content": "Branch feat/share-links pushed. 24 new tests, all passing. Added SQLite store, admin routes, public viewer route.", "type": "update"}'
curl -X PATCH "$VERS_INFRA_URL/board/tasks/$TASK_ID" \
-H "Content-Type: application/json" \
-d '{"status": "in_review"}'
The orchestrator moves tasks from in_review to done after verification. LTs don't mark their own tasks done.
Subsuming Tasks
When a new task replaces or absorbs multiple older tasks, link them bidirectionally:
- On the old tasks: add a note saying "Subsumed by
<new-task-id> ()" and close them as done.
- On the new task: add a note listing all subsumed task IDs with their titles and what design context they contain.
This ensures future visitors can trace the lineage in both directions — from the old tasks forward to where the work moved, and from the new task back to the prior thinking.
Self-Management
Orchestrators are responsible for keeping the board current. Don't wait to be asked. The board is the persistence layer — a new session reads it to understand what's happening. If it's stale, recovery fails.
- Create tasks as work is identified (even from casual conversation)
- Update status immediately when work starts, finishes, or gets blocked
- Add notes with findings, decisions, context as work progresses
- Close tasks when PRs merge or work is verified
- Clean up stale tasks — if an agent is gone, update the task
Automatic Behavior
The agent-services extension does not auto-create board tasks — all task management is manual/explicit. However, agents auto-register in the registry and publish to the feed on startup, so you can discover available agents before assigning tasks.
Pi Tools
If the agent-services extension is loaded:
board_create_task — Create a new task
board_list_tasks — List/filter tasks
board_update_task — Update status, assignee, etc.
board_add_note — Post a finding, blocker, question, or update
Task Schema
interface Task {
id: string;
title: string;
description?: string;
status: "open" | "in_progress" | "blocked" | "done";
assignee?: string;
tags: string[];
dependencies: string[];
createdBy: string;
createdAt: string;
updatedAt: string;
notes: Note[];
}
interface Note {
id: string;
author: string;
content: string;
type: "finding" | "blocker" | "question" | "update";
createdAt: string;
}