Brummel
7a58a530b1
The selector forced every task through the heaviest methodology's
critical path: a behaviour-preserving, type-enumerable change paid the
same specify -> planner -> implement front-half as a novel feature,
because it was neither new behaviour (tdd) nor an observed bug (debug)
and so fell to specify by elimination. Two coupled defects — a selector
with no verification axis, and an all-or-nothing executor — kept the
existing lighter path unreachable and uneconomical. This fixes both.
Part A — verification-keyed selector (boss/SKILL.md):
- Replace the three-way "design line" with an ordered cascade that adds
a verification/enumeration axis ahead of the settled-vs-fork question.
Each lighter arm carries a positive trigger matched by signature, not
reached by elimination.
- New `compiler-driven` arm: a type/signature edit at a definition site
that propagates mechanically. Observe-then-bounce — make the edit,
build, run the suite; clean build AND suite green unchanged commits;
a hole bounces up (specify for a design choice, tdd for discovered
test-specifiable new behaviour); a regression bounces to debug.
- The observed-bug RED-first gate is first in the cascade, so a
mechanical-looking fix cannot bypass it.
- The straddle rule ("add an enum variant") is codified as a rule:
mechanical/forwarding -> compiler-driven; encodes new behaviour ->
tdd/spec; doubt routes up.
- The executor is the elevated inline carve-out plus a shipped workflow,
not a heavy new skill ("the largest concrete win is small").
Part B — Workflow substrate (implement/workflows/):
- implement-loop.js: the per-task loop as a deterministic script. Each
phase (implementer -> spec-compliance -> quality, + tester for E2E) is
a separate top-level agent() call, so a single phase is independently
invokable and inter-phase aggregation/re-loop is code. Retires the
implement-orchestrator agent's inline-role-switch workaround (the four
phase agents survive as the agent-types the script dispatches).
- compiler-driven-edit.js: the observe-then-bounce loop.
- install.sh / uninstall.sh symlink shipped workflows into
~/.claude/workflows/.
- specify and brainstorm stay prose + interactive (human-intent oracle);
only the autonomous/mechanical loops moved. try-and-error is deferred.
Docs (pipeline taxonomy, design, agent-template, migration, README) and
all selector<->executor cross-references updated; the arm and its
executor are co-located so a future re-route through the full loop is a
visible regression.
Verified by an adversarial multi-agent pass: PASS on all six acceptance
criteria; two coherence concerns fixed. The shipped scripts are
syntax-validated but exercised only in a downstream target project (the
skills repo is not itself a pipeline target).
closes #7
298 lines
14 KiB
Markdown
298 lines
14 KiB
Markdown
# 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`, 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.
|
|
|
|
The sign-off is the user's by default, including under `/boss`. The
|
|
one exception is spec auto-sign (a project that enables it in its
|
|
CLAUDE.md project facts): with it on, a `/boss` run may sign a spec in
|
|
the user's place — 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`
|
|
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.
|
|
|
|
### 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. The only behavioural
|
|
toggle is spec auto-sign under `/boss`, declared in a project's
|
|
CLAUDE.md project facts. 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`).
|