If you have spent time using AI coding agents — GitHub Copilot, Claude Code, Gemini CLI — you have probably run into this situation: you describe what you want, the agent generates a block of code that looks correct, compiles, and then subtly misses the actual intent. This “vibe-coding” approach can work for quick prototypes but becomes less reliable when building mission-critical applications or working with existing codebases. The issue, as GitHub frames it, is not the coding agent’s ability — it is the approach. Developers have been treating coding agents like search engines, when they should be treated more like literal-minded pair programmers who excel at pattern recognition but still need unambiguous instructions.
To address this, GitHub has open sourced Spec-Kit — a toolkit designed to bring Spec-Driven Development (SDD) to AI coding workflows. The project currently has 90k+ stars and 8k+ forks on GitHub, and has become one of the faster-growing developer tooling repositories in recent memory.
What is Spec-Driven Development?
Spec-Driven Development inverts the traditional power structure of software development. Specifications do not serve code — code serves specifications. The Product Requirements Document (PRD) is not a guide for implementation; it is the source that generates implementation.
In practice, this means you write a structured specification first — describing what you want to build and why, without specifying the tech stack — and then feed that into an AI coding agent as a grounding document. The spec becomes the source of truth that tools and AI agents use to generate, test, and validate code. The result is less guesswork, fewer surprises, and higher-quality code.
This is distinct from “documentation-first” as traditionally practiced. SDD is not about writing exhaustive, dry requirements documents that nobody reads. It is not about waterfall planning or trying to predict the future through extensive planning exercises. And it is not about creating more bureaucracy that slows engineering teams down. The spec remains a living artifact — updated as requirements evolve, rather than filed away after project kickoff.
What Spec-Kit Actually Includes
Spec-Kithas two key components: the Specify CLI, a helper command-line tool that bootstraps projects for SDD by downloading official templates for the coding agent and platform of your choice; and a set of templates and helper scripts that establish the foundation for the SDD experience — defining what a spec looks like, what a technical plan encompasses, and how it all breaks down into individual tasks that an AI agent can execute.
The CLI is written in Python and requires Python 3.11+. Installation via uv is the recommended method:
Copy CodeCopiedUse a different Browseruv tool install specify-cli –from git+https://github.com/github/spec-kit.git@vX.Y.Z
specify init <PROJECT_NAME>
Once initialized, the agent has access to a set of slash commands that map directly to the SDD workflow. The core commands are:
/speckit.constitution — establishes the project’s non-negotiable governing principles
/speckit.specify — captures what you want to build, focused on the “what” and “why” without tech stack details
/speckit.plan — generates the technical implementation plan given your chosen stack
/speckit.tasks — breaks the plan into an actionable, dependency-ordered task list
/speckit.taskstoissues — converts the generated task list into GitHub issues for tracking and execution
/speckit.implement — executes those tasks using the AI coding agent
There are also three optional commands for enhanced quality and validation:
/speckit.clarify — surfaces underspecified areas through structured, sequential questioning before a technical plan is created (recommended before /speckit.plan to reduce rework downstream)
/speckit.analyze — runs cross-artifact consistency and coverage analysis after /speckit.tasks and before /speckit.implement
/speckit.checklist — generates custom quality checklists that validate requirements completeness, clarity, and consistency
An important addition is constitution.md. In the SDD context, a constitution document establishes a set of non-negotiable principles for a project — testing conventions, CLI-first requirements, organizational design system standards. These are captured once and referenced throughout every subsequent development phase.
#sk-guide *{box-sizing:border-box;margin:0;padding:0}
#sk-guide{
font-family:-apple-system,BlinkMacSystemFont,”Segoe UI”,Roboto,sans-serif;
max-width:720px;
margin:0 auto;
padding:2rem 1rem 2.5rem;
color:#1a1a1a;
}
#sk-guide .sk-badge{
display:inline-flex;align-items:center;gap:6px;
background:#e8f5e0;color:#2d6a0a;
font-size:11px;font-weight:600;letter-spacing:.05em;text-transform:uppercase;
padding:4px 12px;border-radius:20px;margin-bottom:.85rem;
}
#sk-guide .sk-badge svg{width:12px;height:12px;fill:#2d6a0a}
#sk-guide .sk-title{font-size:21px;font-weight:700;color:#111;line-height:1.3;margin-bottom:.4rem}
#sk-guide .sk-sub{font-size:14px;color:#555;line-height:1.7;margin-bottom:1.75rem;max-width:640px}
#sk-guide .sk-progress-wrap{display:flex;align-items:center;gap:10px;margin-bottom:1.5rem}
#sk-guide .sk-progress-track{flex:1;height:3px;background:#e8e8e8;border-radius:2px;overflow:hidden}
#sk-guide .sk-progress-fill{height:100%;background:#3a7d00;border-radius:2px;transition:width .35s ease}
#sk-guide .sk-progress-label{font-size:12px;color:#888;white-space:nowrap}
#sk-guide .sk-dots{display:flex;gap:6px;margin-bottom:1.2rem;flex-wrap:wrap}
#sk-guide .sk-dot{
width:8px;height:8px;border-radius:50%;background:#d4d4d4;cursor:pointer;
transition:background .2s,transform .15s;border:none;padding:0;
}
#sk-guide .sk-dot:hover{background:#888;transform:scale(1.2)}
#sk-guide .sk-dot.active{background:#3a7d00;transform:scale(1.25)}
#sk-guide .sk-card{
display:none;background:#fff;border:1px solid #e2e2e2;border-radius:12px;
padding:1.5rem 1.75rem 1.25rem;box-shadow:0 2px 8px rgba(0,0,0,.05);
}
#sk-guide .sk-card.active{display:block}
#sk-guide .sk-step-label{font-size:11px;font-weight:600;letter-spacing:.06em;text-transform:uppercase;color:#3a7d00;margin-bottom:6px}
#sk-guide .sk-step-title{font-size:18px;font-weight:700;color:#111;margin-bottom:.75rem;line-height:1.35}
#sk-guide .sk-step-body{font-size:14px;color:#444;line-height:1.75;margin-bottom:1rem}
#sk-guide .sk-step-body strong{color:#111}
#sk-guide .sk-code{
font-family:”SFMono-Regular”,Consolas,”Liberation Mono”,Menlo,monospace;
font-size:13px;background:#f5f5f0;border:1px solid #e0e0d8;border-left:3px solid #3a7d00;
border-radius:6px;padding:12px 16px;color:#1a1a1a;margin:.75rem 0 1rem;
white-space:pre;overflow-x:auto;line-height:1.65;
}
#sk-guide .sk-code .comment{color:#888}
#sk-guide .sk-code .cmd{color:#1a6600}
#sk-guide .sk-code .arg{color:#0055aa}
#sk-guide .sk-code .flag{color:#aa5500}
#sk-guide .sk-tip{
display:flex;gap:10px;font-size:13px;color:#444;line-height:1.65;
padding:.65rem 1rem;background:#f0f7e8;border-radius:8px;border:1px solid #cce5b0;margin:.75rem 0;
}
#sk-guide .sk-tip .sk-icon{font-size:16px;flex-shrink:0;margin-top:1px}
#sk-guide .sk-tip strong{color:#1a5200}
#sk-guide .sk-warn{
display:flex;gap:10px;font-size:13px;color:#444;line-height:1.65;
padding:.65rem 1rem;background:#fff8e8;border-radius:8px;border:1px solid #f0d890;margin:.75rem 0;
}
#sk-guide .sk-warn .sk-icon{font-size:16px;flex-shrink:0;margin-top:1px}
#sk-guide .sk-warn strong{color:#7a5000}
#sk-guide .sk-checklist{list-style:none;display:flex;flex-direction:column;gap:8px;margin:.75rem 0 1rem}
#sk-guide .sk-checklist li{display:flex;gap:10px;align-items:flex-start;font-size:14px;color:#444;line-height:1.6}
#sk-guide .sk-checklist li .ck{
width:18px;height:18px;flex-shrink:0;border-radius:4px;background:#3a7d00;
display:flex;align-items:center;justify-content:center;margin-top:2px;
}
#sk-guide .sk-checklist li .ck svg{width:10px;height:10px;fill:none;stroke:#fff;stroke-width:2.5;stroke-linecap:round;stroke-linejoin:round}
#sk-guide .sk-opt-grid{display:grid;grid-template-columns:1fr 1fr;gap:10px;margin:.75rem 0 1rem}
#sk-guide .sk-opt-card{background:#f8fbf5;border:1px solid #cce5b0;border-radius:8px;padding:.85rem 1rem}
#sk-guide .sk-opt-card .sk-opt-cmd{
font-family:”SFMono-Regular”,Consolas,”Liberation Mono”,Menlo,monospace;
font-size:12.5px;color:#1a6600;font-weight:600;margin-bottom:5px;
}
#sk-guide .sk-opt-card .sk-opt-desc{font-size:12.5px;color:#555;line-height:1.55}
@media(max-width:520px){#sk-guide .sk-opt-grid{grid-template-columns:1fr}}
#sk-guide .sk-footer{
display:flex;justify-content:space-between;align-items:center;
margin-top:1.25rem;padding-top:1rem;border-top:1px solid #f0f0f0;
}
#sk-guide .sk-counter{font-size:12px;color:#aaa}
#sk-guide .sk-nav-btns{display:flex;gap:8px}
#sk-guide .sk-btn{
font-size:13px;font-weight:500;padding:7px 18px;border-radius:8px;cursor:pointer;
transition:background .15s,color .15s;border:1px solid #ddd;background:#fff;color:#333;
}
#sk-guide .sk-btn:hover{background:#f5f5f5}
#sk-guide .sk-btn.primary{background:#3a7d00;color:#fff;border-color:#3a7d00}
#sk-guide .sk-btn.primary:hover{background:#2d6200}
#sk-guide .sk-btn:disabled{opacity:.35;cursor:not-allowed}
#sk-guide .sk-summary{
margin-top:1.5rem;background:#f7fbf3;border:1px solid #c8e6b0;
border-radius:12px;padding:1.25rem 1.5rem;display:none;
}
#sk-guide .sk-summary.visible{display:block}
#sk-guide .sk-summary h4{font-size:14px;font-weight:700;color:#1a5200;margin-bottom:.75rem}
#sk-guide .sk-summary ul{list-style:none;display:flex;flex-direction:column;gap:6px}
#sk-guide .sk-summary ul li{display:flex;gap:8px;align-items:flex-start;font-size:13px;color:#333;line-height:1.6}
#sk-guide .sk-summary ul li::before{content:”✓”;color:#3a7d00;font-weight:700;flex-shrink:0}
#sk-guide .sk-source{margin-top:1rem;text-align:right;font-size:12px;color:#aaa}
#sk-guide .sk-source a{color:#3a7d00;text-decoration:none}
#sk-guide .sk-source a:hover{text-decoration:underline}
GitHub Spec Kit
How to Use GitHub Spec Kit: A Step-by-Step Guide
Spec-Driven Development (SDD) with AI coding agents — from installing the CLI to running your first implementation. Follows the official workflow from the github/spec-kit repository.
Step 1 of 10
Step 1 — Prerequisites
Make sure you have the right tools installed
Before installing the Specify CLI, you need four things on your machine. Spec Kit is cross-platform and works on Linux, macOS, and Windows.
Python 3.11+ — download from python.org
uv (recommended) or pipx for package management — install uv from docs.astral.sh/uv
Git — download from git-scm.com
A supported AI coding agent — Claude Code, GitHub Copilot, Gemini CLI, Cursor, Windsurf, Codex CLI, or any of the 29 supported integrations
Why uv? It manages tool installations globally, keeps them in your PATH, and makes upgrading easy with uv tool list, uv tool upgrade, and uv tool uninstall. It’s the officially recommended method.
1 / 10
← Back
Next →
Step 2 — Installation
Install the Specify CLI from GitHub
The only official Spec Kit package is published directly from the GitHub repository. Do not install from PyPI — any package there with the same name is not maintained by the Spec Kit team.
# Persistent install (recommended) — replace vX.Y.Z with latest tag
uv tool install specify-cli –from git+https://github.com/github/spec-kit.git@vX.Y.Z
# Or using pipx
pipx install git+https://github.com/github/spec-kit.git@vX.Y.Z
# Verify installation
specify version
Check the Releases page for the latest tag (e.g. v0.8.4). Installing from main may include unreleased changes.
One-time usage (no install): Run uvx –from git+https://github.com/github/spec-kit.git@vX.Y.Z specify init <PROJECT> to try without a persistent install.
2 / 10
← Back
Next →
Step 3 — Initialize
Bootstrap your project with specify init
Navigate to your project folder and run specify init. The CLI detects which AI coding agent you have installed and sets up the right directory structure, templates, and commands automatically.
# New project in a new folder
specify init my-photo-app
# Initialize inside an existing directory
specify init . –integration claude
# Skills mode for Claude Code and Codex CLI
specify init . –integration codex –integration-options=”–skills”
# Check all required tools are present
specify check
After this, your project will contain a .specify/ directory with memory/, scripts/, specs/, and templates/ subdirectories.
Skills mode: Claude Code, Codex CLI, Kimi Code, Devin, and several other agents use a skills-based installation — files go into agent-specific directories (e.g. .claude/skills/) instead of slash-command prompt files. Run specify integration list to see which mode each agent uses.
3 / 10
← Back
Next →
Step 4 — Constitution
Set project principles with /speckit.constitution
The first command you run inside your agent is /speckit.constitution. This creates a constitution.md file containing non-negotiable governing principles the agent follows throughout every subsequent phase. Run this once per project.
# Example — photo album app
/speckit.constitution Create principles focused on:
– Code quality and test coverage standards
– User experience consistency across all screens
– Performance requirements for image-heavy interfaces
– No third-party image upload services — local storage only
This writes to .specify/memory/constitution.md. Think of it as standing instructions — things like “always use TypeScript,” “never introduce breaking API changes,” or “follow our internal design system.”
4 / 10
← Back
Next →
Step 5 — Specification
Describe what to build with /speckit.specify
Now describe what you want to build — focus entirely on the “what” and “why.” Do not mention the tech stack at this stage. The agent produces a spec.md with user stories and functional requirements.
# Example — photo album app spec
/speckit.specify Build an application that organizes photos into albums.
Albums are grouped by date and can be re-organized by dragging
and dropping on the main page. Albums are never nested inside
other albums. Within each album, photos are previewed in a
tile-like interface. Users can rename and delete albums but
cannot delete individual photos from within an album view.
Do not mention tech stack here. Mixing “what to build” with “how to build it” at this stage leads to over-constrained specs. The tech stack comes in Step 7.
The output goes into .specify/specs/001-photo-app/spec.md and a new Git branch is created automatically.
5 / 10
← Back
Next →
Step 6 — Optional Quality Commands
Clarify and validate your spec before planning
Before generating the technical plan, two optional commands help surface gaps and validate your specification. Both are recommended, and can be skipped for quick spikes or exploratory prototypes.
/speckit.clarify
Structured, sequential questioning that records answers directly in a Clarifications section of the spec. Reduces rework downstream. Run before /speckit.plan.
/speckit.checklist
Generates custom quality checklists that validate requirements completeness, clarity, and consistency — described in the README as “unit tests for English.” Run after clarification.
# Run clarification first
/speckit.clarify
# Then validate spec completeness and clarity
/speckit.checklist
During clarification, the agent might ask things like:
Should albums support multiple selection for batch operations?
Is there a maximum number of photos per album?
Should drag-and-drop work on mobile, or desktop only?
If intentionally skipping clarification, explicitly tell the agent — otherwise it may block waiting on missing clarifications before allowing you to proceed to planning.
6 / 10
← Back
Next →
Step 7 — Technical Plan
Define the stack with /speckit.plan
Now specify the tech stack and architecture. The agent generates a plan.md, a data-model.md, a research.md, and a quickstart.md.
# Example — photo album app plan
/speckit.plan Use Vite with vanilla HTML, CSS, and JavaScript.
Keep third-party libraries to a minimum. Images are not uploaded
anywhere — metadata is stored in a local SQLite database via
a lightweight Express backend. Drag-and-drop uses the native
HTML5 Drag and Drop API.
Your directory after this step:
.specify/specs/001-photo-app/
├── spec.md
├── plan.md
├── data-model.md
├── research.md
└── quickstart.md
Check research.md to verify the correct tech stack was chosen. If a rapidly-changing framework is involved, ask the agent to research the specific installed version before moving forward.
7 / 10
← Back
Next →
Step 8 — Task Breakdown
Generate tasks with /speckit.tasks and /speckit.taskstoissues
Run /speckit.tasks to produce a tasks.md with the full implementation roadmap. Tasks are organized by user story, dependency-ordered, and annotated with parallel execution markers.
/speckit.tasks
# tasks.md output structure (example excerpt):
## User Story: Album Management
– [ ] Create SQLite schema: albums, photos tables
– [ ] [P] Build Express GET /albums endpoint
– [ ] [P] Build Express POST /albums endpoint
– [ ] [P] Implement album rename PUT /albums/:id
## Checkpoint: Validate album CRUD independently
The [P] marker indicates tasks that can run in parallel. Each user story section ends with a Checkpoint to validate that phase’s functionality works independently before the next begins. Optionally, convert tasks to GitHub Issues:
/speckit.taskstoissues
8 / 10
← Back
Next →
Step 9 — Cross-Artifact Analysis
Validate consistency with /speckit.analyze
After generating tasks and before running implementation, run the optional /speckit.analyze command. It performs a cross-artifact consistency and coverage check across the spec, plan, data model, and tasks to ensure everything is aligned.
/speckit.analyze
The agent will flag issues such as:
A user story in spec.md with no corresponding task in tasks.md
The plan referencing a database table that is undefined in the data model
A behaviour described in the spec that has no task assigned to implement it
This is a read-only command — it produces a findings report without modifying any files. Fix flagged issues before running /speckit.implement to prevent cascading errors during code generation.
9 / 10
← Back
Next →
Step 10 — Implementation
Execute with /speckit.implement
With all artifacts in place, run /speckit.implement. The agent first validates that constitution.md, spec.md, plan.md, and tasks.md are all present, then executes tasks in order — respecting dependencies and [P] parallel markers.
/speckit.implement
# The agent will:
# 1. Validate all prerequisite artifacts exist
# 2. Parse tasks.md for the correct execution order
# 3. Execute tasks, respecting [P] parallel markers
# 4. Report progress and handle errors at each step
Local CLI tools must be installed. The agent will run commands like npm, dotnet, or python directly on your machine. Make sure all required runtimes are available before running this command.
Adding a new feature? Skip /speckit.constitution (runs once per project) and start from /speckit.specify for each subsequent feature.
10 / 10
← Back
✓ Done
Full Spec Kit Workflow — Quick Reference
Install: uv tool install specify-cli –from git+https://github.com/github/spec-kit.git@vX.Y.Z
Init project: specify init <PROJECT> –integration <agent>
Set principles: /speckit.constitution — run once per project
Write spec: /speckit.specify — describe what to build, not how
Clarify gaps: /speckit.clarify (optional, recommended before plan)
Validate spec: /speckit.checklist (optional, after clarify)
Generate plan: /speckit.plan — specify tech stack and architecture
Break into tasks: /speckit.tasks + optional /speckit.taskstoissues
Check consistency: /speckit.analyze (optional, after tasks, before implement)
Build it: /speckit.implement
Source: github.com/github/spec-kit · MIT License · v0.8.4
(function(){
var total = 10;
var dotsEl = document.getElementById(‘sk-dots’);
for(var i=1;i