From a rough idea to ordered, executable development phases — files a coding agent can build from.

What you get

This is the app's project page, open on Spec4's own repository.

Every file of every round is readable in the app's Artifacts view.

A round leaves this in your project directory, one folder per pass:

.spec4/
└── v1/                        # one directory per planning round
    ├── code_review.json       # CodeScanner — the existing codebase, as facts with sources
    ├── vision.json            # Brainstormer — purpose, audiences, MVP features
    ├── feature_specs.json     # Brainstormer — a behavioral spec per MVP feature
    ├── ai_catalog.json        # Agentifier — its recommendation and your decision, per feature
    ├── ai_features.json       # Agentifier — where AI belongs, at what tier, built how
    ├── design/
    │   ├── mock.html          # Designer — a self-contained mock of the starting screen
    │   └── manifest.json      # Designer — the design decisions the mock embodies
    ├── stack.json             # StackAdvisor — the technology stack, with canonical doc links
    ├── phases/                # Phaser — ordered phase files, one per implementation step
    │   ├── phase1.md
    │   ├── phase2.md
    │   └── ...
    ├── deployment-plan.md     # Deployer — infrastructure, CI/CD, config files, Terraform
    ├── usage.json             # what each agent cost this round, per call
    └── IMPLEMENTED            # the coding agent's marker that the round is built

Three kinds of file. The phase files are prompts for the coding agent. The JSON and the mock are reference for the agent: the decisions it grounds against. deployment-plan.md and usage.json are a record for you. Artifacts

The phase files are the point. Each one is written for a coding agent, not for you. This is from Spec4's own repository — .spec4/v0/phases/phase1.md, the first phase of the round that reworked this app's UI, and the thing a coding agent is handed:

# Phase 1 of 7: Integration Thread — Baseline Validation of the Existing Spec4 App

Prove the existing Dash application builds, serves at localhost:8050, and passes
its full quality gate (pytest, ruff, mypy) unchanged, and read the existing
callback co-presence contract so the coming shell rework is done against a
known-green baseline rather than a guessed one. No feature work, no layout
changes, no new files.

## Tech Stack

**Dependencies:** uv, dash, dash-mantine-components, pytest, pytest-cov, ruff, mypy, …

**Configurations:** No required env vars. Optional: DASH_DEBUG (enables Dash
hot-reload), LITELLM_LOG (must be set before litellm is first imported). App
serves HTTP on localhost:8050 only.

## Instructions

1. Run `uv build` and confirm it completes without error using the existing
   uv_build backend and pyproject.toml; do not modify pyproject.toml in this phase.
2. Run `uv run pytest` and record the exact number of passing tests and any
   pre-existing failures. This count is the baseline every later phase must meet
   or exceed.
…
7. Open src/spec4/app.py and confirm the litellm setup ordering is intact …
   Write a one-line D-XX comment above that block noting the ordering must not
   be changed by this round's work.
8. Read tests/test_callback_co_presence.py in full … This file is the existing
   component-id contract; do NOT create a parallel inventory, a new id-manifest
   file, or a duplicate test module.

## Risk Assessment
## Verification
## References

Every phase carries a JSON frontmatter with the same content as structured data, a risk assessment naming where a coding agent is likely to go wrong and what to do about it, and a Verification section with the exact command or observable that proves the phase is done. Phase 1 is always a steel thread — the thinnest live end-to-end path — before any feature work.

The pipeline

Seven agents, in order. Each reads what the ones before it wrote.

They are conversational — all but CodeScanner, which reports facts about the code rather than forming an opinion. Each is a specialist in its stage, working a fixed agenda with you one topic at a time and writing down what you decide. Nothing advances without your confirmation. It runs like a project team meeting: the specialists give their input, and the project owner makes the final call.

Run the agents a round needs. Spec4's own rounds ran five of the seven.

CodeScanner reads an existing directory and records its architecture, stack, commands, entry points, and conventions as facts with sources, so the later agents plan against what's there rather than what they'd guess.

Brainstormer develops the vision through focused questions — purpose, audiences, MVP features — and, on completion, derives a technology-agnostic behavioral spec for every MVP feature: inputs, outputs, success criteria, failure modes. It searches the web for the standards it names and embeds canonical documentation links.

Agentifier looks for places in the vision where an AI feature would serve it, recommends how much AI each one needs, and drafts a spec for each feature you keep. The next section shows what it records.

Designer generates a self-contained HTML mock of the application's starting screen from the vision and AI features — or from screenshots of what you already have. Approve it, refine it with a description of changes, or start over. Phaser directs the coding agent to build to it. Example mock.

StackAdvisor recommends a technology stack that serves the features and the AI tiers, with canonical documentation links for every library it names.

