Spec-driven development

Writes a spec before code, surfacing assumptions and covering objective, commands, structure, style, tests and boundaries, then gates plan, tasks and code on approval, with capability maps and delta specs. Use when new work has vague requirements.

Vibe codingPack: Agent Skills by Addy Osmani307 linesspec-driven-development
Author
Source
addyosmani/agent-skills/skills/spec-driven-development @ 8c99fa3
License
MIT · Copyright (c) 2025 Addy Osmani

About this skill

What it does

The skill makes the agent write a specification before code and moves the work through four phases — specify, plan, tasks, implement — each gated by your review. In the first phase the agent lists its assumptions for you to correct, turns vague asks into testable criteria ("faster" becomes LCP under 2.5 s) and writes a spec covering six areas: objective, commands, project structure, code style, testing strategy and boundaries. The template adds success criteria, an Out of Scope (Deferred) list and open questions. Then the agent stops and waits for your approval before planning.

Two parts set it apart. A Phase 0 scope check: when one request bundles several independently testable capabilities, the agent first puts a capability map up for your review — module ids, dependencies, build order — saves it as spec/capability-map.md, then writes one spec per module. And versions: the spec title says V1, ideas that come up mid-build go to the Deferred list, and a change to a shipped feature gets its own delta spec (SPEC-<change>.md next to SPEC.md), folded back into the original once it ships. A project already on OpenSpec keeps its format.

The folder holds SKILL.md and the licence.

When to use it, and when not

Use it to start a project or feature, when requirements are vague, when a change spans several modules or would take more than about 30 minutes, and to scope a V2 or a change to something already shipped.

Skip it for one-line fixes, typos and changes whose requirements are clear and self-contained.

How to run it

The install command below puts SKILL.md and the licence in place. The agent picks the skill up by its description when new work has no spec yet; to call it yourself:

  • Claude Code: /spec-driven-development, or ask for the skill by name.
  • Codex: $spec-driven-development.
  • Cursor: type / in the Agent chat and pick spec-driven-development.

Example: /spec-driven-development We need team invitations by email. Write the spec and wait for my review.

Plan and tasks follow Planning and task breakdown; implementation follows Incremental implementation and Test-driven development, red-green-refactor, with Context engineering for agents for loading the right spec sections. Install them together for the whole flow.

How it differs from similar skills

Spec-first kickoff is the light version: up to five questions with defaults, then a one-page spec and a 4–10-step plan in one go. Conversation to spec does not interview at all: it turns what was already discussed into user stories and implementation decisions and publishes them to the tracker set up by the author's setup-matt-pocock-skills, or one you name. Brainstorming before you build also holds code back until you approve, but you approve one design doc reached in conversation, and the plan is left to another skill. Interview me from the same pack comes before this skill when you do not yet know what you want, and hands it the confirmed intent. This skill is the one with gates between phases, capability maps, versions and delta specs.

Install

Run one command — it saves SKILL.md and the files it uses into your agent's skills folder. Claude Code and Codex pick up a new skill without a restart; if it does not show up, restart the agent.

