MCPInstall

spec

by juliusbrusseeCode Quality & Workflow

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.

Installs
2.7K
Last 24h
—
Trending rank
—
Security
Not audited

Install

Works with every agent the skills CLI supports.

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

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads spec automatically when relevant.

  3. 03

    Review the result

    The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

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.

FAQ

What does the spec skill do?

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.

How do I install spec?

Run npx skills add https://github.com/juliusbrussee/cavekit --skill spec in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/spec/ (personal) or .claude/skills/spec/ (project).

Which AI agents can use spec?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is spec safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains spec?

It is published by juliusbrussee in juliusbrussee/cavekit. It has 2,699 recorded installs.

More from juliusbrussee/cavekit

View all →

caveman

juliusbrussee/cavekit

Caveman encoding for SPEC.md and spec-adjacent writes. Loaded by /spec, /build, /check. Cuts tokens 75% vs prose while staying precise. Triggers on any write to SPEC.md or when user says "caveman", "compress this", "be brief".

Code Quality & Workflow2.8K installs

build

juliusbrussee/cavekit

Plan-then-execute implementation against SPEC.md. Native single-thread loop, no sub-agents. On test or build failure, auto-invokes the backprop skill before retrying — a failed verification always considers whether a new §V invariant would prevent recurrence. Triggers when the user asks to build, implement, execute the spec, or tackle a specific §T task (build §T.3, build --next, implement next task, run the build). Expects SPEC.md to exist; if not, defers to the spec skill.

Code Quality & Workflow2.7K installs

check

juliusbrussee/cavekit

Read-only drift detector. Diffs SPEC.md against current code and reports violations grouped by severity. Writes nothing — suggests remedies via the spec or build skills but never invokes them. Triggers when the user asks to check drift, audit the spec, verify invariants, or ask whether code still matches the spec. Phrasings: "check drift", "audit the spec", "does the code still match §V", "check invariants", "spec vs code".

Code Quality & Workflow2.7K installs

backprop

juliusbrussee/cavekit

Bug → spec protocol. When a bug is found or a test fails, trace the cause, decide whether a new §V invariant would catch recurrence, append to §B. This is the one non-obvious thing SDD does that plan-then-execute doesn't. Triggers on test failure, bug report, post-mortem, or explicit user ask.

Code Quality & Workflow2.6K installs

grill

juliusbrussee/cavekit

Calibrated interrogation of a fuzzy idea before it becomes a spec. Asks one question at a time, recommends an answer, and lands each answer in §G (goal) or §C (constraints) — unknowns parked as ? items, never guessed. The cheapest place to kill a bad idea is before §T exists. Triggers when the user has a vague idea, says "grill me", "stress-test this", "challenge my plan", "interview me before I spec", or invokes /ck:grill. Defers the actual write to the spec skill.

Code Quality & Workflow797 installs

review

juliusbrussee/cavekit

Adversarial senior review of the spec before any code is written. Constructs a skeptical reviewer whose authority comes from the codebase, §R research, and live best-practice — then tries to REFUTE the spec, not rubber-stamp it. Every finding cites evidence (file:line or source); unverifiable ones are flagged. Survivors harden §V; the run ends in an explicit go / no-go gate. Triggers before building anything high-blast-radius, when the user says "review the spec", "red-team this", "is this plan sound", "senior review", or invokes /ck:review.

Code Quality & Workflow791 installs

Popular code quality & workflow skills

View category →

grill-me

mattpocock/skills

A relentless interview to sharpen a plan or design.

Code Quality & Workflow1.4M installs

improve-codebase-architecture

mattpocock/skills

Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.

Code Quality & Workflow1.2M installs

handoff

mattpocock/skills

Compact the current conversation into a handoff document for another agent to pick up.

Code Quality & Workflow1.1M installs

domain-modeling

mattpocock/skills

Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.

Code Quality & Workflow890.6K installs

codebase-design

mattpocock/skills

Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.

Code Quality & Workflow863.8K installs

diagnosing-bugs

mattpocock/skills

Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.

Code Quality & Workflow848.4K installs