GitHub Spec Kit: A Practical Guide and Where It Fits Your SDD Workflow

GitHub Spec Kit makes intent the source of truth by routing an AI coding agent through versioned design artifacts, then task files, so the agent executes against repository artifacts instead of a chat transcript.

An AI coding agent adds a repository layer to a service that already routes every query through a shared data-access package. Forty minutes earlier in the same session, the model agreed to reuse that package. The model no longer remembered the earlier agreement, so it chose a pattern common in its training data but absent from this codebase. The pull request passes lint, and a reviewer identifies the mismatch during code review.

A vague prompt "forces the model to guess at potentially thousands of unstated requirements," per GitHub's September 2, 2025, Spec Kit announcement. Spec Kit answers with files the agent has to read before it writes code, and with checkpoints where a human corrects the files before any code exists.

A developer weighing Spec Kit on a codebase they already maintain gets the v1.0.6-pinned install, the constitution, the four core commands and the files each writes. It also covers the clarify and analyze gates, agent integration, and the point where the approach stops paying, while skipping the Jira extension, the checklist and taskstoissues commands, and preset authoring beyond the FAQ.

What GitHub Spec Kit Is and the Problem It Solves

GitHub publishes Spec Kit as an MIT-licensed command-line tool named specify-cli. It scaffolds a .specify/ directory in a repository and installs slash commands into whichever AI coding agent the developer already uses. The project's integrations reference names more than 50 supported AI coding agents as of September 14, 2026, and Den Delimarsky's launch post on the GitHub Blog frames the shift as intent replacing code as the source of truth. Spec Kit ships no model or agent of its own; it supplies the files and sequence.

The failure it targets is what the launch post calls vibe coding: describe a goal, receive a block of code that looks right but doesn't quite work, as the reused-package example above showed. The post scopes that failure to serious applications and existing codebases, where the agent's assumptions collide with conventions it never saw.

The developer states what to build and why in /speckit.specify, the agent writes spec.md, and the developer edits it before /speckit.plan reads it. Each artifact lives in the repository, so the constraint that left the model's active context now sits in a file the agent reads at each command.

Spec-Driven Development as a Discipline

Spec-driven development (SDD) means writing the spec before writing code with AI, and treating that spec as the source of truth for both the human and the model. A structured, behavior-oriented natural-language artifact that guides coding agents: that is how Birgitta Böckeler defines the spec, in an SDD article dated October 15, 2025. Böckeler's taxonomy starts with spec-first tools, which write the spec before code, then moves to spec-anchored tools, which keep the spec after the task ends to guide maintenance. At the third level, spec-as-source tools make the spec the file humans edit and treat code as generated output. She places Spec Kit at the first level, calling it "spec-first only, not spec-anchored over time."

The agent reads spec.md directly as context. GitHub added the /speckit.converge command in v0.11.2, and its template treats the design artifacts in spec.md and plan.md as part of the sole source of intent when converge audits finished code. The work that tasks.md records completes that source.

Installing and Initializing Spec Kit

GitHub tagged v1.0.6 as the current stable release on September 10, 2026, and the author captured every command and path here against that tag. The project has moved through more than 180 release tags since v0.0.17 in September 2025, so flags and paths shift between minor versions, and pinning keeps a team on one file layout.

uv is the documented default installer. These two commands install the pinned v1.0.6 binary and initialize a project for Claude Code.

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@v1.0.6
specify init my-project --integration claude

The init run against v1.0.6 writes the scaffold and the Claude Code skill files. The following list trims the output to the paths it creates.

specify init my-project --integration claude
my-project/.specify/
my-project/.claude/skills/
my-project/CLAUDE.md

Those paths come from the project's integrations reference. Passing --integration copilot writes .github/skills/ and .github/copilot-instructions.md in their place. Both integrations create the shared .specify/ infrastructure alongside their own agent-specific files. specify init checks for the agent's CLI tool; --ignore-agent-tools skips that check.

A one-off run with no persistent install uses uvx, and --here initializes the current directory.

uvx --from git+https://github.com/github/spec-kit.git@v1.0.6 specify init --here --integration copilot

The project homepage describes the v1.0.6 scaffold below. The tree trims it to one script directory and the commands discussed here.

.specify/
├── memory/
│   └── constitution.md
├── scripts/
│   └── bash/
│       └── create-new-feature.sh
└── templates/
    ├── spec-template.md
    ├── plan-template.md
    ├── tasks-template.md
    ├── constitution-template.md
    └── commands/
        ├── analyze.md
        ├── clarify.md
        ├── implement.md
        ├── plan.md
        ├── specify.md
        └── tasks.md

