Quick Start Tutorial

Relevant source files

• README.md
• src/specify_cli/__init__.py

Purpose and Scope

This tutorial walks you through creating your first Spec Kit project from initialization to working implementation. You will execute the complete Spec-Driven Development workflow, creating a simple application to understand how specifications transform into running code through the /speckit.* command sequence.

For detailed installation instructions, see Installation and Setup. For comprehensive coverage of the SDD methodology and advanced features, see Spec-Driven Development Workflow and its subsections.

---

Prerequisites Verification

Before beginning, verify your environment meets the requirements:

This command executes `check_tool()` for each required tool and displays their availability status using the `StepTracker` rendering system.

Required:

• Git (for branch management)
• Python 3.11+ (for CLI execution)
• One supported AI agent (Claude Code, Gemini CLI, GitHub Copilot, etc.)

The `AGENT_CONFIG` dictionary defines metadata for all 17 supported agents, including whether they require CLI tools (requires_cli field) or are IDE-based.

Sources: src/specify_cli/__init__.py1282-1321 src/specify_cli/__init__.py484-513

---

Project Initialization

Bootstrap a New Project

Initialize a project in a new directory:

Or initialize in your current directory:

The `init()` command performs these operations:

Step	Action	Code Reference
Tool Detection	Validates Git availability	src/specify_cli/__init__.py1076-1079
Agent Selection	Interactive selection via `select_with_arrows()` or --ai flag	src/specify_cli/__init__.py1081-1093
Script Type Selection	Chooses bash (.sh) or PowerShell (.ps) variants	src/specify_cli/__init__.py1113-1125
Template Download	Fetches agent-specific template ZIP via `download_template_from_github()`	src/specify_cli/__init__.py1163
Extraction	Unpacks template using `download_and_extract_template()`	src/specify_cli/__init__.py751-898
Permissions	Sets execute bits on .sh scripts via `ensure_executable_scripts()`	src/specify_cli/__init__.py1165
Constitution Setup	Copies constitution-template.md to memory/ via `ensure_constitution_from_template()`	src/specify_cli/__init__.py1167
Git Initialization	Creates repository with initial commit via `init_git_repo()`	src/specify_cli/__init__.py1170-1183

The `StepTracker` provides live progress updates during initialization, with each step tracked via .add(), .start(), .complete(), and .error() methods.

Sources: src/specify_cli/__init__.py981-1269 src/specify_cli/__init__.py751-898

---

Initialization Process Flow

Sources: src/specify_cli/__init__.py981-1269 src/specify_cli/__init__.py1156-1203

---

Project Structure After Initialization

The `download_and_extract_template()` function creates this structure:

todo-app/
├── .specify/
│   ├── memory/
│   │   └── constitution.md          # Copied from constitution-template.md
│   ├── scripts/
│   │   ├── create-new-feature.sh    # Branch and spec directory creation
│   │   ├── update-agent-context.sh  # Updates CLAUDE.md with tech stack
│   │   ├── check-prerequisites.sh   # Validates required tools
│   │   └── common.sh                # Shared utility functions
│   ├── templates/
│   │   ├── spec-template.md         # Specification structure
│   │   ├── plan-template.md         # Implementation plan structure
│   │   ├── tasks-template.md        # Task breakdown structure
│   │   └── constitution-template.md # Constitutional principles template
│   └── specs/                       # Created during /speckit.specify
│       └── 001-feature-name/
│           ├── spec.md
│           ├── plan.md
│           ├── tasks.md
│           └── contracts/           # API specifications
├── .claude/                         # For Claude Code agent
│   └── commands/
│       ├── constitution.md          # /speckit.constitution command
│       ├── specify.md               # /speckit.specify command
│       ├── plan.md                  # /speckit.plan command
│       ├── tasks.md                 # /speckit.tasks command
│       └── implement.md             # /speckit.implement command
└── CLAUDE.md                        # Agent context file with project info

