Brummel
4f83305525
Add `specify` as a third co-equal entry path into the dev cycle: it produces an approved spec from already-settled sources (an exhaustive issue, a long in-context design discussion, or a design brainstorm just ratified) with review but no interview. This is the producing half of a deliberate deciding/producing split — `brainstorm` shrinks to optional discovery, `specify` becomes the sole spec-production gate before `planner`, mirroring the RED->GREEN split that keeps tdd/debug honest. What moved: - brainstorm/SKILL.md: stripped of the hard-gate, the acceptance criterion, write-spec, self-review, grounding-check, user-review, and planner-handoff steps; terminal state is now handing a ratified design narrative to specify. Steps renumbered 1-5 (production steps left). - specify/SKILL.md (new): the production core, with a precondition gate (Step 1.5) that bounces to brainstorm the moment the sources do not resolve a load-bearing decision — the same discipline tdd uses. - The grounding-check agent moved brainstorm/agents/ -> specify/agents/ (no-orphan-agents: it lives under its dispatcher), refs repointed. - boss/SKILL.md: Entry-path reflection is now three-way (tdd / specify / brainstorm). specify dispatches autonomously (bounded, no interview) and pauses at its user-review gate; only a fresh brainstorm cycle stays a pre-dispatch bounce-back. - pipeline.md, README, profile-schema, the profile template, and the migration layout updated so every pipeline rendering agrees; specify is a CORE node (not opt-in, unlike tdd) carrying gates: [planner]. Design alternative rejected: parallel sibling skills sharing a docs/spec-production.md (extract-to-doc). Chosen extract-and-chain instead — the shared surface is ~70%, so a shared doc would either become the skill body or drift; chaining keeps one executed home for the gates. Verification (prose repo, no test suite): the spec's internal- consistency grep suite (no two-path drift, no direct brainstorm->planner edge, specify referenced in every rendering, grounding-check single home under specify, specify structural completeness) all green. Orchestrator inspection additionally fixed two dead step-refs the plan under-scoped (a "(Step 4)" lift-validation pointer and a "Skipping Step 7 self-review" red flag, both pointing at steps brainstorm no longer has) and corrected six pre-existing brainstorm->planner renderings in pipeline.md and tdd that predated this cycle. Known follow-ups (non-blocking): the committed spec writes `skills/specify/` in places (typo; skill dirs are repo-top-level) — to be corrected separately. The grounding-check hard-gate was degenerate for this very cycle (this repo has no profile and no test suite); the skip is documented in the spec and the session.
223 lines
9.5 KiB
Markdown
223 lines
9.5 KiB
Markdown
# 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.
|