Task Workflow States
BoardTask.status (backlog | queued | running | completed | failed | cancelled | archived | deferred) describes the execution lifecycle of a task. Workflow states are a separate, customizable layer on top — team-defined labels like "Needs Review" or "Blocked on PM" that are orthogonal to whether a runner is currently executing the task.
A task carries an optional workflowStateId that references one of the workflow states defined in the registry.
Default States
Seven defaults are seeded on first read:
| ID | Label | Category | Color |
|---|---|---|---|
triage | Triage | triage | amber |
backlog | Backlog | backlog | gray |
todo | Todo | unstarted | blue |
in_progress | In Progress | started | violet |
needs_review | Needs Review | started | pink |
done | Done | completed | green |
cancelled | Cancelled | cancelled | gray |
Categories are fixed (triage | backlog | unstarted | started | completed | cancelled) but you can add custom states inside any category.
API
GET /api/task-workflow-states List states (use ?projectId=<id> for project-scoped)
POST /api/task-workflow-states Create or update a state
DELETE /api/task-workflow-states?id=<stateId> Delete a state
DELETE /api/task-workflow-states?reset=true Reset to defaults
POST body shape:
{
"id": "needs_pm_signoff",
"label": "Needs PM Sign-off",
"category": "started",
"projectId": null,
"color": "#ec4899",
"position": 5,
"autoArchiveAfterDays": null
}
CLI
swarmclaw workflow-states list
swarmclaw workflow-states create --json '{"label":"Needs PM Sign-off","category":"started","color":"#ec4899"}'
swarmclaw workflow-states delete --query id=<state-id>
swarmclaw workflow-states delete --query reset=true
Atomic Task Checkout
Workflow states pair with the existing atomic task checkout (task-checkout.ts): two runners hitting the same task on near-simultaneous heartbeats can't both claim it. Only one transitions queued → running and stamps checkoutRunId; the other gets null back from checkoutTask() and skips.
This was already in place pre-v1.5.57 — workflow states just give you the team-customizable labels to drive the kanban view on top.