Detailed SDD Walkthrough
Relevant source files
The following files were used as context for generating this wiki page:This document provides a comprehensive walkthrough of the Spec-Driven Development (SDD) process as implemented in the spec-kit project. It details the step-by-step workflow, from project initialization to task generation, using the provided CLI and AI agent commands. The SDD process inverts the traditional development model by making specifications executable artifacts that directly generate implementation plans and code, rather than just guiding them.
The core of this workflow is a series of commands (/specify, /plan, /tasks) that automate the transformation of a high-level feature idea into a structured, actionable development plan. This approach enforces consistency, completeness, and traceability, amplifying developer effectiveness by automating the mechanical translation from specification to implementation.
Sources: spec-driven.md:4-14, 102-106, README.md:19-22
High-Level Workflow
The SDD process is a structured sequence of steps, each facilitated by a specific command. The overall flow ensures that development proceeds from a high-level intent to a detailed, technically-grounded implementation plan before any code is written.
The following diagram illustrates the primary stages of the SDD workflow.
Sources: README.md:25-45, spec-driven.md:108-132
Step 0: Project Initialization
The first step is to bootstrap a new project environment using the specify init command. This command sets up the necessary directory structure and template files.
Sources: README.md:110-113, src/specify_cli/init.py:560-568
specify init Command
The init command is part of the specify_cli tool. It downloads the latest template release from the github/spec-kit repository and configures it for the chosen AI assistant.
The command offers several options to customize the initialization process:
| Option | Alias | Description |
|---|---|---|
--ai | Specifies the AI assistant to use: claude, gemini, or copilot. If not provided, an interactive selection menu is shown. | |
--here | Initializes the project in the current directory instead of creating a new one. | |
--ignore-agent-tools | Skips the check for required AI agent CLI tools (e.g., claude or gemini). | |
--no-git | Skips the automatic initialization of a Git repository. |
Sources: src/specify_cli/init.py:560-567, README.md:123-132
Initialization Flow
The init command follows a sequence of steps to prepare the project, including fetching the template from GitHub, extracting it, and initializing a git repository.
This sequence diagram shows the interactions during the specify init process.
Step 1: Creating the Specification (/specify)
After initialization, the first development command is /specify. It takes a natural language description of a feature and creates a structured specification document.
Example Usage:
/specify Build an application that can help me organize my photos in separate photo albums.
Sources: README.md:31-35, spec-driven.md:110-116
/specify Command Logic
The /specify command automates several setup tasks, ensuring consistency for every new feature.
- Feature Numbering & Branching: It runs the
create-new-feature.shscript, which determines the next sequential feature number (e.g.,003) and creates a semantic Git branch (e.g.,003-photo-organizer). - Directory & File Creation: The script creates a new directory under
specs/(e.g.,specs/003-photo-organizer/) and copies thespec-template.mdinto it asspec.md. - Specification Generation: The AI agent then populates this new
spec.mdfile, translating the user's description into the structured format defined by the template.
Sources: templates/commands/specify.md:8-14, scripts/create-new-feature.sh:34-63
This flowchart details the process executed by the /specify command.
Specification Structure
The generated spec.md is based on templates/spec-template.md. It focuses on the what and why, deliberately avoiding implementation details. Key sections include:
- User Scenarios & Testing: Defines the primary user story, acceptance scenarios, and edge cases.
- Functional Requirements: A list of testable
FR-items (e.g., "System MUST..."). - Key Entities: Describes data concepts without implementation details.
- Review & Acceptance Checklist: A gate to ensure the spec is complete and unambiguous.
The template instructs the AI to use [NEEDS CLARIFICATION: specific question] for any ambiguities, preventing assumptions and forcing clarity.
Sources: templates/spec-template.md:21-22, 44-77
Step 2: Generating the Implementation Plan (/plan)
With a clear specification, the /plan command is used to define the technical approach. The developer provides the tech stack, and the AI generates a detailed implementation plan.
Example Usage:
/plan The application uses Vite with minimal number of libraries. Use vanilla HTML, CSS, and JavaScript.
Sources: README.md:38-41, spec-driven.md:118-124
/plan Command Logic
The /plan command orchestrates the creation of several design artifacts based on the feature specification and the developer's technical input.
- Analyze Spec: It reads the
spec.mdto understand requirements. - Check Constitution: It validates the proposed plan against the project's
memory/constitution.md. - Generate Artifacts: It populates the
plan-template.mdand generates supporting documents.
Sources: templates/commands/plan.md:8-25
The diagram below shows the inputs and outputs of the /plan command.
Step 3: Breaking Down into Tasks (/tasks)
Once the plan is finalized, the /tasks command analyzes all the design documents and generates a detailed, sequential, and parallelizable list of development tasks.
Example Usage:
/tasks
Sources: README.md:43-45, spec-driven.md:126-132
/tasks Command Logic
The /tasks command converts the high-level plan into an executable task list.
- Load Design Docs: It reads
plan.mdand any available supporting documents likedata-model.mdandcontracts/. - Generate Tasks: It creates tasks for setup, tests, core implementation, integration, and polish.
- Apply Rules: It marks tasks that can be run in parallel with
[P](if they affect different files) and enforces a Test-Driven Development (TDD) order. - Output: It writes the final, numbered task list to
tasks.md.
Sources: templates/commands/tasks.md:8-41
Step 4: Implementation and Validation
The final step is the implementation itself. An AI coding agent is instructed to execute the plan.md or the generated tasks.md. The agent will carry out the tasks, create files, and write code.
During this phase, the developer's role shifts to supervision and validation. This includes:
- Running the application to check for runtime errors.
- Copying any browser or CLI errors back to the agent for resolution.
- Ensuring the final implementation meets the acceptance criteria from the original
spec.md.
Sources: README.md:255-269
Conclusion
The Spec-Driven Development walkthrough demonstrates a powerful, structured, and automated approach to software development. By using the spec-kit tooling, teams can ensure that development is tightly aligned with requirements, technical decisions are documented, and the process from idea to implementation is both rapid and consistent. This methodology shifts the focus from writing boilerplate code to defining intent and validating outcomes, leveraging AI to handle the mechanical aspects of coding.
Sources: spec-driven.md:15-18, 222-226