/spec

Goal

Turn a fuzzy request into two committed artifacts — a spec (what/why) and a plan (how, in waves) — before any implementation edit, then hand the plan to the user for approval. Approval is what unlocks editing: plan-gate.py writes the plan-approval flag, and spec-gate.py (a PreToolUse gate) stops asking once that flag exists.

This skill supplies the methodology; the enforcement is a tool boundary. You cannot prompt your way past spec-gate — you produce the artifacts and get the plan approved, or you flip the mode. That separation is the point.

Steps

1. Brainstorm

Explore the request before committing to a shape:

a. Restate the request in one sentence and name the success criterion. b. Surface the 2-3 plausible approaches and the tradeoff between them; pick one and say why. If the request is ambiguous, ask — don't guess. c. List what's explicitly out of scope (prevents scope creep later).

--interview — opt-in deep-interview submode

The default brainstorm is a single pass. /spec <slug> --interview replaces step 1b's one-shot "ask if ambiguous" with a structured question loop for requests fuzzy enough that a wrong guess commits the whole spec to the wrong shape. It is opt-in by design: simple requests keep the single pass, and the enforcement story is untouched — the spec-gate tool boundary neither knows nor cares which submode produced the artifacts.

1. Unknowns table. List every unknown in the request; mark each decision-changing (Y/N) — would different answers produce different specs? N-unknowns are implementation details; leave them to the plan.
2. Batch-question the Y rows only — at most 4 questions per round, each naming the options and your recommended default.
3. Re-score after the answers. Answers resolve rows and surface new unknowns; add those to the table and mark them Y/N. This is the decision-tree pruning: each round should shrink the Y set.
4. Terminate on either condition (whichever comes first):
   • the table has zero open decision-changing unknowns, or
   • 3 rounds have run. Unresolved rows carry into spec.md under ## Open questions — named and deferred beats silently guessed.
5. Run the interview at effort: low (advisory). The loop drafts against what the user already surfaced rather than discovering edge cases, and the more detailed the approved spec, the lower the implementation effort can be (docs/model-routing.md → The effort axis).

The interview's Q/A trail is recorded in spec.md under ## Interview log (one line per question: the question, the answer, the decision it settled), so the spec shows why it has its shape, not just the shape.

--score-candidates — opt-in candidate-scoring submode

Step 1b picks an approach in prose. When the harder question is which problem or approach to commit to — a wide field where the pick should be earned, not asserted — /spec <slug> --score-candidates replaces 1b's one-line "pick one and say why" with an explicit numeric pass. Like --interview, it is opt-in and touches only the brainstorm; the spec-gate boundary is indifferent to it.

1. List the candidates. Enumerate the plausible problems/approaches — the field before pruning (the reference workflow scored 18, kept 3). A field of one means you don't need this submode.
2. Name the dimensions. 3–5 criteria that actually discriminate (e.g. impact, effort, risk, fit). Reuse the repo's scoring idiom — each dimension scored 0–5, aggregated per candidate — rather than coining a new scale (docs/scoring-convention.md, core/infra/supervisor-goal-audit.sh).
3. Score and rank. Build a candidates × dimensions table, aggregate, and take the top-K (usually K=1, sometimes a short list the plan sequences). The score ranks; it never gates — a low-scoring candidate is dropped by judgment, not auto-rejected by a threshold.
4. Record the winner and the cut. The chosen candidate becomes step 1b's pick; the runners-up and why they lost are the audit trail.

The scoring table is recorded in spec.md under ## Candidate scoring, so the spec shows the field it chose from, not just the choice.

2. Write spec.md

Pick a short kebab-case <slug> and write .agent/plans/<slug>/spec.md:

# <slug> — spec

## Problem
<the one-sentence problem + why it matters>

## Success criteria
- <falsifiable, checkable outcomes>

## Approach
<the chosen approach + the tradeoff rejected>

## Out of scope
- <explicitly deferred>

## Must not
- <behaviour the feature must never show — falsifiable, the thing to check in `backticks`>
- none — <reason>          <!-- use INSTEAD of lines when nothing is forbidden -->

## Edge cases
- <unspoken detail: empty input, failure, concurrency, legacy data> → <DECIDED behaviour>
- none — <reason>          <!-- use INSTEAD of lines when there are none -->

## Decisions
- D1: <decision> — settled by <interview|approach|user>
- none — <reason>          <!-- use INSTEAD of D-lines when nothing was decided -->

## Candidate scoring        <!-- --score-candidates runs only -->
| candidate | <dim1> | <dim2> | <dim3> | total | verdict |
|---|---|---|---|---|---|
| <winner>  | 5 | 4 | 5 | 14 | chosen |
| <runner-up> | 3 | 5 | 2 | 10 | cut: <why> |

## Interview log            <!-- --interview runs only -->
- Q: <question> → A: <answer> → settled: D1

## Open questions           <!-- --interview runs only -->
- <unresolved decision-changing unknown, carried, with its default>

## Decisions is mandatory on every spec, submode or not: one D<n> line per decision, or - none — <reason> when nothing was decided. D-IDs are stable — never renumber; append new ones. settled: in the interview log cites the D-ID. /verify-completion checks that the completion claim covers each D-ID (advisory, dryrun) through the claim's optional decisions: [{id, evidence}] field.

