# `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).