A SoftwareDevelopment Field Guide to spec-first Agent Workflows: Review Gates, Parallel Worktrees, Decision Logs

Most teams do not lose time because an agent writes too little code. They lose time because nobody can prove the code is right, because branches tangle into each other, and because the reasoning vanished with the chat window. The spec-first answer to those three problems is procedural: the written spec is reviewed before any build begins, each spec is isolated on its own branch and worktree, and a commit is only allowed when your own checks pass. Agent Smith is built daily across more than a thousand specs, and the difference shows up in verification, isolation, continuity, and record rather than in raw typing speed.

What the pipeline gains when the spec leads

Verification moves ahead of the keyboard

Nobody who worked on a spec reviews it. A reviewer with no prior involvement compares the written spec with the code, and before the commit, a gate performs your checks.

Isolation by default

Each spec receives its own branch and worktree, so concurrent work never shares a directory. Ids drawn from the clock keep two agents from taking the same one.

Fewer interruptions mid-build

Because open questions are settled during review, the agent can continue to its done criteria rather than coming back with more questions.

A pull request that always has the same shape

The one spec, one branch, one commit pattern gives pull requests a consistent shape, whether they carry a single change or a whole series.

State you can resume

The project state lives in context.yaml; after a restart of the machine or agent, the work resumes at its stopping point.

Explanation produced while you work

Each choice is recorded beside the code, noting what it beat and why, instead of being reconstructed weeks later.

Parallel delivery: turning a spec series into one pull request

A bigger change can be broken into multiple specs. /spec-first:deliver-series reviews the set, builds groups that share no file at the same time, verifies the merged tree, and opens one pull request.

The run labelled 2026-10-27-8a3f is representative: while building, the queue reports 5 specs and 3 groups; the run uses 3 worktrees in parallel and lands as PR #42.

Spec	Group	Dependency	Build group
a	tickets-provider-contract	requires nothing	1
b	tickets-github-provider	requires a	1
c	tickets-jira-provider	requires a	1
d	settings-provider-page	requires nothing	2
e	ci-restore-cache	requires nothing	3

Specs that share no file are built together, while specs that depend on one another share a group. Every spec commit still passes through the gate.

Four skills carry a piece of work to a gated commit

Four skills move one spec through its own branch and worktree. Each one leaves a file behind for the next step and for whoever reads the history later.

• create-spec records the goal, steps, facts with file and line, and what done means, before code exists.

  specs/planned/{id}.yaml

• review-spec resolves every citation, then asks a fresh reviewer who never saw the chat to challenge it.

  BUILD · CUTS · REFUSE

• apply-spec builds contracts, code, wiring, and tests according to the project's own rules.

  decisions/{id}.yaml

• deliver-spec makes one commit through the gate, pushes it, and opens the pull request.

  feat: … ({id})

The record grows with each spec

The record is written once and read before every later step.

• specs/ stores every spec, from planned to done, with facts and done criteria.

• decisions/ stores what each spec chose, what it chose over, and why.

• memory/ stores what you told the agent once, so you do not have to say it twice.

/spec-first:bootstrap-project writes stack, rules, and required checks once from your code. After that, each spec adds one line of state.

Reading a spec under review

A REFUSE costs one spec. Without review, the same mistake would cost the branch.

Spec under review

Spec	2026-10-27-8a3f
Applies to	server
Branch	spec/8a3f
Goal	Ticket providers so pipelines can pull work from GitHub and Jira.
Facts, read in the code	Pipelines take work only from the CLI today Program.cs:40-58 Config already carries a tracker section AppConfig.cs:12-19
Decision	Adapter over repository: read-mostly data, no unit of work needed.
Done when	GitHub provider returns tickets end to end Jira provider behind the same interface verify: stages green

REVIEWED · BUILD fresh reviewer · 27 OCT. The review is dated 2026-10-27.

Verdict from review-spec on 2026-10-27-8a3f: 2 cuts

evidence resolves: 1 spec

BUILD WITH CUTS: the spec holds once two steps change.

• CUT 1: jira needs a second auth mode the config can't hold yet. AppConfig.cs:15 Move it to its own spec.

• CUT 2: Paging is missing: GitHub returns 30 issues per page. GitHubClient.cs:88 Add a done criterion.

