spec
The `spec` skill is designed to be a robust technical specification management tool. It offers multiple modes to interact with specifications: generating new ones from user ideas, distilling them from existing code, or precisely amending current documentation. Crucially, this skill also features a backpropagation mechanism to automatically handle bugs and update affected specifications. By maintaining synchronization between specifications and the codebase, `spec` significantly improves software architecture clarity and overall engineering efficiency.
npx skills add https://github.com/juliusbrussee/cavekit --skill specBefore / After Comparison
1 组Engineers manually analyze code, identify issues, and update technical specifications, which is time-consuming and error-prone, leading to discrepancies between specs and actual code, impacting development efficiency.
Using AI Skill to automatically analyze bug descriptions and code, quickly locate and update relevant sections in SPEC.md, significantly improving specification update efficiency and accuracy.
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.mdat repo root AND args describe idea → NEW - No
SPEC.mdANDfrom-codein args → DISTILL SPEC.mdexists AND args startbug:→ BACKPROPSPEC.mdexists AND args startamend→ AMENDSPEC.mdexists, no args → ask user which mode
NEW — idea → spec
Input: user idea.
Steps:
- Extract goal (1 line, caveman). → §G.
- List constraints user stated or implied. → §C.
- List external surfaces user named. → §I.
- 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? 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:
- 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
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.
User Reviews (0)
Write a Review
No reviews yet
Statistics
User Rating
Rate this Skill