Roles

Role	When it fires	Reads	Writes
planner	First run, if features.json missing	SPEC.md	features.json, validation-contract.md
plan-reviewer	After planner, gated by config	All planner output	plan-review.md (verdict line)
worker	Orchestrator: NEXT_WORKER <fid>	features.json, contract, knowledge.md	feature implementation, worker-log.md
validator	Orchestrator: NEXT_VALIDATOR <fid>	Contract, worker-log.md	issues.md, pending-issues.jsonl, status mutation
crosscheck	After validator pass, if enabled	Same as validator	CROSSCHECK agree/disagree line
ui-qa	After validator pass, if claims include VAL-UI-*	Real browser via verdict	ui-qa.md
debugger	Pre-worker when attempts ≥ threshold	Failure logs, contract	debug/<fid>.md (root-cause)
architect	When orchestrator emits NEXT_ARCHITECT <fid>	Spec + contract + issues	Resolves spec ambiguity
curator	On terminal events (DONE / ESCALATE) or every N iters	raw.md, all state	summary.md, MEMORY.md, identity/<role>.md, issues.json merge
documenter	After validator pass + on DONE	Code + spec	docs/ (Starlight)
product	Optional: at near-done threshold or on-done	GOAL.md vs SPEC.md	proposals/<ts>.md
supervisor	External cron or rc=3 chain	Full mission state	supervisor-notes.md (intervention)
orchestrator	Every iteration	All state	One-line decision verb

Role design rules

1. Fresh context. No role keeps in-memory state across invocations.
2. One job. Every role’s prompt explicitly tells it what its single output is. Multi-purpose roles drift.
3. Boil the lake. Specialists stay in lane (gstack-inspired). If they see a problem outside scope, they flag it as an issue rather than fixing it.
4. Identity bias. Every role reads its identity file at startup so it inherits past wisdom (Agent Swarm-inspired).
5. Evidence required. Validators must quote test output to claim pass (claudecode-orchestrator-inspired).
6. TDD iron law. Behavioural assertions need a test that failed before the change (Superpowers-inspired).

Anti-patterns we avoid

• A “supervisor” that runs every loop iteration. Supervisor wakes on cron or escalation only — running it inline turns it into yet another orchestrator and double-counts decisions.
• “Helper” roles that do bits of everyone else’s job. Each role owns a single output file.
• Roles that mutate validation-contract.md. Only the architect can.
• Roles that commit code. Only the worker writes; only run.sh commits.