Spec-Driven Development Workflow

A structured approach to feature development through four phases: Brainstorm, Requirements, Design, and Tasks. This methodology prevents ad-hoc coding by ensuring proper planning before implementation.

Overview

Spec-driven development transforms vague feature ideas into formal, traceable specifications:

Feature Idea → Brainstorm (Conversation) → Requirements (EARS) → Design (Architecture) → Tasks (Trackable)

Phase 0: Brainstorm

Before formalizing requirements, use /spec-brainstorm to explore the idea through conversation.

When to Brainstorm

You have a vague idea that needs refinement
You're weighing multiple approaches
You want to think through feasibility before committing
The scope isn't clear yet

Brainstorm Workflow

Start with /spec-brainstorm [idea]
Have a back-and-forth conversation exploring the problem
Codex asks probing questions, suggests alternatives, identifies gaps
When the idea is solid, Codex outputs a brief
Use that brief as input for /spec <feature-name>

The brainstorm phase is optional — if you already know exactly what you want, skip straight to /spec.

All new spec files are stored in .claude/specs/<feature-name>/. Existing .codex/specs/<feature-name>/ specs remain supported as a migration fallback:

requirements.md - User stories with EARS acceptance criteria
design.md - Architecture, components, data flow
tasks.md - Implementation tasks tracked by status, wiring, verification, and dependencies

Phase 1: Requirements

Capture WHAT the system should do using EARS (Easy Approach to Requirements Syntax).

EARS Notation

Structure requirements as testable statements:

WHEN [condition/trigger]
THE SYSTEM SHALL [expected behavior]

Examples:

WHEN a user submits a login form with valid credentials
THE SYSTEM SHALL authenticate the user and redirect to dashboard

WHEN a user submits invalid form data
THE SYSTEM SHALL display inline validation errors without page reload

WHEN an API request fails after 3 retries
THE SYSTEM SHALL display a user-friendly error message and log the failure

User Story Format

### US-1: [Story Title]

**As a** [user role]
**I want** [goal/desire]
**So that** [benefit/value]

#### Acceptance Criteria (EARS)

1. WHEN [condition]
   THE SYSTEM SHALL [behavior]

Requirements Phase Workflow

Ask clarifying questions about the feature scope
Identify user roles and their goals
Write user stories with EARS acceptance criteria
Identify non-functional requirements (performance, security, accessibility)
Document out-of-scope items explicitly
List open questions for resolution

For detailed EARS patterns and examples, consult references/ears-notation.md.

Phase 2: Design

Define HOW the system will implement the requirements.

Design Components

Architecture Overview - High-level component diagram
Data Flow - How data moves through the system
Component Specifications - Purpose, responsibilities, interfaces
Data Models - Schemas, types, relationships
API Design - Endpoints, request/response formats
Sequence Diagrams - Key interaction flows

Design Phase Workflow

Review all requirements from Phase 1
Identify major components needed
Define interfaces between components
Design data models and storage
Plan API contracts if applicable
Document security and performance considerations
List alternatives considered with rationale

For detailed design patterns, consult references/design-patterns.md.

Phase 3: Tasks

Break down the design into discrete, trackable implementation tasks.

Task Structure

### T-1: [Task Title]

- **Status**: pending | in_progress | completed
- **Wired**: no | yes | n/a
- **Verified**: no | yes
- **Requirements**: US-1, US-2
- **Description**: [Detailed description]
- **Acceptance**: [How to verify completion]
- **Dependencies**: T-0 | none

Task Breakdown Principles

Single Responsibility - Each task does one thing
Testable - Clear acceptance criteria
Traceable - Links to requirements
Sequenced - Dependencies explicit
Time-boxed - Completable in reasonable scope

Task Phases

Organize tasks into logical phases:

Setup - Project scaffolding, dependencies, configuration
Core Implementation - Main feature functionality
Integration - Connect components, APIs
Testing - Unit, integration, E2E tests
Polish - Error handling, edge cases, cleanup

Tasks Phase Workflow

Review design from Phase 2
Identify discrete implementation units
Sequence tasks based on dependencies
Link each task to requirements
Define acceptance criteria per task
Keep tasks traceable in tasks.md; if the active client has a native todo tool, mirror the task list there.

For detailed task breakdown strategies, consult references/task-breakdown.md.

Phase 4: Execution

After planning is complete, execute the spec autonomously using the provided scripts.

Single Iteration

Run one task at a time:

${CODEX_PLUGIN_ROOT:-$CLAUDE_PLUGIN_ROOT}/scripts/spec-exec.sh --spec-name <name>

Each run picks the highest-priority pending task, implements it, tests it, updates the spec, and commits.

Loop Until Done

Run all tasks in a loop:

${CODEX_PLUGIN_ROOT:-$CLAUDE_PLUGIN_ROOT}/scripts/spec-loop.sh --spec-name <name> --max-iterations 50

The loop re-reads spec files each iteration, detects completion via <promise>COMPLETE</promise>, and stops when all tasks are done.

Execution Commands

Command	Description
`/spec-exec`	Run one implementation iteration
`/spec-loop`	Loop until all tasks complete

Spec File Location

Create specs in the project's .claude/specs/ directory. If an older project already has .codex/specs/, the scripts read that location unless SPEC_ROOT is set:

project/
├── .codex/
│   └── specs/
│       └── user-authentication/
│           ├── requirements.md
│           ├── design.md
│           └── tasks.md
└── src/

Integration with Codex

Creating Specs

Use the /spec <feature-name> command to start a new spec with interactive guidance through all three phases.

Task Synchronization

After completing the Tasks phase, keep tasks.md authoritative and mirror to the active client's todo system when available:

For each task in tasks.md:
  Create or update a todo with subject, description, and dependencies

Auto-Context

When implementing features, include relevant spec files as context. This ensures implementation stays aligned with requirements.

Refinement

Use /spec-refine to update requirements or design. Changes cascade:

Updated requirements → Review design
Updated design → Regenerate tasks

Templates

Templates are available at ${CODEX_PLUGIN_ROOT:-$CLAUDE_PLUGIN_ROOT}/templates/:

requirements.md - Requirements template with EARS format
design.md - Design document template
tasks.md - Task tracking template

Quick Reference

Phase	Focus	Output	Key Question
Requirements	WHAT	User stories + EARS	What should it do?
Design	HOW	Architecture docs	How will it work?
Tasks	WHEN	Task list + todos	What's the sequence?

Additional Resources

Reference Files

For detailed guidance on each phase:

references/ears-notation.md - Complete EARS patterns and examples
references/design-patterns.md - Architecture documentation patterns
references/task-breakdown.md - Task decomposition strategies

Commands

/spec <name> - Start new spec
/spec-refine - Update existing spec
/spec-tasks - Regenerate tasks
/spec-status - View progress
/spec-validate - Validate completeness