GitHub Spec Kit: How 104K Developers Are Making AI Plan Before It Codes in 2026
TL;DR Summary
- GitHub Spec Kit has 104k stars and forces AI coding agents to plan before they code — replacing "vibe coding" (prompt-and-hope) with a structured spec → plan → tasks → implement pipeline
- Six slash commands:
/speckit.constitution(project principles),/speckit.specify(requirements),/speckit.clarify(AI asks questions),/speckit.plan(tech stack),/speckit.tasks(breakdown),/speckit.implement(execute) - Works with 30+ AI coding agents including Claude Code, Cursor, Copilot, Gemini CLI, Codex, Windsurf, and opencode
- MIT licensed, community extensions and presets for customization — add compliance gates, custom terminology, or entirely new workflows
- Supports brownfield projects (not just greenfield) — iterative enhancement on existing codebases
Direct Answer Block
GitHub Spec Kit is an open-source toolkit (104k stars, MIT) that implements Spec-Driven Development — a workflow where AI coding agents fully understand what you want before writing code. You define project principles, specify requirements, let the AI ask clarifying questions, create a technical plan, break it into ordered tasks, then execute. It works with 30+ agents and supports extensions for compliance, domain-specific workflows, and custom templates.
Introduction
"Vibe coding" has a 100% failure rate on non-trivial projects. You throw a prompt at an AI agent, it starts writing code immediately, skips half your requirements, invents a different architecture than what you use, and breaks three things it wasn't supposed to touch. GitHub Spec Kit breaks that cycle by forcing the agent through a structured pipeline: understand first, then build. 104,000 developers have starred it. 30+ AI coding agents support it. Here's how the workflow actually works and why it's worth the extra 5 minutes of planning.
What is Spec-Driven Development and why does "vibe coding" with AI agents keep breaking your code?
Spec-Driven Development flips the traditional script — literally. Instead of specs being throwaway documents you write before the "real work" begins, specifications become executable — directly generating working implementations rather than just guiding them.
The problem it solves is well-documented and universally experienced: AI coding agents are prompt-optimizers. They fill ambiguity with creativity. When you say "build a photo album app," the agent makes 50 silent assumptions about your tech stack, architecture, file structure, and user flow. Some of those assumptions will be wrong. The agent won't ask — it'll just code.
"Spec-Driven Development flips the script on traditional software development. For decades, code has been king — specifications were just scaffolding we built and discarded once the 'real work' of coding began. Spec-Driven Development changes this: specifications become executable, directly generating working implementations rather than just guiding them." — GitHub Spec Kit README
Spec Kit's README identifies several specific failure patterns of vibe coding that the structured workflow prevents: starting without understanding requirements, over-engineering simple features, touching unrelated code, and building on wrong architectural assumptions. The constitution step alone — defining project principles before any feature work — eliminates a class of errors where the agent picks the wrong library or pattern because it doesn't know your team's standards.
How do you initialize a project with Spec Kit — and which of the 30+ agent integrations should you choose?
Setup takes two commands:
# Install the CLI (requires uv)
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@v0.8.12
# Initialize a project with your agent of choice
specify init my-project --integration claude
cd my-project
The --integration flag supports 30+ agents. Here are the major options and when to choose each:
| Agent | Integration flag | Best for |
|---|---|---|
| Claude Code | --integration claude |
Deep reasoning, complex architecture |
| GitHub Copilot | --integration copilot |
IDE-native workflow, fast iterations |
| Cursor | --integration cursor |
Multi-file editing, agent mode |
| Gemini CLI | --integration gemini |
Google ecosystem integration |
| Codex CLI | --integration codex |
OpenAI model access, sandbox |
| OpenCode | --integration opencode |
Open-source, local-first |
The CLI auto-detects which agents you have installed. If you prefer to skip detection, use --ignore-agent-tools. For agents supporting skills mode (Codex, Gemini), passing --integration-options="--skills" installs agent skills instead of slash-command prompt files.
After initialization, the agent has access to the spec-kit slash commands. The project structure looks like:
.specify/
├── memory/
│ └── constitution.md # project principles
├── scripts/ # automation scripts
├── specs/ # feature specifications
│ └── 001-create-taskify/
│ ├── spec.md
│ ├── plan.md
│ └── tasks.md
└── templates/ # spec, plan, tasks templates
How does the workflow progress from constitution through specification, clarification, planning, and task breakdown?
The full workflow is a 6-step pipeline. Each step builds on the previous. Skipping steps produces progressively worse results.
Step 1: /speckit.constitution — Establish project principles
This is the foundation. You define your project's governance — code quality standards, testing requirements, UX consistency rules, performance expectations. The constitution gets stored in .specify/memory/constitution.md and is referenced by the agent during every subsequent phase.
Example prompt:
/speckit.constitution Create principles focused on code quality, testing standards,
user experience consistency, and performance requirements. Include governance for
how these principles should guide technical decisions and implementation choices.
Step 2: /speckit.specify — Define what to build
This is where you describe the what and why — not the how. Be exhaustively specific. The README's example prompt for a Taskify project is 15 lines of detailed requirements: user roles, Kanban columns, drag-and-drop behavior, comment permissions, color coding, everything. The more you specify, the less the agent guesses.
The output is a spec.md with structured user stories and functional requirements. A new git branch is created (e.g., 001-create-taskify).
Step 3: /speckit.clarify — AI asks clarifying questions
This is the most underrated step. Before any technical planning, the agent runs a structured clarification workflow — sequential, coverage-based questioning that identifies underspecified areas and records answers.
The README explicitly warns: "You should run the structured clarification workflow before creating a technical plan to reduce rework downstream." The agent asks questions you didn't know needed answers. Each answer gets recorded in a Clarifications section of the spec.
If you intentionally want to skip clarification (spike or prototype), explicitly state that — otherwise the agent may block on missing clarifications.
Step 4: /speckit.plan — Choose tech stack and architecture
Now you get specific about implementation:
/speckit.plan Use .NET Aspire with Postgres. Frontend: Blazor server with drag-and-drop
task boards, real-time updates. REST API: projects, tasks, notifications.
The output includes plan.md, data-model.md, research.md, quickstart.md, and API contracts. The research document is valuable — ask the agent to research specifics about rapidly changing libraries (".NET Aspire is changing fast, research the specific versions we'll use").
A critical note from the README: "Claude Code might be over-eager and add components that you did not ask for. Ask it to clarify the rationale and the source of the change."
Step 5: /speckit.tasks — Generate task breakdown
This generates tasks.md organized by user story, with:
- Dependency ordering — tasks respect component dependencies
-
Parallel execution markers
[P]— tasks that can run simultaneously - File path specifications — exact paths where implementation should occur
- TDD structure — test tasks written before implementation tasks
- Checkpoint validation — each user story phase has independent validation
Step 6: /speckit.implement — Execute
The agent validates prerequisites are in place, parses the task breakdown, executes in dependency order, respects parallel markers, follows TDD structure, and provides progress updates. After implementation, test thoroughly — CLI logs won't catch browser console errors.
How does /speckit.clarify force the AI to ask questions before writing code — and why does this prevent scope creep?
The clarification step solves a specific failure mode: agents that assume instead of asking. When an agent reads "build an app to organize photos in albums," it makes assumptions about:
- What "organize" means (drag-and-drop? automatic sorting? tags?)
- What "albums" means (nested? flat? shared?)
- What "photos" means (uploaded files? URLs? both?)
- Where data lives (local storage? cloud? database?)
Without clarification, the agent picks answers — and you discover the wrong ones during implementation. With /speckit.clarify, the agent systematically identifies every underspecified area and asks you about it. Each answer is recorded in the spec.
The README recommends this order: /speckit.clarify first (structured), then optionally follow up with ad-hoc free-form refinement if something still feels vague. The structured pass catches 90% of the ambiguity. The free-form pass catches edge cases.
This prevents scope creep because the spec becomes the contract. When the agent wants to add something not in the spec, you point to the spec. When the agent over-engineers a feature, you point to the constitution's simplicity principle. The documents aren't just documentation — they're behavioral constraints on the agent.
How do extensions and presets let you customize Spec Kit for compliance, domain terminology, and organizational standards?
Spec Kit has a layered customization system with clear priority:
| Priority | Layer | What it does |
|---|---|---|
| 1 (highest) | Project-Local Overrides | One-off adjustments for a single project |
| 2 | Presets | Customize how existing workflows produce artifacts |
| 3 | Extensions | Add entirely new commands and workflows |
| 4 (lowest) | Spec Kit Core | Built-in SDD commands and templates |
Extensions — Add new capabilities
Install domain-specific workflows not covered by the core commands:
specify extension search # find available extensions
specify extension add <name> # install one
Examples from the documentation: Jira integration, post-implementation code review, V-Model test traceability, project health diagnostics. Extensions expand what Spec Kit can do.
Presets — Customize existing workflows
Change how Spec Kit works without adding new capabilities:
specify preset search # find available presets
specify preset add <name> # install one
Examples: restructure spec templates for regulatory traceability, adapt workflow to Agile/Kanban/Waterfall/DDD, add mandatory security review gates, enforce test-first task ordering, localize entire workflow to different languages. The README links to a pirate-speak demo showing how deep customization can go.
Template resolution
Templates are resolved at runtime — Spec Kit walks the priority stack top-down and uses the first match. If multiple presets or extensions provide the same command, the highest-priority version wins. On removal, the next-highest-priority version is restored automatically.
How do you integrate Spec Kit into existing brownfield projects without starting from scratch?
Spec Kit isn't just for greenfield projects. The methodology supports three development modes:
0-to-1 Development (Greenfield): Start from requirements, generate specs, plan, and build. The standard flow.
Iterative Enhancement (Brownfield): Add features to existing codebases. Initialize Spec Kit in an existing directory with specify init . --force --integration claude. The --force flag merges Spec Kit into a non-empty directory. Then use the pipeline for each new feature — the constitution captures your existing standards, specs define incremental additions, and tasks are scoped to the feature boundary.
Creative Exploration: Run parallel implementations with different tech stacks or UX patterns. Spec Kit supports this through separate specification branches — each exploring a different approach before committing to one.
The specify init --here flag (or specify init .) initializes in the current directory without creating a new project folder. For CI/non-interactive environments, specify init defaults to Copilot unless you pass --integration.
Frequently Asked Questions
Q: Does Spec Kit work with languages other than English?
Yes. The preset system supports full localization — change all templates, commands, and terminology to any language. The pirate-speak demo in the README demonstrates the depth of customization possible. Enterprise presets can enforce company-specific terminology and regulatory language.
Q: Can I use Spec Kit without installing anything?
The templates and slash commands require the Specify CLI. However, the methodology itself (constitution → spec → plan → tasks → implement) can be followed manually with any AI coding agent by providing structured prompts that follow the same sequence.
Q: What happens if the agent's generated plan is wrong?
The README recommends an audit step between plan and implementation: "Read through it with an eye on determining whether or not there is a sequence of tasks that you need to be doing." You can also ask the agent to cross-check for over-engineered components. The constitution serves as a reference — if the plan violates a principle, point to the constitution.
Q: How does Spec Kit compare to writing a PRD manually?
A PRD is a document you write. Spec Kit generates the spec, plan, and tasks through interaction with the AI agent — the agent asks clarifying questions, researches tech choices, and structures the output. The output is richer (data models, API contracts, research docs) and the process catches gaps you'd miss writing alone.
Q: Can I run multiple Spec Kit projects with different constitutions?
Yes. Each project has its own .specify/memory/constitution.md. Different projects can have different standards — a production monorepo might have strict testing and compliance rules, while a prototype might have minimal constraints.
Q: What's the difference between /speckit.analyze and the pre-implementation audit?
/speckit.analyze is an optional command that runs cross-artifact consistency and coverage analysis — checking that the spec, plan, and tasks are internally consistent. Run it after /speckit.tasks and before /speckit.implement. The pre-implementation audit is a manual review step where you ask the agent to walk through the plan looking for gaps.
Glossary
- Spec-Driven Development: A methodology where specifications become executable — they directly generate implementations rather than just guiding them
- Vibe coding: The practice of throwing prompts at an AI agent without structured requirements, hoping the output works — characterized by skipped requirements and broken functionality
-
Constitution: The project's governing principles document in
.specify/memory/constitution.md— referenced by the agent throughout all development phases - Clarification workflow: A structured, coverage-based questioning process where the AI agent identifies underspecified areas before technical planning begins
- Preset: A customization layer that overrides templates and terminology without adding new commands — for enforcing organizational standards
- Extension: A customization layer that adds entirely new commands and workflows beyond Spec Kit's core — for integrating external tools or adding development phases
Author
Ramsis Hammadi — AI/ML engineer specializing in GenAI, LLM engineering, and automation. Full bio →
Top comments (0)