# Write Specs First

Writes a spec with objectives and scope before any code for a new feature.

- Repository: https://github.com/addyosmani/agent-skills (112533 stars)
- Category: Documents
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add addyosmani/agent-skills --skill spec-driven-development -g -a claude-code -y`
Codex: `npx skills add addyosmani/agent-skills --skill spec-driven-development -g -a codex -y`
Cursor: `npx skills add addyosmani/agent-skills --skill spec-driven-development -g -a cursor -y`
Gemini CLI: `npx skills add addyosmani/agent-skills --skill spec-driven-development -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add addyosmani/agent-skills`

## Description

Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet. Use when drafting a PRD or requirements document with objectives and scope, or when requirements are unclear, ambiguous, or only exist as a vague idea. Use when a single requirement spans several independently testable capabilities and needs decomposing into a capability map of modules before specifying.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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:

```markdown
# Capability Map: [Initiative Name]

The rest: https://github.com/addyosmani/agent-skills/blob/HEAD/skills/spec-driven-development/SKILL.md