Spec
Maintain a single repo-root SPEC.md (goal, constraints, invariants, tasks, bugs) before and during agent-driven builds.
Overview
Spec is an agent skill most often used in Validate (also Build, Operate) that creates and amends repo-root SPEC.md as the sole authoritative project spec.
Install
npx skills add https://github.com/juliusbrussee/blueprint --skill specWhat is this skill?
- Sole mutator of repo-root SPEC.md with dispatch modes: NEW, DISTILL, BACKPROP, AMEND
- Structures spec as §G, §C, §I, §V, numbered invariants, §T task pipe table, and §B bug log
- NEW flow extracts goal, constraints, surfaces, invariants, and ordered tasks (T1…)
- DISTILL walks the repo to backfill a spec from production code
- BACKPROP records bugs via bug: args; amend: edits sections like §V.3
- Six spec sections: §G, §C, §I, §V, §T, and §B
- Four dispatch modes: NEW, DISTILL, BACKPROP, AMEND
Adoption & trust: 5 installs on skills.sh; 1k GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your agent has scattered goals, tasks, and bugs across chat with no single structured spec file to drive build and iteration.
Who is it for?
Solo builders running Cavekit/Blueprint-style loops who want one caveman-encoded spec file mutated only through explicit spec commands.
Skip if: Repos that already treat README or ad-hoc docs as the spec without wanting FORMAT.md caveman rules or a dedicated SPEC.md contract.
When should I use this skill?
User asks to write a spec, start a new spec, distill from code, amend sections (§G, §C, §I, §V, §T, §B), or record a bug via backprop.
What do I get? / Deliverables
You get an updated SPEC.md with §G–§B sections ready for review, edits, or invoking build against ordered tasks.
- Updated SPEC.md at repository root
- §T ordered task pipe table with status dots
- §B bug log rows when using backprop
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Canonical shelf is validate/scope because the skill’s entry path is turning an idea or existing code into a committed project spec before heavy implementation. Scope is where goals, constraints, and ordered tasks are frozen into §G–§T so later build modes have a single source of truth.
Where it fits
Turn a one-paragraph product idea into §G goal, §C constraints, and a §T task table before any coding.
Amend §T rows and §V invariants when scope shifts mid-implementation without breaking the single-spec rule.
Backprop a production bug with bug: args into §B while keeping cause/fix traceable for the next agent pass.
Distill spec from an existing codebase so agents inherit accurate §I surfaces and §V invariants.
How it compares
Use instead of freeform planning chat when you need a versioned, section-numbered spec artifact—not a generic note-taking or PRD template skill.
Common Questions / FAQ
Who is spec for?
Indie and solo builders using agent build pipelines who need one enforced SPEC.md at the repo root for goals, tasks, invariants, and bug backprop.
When should I use spec?
In validate/scope when starting “new spec” or “write the spec for…”; in build/pm when amending §T tasks; in operate/iterate when logging “bug:” entries via backprop; anytime you need “distill spec from code” on an existing repo.
Is spec safe to install?
It is designed to rewrite SPEC.md at repo root when invoked—review changes in git diffs and check the Security Audits panel on this Prism page before trusting it in production repos.
SKILL.md
READMESKILL.md - Spec
# 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 ## NEW — idea → spec Input: user idea. Steps: 1. Extract goal (1 line, caveman). → §G. 2. List constraints user stated or implied. → §C. 3. List external surfaces user named. → §I. 4. Propose initial invariants. → §V (numbered V1…). 5. Break goal into ordered tasks. → §T pipe table, all status `.`, ids T1… 6. §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: 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.