Skills/docs/pipeline.md

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 the configured spec_dir, runs the parse-every-block and grounding-check gates, 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, not opt-in (unlike tdd).

planner

Hard-gate before implement. Produces a placeholder-free, bite-sized implementation plan in the configured plan_dir 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

Opt-in alternative to the brainstorm → specify → planner design entry, 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 an opt-in alternative entry to brainstorm for test-specifiable work; it bounces back to brainstorm on a design fork. A profile that omits the tdd phase disables it.
• 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

The phase set, gating, and conditional dispatch are configured in the project profile under pipeline:. A project that does not want fieldtest simply omits the key. A project that wants a different gate set (e.g. planner without a brainstorm gate, for trivial bug-fix iterations) configures it there.

See profile-schema.md for the syntax.

If the profile sets paths.glossary, that file is standing reading for every role — the canonical-nomenclature source every skill and agent consults (see glossary-convention.md). Unset, it is a no-op.