How does the review step work?

First a script verifies that every file and line the spec cites actually exists. Then a new agent with no conversation history reads the code as it is and attacks the spec, returning BUILD, BUILD WITH CUTS, or REFUSE, with every finding naming a file and a line. Cuts are applied before anything is built.

Can multiple specs run at the same time?

Yes. Each spec gets its own branch and worktree, and ids are minted from the clock offline so parallel agents never collide. /spec-first:deliver-series builds groups of specs that share no files simultaneously and opens one pull request for the series.

What happens if tests fail?

The commit gate runs every verify stage declared in the project's contexts. The first red stage blocks the commit and its output goes back to the agent; only all-green commits land. Every gate run is recorded in a log ledger.

What files does the workflow keep in my repo?

specs/ (every spec from planned to done), decisions/ (what each spec chose, over what, and why), memory/ (constraints you told the agent once), and context.yaml (current state so work resumes after a restart).

spec-first — Spec-first agentic development for AI coding agents

Spec-first agentic development is an open source, specification-driven workflow for AI coding agents. Instead of ad-hoc "vibe coding," you describe a feature in your own words and the tool guides it through four skills: writing a reviewed spec (with goal, facts cited to file and line, steps, and done criteria), attacking that spec against the code with a fresh-context reviewer, building it on its own branch and git worktree, and delivering it through a commit gate as a pull request. Specs, decisions, and memory live as plain YAML and Markdown in your repo, and multiple specs can run in parallel.

Key Features

Four-command workflow

/create-spec writes goal, facts with file/line evidence, steps and done criteria on a fresh branch in its own worktree (no code yet); /review-spec verifies every cited file and line and has a fresh agent with no chat history attack the spec (verdict: BUILD, BUILD WITH CUTS, or REFUSE); /apply-spec b

Commit gate

A commit that names its spec id triggers every verify stage the project's contexts declare (e.g. build, tests). All green means it commits; the first red stage blocks it and its output goes back to the agent. Gated commands include -F <file>, -C and --amend --no-edit, and every gate run is logged to

Parallel spec series

/spec-first:deliver-series reviews a series of specs, builds groups that share no files simultaneously in separate worktrees, verifies the merged tree, and opens one pull request for the whole series.

Decision logging

While building, the agent logs each non-obvious choice in decisions/{id}.yaml with what it chose, what it chose over, and why — the project's reasoning lives next to the code instead of in a separate wiki.

Project memory and resumability

memory/ stores constraints you told the agent once; /spec-first:bootstrap-project writes contexts (stack, rules, verify checks) from your code; state lives in context.yaml, so restarting the machine or agent picks up where work stopped.

Multi-agent support

In Claude Code it installs as a plugin (via plugin marketplace) that does the bookkeeping and runs the gate. Other agents (Codex, Cursor, Copilot and others) follow the same files through AGENTS.md, with a git hook running the same gate. Spec ids are minted from the clock offline, so parallel agents

How It Works

Describe

You describe the app or feature in your own words. Before asking anything, the agent reads your memory files and the repository, so it only asks what neither can answer.

Write the spec

/create-spec produces a YAML spec (goal, facts with file and line citations, steps, done criteria) on a fresh branch in its own worktree — no code yet.

Review

A script checks that every cited file and line exists; then a fresh agent with no chat history attacks the spec against the code and its cuts are applied before anything is built. A REFUSE costs one spec rather than a whole branch.

Build and deliver

/apply-spec works through the steps, writes the tests the spec names, and logs decisions. /deliver-spec runs the commit gate (build and tests must pass), pushes the branch, and opens the pull request with the spec inside.

Pros & Cons

Pros

MIT licensed and open source, with plain YAML and Markdown files stored in your own repo (no proprietary format)
Specs are verified before any code is written: evidence is script-checked and a fresh-context reviewer can cut or refuse a bad spec early
Strong isolation and parallelism: one branch and worktree per spec, offline clock-based ids, parallel group builds for series
Commit gate blocks any spec commit that doesn't pass declared verify stages, with a ledger log
Decision and memory files capture reasoning and operator preferences as a side effect of building

Who It's For

Best for

Developers and teams using AI coding agents (Claude Code, Codex, Cursor, Copilot) who want structure and verification instead of unstructure
Projects that want every agent-driven change to arrive as a reviewed spec plus a gated, tested pull request
Teams running multiple agent tasks in parallel who need collision-free branching and worktrees
Maintainers who value an automatic record of architectural decisions alongside the code

Not ideal for

Developers who don't use AI coding agents at all
Quick one-off edits where writing and reviewing a spec is disproportionate overhead

Use Cases

Turning a spoken feature description into a reviewed, verified pull request via AI coding agents

Running multiple independent features in parallel, one branch and worktree per spec

Breaking a large change into a series of specs with dependency-aware parallel builds and a single pull request

Keeping project reasoning on record automatically (what each spec chose, over what, and why)

Resuming long agent runs after a machine or agent restart via context.yaml

FAQ

What is spec-first.dev?

It's an open source (MIT) specification-driven development workflow for AI coding agents: you describe a feature, and four commands write a reviewed spec, check it against your code, build it in its own worktree, and deliver it through a commit gate as a pull request.

Which AI agents does it work with?

It is a Claude Code plugin natively. Codex, Cursor, Copilot and other agents follow the same files through AGENTS.md, with a git hook running the same commit gate.

How do I install it?

In Claude Code, add the plugin marketplace with /plugin marketplace add holgerleichsenring/specification-first-agentic-development and then install the spec-first plugin. For other agents, the workflow runs through AGENTS.md files plus a git hook for the gate.

Is it free / open source?

spec-first