The exact agent directory (.claude/, .gemini/, .github/, etc.) depends on the selected AGENT_CONFIG[ai_assistant]["folder"] value.

Sources: src/specify_cli/__init__.py751-898 README.md440-459

---

Spec-Driven Development Workflow

Command-to-Artifact Mapping

Sources: README.md246-269 README.md390-615

---

Step-by-Step Example: Building a TODO Application

Step 1: Establish Project Principles

Navigate to the project directory and launch your AI agent (e.g., claude). Execute:

What Happens:

1. Agent reads `templates/constitution-template.md`
2. Agent writes or updates `.specify/memory/constitution.md`
3. File contains 9 Articles defining architectural principles

The constitution enforces constraints like:

• Article VII (Simplicity Gate): Projects should use ≤3 separate deployable units
• Article VIII (Anti-Abstraction): Use framework features directly, avoid premature abstraction layers
• Article IX (Integration-First Testing): Test with real dependencies, not mocks

Sources: README.md93-101 README.md390-404

---

Step 2: Create Feature Specification

Execute the specification command with your feature description:

What Happens:

1. Agent executes `create-new-feature.sh` which:

   • Determines next feature number (e.g., 001)
   • Creates branch 001-todo-app
   • Creates directory .specify/specs/001-todo-app/

2. Agent reads `templates/spec-template.md` to understand structure

3. Agent writes `.specify/specs/001-todo-app/spec.md` containing:

   • Feature overview and objectives
   • User stories with acceptance criteria
   • Functional requirements organized by category
   • Non-functional requirements
   • Out-of-scope items
   • [NEEDS CLARIFICATION] markers for ambiguous areas

Example spec.md structure:

Section	Purpose	Template Enforcement
Feature Overview	High-level summary	Required by spec-template.md
User Stories	As a [user], I want [action], So that [benefit]	Structured format enforced
Functional Requirements	Technical capabilities organized by category	Must be testable and specific
Non-Functional Requirements	Performance, security, accessibility	Quantifiable metrics required
Review Checklist	Validation criteria	Agent marks items as complete/incomplete

Sources: README.md406-438 templates/spec-template.md

---

Step 3: Clarify Underspecified Areas (Optional but Recommended)

Before planning, resolve any [NEEDS CLARIFICATION] markers:

What Happens:

1. Agent scans spec.md for clarification markers
2. Asks structured questions about ambiguous requirements
3. Updates spec.md with clarifications in a dedicated section
4. Removes [NEEDS CLARIFICATION] markers

This step prevents rework during planning and implementation by addressing ambiguities early.

Sources: README.md462-488

---

Step 4: Create Technical Implementation Plan

Specify your technology stack:

What Happens:

1. Constitutional Validation: Agent reads `.specify/memory/constitution.md` and validates plan against principles

2. Planning Artifacts: Agent reads `templates/plan-template.md` and creates:

   • `.specify/specs/001-todo-app/plan.md` - Core implementation plan with phases
   • `.specify/specs/001-todo-app/data-model.md` - Data structures and schemas
   • `.specify/specs/001-todo-app/contracts/` - API specifications (if applicable)

3. Context Update: Agent executes `update-agent-context.sh` which:

   • Parses tech stack from plan.md
   • Updates CLAUDE.md (or equivalent agent file) with project dependencies
   • Ensures subsequent commands have current context

plan.md structure:

Sources: README.md490-529 templates/plan-template.md

---

Step 5: Generate Task Breakdown

Convert the plan into executable tasks:

What Happens:

1. Agent reads `plan.md` and `data-model.md`
2. Agent reads `templates/tasks-template.md` for structure
3. Agent writes `.specify/specs/001-todo-app/tasks.md` with:
   • Numbered tasks with file paths
   • Dependency ordering
   • [P] markers for parallel execution
   • Checkpoints for incremental validation

tasks.md example:

Tasks are ordered to respect dependencies (e.g., storage layer before UI, tests before implementation if TDD is specified in plan).

Sources: README.md576-594 templates/tasks-template.md

