Use when running or planning a work item (W-NNN): item types, states, the flow per type, size limits, and invariants. The flow table is binding for the Orchestrator.
Workflow¶
States¶
inbox → ready → active → review → (accept for apps with [manual] requirements) → done (removed from the board, added to docs/work/archive.md). An item can also be blocked, with a reason.
Flow per type¶
| Type | Flow | Invariant |
|---|---|---|
| feature | spec → plan → (scaffold) → per step: tests → implement → review → final review | Every requirement ID has a test carrying the ID |
| bug | plan → per step: regression test → fix → review | A regression test exists |
| refactor | plan → per step: characterization tests (if missing) → change → review | Existing tests and specs have no diff; public API unchanged |
| chore | plan → per step: change → review | No behaviour change |
| spike | question → research (Explorer) → write up findings; no production code |
Findings and follow-up items are recorded |
Size and epics¶
- S: one step, M: a few steps, L: too big. Split every L item into S/M items.
- Group related items under an epic. Every epic should have a next item.
- Respect the WIP limit on
activeitems.
Ready¶
An item is ready when its type-specific sections are filled in, it is not size L, and every Depends item is done.
Rules¶
- The item file is the source of truth for steps. The board is the source of truth for state.
- After 2 failed review rounds on a step, stop and ask the user.
- Stop and ask on open questions, library limitations, or needed dependency changes.