Harnesses > Spec-driven toolkits
Spec Kit
Draft. This entry has not been checked against its sources yet.
GitHub's spec-driven development toolkit. A Python CLI installs ten commands, page templates, and scripts into a project for one of 40 coding agents; the commands turn a feature description into a spec, a plan, and a task list, then implement the tasks and check the code against those documents.
| Maintainer | GitHub (lead maintainer Manfred Riem, mnriem) |
|---|---|
| Category | Spec-driven toolkits |
| Hosts | Claude Code, Cursor, Codex, Gemini CLI, OpenCode, GitHub Copilot, Factory Droid, Pi, oh-my-pi, Cline, Kiro, Qwen Code, Kimi Code CLI, Antigravity, Grok Build CLI, Devin CLI, Hermes Agent, Muse, Alquimia AI, Amp, Auggie (Augment CLI), IBM Bob, CodeBuddy, Command Code, DeepSeek Harness, Docker Agent, Firebender, ForgeCode, Goose, Junie, Kilo Code, Lingma, Mistral Vibe, Qoder, Rovo Dev, SHAI, Tabnine, Trae, ZCode, Zed |
| Components | 10 skills |
| License | MIT |
| Version | 1.0.12 |
| Source code | https://github.com/github/spec-kit |
| Website | https://github.github.io/spec-kit/ |
| Docs | https://github.github.io/spec-kit/reference/overview.html |
| DeepWiki | https://deepwiki.com/github/spec-kit |
| Last researched | 2026-09-28, at commit c00dc05 |
Features
Definitions are on the compare page.
| Feature | Supported | Notes |
|---|---|---|
| Stages of work it covers | ||
| Brainstorming | yes | speckit-specify asks at most three questions, each with a table of options, and writes the answers into spec.md. speckit-clarify (optional) asks up to five more, one at a time. |
| Written plans | yes | speckit-plan writes plan.md, research.md, data-model.md, contracts/, and quickstart.md to specs/<NNN-feature>/; speckit-tasks then writes tasks.md. |
| Test first | partial | Test tasks are 'OPTIONAL - only include them if explicitly requested'. When included, they come first and must fail before the code (templates/tasks-template.md). |
| Debugging process | yes | Opt-in bug extension: assess records a reproduction and a root-cause hypothesis before any fix; fix stops and sends you back to assess if the cause is elsewhere. |
| Code review | partial | speckit-converge checks the code against the spec, plan, tasks, and constitution and appends missing work as tasks. It runs in the same session; there are no code-quality reviewers or reviewer subagents. |
| Verification | partial | speckit-implement says to 'Validate that tests pass' but asks for no output. The opt-in bug-test step records commands, exit status, and output excerpts. |
| Learning capture | no | No lessons store. The constitution and specs stay in the repository, and later commands read the constitution. |
| Branch to PR | partial | The opt-in git extension creates numbered feature branches and can commit before or after each command (off by default). No pull request step. |
| How it runs | ||
| Single entry point | no | The README calls its three processes 'independent entry points'. specify workflow run speckit chains specify, plan, tasks, and implement, always in that order. |
| Automatic activation | partial | On Claude Code the skills are marked model-invocable, but the README says to invoke each step yourself. Hosts that get command files, such as Gemini CLI, run them only when typed. |
| Session-start hook | no | Installs no host hooks. Its 'hooks' are entries in .specify/extensions.yml that each command tells the agent to check and run. |
| Blocking hooks | no | No host hooks by default. Its extension hooks are instructions the agent is asked to run. |
| Subagents | partial | No subagent definitions. speckit-plan says to 'dispatch research agents', and the docs suggest asking implement to delegate tasks. specify workflow run starts a headless agent per step. |
| Parallel agents | partial | tasks.md marks independent tasks [P] and implement says they 'can run together'; whether they do is left to the host or your prompt. |
| Git worktrees | no | The git extension works with branches in the current checkout. |
| Adopting it | ||
| Multiple hosts | yes | 41 built-in integrations: 40 named agents and a generic one for any agent that reads a commands folder. |
| Per-project setup | yes | specify init writes everything into .specify/ and the agent's folder in the repository. Hermes is the exception: its skills go to ~/.hermes/skills/. |
| Team extensions | yes | Documented extensions, presets, project-local template overrides, workflows, and bundles. The catalogs list 175 community extensions and 40 community presets. |
| No extra services | yes | Needs Python 3.11+ and uv or pipx for the CLI. speckit-taskstoissues needs the GitHub MCP server in the host. |
How it works
Spec Kit has two parts. The specify CLI, a Python package, is the installer: specify init renders ten command templates into the format your agent reads and copies page templates and scripts into the project. Later, specify extension add, specify preset add, and specify integration upgrade change what is installed. The harness is what lands in the repository: the commands, templates, scripts, and a constitution file.
The workflow
The README offers three processes as "independent entry points, not three mandatory phases": spec-driven development (SDD), which ships in core, and bug fixing and idea assessment, which are bundled extensions you add. The core sequence is "Constitution once per project; specify → plan → tasks → implement → converge per feature". You run each step yourself in the agent's chat and review its output before the next one. On Claude Code a step is a skill invoked as /speckit-plan; the reference docs write it as /speckit.plan, and Codex uses $speckit-plan.
- Constitution (
speckit-constitution). Fills.specify/memory/constitution.mdwith the project's principles and a version number. Every later command reads it. - Specify (
speckit-specify). Turns your description intospecs/<NNN>-<short-name>/spec.md: user stories with priorities, testable functional requirements, and measurable success criteria. It covers "WHAT users need and WHY" and leaves out the tech stack. The agent fills gaps with stated assumptions and may mark at most three points[NEEDS CLARIFICATION], which it puts to you as questions with suggested answers. It then checks the spec against a quality checklist (checklists/requirements.md) and revises it up to three times. - Clarify (optional). Scans the spec for gaps by category and asks up to five questions, one at a time, each with a recommended answer. Answers go into the spec.
- Plan (
speckit-plan). You give the tech stack. The agent fills in the technical context, checks it against the constitution ("ERROR if violations unjustified"), writesresearch.mdto resolve unknowns, thendata-model.md,contracts/, andquickstart.md, and checks the constitution again. - Checklist (optional). Writes checklists that test the requirements, which the command calls "Unit Tests for English", not the code.
- Tasks (
speckit-tasks). Writestasks.md: setup, foundational work, one phase per user story in priority order, then polish. Every line has an ID, a parallel marker where it applies, a story label, and a file path, for example- [ ] T012 [P] [US1] Create User model in src/models/user.py. - Analyze (optional). A read-only check that the spec, plan, and tasks agree and cover each other. Conflicts with the constitution are always CRITICAL.
- Implement (
speckit-implement). If any checklist has unchecked items, it stops and asks whether to continue. It sets up ignore files, runs the tasks phase by phase with test tasks before their code, halts when a sequential task fails, and ticks each task off intasks.md. - Converge (
speckit-converge). Compares the code with the spec, plan, tasks, and constitution, sorts each gap as missing, partial, contradicts, or unrequested, and appends them as a newPhase N: Convergenceintasks.md. You repeat implement and converge until it reports converged; it then suggests a review or a pull request.
speckit-taskstoissues optionally turns tasks into GitHub issues through the GitHub MCP server.
From the terminal, specify workflow run speckit -i spec="..." runs specify, plan, tasks, and implement in order. Each step is a separate headless call to the agent's CLI (for example claude -p), with approve-or-reject gates after the spec and after the plan. The run can be resumed with specify workflow resume. It does not run converge.
Bug fixing (specify extension add bug): speckit-bug-assess, speckit-bug-fix, speckit-bug-test, with one report per step in .specify/bugs/<slug>/. Assess decides whether the report is a real bug, writes reproduction steps and a root-cause hypothesis, and does not touch code. Fix changes only the files the assessment named; if the assessment proves wrong, it stops and recommends assessing again. Test re-runs the reproduction and the tests and returns verified, partial, or failed. The README: "Missing verification is not a successful fix."
Idea assessment (specify extension add assess): intake, research, define, shape, and decide, ending in go, needs-clarification, or kill. A go can be handed to speckit-specify.
Components
Counted by running specify init --integration claude --script sh from the researched commit into an empty folder and listing the result with find. One Claude Code install writes 30 files:
- 10 skills in
.claude/skills/speckit-*/SKILL.md, 2,485 lines in total:constitution,specify,clarify,plan,checklist,tasks,analyze,implement,converge, andtaskstoissues. They are generated fromtemplates/commands/. Hosts that take command files get the same ten as commands instead, for example TOML files in.gemini/commands/for Gemini CLI. The same run for Cursor, Codex, Copilot, and Gemini CLI also wrote 30 files each. - 5 page templates in
.specify/templates/: spec, plan, tasks, checklist, and constitution. - 6 bash scripts in
.specify/scripts/bash/that create the feature folder, find the current feature, check prerequisites, and pick the template to use.--script psor--script pyinstalls PowerShell or Python versions instead. - The constitution (an unfilled copy of the template), the
speckitworkflow definition, and 7 metadata files: two manifests with a SHA-256 hash of every installed file, init options, integration settings, a workflow registry, a constitution-source record, and.specify/.gitignore. - No subagent definitions, no hooks, no MCP servers, and no change to
CLAUDE.md.
Bundled in the package but not installed by default: four extensions (git with 5 commands, bug with 3, assess with 5, and agent-context with 1) and two presets (lean, which shortens the core prompts, and constitution-sync). With all four extensions added, a Claude Code project has 24 skills and still no host hooks. The repository's community catalogs list 175 extensions, 40 presets, 2 workflows, and 3 bundles.
How it steers the agent
All steering is prompt text and scripts. Nothing blocks a tool call.
- Templates as structure. The spec, plan, and tasks templates fix the sections, and placeholder blocks are marked "ACTION REQUIRED". The spec checklist includes "No implementation details (languages, frameworks, APIs)".
- Marked uncertainty. Unknowns become
[NEEDS CLARIFICATION]markers, capped at three in specify and five questions in clarify, so the agent guesses openly instead of silently. - The constitution as authority. Analyze and converge call it "non-negotiable", and plan has a gate that must pass before research starts.
- Stops that ask you. Implement stops on unchecked checklist items. Workflow runs pause at gates. Otherwise you start each step yourself.
- Strict formats. Task lines follow one format, with correct and wrong examples. Converge may only append to
tasks.mdand must leave it "byte-for-byte unchanged" when nothing is left. - Closing checklists. Every command ends with a "Done When" list and a "Mandatory Post-Execution Hooks" section: "You MUST complete this section before reporting completion to the user."
- Prompt-level hooks. Extensions register
before_*andafter_*commands in.specify/extensions.yml. Each core command tells the agent to read that file and run the mandatory ones, noting that "Emitting the block alone does not run the hook." Whether they run depends on the model. The CLI can also write native host hooks for extensions that declare them; no bundled extension does.
Files it writes
- Feature folders:
specs/<NNN>-<short-name>/withspec.md,checklists/,plan.md,research.md,data-model.md,contracts/,quickstart.md, andtasks.md. Numbers are sequential by default; timestamps are an option. Each later command reads the earlier files, and analyze and converge read all three core documents. - Constitution:
.specify/memory/constitution.md, read by specify, plan, tasks, implement, analyze, and converge. - Current feature:
.specify/feature.json, a pointer used by later commands. It is git-ignored as per-checkout state. - Extension reports:
.specify/bugs/<slug>/and.specify/assessments/<slug>/. - Workflow state:
.specify/workflows/runs/<run_id>/. - Agent context file: only with the opt-in
agent-contextextension, which keeps a marked section inCLAUDE.md,AGENTS.md, or similar pointing at the current plan.
There is no lessons file. What happens to specs after requirements change is left to the team; docs/concepts/spec-persistence.md describes three options and says "None is the default".
Install
Install the CLI once per machine. It needs Python 3.11+ and uv:
uv tool install specify-cli
The installation guide recommends pinning a release from the repository instead: uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@vX.Y.Z. pipx and pip also work, and uvx runs it once without installing.
Then, in the project:
specify init --here --integration claude
Replace claude with your agent's key, for example copilot, cursor-agent, codex, gemini, or opencode. Without --integration, init asks; in a non-interactive session it picks Copilot. For agents with a CLI, init checks that the CLI is installed; --ignore-agent-tools skips the check. In an existing repository the guide says to commit first and add --force. Commit the result so the team shares it. To add another agent to the same project, run specify integration install <key> (automatic only for integrations marked multi-install safe, Claude Code among them). Add extensions with specify extension add bug. specify integration upgrade keeps files you have edited unless you pass --force.
The 40 named integrations: Alquimia AI, Amp, Antigravity, Auggie CLI, Claude Code, Cline, CodeBuddy CLI, Codex CLI, Command Code, Cursor, DeepSeek Harness, Devin for Terminal, Docker Agent, Factory Droid, Firebender, Forge, Gemini CLI, GitHub Copilot, Goose, Grok Build, Hermes Agent, IBM Bob, Junie, Kilo Code, Kimi Code, Kiro CLI, Lingma, Mistral Vibe, Muse Code, Oh My Pi, opencode, Pi Coding Agent, Qoder CLI, Qwen Code, RovoDev, SHAI, Tabnine CLI, Trae, ZCode, and Zed. For anything else, --integration generic --integration-options="--commands-dir <path>" writes the commands to a folder you choose. Some hosts have limits: Hermes installs skills globally rather than per project, taskstoissues does not work on Pi without an MCP extension, and Kiro CLI does not substitute arguments, so Spec Kit adds a prose fallback.
Git is needed only for the git extension.
When to choose it
- You want each feature to start from a written spec and plan in the repository that a person reviews before any code is written.
- Your team uses different agents. One repository layout works for 40 of them, and several can be installed side by side.
- You want to adapt the process to your organization with presets, extensions, and template overrides rather than by forking.
- You want to run the steps one at a time and read each document before moving on.
When not to
- You want the process to apply without anyone starting it. Nothing loads at session start, and each step is a command you run.
- You want test-first by default. Tests are written only when the spec or the user asks for them.
- You want independent code review. Converge checks the code against the spec in the same session; there are no reviewer subagents and no quality or security pass unless you add a community extension.
- You want the agent to learn from past work. There is no lessons store.
- Your changes are small. Each feature gets a spec, a checklist, a plan, research notes, a data model, contracts, a quickstart guide, and a task list. The
leanpreset cuts this down to a spec, a plan, and a task list. - Your features are large. The docs warn that a long implement run can "lose track of the plan", usually around context compaction, and suggest running one phase or a range of tasks at a time.
- You want a stable process. The changelog lists 228 releases between August 2025 and September 2026.
The methodology essay spec-driven.md describes "Phase -1" plan gates and a "NON-NEGOTIABLE" test-first rule that the shipped templates no longer contain. Trust the templates over the essay.
Sources
- github/spec-kit at c00dc05:
README.md,spec-driven.md,templates/,scripts/,extensions/,presets/,workflows/,integrations/catalog.json,src/specify_cli/(command_init.py,integrations/,events/,workflows/),docs/,CHANGELOG.md,.github/CODEOWNERS - A test install from that commit:
specify initfor Claude Code, Cursor, Codex, Copilot, and Gemini CLI, andspecify extension addfor the four bundled extensions - Spec Kit documentation (linked from the README; read from
docs/in the repository rather than the live site) - DeepWiki was not used: it was unreachable from the research environment.