Concepts: Understanding Spec-Driven Development

What is Spec-Driven Development?

Spec-Driven Development (SDD) is a methodology for managing AI-assisted development workflows. It provides structure and determinism to the inherently fluid process of working with AI coding assistants.

Core Principles

Specifications as Source of Truth: Work items are defined in structured markdown files organized in a specs/ directory hierarchy.
Deterministic Status: Item status (OPEN, IN PROGRESS, DONE) is determined by filesystem state, not LLM interpretation.
Hierarchical Organization: Work is organized into capabilities → features → stories, enabling clear scope and progress tracking.
Session Continuity: Context handoffs enable seamless work continuation across sessions and agents.

Work Item Hierarchy

1Capability
2└── Feature
3    └── Story
4        └── Tests

Capability: A high-level business capability (e.g., “Core CLI”)
Feature: A specific feature within a capability (e.g., “Pattern Matching”)
Story: An implementable unit of work (e.g., “Parse capability names”)
Tests: Verification that the story is complete

Status Determination

Status flows from the filesystem, providing instant, deterministic classification:

State	Condition
OPEN	No `tests/` directory, or empty `tests/`
IN PROGRESS	`tests/` directory has files, but no `DONE.md`
DONE	`tests/DONE.md` exists

This simple convention means status checks take milliseconds, not minutes.

BSP Numbering

Work items use Binary Space Partitioning numbers for easy ordering and insertion:

121, 32, 43, 54, 65, 76, 87...

To insert between 21 and 32, use 27 (midpoint). This allows unlimited insertion without renumbering.

Directory Structure

 1project/
 2├── specs/
 3│   ├── backlog/          # Future work
 4│   ├── doing/            # Active work
 5│   │   └── capability-21_core-cli/
 6│   │       ├── core-cli.capability.md
 7│   │       └── feature-21_pattern-matching/
 8│   │           ├── pattern-matching.feature.md
 9│   │           └── story-21_parse-names/
10│   │               ├── parse-names.story.md
11│   │               └── tests/
12│   │                   └── DONE.md
13│   └── done/             # Completed work
14└── .spx/
15    └── sessions/         # Handoff sessions

Session Management

Sessions enable context preservation across work boundaries:

Handoff: Save current context with priority
Pickup: Resume the highest-priority session
Release: Return session to queue without completing

This creates a priority queue of work items that agents can pick up and continue.

Integration with Claude Code

The SPX-Claude marketplace provides plugins that understand this structure:

/handoff command creates sessions
/pickup command resumes sessions
Skills like /coding-typescript follow the spec structure
/writing-prd and /writing-trd create specifications

Together, the CLI and plugins form a complete workflow for AI-assisted development.