spec — spec mutator

spec

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.

juliusbrussee/cavekit·2.7Kinstalls1.1Kstars

SKILL.md

Full skill instructions

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:

No SPEC.md at repo root AND args describe idea → NEW
No SPEC.md AND from-code in args → DISTILL
SPEC.md exists AND args start bug: → BACKPROP
SPEC.md exists AND args start amend → AMEND
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:

Extract goal (1 line, caveman). → §G.
List constraints user stated or implied. → §C.
List external surfaces user named. → §I.
§R only if research ran — else omit the section (right-size).
Propose initial invariants. → §V (numbered V1…).
Break goal into ordered tasks. → §T pipe table, all status ., ids T1…
§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:

Parse bug description.
Find root cause (read relevant code).
Decide: would a new invariant catch recurrence? If yes → draft V<next>.
Append §B row: B<next>|<date>|<cause>|V<N>.
Append new invariant to §V.
If fix also changes behavior → add/update §T rows.
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.

Install skill

Copy and run in your terminal

npx -y skills add https://github.com/juliusbrussee/cavekit --skill spec

View on GitHub

spec

caveman
Ultra-compressed communication mode cutting token usage ~75% while preserving technical accuracy.
559K installs
caveman-commit
Terse, conventional commit messages that prioritize reasoning over description.
392.8K installs
caveman-review
Ultra-compressed code review comments: location, problem, fix on one line each.
388.8K installs
caveman-compress
Compress natural language memory files into caveman-speak to reduce input tokens.
387.7K installs

More skills from juliusbrussee

juliusbrussee/caveman

caveman-help

Quick-reference card for caveman modes, skills, and commands with one-shot display.

109.9K 379.4K

View

juliusbrussee/caveman

cavecrew

Delegate code tasks to compressed subagents that shrink context by ~60% per delegation.

109.9K 335.7K

View

juliusbrussee/caveman

caveman-stats

Real token usage and estimated savings metrics from your Claude Code session log.

109.9K 334.9K

View

juliusbrussee/caveman

compress

Compress natural language memory files into caveman-speak to reduce input tokens.

109.9K 46.9K

View

juliusbrussee/skills

caveman

Ultra-compressed communication mode. Cuts token usage ~75% by speaking like caveman while keeping full technical accuracy. Supports intensity levels: lite, full (default), ultra, wenyan-lite, wenyan-full, wenyan-ultra. Use when user says "caveman mode", "talk like caveman", "use caveman", "less tokens", "be brief", or invokes /caveman. Also auto-triggers when token efficiency is requested.

160 3.5K

View

juliusbrussee/cavekit

caveman

1.1K 2.8K

View

juliusbrussee/cavekit

build

1.1K 2.7K

View

juliusbrussee/cavekit

check

1.1K 2.7K

View

juliusbrussee/cavekit

backprop

1.1K 2.6K

View

juliusbrussee/skills

grill-me

Calibrated grilling session for stress-testing a plan, design, idea, or decision. First assesses the user's topic knowledge, confidence, and desired pressure level, then asks one question at a time with recommended answers. Use when user says "grill me", "stress-test this", "challenge my plan", "interview me", or wants a plan probed without being overwhelmed.

160 2.6K

View

juliusbrussee/skills

junior-to-senior

Adversarial senior-engineer review for agent-generated plans, designs, and architectures. Treats the current output as junior work, constructs a senior reviewer whose domain expertise comes from live codebase research plus web research of current best practices, diagnoses altitude failures (too vague or too granular), then rewrites the plan into a scoped, state-of-the-art version. Use when the user says "junior to senior", "senior review", "review this like a staff engineer", when a plan feels hand-wavy or lost in details, or before committing to any agent-written plan.

160 2.5K

View

juliusbrussee/skills

interface-kit

Authoritative guide for implementing stunning, accessible, performant UI. Synthesizes design engineering philosophy, accessibility standards, animation principles, spatial design, typography, color systems, and component craft into a single actionable reference. Complements the design-system skill (which covers DESIGN.md spec writing) by covering the HOW of implementation. Trigger phrases: "build UI", "create component", "landing page", "make it look good", "frontend", "design", "polish UI", "implement design", "make it beautiful", "UI implementation", "component styling", "animation", "accessibility"

160 2.1K

View