Home
Relevant source files
The following files were used as context for generating this wiki page:Spec-kit is a project that enables Spec-Driven Development (SDD), a methodology that inverts the traditional software development process. Instead of specifications being temporary guides for writing code, SDD makes specifications executable artifacts that directly generate working implementations. This approach aims to bridge the gap between intent and implementation, allowing organizations to focus on product scenarios rather than undifferentiated code.
The core of spec-kit is a structured, multi-step refinement process powered by AI agents and a set of commands (/specify, /plan, /tasks). This process transforms high-level feature descriptions into detailed, executable task lists, ensuring consistency and adherence to architectural principles. The entire workflow is designed around specifications as the central source of truth, with code being a continuously regenerated output.
Sources: README.md:7-10, spec-driven.md:5-13
Core Philosophy
Spec-Driven Development is founded on a set of key principles that guide the entire workflow:
- Intent-Driven Development: The process starts with the "what" and "why" of a feature, captured in a high-level specification, before defining the "how" of implementation.
- Executable Specifications: Specifications are not just documents; they are precise, complete, and unambiguous inputs that are capable of generating code.
- Multi-step Refinement: Rather than one-shot code generation, SDD uses a phased approach (specify, plan, task) to iteratively refine an idea into a concrete implementation plan.
- Constitutional Foundation: A project
constitutiondefines immutable architectural principles that every generated implementation must follow, ensuring quality and consistency. - Branching for Exploration: The methodology supports generating multiple implementation approaches from a single specification to explore different technology stacks, architectures, or UX patterns.
Sources: README.md:46-52, spec-driven.md:83-95, memory/constitution.md
The SDD Command Workflow
The spec-kit workflow is orchestrated through three primary commands used within an AI coding agent. These commands automate the process of turning a feature idea into an executable plan.
This diagram illustrates the high-level interaction between a user, the AI agent, and the spec-kit scripts.
Step 1: Specification (/specify)
The workflow begins with the /specify command, which takes a natural language description of a feature and creates a structured, non-technical specification.
The following diagram shows the flow for the /specify command.
This process is guided by templates/spec-template.md, which ensures the output focuses on user stories, functional requirements, and acceptance criteria while explicitly avoiding implementation details. Any ambiguities are marked with [NEEDS CLARIFICATION].
Sources: README.md:30-34, spec-driven.md:103-111, templates/spec-template.md, scripts/create-new-feature.sh, templates/commands/specify.md
Step 2: Planning (/plan)
Once the specification is ready, the /plan command translates the "what" from spec.md into the "how." The user provides technical context, such as the desired tech stack.
The diagram below outlines the planning phase.
This phase uses templates/plan-template.md to generate a comprehensive set of documents, including a data model, API contracts, and research notes. A critical step is the Constitution Check, which validates the plan against the project's architectural rules defined in memory/constitution.md.
Sources: README.md:36-38, spec-driven.md:113-121, templates/plan-template.md, templates/commands/plan.md
Step 3: Task Generation (/tasks)
The final command, /tasks, analyzes the implementation plan and its associated design documents to produce a detailed, ordered list of executable tasks.
The task generation process is shown below.
This step is guided by templates/tasks-template.md. It enforces a Test-Driven Development (TDD) workflow by ordering test creation tasks before implementation tasks. It also identifies tasks that can be worked on in parallel, marked with [P], to improve efficiency.
Sources: README.md:40-42, spec-driven.md:123-130, templates/tasks-template.md, templates/commands/tasks.md
Development Phases
The SDD methodology is applicable across the entire software lifecycle, from initial creation to iterative updates.
| Phase | Focus | Key Activities |
|---|---|---|
| 0-to-1 Development ("Greenfield") | Generate from scratch | Start with high-level requirements, generate specifications, plan implementation, and build applications. |
| Creative Exploration | Parallel implementations | Explore diverse solutions, support multiple tech stacks, and experiment with different architectures or UX patterns. |
| Iterative Enhancement ("Brownfield") | Brownfield modernization | Add features iteratively, modernize legacy systems, and adapt existing processes. |
Sources: README.md:55-66
The Constitutional Foundation
A core component of spec-kit is the project constitution, located at memory/constitution.md. This document defines a set of non-negotiable principles that govern all development to ensure consistency, simplicity, and quality.
Key articles from the constitution include:
- Library-First Principle: Every feature must begin as a standalone, reusable library.
- CLI Interface Mandate: Every library must expose its functionality through a command-line interface for testability and observability.
- Test-First Imperative: All implementation must follow a strict Red-Green-Refactor TDD cycle. No implementation code is written before failing tests are approved.
- Simplicity: The system should start simple, with a minimal project structure, and avoid premature abstractions or over-engineering.
These principles are enforced automatically during the /plan phase through "gates" defined in the plan-template.md. Any deviation from the constitution must be explicitly justified.
Sources: spec-driven.md:195-257, memory/constitution.md, templates/plan-template.md:41-69
Getting Started
To begin using spec-kit, you need the following prerequisites installed:
- Linux/macOS (or WSL2 on Windows)
- An AI coding agent (Claude Code, GitHub Copilot, or Gemini CLI)
uvfor package management- Python 3.11+
- Git
You can initialize a new project with the specify CLI:
uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>
This command bootstraps your project with the necessary templates and scripts to start using the /specify, /plan, and /tasks commands within your chosen AI agent.
Sources: README.md:78-85, README.md:100-102, CONTRIBUTING.md:10-14