# Pipeline ``` [new cycle] [test-specifiable feature] [bug observed] | | | v v v brainstorm -> specify -> plan -> implement debug -> implement (mini) ^ ^ | | | tdd -> implement (mini) | specify -> plan (design settled in sources) +----(design fork)----------/ (specify/tdd bounce here; RED executable-spec -> GREEN) (per iteration loop) | [cycle close — a loop step, not a milestone close] | v audit --(drift)--> plan + implement (tidy iteration) --(ratify)-> --update-baseline + ratify paragraph in audit commit body --(drift-clean)-+ | [orchestrator: cycle complete? if surface-touch:] v fieldtest --(bug)------> debug -> implement (mini) --(friction)-> brainstorm OR plan (tidy) --(spec_gap)-> ratify OR tighten ledger --(clean)----+ | [orchestrator: surface stable across N cycles?] v docwriter | v next cycle ``` ## Cycle vs. milestone These are two distinct axes, and conflating them is a bug. - A **cycle** is one round in the pipeline graph above (`brainstorm → specify → planner → implement → audit → [fieldtest]`). A cycle close is an internal loop step. - A **milestone** is a tracker container (Gitea milestone, GitHub milestone, Linear project — whatever the project's tracker calls a long-running work scope). A milestone spans potentially many cycles and closes only when the work it promised is **complete and functional** (see the gate below). `audit` runs at cycle close and proves *drift-clean* — the code matches the design ledger. It is blind to whether the work is *functional* from a downstream consumer's point of view; that is what `fieldtest` measures. So no `audit` result closes a milestone, and neither does a `/boss` done-state. ## Milestone-close gate A milestone may be closed in the tracker only when **both** legs hold: 1. **Complete** — every cycle filed under the milestone is `audit` drift-clean (or its drift explicitly ratified), and the milestone container has no open iterations / issues left. 2. **Functional** — the **milestone fieldtest** has run its curated end-to-end scenarios against the milestone's promise and its status roll-up is `clean`: every scenario demonstrably delivers what the milestone promised; no open `bug` findings; `friction` / `spec_gap` findings resolved or ratified into the design ledger. The milestone fieldtest is the milestone-wide variant of the `fieldtest` skill: the same fieldtester agent, a carrier scoped to the milestone's promise rather than one cycle's surface. Its scenarios are chosen top-down from what the milestone as a whole promised, not assembled as the union of per-cycle axes. A milestone whose entire scope is internal (no user-visible surface) is exempt from the functional leg — the milestone fieldtest is *not applicable* and the complete leg suffices. This gate defines *when* a milestone is closeable. The actual close stays a deliberate human / orchestrator act — the tracker's own milestone-close action (on Gitea, `tea milestone close`); no skill performs it automatically. ## Phase descriptions ### brainstorm Optional discovery front-end. Gathers requirements, explores 2-3 approaches with trade-offs, presents a sectioned design with user approval, then hands the ratified design to `specify` (it writes no spec itself). Skipped when the design is already settled in the sources — that work enters through `specify` directly. ### specify Hard-gate before plan — the spec-production core and the carrier of the "no plan without an approved spec" invariant. Takes a settled design (directly from sources, or a ratified design handed over by `brainstorm`), applies the feature-acceptance criterion, writes the spec to `docs/specs`, runs the `grounding-check` gate, and takes user sign-off — with review but no interview. Bounces to `brainstorm` the moment the sources do not resolve a load-bearing design decision. A core node — the spec-production gate before `planner` on every design path. The sign-off is the user's by default, including under `/boss`. The one exception is spec auto-sign (a project that enables it in its CLAUDE.md project facts): with it on, a `/boss` run may sign a spec in the user's place — but only when every objective gate is green AND a unanimous five-lens `spec-skeptic` panel passes; the orchestrator's own confidence never signs. A `BLOCK` is never signed over: an editorial one (`criterion` / `ambiguity` / `plan-readiness`) is repaired in a bounded ≤ 2-round loop that re-runs the objective gates and re-dispatches all five lenses each round; a design one (`scope-fork` / `grounding`), an `INFRA_ERROR`, or an exhausted budget falls back to the human sign-off pause. When the entry is in-context and the seeding issue still lists a now-resolved fork as open, `specify` posts a provenance-bearing reconciliation comment on the issue (Step 1.5) so the `scope-fork` juror can ratify the resolution instead of blocking on the stale body. See `../specify/SKILL.md` Step 6 and `../boss/SKILL.md` §"Spec auto-sign". ### planner Hard-gate before implement. Produces a placeholder-free, bite-sized implementation plan in `docs/plans` that the implement skill can execute task-by-task. Dispatches the plan-recon agent for read-only file-structure mapping. ### implement Dispatches the implement-orchestrator agent, which runs the entire per-task loop (implementer phase → spec-compliance check → quality check) as sequential role-switches inside its own context. Writes code, tests, and stats files directly in the working tree as unstaged changes. On `PARTIAL` or `BLOCKED`, also writes `BLOCKED.md` at the repo root. ### audit Runs at cycle close. Dispatches the architect agent (read-only drift review against the design ledger) and the bencher agent (regression diagnostics). Reports drift and regress. ### debug Runs whenever a bug is observed. RED-first: produces a failing test in the working tree before any fix is attempted. Hands off the GREEN side to the implement skill in mini mode. ### tdd A standard alternative entry, alongside `brainstorm → specify → planner`, for work whose desired behaviour is test-specifiable — expressible as one failing test. RED-first: the `tdd-author` agent turns a description or issue into a single minimal, autonomous RED executable-spec ("how it should work"), then hands the GREEN side to `implement` in mini mode, exactly as a bug fix. When the behaviour is not test-specifiable (a genuine design fork surfaces), or two decomposition rounds fail, it bounces back to `brainstorm`. When one iteration cannot reach GREEN, the headline test is carved into a ladder of BLOCKER sub-tests, each its own RED→GREEN mini-cycle. Distinct from the per-task TDD the implementer already practices inside `implement`. ### fieldtest Optional. Orchestrator-dispatched after the audit closes clean on a cycle that touched user-visible surface. Picks 2-4 real- world tasks within the cycle's scope, implements them using only the design ledger and public examples (never the language's own implementation), runs the results, and writes a friction- and-bug spec. ### docwriter Optional. Orchestrator-dispatched after API surface has stabilised across multiple cycles. Brings docstrings up to a level where a newcomer can navigate the public API without reading the design ledger first. ## Status protocol Agents return one of these terminal states: | State | Meaning | |-------|---------| | `DONE` | Task complete; no concerns. | | `DONE_WITH_CONCERNS` | Task complete; flagged issues the orchestrator should weigh before committing. | | `PARTIAL` | Task partially complete; the rest is blocked or out-of-scope. Writes `BLOCKED.md`. | | `BLOCKED` | Task cannot proceed; explanation in report. Writes `BLOCKED.md`. | | `NEEDS_CONTEXT` | Task cannot proceed without additional information from the orchestrator. | Reviewer agents have role-specific states: | Role | States | |------|--------| | spec-reviewer | `compliant` / `non_compliant` / `unclear` / `infra_blocked` | | quality-reviewer | `approved` / `changes_requested` / `infra_blocked` | ## Skip rules Skipping is codified per skill, not ad hoc. Each `SKILL.md` documents what the skill skips and under what conditions: - `specify` is never skipped at cycle start — it is the spec-production gate before `planner`. `brainstorm` is the *optional* discovery stage before it: skipped when the design is already settled in the sources (the work enters through `specify` directly), run when a load-bearing decision is still open. - `planner` is never skipped at iteration start, except for the bug-driven `debug → implement (mini)` side path. - `implement` is the iteration body; not skippable. - `audit` is mandatory at cycle close. - `debug` is mandatory RED-first for any observable bug. - `tdd` is a standard alternative entry to `brainstorm` for test-specifiable work; it bounces back to `brainstorm` on a design fork. Always available — not opt-in. - `fieldtest` and `docwriter` are optional and orchestrator- dispatched. If a skill's body says it must run and the orchestrator wants to skip it, the orchestrator records the reason in the relevant commit body — never as undocumented practice. ## Pipeline configuration There is none. The phase set, the gates, and the conditional dispatch shown above are fixed — the same for every project. All phases (`brainstorm`, `specify`, `planner`, `implement`, `audit`, `debug`, `tdd`, `fieldtest`, `docwriter`) are always available; which ones run on a given iteration is the orchestrator's judgement per the skip rules above, not a per-project setting. The only behavioural toggle is spec auto-sign under `/boss`, declared in a project's CLAUDE.md project facts. See `conventions.md`. If a project declares a glossary in its CLAUDE.md project facts, that file is standing reading for every role — the canonical-nomenclature source every skill and agent consults (see `glossary-convention.md`).