Requirement Workflow (v5)
A minimal orchestrator for spec-driven development. The CLI keeps state, runs gates, and writes a curated brief for the next phase — read the brief instead of re-discovering the codebase.
Core idea
| Concept | Where | Purpose |
|---|---|---|
| Lifecycle | lite / standard / full | Phase ladder — start small, escalate on evidence |
| Brief | briefs/<PHASE>.md | Curated context the next agent reads |
| Gate | TS validator per phase | Blocks advance until artifacts meet criteria |
| Traceability | traceability.md | Auto-rebuilt AC ↔ task ↔ files matrix |
Lifecycles
lite INIT → IMPLEMENTING → TESTING → DONE
standard INIT → PLANNING → IMPLEMENTING → TESTING → DONE
full INIT → DEFINING → PLANNING → DESIGNING → IMPLEMENTING → TESTING → DELIVERING → DONE
Use lite by default. Promote with:
node scripts/cli.cjs escalate -r . --to standard --reason "scope grew past 5 files"
node scripts/cli.cjs escalate -r . --to full --reason "auth code touched"
Common escalation triggers:
- A task touches >5 files → bump to standard (need PLANNING)
- Auth, payment, crypto, or PII keyword → bump to full (need DEFINING + DESIGNING)
- AC failures repeat in TESTING → bump to full to formalise spec
The three commands you need
node scripts/cli.cjs init -r . -n "<name>" [-l lite|standard|full]
node scripts/cli.cjs advance -r . # gate-checked transition
node scripts/cli.cjs status -r . # phase, brief, last gate, AC/task counts
Plus three useful auxiliaries:
node scripts/cli.cjs brief -r . --print # show current-phase brief
node scripts/cli.cjs brief -r . --regen # rebuild brief from current artifacts
node scripts/cli.cjs trace -r . # rebuild traceability.md
Workflow loop
1. cli.cjs init -r . -n "..." ← scaffolds .agents/workflow/<id>/
2. cli.cjs advance -r . ← runs gate, writes next brief
3. AI reads briefs/<NEW PHASE>.md ← single context source
4. AI edits the artifact named in the brief (spec.md / tasks.md / design.md / code / checklist.md)
5. Repeat 2-4 until DONE
If the gate fails, advance exits 2 and prints which criterion failed. Fix the artifact and retry, or pass --force to bypass.
Per-phase reference (load on demand)
| Phase | When | Reference |
|---|---|---|
| INIT | Always | n/a |
| DEFINING | full only | references/phases/DEFINING.md |
| PLANNING | standard, full | references/phases/PLANNING.md |
| DESIGNING | full only | references/phases/DESIGNING.md |
| IMPLEMENTING | Always | references/phases/IMPLEMENTING.md |
| TESTING | Always | references/phases/TESTING.md |
| DELIVERING | full only | references/phases/DELIVERING.md |
Default agents
Each phase has one default agent (run first) and a list of optional agents (opt-in when needed). See agents/AGENTS.md for the full registry.
| Phase | Default | Optional |
|---|---|---|
| DEFINING | problem-definer | iron-audit-pm, risk-auditor, spec-by-example |
| PLANNING | story-mapper | mvp-freeze-architect |
| DESIGNING | architecture-advisor | domain-modeler, responsibility-modeler |
| IMPLEMENTING | tdd-coach | refactoring-guide, legacy-surgeon |
| TESTING | test-strategist | test-strategy-advisor, code-reviewer, error-analyzer |
| DELIVERING | tech-design-reviewer | code-reviewer |
IDE hooks (optional)
node scripts/cli.cjs hooks generate -r . # print hooks.json
node scripts/cli.cjs hooks install -r . # write hooks.json to .trae/ and .claude/ (IDE-owned config). Workflow state itself lives in `.agents/`.
Installs a SessionStart hook that surfaces the active workflow + brief path, and a Stop quality gate that blocks premature stopping in IMPLEMENTING/TESTING.
See also
- references/QUICKREF.md — one-page cheat sheet
- references/hooks-standard.md — IDE hook spec