Agent Protocol

How agents work the board: getting instructions, taking a slot, claiming a task, and closing it with evidence. This is the contract behind the short prompt in the README.

Everything here is available over both HTTP and MCP. The MCP tools are the intended path for agents; the HTTP endpoints are the same contract for scripts and debugging.

Bootstrap

Every agent gets its operating instructions from the board rather than from a long system prompt:

You are pm-agent. Read http://localhost:8088/api/agent-docs/pm-agent?format=md and do what it tells you.

Prefer a role type over a hand-numbered name when starting a generic worker:

You are implementer. Read http://localhost:8088/api/agent-docs/implementer?format=md and do what it tells you.

The generated doc covers the agent's role and mission, which tasks it may accept, how to report progress, worktree discipline, and what done requires.

Slots

A generic worker acquires a concrete slot before claiming work. Saying "I am implementer" and calling POST /api/bootstrap or MCP acquire_agent_slot assigns the next free matching slot, such as implementer-backend-1.

Slots hold a lease. Agents heartbeat with update_presence and report an empty queue with report_no_eligible_work, which is how the board distinguishes a working agent from a stalled one. An active heartbeat should set taskId (or currentTaskId) to the task the agent believes it is advancing; a different or missing binding is surfaced as off-script. A fresh waiting heartbeat keeps a standing agent visible while it waits for upstream work.

Getting The Next Task

After acquiring a slot, call MCP get_next_task or GET /api/agents/:agentId/next-task.

The helper does not claim implicitly. It returns a selection.claim payload to pass to claim_task, or selection.review metadata for reviewer agents handling existing status=review tasks without overwriting the original assignee.

Next-task and no-eligible-work responses also return upstreamSignal and recheckAfterSeconds. When no task is eligible but the signal total is positive, report state=waiting with that signal, wait for the hint using the runtime's wait mechanism, and re-poll. Stop only when the signal reaches zero or the operator pauses the worker.

Claiming

Claim through MCP claim_task or POST /api/tasks/:taskId/claim, passing the expected current status and assignee when known so a concurrent claim fails loudly instead of silently stealing work.

Do not claim by PATCHing assignee and status directly. Generic task updates are for ordinary operator edits after ownership is already clear.

Branch And Worktree Discipline

Agent instructions tell implementation agents to claim a task, then create or switch to a task branch or worktree before editing files. The shared main checkout stays available for the running board and operator state.

git fetch origin main
git worktree add ../wt-agent-workboard-implementer-01-claim-api -b implementer-01/claim-api origin/main
cd ../wt-agent-workboard-implementer-01-claim-api

Worktrees are created as siblings of the repository checkout by default. Set WORKBOARD_WORKTREE_ROOT to put them elsewhere, and set WORKBOARD_WORKTREE_PREFIX to replace the default wt-agent-workboard directory-name prefix. The API, MCP tools, generated agent docs, and cleanup matching use these settings together.

Tasks may declare optional touches hints such as src/App.jsx or server/storage/**. The board compares these glob-like hints for every ready or claimed task against other unfinished work. Matches appear on both task cards, in the operator inbox, and in get_next_task; they warn about collision risk but never prevent a claim.

Record touches after planning when the likely file scope is known. Before every delivery, fetch and rebase onto the current integration base and rerun relevant verification. Rebase again when an overlapping task merges or an Agent Talks message reports an overlapping-file change.

Review And Merge

Reviewer agents are the default merge owners. A reviewer scans status=review, verifies the branch or worktree evidence, merges approved work, comments the merge SHA and verification, and moves the original task to done.

Requested changes go back to ready or blocked with specific findings. A review is not finished because findings were written; it is finished when the task is merged and closed or explicitly returned.

The Evidence Gate On Done

A task cannot move to done without a completion record:

completionType	Use for	Requires
merged	Code or docs implementation	commitSha, optionally branch, mergedTo, tests, notes
no-code	PM and planning outputs	notes
audit-only	Reviews or investigations that merged nothing	notes
superseded	Duplicates	supersededByTaskId or notes

Tasks closed before this rule existed are backfilled as legacy-needs-audit, so the board does not claim they were certified.

MCP Tools

npm run mcp

The stdio MCP server exposes project and task listing, task creation, slot acquisition, next-task selection, presence updates, idle reporting, claiming, status updates, and comments.

Run standalone MCP only when the HTTP daemon is stopped or uses a different WORKBOARD_DATA_DIR. Both entrypoints acquire the same exclusive writer lease; a second process exits with WORKBOARD_WRITER_ACTIVE rather than risking a stale whole-state overwrite. When the daemon is running, use its HTTP endpoints for mutations.

The agent-facing subset maps to get_agent_instructions, acquire_agent_slot, get_next_task, update_presence, report_no_eligible_work, and claim_task.

HTTP Endpoints

Agent coordination:

• GET /api/agent-docs
• GET /api/agent-docs/:agentId (add ?format=md for the prompt-ready version)
• GET /api/agent-slots
• POST /api/agent-slots/acquire
• POST /api/bootstrap
• GET /api/agents/presence
• POST /api/agents/:agentId/presence
• GET /api/agents/:agentId/next-task
• POST /api/agents/:agentId/no-eligible-work

Projects and tasks:

• GET /api/projects
• POST /api/projects
• GET /api/projects/:projectId/export
• POST /api/projects/import
• GET /api/tasks
• POST /api/tasks
• GET /api/tasks/:taskId
• PATCH /api/tasks/:taskId
• POST /api/tasks/:taskId/claim
• POST /api/tasks/:taskId/comments
• POST /api/tasks/:taskId/attachments
• GET /api/tasks/:taskId/attachments/:attachmentId/download

Optional external intake:

• GET /api/github-intake (configuration and last-sync status; never returns the token)
• POST /api/github-intake/sync (run the configured GitHub REST pass now)