Development Phases

The Spec-Driven Development (SDD) process is a structured methodology that inverts the traditional software development lifecycle by making specifications executable artifacts that generate code. This approach is organized into distinct phases, each with a specific focus, set of activities, and automated tooling. The entire workflow is designed to transform a high-level feature idea into a production-ready application through a series of refinement steps.

The development lifecycle is categorized into three overarching types of development, each supported by the core SDD workflow. These categories define the strategic context for a development effort.

Sources: README.md:52-62

Core SDD Workflow

The practical application of SDD is streamlined through three core commands: /specify, /plan, and /tasks. This sequence transforms a natural language requirement into a detailed, executable task list.

The following diagram illustrates the high-level command-driven workflow.

Phase 0: Specification (/specify)

This is the first phase, where a user's high-level feature description is converted into a structured, formal specification. The goal is to define the "what" and "why" of the feature, avoiding any implementation details.

Process Flow

The /specify command initiates this phase by executing the create-new-feature.sh script.

1. Feature Numbering & Branching: The script scans existing specs to determine the next sequential feature number (e.g., 003) and creates a new Git branch (e.g., 003-chat-system).
2. Directory & File Creation: A corresponding directory is created under specs/ (e.g., specs/003-chat-system/), and the spec-template.md is copied into it as spec.md.
3. Specification Generation: An AI agent populates the spec.md file based on the user's input, filling in sections like User Stories, Functional Requirements, and Key Entities.

Sources: spec-driven.md:146-153, templates/commands/specify.md:6-14, scripts/create-new-feature.sh

The diagram below shows the execution flow of the /specify command.

Key Artifact: spec.md

The primary output is the spec.md file, which must adhere to strict guidelines:

• Focus: Describes what users need and why.
• Exclusion: Explicitly avoids implementation details like tech stacks, APIs, or code structure.
• Ambiguity Handling: Any unclear aspects from the user's prompt must be marked with [NEEDS CLARIFICATION: specific question].

Sources: templates/spec-template.md:18-20, 26-28

Phase 1: Planning (/plan)

Once the specification is stable, the /plan command initiates the planning phase. Here, technical decisions are made to translate the "what" from the spec.md into the "how."

Process Flow

1. Input Analysis: The command analyzes the spec.md file and the user-provided technical context (e.g., tech stack, architecture).
2. Constitution Check: The plan is validated against the project's constitution.md to ensure it adheres to core architectural principles (e.g., simplicity, testability).
3. Research (Sub-phase 0): Any NEEDS CLARIFICATION markers in the plan's Technical Context section trigger research tasks. Findings are consolidated in research.md.
4. Design & Contracts (Sub-phase 1): The AI agent generates detailed design documents based on the resolved plan.
5. Task Planning Approach (Sub-phase 2): The plan outlines the strategy for the /tasks command to generate an executable task list.

Sources: templates/plan-template.md:8-17, templates/commands/plan.md:6-23

The diagram below outlines the inputs and outputs of the /plan command.

Key Artifacts

This phase produces a suite of design documents within the feature's specs/ directory:

• plan.md: The central planning document detailing technical context, decisions, and the multi-phase execution flow.
• research.md: Contains findings on technology choices, best practices, and resolutions for any ambiguities.
• data-model.md: Defines data entities, fields, relationships, and validation rules.
• contracts/: Directory containing API specifications, such as OpenAPI schemas or GraphQL definitions.
• quickstart.md: A guide with key validation scenarios derived from user stories, used for testing.

Sources: templates/plan-template.md:86-92, 110-126

Phase 2: Task Generation (/tasks)

With a complete implementation plan and design artifacts, the /tasks command breaks the work down into a granular, ordered list of executable tasks.

Process Flow

1. Prerequisite Check: The check-task-prerequisites.sh script verifies that plan.md exists and identifies other available design documents (data-model.md, contracts/, etc.).
2. Task Derivation: The command analyzes all available design documents to generate tasks.
   • contracts/ files lead to contract test tasks.
   • data-model.md entities lead to model creation tasks.
   • User stories from spec.md (via plan.md) lead to integration test tasks.
3. Ordering and Parallelization: Tasks are ordered according to a strict Test-Driven Development (TDD) sequence: tests are always created before the implementation code that makes them pass. Independent tasks are marked with [P] to indicate they can be executed in parallel.
4. Output: The final list is written to tasks.md.

Sources: templates/tasks-template.md:8-22, templates/commands/tasks.md:6-37, scripts/check-task-prerequisites.sh

Key Artifact: tasks.md

The tasks.md file is the final output before implementation begins. It contains a numbered list of tasks with specific instructions and file paths.

Task Generation Rules:

• TDD Enforcement: Tests must be written and fail before any implementation work begins.
• Dependency Order: Tasks are structured to respect dependencies (e.g., models before services, services before API endpoints).
• Parallelism: Tasks that modify different files and have no dependencies are marked [P] for parallel execution.

An example task list structure:

# Tasks: [FEATURE NAME]

## Phase 3.2: Tests First (TDD) ⚠️ MUST COMPLETE BEFORE 3.3
- [ ] T004 [P] Contract test POST /api/users in tests/contract/test_users_post.py
- [ ] T005 [P] Contract test GET /api/users/{id} in tests/contract/test_users_get.py

## Phase 3.3: Core Implementation (ONLY after tests are failing)
- [ ] T008 [P] User model in src/models/user.py
- [ ] T011 POST /api/users endpoint

Sources: templates/tasks-template.md:36-49, 90-100

Phase 3+: Implementation & Validation

These phases are beyond the scope of the planning and tasking commands but are the logical next steps in the development lifecycle.

• Phase 3: Task Execution: An AI agent or a developer executes the tasks listed in tasks.md in the specified order.
• Phase 4: Implementation: The agent writes the code to make the failing tests pass, following the constitutional principles.
• Phase 5: Validation: The completed feature is validated by running all tests, executing the quickstart.md scenarios, and checking performance goals.

Sources: templates/plan-template.md:144-147, README.md:288-300