spec-first

Spec-first is a working method plus a small command set for people who use AI coding agents on real repositories and want the output to be reviewable rather than merely plausible. It is distributed as a Claude Code plugin, though the underlying files are plain YAML and Markdown committed to your own repo, so the approach is not locked to one agent vendor. The project is MIT licensed and installable from a plugin marketplace.

The flow is deliberately narrow. You describe a feature in your own words; the agent first reads your repository and stored memory so it only asks what those cannot answer. Then create-spec writes the goal, cited facts with file and line references, implementation steps, and done criteria onto a fresh branch in its own worktree — with no code written yet.

Review is the part that carries the weight. A script verifies that every cited file and line actually exists, then a separate agent with no chat history critiques the spec against the codebase, and its corrections are applied before building begins. apply-spec then works through the steps, and deliver-spec routes the result through your checks to produce a verified pull request. Several features can run side by side in separate worktrees.

It suits developers already using agentic coding on nontrivial changes — multi-file features, refactors, anything where a wrong assumption is expensive — and teams that want a paper trail for AI-assisted work. It is less useful for one-line fixes or exploratory proto