Claude Code — macOS, Linux
curl -fsSL --create-dirs -o ~/.claude/skills/spec-driven-development/SKILL.md https://anymodel.org/en/skills/addy-osmani/spec-driven-development/SKILL.md -o ~/.claude/skills/spec-driven-development/LICENSE https://anymodel.org/en/skills/addy-osmani/spec-driven-development/LICENSE
Codex, Cursor — macOS, Linux
curl -fsSL --create-dirs -o ~/.agents/skills/spec-driven-development/SKILL.md https://anymodel.org/en/skills/addy-osmani/spec-driven-development/SKILL.md -o ~/.agents/skills/spec-driven-development/LICENSE https://anymodel.org/en/skills/addy-osmani/spec-driven-development/LICENSE
Claude Code — Windows PowerShell
foreach ($f in 'SKILL.md','LICENSE') { $p = Join-Path "$HOME\.claude\skills\spec-driven-development" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/addy-osmani/spec-driven-development/$f" -UseBasicParsing -OutFile $p }
Codex, Cursor — Windows PowerShell
foreach ($f in 'SKILL.md','LICENSE') { $p = Join-Path "$HOME\.agents\skills\spec-driven-development" $f; New-Item -ItemType Directory -Force (Split-Path $p) | Out-Null; Invoke-WebRequest "https://anymodel.org/en/skills/addy-osmani/spec-driven-development/$f" -UseBasicParsing -OutFile $p }

Any other agent: save the file into its skills folder, or give it the link to the file: https://anymodel.org/en/skills/addy-osmani/spec-driven-development/SKILL.md

SKILL.md

Raw

Spec-Driven Development

Overview

Write a structured specification before writing any code. The spec is the shared source of truth between you and the human engineer — it defines what we're building, why, and how we'll know it's done. Code without a spec is guessing.

When to Use

  • Starting a new project or feature
  • Requirements are ambiguous or incomplete
  • The change touches multiple files or modules
  • You're about to make an architectural decision
  • The task would take more than 30 minutes to implement

When NOT to use: Single-line fixes, typo corrections, or changes where requirements are unambiguous and self-contained.

The Gated Workflow

Spec-driven development has four phases, preceded by a scope check (Phase 0) that activates only when one request bundles several independently testable capabilities. Do not advance to the next phase until the current one is validated.

SPECIFY ──→ PLAN ──→ TASKS ──→ IMPLEMENT
   │          │        │          │
   ▼          ▼        ▼          ▼
 Human      Human    Human      Human
 reviews    reviews  reviews    reviews

Phase 0: Scope Check

Most requests describe one capability. If this one does, skip this phase and go straight to Specify — Phase 0 exists for the exception, not the rule, and it puts no hierarchy on single-capability features.

Detection. Decompose before specifying when a single requirement bundles several independently testable capabilities:

  • The requirement names distinct capabilities with their own consumers or data (e.g. identity, billing, notifications, reporting)
  • Acceptance criteria cluster into groups that could ship and be verified separately
  • One capability could be cut or replaced without rewriting the others' requirements

Propose a capability map before writing any spec. Small and reviewable — a module table plus a build order, not a project plan:

# Capability Map: [Initiative Name]

| Module id | Responsibility | Depends on |
|---|---|---|
| identity | Accounts, sessions, SSO | — |
| billing | Plans, invoices, payments | identity |
| notifications | Email and webhook fan-out | identity |
| reporting | Usage dashboards | billing, notifications |

Build order: identity → billing, notifications → reporting
  • Stable module ids. Kebab-case, chosen once, never renamed mid-initiative. Specs, plans, and downstream commands select work by these ids instead of guessing which spec is active.
  • Dependency direction, no cycles. Arrows point one way. If two modules each need the other, they are one module.
  • Interfaces live at the boundary. The map records that billing depends on identity; the contract between them belongs in the provider module's spec (see api-and-interface-design for designing it).

The map is gated like every phase. The human reviews module boundaries, dependency direction, and build order before any module spec is written. Getting the map wrong is expensive; reviewing ten lines is not.

Then recurse per module. Run Specify → Plan → Tasks → Implement for each module in dependency order. Each module gets its own spec, scoped to that module's objective, boundaries, and success criteria. Save the approved map as spec/capability-map.md and each module's spec alongside it in spec/, named by module id (spec/SPEC-identity.md, spec/SPEC-billing.md) — /build already accepts specs under spec/, and the root stays uncluttered — the map, not filename guessing, is the index of what exists.

Phase 1: Specify

Start with a high-level vision. Ask the human clarifying questions until requirements are concrete.

Surface assumptions immediately. Before writing any spec content, list what you're assuming:

ASSUMPTIONS I'M MAKING:
1. This is a web application (not native mobile)
2. Authentication uses session-based cookies (not JWT)
3. The database is PostgreSQL (based on existing Prisma schema)
4. We're targeting modern browsers only (no IE11)
→ Correct me now or I'll proceed with these.

Don't silently fill in ambiguous requirements. The spec's entire purpose is to surface misunderstandings before code gets written — assumptions are the most dangerous form of misunderstanding.

Write a spec document covering these six core areas:

  1. Objective — What are we building and why? Who is the user? What does success look like?

  2. Commands — Full executable commands with flags, not just tool names.

    Build: npm run build
    Test: npm test -- --coverage
    Lint: npm run lint -- --fix
    Dev: npm run dev
    
  3. Project Structure — Where source code lives, where tests go, where docs belong.

    src/           → Application source code
    src/components → React components
    src/lib        → Shared utilities
    tests/         → Unit and integration tests
    e2e/           → End-to-end tests
    docs/          → Documentation
    
  4. Code Style — One real code snippet showing your style beats three paragraphs describing it. Include naming conventions, formatting rules, and examples of good output.

  5. Testing Strategy — What framework, where tests live, coverage expectations, which test levels for which concerns.

  6. Boundaries — Three-tier system:

    • Always do: Run tests before commits, follow naming conventions, validate inputs
    • Ask first: Database schema changes, adding dependencies, changing CI config
    • Never do: Commit secrets, edit vendor directories, remove failing tests without approval

Spec template:

# Spec: [Project/Feature Name] — V[N]

## Objective
[What we're building and why. User stories or acceptance criteria.]

## Tech Stack
[Framework, language, key dependencies with versions]

## Commands
[Build, test, lint, dev — full commands]

## Project Structure
[Directory layout with descriptions]

## Code Style
[Example snippet + key conventions]

## Testing Strategy
[Framework, test locations, coverage requirements, test levels]

## Boundaries
- Always: [...]
- Ask first: [...]
- Never: [...]

## Success Criteria
[How we'll know this is done — specific, testable conditions]

## Out of Scope (Deferred)
[Ideas explicitly excluded from this version — the V2 backlog. One line each: what, and why it's deferred.]

## Open Questions
[Anything unresolved that needs human input]

External spec tools: This workflow is format-agnostic. If the project already uses OpenSpec or another specification system, keep that system's artifact format and storage conventions instead of creating a duplicate SPEC.md. This skill owns the clarification, content, and approval gates; the external tool owns how the approved spec is represented.

Reframe instructions as success criteria. When receiving vague requirements, translate them into concrete conditions:

REQUIREMENT: "Make the dashboard faster"

REFRAMED SUCCESS CRITERIA:
- Dashboard LCP < 2.5s on 4G connection
- Initial data load completes in < 500ms
- No layout shift during load (CLS < 0.1)
→ Are these the right targets?

This lets you loop, retry, and problem-solve toward a clear goal rather than guessing what "faster" means.

Stop after writing the spec (CRITICAL). Once the spec is saved:

  1. Summarize it and list any Open Questions.
  2. Ask the human to approve it or request changes.
  3. STOP YOUR TURN IMMEDIATELY. Do NOT start Phase 2, invoke planning-and-task-breakdown, or write code in this turn. Planning starts only after the human approves the spec in a later turn.

Phase 2: Plan

With the validated spec, generate a technical implementation plan:

  1. Identify the major components and their dependencies
  2. Determine the implementation order (what must be built first)
  3. Note risks and mitigation strategies
  4. Identify what can be built in parallel vs. what must be sequential
  5. Define verification checkpoints between phases

Follow planning-and-task-breakdown for the dependency-graph mapping and vertical-slicing mechanics behind these steps; it is the canonical source. The bullets above are a lightweight summary; if they ever diverge, planning-and-task-breakdown takes precedence.

Output convention: Save the plan to tasks/plan.md and record the task list in the task list target defined by planning-and-task-breakdown (default tasks/todo.md; projects may designate an external tracker instead). Create tasks/ if it does not exist. Downstream commands (/build, etc.) expect these defaults.

The plan should be reviewable: the human should be able to read it and say "yes, that's the right approach" or "no, change X."

Phase 3: Tasks

Break the plan into discrete, implementable tasks:

  • Each task should be completable in a single focused session
  • Each task has explicit acceptance criteria
  • Each task includes a verification step (test, build, manual check)
  • Tasks are ordered by dependency, not by perceived importance
  • No task should require changing more than ~5 files

Follow planning-and-task-breakdown for the full task-sizing and dependency-ordering mechanics; it is the canonical source. The template below is a lightweight inline form; if they ever diverge, planning-and-task-breakdown takes precedence.

Task template:

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

Phase 4: Implement

Execute tasks one at a time following skills/incremental-implementation/SKILL.md (incremental-implementation) and skills/test-driven-development/SKILL.md (test-driven-development). Use skills/context-engineering/SKILL.md (context-engineering) to load the right spec sections and source files at each step rather than flooding the agent with the entire spec.

Keeping the Spec Alive

The spec is a living document, not a one-time artifact:

  • Update when decisions change — If you discover the data model needs to change, update the spec first, then implement.
  • Update when scope changes — Features added or cut should be reflected in the spec.
  • Commit the spec — The spec belongs in version control alongside the code.
  • Reference the spec in PRs — Link back to the spec section that each PR implements.

Spec Evolution: V1 Scoping and Follow-Up Changes

A spec describes one version of the work. New ideas and post-ship changes don't expand it — they queue behind it.

Scope each version explicitly

Label the spec with the version it describes, in the title (# Spec: Invoice Pipeline — V1). When a shipped delta is folded back in, bump the version — the label always states which version of the system the spec describes, and makes "that's a V2 idea" an objective call rather than a judgment made mid-build.

During Specify, ideas that won't make this version go under Out of Scope (Deferred) — captured, not lost. This makes the V1 boundary enforceable: during implementation, anything not in the spec's requirements is out, even if it's written in the same file under Deferred. When an idea arrives mid-build, park it in the Deferred list and keep going; re-scoping happens between versions, not during one.

Follow-up changes get a delta spec

Once a spec has shipped, a new requirement — swapping the storage engine, replacing a manual step with OCR, promoting a deferred V2 item — gets its own small spec rather than a hand-edit of the shipped one. A delta spec covers only what changes:

# Spec Delta: [Change Name]

Status: proposed

## Objective
[The change and why. Which deferred item or new requirement this implements.]

## Current Behavior
[What exists today — link the relevant section of the original spec.]

## New Behavior
[What will be true after the change.]

## Success Criteria
[Specific, testable conditions — including what must NOT change.]

## Boundaries
[Only deltas from the original spec's boundaries; everything else inherits.]

Save it alongside the original (e.g. SPEC-postgres-migration.md next to SPEC.md) and run it through the same gated workflow: human review, then plan, tasks, implement. Downstream commands know this convention — /build auto accepts a root-level SPEC-<change>.md as the spec for a follow-up change and treats it as a planning artifact in its clean-baseline check. Keep one change per delta spec — that keeps each plan/build cycle small and reviewable.

After the change ships, fold the outcome into the original spec (per Keeping the Spec Alive) so it stays the source of truth for what exists, and mark the delta implemented by changing its Status: line to Status: implemented. The original spec always describes the current system; delta specs describe transitions.

Common Rationalizations

Rationalization Reality
"This is simple, I don't need a spec" Simple tasks don't need long specs, but they still need acceptance criteria. A two-line spec is fine.
"I'll write the spec after I code it" That's documentation, not specification. The spec's value is in forcing clarity before code.
"The spec will slow us down" A 15-minute spec prevents hours of rework. Waterfall in 15 minutes beats debugging in 15 hours.
"Requirements will change anyway" That's why the spec is a living document. An outdated spec is still better than no spec.
"The user knows what they want" Even clear requests have implicit assumptions. The spec surfaces those assumptions.
"This idea is good, I'll fold it into the current spec" Mid-build scope growth is how V1 slips. Park it under Out of Scope (Deferred) — captured without expanding the current cycle.
"The feature already has a spec, I'll just edit it for the change" A shipped spec describes what exists. A delta spec keeps the change reviewable on its own; the original gets updated after the change ships, not before.
"It's one big feature; splitting it is overhead" If acceptance criteria cluster into independently testable groups, a monolithic spec forces every downstream task to reason over the whole contract. A ten-line capability map is the cheap alternative.
"I'll decompose during planning" Planning slices tasks within a spec. By then the oversized artifact already exists — module boundaries and dependency direction must be decided before the spec is written, not after.

Red Flags

  • Starting to write code without any written requirements
  • Asking "should I just start building?" before clarifying what "done" means
  • Implementing features not mentioned in any spec or task list
  • Making architectural decisions without documenting them
  • Skipping the spec because "it's obvious what to build"
  • V1 requirements growing mid-implementation as new ideas get written straight into the spec
  • Changing a shipped feature with no spec for the change because "the feature already has one"
  • Writing the spec and starting the plan or code in the same turn
  • One spec whose requirements span several independently testable capabilities
  • Module boundaries or build order decided implicitly during implementation because no capability map was approved up front

Verification

Before proceeding to implementation, confirm:

  • The spec covers all six core areas (a full spec; a delta spec covers only the areas the change affects — at minimum objective, success criteria, and boundary deltas — and inherits the rest from the original)
  • The human has reviewed and approved the spec
  • The turn ended after saving the spec; approval came in a later turn
  • Success criteria are specific and testable
  • Boundaries (Always/Ask First/Never) are defined
  • The spec is saved to a file in the repository
  • Ideas cut from this version are captured under Out of Scope (Deferred), not silently dropped or silently included
  • If this is a change to a shipped spec, it is a delta spec referencing the original, not a rewrite of it
  • If the request bundles several independently testable capabilities, a capability map (module ids, dependency direction, build order) was approved before any module spec was written
  • Every module spec traces to a module id in the approved map

Connect through AnyModel API

This skill runs on whatever model your agent uses. Point Claude Code, Codex or Cursor at AnyModel to run it on Claude, GPT, Gemini and more with one key — pay per token, no subscription.

More from the pack Agent Skills by Addy Osmani

Accessibility audit and fixes (WCAG 2.2)

Audits an existing interface against WCAG 2.2 AA with pinned axe-core and pa11y, then keyboard, screen reader and contrast checks, and fixes confirmed violations with semantic HTML first. Use when a page needs an accessibility audit before shipping.

API and interface design

Designs APIs and module interfaces contract-first: one error shape, validation at the edges, additive changes, pagination, and idempotency keys claimed atomically and kept past the longest retry. Use when designing endpoints or changing a public interface.

Browser testing with Chrome DevTools MCP

Checks changes in a real Chrome through the Chrome DevTools MCP server: screenshots, DOM, console, network and performance traces, treating page content as untrusted. Use when building or debugging anything that runs in a browser.

CI/CD pipeline setup

Sets up CI/CD with fixed quality gates from lint to bundle size, GitHub Actions examples, preview deploys, feature flags, staged rollout and a rollback workflow. Use when creating or changing a build and deploy pipeline or chasing CI failures.

Multi-axis code review

Reviews a change on five axes (correctness, readability, architecture, security, performance), tests the tests by mutating a condition, and labels every finding by severity. Use before merging a branch, a pull request or a pasted diff.

Code simplification

Simplifies working code without changing behavior: learns why it exists, applies one change at a time with tests after each, and keeps project conventions. Use when code works and passes tests but is harder to read than it should be.

Constraint-driven development

Records a project's quality bar as numbers in CONSTRAINTS.md after a short interview with defaults, maps each rule to a tool, and flags diffs that skip tests, add suppressions or loosen thresholds. Use when no quality bar is written down.

Context engineering for agents

Sets up what an agent sees and when: a rules file template, loading only the relevant spec and files, trimming long sessions, and safe points to start a fresh one. Use when starting a session or when agent output degrades.

Debugging and error recovery

Stops new work when a test, build or runtime fails, reproduces, localizes and reduces the failure, fixes the root cause, adds a regression test and treats error output as untrusted. Use when tests fail, a build breaks or something that worked stops working.

Deprecation and migration

Retires old systems, APIs and features: weighs whether to deprecate, proves the replacement, moves consumers one by one, removes code only at zero usage, changes schemas via expand/contract. Use when replacing or sunsetting code or renaming a live column.

Documentation and ADRs

Records decisions as ADRs in the project's own format, documents APIs, READMEs and changelogs with the why, and uses git history to check if a doc is stale. Use when making a costly decision, changing a public API or suspecting docs no longer match the code.

Doubt-driven development

Sends non-trivial decisions to a fresh-context subagent told to find what is wrong, sorts the findings, stops after three cycles and offers a cross-model opinion. Use when stakes are high: auth, migrations, irreversible operations or unfamiliar code.

Frontend UI engineering

Builds UI components and pages on the project's design system: composition, simple state, WCAG 2.1 AA, mobile-first layouts, loading, empty and error states, no generic AI look. Use when building or changing a user-facing interface.

Git workflow and versioning

Keeps git work in atomic commits on short-lived branches, with typed messages, a pre-commit check for secrets and tests, worktrees for parallel agents, semver bumps, tags and a human changelog. Use when committing, branching, opening a PR or cutting a release.

Idea refinement

Refines a raw idea in three phases: sharpening questions and five to eight variations, two or three directions tested for value and feasibility, then a one-pager with MVP scope and a Not Doing list. Use when an idea is vague or a plan needs stress-testing.

Incremental implementation

Builds changes in thin vertical, contract-first or risk-first slices, each tested, verified and committed before the next, with strict scope, feature flags and revertable steps. Use when a change spans several files or a task is too big to land in one step.

Interview me

Interviews the user one question at a time, each with a guessed answer and a confidence number, until the agent can predict the next replies, then confirms a statement of intent before any spec or code. Use when a request leaves who, why or success unclear.

Observability and instrumentation

Instruments a feature with structured JSON logs and request IDs, RED and USE metrics with bounded labels, OpenTelemetry traces and symptom-based alerts with runbooks, then tests the telemetry. Use when a feature, job or integration is headed for production.

Performance optimization

Optimizes by measurement: takes a baseline, fixes the one proven bottleneck, re-measures against noise and reverts neutral changes, with worked fixes for N+1 queries, indexes, caching and bundles. Use when something is slow or misses a performance budget.

Planning and task breakdown

Breaks a spec into small vertical-slice tasks with acceptance criteria, verification steps, sizes, dependency order and checkpoints, saved to tasks/todo.md or a named tracker. Use when a spec is ready but the work is too big to start in one go.

Security hardening

Hardens code with a short threat model, always, ask-first and never rules, and patterns for injection, XSS, access control, SSRF, secrets, dependencies, personal data and LLM output. Use when code handles user input, auth, sensitive data or outside services.

Shipping and launch

Prepares a production launch with a pre-launch checklist, a feature-flag rollout from 5% to 100%, thresholds for advancing or rolling back, an error-budget gate, a rollback plan and first-hour checks. Use when a feature or major change is about to ship.

Source-driven development

Grounds framework code in official docs: reads exact versions from the dependency file, fetches the relevant page, follows the documented API and cites full URLs, flagging anything unverified. Use when framework-specific code must match the version in use.

Test-driven development, red-green-refactor

Drives changes with red-green-refactor: finds the repository's own test commands, writes the failing test first, reproduces each bug with a test before fixing it, and sets rules on mocks and naming. Use when adding logic, fixing a bug or changing behavior.