Spec Kit: Specification-Driven Development

Overview

Spec Kit implements Specification-Driven Development (SDD) - a methodology where specifications drive code, not vice versa. Instead of specs serving as documentation for code, code becomes the expression of specifications.

The Power Inversion

Traditional development: Code is truth, specs are scaffolding SDD: Specifications are truth, code is generated output

This eliminates the gap between intent and implementation by making specifications executable through AI.

Commands

`/speckit.specify <feature-description>`

Creates a comprehensive feature specification from a natural language description.

Usage: /speckit.specify Real-time chat with message history and presence

Output:

specs/{feature-name}/spec.md - Complete feature specification
specs/{feature-name}/checklists/requirements.md - Quality validation checklist

Process:

Parse user description, extract key concepts (actors, actions, data, constraints)
Generate user scenarios with prioritized stories (P1, P2, P3)
Define functional requirements (FR-001, FR-002, etc.)
Create measurable success criteria
Identify key entities
Validate against quality checklist
Present clarification questions (max 3) if critical ambiguities exist

Guidelines:

Focus on WHAT users need and WHY
Avoid HOW (no tech stack, APIs, code structure)
Make informed guesses using industry standards
Limit [NEEDS CLARIFICATION] markers to 3 maximum
Every requirement must be testable

For detailed template: read assets/templates/spec-template.md For command details: read references/commands/specify.md

`/speckit.plan [tech-context]`

Creates an implementation plan from an existing specification.

Usage: /speckit.plan WebSocket, PostgreSQL, Redis or /speckit.plan (will determine tech from context)

Prerequisites: spec.md must exist in the feature directory

Output:

specs/{feature}/plan.md - Implementation plan with tech decisions
specs/{feature}/research.md - Technology research and decisions
specs/{feature}/data-model.md - Entity definitions
specs/{feature}/contracts/ - API specifications (OpenAPI/GraphQL)
specs/{feature}/quickstart.md - Validation scenarios

Process:

Load feature specification and project constitution
Fill Technical Context section
Run Constitution Check (evaluate architectural gates)
Phase 0: Research unknowns, generate research.md
Phase 1: Design data models, generate contracts
Re-evaluate constitution compliance post-design

Constitution Gates (if using constitution):

Simplicity Gate: Using ≤3 projects? No future-proofing?
Anti-Abstraction Gate: Using framework directly?
Integration-First Gate: Contracts defined?

For detailed template: read assets/templates/plan-template.md For command details: read references/commands/plan.md

`/speckit.tasks`

Generates an executable task list from the implementation plan.

Usage: /speckit.tasks

Prerequisites: plan.md and spec.md must exist

Output:

specs/{feature}/tasks.md - Dependency-ordered task list

Process:

Load plan.md (tech stack, structure) and spec.md (user stories)
Optionally load: data-model.md, contracts/, research.md
Generate tasks organized by user story:
- Phase 1: Setup (shared infrastructure)
- Phase 2: Foundational (blocking prerequisites)
- Phase 3+: User Stories in priority order (P1, P2, P3...)
- Final Phase: Polish & cross-cutting
Mark parallelizable tasks with [P]
Number tasks (T001, T002...)
Generate dependency graph and parallel execution examples

Task Format: [ID] [P?] [Story] Description

[P] = Can run in parallel (different files, no dependencies)
[Story] = Which user story (US1, US2, US3)

For detailed template: read assets/templates/tasks-template.md For command details: read references/commands/tasks.md

Workflow Example

# 1. Create specification (5 min)
/speckit.specify Real-time chat with message history and user presence

# 2. Generate implementation plan (5 min)
/speckit.plan WebSocket for messaging, PostgreSQL for history, Redis for presence

# 3. Create task list (5 min)
/speckit.tasks

Result (in 15 minutes):

Complete feature spec with user stories and acceptance criteria
Detailed implementation plan with technology rationale
API contracts and data models
Executable task list organized by user story

Project Constitution

A constitution defines immutable architectural principles for a project. When present at memory/constitution.md, the /speckit.plan command will:

Validate against constitutional gates before planning
Require justification for any violations
Track complexity deviations

Sample principles:

Library-First: Features start as standalone libraries
Test-First: TDD mandatory (Red-Green-Refactor)
Simplicity: Maximum 3 projects, YAGNI
Integration-First: Real databases over mocks

For constitution template: read assets/templates/constitution-template.md

Key Concepts

User Story Organization

Tasks are grouped by user story to enable:

Independent implementation
Independent testing
Incremental delivery (ship P1, then P2, then P3)

MVP-First Delivery

Complete Setup + Foundational phases
Implement User Story 1 (P1) → Test → Deploy
Add User Story 2 (P2) → Test → Deploy
Continue incrementally

Template-Driven Quality

Templates constrain AI behavior for better outcomes:

Prevent premature implementation details
Force explicit uncertainty markers
Enforce test-first thinking
Prevent speculative features

File Locations

When working in a project:

Specifications: specs/{feature-name}/
Constitution: memory/constitution.md

Reference Files

Templates (fill-in artifacts for output)

assets/templates/spec-template.md - Feature specification template
assets/templates/plan-template.md - Implementation plan template
assets/templates/tasks-template.md - Task list template
assets/templates/constitution-template.md - Project constitution template

Documentation (methodology and command details)

references/methodology.md - Full SDD philosophy document
references/commands/specify.md - /speckit.specify command definition
references/commands/plan.md - /speckit.plan command definition
references/commands/tasks.md - /speckit.tasks command definition