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:
uv tool install specify-cli --from git+https://github.com/github/[email protected]
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.planto reduce rework downstream)/speckit.analyze— runs cross-artifact consistency and coverage analysis after/speckit.tasksand 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.
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 — 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.
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.
uv tool install specify-cli –from git+https://github.com/github/spec-kit.git@vX.Y.Z
pipx install git+https://github.com/github/spec-kit.git@vX.Y.Z
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/[email protected] specify init <PROJECT> to try without a persistent install.
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.
specify init my-photo-app
specify init . –integration claude
specify init . –integration codex –integration-options=”–skills”
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.
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.
/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.”
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.
/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.
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.
/speckit.clarify
/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.
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.
/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.
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
## 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
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.mdwith no corresponding task intasks.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.
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
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.
✅ Full Spec Kit Workflow — Quick Reference
- Install:
uv tool install specify-cli --from git+https://github.com/github/[email protected] - 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
The Development Phases
Spec-Kit supports three broad development scenarios. For greenfield projects, you start with high-level requirements, generate specifications, and plan implementation before writing any code. For iterative enhancement on existing codebases (“brownfield”), you add features incrementally without discarding prior context. For legacy modernization, where the original intent is often lost to time, you capture essential business logic in a modern spec, design a fresh architecture in the plan, and let the AI rebuild the system without carrying forward inherited technical debt.
The /speckit.tasks command produces a tasks.md file with task breakdowns organized by user story, dependency ordering (so models are implemented before services, services before endpoints), parallel execution markers tagged [P], exact file path specifications, and checkpoint validation between phases.
Agent Compatibility and Extensibility
The Specify CLI supports a wide range of AI coding agents. When you run specify init, the CLI sets up the appropriate command files, context rules, and directory structures for your chosen AI coding agent. Spec-Kit currently supports 29 named integrations — including Claude Code, GitHub Copilot, Gemini CLI, Cursor, Windsurf, Codex CLI, Qwen Code, Kiro CLI, Goose, Mistral Vibe, Devin for Terminal, Roo Code, and IBM Bob — along with a Generic integration for any agent not on the list.
An important distinction: for several agents, Spec-Kit installs agent skills rather than slash-command prompt files. Claude Code, for example, uses a skills-based integration that places files under .claude/skills/. Codex CLI similarly uses skills invoked as $speckit-<command>. For these integrations, pass --integration-options="--skills" during specify init to install in skills mode.
The toolkit can also be extended through two mechanisms. Extensions introduce new commands and templates — for example, Jira or Azure DevOps integration, post-implementation code review, OWASP LLM threat modeling, or V-Model test traceability. Presets override existing templates and commands to enforce organizational or regulatory standards without adding new capabilities. There are currently over 70 community-contributed extensions in the catalog, covering categories including docs, code, process, integration, and visibility, each flagged as either Read-only or Read+Write in effect.
Key Takeaways
- GitHub’s Spec-Kit is an open source toolkit that introduces a structured Spec-Driven Development (SDD) workflow for AI coding agents, moving away from ad-hoc prompting.
- The core workflow runs through six commands:
/speckit.constitution→/speckit.specify→/speckit.plan→/speckit.tasks→/speckit.taskstoissues→/speckit.implement, with three additional optional commands for validation. - Spec-Kit supports 29 named AI coding agent integrations plus a Generic option; some agents (including Claude Code and Codex CLI) use a skills-based installation mode rather than slash commands.
- A growing ecosystem of 70+ community extensions adds integrations with tools like Jira, Azure DevOps, and GitHub Issues, plus quality gates for security, testing, and drift detection.
- The project is self-described as an experiment and is best suited for greenfield builds and large feature work rather than small bug fixes.
Check out the GitHub Repo here. Also, feel free to follow us on Twitter and don’t forget to join our 150k+ ML SubReddit and Subscribe to our Newsletter. Wait! are you on telegram? now you can join us on telegram as well.
Need to partner with us for promoting your GitHub Repo OR Hugging Face Page OR Product Release OR Webinar etc.? Connect with us
