Issue lifecycle and dispatch
Cate sorts issues into four queues: To Do, In Progress, AI Review, and Ready for Review. That doesn’t mean you need to change your process or your tracker — workflows.json lets you map your project to Cate’s lifecycle. Usually the only change is adding a status for AI Review, and even that’s optional.
The four queues
Section titled “The four queues”Cate organizes work around four queues. Each queue drives a different type of agent session:
| Queue | What it means | What happens |
|---|---|---|
| To Do | Available work, ranked by board position | A worker agent claims the top issue |
| In Progress | An agent is actively working on this | The agent codes, commits, and opens a PR |
| AI Review | PR submitted, awaiting agent review | A reviewer agent checks the PR |
| Ready for Review | Agent work is done — your turn | You review the PR and merge |
Issues that reach Done are closed. Cate doesn’t manage that transition — it happens when you merge the PR in GitHub and your tracker auto-closes the issue.
Mapping your statuses
Section titled “Mapping your statuses”The statuses array in workflows.json maps each of your tracker’s statuses to one of Cate’s queue IDs. The statusOptions object provides the tracker-specific identifiers (option IDs in Jira, status IDs in GitHub Projects or Linear) so Cate can read and write status changes through your tracker’s API.
You set this up during project setup — an agent interviews you about your board and writes the configuration. If your tracker statuses change later, update the mapping in workflows.json.
How dispatch works
Section titled “How dispatch works”Agents pull work from queues, not from statuses directly. Within a queue, board rank determines priority — the issue at the top of your board is picked up first.
Conflict-free dispatch ensures no two agents work the same issue, even when multiple agents pull from the queue simultaneously. Cate handles this as a distributed coordination problem — if an issue was already claimed, the agent moves on to the next one without interruption. Dispatch also understands blocking relationships: epic sub-issues with unresolved dependencies are skipped until their blockers are complete.
Handoff comments accompany every status change. Before moving an issue, the agent posts a structured comment covering what was done, key decisions, what needs attention, and what’s next. This creates an audit trail that any agent or person can read to pick up where the last one left off.
Epic sub-issues
Section titled “Epic sub-issues”Sub-issues that belong to an epic follow a modified flow:
- The worker agent creates a PR targeting the epic branch, not
main - The reviewer agent, if the PR passes review, merges it to the epic branch and closes the sub-issue — skipping Ready for Review for that individual piece
- When all sub-issues are complete, the epic’s tracking PR (epic branch →
main) is marked ready and moves to Ready for Review - You review the full epic as one unit and merge to
main
If an issue has the cate:supervised label, sub-issues go through Ready for Review individually instead of being auto-merged by the reviewer.
When something goes wrong
Section titled “When something goes wrong”Agents don’t try to resolve ambiguous situations on their own. If a reviewer and a worker disagree, an epic sub-issue is misconfigured to target main, or an agent hits a state it can’t reconcile — the response is the same: flag the issue, post a comment explaining what happened, and move it to Ready for Review so you see it.
This applies to any situation where the expected flow breaks down. Cate escalates rather than guesses.
Customization
Section titled “Customization”Status names, queue mappings, transitions, and dispatch priorities are all defined in workflows.json. See the full schema reference for the statuses, queue, and commands sections.