Two checks stand behind the verdict

A script opens each file and line the spec cites, and a claim nobody checked in the code must be listed as an assumption.

A new agent with no conversation history then reads the code as it is, not as the spec says it is.

The verdict is BUILD, BUILD WITH CUTS, or REFUSE, and every finding names a file and a line.

The reasoning arrives as a build artifact

Documentation is not postponed. While the agent builds, it logs each choice that was not obvious: what it chose, what it chose over, and why. One file per spec sits next to the code.

Example decision file

decisions/2026-10-27-8a3f.yaml

spec: 2026-10-27-8a3f

decisions:

• category: TradeOff
  chose: "Raw HttpClient for the GitHub API"
  over: "Octokit"
  reason: "Three megabytes of dependencies for four calls."

• category: Architecture
  chose: "One ITicketProvider per tracker"
  over: "A generic REST mapper"
  reason: "Each tracker pages and authenticates differently; the mapper would leak it."

No wiki, plus memory and a fast restart

No wiki has to be kept alive. cat decisions/*.yaml is the project's reasoning, spec by spec, in the same history as the code it explains.

Memory stores what git can't tell: how the operator wants things done, a constraint outside the repo, or a pointer elsewhere. One fact per file, one line in an index.

Back in thirty seconds: restart the machine, restart the agent, and open context.yaml. It knows what is done, what is active, and what comes next.

Nothing lands past a red stage

The plugin's commit gate runs every verify stage declared in contexts when a commit names its spec. If all stages are green, it commits. The first red stage blocks the commit and sends its output back to the agent.

The commit that triggers the gate

git commit -m "feat: ticket providers (2026-10-27-8a3f)"

The id in parentheses triggers the gate. -F <file>, -C, and --amend --no-edit are gated too.

verify stages

• ✓ build dotnet build

• ✓ tests dotnet test

• ✕ web cd web && npm test

PASSED means every stage is green and the commit is allowed. BLOCKED means the first red stage stops it, and its output goes back to the agent.

Gate ledger

# spec-first-gate.log · one line per spec commit

2026-10-27T09:14:02Z blocked 2026-10-27-8a3f /work/repo a1b2c3d web

2026-10-27T09:31:47Z passed 2026-10-27-8a3f /work/repo a1b2c3d build,tests,web

A spec commit with no line in the ledger never met the gate. A project with its own gate says gate: project, and the plugin steps aside.

Evidence from a repository built this way

Agent Smith is the open source agentic software factory: a ticket goes in, a verified pull request comes out. It was built entirely with this method, and the method grew from building it. Everything in the plugin ran there first.

• 1,300+ specs done

• 1,190+ decision files: chose, over, why

• 650+ specs through the gate

Counted in the Agent Smith repository, October 2026.

Installation: getting the gate running

In Claude Code, the plugin handles bookkeeping and runs the gate. Codex, Cursor, Copilot, and other agents follow the same files through AGENTS.md, while a git hook can run the same gate.

Claude Code

/plugin marketplace add holgerleichsenring/specification-first-agentic-development

/plugin install spec-first@specification-first-agentic-development

Then run /spec-first:bootstrap-project. It reads your code and writes the contexts and rules from what it finds.

Skills you will call

• create-spec writes the spec on its own branch and worktree.

• review-spec performs the evidence check and the fresh reviewer's verdict.

• apply-spec builds the spec up to its done criteria.

• deliver-spec commits through the gate and opens the pull request.

• deliver-series takes a whole series of specs to one pull request.

• log-decision, update-project, and bootstrap-project handle decisions, upgrades, and setup.

Setup for an agent that can read and write the repository

An agent following the method can be asked to create the contexts, specs, decisions, and memory directories, then write AGENTS.md from the templates.

Templates are available at https://github.com/holgerleichsenring/specification-first-agentic-development/tree/main/templates

1. Create .{project}/contexts/default/context.yaml and coding-principles.md. Fill them from the code as it is: stack, architecture, limits, conventions, and the commands that build and test it as verify: stages. Invent nothing.

2. Create .{project}/specs/planned, active and done, .{project}/decisions/, and .{project}/memory/MEMORY.md.

3. Write AGENTS.md from templates/prompt.md, with .{project}/ filled in.

4. Add "gate: git" at the top level of that context.yaml.

Codex, Cursor, and Copilot read AGENTS.md when a session starts. It holds the read order and workflow, and every step says how to do it by hand, including the review brief for a fresh session.

Clone the spec-first repository once, then run python3 <clone>/hooks/install-git-hook.py in each clone of your project. The commit-msg hook runs verify: stages on every commit that names a spec, from any agent or the terminal. git commit --no-verify skips it. The evidence check is skills/review-spec/scripts/check-evidence.py in the same clone and needs PyYAML.

Common misconceptions about spec-first agent workflows

"You have to switch to Claude Code."

No. The plugin runs the steps as commands, but Codex, Cursor, Copilot, or a terminal can follow the same files through AGENTS.md, and a git commit-msg hook runs the same commit gate in every clone where it is installed.

"A saved prompt is already a spec."

The spec names the goal, the facts it rests on with file and line, the steps, and the done criteria, and it is checked against the code before the first line is written. A prompt is none of those things.

"Amending or bypassing the commit dodges the check."

-F <file>, -C, and --amend --no-edit are gated too. git commit --no-verify skips the hook, which is exactly why the ledger exists: a spec commit with no line in it never met the gate.

"Documentation can be written later, in a wiki."

No wiki has to be kept alive. The reasoning is logged beside the code as the build happens, one file per spec, in the same history as the code it explains.

"The agent will come back with questions halfway through the build."

Open questions are settled during review, which is the point of putting the reviewer first: the agent runs to its done criteria instead of stopping to ask.

"This is just vibe coding with extra ceremony."

You still describe the feature in your own words and talk it through. After that, the agent works from a reviewed spec instead of from the last prompt.

FAQ: spec-first agentic development

What is spec-first agentic development?

It is a way of working with AI coding agents in which every change starts as a written spec in your repository. A fresh reviewer checks the spec against your code before anything is built, the agent builds it on its own branch and worktree, and the commit lands only when your checks pass.

What does specification-driven agentic development mean here?

The spec drives the work from start to finish. It names the goal, the facts it rests on with file and line, the steps, and the done criteria, and the agent builds to exactly that. Spec-first agentic development is specification-driven agentic development in which the spec is reviewed against the code before the first line is written.

Do I need Claude Code?

No. The Claude Code plugin runs the steps as commands. Codex, Cursor, Copilot, or a terminal can follow the same files through AGENTS.md, and a git commit-msg hook runs the same commit gate in every clone where it is installed.

How does it differ from vibe coding?

You still describe the feature in your own words and talk it through. After that, the agent works from a reviewed spec instead of from the last prompt, logs each decision with its reason, and a commit lands only when your build and tests pass.

What does a spec contain?

A one-sentence goal, the facts it rests on with file and line, the steps, what an upgrade costs an operator, and the done criteria. The decisions made while building go into a separate YAML file next to it.

What does it cost?

Nothing. The method, the templates, and the Claude Code plugin are MIT licensed.

Action checklist for your next iteration

1. Run /spec-first:bootstrap-project once so stack, rules, and required checks are written from the code as it is. Invent nothing.

2. Give each piece of work its own branch and worktree, with ids drawn from the clock so two agents never take the same one.

3. Have a reviewer with no prior involvement return BUILD, BUILD WITH CUTS, or REFUSE before any build starts.

4. Log each non-obvious choice beside the code: chose, over, why.

5. Name the spec id in the commit message so the gate runs every verify stage declared in contexts.

6. Add "gate: git" at the top level of context.yaml, or "gate: project" if your repository already gates commits and the plugin should step aside.

7. Install the commit-msg hook in each clone, keep context.yaml current with one added line per spec, and let deliver-series merge file-disjoint groups in parallel.

Where the method comes from

• Essay: The Why Never Gets Written Down, codingsoul.org · April 2026

• Essay: Next Level Vibe Coding, codingsoul.org · April 2026

For software teams whose bottleneck is trust rather than throughput, the sequence is worth adopting as written: review one spec before the build, isolate the work in its own branch and worktree, let the gate decide when a commit is allowed, and let the reasoning accumulate next to the code. Start with a single spec you control end to end; by the time the pull request opens, the record is already there for the next agent, or the next engineer, to resume from.