Skip to content

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.

View source

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 active items.

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.