Skip to content

Concepts

Work item. One unit of work (W-NNN) in docs/work/W-NNN-<slug>.md. It has a type, a target (package or app), a size, a state, and ordered steps.

Type. feature, bug, refactor, chore, or spike. The type decides the flow and its invariant, for example "a regression test exists" for bugs.

Board. docs/project/board.md has one row per open item and is the source of truth for state. Only Triage writes it.

State. inbox → ready → active → review → (accept for items with manual checks) → done. An item can also be blocked.

Size. S or M. Anything larger (L) is split before it can be ready.

WIP limit. The maximum number of active items. The Orchestrator checks it before starting.

Flow. The sequence of agents for a type, for example feature: spec → plan → per step: tests → implement → review → final review. The table lives in the workflow skill.

Gate. A point where agents stop and ask you. After two failed review rounds on a step they also stop.

Spec. A requirement document in docs/specs/NNN-<name>/ with IDs. Every requirement ID must have a test carrying that ID.

Agent, skill, command, tool.

  • Agents do the work.
  • Skills are instructions agents load on demand.
  • Commands are prompts you start with /.
  • Tools are what agents call to act on the repository.