feat(specify): add spec-production entry path; split brainstorm
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.
This commit is contained in:
@@ -25,6 +25,8 @@ seven skills follow once the pattern is approved.
|
||||
├── boss/ (pilot: landed)
|
||||
│ └── SKILL.md
|
||||
├── brainstorm/
|
||||
│ └── SKILL.md
|
||||
├── specify/
|
||||
│ ├── SKILL.md
|
||||
│ └── agents/
|
||||
│ └── grounding-check.md
|
||||
|
||||
+29
-10
@@ -4,10 +4,11 @@
|
||||
[new cycle] [test-specifiable feature] [bug observed]
|
||||
| | |
|
||||
v v v
|
||||
brainstorm -> plan -> implement debug -> implement (mini)
|
||||
^ |
|
||||
| tdd -> implement (mini)
|
||||
+----(design fork)----------/ (RED executable-spec -> GREEN, like a bug fix)
|
||||
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]
|
||||
@@ -37,7 +38,7 @@
|
||||
These are two distinct axes, and conflating them is a bug.
|
||||
|
||||
- A **cycle** is one round in the pipeline graph above
|
||||
(`brainstorm → planner → implement → audit → [fieldtest]`).
|
||||
(`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
|
||||
@@ -85,9 +86,23 @@ close`); no skill performs it automatically.
|
||||
|
||||
### brainstorm
|
||||
|
||||
Hard-gate before plan. Gathers requirements, explores 2-3
|
||||
approaches with trade-offs, presents a sectioned design with
|
||||
user approval, writes the spec to the configured `spec_dir`.
|
||||
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
|
||||
|
||||
@@ -119,7 +134,7 @@ the GREEN side to the implement skill in mini mode.
|
||||
|
||||
### tdd
|
||||
|
||||
Opt-in alternative to the `brainstorm → planner` design entry,
|
||||
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
|
||||
@@ -172,7 +187,11 @@ Reviewer agents have role-specific states:
|
||||
Skipping is codified per skill, not ad hoc. Each `SKILL.md`
|
||||
documents what the skill skips and under what conditions:
|
||||
|
||||
- `brainstorm` is never skipped at cycle start.
|
||||
- `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.
|
||||
|
||||
+14
-5
@@ -9,7 +9,7 @@ lowercase snake_case. Lists are YAML sequences.
|
||||
|
||||
| Key | Type | Default | Description |
|
||||
|---------------------|--------|------------------------|-------------|
|
||||
| `spec_dir` | string | `docs/specs` | Where the brainstorm skill writes specs. |
|
||||
| `spec_dir` | string | `docs/specs` | Where the specify skill writes specs. |
|
||||
| `plan_dir` | string | `docs/plans` | Where the planner skill writes plans. |
|
||||
| `glossary` | string | (unset) | Canonical-nomenclature file (optional). If set, it is standing reading for every role — no separate `standing_reading.always` entry is needed; unset is a documented no-op. See `glossary-convention.md`. |
|
||||
| `design_ledger` | string | `docs/design/INDEX.md` | Canonical specification index (optional — projects without a design ledger can omit). |
|
||||
@@ -188,7 +188,10 @@ Per-phase configuration. Each phase has its own sub-map.
|
||||
```yaml
|
||||
pipeline:
|
||||
brainstorm:
|
||||
gates: [planner] # planner cannot start until this has run
|
||||
gates: [specify] # optional discovery; hands ratified design to specify
|
||||
optional: true # skipped when the design is settled in the sources
|
||||
specify:
|
||||
gates: [planner] # core node — planner cannot start until the spec is approved
|
||||
planner:
|
||||
gates: [implement]
|
||||
implement: {} # standard
|
||||
@@ -207,6 +210,7 @@ pipeline:
|
||||
debug:
|
||||
trigger: bug # observable misbehaviour
|
||||
red_first: true # RED test before any fix
|
||||
# specify above is a CORE node (always present); tdd below is opt-in.
|
||||
tdd: # opt-in: omit the key to disable the entry path
|
||||
trigger: test_specifiable_feature # behaviour expressible as one failing test
|
||||
red_first: true # RED executable-spec before any implementation
|
||||
@@ -217,8 +221,12 @@ pipeline:
|
||||
|
||||
Phases not listed are disabled for the project. A project that
|
||||
does not want a `fieldtest` phase simply omits the key. `tdd` is
|
||||
opt-in the same way: a profile that omits it keeps
|
||||
`brainstorm → planner` as the only design entry path.
|
||||
opt-in the same way. `specify`, by contrast, is a **core** node — it
|
||||
is the spec-production gate before `planner` on every design path,
|
||||
reachable directly from settled sources or via the optional
|
||||
`brainstorm` discovery stage. `tdd` opt-in only adds the
|
||||
test-specifiable bypass; with `tdd` omitted, the design entry paths
|
||||
are `brainstorm → specify → planner` and `specify → planner`.
|
||||
|
||||
## Example: minimal profile
|
||||
|
||||
@@ -247,7 +255,8 @@ git:
|
||||
close_marker: "closes #N"
|
||||
|
||||
pipeline:
|
||||
brainstorm: { gates: [planner] }
|
||||
brainstorm: { gates: [specify], optional: true }
|
||||
specify: { gates: [planner] }
|
||||
planner: { gates: [implement] }
|
||||
implement: {}
|
||||
audit: { mandatory_at: cycle_close }
|
||||
|
||||
Reference in New Issue
Block a user