Spec-driven development

This guide introduces spec-driven development and the workflow Flow builds around it. You will learn:

• What spec-driven development is and why it suits AI coding agents
• The skills in the Flow workflow and the order you run them in
• How Flow organizes the files the workflow produces

Overview

Spec-driven development, often shortened to SDD, is a way of building software where you write and review a specification before any code exists, and the implementation is then held to that spec.

The idea is not new. What makes it matter now is AI coding agents. When you hand an agent a one-line request, such as "add a way for users to archive a project", it does not ask the dozens of questions a careful engineer would. It picks an answer for each one, silently, and writes code. You review the result, but by then the hundred small decisions are already baked in, and the only record of them is the code itself.

Spec-driven development breaks that pattern. It forces the decisions into the open, as documents you review while they are still cheap to change.

Why spec-driven development

Reviewing a plan is faster and safer than reviewing a finished feature. A plan that says "archived projects stay visible in a separate tab" is one line to correct. The same decision discovered after the build is a component, a query, a route, and a test to unwind.

For an AI agent specifically, the workflow does three things:

• It surfaces the gaps. Instead of guessing what "archive" means, the agent interviews you, and every ambiguity becomes a question you answer.
• It splits one large review into several small ones. You review a product brief, then a technical plan, then a test plan. Each is short and focused, and a mistake caught in the brief never reaches the code.
• It constrains the build. The agent writing the code is executing an approved plan, not improvising. When reality does not match the plan, it stops and asks rather than papering over the difference.

The workflow

Flow implements spec-driven development as a sequence of skills. Each skill is a slash command you invoke, and each one produces a document the next skill reads. See your agent's guide for the exact command syntax.

A feature moves through six skills, in order:

1. Brief interviews you about the feature the way a product manager would. The output is a product brief: what the user does and sees, with no technology in it.
2. Blueprint turns the brief into a technical plan, grounded in the harness docs. It decides the schema, the controllers, the validation, and the rest.
3. Assert plans the tests: exactly what each test will assert, pinned down before any code is written.
4. Build implements the change, holding the code to the blueprint and the test plan.
5. Sync promotes the finished change into Flow's long-lived record of how each capability behaves.
6. Archive files the completed change away.

Every step gates on your approval. The planning skills (brief, blueprint, and assert) work one decision at a time, present their reasoning, and wait. None of them writes application code. Build is the only skill that touches your codebase, and it does so against plans you have already approved.

The open-ended track

Not all work is a user-facing feature. Migrating a package, restructuring a folder, or applying a refactor across many files has no user journey to interview and no obvious set of tests to plan first.

For this work, Flow provides a second track. The task skill takes a description of the work, breaks it into ordered steps, and writes a single self-contained workflow document that an agent then executes. It replaces the blueprint, assert, and build trio for work that does not fit the feature shape.

How Flow organizes its files

Everything the workflow produces lives under a .flow/ directory in your project.

• .flow/docs/ holds the knowledge base, the harness docs the skills read.
• .flow/changes/<name>/ is one folder per change in progress. The brief, blueprint, and test plan for a change all live here.
• .flow/changes/archive/ holds finished changes, filed by the archive skill.
• .flow/states/ holds the canonical state: one file per capability, describing what that capability does today.

The distinction between a change and a state is worth pausing on. A change is one unit of work, and it is temporary: once it ships, the change folder is archived. A state file is durable. It is the current, always-true description of a capability, updated every time a change touches it. The sync skill is the bridge: it reads what a finished change altered and folds that into the state files, so the canonical record never goes stale.

Next steps

• Start the workflow with the Brief guide.
• New to the harness docs the skills depend on? Read the Knowledge base guide.