Spec-Driven Development

Structure complex features through a four-phase workflow: requirements, planning, blueprint, and build. Each phase produces a durable artifact that becomes the contract between discovery and implementation.

When to Use Specs

Use the specs plugin when:

• Non-trivial features — Multiple files, unclear scope, or significant architectural decisions required
• Multi-step workflows — You want to confirm understanding before writing code
• Clarity before code — Requirements, trade-offs, and implementation approach need explicit documentation

Skip specs for:

• Small bug fixes or single-file changes
• Exploratory work where you're still learning the problem
• Tasks where the approach is obvious and uncontested

The Four Phases

Phase 1: Requirements (/specs:prd)

Capture what you're building and why. A Socratic interview process uncovers the real problem, success criteria, scope boundaries, and constraints.

Output: .agents/specs/<feature>/1-prd.md

The PRD includes:

• Problem statement
• User stories
• Acceptance criteria (testable, specific)
• Scope (in/out, explicitly bounded)
• Constraints and assumptions
• Open questions

Phase 2: Planning (/specs:plan)

Evaluate alternatives and make defensible architectural decisions. No code yet — focus on WHAT and WHY, not HOW.

Output: .agents/specs/<feature>/2-plan.md

The plan includes:

• Problem statement (from PRD, briefly)
• Approach in plain language
• Alternatives considered and why they were rejected
• Key decisions with rationale
• Scope and affected areas
• Risks and mitigations
• Implementation phases

Phase 3: Blueprint (/specs:blueprint)

Translate the plan into a concrete implementation roadmap. File structure, skeletal pseudo-code, task checklist, and dependencies.

Output: .agents/specs/<feature>/3-blueprint.md

The blueprint includes:

• File structure tree with [A] Add, [M] Modify, [D] Delete markers
• Mermaid diagrams for complex flows
• Skeletal pseudo-code (~10-20 lines per component)
• Task checklist by phase
• Dependencies and integration points
• Constraints from the PRD

Phase 4: Build (/specs:build)

Execute the blueprint using parallel code-writer agents. The blueprint drives task dispatch and success criteria from the plan verify completion.

Each agent:

1. Reads the blueprint for the task
2. Implements one or more files
3. Reports completion and any blockers

Build orchestrates phases in order and verifies success criteria before declaring completion.

Artifact Structure

Each spec lives in .agents/specs/<feature>/ with three files. Use kebab-case for folder names (e.g., user-onboarding-flow):

.agents/specs/
└── user-onboarding-flow/
    ├── 1-prd.md         # Requirements: problem, scope, success criteria
    ├── 2-plan.md        # Architecture: decisions, alternatives, phases
    └── 3-blueprint.md   # Implementation: files, tasks, pseudo-code

These artifacts are durable — they survive the implementation and serve as design documentation for future changes to the feature.

Invoking Specs

Start a new spec from scratch:

/specs:prd
# → Socratic interview
# → Creates .agents/specs/<feature>/1-prd.md
# → Asks: Ready to plan?

Continue from an existing PRD:

/specs:plan
# → Reads .agents/specs/<feature>/1-prd.md
# → Explores codebase and similar patterns
# → Creates .agents/specs/<feature>/2-plan.md

Continue from an existing plan:

/specs:blueprint
# → Reads .agents/specs/<feature>/2-plan.md
# → Creates .agents/specs/<feature>/3-blueprint.md
# → Asks: Ready to build?

Execute the blueprint:

/specs:build
# → Spawns parallel code-writer agents
# → Tracks task completion by phase
# → Verifies success criteria from the plan
# → Reports when implementation is complete

Key Principles

Separate concerns: Requirements → Architecture → Implementation. Each phase has a clear input and output. Don't decide implementation details during planning.

Document decisions: Every decision in the plan includes rationale. This prevents re-litigating choices later.

Durable artifacts: Each spec produces markdown files stored in git. Future changes to the feature can reference the original design intent.

User checkpoints: After each phase, you're asked to confirm before proceeding. This prevents costly misalignments.

Related

• Component Model — How commands, skills, and agents interact
• Skill Activation — How Claude discovers and uses specs skills
• Plugins Overview — The broader plugin architecture