Spec
- 2.5k installs
- 1.1k repo stars
- Updated June 18, 2026
- juliusbrussee/cavekit
cavekit spec creates and amends SPEC.md with goals, invariants, tasks, and bug backprop in caveman format.
About
Cavekit spec is the sole mutator of SPEC.md at repo root, creating, amending, distilling, or backpropagating bugs per FORMAT.md caveman encoding rules. Dispatch modes are NEW for ideas without a spec, DISTILL to infer spec from existing code, BACKPROP for bug entries, and AMEND for targeted section edits. NEW extracts goal constraints interfaces invariants tasks and an empty section B header, optionally ingesting grill research review and deepen handoffs into the right sections without rewriting unrelated content. BACKPROP parses bug descriptions, finds root cause, drafts new invariants when they would catch recurrence, appends section B rows, and shows a diff before applying. DISTILL walks the repo to infer sections from README stack public APIs tests and TODOs, flagging uncertain items with question marks. Output preserves identifiers, keeps numbering monotonic, and never auto-builds after writing.
- Sole SPEC.md mutator with NEW, DISTILL, BACKPROP, and AMEND dispatch modes.
- Follows FORMAT.md caveman encoding and pipe-table shapes for tasks and bugs.
- BACKPROP links every bug to a section B row and prefers new invariants.
- Ingests grill, research, review, and deepen handoffs into named sections only.
- Shows diffs and waits for user OK; never silently rewrites unnamed sections.
Spec by the numbers
- 2,479 all-time installs (skills.sh)
- +78 installs in the week ending Aug 4, 2026 (Skillselion tracking)
- Ranked #213 of 3,282 Productivity & Planning skills by installs in the Skillselion catalog
- Security screen: HIGH risk (skills.sh audit)
- Data as of Aug 4, 2026 (Skillselion catalog sync)
spec capabilities & compatibility
- Capabilities
- new spec creation from ideas · distill spec inference from code · backprop bug and invariant capture · targeted amend section editing · handoff ingestion from grill and research skills
- Use cases
- planning · project management · documentation
- Runs
- Runs locally
- Pricing
- Free
What spec says it does
Never silently rewrite sections user did not name.
npx skills add https://github.com/juliusbrussee/cavekit --skill specAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 2.5k |
|---|---|
| repo stars | ★ 1.1k |
| Security audit | 2 / 3 scanners passed |
| Last updated | June 18, 2026 |
| Repository | juliusbrussee/cavekit ↗ |
How do I write or update a spec-driven SPEC.md for this project?
Create, amend, distill, or backprop bugs into SPEC.md as the sole mutator of project specifications in caveman format.
Who is it for?
Starting or maintaining Cavekit spec-driven projects at repo root.
Skip if: Skip for read-only drift checks; use the check skill instead.
When should I use this skill?
User asks to write a spec, amend a section, distill from code, or record bug backprop.
What you get
An updated SPEC.md with section G C I V T B content and monotonic numbering.
- SPEC.md
- Amended §-sections
- Backpropagated bug records
Files
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
citescolumn ! 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.
Related skills
Grill MeHave an agent relentlessly pressure-test their plan or design until every decision branch is resolved and shared understanding is reached.691k196kGrill With DocsPressure-test architecture decisions against their live codebase and living documentation before writing production code.585k196k
Lark CalendarLet their coding agents read, create, and manage events inside Lark (Feishu) Calendar directly from natural language instructions.493kLark ImLet their coding agent send instant notifications, post updates, and receive commands directly inside Lark (Feishu) workspaces.493kLark ContactLet their AI coding agents read and write contacts, send messages, and manage user data inside Lark (Feishu).493kLark AttendanceAutomatically fetch and report daily attendance data from Lark (Feishu) into their own tools or agents.493kHow it compares
Use spec when Cavekit repos need a single agent-readable contract; use general PRD skills when the output is a human product doc rather than machine-consumed SPEC.md.
FAQ
What happens on bug backprop?
Every bug gets a section B row and a new invariant is added when it would prevent recurrence.
Can spec rewrite unrelated sections?
No. Amend and handoff ingestion only touch sections the user or handoff names.
Does spec trigger builds automatically?
No. The user invokes build explicitly after approving the spec.
Is Spec safe to install?
skills.sh reports 2 of 3 security scanners passed. Review the Security Audits panel on this page before installing in production.