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.
A spec-mutation skill that is the sole writer of a project's SPEC.md file at the repository root. It centralizes all changes to the spec so that other workflow verbs (grill, research, review, deepen) produce material while this skill is the only thing that actually writes it into the correct section. Sections follow a fixed, owned layout: goal (§G), constraints (§C), interfaces (§I), research rows (§R), invariants (§V), tasks (§T), and bugs (§B). All writes use the "caveman" encoding and pipe-table shape defined in FORMAT.md, which is read before any mutation.
Use it when starting a new spec from an idea, distilling a spec from an existing codebase, amending a named section, or recording a bug via backprop. It dispatches on repository state and the invocation arguments: absent SPEC.md with an idea triggers NEW; absent SPEC.md with `from-code` triggers DISTILL; an existing SPEC.md with arguments starting `bug:` triggers BACKPROP; arguments starting `amend` trigger AMEND; and an existing SPEC.md with no arguments prompts the user to choose a mode. Common phrasings include "write the spec for...", "new spec", "bug: ...", "amend §V.3", and "distill spec from code".
Each mode has a defined procedure. NEW extracts a one-line goal, lists constraints and external surfaces, proposes numbered invariants, and breaks the goal into ordered §T tasks. DISTILL walks the repo to infer sections from README, stack, public APIs, and tests, flagging uncertain items with `?`. BACKPROP parses the bug, finds the root cause, optionally drafts a new invariant, and always appends a §B row. AMEND edits only the section the user named. Every change is shown as a diff and written only on user approval, numbering stays monotonic, and identifiers, paths, and code are preserved verbatim. It runs on the main thread with no sub-agents, no dashboards, no state files beyond SPEC.md, and never auto-builds afterward.
It is the sole mutator of SPEC.md at the repository root. It does not create dashboards, logs, or any state files beyond SPEC.md itself.
Invoke it with arguments starting `bug:` followed by a description. It finds the root cause, optionally drafts a new invariant, and always appends a §B row dated and linked to the relevant invariant.
Yes. When there is no SPEC.md and `from-code` is in the arguments, the DISTILL mode walks the repo to infer the goal, constraints, interfaces, invariants, and tasks, flagging uncertain items with a `?`.
No. It never silently rewrites sections the user did not name, and it will not rewrite a section that a handoff block did not reference. Section ownership is enforced per FORMAT.md.
No. For every mode it shows a diff and writes only on user approval, and it does not auto-build after writing the spec—the user must invoke build explicitly.
Quick Setup:
.claude/skills/Repository
juliusbrussee/cavekit