Spec-Driven Development

Manage complex development tasks through structured specifications that persist across sessions and minimize context overhead.

When to Use

Feature too large for single chat session
Multiple implementation phases required
Cross-cutting changes spanning multiple files
Need to track requirements/progress across sessions
Brownfield changes to existing behavior

Core Workflow

Spec → Define requirements (WHAT, not HOW)
Plan → Technical approach (architecture, stack)
Tasks → Actionable breakdown with dependencies
Implement → Execute tasks with validation
Archive → Update specs, close feature

Directory Structure

specs/
├── project.md           # Project-level conventions, stack, patterns
├── features/            # Active specifications (source of truth)
│   └── {feature}/
│       ├── spec.md      # Requirements + acceptance criteria
│       ├── plan.md      # Technical implementation plan
│       ├── tasks.yaml   # Task breakdown (YAML format)
│       └── design.md    # Architecture decisions (optional)
├── changes/             # Proposed changes (deltas)
│   └── {change-name}/
│       ├── proposal.md  # What and why
│       ├── tasks.yaml   # Implementation checklist
│       └── specs/       # Spec deltas (additions/modifications)
└── archive/             # Completed changes

Phase 1: Specification

Create specs/features/{feature}/spec.md:

# {Feature Name}

## Purpose
One-line description of what this delivers.

## User Stories
### US-1: {Story Title}
AS A {role} I WANT {capability} SO THAT {benefit}

#### Acceptance Criteria
- [ ] GIVEN {context} WHEN {action} THEN {outcome}
- [ ] ...

## Requirements
### REQ-1: {Requirement}
The system SHALL {behavior}.

### REQ-2: {Requirement}
The system MUST {constraint}.

## Out of Scope
- {Explicitly excluded items}

## Open Questions
- [ ] {Unresolved decisions}

Key principles:

Focus on WHAT, not HOW
Be explicit about boundaries
One user story = one testable unit
Use SHALL/MUST/SHOULD per RFC 2119

Clarifying requirements: Use the AskUserQuestion tool to resolve ambiguities before writing specs. Common clarifications:

