/new-spec

name: new-spec
description: Author a new CAPABILITY SPEC — a living, slug-identified record of what the system must do — in a documentation-led repo whose record model separates decisions from specs. Picks a unique slug, fills the spec template, sets status Draft, walks Draft→Agreed as a human gate, regenerates INDEX, commits. Use when the user says "add a spec", "new spec", "record a capability", "write the spec for X", or invokes /new-spec. NOT for recording a decision or its rationale (use /new-adr), NOT for queueing a unit of work (use /new-plan), and NOT for a reusable rule or term (use /add-convention). Refuses cleanly in repos whose record model has no specs.

new-spec

Author one living capability spec, consistent with this repo's conventions. A spec is *supposed to change*: growth is an edit with a Revision History row, never supersession.

Step 0 — Preconditions and context

1. Confirm the repo is bootstrapped (`AGENTS.md`, `CONVENTIONS.md`). 2. Read the capability manifest (`docflow.yml` at the artefact root). **This skill applies only when the record model separates decisions from specs** (`model: decisions+specs`). On any other model — including `decisions-only`, where capability content is managed outside this repo — refuse cleanly, name the recorded model, and point at the bootstrap re-run as the way to change it. 3. Read `CONVENTIONS.md` §Capability Specs for this repo's spec rules, the language mandate (if any), and the **artefact root** — resolve `spec/`, `adr/`, and `INDEX.md` against it. 4. `ls spec/` to learn existing slugs.

Step 0.5 — Assessment (run first)

Run the shared assessment protocol before authoring:

• **Depth selector first.** Ask how deep this assessment should go:

**express** — every choice takes its recommended default; only questions with no derivable default (the free-text essentials) are still asked; **guided** — only the questions marked high-impact below, plus the free-text essentials; **full** — every question below. If the repo's `CONVENTIONS.md` records an `Assessment depth:`, pre-select it as the recommended option — the selector always appears (one narrow exception: when the invocation already answers every question the tiers differentiate, skip it and say so in one line); a recorded depth is never applied silently. Otherwise recommend **full** when the request arrived with little or no context and **express** when it is already fully specified. At any question the operator may answer "defaults from here" or "go deeper"; honour the switch immediately.

• Ask the questions below **one at a time**, each with a **recommended

option** and a one-line reason; wait for each answer.

• Use **structured selection** where the options are enumerable; free

text only where they are not (title, criteria).

• **The operator decides.** Never proceed past a question without an

answer, and never guess scope when invoked with no context.

Questions (skip any the request already answers): 1. **Slug** — kebab-case, unique under `spec/`. *Recommended: derived from the title.* *(High-impact — asked in guided: the slug is immutable once Agreed; renaming later means retiring and creating anew.)* 2. **Authorising decisions** — which decision record(s) authorise this capability (`decided-by:`). *Recommended: the one named in the request.* If none exists, offer the ADR skill first — a capability with no authorising decision is a request, not a record. 3. **Bounding constraints** — which constraint ids apply (`constrained-by:`), if the repo carries a constraints file. *Recommended: none unless one plainly applies.* 3b. **Serves** — which goal id(s) this capability advances (`serves:`), if the repo carries a `goals/` directory; every listed id must resolve to a goal file. *Recommended: the goal the request names, or none.* 4. **Walk to Agreed now?** — yes / no. *Recommended: no — Draft first, agree when the criteria are settled.* 5. **Title** — free text (asked at every depth).

Step 1 — Gather content

Ask for the pieces the template needs, one prompt at a time: the capability statement, user stories, and **numbered, testable acceptance criteria — each ending with a `Verify:` line** (an inline command, `gate-check`, or `manual`). A criterion nobody can name a check for is not ready to be written — ask, don't invent. **Avoid time-bound criteria**: one whose truth is momentary ("the directory is empty") is permanently false on every future re-run at HEAD — word criteria to be durably true, or scope them to the event they describe. Honour the language mandate if one is set.

Step 2 — Write

• Copy the repo's spec template, fill all placeholders. `id:` must

equal the filename slug. Status `Draft`, today's date, owner = current agent/human. Seed Revision History with `r1 — Initial draft`.

• Do not invent criteria, stories, or constraint references to fill

space.

Step 3 — Wire up

• Regenerate `INDEX.md`: the **Specs** section gains this spec's row

(slug, title, status). Create the section if this is the repo's first spec.

• If `domains/` exists and the repo groups specs, file it under its

domain.

Step 4 — Walk to Agreed (only on explicit approval)

`Draft → Agreed` is a **human gate**: the operator agrees the contract. Require at least one acceptance criterion, each with its `Verify:` method, before offering the walk. On agreement, set the status, append the Revision History row, regenerate `INDEX.md`. From here the slug is immutable and a normative change returns the spec to `Draft` for re-agreement.

Step 5 — Commit

Conventional Commit. A spec is not a decision record, so the `Rationale:` footer convention for decision-touching commits does not apply unless the same commit also touches one.

Step 6 — Offer the next step

An `Agreed` spec is a contract awaiting delivery. Offer to queue the work (the plan skill), tracing items to this spec