refactor: drop dev-cycle-profile.yml for conventions + CLAUDE.md facts
The profile was never parsed — it was prose the skill bodies told the model to read, so most slots were dead, constant across every project, or fiction (the whole pipeline block, including the "tdd is opt-in" claim, was enforced by nothing). Split it in two: constants become fixed conventions named directly by the skills (new docs/conventions.md), and the few genuinely per-project facts move to each project's CLAUDE.md under '## Skills plugin: project facts'. tdd/fieldtest/docwriter are now always available; the only behavioural toggle left is spec auto-sign. Delete docs/profile-schema.md and templates/project-profile.yml; add docs/conventions.md and a project-facts section to templates/CLAUDE.md.fragment; rewrite all SKILL/agent prose and the pipeline/design/migration/README/INSTALL docs accordingly.
This commit is contained in:
+26
-20
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: specify
|
||||
description: Use when the design is already settled — a long in-context design discussion, an exhaustive tracker issue, or a ratified design handed over by brainstorm — and a spec must be produced from those sources with review but without an interview. The spec-production core: applies the feature-acceptance criterion, writes the spec under paths.spec_dir, runs the parse and grounding-check gates, takes user sign-off, hands off to planner. Bounces to brainstorm the moment the sources do not resolve a load-bearing design decision. Co-equal third entry path alongside brainstorm and tdd.
|
||||
description: Use when the design is already settled — a long in-context design discussion, an exhaustive tracker issue, or a ratified design handed over by brainstorm — and a spec must be produced from those sources with review but without an interview. The spec-production core: applies the feature-acceptance criterion, writes the spec under docs/specs, runs the parse and grounding-check gates, takes user sign-off, hands off to planner. Bounces to brainstorm the moment the sources do not resolve a load-bearing design decision. Co-equal third entry path alongside brainstorm and tdd.
|
||||
---
|
||||
|
||||
# specify — spec-production entry path
|
||||
@@ -33,9 +33,11 @@ RED from GREEN across two dispatches so the spec stays honest;
|
||||
`specify` splits deciding from producing so the producing phase reads
|
||||
the decision as a *source* rather than making it inline.
|
||||
|
||||
This skill is **not** opt-in. Unlike `tdd` (a profile-gated bypass),
|
||||
`specify` is a core pipeline node: it is the gate before `planner` on
|
||||
every design path that is not a bug fix or a test-specifiable feature.
|
||||
Where `tdd` is one entry path among three (chosen when behaviour is
|
||||
test-specifiable), `specify` sits on every prose-design path — it is
|
||||
not bypassed for those.
|
||||
|
||||
## When to Use / Skipping
|
||||
|
||||
@@ -52,8 +54,8 @@ Triggers:
|
||||
load-bearing decision. Use `brainstorm` (its discovery is what
|
||||
resolves the fork). `specify` itself bounces here the moment it
|
||||
detects this (see The Iron Law and Step 1.5).
|
||||
- A test-specifiable feature, on a profile that enables `tdd` — the
|
||||
RED executable-spec is the spec. Use `tdd` directly.
|
||||
- A test-specifiable feature — the RED executable-spec is the spec.
|
||||
Use `tdd` directly.
|
||||
- An observed bug — use `debug` directly (RED-first).
|
||||
- A tidy iteration — use `audit` directly.
|
||||
- A trivial mechanical edit — per the project's CLAUDE.md carve-out.
|
||||
@@ -96,7 +98,7 @@ Before producing anything, establish what the sources actually say:
|
||||
- **Chain entry** (from `brainstorm`): the ratified design narrative
|
||||
is already in-context. Re-ground lightly — fresh `git log`, the
|
||||
files the design touches — rather than re-deriving it.
|
||||
- If the project has a design ledger under `paths.design_ledger`,
|
||||
- If the project has a design ledger (its CLAUDE.md project facts),
|
||||
walk to the contracts the work touches. Note any `status:
|
||||
aspirational` source: its code is a target, not verified fact —
|
||||
track it for the Step-4 parse gate.
|
||||
@@ -199,16 +201,17 @@ honest* slice of the north-star program the infrastructure serves. "No
|
||||
surface so no code to show" is the rationalisation to refuse.
|
||||
|
||||
**Code lifted from an aspirational source is a hypothesis, not
|
||||
evidence.** If the concrete code here is lifted from a `design_models`
|
||||
evidence.** If the concrete code here is lifted from a design-models
|
||||
file (or any `status: aspirational` source, per Step 1), it carries no
|
||||
validation by default. Treat it as the spec's most suspect bytes: it
|
||||
must clear the Step-4 parse-every-block gate before PASS.
|
||||
|
||||
### Step 3 — Write the spec
|
||||
|
||||
Path: under `paths.spec_dir`, with a name per the project's
|
||||
`naming.policy` (see profile schema). Determine the next slot per the
|
||||
policy.
|
||||
Path: under `docs/specs`, named per the fixed naming convention —
|
||||
`NNNN-slug.md`, 4-digit per-directory counter (see
|
||||
`docs/conventions.md`). Determine the next free number by scanning the
|
||||
directory.
|
||||
|
||||
Structure:
|
||||
|
||||
@@ -256,10 +259,10 @@ Inline checklist (not a subagent dispatch):
|
||||
worked user-facing example for a surface cycle)? A load-bearing
|
||||
change described only in prose is a self-review failure to fix.
|
||||
6. **Parse-every-block gate.** Extract every fenced code block and run
|
||||
it through the `spec_validation` gate defined in
|
||||
`docs/profile-schema.md` (which owns the parser-invocation
|
||||
protocol, the no-parser skip, the malformed-entry failure, and the
|
||||
no-op when the profile declares no `spec_validation`). A parse
|
||||
it through the spec-validation parsers the project declares in its
|
||||
CLAUDE.md project facts (a fence label with no parser is a documented
|
||||
skip, never a silent pass; a malformed entry fails closed; the whole
|
||||
gate is a no-op when the project declares no parsers). A parse
|
||||
failure is a self-review failure — fix the spec; do not pass
|
||||
unparsed bytes downstream. Paste the parse-trace into the chat: a
|
||||
visible trace attests the gate fired; its absence means it was
|
||||
@@ -338,7 +341,8 @@ the commit itself.
|
||||
**In `/boss` (autonomous):** `specify` is dispatched autonomously —
|
||||
it is bounded (no interview). It runs the criterion, parse, and
|
||||
grounding-check gates without a checkpoint. What happens at *this*
|
||||
gate then depends on the profile slot `pipeline.boss.spec_auto_sign`:
|
||||
gate then depends on whether the project enables spec auto-sign (its
|
||||
CLAUDE.md project facts):
|
||||
|
||||
- **Slot absent or `false` (default):** `specify` **pauses here** as a
|
||||
problem-state notify ("spec X ready, please sign off") and waits for
|
||||
@@ -434,7 +438,7 @@ is invoked from `specify`. NO direct jump to `implement`.
|
||||
|
||||
Hand off carries:
|
||||
|
||||
- path to the spec under `paths.spec_dir`
|
||||
- path to the spec under `docs/specs`
|
||||
- iteration scope ("the first iteration covers section X+Y of the
|
||||
spec")
|
||||
|
||||
@@ -488,8 +492,9 @@ discipline `tdd` applies when behaviour is not test-specifiable.
|
||||
- "The sources are thorough, skip a gate" thoughts (any flavour)
|
||||
- A load-bearing change described in prose with no before → after code
|
||||
block; a surface cycle with no worked user-facing example
|
||||
- A spec carrying a code block whose fence label has a configured
|
||||
`spec_validation` parser, committed without a parse-trace in the chat
|
||||
- A spec carrying a code block whose fence label has a spec-validation
|
||||
parser (the project's CLAUDE.md project facts), committed without a
|
||||
parse-trace in the chat
|
||||
- Lifting code verbatim from a `status: aspirational` source without
|
||||
flagging it for the Step-4 parse gate
|
||||
- Editing the spec file after a Step 5 PASS without re-dispatching
|
||||
@@ -520,7 +525,8 @@ discipline `tdd` applies when behaviour is not test-specifiable.
|
||||
PASS / BLOCK / INFRA_ERROR.
|
||||
- **Agent dispatched (auto-sign only):** `agents/spec-skeptic.md` —
|
||||
dispatched in Step 6 five times in parallel (one per lens) ONLY under
|
||||
a `/boss` session with `pipeline.boss.spec_auto_sign` enabled. Each
|
||||
a `/boss` session with spec auto-sign enabled (the project's CLAUDE.md
|
||||
project facts). Each
|
||||
juror tries to refute the spec along its lens; a unanimous `SOUND` is
|
||||
what lets the orchestrator sign in the user's place. An editorial-lens
|
||||
`BLOCK` (`criterion` / `ambiguity` / `plan-readiness`) is self-
|
||||
@@ -529,7 +535,7 @@ discipline `tdd` applies when behaviour is not test-specifiable.
|
||||
an exhausted budget falls back to the human sign-off pause.
|
||||
- **Ad-hoc dispatch.** The orchestrator MAY also ad-hoc dispatch
|
||||
`../planner/agents/plan-recon.md` during Step 1 when the work enters
|
||||
code territory not recently read; opt-in, not part of the standard
|
||||
process.
|
||||
code territory not recently read; discretionary, not part of the
|
||||
standard process.
|
||||
- **Project feature-acceptance criterion:** declared in the project's
|
||||
`CLAUDE.md`. Applied prospectively in Step 2.
|
||||
|
||||
Reference in New Issue
Block a user