Spec-Driven Development Workflow

Relevant source files

• CODE_OF_CONDUCT.md
• CONTRIBUTING.md
• README.md
• spec-driven.md

Purpose and Scope

This document describes the complete Spec-Driven Development (SDD) workflow implemented in Spec Kit, covering the end-to-end process from project initialization through feature implementation. It explains how AI agents interact with slash commands, scripts, templates, and artifacts to transform natural language requirements into working code.

For details on the specify CLI tool and project initialization, see Core CLI Tool. For information on multi-agent configuration and agent-specific file management, see AI Agent Integration. For template system implementation details, see Templates and Scripts.

Overview of the Workflow

Spec-Driven Development is a structured methodology where specifications serve as executable artifacts that directly drive implementation. The workflow consists of five sequential phases, each producing specific artifacts that serve as immutable checkpoints for subsequent phases.

The core workflow progression:

Phase	Slash Command	Primary Output	Purpose
Constitutional Governance	/speckit.constitution	.specify/memory/constitution.md	Establish project principles and constraints
Specification	/speckit.specify	specs/NNN-short-name/spec.md	Define requirements and user stories
Planning	/speckit.plan	specs/NNN-short-name/plan.md	Create technical implementation plan
Task Generation	/speckit.tasks	specs/NNN-short-name/tasks.md	Generate dependency-ordered task list
Implementation	/speckit.implement	Source code, tests	Execute tasks and build feature

Sources: README.md39-135 README.md245-270 README.md286-293

Command Execution Flow

The workflow is driven by slash commands that AI agents execute. Each command triggers specific scripts in .specify/scripts/, processes templates from .specify/templates/, and generates artifacts in .specify/memory/ or specs/NNN-short-name/.

Slash Command to Script and File Mapping

Diagram: Command to Code Entity Mapping

Sources: README.md245-270 README.md390-616 README.md441-528

The Workflow Phases

Phase 1: Constitutional Governance

The /speckit.constitution command establishes project-wide principles that govern all subsequent development decisions. The constitution acts as a constraint system that AI agents reference during specification, planning, and implementation.

Key artifacts:

• .specify/memory/constitution.md - Project governance principles

Constitution content typically includes:

• Code quality standards (formatting, linting, testing coverage)
• Technology constraints (approved frameworks, libraries, platforms)
• Architecture patterns (layering, separation of concerns)
• Performance requirements (response times, resource limits)
• User experience principles (accessibility, consistency)

