Quick Start Guide

This guide provides a step-by-step walkthrough for getting started with spec-kit and the Spec-Driven Development (SDD) methodology. SDD is a process that inverts traditional development by making specifications executable, directly generating working implementations rather than just guiding them. The core philosophy emphasizes intent-driven development, multi-step refinement, and a heavy reliance on AI model capabilities.

The goal is to allow organizations to focus on product scenarios rather than writing undifferentiated code. This guide will cover setting up your project and using the core commands to build software. For a deeper dive into the methodology, see the Complete Spec-Driven Development Methodology.

Sources: README.md:1-12, 23-26, 50-56, spec-driven.md:3-12

Prerequisites

Before you begin, ensure you have the following tools installed on a Linux/macOS system (or WSL2 on Windows):

• Python 3.11+
• uv for package management
• Git
• An AI coding agent, such as:
  • Claude Code
  • GitHub Copilot
  • Gemini CLI

Sources: README.md:82-88, CONTRIBUTING.md:12-15

1. Project Initialization

The first step is to initialize your project using the specify CLI. This tool bootstraps your environment with the required artifacts for the SDD workflow.

Sources: README.md:30-32, 110-112

The specify init Command

Run the init command to create a new project or set up spec-kit in an existing directory.

# Create a new project directory
uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>

# Or initialize in the current directory
uvx --from git+https://github.com/github/spec-kit.git specify init --here

The CLI will prompt you to select your AI agent. You can also specify it directly with the --ai flag.

Sources: README.md:31, src/specify_cli/init.py:608-610, 687-692

The init command performs several actions, as illustrated in the diagram below.

This diagram shows the sequence of events when a user runs the specify init command.

Command Options

The init command supports several options to customize its behavior.

Sources: src/specify_cli/init.py:609-614

2. The Spec-Driven Development Workflow

The SDD workflow is a structured, multi-phase process that transforms a high-level idea into an implemented feature. It revolves around three core commands: /specify, /plan, and /tasks.

This diagram provides a high-level overview of the entire Spec-Driven Development workflow.

Step 2.1: Create the Specification (/specify)

The workflow begins with the /specify command. You provide a natural language description of the feature you want to build, focusing on the what and why, not the technical implementation.

Example:

/specify Build an application that can help me organize my photos in separate photo albums. Albums are grouped by date and can be re-organized by dragging and dropping on the main page.

This command triggers a script that:

1. Determines the next sequential feature number (e.g., 001, 002).
2. Creates a new Git branch with a semantic name (e.g., 001-photo-organizer).
3. Creates a feature directory (e.g., specs/001-photo-organizer/).
4. Generates a spec.md file inside this directory from a template, populating it with details from your description.

Sources: README.md:34-38, spec-driven.md:152-160, templates/commands/specify.md:6-14, scripts/create-new-feature.sh

The generated spec.md is structured to capture user stories, functional requirements, and acceptance criteria while explicitly avoiding implementation details.

Sources: templates/spec-template.md

Step 2.2: Create the Technical Plan (/plan)

Once the specification is drafted and refined, use the /plan command to define the technical approach. Here, you specify the how: the technology stack, architecture, and other implementation details.

Example:

/plan The application uses Vite with minimal number of libraries. Use vanilla HTML, CSS, and JavaScript as much as possible. Images are not uploaded anywhere and metadata is stored in a local SQLite database.

The /plan command analyzes the spec.md and your technical input to generate a comprehensive implementation plan.

This diagram shows the execution flow of the /plan command.

This process produces several key artifacts in the feature directory:

• plan.md: The main implementation plan.
• research.md: Documents research on technology choices.
• data-model.md: Defines data structures.
• contracts/: Contains API specifications (e.g., OpenAPI).
• quickstart.md: A guide for validation.

Sources: README.md:40-43, 185-199, spec-driven.md:162-170, templates/plan-template.md:82-88

Step 2.3: Generate Tasks (/tasks)

With a detailed plan in place, the /tasks command breaks it down into a list of discrete, actionable implementation steps.

Example:

/tasks

This command reads the plan.md and other design documents to generate a tasks.md file.

This diagram illustrates the logic of the /tasks command.

The resulting tasks.md file contains a numbered list of tasks, ordered by dependency and marked for parallel execution where possible. This list is designed to be directly executable by an AI agent or a developer.

Sources: README.md:45-46, spec-driven.md:172-179, templates/tasks-template.md

3. Implementation and Iteration

After tasks.md is generated, the final step is implementation. You can instruct your AI agent to execute the plan.

Example:

implement specs/001-photo-organizer/plan.md

The agent will follow the steps in tasks.md to write the code, run tests, and build the feature. The SDD process is iterative; you can refine the specification or plan at any time and regenerate the subsequent artifacts to keep the implementation in sync with the requirements.

Sources: README.md:253-255, spec-driven.md:52-57