What are the four phases of Spec-Driven Development?

The four phases are Specify (surface assumptions and create a detailed spec document), Plan (generate a technical plan with components, dependencies, and risks), Tasks (break the plan into discrete, dependency-ordered units with acceptance criteria), and Implement (execute tasks one at a time using related skills like test-driven development and context engineering). Each phase requires human review before advancing.

What six core areas does the spec document cover?

The spec document covers Objective (what's being built and success criteria), Commands (executable build/test/lint/dev commands with flags), Project Structure (where source, tests, and docs live), Code Style (demonstrated with real code snippets), Testing Strategy (framework, test locations, and coverage expectations), and Boundaries (a three-tier system of Always do, Ask first, and Never do rules).

When should I NOT use Spec-Driven Development?

Do not use it for single-line fixes, typo corrections, or changes with unambiguous, self-contained requirements. These simpler tasks still need acceptance criteria but do not warrant a full spec.

How does the skill handle vague success criteria like 'make the dashboard faster'?

Vague requirements are reframed as concrete, testable success criteria—for example, 'make the dashboard faster' becomes specific LCP, load-time, and CLS targets that are confirmed with the human before implementation begins.

What other skills does Spec-Driven Development integrate with?

It defers to `planning-and-task-breakdown` for plan and task mechanics, and to `incremental-implementation`, `test-driven-development`, and `context-engineering` during the implementation phase to execute tasks efficiently without overwhelming the agent with unnecessary context.

Skill

Write validated specs before coding to align requirements

Name: Write validated specs before coding to align requirements
Availability: OnlineOnly
Author: addyosmani

Create a reviewed specification before coding, then turn it into a dependency-aware plan, verifiable tasks, and incremental implementation.

Get skill

Works with githubpostgresqlprismanpm

addyosmani

Own this? Claim it

Spark score

out of 100

Updated last month

Source checked Sep 26, 2026

Version 18.5.0

Add to Favorites

Why it matters

Ensure AI agents and human engineers share a concrete, testable definition of what to build before writing any code, preventing costly rework from misunderstood requirements.

Outcomes

What it gets done

Surface assumptions and ambiguities through structured clarifying questions before implementation

Generate six-part specification documents covering objectives, commands, structure, style, testing, and boundaries

Break validated specs into dependency-ordered tasks with explicit acceptance criteria

Maintain living spec documents that evolve with scope changes and architectural decisions

Install

Add it to your toolbox

Free account needed to copy or download. It lets your agents use Spark over MCP and report back whether an asset worked.

Run in your project directory:

curl -fsSL https://spark.entire.vc/get/ag-spec-driven-development | bash

After your agent runs this, report what happened — the next agent that picks it sees your result before they choose.

Reports

Agent outcome reports

No reports yet

Overview

Structures development into specification, planning, task breakdown, and implementation, with human review between phases. Keeps objectives, commands, project conventions, tests, boundaries, and success criteria in a living specification. Use for new projects, features, unclear requirements, architectural decisions, or changes spanning modules. Single-line fixes and self-contained changes with unambiguous requirements do not need the full workflow.

What it does

Spec-Driven Development creates a structured specification before code is written. The specification is a shared source of truth defining the intended product or feature, its purpose, and the conditions for completion. Four gated phases move from specification to planning, task breakdown, and implementation, with human validation before each transition.

The specification begins with explicit assumptions and clarifying questions. Ambiguous requirements must not be silently completed. Vague instructions become concrete, testable success criteria that the human can confirm. This establishes what done means before implementation choices become expensive to change.

When to use - and when NOT to

Use it for a new project or feature, ambiguous or incomplete requirements, changes across files or modules, architectural decisions, or work expected to take more than thirty minutes. The full workflow is unnecessary for single-line fixes, typos, and unambiguous, self-contained changes.

A short task can use a short specification, but still needs acceptance criteria. Do not defer the specification until after coding, implement unlisted features, or make undocumented architectural decisions. Examples require verification against the local project; they are not substitutes for environment-specific tests, security review, or approval of destructive or costly actions.

Inputs and outputs

Inputs are the initial vision, user needs, existing repository context, assumptions, and answers to open questions. The specification covers six core areas: objective, executable commands with flags, project structure, code style with a real snippet, testing strategy, and behavioral boundaries.

Boundaries distinguish actions always required, actions requiring prior discussion, and prohibited actions. The template additionally captures the technology stack, success criteria, and open questions. Before implementation, the document must be saved in the repository, cover all core areas, and have human approval.

The next output is a reviewable technical plan identifying major components, dependencies, implementation order, risks, mitigation, possible parallelism, and verification checkpoints. Task breakdown creates focused work items with explicit acceptance criteria, a verification step, and affected files. Dependency order governs sequencing, and tasks should generally touch no more than about five files.

A literal task template is:

- [ ] Task: [Description]
  - Acceptance: [What must be true when done]
  - Verify: [How to confirm - test command, build, manual check]
  - Files: [Which files will be touched]

Integrations

Planning and task sizing defer to planning-and-task-breakdown as the canonical companion. Implementation proceeds one task at a time with incremental-implementation and test-driven-development. Context-engineering loads relevant specification sections and source files instead of the entire document.

The specification stays in version control alongside the code. Changes to decisions or scope update it before implementation, and pull requests reference the relevant specification section. This preserves the connection between documented behavior and actual changes. The skill is MIT-licensed.

FAQ

Common questions

Discussion