Skills/docs/pipeline.md

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.

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 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.

Outside /boss the sign-off is the user's. Under /boss the orchestrator may sign a spec in the user's place through the auto-sign gate — 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, specify gives the scope-fork juror an auditable source for an in-context fork resolution (Step 1.5) — a provenance- bearing reconciliation comment when a seeding issue lags the discussion, or a freshly created seeding issue when the cycle had none — so the juror can ratify the resolution instead of blocking for lack of one. 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).