Spec-Driven Development Plugin

A structured workflow plugin for Claude Code that transforms feature ideas into formal specifications before implementation.

Overview

This plugin guides you through three phases:

1. Requirements - User stories with EARS notation and acceptance criteria
2. Design - Technical architecture, sequence diagrams, implementation considerations
3. Tasks - Discrete, trackable implementation items synced to Claude Code todos

Commands

Command	Description
/spec-brainstorm	Brainstorm a feature idea (optionally with domain expert consultants)
/spec <feature-name>	Start a new spec with interactive 3-phase workflow
/spec-import	Import a markdown/PRD file and convert to EARS requirements
/spec-refine	Refine requirements/design for current spec
/spec-tasks	Regenerate tasks from updated spec
/spec-status	Show spec progress, task completion, and dependency status
/spec-sync	Sync tasks.md status back to Claude Code task list
/spec-validate	Validate spec completeness and consistency
/spec-exec	Run one autonomous implementation iteration
/spec-loop	Loop implementation until all tasks complete
/spec-team	Execute with agent team (4 specialized agents)
/spec-accept	Run user acceptance testing for formal sign-off
/spec-docs	Generate documentation from spec and implementation
/spec-release	Generate release notes and deployment checklist
/spec-verify	Run post-deployment smoke tests
/spec-retro	Run a retrospective on a completed spec

Usage

Starting a New Spec

/spec user-authentication

This will:

1. Create .claude/specs/user-authentication/ directory
2. Gather requirements interactively (2-3 rounds of questions)
3. Guide you through Design phase (architecture docs)
4. Generate Tasks and sync to Claude Code todos

Importing from an Existing PRD

/spec-import my-feature --file /path/to/prd.md

Reads a markdown document (PRD, RFC, design doc) and converts it to EARS requirements. Review the output, then proceed to design with /spec-refine.

Spec Files Location

Specs are stored in .claude/specs/<feature-name>/:

.claude/specs/user-authentication/
├── requirements.md   # User stories with acceptance criteria
├── design.md         # Architecture and implementation plan
└── tasks.md          # Trackable implementation tasks

Cross-Spec Dependencies

Specs can declare dependencies on other specs via a ## Depends On section in requirements.md:

## Depends On

- auth-system
- database-migrations

Execution scripts check dependencies before running. A dependency is considered complete when all its tasks are verified. /spec-status shows dependency status.

Execution

After creating a spec, run autonomous implementation:

# single task
spec-exec.sh --spec-name user-authentication

# loop until done
spec-loop.sh --spec-name user-authentication --max-iterations 20

# agent team (Implementer + Tester + Reviewer + Debugger)
spec-team.sh --spec-name user-authentication

Scripts live in the plugin's scripts/ directory. If only one spec exists, --spec-name is auto-detected.

Git Worktree Isolation

By default, execution scripts create a git worktree for each spec:

• Branch: spec/<spec-name>
• Path: .claude/specs/.worktrees/<spec-name>/
• Main branch stays clean while the spec is implemented
• Multiple specs can run in parallel on separate worktrees
• On completion, a gh pr create command is suggested

Use --no-worktree to commit directly to the current branch (v2.x behavior).

Crash Recovery

spec-loop.sh and spec-team.sh create checkpoint commits before each iteration. If Claude crashes or exits non-zero, the branch is rolled back to the last checkpoint automatically.

Task Sync

After running execution scripts, use /spec-sync to update the Claude Code task list from tasks.md. The subprocess can't call TaskUpdate directly, so this reconciliation step keeps the two in sync.

Agent Team Mode

Use spec-team.sh when you need reliable verification. It spawns 4 specialized agents:

• Implementer -- writes code
• Tester -- verifies with Playwright/tests (only they can mark Verified: yes)
• Reviewer -- checks code quality, security, architecture (uses Opus)
• Debugger -- fixes issues when Tester or Reviewer reject

This costs more tokens but prevents tasks from being marked complete without real testing.

Post-Implementation Pipeline

After all tasks are complete, run the post-implementation scripts:

# user acceptance testing (verify requirements are met)
spec-accept.sh --spec-name user-authentication

# generate documentation from spec + code
spec-docs.sh --spec-name user-authentication