Status lifecycle

Statuses

Status	Purpose	Who acts
To Do	Available for agents. Top item is highest priority.	App dispatches to agent
In Progress	Actively being worked on by an agent.	Agent works
AI Review	PR created, awaiting agent code review.	App dispatches to reviewer
Human Review	Agent reviewed, ready for you to merge. This is your signal.	You review and merge
Done	Merged and closed.	Terminal state

Valid transitions

To Do          -> In Progress        agent claims work
In Progress    -> AI Review          agent creates PR
In Progress    -> To Do              agent is stuck, posts blocker details
AI Review      -> Human Review       reviewer: no blocking issues
AI Review      -> To Do              reviewer: blocking issues found
Human Review   -> Done               you approve and merge
Human Review   -> To Do              you request changes

Transition rules

Every transition includes a handoff comment. Before changing an issue’s status, the agent posts a structured comment covering what was done, key decisions made, what needs attention, and what’s next. This creates an audit trail any agent or human can read to understand the full history of an issue.

Status claims use optimistic locking. When an agent claims work — moving from To Do to In Progress — it uses a check-and-set: “move this issue to In Progress, but only if it’s still in To Do.” If another agent claimed it first, the operation fails and the agent moves on. This prevents two agents from working on the same issue.

Only you move issues to Done. Agents never close issues or mark them complete on their own — with one exception: for epic sub-issue PRs that merge to an epic branch, the reviewing agent closes the sub-issue after merging. For all other work, you merge the PR and the issue closes automatically.

Stuck agents return issues to To Do. If an agent gets stuck during implementation, the issue goes back to To Do with detailed blocker information. The board’s rank ordering handles priority — you can move unblocked items above blocked ones.

Change request items get priority. Issues returned to To Do after a review with change requests are picked up before fresh work. Within To Do, the order on the project board determines which issue an agent picks up first (top of the list = highest priority).

Dispatch priority

The work queue in workflows.json defines the priority order for code agents. The default configuration pulls from To Do:

"worker": {
  "entries": [
    { "status": "ready" }
  ]
}

Within the status, the order on the project board determines which issue an agent picks up first (top of the list = highest priority). You control priority by reordering issues on your board.

Epic sub-issue lifecycle

Sub-issues that are part of an epic follow a modified lifecycle:

• The worker agent creates a PR targeting the epic branch (not main)
• The reviewing agent, if the PR passes review, squash-merges it to the epic branch and closes the sub-issue — skipping Human Review for that individual sub-issue (unless the cate:supervised label is applied)
• When all sub-issues are complete, the epic’s tracking PR (epic branch -> main) is marked ready and the epic moves to Human Review
• You review the full epic as one unit and merge to main

Customization

Teams can customize status names and transitions by editing workflows.json. The statuses array defines available statuses with IDs, display names, and colors. Each command’s transitions array defines the valid state changes for that command. Users can add custom statuses and place them in the worker queue to get them worked.