Validation: The /speckit.analyze command (see #4.6) performs constitutional compliance checking, flagging violations as CRITICAL findings.

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

Phase 2: Specification

The /speckit.specify command initiates feature creation. It executes .specify/scripts/create-new-feature.sh or .specify/scripts/create-new-feature.ps1 to establish the feature structure, then generates a functional specification from user requirements.

Diagram: Specification Phase Workflow

Script behavior: .specify/scripts/create-new-feature.sh / .specify/scripts/create-new-feature.ps1

Operation	Implementation
Parse description	Accepts natural language feature description as argument
Filter stop words	Removes "a", "an", "the", "and", "or", "but", "in", "on", "at", "to", "for"
Generate short-name	Takes first 3-4 significant words, lowercases, joins with hyphens
Determine branch number	Runs git ls-remote --heads origin, git branch --list, scans specs/ directory
Calculate next number	Finds max of all branch numbers + existing spec numbers, adds 1
Create branch	Executes git checkout -b NNN-short-name
Create directory	Creates specs/NNN-short-name/ directory structure
Return JSON	Outputs {"branch": "001-user-auth", "spec_path": "specs/001-user-auth/spec.md", "short_name": "user-auth"}

Template structure: .specify/templates/spec-template.md

The template enforces structured specification generation through the following sections:

• Overview - High-level feature description and goals
• User Stories - Structured as "As a [role], I want [capability] so that [benefit]"
• Functional Requirements - Specific, testable requirements organized by category
• Non-Functional Requirements - Performance, security, scalability constraints
• Acceptance Criteria - Measurable validation conditions
• Out of Scope - Explicit exclusions to prevent scope creep
• Review & Acceptance Checklist - Quality validation gates

Template constraints on LLM behavior:

Generated artifact: specs/NNN-short-name/spec.md

The specification artifact contains:

• Functional requirements (what to build, not how to implement)
• User stories with explicit acceptance criteria
• [NEEDS CLARIFICATION] markers for underspecified areas
• Quality validation checklist for self-review

Sources: README.md103-109 README.md406-441 README.md441-459 spec-driven.md165-225

Phase 3: Clarification (Optional)

The /speckit.clarify command performs structured requirement clarification before technical planning. It surfaces targeted questions (maximum 5) about underspecified areas marked with [NEEDS CLARIFICATION] in the specification.

Clarification workflow:

1. Agent parses spec.md for clarification markers
2. Generates focused questions about ambiguous requirements
3. User provides answers
4. Agent updates spec.md with clarifications in dedicated section
5. Agent removes [NEEDS CLARIFICATION] markers

Alternative approach: Free-form refinement can supplement structured clarification, but /speckit.clarify provides systematic coverage and audit trail.

Sources: README.md461-489

Phase 4: Planning

The /speckit.plan command creates the technical implementation plan, incorporating technology stack decisions and architecture choices. It executes .specify/scripts/setup-plan.sh / .specify/scripts/setup-plan.ps1 to prepare the directory structure, then generates multiple artifacts that define implementation details.

Diagram: Planning Phase Workflow

Script behavior: .specify/scripts/setup-plan.sh / .specify/scripts/setup-plan.ps1

Operation	Implementation
Validate prerequisites	Checks that specs/NNN-short-name/spec.md exists
Create contracts directory	Executes mkdir -p specs/NNN-short-name/contracts/
Initialize artifact structure	Prepares for multi-file generation (plan.md, data-model.md, contracts/, research.md)

Script behavior: .specify/scripts/update-agent-context.sh / .specify/scripts/update-agent-context.ps1

This script synchronizes project context across all agent-specific files after plan generation:

Operation	Implementation
Parse plan.md	Extracts structured sections: Languages, Frameworks, Database, External Services
Identify tech stack	Builds list of technologies from plan sections
Update CLAUDE.md	Appends tech stack to Claude context
Update GEMINI.md	Appends tech stack to Gemini context
Update .github/agents/copilot-instructions.md	Appends tech stack to GitHub Copilot context
Update .cursor/commands/context.md	Appends tech stack to Cursor context
Update .windsurf/rules/specify-rules.md	Appends tech stack to Windsurf context

Template structure: .specify/templates/plan-template.md

The plan template enforces constitutional compliance through pre-implementation gates:

Generated artifacts:

File Path	Purpose	Example Content
specs/NNN-short-name/plan.md	Core implementation plan with architecture decisions	Tech stack, phases, file creation order, constitutional gates
specs/NNN-short-name/data-model.md	Database schema, entity relationships, data structures	ER diagrams, table definitions, relationships
specs/NNN-short-name/contracts/api-spec.json	REST API contracts in OpenAPI/Swagger format	Endpoints, request/response schemas, HTTP methods
specs/NNN-short-name/contracts/signalr-spec.md	Real-time protocol specifications	WebSocket events, message formats
specs/NNN-short-name/research.md	Technology research, version compatibility	Library versions, compatibility notes, alternatives
specs/NNN-short-name/quickstart.md	Key validation scenarios for manual testing	Setup steps, test scenarios, expected outcomes

Sources: README.md111-118 README.md490-556 spec-driven.md206-225

Phase 5: Analysis (Optional)

The /speckit.analyze command performs cross-artifact consistency analysis before implementation. It validates that specifications, plans, and constitution align without contradictions.

Analysis checks:

• Constitutional compliance: Verifies plan.md adheres to principles in constitution.md
• Specification coverage: Ensures plan.md addresses all requirements in spec.md
• Consistency validation: Detects contradictions between artifacts
• Gap identification: Surfaces missing implementation details

Violation severity levels:

• CRITICAL - Constitutional violations requiring resolution
• WARNING - Inconsistencies that may cause implementation issues
• INFO - Suggestions for improvement

Non-destructive analysis: The command only reports findings; it does not modify artifacts.

Sources: README.md265-268

Phase 6: Task Generation

The /speckit.tasks command generates a dependency-ordered task breakdown from the implementation plan. It processes .specify/templates/tasks-template.md to create specs/NNN-short-name/tasks.md with tasks structured for systematic execution by /speckit.implement.

Diagram: Task Generation Workflow

Task structure in specs/NNN-short-name/tasks.md:

Task markers and annotations:

Marker	Meaning	Example
[P]	Parallel execution (safe to run concurrently)	[P] Install dependencies
[US1], [US2]	User story reference from spec.md	[US1] User Authentication
(create: path)	File creation task	(create: src/models/User.js)
(update: path)	File modification task	(update: package.json)
(run: command)	CLI command execution	(run: npm install express)

Dependency ordering rules:

Layer	Depends On	Example
Models	Database schema	User.js requires database tables
Services	Models	AuthService.js requires User.js
Endpoints	Services	POST /api/auth/login requires AuthService.js
Contract tests	Contracts	tests/contracts/auth.test.js requires contracts/api-spec.json
Integration tests	Endpoints	tests/integration/auth.test.js requires endpoints implemented

Template structure: .specify/templates/tasks-template.md

The template enforces:

• Phase-based organization (infrastructure → user stories → polish)
• Dependency-aware task ordering (models before services, services before endpoints)
• Parallel task identification for optimization
• Checkpoint definitions for incremental validation
• File path specifications for clarity

Sources: README.md119-125 README.md576-593 spec-driven.md96-104

Phase 7: Implementation

The /speckit.implement command executes the task breakdown systematically by parsing specs/NNN-short-name/tasks.md, generating source code, running CLI commands, executing tests, and committing changes. It may invoke .specify/scripts/check-prerequisites.sh / .specify/scripts/check-prerequisites.ps1 to validate tool availability.

Diagram: Implementation Phase State Machine

Implementation execution steps:

Step	Operation	Code Entity
1. Validate prerequisites	Check for .specify/memory/constitution.md, specs/NNN-short-name/spec.md, specs/NNN-short-name/plan.md, specs/NNN-short-name/tasks.md	.specify/scripts/check-prerequisites.sh
2. Parse tasks.md	Load specs/NNN-short-name/tasks.md, extract phases and tasks	Agent parses markdown structure
3. Execute setup phase	Run infrastructure tasks sequentially	Commands like npm init, npm install express pg
4. Execute user story phases	Process each user story's tasks in dependency order	Create src/models/User.js, src/services/AuthService.js, etc.
5. Handle parallel tasks	Execute tasks marked [P] concurrently	Multiple file creations or API endpoint implementations
6. Run checkpoints	Execute validation commands after each phase	npm test, curl commands, manual checks
7. Commit changes	Stage and commit files after successful phase completion	git add ., git commit -m "Phase N complete"

Task execution patterns:

Task Type	Pattern	Example
File creation	(create: path) → Generate file content → Write to path	(create: src/models/User.js) → Generate class → Write file
File update	(update: path) → Read existing → Modify → Write back	(update: package.json) → Add dependency → Save
CLI command	(run: command) → Execute in shell → Capture output	(run: npm install express) → Run npm → Check exit code
Test execution	(run: test command) → Execute → Verify pass/fail	(run: npm test) → Run tests → Report results

Checkpoint validation:

After each phase, the agent executes checkpoint commands defined in tasks.md:

Error handling:

Error Type	Agent Behavior
Missing prerequisite file	Report error, list missing files, halt execution
CLI command failure	Report command output, suggest fixes, pause for user input
Test failure	Show test output, identify failing tests, allow retry or skip
File creation conflict	Warn about existing file, offer merge/overwrite/skip options

Parallel execution:

Tasks marked [P] are identified as safe for concurrent execution:

Agent may process these simultaneously by spawning multiple file generation operations.

Sources: README.md126-134 README.md595-616

Artifact Dependency Graph

The workflow produces artifacts that form a dependency chain, where each artifact serves as input to subsequent phases.

Immutable checkpoints: Once generated, artifacts like spec.md and plan.md serve as historical records. Changes are additive (clarifications, refinements) rather than destructive.

Bidirectional traceability:

• Forward: Requirements → Plan → Tasks → Code
• Backward: Code → Tasks → Plan → Requirements

Sources: README.md441-528 README.md576-616

Optional Quality Enhancement Commands

/speckit.checklist Command

Generates custom quality checklists for validating specifications and implementations. Acts as "unit tests for English" by creating objective validation criteria.

Checklist generation:

• Extracts requirements from spec.md
• Creates binary validation questions (yes/no, pass/fail)
• Organizes by requirement category
• Embedded in spec.md or maintained separately

Sources: README.md269-270

Clarification vs Analysis

Two commands support iterative refinement:

Command	Timing	Purpose	Modifies Artifacts
/speckit.clarify	After /speckit.specify, before /speckit.plan	Surface requirement gaps	Yes (updates spec.md)
/speckit.analyze	After /speckit.tasks, before /speckit.implement	Validate cross-artifact consistency	No (read-only analysis)

Sources: README.md265-270 README.md461-489

Integration with Git

The workflow integrates tightly with Git for feature branch management and change tracking.

Branch Lifecycle

Branch numbering strategy:

• Script scans remote branches: git ls-remote --heads origin
• Script scans local branches: git branch --list
• Script scans existing specs: specs/ directory
• Determines next available number: max(all_numbers) + 1

Branch naming:

• Format: NNN-short-name
• NNN: Zero-padded number (001, 002, etc.)
• short-name: 3-4 word description with stop words filtered
• Enforces GitHub 244-byte branch name limit

Implementation commits:

• AI agent commits changes during /speckit.implement execution
• Commit messages reference task descriptions
• Incremental commits per phase or user story

Sources: README.md432-441

Workflow Execution Example

Complete workflow execution for a "user authentication" feature:

Sources: README.md390-616

Non-Git Repository Support

For projects not using Git, the workflow supports manual feature directory specification:

Environment variable: SPECIFY_FEATURE

• Set to feature directory name (e.g., 001-photo-albums)
• Overrides Git branch-based feature detection
• Must be set in agent context before /speckit.plan and subsequent commands

Usage example:

Sources: README.md273-276

Template-Driven Generation

All commands use templates from .specify/templates/ to ensure consistent artifact structure:

Template File	Used By Command	Output Artifact
constitution-template.md	/speckit.constitution	.specify/memory/constitution.md
spec-template.md	/speckit.specify	specs/NNN-short-name/spec.md
plan-template.md	/speckit.plan	specs/NNN-short-name/plan.md
tasks-template.md	/speckit.tasks	specs/NNN-short-name/tasks.md
checklist-template.md	/speckit.checklist	Embedded in spec.md or separate file

Template processing:

• AI agent loads template
• Populates sections with generated content
• Preserves template structure (headings, sections, checklists)
• Maintains consistency across features and projects

Sources: README.md441-528

Constitutional Governance System

The .specify/memory/constitution.md artifact establishes immutable architectural principles that constrain all subsequent development. The constitution enforces quality through template-based gates and AI agent self-validation.

The 9 Articles of Development

The constitution defines 9 articles that govern code generation:

Article	Principle	Enforcement Mechanism
Article I	Library-First Principle	Every feature must begin as a standalone library
Article II	CLI Interface Mandate	All libraries must expose text-based CLI interfaces
Article III	Test-First Imperative	No implementation code before tests are written and approved
Article VII	Simplicity Gate	Maximum 3 projects for initial implementation, no future-proofing
Article VIII	Anti-Abstraction Gate	Use framework features directly, single model per resource
Article IX	Integration-First Testing	Prefer real databases/services over mocks, contract tests mandatory

Sources: spec-driven.md274-407

Constitutional Enforcement Through Plan Template

The .specify/templates/plan-template.md operationalizes constitutional articles through Phase -1 gates:

Diagram: Constitutional Gate Enforcement

Phase -1 Gates in plan-template.md:

Constitutional validation by /speckit.analyze:

The /speckit.analyze command performs cross-artifact constitutional compliance checking:

Validation Check	Severity	Example Finding
Article VII violation	CRITICAL	"Plan defines 5 projects, exceeds limit of 3"
Article VIII violation	CRITICAL	"Plan creates custom ORM layer, violates direct framework use"
Article IX violation	WARNING	"Tests use mocked database, prefer real database per Article IX"
Missing gate justification	WARNING	"Gate unchecked but no justification in Complexity Tracking"

Sources: spec-driven.md274-407 spec-driven.md206-225

Constitutional Immutability and Evolution

The constitution itself is versioned and tracked for changes:

Amendment process:

1. Modification requires explicit documentation of rationale
2. Review and approval by project maintainers
3. Backwards compatibility assessment
4. Version number increment in constitution.md

Constitution structure in .specify/memory/constitution.md:

Sources: spec-driven.md384-396

Workflow State Tracking

The workflow maintains state through the file system, enabling resumption and validation:

State indicators:

File Existence	Indicates	Next Valid Command
.specify/memory/constitution.md exists	Constitution established	/speckit.specify
specs/NNN-short-name/spec.md exists	Specification created	/speckit.clarify, /speckit.plan
specs/NNN-short-name/plan.md exists	Planning complete	/speckit.analyze, /speckit.tasks
specs/NNN-short-name/tasks.md exists	Tasks generated	/speckit.implement

Validation behavior:

• Commands validate prerequisites before execution
• Missing artifacts trigger informative error messages
• Prevents out-of-order execution (e.g., /speckit.implement before /speckit.tasks)

Sources: README.md595-616

Multi-Agent Consistency

The update-agent-context.sh / update-agent-context.ps1 scripts ensure all agents operate with synchronized project context:

Context synchronization:

1. Script parses plan.md for technology stack
2. Extracts: Languages, Frameworks, Database, External Services
3. Updates agent files: CLAUDE.md, GEMINI.md, .github/agents/copilot-instructions.md, .windsurf/rules/specify-rules.md, etc.
4. Maintains consistency across multi-agent development environments

Execution timing: Runs automatically after /speckit.plan command completion.

Sources: README.md490-528