Phaser turns all of it into ordered implementation phases, one file each, written for a coding agent. It treats the stack as the approved component list: a phase that needs something not in it has to ask you first, so a dependency never appears in a plan without your having said yes to it.

Deployer asks which coding agent you're using, produces a deployment plan — service, containerization, CI/CD, environment, monitoring, exact commands and complete config files, Terraform if you want it — and can author the project README, updating an existing one in place. Example plan.

At every step after Brainstormer, Spec4 shows the options and the tradeoffs; you decide. The spec isn't something the AI wrote for you. It's your decisions, captured in a form an agent can execute.

Which features get AI, and how much

Agentifier looks for places in the vision where an AI feature would serve it and recommends how much AI each one needs: a complexity tier from a nine-tier ladder (deterministic code → embeddings → single call → RAG → tool use → … → multi-agent collaboration) and the mechanisms to build it with. You choose the candidates and decide each tier; it records both and drafts a full spec for each feature you keep. The tiers are the same ones the Built With Spec4 gallery demonstrates as working apps.

The ladder starts at deterministic code: the cheapest tier that does the job, and sometimes that is no model at all. Agentifier

Agentifier writes its recommendation and the developer's decision to the same file, side by side. This record is from .spec4/v0/ai_catalog.json in the Built With Spec4 repository:

{
  "name": "rag_example_app",
  "tier_recommendation": "single_call",
  "tier_decision": "rag",
  "tier_decision_rationale": "The whole point of this example is to illustrate the use of RAG, so the retrieval pipeline is intentional despite the small dataset size."
}

The tool argued against the agent; the developer decided; the file records both.

Rounds: why this isn't waterfall

The standard objection to spec-driven development is that it turns into waterfall: the spec is written once, the code drifts from it, and after a month the plan describes a program that doesn't exist.

Spec4 is built around the round instead of the spec. A round is one pass over the project — .spec4/v1/, v2/, v3/ — and every round after the first starts from the code, not from the previous plan:

• CodeScanner reads what was actually built — by anyone. The code review for round N is of the code as it stands, including what the coding agent did that the plan didn't say and whatever you changed yourself in between. Spec4 doesn't assume it's the only thing editing the repository; a hotfix, a refactor, or a week of work done without it is just what the next round plans against.
• Brainstormer stamps a delta. In a revision round it records which features were added, modified, and removed, and the downstream agents scope to that delta rather than re-deriving the whole application.
• Phaser plans only the change. Phase 1 of a revision is an integration thread that wires the new surface into the existing code, not a from-scratch steel thread, and no phases are emitted for established, unchanged features.
• Stale inputs are flagged, not ignored. Every artifact is dated against the ones upstream of it. If you re-run Brainstormer after StackAdvisor, the project page shows StackAdvisor as needing an update — and the coding agent's IMPLEMENTED marker is what tells Spec4 the round is built and the next one may begin.

So the plan is never the source of truth for long. The code is, and each round re-reads it. The Spec4 repository carries three rounds of Spec4 planning its own changes under .spec4/; the phase file quoted above is the first phase of the first of them.

Greenfield is only round one against an empty repository: the same re-read runs every round, so the plan is regenerated rather than maintained, and anything an upstream change has left behind is shown on the project page as stale inputs.

A round is a feature or a rework. For a change smaller than that, don't run one. Rounds

Built for production, not demos

A demo needs a happy path. A production system needs the rest, and Spec4's artifacts carry it:

• Every feature has failure modes. feature_specs.json records inputs, outputs, success criteria, and failure modes per MVP feature, technology-agnostic, before any stack is chosen.
• Non-functional goals are threaded, not listed. Performance, security, and reliability goals from the vision are matched to the stack components that satisfy them and rendered into the Verification section of every phase that touches them, as acceptance criteria — deterministically, from the stack spec, so the model can't drop one.
• Every phase names where the coding agent will go wrong. The Risk Assessment section calls out the likely bottlenecks and the places an AI coder tends to hallucinate — auth flows, third-party API quirks — with a mitigation for each.
• Every phase is verifiable. The Verification section is the exact command or observable that proves it's done, not a description of done.
• No dependency arrives unapproved. The stack spec is the component list. A phase that needs something not on it stops and asks; the answer is recorded as a stack addition.
• The deployment plan is complete files, not pointers. Dockerfile, CI pipeline, environment and secrets management, monitoring — and for AI features, model observability, eval cadence, and guardrails — as ready-to-use content with the exact commands to run.
• Canonical references, from live search. Every standard, protocol, or SDK a phase names links to its documentation, found by web search at planning time rather than recalled.

