spec-kitty

Spec-Driven Development Explained

Spec-driven development is the methodology at the heart of Spec Kitty. This document explains what it is, why it matters, and when to use it.

What is Spec-Driven Development?

Spec-driven development is an approach where you write a detailed specification before writing any code. The specification becomes the source of truth that guides implementation.

Traditional development:

1. Developer has an idea
2. Developer writes code
3. Developer writes documentation (maybe)
4. Requirements drift as understanding evolves

Spec-driven development:

1. Developer writes specification
2. Specification is reviewed and refined
3. Implementation follows specification
4. Documentation already exists (the spec)

The key insight: AI agents need clear, unambiguous requirements to produce quality output. Specifications provide that clarity.

Why Spec-First?

AI Agents Need Clear Requirements

Human developers can fill in gaps, ask clarifying questions mid-task, and use intuition. AI agents work better with explicit requirements:

• Ambiguity causes inconsistency: “Make the button look better” produces different results each time
• Specifications reduce rework: “Button: 44px height, #007AFF background, 12px border-radius” produces consistent results
• Context is bounded: AI agents work within context windows; specifications provide focused context

Specifications Become Executable

In Spec Kitty, specifications aren’t just documentation—they drive the workflow:

• /spec-kitty.specify creates the spec
• /spec-kitty.plan creates implementation plan from the spec
• /spec-kitty.tasks generates work packages from the plan
• Each work package references back to the spec

The specification is the contract that all agents follow.

Reduces Rework and Misunderstanding

When multiple agents (or humans) work on a feature:

• Without spec: Each person interprets requirements differently
• With spec: Everyone references the same document

This becomes critical in parallel development where multiple AI agents implement different work packages simultaneously.

The Spec-Kitty Workflow

┌─────────────────────────────────────────────────────────────────┐
│                     PLANNING PHASE                              │
│                  (in main repository)                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  /spec-kitty.specify     →    Creates spec.md                   │
│         ↓                                                       │
│  /spec-kitty.plan        →    Creates plan.md                   │
│         ↓                                                       │
│  /spec-kitty.tasks       →    Creates tasks/WP01.md, etc.       │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                   IMPLEMENTATION PHASE                          │
│                (in separate worktrees)                          │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  spec-kitty implement WP01   →   Agent A implements WP01        │
│  spec-kitty implement WP02   →   Agent B implements WP02        │
│  spec-kitty implement WP03   →   Agent C implements WP03        │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                      REVIEW PHASE                               │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  /spec-kitty.review          →   Check implementation vs spec   │
│  /spec-kitty.accept          →   Approve and merge              │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Each phase produces artifacts that feed into the next phase.

How It Differs from Traditional Development

Aspect	Traditional	Spec-Driven
Requirements	Often implicit, evolve during coding	Explicit, written upfront
Documentation	Written after implementation (often skipped)	Built into the process
Parallelization	Difficult without clear boundaries	Natural work package boundaries
AI-assisted development	Agents need context each time	Agents reference specifications
Rework	Common when requirements misunderstood	Reduced by upfront clarity
Scope creep	Easy to add “just one more thing”	Spec defines boundaries

When to Use Spec-Driven Development

Good Fit

Features with clear boundaries:

• “Add user authentication with OAuth”
• “Implement shopping cart functionality”
• “Create admin dashboard”

Multi-agent or team projects:

• Multiple AI agents working in parallel
• Human + AI collaboration
• Distributed teams

Non-trivial features:

• More than one work package
• Requires architectural decisions
• Has integration points with existing code

Poor Fit

Exploratory work:

• Prototyping where requirements are unknown
• Research tasks (use Deep Research Kitty instead)
• “Try different approaches and see what works”

Simple one-off changes:

• Fix a typo
• Update a single constant
• Minor refactoring

Emergency fixes:

• Production is down
• Security patch needed immediately
• (Write the spec after, for documentation)

The Three Phases in Detail

Phase 1: Specification

The specification answers: What are we building and why?

A good spec includes:

• Problem statement: What problem does this solve?
• User stories: Who benefits and how?
• Requirements: What must the solution do?
• Non-requirements: What is explicitly out of scope?
• Success criteria: How do we know we’re done?

Phase 2: Planning

The plan answers: How will we build it?

A good plan includes:

• Technical approach: Architecture and design decisions
• Work package breakdown: Discrete units of work
• Dependencies: What must be built first?
• Risks and mitigations: What could go wrong?

Phase 3: Implementation

Implementation answers: Building the actual solution.

Each work package:

• References the spec and plan
• Has clear acceptance criteria
• Can be implemented independently
• Gets reviewed against the spec

Why Specifications Enable Parallelization

Traditional development often becomes serial:

1. Developer A implements feature foundation
2. Developer B waits for A to finish
3. Developer B implements dependent feature
4. (Repeat)

Spec-driven development with Spec Kitty enables parallel work:

1. Specification defines all work packages upfront
2. Dependencies between WPs are explicit
3. Independent WPs can be implemented simultaneously
4. Each agent has clear scope boundaries

Example: A feature with 5 work packages:

• Sequential: 5 time units
• With Spec Kitty (2 parallel, 3 sequential): 3 time units

See Also

• Workspace-per-WP Model - How isolation enables parallelization
• Kanban Workflow - How work moves through lanes
• Mission System - Different workflows for different needs

---

This document explains the “why” behind spec-driven development. For “how” to create specifications, see the tutorials and how-to guides.

Try It

• Claude Code Integration
• Claude Code Workflow

How-To Guides

• Install Spec Kitty
• Use the Dashboard

Reference

• CLI Commands
• Slash Commands

This site is open source. Improve this page.