scripts/bash/ appears with the default --script sh on Linux and macOS, while Windows defaults to --script ps. Spec Kit maintainers added the py script type in v0.12.4, and --script py selects it. No specs/ directory exists yet; the project documentation places /speckit.specify output at specs/<NNN>-<feature-name>/.

Writing a Constitution That Constrains the Agent

constitution.md at .specify/memory/constitution.md holds the project-level rules Spec Kit applies to every feature. specify init seeds it once from constitution-template.md, and /speckit.constitution fills it in with the high-level principles that are immutable and apply to every change. The upgrade documentation reserves hash-based safety for a different command. specify integration upgrade <key> compares on-disk files against the recorded install manifest, stops and asks for review when a managed file was edited after install, and refreshes only what still matches. specify init --force skips those per-integration manifest checks entirely; it overwrites the managed scaffold without comparing hashes, though it leaves an existing constitution alone. A preset install or removal never rewrites a constitution that a developer has authored.

A constraint changes agent behavior when it names a checkable gate. The Spec Kit repository's own constitution gates work on ruff and pytest, plus markdown lint and CodeQL. /speckit.converge reads the constitution as the governing constraints when it audits tasks.md against the code. A principle written in that shape for the opening example's service looks like the following excerpt.

## III. Data Access
All persistence goes through the shared `data_access` package. A task that adds a
repository abstraction or direct persistence query outside that package is out of
scope and MUST be rewritten as a change to `data_access` before it is marked [X].

The model interprets compliance; Böckeler notes that the AI judges checklist adherence with no guarantee of enforcement.

How Commands Produce Artifacts

The core command set contains four commands, and each reads the artifact generated by the preceding command. The project documents nine commands in total: those four plus constitution and converge, and three optional quality gates, clarify, checklist, and analyze. Most agents invoke them as /speckit.*, while Codex CLI and Command Code in skills mode use $speckit-*, a hyphenated prefix those integrations require in place of the dot form. The agentic SDD reference states that the workflow requires only /speckit.specify before /speckit.plan; the remaining order is a recommendation.

For the opening example's feature, the spec.md /speckit.specify writes contains behavior only, with no stack decisions.

## User Journeys
A support engineer searches archived tickets by customer ID and sees matching
tickets ordered by most recent activity.

## Success Criteria
- Search by customer ID returns results for accounts holding up to 10,000
  archived tickets within 2 seconds.

The plan.md that /speckit.plan writes for the same example names the stack and records the reuse decision the constitution requires.

## Technical Context
Python with FastAPI handlers and PostgreSQL; no new persistence layer.

## Data Access
Archived-ticket queries extend the shared `data_access` package.

## Contracts
GET /tickets/search?customer_id=<id>&archived=true returns tickets by last activity

/speckit.tasks turns that spec into checkbox lines, and implement marks each one [X] in place as it lands.

## Phase 2: Query Layer
- [X] T001 Add an archived-ticket query to the shared `data_access` package
- [ ] T002 Extend the `data_access` customer-ID filter to cover archived rows
- [ ] T003 Call the new `data_access` query from the ticket search handler

Specify stores the feature path in .specify/feature.json, so later commands resolve the feature from that file rather than the checked-out branch, and Git is not required. /speckit.converge follows implement, appends one checklist item per gap it finds, and repeats the loop.

Clarify and Analyze Before Things Compound

/speckit.clarify runs between specify and plan, updates spec.md in place, and re-validates checklists/requirements.md. It targets the underspecified area that would otherwise become an architectural guess: in the opening example, whether the feature reuses the shared data-access package or adds its own layer. /speckit.analyze runs after tasks as a read-only consistency and coverage report across the design artifacts in spec.md and plan.md and the work in tasks.md; it never edits a file. A requirement with no task, or a task referencing an undefined contract, appears in that report while it still costs one edit to fix.

Extensions add commands and templates; presets ship ready-made workflows such as assess and bug, and a team can override any of it through .specify/templates/overrides/.

Compatible AI Coding Agents

The launch post named GitHub Copilot, Claude Code, and Gemini CLI, and the homepage list has grown since. Compatible means specify init writes the command files into the directory that the agent scans for user-defined slash commands, so the agent registers /speckit.plan as a command and resolves the versioned template from disk on each invocation. Without that registration, a developer falls back to prompt injection: pasting the template text into the prompt as ordinary prose every run, with no argument substitution.

Claude Code reads .claude/skills/, and Copilot reads .github/skills/ by default since v0.16.0 on August 5, 2026. Gemini CLI reads .gemini/commands/<command>.toml, as the integrations reference documents. Markdown-based integrations substitute the user's text into $ARGUMENTS; Gemini's TOML uses {{args}}. Kiro CLI is a prose fallback with no $ARGUMENTS substitution. A developer on that fallback supplies the command text and the feature description together on every run.