---

Step 6: Execute Implementation

Run the implementation command:

What Happens:

1. Prerequisite Validation: Agent verifies existence of:

   • .specify/memory/constitution.md
   • .specify/specs/NNN-feature-name/spec.md
   • .specify/specs/NNN-feature-name/plan.md
   • .specify/specs/NNN-feature-name/tasks.md

2. Task Execution: Agent processes tasks.md sequentially:

   • Executes local CLI commands (e.g., npm install, dotnet new)
   • Generates code files based on plan specifications
   • Runs tests to validate each checkpoint
   • Respects [P] markers for potential parallelization

3. Progress Tracking: Agent reports completion of each task and checkpoint

4. Error Handling: If a task fails, agent reports error context and awaits correction

Implementation output:

✓ Task 1: Created src/storage.js with localStorage wrapper
✓ Task 2: Created tests/storage.test.js with 8 test cases
✓ Checkpoint: All storage tests pass
✓ Task 3: Created index.html with semantic structure
✓ Task 4: Created src/ui.js with rendering functions
✓ Task 5: Created src/app.js with event wiring
✓ Checkpoint: Manual test - add/delete/complete tasks works

Sources: README.md596-615 README.md259-264

---

Complete Workflow Sequence

Sources: README.md390-615 Diagram 2 from high-level system architecture

---

File Evolution Timeline

Command	Files Created/Modified	Purpose
specify init	.specify/memory/constitution.md .specify/scripts/*.sh .specify/templates/*.md .claude/commands/*.md CLAUDE.md	Bootstrap project structure with templates, scripts, and agent commands
/speckit.constitution	.specify/memory/constitution.md	Define architectural principles and constraints
/speckit.specify	.specify/specs/001-feature-name/spec.md Branch: 001-feature-name	Create feature specification with user stories and requirements
/speckit.clarify	.specify/specs/001-feature-name/spec.md	Add clarifications section to resolve ambiguities
/speckit.plan	.specify/specs/001-feature-name/plan.md .specify/specs/001-feature-name/data-model.md .specify/specs/001-feature-name/contracts/ CLAUDE.md (updated)	Create implementation plan, data models, API contracts; update agent context
/speckit.tasks	.specify/specs/001-feature-name/tasks.md	Generate ordered task breakdown with dependencies
/speckit.implement	src/**/* tests/**/* Application code	Generate implementation files according to task plan

Sources: README.md440-528

---

Verification and Testing

After /speckit.implement completes:

1. Verify Artifact Completeness

Check that all expected files exist:

2. Run Tests

If tests were included in the task plan:

3. Manual Testing

Execute the application and validate functionality against the acceptance criteria in spec.md:

Cross-reference behavior with the Review & Acceptance Checklist section in `specs/001-todo-app/spec.md`

4. Runtime Error Resolution

Browser console errors or CLI errors should be captured and provided back to the AI agent for resolution:

Sources: README.md612-615 README.md482-488

---

Next Steps

After completing your first feature:

Extend the Application

Create additional features by repeating the workflow:

1. New feature branch: Execute /speckit.specify with new requirements - the agent will automatically run create-new-feature.sh to create 002-feature-name branch and directory
2. Plan incrementally: Reference existing 001-*/plan.md for consistency
3. Maintain constitutional compliance: Each new plan is validated against .specify/memory/constitution.md

Explore Advanced Commands

• /speckit.analyze - Cross-artifact validation (see 2.3 for details)
• /speckit.checklist - Custom quality gate generation (see 5.9 for details)
• Extension system - Add project-specific commands (see Extension System for details)

Review Methodology

For comprehensive understanding of the philosophy and advanced patterns:

• Core Concepts and Methodology - Principles behind Spec-Driven Development
• Constitutional Governance System - Deep dive into the 9 Articles and enforcement gates
• Feature Creation and Branch Management - Details on create-new-feature.sh and numbering scheme

Sources: README.md238-279 README.md287-318