/spec

name: spec
description: |
  Create, amend, or backprop bugs into SPEC.md at repo root. Sole mutator
  of the project spec. Triggers when the user asks to write a spec, start
  a new spec, distill a spec from existing code, add invariants, amend
  sections (§G, §C, §I, §V, §T, §B), or record a bug via backprop.
  Common phrasings: "write the spec for...", "new spec", "bug: ...",
  "amend §V.3", "distill spec from code", "spec this idea". Reads and
  follows FORMAT.md for the caveman encoding rules and pipe-table shape
  of §T and §B.

spec — spec mutator

Read `FORMAT.md` at repo root if not already loaded. Caveman skill applies to all writes here.

DISPATCH

Inspect user request and project state:

1. No `SPEC.md` at repo root AND args describe idea → **NEW** 2. No `SPEC.md` AND `from-code` in args → **DISTILL** 3. `SPEC.md` exists AND args start `bug:` → **BACKPROP** 4. `SPEC.md` exists AND args start `amend` → **AMEND** 5. `SPEC.md` exists, no args → ask user which mode

INPUTS — spec is the sole mutator

The other verbs produce material; spec writes it. Ingest their handoff blocks into the right section, show a diff, write on OK:

• **grill** → sharpened §G + §C
• **research** → §R rows (add the §R section if absent)
• **review** → drafted §V lines + the risk verdict
• **deepen** → §I/§V/§T amendments

⊥ rewrite a section the handoff did not name. Sectioned ownership (see FORMAT.md).

NEW — idea → spec

Input: user idea. If it arrived fuzzy, prefer running **grill** first.

Steps: 1. Extract goal (1 line, caveman). → §G. 2. List constraints user stated or implied. → §C. 3. List external surfaces user named. → §I. 4. §R only if **research** ran — else omit the section (right-size). 5. Propose initial invariants. → §V (numbered V1…). 6. Break goal into ordered tasks. → §T pipe table, all status `.`, ids T1… 7. §B section with header row only (`id|date|cause|fix`).

Write to `SPEC.md`. Show user full file. Ask: "spec OK? `/review` if high-blast-radius, else `/build`."

DISTILL — code → spec

Walk repo. Produce §G (infer from README/package.json/main entry), §C (infer from stack), §I (enumerate public APIs/CLIs/configs), §V (derive from tests and assertions), §T (one task per known TODO or missing test), §B (empty).

Caveman everywhere. Flag uncertain items with `?` in text so user can confirm.

BACKPROP — bug → §B + §V

Input: `bug: <description>`.

Steps: 1. Parse bug description. 2. Find root cause (read relevant code). 3. Decide: would a new invariant catch recurrence? If yes → draft `V<next>`. 4. Append §B row: `B<next>|<date>|<cause>|V<N>`. 5. Append new invariant to §V. 6. If fix also changes behavior → add/update §T rows. 7. Show diff. Apply only on user OK.

Rule: every bug gets a §B entry. Invariant optional but preferred.

AMEND — targeted edit

Input: `amend §V.3` or `amend §T` etc.

Read that section. Show current. Ask user what changes. Write. Show diff.

Never silently rewrite sections user did not name.

OUTPUT RULES

• Caveman format per `FORMAT.md`.
• Preserve identifiers, paths, code verbatim.
• Numbering monotonic — never reuse §V.N or §B.N.
• §T row `cites` column ! list §V/§I deps: `T5|.|impl auth mw|V2,I.api`.

NON-GOALS

• No sub-agents. Main thread writes.
• No dashboards, no logs, no state files beyond SPEC.md itself.
• No auto-build after spec. User invokes build explicitly.