A user-visible change needs a user-action criterion. When the change alters something a person sees or operates (a page, a control, a command's output), at least one success criterion states the action the person takes and what they then see — e.g. "clicking Mode switches the board to game mode, at 390px and 1440px wide" — and names the command that checks it by performing that action (a browser-driving check for a page, the real invocation for a CLI). Put that command in the completion claim's tests: so /supervise --verify-blocking refuses completion until it passes. A source grep or a static screenshot does not satisfy this criterion.

## Must not and ## Edge cases are mandatory too, with the same - none — <reason> escape. Decide them here, with the human, before the model fills the gap silently: each line becomes a negative test. plan-lint.sh checks their backticked terms like success criteria (one term must appear in a Wave step), and plan-checker checks that a step's verify actually provokes each situation.

The remaining trailing sections are submode-specific — ## Candidate scoring on --score-candidates runs, ## Interview log / ## Open questions on --interview runs; a single-pass spec omits them.

3. Write plan.md

Write .agent/plans/<slug>/plan.md as ordered waves — the shape /supervise consumes:

# <slug> — plan

## Wave 1: <name>
- <step> → verify: <check>

## Wave 2: <name>
- <step> → verify: <check>

plan.md holds only the # <slug> — plan title and ## Wave N: <name> sections; any other ## section fails lint. Every Wave needs at least one step, and steps may be -, * or 1. bullets.

Decompose into vertical slices. Each Wave is a thin end-to-end slice (a tracer bullet through every layer the feature touches — data, logic, interface, test) that works and can be checked on its own, not a horizontal layer such as "all the schema, then all the handlers". Order the first slice to prove the riskiest assumption. Where a step needs another step's output, say so in the step text with an explicit blocking edge — (blocked-by: Wave 1 step 2) — and leave steps with no edge free to run in parallel. Edges live inside the step line because plan-lint.sh allows only the title and ## Wave N: sections; the steps still need → verify:, and each spec success-criterion's backticked term must appear in some step.

Every step names its verification. A plan whose steps aren't checkable isn't done. Default each → verify: to an executable check — a command whose exit code decides (bash core/tests/<battery>.sh, grep -q <artifact>); prose verification is allowed only when it carries reason: <why no command can check it> on the same step — that is the marker plan-lint.sh looks for.

3.5 Check the plan

Before asking for approval, lint and review the plan:

1. Run bash "${CLAUDE_PLUGIN_ROOT}/core/infra/plan-lint.sh" <slug> (deterministic). Exit 1 names the defects: a missing ## Wave N: header, a step without → verify:, a prose verify without reason:, a spec missing ## Decisions, ## Must not or ## Edge cases, or a success criterion, must-not or edge-case line with backticked terms of which none is mentioned in a Wave step (any one hit is enough, not every term).
2. When lint passes, dispatch the read-only plan-checker agent (agent-harness:plan-checker) with the spec.md and plan.md paths. It returns a verdict-schema object (docs/scoring-convention.md); its refutations are the semantic findings.
3. Revise plan.md (and spec.md if a decision is missing), then re-run. At most 3 rounds in total.
4. Whatever lint defects or refutations remain after the last round are listed in the Step 4 approval message — never silently dropped.

4. Route to approval

Present the plan to the user and exit plan mode (ExitPlanMode). User approval is what triggers plan-gate.py to write /tmp/agent-plan-approved. From that point spec-gate allows edits for the rest of the session (the flag is the dedup — approve once, not per-edit). SessionStart/Stop clear the flag, so each new session starts unapproved.

This skill is complete when spec.md and plan.md both exist under .agent/plans/<slug>/ and the plan has been routed through ExitPlanMode — approval itself is the user's move, not yours.

Enforcement — the tool boundary, not prompt coercion

core/hooks/spec-gate.py runs on every Write|Edit|MultiEdit. When no plan is approved this session and the target is substantive impl code (matches the scope regex, not a test/type/config/doc/meta file, not a risk area), it acts:

Deny vs ask. The gate uses ask, not deny. A planning-discipline gate is reversible — the edit isn't destructive and the escape is trivial — so ask (the harness default for reversible gates) is more defensible than a hard deny, and it de-risks a false positive by leaving the user in control.

Escapes

Two, both named in the gate's own reason message:

1. Approve a plan via ExitPlanMode (this skill's normal path) → the flag is written and edits are allowed for the session.
2. Set AGENT_SPEC_GATE_MODE=off → disable the gate entirely.

Hard rules

• Spec and plan before impl. The artifacts come first; editing is what they unlock.
• Never hand-write the approval flag. It's written by plan-gate.py on real approval — forging it defeats the gate.
• The scope is substantive impl code only. Tests, types, config, docs, and .agent/ meta are out of scope by design; risk-area paths defer to their own hooks. Don't widen the gate to nag on trivial edits.

Credits

The vertical-slice and blocking-edge guidance adapts to-tickets in mattpocock/skills (MIT). Rewritten in this repo's own words.