# Pipeline ``` ENTRY PATHS — the selector cascade, walked top to bottom (see boss/SKILL.md) bug observed ........... debug ........................ implement (mini) # RED-first; FIRST in the cascade design fork ............ brainstorm -> specify -> plan -> implement type/signature edit .... compiler-driven -> commit (clean build + suite green unchanged) -> bounce: specify | tdd (a hole) | debug (suite red) test-specifiable ....... tdd -> implement (mini) # RED executable-spec -> GREEN settled prose design ... specify -> plan -> implement (specify / tdd bounce to brainstorm on a design fork) (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 ``` ## The methodology taxonomy Development paths differ on two irreducible axes — the **first artefact written**, and the **correctness oracle**. (Error-recovery is not a third axis: whole-attempt discard is the plugin's universal containment, not a per-path signature.) The top-level cut — ratified prose intent before code (spec-driven) vs. machine / test / run oracles — is the hard boundary; the paths cannot be centralised in one skill, only share the implement executor as a primitive and the cycle-close `audit` tail. | Path | First artefact | Oracle | Bounce-out when | |------|----------------|--------|-----------------| | **spec-driven** | ratified prose spec | human intent, judged at the document | (the deliberate heavy sink) | | **tdd / debug** | a RED test | the assertion goes green | not test-specifiable → `brainstorm` | | **compiler-driven** | a type / signature edit | clean build + suite green unchanged | a hole needs a decision → `specify` (or `tdd` if it is test-specifiable new behaviour); suite red → `debug` | | **try-and-error** | throwaway code | an observed run | attempt budget exhausted | `try-and-error` is **deferred** — listed for completeness, not yet a live path. It is an exploration front-end terminating in a tdd-style handoff, and its attempt tail is structurally unbounded (it can cost more wall-clock than the spec-driven baseline it is meant to beat, and its attempt-budget is a magic number the selector cannot derive). Out of scope until it is given a bounded form. ## 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. A `clean` roll-up is honoured only with positive evidence the test actually ran — at least 2 examples in the working tree (`examples_added`). A `clean` with fewer, over a milestone that touched user-visible surface, is itself a `spec_gap`, not a clean close (the agent owes the same floor — `fieldtest/agents/fieldtester.md` "What you DO NOT ship"; the gate verifies it rather than trusting the roll-up). The empty report is valid only when no example was applicable. 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` (an ephemeral active-cycle artefact, git-tracked and `git rm`'d at cycle close — see `conventions.md` § Lifecycle), runs the `grounding-check` gate, and takes sign-off — with review but no interview. Under the bold stance it decides every load-bearing fork it can *derive* an answer for and records the decision in the run's reference issue; it bounces to `brainstorm` only when a fork hangs on a pure user preference no source settles. A core node — the spec-production gate before `planner` on every design path. Outside `/boss` the sign-off is the user's. Under `/boss` the autonomous signature is the **`grounding-check` `PASS`** itself: an independent fresh-context agent's verdict against currently-green tests, not the orchestrator's confidence. On `PASS` the orchestrator commits the spec (subject `(boss-signed)`), fires the vetoable auto-sign notify, and continues to `planner`; a no-override grounding `BLOCK` / `INFRA_ERROR` routes to the human sign-off pause. The former obligatory five-lens `spec-skeptic` panel is **retired** (baseline tag `pre-autosign-rework`): the judgement it applied now lives upstream in Step 1.5's bold-decide stance, and `spec-skeptic` survives only as the optional ad-hoc bias-breaker the orchestrator pulls when unsure whether its leaning on a fork is judgement or bias. Editorial roughness the panel would have caught is let through deliberately — cheap to patch inline downstream. 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` (ephemeral, retired alongside the spec at cycle close — see `conventions.md` § Lifecycle) that the implement skill can execute task-by-task. Dispatches the plan-recon agent for read-only file-structure mapping. ### implement Runs the `implement-loop` Workflow (`implement/workflows/implement-loop.js`), a deterministic script that executes the per-task loop — implementer → spec-compliance → quality, each a separate `agent()` call — and aggregates the verdicts in code. A Workflow orchestrates from the top level, so the per-task phases are real, independently-invokable agent calls; this retired the former `implement-orchestrator` agent's inline-role-switch workaround (the four phase agents survive as the agent-types the script dispatches). Writes code, tests, and stats files directly in the working tree as unstaged changes; never commits. On `PARTIAL` or `BLOCKED`, also writes `BLOCKED.md` at the repo root. ### compiler-driven The lighter executor for a **behaviour-preserving type/signature edit at a definition site** — the cascade arm between `debug` and `tdd`. Runs the `compiler-driven-edit` Workflow (`implement/workflows/compiler-driven-edit.js`): make the edit, propagate it mechanically across the sites the build enumerates, then let a real build + suite run settle the verdict — **observe-then-bounce**. Clean build AND suite green *unchanged* → the edit is committed by the orchestrator; a hole that forces a design decision → bounce to `specify` (or `tdd` if it turns out to be test-specifiable new behaviour, per the straddle rule); the suite not green-unchanged (a regression — the edit was not behaviour-preserving) → bounce to `debug`, RED-first. A truly trivial edit may run inline without the workflow, under the same done-signal. Never skips the review-and-commit discipline; the orchestrator inspects and commits. ### 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. Once it is drift-clean, the orchestrator retires the cycle's spec and plan — `git rm`'ing them in the cycle-close commit (see `conventions.md` § Lifecycle). ### 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 side paths that carry no prose plan: the bug-driven `debug → implement (mini)` path and the `compiler-driven` path (whose "plan" is the type-checker's enumeration of edit sites). - `implement` is the iteration body; not skippable. - `audit` is mandatory at cycle close. - `debug` is mandatory RED-first for any observable bug — first in the selector cascade, so a mechanical-looking fix cannot bypass it. - `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. - `compiler-driven` is the cascade arm for a behaviour-preserving type/signature edit: it skips `specify` and `planner`, and its done-signal (clean build + suite green unchanged) is the gate. It bounces on a hole to `specify` (a design choice) or `tdd` (discovered test-specifiable new behaviour), and to `debug` on a regression. 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. There is no behavioural toggle either: spec auto-sign is always on under `/boss`. 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`).