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. 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 milestone
   fieldtest always runs **full tier** (the probe tier is
   per-cycle only — `../fieldtest/SKILL.md` § Two tiers: probe
   and full), so this floor is unconditional. 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.

## Harvest sweep

A recognised batch shape for draining settled single-issue
backlog. When small, settled items accumulate on the tracker
(bundled fieldtest findings, absorbed leftovers, mechanical
one-offs), one full pipeline cycle per item is structurally
uneconomical; a harvest sweep drains them in one batch:

- the settled issue bodies stand in for spec and plan — each
  item is already ratified and bite-sized, so `specify` and
  `planner` are skipped by design (the exception is registered
  in § Skip rules);
- the implementer works in sequential batches of 2-3 items —
  direct `implementer` dispatches (the `implement-loop` carrier
  needs a plan the sweep deliberately lacks), with no per-task
  review pair; the whole-diff review below replaces it;
- the sweep closes with one **independent diff review over the
  whole sweep** — an ad-hoc fresh-context reviewer over the
  sweep's full diff, independent of the orchestrator and the
  implementers (the per-task reviewer carriers do not fit a
  whole-sweep diff) — then the mandatory `audit` close, and one
  compact `fieldtest` under its normal skip rules (a
  zero-surface sweep skips it).

The whole-diff review is **not removable**. Unlike a planned
cycle, where the task is the unit of review (`planner`'s
decomposition discipline), the sweep amortises review over the
batch — and in the consumer-project sweep this shape was
ratified from (recorded on issue #36), that one review caught
the only substantive error, which originated from orchestrator
+ fieldtest consensus, not from the implementers.

A sweep is orchestrator-decided at queue selection — a
judgement call like the `fieldtest` / `docwriter` dispatches,
not an arm of the selector cascade; the trigger is observed
accumulation of settled single-issue items.

## Cycle recon

Recon fan-out is budgeted **per cycle, not per phase**. The field
evidence behind the budget (issue #35, one bounded cycle): a broad
Explore-type sweep grounding `specify` (151k tokens) plus the
`plan-recon` dispatch grounding `planner` (99k tokens) overlapped
~40 % — two full recon passes over the same territory, the single
biggest obligatory per-cycle cost. This section is the single
source of the budget, reuse, and delta rules; the skills point
here and add only their own dispatch mechanics.

- **At most ONE full recon dispatch while a valid cycle recon
  exists** — the **cycle recon**. It is a `plan-recon` dispatch
  (`../planner/agents/plan-recon.md`) in the pre-spec carrier
  form, normally fired at `specify` Step 1 when the work enters
  code territory the orchestrator has not recently read; an
  ad-hoc dispatch `brainstorm` fired earlier in the same cycle is
  the cycle recon instead (subject to the coverage condition
  below). One report serves every downstream consumer: the spec's
  concrete code shapes and the plan's file-map. Normally that is
  one full dispatch per cycle; a further full dispatch is
  legitimate only via the fallback below.
- **Broad exploration sweeps are not recon.** No Explore-type
  fan-out for spec, plan, or pre-dispatch grounding — grounding
  fan-out goes through the one cycle-recon dispatch. This binds
  the orchestrator in every mode, `/boss` included.
- **Reuse over re-dispatch.** A downstream phase reuses the
  cycle-recon report while ALL of these hold:
  - *Freshness* — no commit since the dispatch has touched the
    paths the report maps (`git log <since-recon> -- <mapped
    paths>` is empty; commits elsewhere — fixtures, tracker
    side-effects — do not invalidate it). In a multi-iteration
    cycle, iteration 1's commits to mapped paths invalidate the
    report for iteration 2's planning.
  - *Quotability* — the orchestrator can still quote the report's
    Modify entries verbatim. A summarized memory of the report is
    not the report. (The designed reuse window is the standard
    same-session `specify` → `planner` handoff; across a session
    break the fallback below applies.)
  - *Coverage* (brainstorm-fired recons only) — the ratified
    design's territory appears in the report's file-map or
    existence-table rows, not merely as a one-line out-of-scope
    acknowledgement. Missing territory is a delta below; a design
    that pivoted wholly outside the mapped territory voids the
    dispatch as cycle recon, and `specify` fires the cycle recon
    afresh.
- **Delta dispatches do not count against the budget.** A delta
  is a narrow re-dispatch whose `focus_hint` names the gap; its
  bounded contract is **Delta dispatch** in
  `../planner/agents/plan-recon.md`. Triggers:
  - the spec names a path or symbol that appears in neither the
    cycle recon's file-map nor its existence table;
  - MANDATORY: the iteration scope is a signature / variant /
    removal or content-pin-perturbing scope and the cycle recon
    carries no compile-driven site set for it — `planner` MUST
    delta-dispatch before planning that scope. (`specify` avoids
    this delta by naming the anticipated change shape in
    `recon_scope`, arming the compile-driven enumeration inside
    the cycle recon itself.)

  Two deltas in one planner run is the smell that the iteration
  scope is too broad — re-read the spec.
- **A full re-dispatch is the bounded fallback, not a failure**:
  no cycle recon exists (a direct tidy dispatch that skipped
  `specify`; a session break), or a reuse condition failed. The
  cost regression is capped at the pre-consolidation status quo —
  one full dispatch.

## Phase descriptions

### brainstorm

Optional discovery front-end. Enumerates the cycle's load-bearing design
forks, then — instead of a serial interview — populates them with a parallel
swarm of grounded, genuinely-opposed `synthetic-user` stances and triages the
result: a fork the swarm settles on a *cited shared ground* was derivable and
is decided (the user vetoes); a fork it splits on, or agrees on with no citable
ground, is a direction fork the user settles. The orchestrator authors the 2-3
approaches from the populated space (never the swarm) and hands the ratified
design to `specify` (it writes no spec itself). A fire-check skips the swarm
when there are too few forks or the project is below a grounding floor
(greenfield, no ledger to cite against), falling back to a direct interview.
Skipped entirely when the design is already settled in the sources — that work
enters through `specify` directly. Under `/boss` the swarm runs autonomously:
convergent forks are decided and recorded on the reference issue, only a
divergent direction fork (or a sub-floor greenfield design) bounces to the
user.

### 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 working file —
git-ignored, never committed, shell-`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. Its code grounding comes from
the single cycle-recon dispatch (§ Cycle recon), never a broad
exploration sweep. 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 keeps the signed
spec as a git-ignored working file (never committed), records the
autonomous sign on the run's reference issue, 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` (an ephemeral,
git-ignored working file, shell-`rm`'d alongside the spec at cycle
close — see `conventions.md` § Lifecycle) that the implement skill can
execute task-by-task. Its file-map normally comes from reusing the
cycle-recon report (§ Cycle recon); it dispatches `plan-recon` only
for that section's delta triggers, or in full when no valid cycle
recon exists.

### 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 and tests directly in the working tree as
unstaged changes; never commits. The end-report carries the finished
stats.json and — on `PARTIAL`/`BLOCKED` — `BLOCKED.md` contents, which
the orchestrator writes (issue #29 retired the finalize dispatch that
only templated the script's own aggregate).

### 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 discards every working-tree spec and plan
with a plain shell `rm` (nothing to `git rm` — they were never
committed); the cycle-close commit contains only code and ledger changes
(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 (probe tier, for a
single-axis surface delta: 1-2 tasks on that axis — see
`../fieldtest/SKILL.md` § Two tiers: probe and full), 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. The one batch exception is the harvest sweep
  (§ Harvest sweep): its settled issue bodies are the ratified spec
  source, so no new spec is written.
- `planner` is never skipped at iteration start, except for the
  side paths that carry no prose plan: the bug-driven
  `debug → implement (mini)` path, the `compiler-driven` path
  (whose "plan" is the type-checker's enumeration of edit sites),
  and the harvest sweep (whose items are already bite-sized —
  § Harvest sweep).
- `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`).