Updated October 23, 2026: rewrote the setup for Spec Kit 1.2.3 (PyPI install, --integration replacing the removed --ai flag, skills-style commands) and added the converge step, the 41 supported agents and an honest-limits section.
GitHub Spec Kit is GitHub’s open-source (MIT) toolkit for spec-driven development: it installs a set of commands into your AI coding agent that make it write a specification, a technical plan and a task list before it writes any code. The current release is v1.2.3 from October 22, 2026; version 1.0.0 shipped on August 21, 2026, exactly one year after the first commit. Setup is two terminal commands (uv tool install specify-cli, then specify init my-project --integration claude), and the workflow runs as /speckit-constitution, /speckit-specify, /speckit-plan, /speckit-tasks, /speckit-implement and /speckit-converge inside your agent’s chat. It supports 41 coding agents, from GitHub Copilot and Claude Code to Codex, Cursor, Gemini CLI and Kiro CLI, and the repository has passed 142,000 stars.
The core idea hasn’t changed since launch: language models are excellent at pattern completion but terrible at mind reading. A vague prompt forces the model to guess at unstated requirements, and some of those guesses will be wrong. Spec Kit co-creator Den Delimarsky put it bluntly in GitHub’s launch post: “The issue isn’t the coding agent’s coding ability, but our approach. We treat coding agents like search engines when we should be treating them more like literal-minded pair programmers.” A literal-minded pair programmer needs a brief. Spec Kit makes you write that brief, and keeps it in the repository next to the code.
What Changed Since March 2026
If you followed a Spec Kit tutorial from early 2026, including the first version of this one, parts of it no longer work. The project has shipped 118 releases since March 22. The changes that matter, from the changelog:
- The CLI is on PyPI.
specify-clihas been published to PyPI since 0.11.5 (June 22), souv tool install specify-cliis enough. Old tutorials that pin@v0.1.4install a CLI that can’t set up current projects: the installation guide notes that a 0.1.6 CLI fails with both--integrationand--ai. --aiis gone. It was deprecated in favor of--integrationin 0.7.1 (April 15) and removed in 0.10.0 (June 9).specify init . --ai copilotnow errors out; usespecify init . --integration copilot.- Commands became skills. Copilot switched to skills by default in 0.16.0 (August 5), so you type
/speckit-specifyinstead of/speckit.specify. Claude Code gets the same steps as.claude/skills/speckit-<command>/SKILL.md. - A new final step.
/speckit.converge(0.11.2, June 18) checks the finished code against spec, plan and tasks and appends whatever is missing totasks.md. - Two new processes. Bug fixing arrived as the bundled
bugextension in 0.9.5 (June 5) and idea assessment as theassessextension in 0.13.0 (July 17). - Git is optional. Numbered feature branches moved into an opt-in
gitextension. Spec Kit now tracks the active feature in.specify/feature.json, not the checked-out branch. - Windsurf was dropped. The changelog retired the Windsurf integration in 0.12.2 (June 30), noting it was “absorbed into Cognition Devin”;
devinis now an integration key. - New stewardship. Den Delimarsky and John Lam conceived the project; Manfred Riem has been lead maintainer since January 22, 2026, according to the project history. Under him, Spec Kit grew workflows, bundles and catalogs on top of integrations, extensions and presets.
Setup Walkthrough: Install, Initialize, First Spec
You need Python 3.11+, uv and a supported coding agent, on Linux, macOS or Windows (PowerShell scripts work without WSL). Git is only required if you enable the git extension.
# 1. Install the Specify CLI from PyPI
uv tool install specify-cli
specify version
# 2a. New project, wired to Claude Code
specify init my-project --integration claude
cd my-project
# 2b. Or add Spec Kit to a repo that already has code (commit first)
specify init --here --force --integration copilot
Prefer pinning a release from source? The docs recommend uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@v1.2.3; pipx and plain pip work too. Already have an old install? uv tool install specify-cli does not upgrade it. Run specify self upgrade, or uv tool install --force specify-cli if your CLI predates that command (upgrade guide). In CI or any shell that can’t send arrow keys, add --non-interactive; without an explicit --integration, non-interactive runs default to Copilot.
specify init writes a .specify/ folder (templates, scripts, and memory/constitution.md) plus your agent’s skill or command files, for example .claude/skills/speckit-*/SKILL.md for Claude Code or .github/skills/speckit-*/SKILL.md for Copilot. Each feature gets its own directory under specs/, such as specs/001-photo-albums/ with spec.md, plan.md and tasks.md. Init doesn’t touch your application code, but review the diff before you commit it.
Then open your agent in the project directory. The steps run in the agent’s chat, not the terminal, and the spelling depends on the agent (command invocation table):
| Agent or mode | How you call the specify step |
|---|---|
| GitHub Copilot (default skills mode), Claude Code | /speckit-specify |
| Codex CLI, Command Code, ZCode | $speckit-specify |
| Kimi Code | /skill:speckit-specify |
| Notation used throughout the official docs | /speckit.specify |
This post uses the hyphenated form from here on.
The Workflow: Constitution to Converge
The core loop is still specify, plan, tasks, implement. Since March it has gained a closing step and three optional quality gates. The full path for a production feature:
/speckit-constitution once per project: non-negotiable principles
/speckit-specify what and why, no tech stack
/speckit-clarify optional: up to five targeted questions
/speckit-plan tech stack and architecture
/speckit-checklist optional: "unit tests for your requirements"
/speckit-tasks dependency-ordered tasks.md
/speckit-analyze optional: read-only consistency check
/speckit-implement build it
/speckit-converge find gaps, append tasks, repeat until Converged
For small features, the docs’ shorter path skips clarify, checklist and analyze. Run each step on its own and review the output before moving on; the gates only work if a human actually reads what comes out of them.
Constitution
/speckit-constitution writes .specify/memory/constitution.md: testing requirements, performance targets, security policies, compliance rules. Every later phase is checked against it. If your organization requires 80% test coverage and OWASP Top 10 scanning, you encode that once and every spec inherits it. For existing repositories, the existing-project guide warns against inventing standards just to fill the template: use rules that are already true for the codebase, or the constitution produces noise instead of useful constraints.
Specify and Clarify
You describe what you want in terms of user journeys and outcomes. No technical decisions yet.
/speckit-specify Build a photo organizer with albums grouped by date and a tile preview of each album.
The spec captures the “what” and “why” without prescribing the “how”, which lets you explore multiple technical approaches from the same requirements. Where your description is too vague to implement safely, the specify step marks up to three gaps with [NEEDS CLARIFICATION] and asks you to resolve them instead of guessing. /speckit-clarify goes further: up to five targeted questions per run, with your answers written back into spec.md.
Plan
/speckit-plan is where the architecture decisions go: framework, database, patterns.
/speckit-plan Use Vite with vanilla JavaScript. Keep images local and store metadata in SQLite.
The plan and its supporting design documents become the shared context that keeps the agent aligned with your technical choices across sessions.
Tasks and Analyze
/speckit-tasks produces a dependency-ordered tasks.md: a Setup phase, a Foundational phase for blocking prerequisites, one phase per user story in priority order, and a final Polish phase, with parallelizable tasks marked. Run /speckit-analyze before you build. It is a read-only cross-check of spec, plan and tasks that flags problems like a task with no matching requirement or a plan choice that contradicts the spec. Fix issues at the step that owns them, then re-run it until it comes back clean.
Implement and Converge
/speckit-implement executes the tasks in dependency order and treats unchecked checklist items as a gate it asks you about. For large features, scope each run (/speckit-implement Implement only the Setup and Foundational phases) so the agent’s context doesn’t overflow, and verify each stage before the next.
/speckit-converge is the most useful addition of 2026. It compares the codebase with the spec, plan and tasks, never edits code, and either reports Converged or appends the missing work as new tasks. You loop implement and converge until it converges. That closes the gap the original four-phase flow left open: nothing checked whether “all tasks done” actually meant “matches the spec”.
The whole trail lives in specs/ next to the code. When someone asks “why did we build it this way?” six months later, the answer is in the repository, not in someone’s Slack DMs.
Supported Agents: All 41 Spec Kit Integrations
Spec Kit doesn’t ship its own model or agent. An integration teaches one coding agent the Spec Kit steps. As of v1.2.3, the integration directory lists 41 agents, plus generic for anything else and none for agent-neutral scaffolding.
The ones most people look for, with their --integration keys: GitHub Copilot (copilot), Claude Code (claude), Codex CLI (codex), Cursor (cursor-agent), Gemini CLI (gemini), Antigravity (agy), Kiro CLI (kiro-cli), opencode (opencode), Junie (junie), Devin for Terminal (devin), Qwen Code (qwen) and Amp (amp).
The rest: Alquimia AI, Auggie CLI, Cline, CodeBuddy CLI, Command Code, DeepSeek Harness, Docker Agent, Factory Droid, Firebender, Forge, Goose, Grok Build, Hermes, IBM Bob, Kilo Code, Kimi Code, Lingma, MiniMax Code, Mistral Vibe, Muse Code, Oh My Pi, Pi Coding Agent, Qoder CLI, RovoDev, SHAI (OVHcloud), Tabnine CLI, Trae, ZCode and Zed.
Teams rarely standardize on one agent, and Spec Kit now has a documented pattern for that. Commit an agent-neutral project (specify init my-project --integration none), let each developer run specify integration switch claude (or their own agent) in their local checkout, and switch back to none before committing. specify integration install <key> adds a second agent without changing the default. The specs, plans and task lists stay the same whichever agent reads them, so swapping agents later doesn’t cost you your planning history.
“Speckit agents” can also mean something narrower. In Copilot’s optional commands layout (--integration-options="--commands"), Spec Kit installs each step as a Copilot custom agent, an .agent.md file under .github/agents/, which you pick with /agents in Copilot CLI. Fresh installs default to skills instead.
Beyond Feature Specs: Bug Fixes, Idea Checks, Extensions and Presets
Spec Kit 1.x is less a four-step workflow than a kit for building agent processes. The README now offers three entry points:
- Spec-Driven Development, the core process above.
- Bug fixing:
specify extension add bug, then/speckit-bug-assess "Submitting an empty password crashes the login form." slug=login-crash,/speckit-bug-fixand/speckit-bug-test. Reports land in.specify/bugs/login-crash/, and only averifiedverdict counts as fixed (the others arepartialandfailed). - Idea assessment:
specify extension add assessruns intake, research, define, shape and decide, ending ingo,needs-clarificationorkill. No source code required.
Around those sit the customization primitives:
- Extensions add commands, quality gates and hooks. The bundled
githubextension, for example, turnstasks.mdinto GitHub issues and replaces the deprecated core/speckit.taskstoissues. - Presets change templates, terminology and methodology without touching the tooling, for example to require regulatory traceability in every plan. One community demo rewrites specifications as “Voyage Manifests” and tasks as “Crew Assignments” in pirate speak, which shows how far presets reach.
- Workflows chain commands, shell steps and human checkpoints, with loops and pause/resume.
- Bundles package extensions, presets, workflows and workflow steps into one versioned install for a team or role.
- Project-local overrides handle one-off template changes without forking anything.
The community extension catalog lists 183 extensions as of this update, and the preset catalog 42. Search them with specify extension search and specify preset search. The README is explicit that catalog listings “are not audits or endorsements”, so read the source before installing: extensions can register hooks that run on agent lifecycle events. For firewalled environments, the core assets ship inside the Python package so specify init works offline, and private catalogs with token authentication are documented.
Walkthroughs Worth Reading
The docs link seven community walkthroughs, all in maintainer Manfred Riem’s GitHub account and, per the page, not reviewed or endorsed by GitHub. The brownfield ones are the most instructive: a token-authenticated headless REST API added to an ASP.NET CMS of roughly 307,000 lines, and a password-protected admin console added to the Piranha Jakarta EE runtime (about 420,000 lines across 180 Maven modules), both started without existing specs or a constitution. A Go/React telemetry dashboard on NASA’s Hermes ground system runs the whole flow from Copilot CLI in a terminal, no IDE involved.
If you prefer a structured course, Microsoft Learn has a 13-unit module, Implement spec-driven development using the GitHub Spec Kit, built around Copilot in VS Code and a brownfield enterprise scenario.
Honest Limits: Where Spec Kit Costs More Than It Saves
Spec Kit adds upfront time and a lot of Markdown. That trade-off is real, and it’s the main criticism from people who have measured it.
- Markdown volume. Colin Eberhardt at Scott Logic rebuilt a feature with Spec Kit in November 2025: 33.5 minutes of agent time, 2,577 lines of Markdown and about 3.5 hours of review for 689 lines of code. The same outcome with plain iterative prompting took 8 minutes of agent time and 15 minutes of code review. His verdict: “the fastest path is still iterative prompting and review, not industrialised specification pipelines.”
- Review fatigue. Birgitta Böckeler, testing Spec Kit, Kiro and Tessl for martinfowler.com, found it created “a LOT of markdown files” and wrote: “I’d rather review code than all these markdown files.” For a 3-to-5-point story, it “felt like overkill for the size of the problem.”
- Spec-first, not spec-anchored. Böckeler’s sharper point is that a spec written per feature and then forgotten isn’t a source of truth. The 2026 docs now make you choose how specs age: keep each feature folder as a frozen record, maintain
spec.mdas a living contract, or reconcile discoveries back from code. None of these is automatic. - Headless permissions. If you automate Spec Kit workflows through Copilot CLI, headless dispatch adds
--yoloby default, allowing tools, paths and URLs without approval. SetSPECKIT_COPILOT_ALLOW_ALL_TOOLS=0if that’s not what you want (Copilot integration docs). - Context budget in Claude Code. Every Spec Kit skill is model-invocable by default, so its description sits in Claude’s context and competes for the skill-listing budget.
--integration-options="--no-model-invocation"makes the core skills user-invoked only (Claude Code integration docs). - Churn. 235 releases since August 2025, often several a week. Pin a version in CI. The project history says 1.0.0 “did not create or freeze” the model; expect commands and layouts to keep moving.
Eberhardt’s and Böckeler’s tests predate converge, the analyze gate and the shorter path, but the arithmetic still holds: every gate is more text for a human to read. The InfoWorld analysis reaches the same conclusion from the other side: spec-driven development is slower than unguided AI coding and assumes you already have development expertise.
Use Spec Kit when:
- You are building a feature that will ship to production and be maintained, with requirements complex enough to be misread
- You are modifying a large existing codebase where the agent needs structural constraints
- Several developers (or several agents) work on the same project and need a shared understanding
- Compliance or audit requirements demand traceability from requirement to implementation
- You have been burned by plausible-looking AI code that breaks in edge cases
Skip it when:
- You are prototyping a throwaway demo or writing a single-file script
- The change is small enough that reviewing the spec takes longer than reviewing the diff
- You already keep requirements in Jira, Linear or Notion and don’t want to maintain them twice
- Speed to a first working version matters more than long-term maintainability
Spec Kit doesn’t replace developer expertise. It moves that expertise from line-by-line code review to specification review, which pays off only if someone actually reads the specs.
Spec Kit vs. Kiro vs. OpenSpec
Spec Kit is the agent-agnostic option: it runs inside whatever agent you already pay for. Kiro builds a similar requirements, design and tasks flow into AWS’s own IDE, CLI and web app, with paid plans from $20 a month; you can even run Spec Kit inside Kiro CLI through the kiro-cli integration. OpenSpec, at roughly 73,000 stars, is the lighter open-source rival. Each change lives in openspec/changes/ as a proposal, spec deltas, design and tasks, and /opsx:archive folds it back into the main specs when you’re done. Its README calls Spec Kit “Thorough but heavyweight.”
Pick Spec Kit when you want gates, extensions and the biggest agent list. Pick OpenSpec when most of your work is changing existing code and you want less ceremony. Pick Kiro if you want the spec workflow built into the editor and don’t mind its credit-based pricing.
Frequently Asked Questions
What is GitHub Spec Kit?
GitHub Spec Kit is GitHub’s open-source, MIT-licensed toolkit for spec-driven development. It installs commands into your AI coding agent that make it write a specification, a technical plan and a task list before writing code, then implement and check the result against the spec (constitution, specify, plan, tasks, implement, converge). The current release is v1.2.3 (October 2026), and it supports 41 coding agents including GitHub Copilot, Claude Code, Codex, Cursor and Gemini CLI.
How do I install GitHub Spec Kit?
Install Python 3.11+ and uv, then run uv tool install specify-cli and specify init my-project --integration claude (replace claude with your agent’s key, for example copilot, codex or gemini). For an existing repository, run specify init --here --force --integration <key> after committing your work. Then open your agent in the project and run /speckit-constitution and /speckit-specify in its chat. The old --ai flag was removed in version 0.10.0, so tutorials that use it no longer work.
Which AI coding agents does Spec Kit support?
As of v1.2.3, Spec Kit lists 41 agent integrations, including GitHub Copilot, Claude Code, Codex CLI, Cursor, Gemini CLI, Antigravity, Kiro CLI, opencode, Junie, Devin for Terminal, Qwen Code, Amp, Goose, Cline and Kilo Code. A generic integration covers other agents, and none creates agent-neutral scaffolding for mixed teams. Windsurf support was retired in June 2026.
How is Spec Kit different from Kiro IDE?
Kiro is AWS’s commercial agentic IDE (also available as a CLI and web app) with spec-driven development built in and credit-based plans from $20 per month. Spec Kit is a free, open-source toolkit that adds a spec-driven workflow to the coding agent you already use. Spec Kit works across 41 agents, including Kiro CLI, while Kiro is a single product with its own editor, models and pricing.
Is Spec Kit worth the extra time compared to direct AI coding?
For production features with complex requirements, often yes; for small changes, usually not. In one measured test, Spec Kit produced 2,577 lines of Markdown and about 3.5 hours of review for 689 lines of code, while plain iterative prompting reached the same result much faster. The trade-off favors Spec Kit when code must be maintained long-term, several people or agents share the work, or you need traceability from requirements to implementation.
