# Spec

Create, amend, or backprop bugs into SPEC.md at repo root.

- Repository: https://github.com/JuliusBrussee/cavekit (1157 stars)
- Category: Writing
- License: MIT
- Last updated: 2026-08-14
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add JuliusBrussee/cavekit --skill spec -g -a claude-code -y`
Codex: `npx skills add JuliusBrussee/cavekit --skill spec -g -a codex -y`
Cursor: `npx skills add JuliusBrussee/cavekit --skill spec -g -a cursor -y`
Gemini CLI: `npx skills add JuliusBrussee/cavekit --skill spec -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add JuliusBrussee/cavekit`

## 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.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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>`.

The rest: https://github.com/JuliusBrussee/cavekit/blob/HEAD/skills/spec/SKILL.md