agentharnesses.dev

A field guide to agentic coding harnesses, for teams that have been told to adopt one.


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.

MaintainerGitHub (lead maintainer Manfred Riem, mnriem)
CategorySpec-driven toolkits
HostsClaude 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
Components10 skills
LicenseMIT
Version1.0.12
Source codehttps://github.com/github/spec-kit
Websitehttps://github.github.io/spec-kit/
Docshttps://github.github.io/spec-kit/reference/overview.html
DeepWikihttps://deepwiki.com/github/spec-kit
Last researched2026-09-28, at commit c00dc05

Features

Definitions are on the compare page.

FeatureSupportedNotes
Stages of work it covers
Brainstormingyesspeckit-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 plansyesspeckit-plan writes plan.md, research.md, data-model.md, contracts/, and quickstart.md to specs/<NNN-feature>/; speckit-tasks then writes tasks.md.
Test firstpartialTest 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 processyesOpt-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 reviewpartialspeckit-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.
Verificationpartialspeckit-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 capturenoNo lessons store. The constitution and specs stay in the repository, and later commands read the constitution.
Branch to PRpartialThe 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 pointnoThe README calls its three processes 'independent entry points'. specify workflow run speckit chains specify, plan, tasks, and implement, always in that order.
Automatic activationpartialOn 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 hooknoInstalls no host hooks. Its 'hooks' are entries in .specify/extensions.yml that each command tells the agent to check and run.
Blocking hooksnoNo host hooks by default. Its extension hooks are instructions the agent is asked to run.
SubagentspartialNo 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 agentspartialtasks.md marks independent tasks [P] and implement says they 'can run together'; whether they do is left to the host or your prompt.
Git worktreesnoThe git extension works with branches in the current checkout.
Adopting it
Multiple hostsyes41 built-in integrations: 40 named agents and a generic one for any agent that reads a commands folder.
Per-project setupyesspecify init writes everything into .specify/ and the agent's folder in the repository. Hermes is the exception: its skills go to ~/.hermes/skills/.
Team extensionsyesDocumented extensions, presets, project-local template overrides, workflows, and bundles. The catalogs list 175 community extensions and 40 community presets.
No extra servicesyesNeeds 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.

  1. Constitution (speckit-constitution). Fills .specify/memory/constitution.md with the project's principles and a version number. Every later command reads it.
  2. Specify (speckit-specify). Turns your description into specs/<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.
  3. 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.
  4. Plan (speckit-plan). You give the tech stack. The agent fills in the technical context, checks it against the constitution ("ERROR if violations unjustified"), writes research.md to resolve unknowns, then data-model.md, contracts/, and quickstart.md, and checks the constitution again.
  5. Checklist (optional). Writes checklists that test the requirements, which the command calls "Unit Tests for English", not the code.
  6. Tasks (speckit-tasks). Writes tasks.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.
  7. Analyze (optional). A read-only check that the spec, plan, and tasks agree and cover each other. Conflicts with the constitution are always CRITICAL.
  8. 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 in tasks.md.
  9. 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 new Phase N: Convergence in tasks.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:

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.

Files it writes

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

When not to

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