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:

Developer has an idea
Developer writes code
Developer writes documentation (maybe)
Requirements drift as understanding evolves

Spec-driven development:

Developer writes specification
Specification is reviewed and refined
Implementation follows specification
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 the repository root checkout)                  │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  /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 next --agent <agent> --mission <slug>               │
│    → Agent A: spec-kitty agent action implement WP01 --agent A  │
│    → Agent B: spec-kitty agent action implement WP02 --agent B  │
│    → Agent C: spec-kitty agent action implement WP03 --agent C  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                      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.

Planning location and branch intent are separate. The planning phase runs in the repository root checkout, while the mission target branch can be the current branch or an explicit branch chosen during mission creation.

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:

Developer A implements feature foundation
Developer B waits for A to finish
Developer B implements dependent feature
(Repeat)

Spec-driven development with Spec Kitty enables parallel work:

Specification defines all work packages upfront
Dependencies between WPs are explicit
Independent WPs can be implemented simultaneously
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

Table of Contents