Design input can enter at specify: a developer can paste get_design_context output from Figma's Dev Mode Model Context Protocol (MCP) server into the /speckit.specify prompt. That output represents design and behavior, not final code style, per Figma's own dev-mode MCP guide.

Where Spec Kit Fits an Existing SDD Workflow

Spec Kit scopes a project to the directory containing .specify/ and assumes one agent command directory. The team commits Markdown artifacts alongside the code. Each project owns its constitution with no inheritance for shared rules, so a monorepo with several .specify/ folders synchronizes constitutions by hand. A version pin matters here because paths have moved, including Claude Code's from .claude/commands/ to .claude/skills/ in v0.14.2.

• Greenfield: Spec Kit fits new work best. "0-to-1 Development" is a first-class phase in the README, and it rates best for greenfield spec workflows among the tools in this site's spec-driven development tool comparison, published February 23, 2026. A new service has no conventions to violate.
• Bounded change in an existing repository: The existing-projects guide, published with v1.0.1 on August 21, 2026, says to initialize in place, capture the rules that matter, and treat the codebase as context while spec.md defines only the intended change. It also says to write the constitution and any template overrides before the first /speckit.specify. Skipping that step leaves init producing generic templates: an anecdotal community report in closed issue #1436 says the result reflects none of an existing project's architecture, stack, or conventions.
• Legacy modernization: Spec Kit fits this case worst. The launch post promises to rebuild a system from a modern spec, but documenting the entire system as the first feature is what the existing-projects guide warns against. Large existing applications are impractical to spec within context limits, per Hari Krishnan's February 19, 2026, InfoQ article.

Modernization that spans repositories over days outgrows a single-agent slash-command flow. Augment Code offers Cosmos, a unified cloud agents platform, on all paid plans, and Cosmos coordinates agent work across the software development lifecycle. Environments define which repositories and systems each agent can access, Experts define agent behavior, and Sessions preserve the auditable record of long-running work.

Where Spec Kit Runs Out of Road

Context pressure limits Spec Kit inside a single agent conversation, and the documented guidance scopes it to bounded changes inside one .specify/ project.

• Context pressure: teams hit instruction bloat and "context rot," per Thoughtworks' Technology Radar entry dated April 15, 2026.
• Task bloat: An anecdotal community report in issue #1136 describes hundreds of tasks across 2,000 lines of tasks.md, at which point any edit touches large areas of the file.
• Multi-repository spans: Community discussion #746 asks where a spec lives when one feature changes many repositories, and the six-repository case is unanswered by the tooling, per Krishnan's InfoQ article.

The documented commands read their required artifacts directly, and Spec Kit provides no documented layer that chunks a large tasks.md or schedules which part the agent sees. Correct for that inside Spec Kit by cutting features until tasks.md fits one implement pass, splitting a monorepo into one .specify/ per package, and keeping the constitution to gating rules.

Beyond that, the mechanism that survives is retrieval keyed to code structure. The Context Engine maps relationships and tracks dependencies across hundreds of thousands of files through syntax and call graphs. Its MCP server has a remote mode that supplies cross-repository context to a connected agent. The Augment GitHub App re-indexes connected repositories when commits land on the default branch, documented in the MCP overview. For the multi-repository span raised in discussion #746, a Cosmos Environment declares the set of repositories an agent can reach. On long-running modernization work, Cosmos Sessions hold the record across runs rather than ending with one conversation. Cosmos Experts carry the same behavior definition into each new Session.

Alternatives Worth Knowing About

BMAD-METHOD and Kiro wrap a spec flow in role agents or an IDE. Cosmos addresses multiple-repository work through Environments and Context Engine retrieval. The author read Kiro's published pricing on September 14, 2026, to support the Kiro row.

Kiro's hooks fire shell commands on session events, providing deterministic enforcement bound to Kiro's own agent. Spec Kit runs on any agent the homepage lists and enforces nothing outside the model's reading of the constitution. Spec Kit covers greenfield single-repository work, and Cosmos provides a context foundation when the same specs must survive across repositories and Experts.

What to Do Next

The tradeoff is four Markdown artifacts and a constitution per feature, in exchange for decisions that outlive the chat window. Pin the install to v1.0.6, initialize it in place, and write the constitution and any template overrides before the first specify. Use one bounded feature to test whether specify, clarify, plan, tasks, implement, and converge keep the repository-layer constraint visible.

Frequently Asked Questions

Related Reading

• 6 Best Spec-Driven Development Tools for AI Coding in 2026
• 6 Best Kiro Alternatives for Spec-Driven Development
• 5 Best AI Spec Review Tools for Development Teams (2026)
• 7 Best Cursor Alternatives for Enterprise Teams in 2026
• Why Cursor Freezes on Large Codebases: 5 Alternatives