Spec-Loop — a contract-first, self-fixing build loop for Claude Code

/spec is a Claude Code skill that turns "build me X" into a disciplined loop:

interview → write a contract → build → INDEPENDENT adversarial audit → fix → re-audit → verify → gated ship

Its whole edge over a normal "spec → build → self-review" loop is one thing: the review is independent and adversarial, not self-review. A build's own review shares the builder's blind spots and says "ship, zero findings." A separate context told to break it finds the real bugs. The spec you write is the contract that adversary checks the build against — so it's written to be attacked, not admired.

• Phase 0 — Interview to clarity. One question at a time until there's a definition of done someone else could check without asking you anything.
• Phase 1 — Write the contract to specs/<name>.md: NEEDS (testable, no hedging), constraints, milestones, the Win, the catastrophic failure, guardrails, and the adversary's attack surface. Nothing gets built until you approve it.
• Phase 2 — The self-fixing loop. Build to the contract, then spawn a fresh-context agent whose only job is to break it against the attack surface. Fix survivors, re-audit if the fix was structural, verify the Win for real, and ship only behind the guardrails with your explicit go.

The easy way — let Claude Code do it:

Send Claude Code this repo's URL and say:

Install the skill from https://github.com/devonbweaver/Spec-Loop — put SKILL.md at ~/.claude/skills/spec/SKILL.md.

By hand:

mkdir -p ~/.claude/skills/spec
curl -fsSL https://raw.githubusercontent.com/devonbweaver/Spec-Loop/main/SKILL.md \
  -o ~/.claude/skills/spec/SKILL.md

Or clone and copy:

git clone https://github.com/devonbweaver/Spec-Loop.git
mkdir -p ~/.claude/skills/spec && cp Spec-Loop/SKILL.md ~/.claude/skills/spec/SKILL.md

A skill is just a markdown file in a folder — once SKILL.md is at ~/.claude/skills/spec/, Claude Code discovers it automatically. (Drop it in a project's .claude/skills/spec/ instead to scope it to one repo.)

/spec <feature-name>

…or just describe a build and ask Claude to "spec it out first." It runs the interview, writes the contract, gets your approval, then drives the build-audit-fix-verify-ship loop.

Customize it: open SKILL.md and edit the "Your project conventions" section to fold in your own reflexes (commit/attribution rules, how migrations apply, flag-gating defaults, where you log shipped work). Those get folded into the guardrails automatically.

See specs/password-reset.md — a complete example of what /spec produces at the end of Phase 1, before a line of code is written. It shows the whole shape: testable NEEDS with no hedging, the catastrophic failure named first, always-on guardrails, and the adversary's attack surface — the checklist the independent audit runs against so the review has teeth. That last section is the point of the whole loop.

MIT — see LICENSE. Use it, fork it, adapt it.