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