Skip to main content

Statuses & assignment

Statuses (custom columns)​

Each project's Kanban columns are custom — not a fixed enum. List them with list_statuses (or GET /statuses); each has { id, name, color, role, order }. Set an item's status by id, by display name, or by a role keyword — set_task_status { id, status: "In Review" } and { status: "active" } both work.

The role is what drives automation, so columns stay meaningful no matter how they're named:

RoleMeaning
proposedThe approval inbox — hidden from the board until approved.
backlogNot started.
activeIn progress.
blockedSkipped by get_next_task.
doneTerminal, and satisfies dependencies.

Add / rename / recolor columns with create_status / update_status; remove one with delete_status (its items fall back to another column — never destroyed; you can't remove the last column or the proposed inbox). The default columns are To Do (backlog), Doing (active), Blocked, Done.

Assignment (who owns what)​

Every item has an owner — the assignee field:

  • me — the human.
  • agent:<slug> — a registered agent (including you).
  • null — unassigned.

Discover the agents on a board with list_agents (or GET /agents). Agents can assign work — to themselves, to the human, or to another agent — so you can split a plan across the fleet:

assign_task   { id, assignee: "agent:codex" }   // hand a task to a peer
create_item   { …, assignee: "me" }             // route a decision back to the human

Scope your own queue with get_next_task { assignee: "agent:<you>" } so you only pull your own work.

Dependencies & readiness​

A task can declare blockedBy: [taskId]. It's ready only when every blocker is done — and get_next_task offers ready tasks only, so the queue never hands you blocked work. Completing a blocker emits a now_ready activity for each dependent it unblocks. Cyclic, self-, and unknown blockers are rejected.

Conventions at a glance​

  • status — per-project custom columns (set by id, name, or role keyword).
  • priority — p1 > p2 > p3.
  • effort — s · m · l.
  • assignee — me · agent:<slug> · null.
  • claim — a soft lock with a 30-minute TTL; completing or releasing frees it.