User roles and permissions model
Edge cases and error scenarios
Priority between conflicting requirements
Scope boundaries (what's explicitly out)

Phase 2: Planning

Create specs/features/{feature}/plan.md:

# Implementation Plan: {Feature}

## Technical Approach
{High-level architecture decision and rationale}

## Stack/Dependencies
- {framework}: {version} - {purpose}
- {library}: {version} - {purpose}

## Data Model
{Schema changes, new models}

## API Contracts
{Endpoint definitions, request/response shapes}

## Implementation Phases
### Phase 1: {Name}
{Description and components}

### Phase 2: {Name}
{Dependencies on Phase 1}

## Risks & Mitigations
| Risk | Impact | Mitigation |
|------|--------|------------|
| {risk} | {H/M/L} | {strategy} |

Before planning:

Explore the codebase using the Task tool with subagent_type=Explore to understand:
- Existing patterns and conventions
- Related components and their interfaces
- Current architecture and data flow
- Files that will be affected
Surface ambiguities by reviewing:
- Authentication/authorization model
- Error handling strategy
- Performance constraints
- Integration boundaries

Use AskUserQuestion if exploration reveals architectural decisions that need user input.

Phase 3: Task Breakdown

Create specs/features/{feature}/tasks.yaml:

feature: feature-name

phases:
  - id: 1
    name: Phase Name
    checkpoint: Validation criteria before Phase 2
    tasks:
      - id: "1.1"
        title: Task Title
        files: [src/file.ts]
        depends: []
        notes: Implementation hints
        subtasks:
          - text: Implementation
            done: false
          - text: Tests
            done: false

      - id: "1.2"
        title: Task Title
        files: [src/other.ts]
        depends: []
        parallel: true
        subtasks:
          - text: Implementation
            done: false
          - text: Tests
            done: false

  - id: 2
    name: Phase Name
    tasks:
      - id: "2.1"
        title: Task Title
        files: [src/file.ts]
        depends: ["1.1", "1.2"]
        subtasks:
          - text: Implementation
            done: false
          - text: Tests
            done: false

Task granularity:

Each task: 1-2 files, <100 lines changed
Include file paths for context loading
Mark dependencies explicitly
Group by functional area

Phase 4: Implementation

Execute tasks sequentially:

Load task from tasks.yaml
Load referenced files (use Task with subagent_type=Explore if you need broader context)
Implement changes
Run tests/validation
Mark subtask done: true
Commit checkpoint

Session continuity: Use ${CLAUDE_PLUGIN_ROOT}/cli/dist/spec resume {feature} to load spec + tasks, show progress, and identify next task.

When blocked: Use AskUserQuestion to get user input on implementation decisions rather than making assumptions.

Phase 5: Archive

When feature complete:

Update specs/features/{feature}/ with final state
Move change folder to specs/archive/
Update project.md if conventions changed

Token Optimization

Spec Loading Strategy

Always load (minimal context):

project.md (conventions only)
tasks.yaml (current phase only)

Load on demand:

spec.md → When clarifying requirements
plan.md → When making technical choices
design.md → When architecting

Compact Spec Format

For token-constrained contexts, use compact notation:

## US-1: User Login
AC: [valid-creds→JWT] [invalid→401] [lockout@5-fails]
REQ: SHALL issue JWT on success, MUST hash passwords bcrypt

Progress Checkpoints

Save progress atomically:

<!-- specs/features/{feature}/checkpoint.md -->
## Session: {date}
- Completed: 1.1, 1.2, 1.3
- Next: 2.1
- Blockers: None
- Notes: {Context for next session}

Brownfield Changes

For modifications to existing behavior:

Create change proposal in specs/changes/{name}/
Spec delta shows ONLY changes:

## ADDED Requirements
### REQ-5: Two-Factor Auth
The system MUST require OTP on login.

## MODIFIED Requirements
### REQ-2: Session Duration (was: 24h)
The system SHALL expire sessions after 1h of inactivity.

## REMOVED Requirements
### REQ-3: Remember Me
Deprecated in favor of REQ-5.

Tasks reference both existing code AND spec delta
Archive merges delta into canonical spec

CLI Commands

The CLI is automatically built when the plugin is installed. Run commands using:

${CLAUDE_PLUGIN_ROOT}/cli/dist/spec [command]

Note: Requires Bun to be installed for the initial build.

Command	Description
`${CLAUDE_PLUGIN_ROOT}/cli/dist/spec init [name]`	Initialize `specs/` structure with templates
`${CLAUDE_PLUGIN_ROOT}/cli/dist/spec status`	Show all features and their progress
`${CLAUDE_PLUGIN_ROOT}/cli/dist/spec resume {feature}`	Show progress + next task + minimal context
`${CLAUDE_PLUGIN_ROOT}/cli/dist/spec next {feature}`	Show only next task (minimal output for AI)
`${CLAUDE_PLUGIN_ROOT}/cli/dist/spec mark {feature} {task-id}`	Mark task/subtask complete
`${CLAUDE_PLUGIN_ROOT}/cli/dist/spec validate {path}`	Check spec completeness, task coverage, dependencies
`${CLAUDE_PLUGIN_ROOT}/cli/dist/spec compact {file} [-o out]`	Generate token-optimized version

AI-Optimized CLI Usage

All commands output JSON by default, optimized for programmatic parsing.

Get structured data:

${CLAUDE_PLUGIN_ROOT}/cli/dist/spec status              # All features as JSON
${CLAUDE_PLUGIN_ROOT}/cli/dist/spec resume {feature}    # Progress + next task as JSON
${CLAUDE_PLUGIN_ROOT}/cli/dist/spec next {feature}      # Only next task as JSON
${CLAUDE_PLUGIN_ROOT}/cli/dist/spec validate {path}     # Validation result as JSON

Minimal output for token efficiency:

${CLAUDE_PLUGIN_ROOT}/cli/dist/spec status -q                    # Just feature names + percentages
${CLAUDE_PLUGIN_ROOT}/cli/dist/spec resume {feature} -q          # Just next task ID + files
${CLAUDE_PLUGIN_ROOT}/cli/dist/spec next {feature} --filesOnly   # Just file paths to load

Update progress:

${CLAUDE_PLUGIN_ROOT}/cli/dist/spec mark {feature} {task-id}             # Mark all subtasks complete
${CLAUDE_PLUGIN_ROOT}/cli/dist/spec mark {feature} {task-id} --subtask 0 # Mark first subtask complete

Tool Usage

Tool	When to Use
`AskUserQuestion`	Clarify requirements, resolve ambiguities, get decisions on implementation choices
`Task` with `subagent_type=Explore`	Understand existing codebase, find patterns, discover affected files
`Task` with `subagent_type=Plan`	Design implementation approach for complex phases

Principle: Ask early, explore thoroughly. Use AskUserQuestion before making assumptions about requirements. Use Explore agents before planning to understand what exists.

Best Practices

Spec first - Never implement without written requirements
Small tasks - Each task fits in one context window
Explicit dependencies - Mark what blocks what
Checkpoint often - Save progress every 2-3 tasks
Compact for continuation - Use token-optimized format between sessions
Separate concerns - Spec (what) vs Plan (how) vs Tasks (when)
Version specs - Use git, specs are source of truth

spec-driven-dev