Skip to main content
The board is Clawboo’s durable, transactional source of truth for task coordination. When a team delegates work, the work becomes a board task. When an agent picks up work, it atomically claims that task. When a run completes, the outcome lands on the board. Refresh the page, restart the server, or run twelve agents concurrently against one project — the board survives all of it. The board is canonical for task and coordination state. Chat is narration of that state. A board mutation is the decision of record; a chat message describes a decision and can never write back to the board. This distinction matters: when something goes wrong, you look at the board, not the chat transcript.

​
The seven task statuses

Every task moves through a defined set of statuses. Two of them (done and cancelled) are terminal — they have no outgoing transitions.
StatusMeaning
backlogCreated but not yet ready to work — triage-only.
todoReady to be claimed by an agent.
in_progressActively owned by an assigned agent.
in_reviewWork complete; awaiting verification.
blockedCannot proceed; waiting on something external.
doneFinished and verified. Terminal.
cancelledAbandoned or no longer needed. Terminal.
The full transition table defines what moves are legal:
FromLegal next statuses
backlogtodo, blocked, cancelled
todoin_progress, blocked, backlog, cancelled
in_progressin_review, done, blocked, todo, cancelled
in_reviewdone, in_progress, blocked, cancelled
blockedtodo, in_progress, backlog, cancelled
done(terminal)
cancelled(terminal)
The in_progress → todo transition is the release path. Releasing a task clears its assignee so a fresh claim can pick it up. It also clears the stored verification verdict — a previous runtime’s result must not gate a new runtime’s legitimate completion.

​
Atomic claiming — one assignee, no races

A task is worked by exactly one agent at a time. Clawboo guarantees this with a single conditional database update: the claim succeeds only if the task is todo, has no current assignee, and has not been dropped — all checked atomically in the same statement that performs the write. Here is the underlying guarantee in full: 
UPDATE tasks
   SET assignee_agent_id = ?, assignee_runtime = ?, status = 'in_progress', updated_at = ?
 WHERE id = ?
   AND status = 'todo'
   AND assignee_agent_id IS NULL
   AND dropped = 0
RETURNING *
Because every condition (status = 'todo', assignee IS NULL, dropped = 0) is evaluated and written in one atomic operation, at most one concurrent caller can win. The winner receives the updated row; every other caller receives zero rows. If two agents try to claim the same task simultaneously, exactly one wins. The loser receives a 409 Conflict response. The rule throughout the system is never retry a 409 — a conflict means another agent legitimately owns the work. Retrying would either be a no-op or create a conflict with the rightful owner.
A 404 Not Found on a claim attempt means the task does not exist. A 409 Conflict means the task exists but someone else already claimed it. These are distinct and should be handled differently in any integration.

​
Dependency chains

Tasks can declare dependencies: “this task cannot start until that task is done.” Dependencies form a graph that the board uses to automatically surface the next ready task once a blocker completes. Dependency links are idempotent — re-linking the same pair is harmless. A task is ready when it is todo, not dropped, and every one of its dependencies is done. When a blocker completes, the board’s ready-pump fires the next step automatically. Tasks are ordered by priority (descending) and then by recency. Dependencies also drive graceful failure. When a blocker moves to blocked and cannot reach done, its downstream dependents would otherwise sit as permanent ghost cards. You can cancel the still-pending transitive dependents of a failed task in a single operation — the board walks the dependency graph recursively, cancels todo and backlog tasks in the chain, and leaves already-in-progress or completed work untouched.

​
The verification gate on → done

Reaching done requires passing a verification check for file-mutating tasks. Any transition to done is rejected when the task carries a non-promotable verification result — a failing build/test command or an unresolved blocking critic finding. The only ways a task can reach done are:
  • Its verification passed.
  • Its verification completed with debt over a green build gate (recorded issues, but the build itself passed).
  • It carried no verification result at all (no file-mutating work to verify).
  • A human explicitly overrides with humanOverride — which is always audited.
This gate is intrinsic to the board state machine. No caller — REST route, MCP tool, or orchestrator — can bypass it without the audited override. See Verification for the full picture.
humanOverride is the only way to move a task with a known-failing verification to done. Every override is written to the audit log — it is never silent.

​
How the board narrates to chat

When the board records a significant event — a task claimed, a status changed, a dependency linked — it reflects a system message into the team chat room after the write completes. These messages appear in chat as kind=system posts. They are context for your team, not instructions; an agent receiving a system chat post treats it as evidence, not a command. This means you can follow team progress in the chat view without leaving it, while knowing that the chat is always a derived summary of what the board actually decided.

​
Crash recovery

The board recovers automatically from two failure modes: Orphan recovery (on startup): Any task that was in_progress when the previous server process died is detected on restart. Its execution record is marked failed, and the task is released to todo so a fresh claim can pick it up. This pass runs once at startup in a single transaction and never blocks the server from starting. Stale task sweep (on an interval): A task that has been in_progress for longer than the stale TTL (60 minutes by default) with no recorded activity is timed out and released to todo. This is a backstop for tasks whose driving client simply went away — the TTL is generous enough that a slow-but-active run is never falsely swept.
You can adjust the stale sweep threshold with the CLAWBOO_BOARD_STALE_TTL_MS environment variable. The default is 60 minutes (3,600,000 ms). Increase it if your agents routinely run long-duration tasks that do not emit frequent board updates.

Verification

The builder ≠ judge gate that makes done mean verified.

Peer Chat

The team chat room the board narrates into.

Governance

Budgets, circuit breakers, and caps that bound every run.

Observability

The event log that records every board mutation.