Spec
Create, distill, amend, or backprop Cavekit SPEC.md at repo root as the single authoritative spec mutator before build work.
Overview
Spec is an agent skill most often used in Validate (also Build, Ship) that creates and amends Cavekit SPEC.md as the only authorized spec writer in the repo.
Install
npx skills add https://github.com/juliusbrussee/cavekit --skill specWhat is this skill?
- Dispatch modes: NEW, DISTILL from code, BACKPROP on bug:, AMEND on section edits
- Sole mutator of repo-root SPEC.md per Cavekit FORMAT.md caveman encoding
- NEW flow fills §G goal, §C constraints, §I interfaces, §V invariants, §T task table, empty §B header
- DISTILL walks production code to reverse-engineer a spec when none exists
- Ends NEW with full file review and handoff to invoke build when spec OK
- Five dispatch modes: NEW, DISTILL, BACKPROP, AMEND, and interactive ask
- NEW seeds §T with status-dot rows and ids T1… plus empty §B header row
Adoption & trust: 1.6k installs on skills.sh; 999 GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
You have an idea or a codebase but no single SPEC.md that encodes goals, invariants, and ordered tasks your agent can execute against.
Who is it for?
Cavekit users starting greenfield ideas, brownfield distill jobs, or controlled §V/§T amendments from chat.
Skip if: Projects not using SPEC.md/FORMAT.md, or teams that want free-form PRD docs outside the Cavekit section model.
When should I use this skill?
User asks to write a spec, start new spec, distill from code, amend §G/§C/§I/§V/§T/§B, or record bug via backprop with phrasings like write the spec for… or bug: …
What do I get? / Deliverables
Repo-root SPEC.md is written or updated in FORMAT.md shape, reviewed with the user, and ready for build—or amended/backpropped without duplicate spec editors.
- Created or updated SPEC.md with Cavekit sections
- User confirmation prompt before build handoff on NEW
- Structured §T pipe table and numbered §V invariants
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
New specs from an idea belong on the Validate shelf where scope is nailed before implementation; the skill also serves later amend and bug modes. NEW mode turns a raw idea into §G, §C, §I, §V, and §T tasks—classic scoping and constraint capture before coding.
Where it fits
You describe a product idea and spec emits §G–§T then asks whether to invoke build.
Mid-sprint you amend §T statuses or add tasks without letting the coding agent edit SPEC.md directly.
A bug: message routes through BACKPROP mode to append §B and invariant lines before re-verification.
How it compares
Use as the structured SPEC.md writer—not as a generic brainstorming or ad-hoc implementation plan skill.
Common Questions / FAQ
Who is spec for?
Solo builders adopting Cavekit spec-driven development who need one skill to own all SPEC.md mutations.
When should I use spec?
At Validate when scoping a new idea, at Build when amending §T tasks or §I interfaces, and at Ship when recording bug: backprop rows—plus DISTILL when onboarding an undocumented repo.
Is spec safe to install?
It can rewrite your canonical spec file; check Security Audits on this page and version-control SPEC.md before trusting automated amends.
Workflow Chain
Then invoke: build
SKILL.md
READMESKILL.md - Spec
# 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 ## NEW — idea → spec Input: user idea. Steps: 1. Extract goal (1 line, caveman). → §G. 2. List constraints user stated or implied. → §C. 3. List external surfaces user named. → §I. 4. Propose initial invariants. → §V (numbered V1…). 5. Break goal into ordered tasks. → §T pipe table, all status `.`, ids T1… 6. §B section with header row only (`id|date|cause|fix`). Write to `SPEC.md`. Show user full file. Ask: "spec OK? suggest edits or invoke 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.