Skills/docs/pipeline.md

Pipeline

[new cycle]                                       [bug observed]
       |                                                |
       v                                                v
 brainstorm  ->  plan  ->  implement                  debug -> implement (mini)
       (per iteration loop)
                  |
       [cycle close]
                  |
                  v
                audit  --(drift)--> plan + implement (tidy iteration)
                       --(ratify)-> --update-baseline + ratify paragraph in audit commit body
                       --(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

Phase descriptions

brainstorm

Hard-gate before plan. Gathers requirements, explores 2-3 approaches with trade-offs, presents a sectioned design with user approval, writes the spec to the configured spec_dir.

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.

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:

• brainstorm is never skipped at cycle start.
• 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.
• 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.