What the coding agent is handed. One phase at a time, as a file. Each phase says what it does and what it does not do yet; carries the stack, the mock, the feature spec, and the non-functional goals it depends on, so those are not the agent's to choose; and ends with a Verification section that is the command you run, not a description of done. The first phase of Spec4's own UI rework is at .spec4/v0/phases/phase1.md.

No spec can force an agent to comply. A phase file leaves it less to decide, and the Verification section is what you run to see what it did.

SnarkCheck is what the handed-over files became: three deployed surfaces, 130 tests, a CI pipeline that gates every deploy on them, and a fallback on every model call, built from one round's seven phase files, with the plan committed beside the code and the places where the two differ written down.

What it costs

Spec4's three rounds on itself, planning changes to its own code, and one greenfield round on SnarkCheck, with every call recorded. claude-sonnet-5 was the default; Phaser ran on claude-opus-5 in all three; Designer ran on claude-fable-5-1 in v0 and v1 and claude-opus-5 in v2. SnarkCheck ran Brainstormer and Agentifier on claude-opus-5 and the rest on claude-sonnet-5 at medium.

Elapsed is the first call's start to the last call's end, including the developer's time in the dialogue. Cost is LiteLLM's estimate from its community cost map; your provider's bill is authoritative. SnarkCheck's round ran in two sittings a day apart, and its elapsed is the two summed.

Spec4's three rounds ran before prompt caching, so their figures carry no cache reads. SnarkCheck's ran with it, on 1.5.1, and read 90% of its 2.55M input tokens from cache — StackAdvisor 96%, Deployer 92%. Spec4 caches the repeated part of each prompt automatically on Anthropic and AWS Bedrock. Caching

In Spec4's own rounds Phaser was the first or second largest line, because it holds every upstream artifact in context while it drafts; the other large lines were long dialogues on the default model. In SnarkCheck's round Phaser was fourth, at $0.43 on claude-sonnet-5 with caching, and the largest lines were Agentifier and StackAdvisor, the long dialogues. usage.json records every call per agent, per round, and the project page shows the totals. Each agent can override the project's default model and effort from its own gate, so you can put a stronger model on Phaser without changing anything else. Settings

What it isn't, and where your data goes

• Not a coding agent, and not tied to one. It doesn't assume every change goes through it either: work on the code however you like between rounds, and the next round starts from what's there. Spec4 produces the plan; Claude Code, Cursor, Codex, Copilot, or whatever you use does the building. The artifacts are plain Markdown and JSON with no agent-specific format — a phase file reads the same to a person as to an agent — and Deployer writes its coding-agent setup instructions for the agent you name, not for one it assumes.
• Not for every change. A round is the unit for a feature or a rework; for a quick script, a refactor, or a small feature in a mature codebase, it is more process than the change needs.
• No commands inside your coding agent. You hand it the files.
• It stops at the spec. Building and verifying the code is your coding agent's job and yours.
• Nothing runs in the cloud. The app is a local process; the only network calls are to the model provider you chose and, if you enable it, the search provider.
• CodeScanner reads your repository locally and sends the model a bounded summary — manifests, entry points, samples — not the tree.
• API keys are held in the browser (localStorage, opt-in) and never sent anywhere but the provider they belong to.
• Web search is off unless you give it a key.

"You've made something really really really cool. I'm almost done with our driver app. Will be field tested by Friday. I don't think I would have built what this is going to become without it."

— Wihan Booyse, Kriterion.ai

Install

Requires Python 3.12+ and uv, plus an API key for at least one of eight supported model providers: Anthropic, AWS Bedrock, Cohere, Google Gemini, Mistral, Nebius, OpenAI, or OpenRouter. A Tavily or Exa key is optional, for web search grounding.

uv tool install spec4 --refresh
spec4

From source:

git clone https://github.com/robertcrowe/spec4
cd spec4
make spec4

Either way the app is at localhost:8050. Pick a project directory, connect a provider, and start with Brainstormer — or CodeScanner if the directory already has code in it.

To upgrade: uv tool upgrade spec4 (PyPI) or git pull && make install (source). Upgrades never touch your artifacts: everything lives in .spec4/ inside your project. Saved credentials live in your browser's localStorage and carry over.

Run it on itself

Spec4 is a brownfield project like any other, and its own .spec4/ is committed:

uv tool install spec4 --refresh
spec4
# then select the spec4 directory as the project

The project page opens on the latest round with its artifacts and costs. Choose "existing project" and run CodeScanner to start a fourth.

Built With Spec4, a gallery of small apps at bw.spec4.ai, was planned in nine rounds, hand edits in between; the history is in its repo.

SnarkCheck, a checkers game with a commenting AI opponent, was planned in one round on 1.5.1 and built from the phase files; the plan, the code, the tests, and every planning call's cost are in its repository.