spec: specify spec-production entry path
Add a third dev-cycle entry path: a specify skill that produces an approved spec from given sources (settled in-context discussion or an exhaustive issue) with review but no interview. Splits brainstorm's deciding half from its producing half — brainstorm becomes optional discovery, specify becomes the sole production gate before planner, mirroring the RED->GREEN split that keeps tdd/debug honest. specify bounces to brainstorm on an unresolved design fork, the same discipline tdd uses.
This commit is contained in:
@@ -0,0 +1,308 @@
|
|||||||
|
# `specify` — Spec-Production Entry Path — Design Spec
|
||||||
|
|
||||||
|
**Date:** 2026-06-04
|
||||||
|
**Status:** Draft — awaiting user spec review
|
||||||
|
**Authors:** orchestrator + Claude
|
||||||
|
|
||||||
|
## Goal
|
||||||
|
|
||||||
|
Add a third entry path into the dev cycle: a `specify` skill that
|
||||||
|
produces an approved spec from **given sources** (a long in-context
|
||||||
|
design discussion, an exhaustive tracker issue, settled design
|
||||||
|
docs) — with review, but **without an interview**.
|
||||||
|
|
||||||
|
The driving observation: when the design is already settled, today's
|
||||||
|
`brainstorm` forces redundant work — it re-opens an interview and
|
||||||
|
re-litigates decisions the sources already made. That is friction,
|
||||||
|
and worse, the re-litigation invites reactive churn on settled
|
||||||
|
calls. But the *production* half of `brainstorm` — apply the
|
||||||
|
acceptance criterion, write the spec, parse-gate it, ground-check
|
||||||
|
it, get user sign-off — is wanted in every case. `specify` is that
|
||||||
|
production half, callable on its own.
|
||||||
|
|
||||||
|
The split is the existing toolchain philosophy applied one level up.
|
||||||
|
`tdd → implement` and `debug → implement` split a discipline across
|
||||||
|
two dispatches so the spec stays honest (the test is written before
|
||||||
|
any implementation). `specify` does the same to design work: a
|
||||||
|
**deciding** phase (`brainstorm`) and a **producing** phase
|
||||||
|
(`specify`), split so the producing phase reads the decision as a
|
||||||
|
*source* rather than making it inline.
|
||||||
|
|
||||||
|
## Architecture
|
||||||
|
|
||||||
|
Three co-equal entry paths feed one production core. `specify` is
|
||||||
|
the sole home of the production gates; `brainstorm` becomes an
|
||||||
|
**optional** discovery front-end.
|
||||||
|
|
||||||
|
```
|
||||||
|
brainstorm ──► specify ──► planner ──► implement design open (discovery + production)
|
||||||
|
specify ──► planner ──► implement design settled in sources
|
||||||
|
tdd ─────────────────────► implement (mini) test-specifiable (test = spec)
|
||||||
|
debug ───────────────────► implement (mini) bug (RED-first)
|
||||||
|
▲
|
||||||
|
└── bounce ── specify / tdd unresolved design fork → discovery
|
||||||
|
```
|
||||||
|
|
||||||
|
**The hard-gate moves.** Today `brainstorm` itself is the "no plan
|
||||||
|
without an approved spec" gate. After this cycle, **`specify`**
|
||||||
|
carries that invariant (it produces and gets sign-off on the spec,
|
||||||
|
and gates `planner`); `brainstorm` is no longer itself a gate — it
|
||||||
|
is the optional discovery stage before `specify`. The universal
|
||||||
|
invariant — *no plan without an approved spec* — is unchanged
|
||||||
|
word-for-word; only its carrier moves from `brainstorm` to
|
||||||
|
`specify`.
|
||||||
|
|
||||||
|
**The bounce-back symmetry.** `specify` is a fast path that is only
|
||||||
|
legitimate when its precondition holds — the sources resolve every
|
||||||
|
load-bearing design decision. The moment writing the spec would force
|
||||||
|
a choice between plausible designs the sources do not resolve, it
|
||||||
|
STOPs and bounces to `brainstorm`. This is structurally identical to
|
||||||
|
`tdd`'s bounce: `tdd` bounces when one honest assertion cannot pin
|
||||||
|
the behaviour; `specify` bounces when the sources cannot pin the
|
||||||
|
design. Both fast paths fall back to the same discovery skill.
|
||||||
|
|
||||||
|
**Discovery vs. production, by verb.** `brainstorm` owns *deciding*:
|
||||||
|
interview, explore 2–3 approaches, ratify the chosen design with the
|
||||||
|
user. `specify` owns *producing*: render the decision into the
|
||||||
|
canonical spec artefact, run all gates, get artefact sign-off. The
|
||||||
|
two reviews are different: `brainstorm`'s per-section ratification
|
||||||
|
asks "is this design right?"; `specify`'s Step-8 review asks "is the
|
||||||
|
written spec faithful and complete?". In the direct path there is no
|
||||||
|
design ratification (no discovery happened) — only the artefact
|
||||||
|
review. That absence *is* "with review, but without interview".
|
||||||
|
|
||||||
|
## Concrete code shapes
|
||||||
|
|
||||||
|
The canonical authoring form for this prose-skill project is the
|
||||||
|
SKILL.md body and the cross-skill topology. The user-facing artefact
|
||||||
|
the cycle delivers is `specify/SKILL.md` and the edited dispatch
|
||||||
|
logic in `boss`.
|
||||||
|
|
||||||
|
### `specify/SKILL.md` — the Iron Law (the load-bearing shape)
|
||||||
|
|
||||||
|
```
|
||||||
|
THE SOURCES MUST RESOLVE EVERY LOAD-BEARING DESIGN DECISION BEFORE THE SPEC IS WRITTEN.
|
||||||
|
IF WRITING THE SPEC FORCES A CHOICE BETWEEN PLAUSIBLE DESIGNS THE SOURCES DO NOT RESOLVE,
|
||||||
|
STOP AND BOUNCE TO `brainstorm`. DO NOT SILENTLY PICK ONE.
|
||||||
|
THE PRODUCTION GATES — ACCEPTANCE CRITERION, PARSE-EVERY-BLOCK, GROUNDING-CHECK, USER-REVIEW —
|
||||||
|
ARE NON-NEGOTIABLE REGARDLESS OF ENTRY PATH.
|
||||||
|
NO PLAN OR CODE WORK UNTIL THE SPEC HAS BEEN PRESENTED AND THE USER HAS APPROVED IT.
|
||||||
|
```
|
||||||
|
|
||||||
|
### `specify/SKILL.md` — process spine
|
||||||
|
|
||||||
|
```
|
||||||
|
Step 1 Explore / re-ground context
|
||||||
|
- direct entry: read the sources (issue body, in-context
|
||||||
|
discussion, design docs) + git log; this IS the design input.
|
||||||
|
- chain entry (from brainstorm): the ratified design narrative
|
||||||
|
is in-context; re-ground lightly (fresh git log, touched files).
|
||||||
|
Step 1.5 PRECONDITION GATE
|
||||||
|
- enumerate the load-bearing design decisions the spec must encode.
|
||||||
|
- for each: do the sources resolve it, or am I about to pick one?
|
||||||
|
- any unresolved fork → BOUNCE to brainstorm (see Error handling).
|
||||||
|
Step 2 Apply the feature-acceptance criterion + write the concrete code
|
||||||
|
(the worked user-facing example = the criterion's empirical evidence).
|
||||||
|
Step 3 Write the spec under paths.spec_dir (mandated structure).
|
||||||
|
Step 4 Self-review (placeholder / consistency / scope / ambiguity /
|
||||||
|
concrete-code / parse-every-block gate).
|
||||||
|
Step 5 Grounding-check (hard-gate) — dispatch read-only grounding-check.
|
||||||
|
Step 6 User-review gate — spec sits uncommitted; await approval;
|
||||||
|
on change request re-run Step 4 AND re-dispatch Step 5.
|
||||||
|
Step 7 Hand off to planner (spec path + iteration scope).
|
||||||
|
```
|
||||||
|
|
||||||
|
`specify` has **no interview step and no approaches step** — those
|
||||||
|
are `brainstorm`'s. It dispatches the existing `grounding-check`
|
||||||
|
agent; it introduces **no new agent**.
|
||||||
|
|
||||||
|
### `boss` — the three-way Entry-path reflection
|
||||||
|
|
||||||
|
```
|
||||||
|
boss Entry-path reflection (feature work, tdd-enabled profile):
|
||||||
|
|
||||||
|
one honest minimal assertion pins the behaviour → tdd [autonomous]
|
||||||
|
sources resolve every load-bearing decision → specify [autonomous]
|
||||||
|
writing one assertion / spec forces an unresolved
|
||||||
|
design choice → brainstorm [bounce-back]
|
||||||
|
|
||||||
|
asymmetry: tdd and specify are bounded (no open Q&A) → dispatch autonomously.
|
||||||
|
brainstorm is high-context discovery the orchestrator cannot
|
||||||
|
compact on its own → bounce-back before dispatch.
|
||||||
|
specify in /boss still pauses internally at its Step-6 user-review gate
|
||||||
|
(problem-state notify: "spec X ready, please sign off") — that is the
|
||||||
|
final sign-off pause, NOT a pre-dispatch checkpoint.
|
||||||
|
```
|
||||||
|
|
||||||
|
### Implementation shape (secondary — the before → after of each edited file)
|
||||||
|
|
||||||
|
```
|
||||||
|
brainstorm/SKILL.md
|
||||||
|
- Step 6–9 (write spec, self-review, grounding-check, user-review, hand off
|
||||||
|
to planner) ──► REMOVED (moved to specify).
|
||||||
|
- Step 9 terminal "invoke planner" ──► "hand ratified design to specify".
|
||||||
|
- Hard-Gate block + "spec before plan" framing ──► removed / re-pointed:
|
||||||
|
brainstorm is no longer itself the gate.
|
||||||
|
- Skip rules: brainstorm gains an explicit "optional when design is settled
|
||||||
|
in sources — that is specify's direct path" clause.
|
||||||
|
|
||||||
|
boss/SKILL.md
|
||||||
|
- Entry-path reflection: two-way ──► three-way (add the specify branch).
|
||||||
|
- Pipeline ASCII block: add specify node on the brainstorm→planner edge.
|
||||||
|
- Common Rationalisations / Red Flags: add the "route settled design to
|
||||||
|
brainstorm to be safe" anti-pattern (mirror of the existing tdd one).
|
||||||
|
|
||||||
|
docs/pipeline.md
|
||||||
|
- ASCII graph: brainstorm ─► specify ─► plan; specify ─► plan direct edge;
|
||||||
|
specify ─(design fork)─► brainstorm bounce edge.
|
||||||
|
- Phase descriptions: new `specify` block; brainstorm block trimmed to discovery.
|
||||||
|
- Skip rules: "brainstorm is never skipped at cycle start" ──► "specify is
|
||||||
|
never skipped at cycle start; brainstorm is the optional discovery stage
|
||||||
|
before it, skipped when the design is already settled in the sources".
|
||||||
|
|
||||||
|
docs/profile-schema.md, docs/design.md, README.md
|
||||||
|
- profile-schema pipeline: gates:[planner] moves brainstorm ──► specify;
|
||||||
|
specify documented as a CORE node (not opt-in, unlike tdd).
|
||||||
|
- design.md pipeline-form line + README skill table: add specify row,
|
||||||
|
flip brainstorm's "Mandatory?" cell to optional-discovery.
|
||||||
|
|
||||||
|
tdd/SKILL.md
|
||||||
|
- Cross-references: name specify as the sibling fast path with the same
|
||||||
|
bounce-to-brainstorm discipline.
|
||||||
|
```
|
||||||
|
|
||||||
|
## Components
|
||||||
|
|
||||||
|
- **`specify/SKILL.md` (new).** The production core. Follows the
|
||||||
|
skill template: Overview, When to Use / Skipping, the Iron Law
|
||||||
|
(precondition gate + bounce-back + non-negotiable gates), the
|
||||||
|
numbered process spine above, Handoff Contract, Common
|
||||||
|
Rationalisations, Red Flags, Cross-references. Dispatches
|
||||||
|
`grounding-check`; no new agent.
|
||||||
|
|
||||||
|
- **`brainstorm/SKILL.md` (edited).** Shrinks to discovery: explore
|
||||||
|
context, interview, 2–3 approaches, per-section design
|
||||||
|
ratification. Terminal state changes from `planner` to `specify`.
|
||||||
|
The hard-gate language and the spec-writing / self-review /
|
||||||
|
grounding-check / user-review / planner-handoff steps are removed
|
||||||
|
(they now live in `specify`). brainstorm no longer writes a spec
|
||||||
|
file; it hands a ratified design narrative to `specify` in-context.
|
||||||
|
|
||||||
|
- **`boss/SKILL.md` (edited).** Entry-path reflection becomes
|
||||||
|
three-way. `specify` direct-entry is autonomously dispatchable
|
||||||
|
(bounded, like `tdd`/`debug`), pausing only at its internal
|
||||||
|
user-review gate. The pre-dispatch bounce-back stays reserved for
|
||||||
|
a fresh `brainstorm` cycle (high-context) and for a surfaced fork.
|
||||||
|
|
||||||
|
- **`tdd/SKILL.md` (edited).** Cross-references gain `specify` as the
|
||||||
|
sibling fast path sharing the bounce-to-`brainstorm` discipline.
|
||||||
|
|
||||||
|
- **`docs/pipeline.md`, `docs/design.md`, `README.md`,
|
||||||
|
`docs/profile-schema.md` (edited).** Pipeline graph, phase
|
||||||
|
descriptions, skip rules, skill table, and the profile pipeline
|
||||||
|
block updated so all four renderings of the pipeline agree on the
|
||||||
|
three-path shape and on `specify` as the new production gate.
|
||||||
|
|
||||||
|
## Data flow
|
||||||
|
|
||||||
|
Carrier contracts (the in-context narrative is the carrier where two
|
||||||
|
skills run in the same orchestrator context — no intermediate
|
||||||
|
artefact, exactly as `tdd → implement` carries the chat history plus
|
||||||
|
the RED-test path):
|
||||||
|
|
||||||
|
| Direction | Carrier |
|
||||||
|
|-----------|---------|
|
||||||
|
| user / issue (design settled) → `specify` | the sources: issue body, in-context design discussion, design docs |
|
||||||
|
| `brainstorm` → `specify` | ratified design narrative (approaches chosen, constraints, sections approved) — in-context; brainstorm writes no spec file |
|
||||||
|
| `specify` → `grounding-check` (Step 5) | `spec_path` (absolute) + `iteration_scope` — same carrier brainstorm uses today |
|
||||||
|
| `specify` → `planner` (Step 7, on PASS or overridden BLOCK) | path to spec + iteration scope |
|
||||||
|
| `specify` → `brainstorm` (precondition bounce, or no-override BLOCK route) | the unresolved design question as a cycle request |
|
||||||
|
| `boss` Entry-path reflection | dispatches `tdd` / `specify` autonomously, or bounces back a fresh `brainstorm` cycle |
|
||||||
|
|
||||||
|
## Error handling
|
||||||
|
|
||||||
|
- **Precondition fails (Step 1.5).** `specify` finds, while
|
||||||
|
enumerating the load-bearing decisions, a fork the sources do not
|
||||||
|
resolve. It STOPs *before writing the spec* and bounces to
|
||||||
|
`brainstorm` with the design question as a cycle request. The
|
||||||
|
working tree is clean — nothing was written. This is the cheap,
|
||||||
|
early bounce (cheaper than `tdd`'s, which may discard a written
|
||||||
|
test).
|
||||||
|
|
||||||
|
- **grounding-check `BLOCK` (Step 5).** Identical failure-mode
|
||||||
|
procedure to today's `brainstorm`: present the report; on no
|
||||||
|
override, delete the just-written spec from the working tree, file
|
||||||
|
a forward backlog issue (or milestone container) naming the
|
||||||
|
unratified dependency, tell the user, end the session.
|
||||||
|
|
||||||
|
- **grounding-check `INFRA_ERROR`.** Abort; spec stays on disk;
|
||||||
|
debug the workspace out-of-band; re-dispatch.
|
||||||
|
|
||||||
|
- **Step-6 change request.** Edit the spec in place (still
|
||||||
|
uncommitted), re-run Step 4 (self-review) AND re-dispatch Step 5
|
||||||
|
(grounding-check) — the previous PASS no longer covers the edited
|
||||||
|
bytes — then return to the review gate.
|
||||||
|
|
||||||
|
- **`specify` in `/boss`.** Dispatched autonomously; runs criterion,
|
||||||
|
parse-gate, and grounding-check without a checkpoint; **pauses at
|
||||||
|
the Step-6 user-review gate** as a problem-state notify ("spec X
|
||||||
|
ready, please sign off"). The distinction from `brainstorm`: no
|
||||||
|
*pre-dispatch* checkpoint (specify is bounded, no interview), only
|
||||||
|
the final artefact sign-off.
|
||||||
|
|
||||||
|
## Testing strategy
|
||||||
|
|
||||||
|
This is a prose / Markdown skill repo with no executable test suite
|
||||||
|
and (currently) no `dev-cycle-profile.yml`. "Tests" are
|
||||||
|
**internal-consistency** properties, verified by `audit` /
|
||||||
|
architect drift-review at cycle close:
|
||||||
|
|
||||||
|
1. **No path-count drift.** No skill or doc still asserts the
|
||||||
|
two-path model. Every mention of the entry paths names three.
|
||||||
|
2. **Pipeline renderings agree.** The pipeline graph in
|
||||||
|
`docs/pipeline.md`, `README.md`, `docs/design.md`, and `boss`
|
||||||
|
are mutually consistent on the three-path shape and on `specify`
|
||||||
|
as the production gate.
|
||||||
|
3. **`specify/SKILL.md` follows the template.** Iron Law, numbered
|
||||||
|
process, Handoff Contract, Common Rationalisations, Red Flags,
|
||||||
|
Cross-references all present.
|
||||||
|
4. **No orphaned gate language in `brainstorm`.** No leftover
|
||||||
|
hard-gate / spec-writing / planner-handoff prose; its terminal
|
||||||
|
state names `specify`.
|
||||||
|
5. **Carrier contracts close.** Every `specify` carrier has a named
|
||||||
|
counterpart skill, and every skill that hands to `specify` (user,
|
||||||
|
brainstorm, boss reflection) is reflected in `specify`'s own
|
||||||
|
Handoff Contract.
|
||||||
|
|
||||||
|
**Note on the Step-5 grounding-check during this very cycle.** Because
|
||||||
|
this repo has no test suite and no profile, the `grounding-check`
|
||||||
|
hard-gate is degenerate here — there is nothing green to ratify and
|
||||||
|
the agent is under-configured. The spec's load-bearing assumptions are
|
||||||
|
plain SKILL.md content facts (brainstorm's current terminal is planner;
|
||||||
|
tdd is opt-in; boss has a two-way reflection), read and verified
|
||||||
|
directly during exploration. The agent is therefore **not dispatched
|
||||||
|
into the void**; this paragraph is the visible trace that the gate was
|
||||||
|
consciously skipped for a degenerate setup, not silently bypassed.
|
||||||
|
|
||||||
|
## Acceptance criteria
|
||||||
|
|
||||||
|
Default criterion (no project CLAUDE.md): solves a real user-facing
|
||||||
|
problem; contradicts no stated design commitment.
|
||||||
|
|
||||||
|
- **Real problem solved.** When the design is settled in the
|
||||||
|
sources, the orchestrator reaches `planner` through `specify`
|
||||||
|
with no interview and no re-litigation of settled decisions —
|
||||||
|
while still passing every production gate.
|
||||||
|
- **Anti-deference preserved (the load-bearing one).** `specify`
|
||||||
|
cannot become the lazy "sources look exhaustive, skip the
|
||||||
|
interview" path: the Step-1.5 precondition gate forces an honest
|
||||||
|
fork check, an unresolved fork bounces to `brainstorm`, and the
|
||||||
|
grounding-check and user-review gates are retained unchanged. The
|
||||||
|
reactive-deference failure class `brainstorm` exists to prevent is
|
||||||
|
not reintroduced.
|
||||||
|
- **Consistent with the toolchain's deepest commitment.** The
|
||||||
|
deciding→producing split mirrors the RED→GREEN split that keeps
|
||||||
|
`tdd`/`debug` honest; `specify` is a co-equal third entry path,
|
||||||
|
chosen by reflection, never a default.
|
||||||
|
- **No drift.** All four pipeline renderings and every cross-
|
||||||
|
reference agree on the three-path shape (verified by audit).
|
||||||
Reference in New Issue
Block a user