Specification First Agentic Development

Your coding agent writes the code. This makes it write down why, too.

Install · Use it · Why · How it works · Agent Smith · FAQ · Website

Contents

What it is

spec-first is a way of working with AI coding agents, and a Claude Code plugin that runs it. Before the agent writes any code, it writes a spec: what to build, which code it rests on, and when it's done. A second agent that never saw your conversation checks that spec against your code. Then the agent builds it on a branch of its own, and the commit only lands when your build and tests pass. Every choice it makes along the way goes into plain files in your repository.

Install

In Claude Code:

Or from a local clone:

Then run /spec-first:bootstrap-project in your repository. It reads your code and writes the setup from what it finds: the stack, the rules, and the commands that build and test it. It does not invent conventions.

Codex, Cursor, Copilot or another agent: see Without Claude Code. The method works there too.

Use it

That's the whole loop. A bigger change becomes a series of specs that /spec-first:deliver-series takes to one pull request.

Why

An agent that writes code all day causes three problems:

- It forgets. Each session starts cold. What was built yesterday, and why, is gone.
- It drifts. Without written constraints, each session makes its own architectural calls, and they don't agree with each other.
- Nobody kept the reason. The diff shows what changed. Why path A beat path B was said once, in a chat window that no longer exists.

Spec-first fixes all three by making the record part of the work. The agent reads it before it starts and adds to it before it commits.

What changes when agents work from specs

How it works

The review: checked before anyone builds it

A REFUSE costs you one…