Agent Smith Plugin Introduces Spec-First Parallel Development Workflow

What changes when agents work from specs

This is how Agent Smith is built every day, across more than a thousand specs.

Verified

A fresh reviewer checks the spec against the code before the build. A gate runs your checks before the commit.

Parallel

One branch and worktree per spec. Ids come from the clock, so two agents never take the same one.

Uninterrupted

A reviewed spec has already answered the open questions, so the agent builds to its done criteria instead of coming back to ask.

Structured

One spec, one branch, one commit. A pull request carries one spec or a whole series, and every change has the same shape.

Resumable

State lives in context.yaml. Restart the machine or the agent and the work picks up where it stopped.

Explained, as a side effect

Each choice is logged with what it beat and why, so the reasoning stays next to the code.

*§*2

A whole series, side by side

Cut a bigger change into a series of specs. /spec-first:deliver-series reviews all of them, builds the groups that share no file at the same time, verifies the merged tree and opens one pull request.

deliver-series 2026-10-27-8a3f5 specs · 3 groupsbuilding SpecGroupreviewbuildgatemerge atickets-provider-contractrequires nothing1 btickets-github-providerrequires a1 ctickets-jira-providerrequires a1 dsettings-provider-pagerequires nothing2 eci-restore-cacherequires nothing3

3 worktrees building in parallel · every spec commit through the gate

PR #42

An example run of /spec-first:deliver-series. Specs that share no file are built at the same time; specs that depend on each other share a group.

*§*3

One spec, from idea to pull request

Four skills take a piece of work 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

Goal, steps, facts with file and line, what done means. No code yet.

specs/planned/{id}.yaml

review-spec

Every citation resolved, then a reviewer who never saw the chat attacks it.

BUILD · CUTS · REFUSE

apply-spec

Contracts, code, wiring, tests, following the project's own rules.

decisions/{id}.yaml

deliver-spec

One commit through the gate, pushed, pull request opened.

feat: … ({id}) The recordgrows with every spec, read before every step specs/

Every spec, from planned to done, with its facts and done criteria.

decisions/

What each spec chose, what it chose over, and why.

memory/

What you told the agent once, so you don't say it twice.

/spec-first:bootstrap-project writes the contexts once from your code: stack, rules and the checks a commit must pass. After that, each spec adds one line of state.

*§*4

A spec is reviewed before anyone builds it

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

Spec2026-10-27-8a3f Applies toserver Branchspec/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 todayProgram.cs:40-58 Config already carries a tracker sectionAppConfig.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 · BUILDfresh reviewer · 27 OCT review-spec · 2026-10-27-8a3f2 cuts ✓ src/Host/Program.cs resolves ✓ src/Config/AppConfig.cs resolves evidence resolves: 1 spec BUILD WITH CUTSthe spec holds once two steps change CUT 1

Step 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.

Every citation is checked

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

The reviewer starts fresh

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

One verdict, with cuts named

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

*§*5

The reasoning comes along for free

Nobody has to write documentation afterwards. While it builds, the agent logs each choice that wasn't obvious: what it chose, what it chose over, and why. One file per spec, next to the code.

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 to keep alive

cat decisions/*.yaml is the project's reasoning, spec by spec, in the same history as the code it explains.

Memory for what git can't tell

How the operator wants things done, a constraint outside the repo, a pointer elsewhere. One fact per file, one line in an index.

Back in thirty seconds

Restart the machine, restart the agent, open context.yaml. It knows what is done, what is active and what comes next.

*§*6

Nothing lands past a red stage

The plugin's commit gate runs every verify stage your contexts declare when a commit names its spec. All green, it commits. The first red stage blocks it, and its output goes back to the agent.

the commit

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

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

verify: stages *✓*builddotnet build *✓*testsdotnet test *✕*webcd web && npm test PASSED

Committed

every stage green

BLOCKED

Not committed

the first red stage stops it, and its output goes back to the agent

spec-first-gate.log · one line per spec commit 2026-10-27T09:14 blocked 2026-10-27-8a3f /work/repo a1b2c3d web 2026-10-27T09:31 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.

Built this way

Agent Smith

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

Agent Smith runs the loop for you → **1,300+**specs done **1,190+**decision files: chose, over, why **650+**specs through the gate Counted in the Agent Smith repository, October 2026. *§*7

Install

In Claude Code the plugin does the bookkeeping and runs the gate. Other agents follow the same files through AGENTS.md, and a git hook runs the same gate.

/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.

Let your agent set it up

Paste this into Codex, Cursor, Copilot or any agent that can read and write your repository.

Set up specification-first agentic development in this repository,
following the templates 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.

AGENTS.md carries the method

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

The gate as a git hook

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 your 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.

*§*8

Questions about spec-first agentic development

Specification-driven agentic development, in short answers.

What is spec-first agentic development?

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 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.

*§*9

Where it comes from

[Essay

The Why Never Gets Written Down

codingsoul.org · April 2026](https://codingsoul.org/2026/04/11/the-why-never-gets-written-down/) [Essay

Next Level Vibe Coding

codingsoul.org · April 2026](https://codingsoul.org/2026/04/21/next-level-vibe-coding/)

作者发帖说明（HN）：

Implemented agent smith since start 2026 with over 1000 specifications which lead to about 500k lines of code. The procedure with that spec-first works well. How do you do it?