github/spec-kit: your agent writes the spec first

Every time you vibe-code a feature, the agent makes hundreds of implicit decisions without telling you: which auth pattern to use, whether to put logic in the service layer or the controller, how to handle errors, whether to mock or use real DB fixtures in tests. Those decisions are invisible, hard to review, and almost impossible to reverse cleanly.

github/spec-kit (103K stars, MIT license) is GitHub's answer to this: a Spec-Driven Development (SDD) toolkit that forces the agent to write down — and get your approval for — every architectural decision before it produces code.1 As the README puts it, specifications become executable: intent is the source of truth, not code.2

It hit a viral wave this week across Reddit, X, and dev.to — and while some of the "GitHub just released this!" takes were inaccurate (the project is 9 months old), the underlying tool is genuinely worth the attention.3

What it does

spec-kit installs a set of slash commands (or equivalent workflow files) into your project that walk an AI coding agent through five sequential phases:

Phase	Command	What happens
Constitution	(setup)	Defines immutable project rules: dependency allowlist, minimum test coverage, type strictness, error handling conventions
Specify	`/specify`	Agent turns your feature description into a structured spec — with automatic branch creation, semantic naming, and a `spec.md` file
Plan	`/plan`	Agent reads the spec, checks constitutional compliance, then produces `plan.md`, `data-model.md`, API contracts, and a quickstart guide
Tasks	`/tasks`	Agent decomposes the plan into an executable `tasks.md` with parallelization markers (`[P]`)
Implement	(per task)	Agent works through tasks one at a time, each with defined acceptance criteria

The architecture surface — spec.md, plan.md, tasks.md — sits in specs/<branch-name>/ and is fully reviewable, version-controlled, and portable across agents.1

The constitution is the part users consistently underestimate. It acts as a standing enforcement layer: once you spend an hour writing strict rules (dependency allowlist, coverage minimums, style constraints), the agent self-polices for the entire project.4 Article III of the default constitution is explicit about TDD: "This is NON-NEGOTIABLE: All implementation MUST follow strict Test-Driven Development. No implementation code shall be written before: 1. Unit tests are written, 2. Tests are validated and approved by the user, 3. Tests are confirmed to FAIL."2

Agents supported: 28 named integrations including Claude Code, GitHub Copilot, Gemini CLI, Cursor, Codex CLI, Windsurf, Devin, Kimi Code, Goose, Roo Code, and 18 others — plus a generic fallback for anything not on the list.5

Install

Prerequisites: Linux, macOS, or WSL2; Python 3.11+; uv; Git.

uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>

Or install as a persistent CLI tool:

uv tool install --from git+https://github.com/github/spec-kit.git specify-cli

The initializer creates a .specify/ directory (containing constitution.md, templates, and scripts) and the agent-specific command directory — for Claude Code, that means .claude/commands/ with /specify, /plan, and /tasks ready to go.1

⚠️ There is a PyPI typosquatter using a similar package name. Install only from the github/spec-kit repository URL above — not from pip install.6

To add a second agent to the same project (multi-install is supported in v0.8.5+):

specify integration install cursor
specify integration list

What a real session looks like

Start with a detailed natural-language description — the more specific the input to /specify, the more precise the spec.7

/specify
Add a rate-limiting layer to the public API. Each IP address should be limited
to 100 requests per minute. Return 429 with a Retry-After header when exceeded.
Use Redis for the sliding window counter.

spec-kit creates a branch, generates spec.md with structured requirements, then waits for your review. Once approved, run /plan. The plan phase is where spec-kit earns its overhead: user u/jokiruiz, after two months with Claude Code, described the /plan step as "the biggest surprise — it caught and blocked 3–4 bad architecture decisions before a single line of code was written."6

After reviewing plan.md, run /tasks. The resulting tasks.md includes parallelization markers — tasks tagged [P] can run concurrently in a multi-agent setup or simply tell you the order doesn't matter.

Portability is a real feature, not marketing copy. The same spec works across agents without modification: generate initial code with Claude Code, hand the spec to Cursor for test refactoring — it picks up without context loss.4

Honest caveats

spec-kit's community feedback is unusually candid, and the criticisms are real.

Token costs are high. Because agents load templates, spec files, the constitution, and module structure on each run, token consumption is higher than direct prompting. One r/GithubCopilot thread title says it directly: "spec-kit is eating my tokens alive."8 Smaller models compound this — Qwen, DeepSeek-Coder, and Llama-class models produce plans that compile but lack coherent architectural reasoning; Claude Code with Sonnet/Opus 4.6+ is where spec-kit operates correctly.6

Spec drift is the unseen maintenance burden. Edit code outside the spec-kit workflow and the spec diverges immediately. u/Deep_Ad1959 in the comments of that same Reddit thread: "the drift problem is the one I'd focus on before anything else... a single agent with a clean spec round-trip beats three agents with a stale one every time."6 The May 2026 /speckit.spec-drift command is an early attempt to surface this automatically, but it's new.

Five phases is overkill for small changes. u/jokiruiz's rule: use full SDD only for new modules or features touching 200+ lines of code. For bug fixes under 50 lines, the workflow is ceremonial.6 Developer Maxim Saplin tried spec-kit and switched to Cursor's built-in Plan Mode for solo greenfield work, describing spec-kit as "bloated, too many artifacts, extra steps" — though he acknowledged SDD makes sense for large teams where hidden knowledge is the enemy.9

Brownfield migration is painful. Retrofitting SDD onto an existing 30K-line codebase is months of work, not days.6 For existing codebases, the community recommends looking at OpenSpec's explore skill, which generates an initial spec from existing code.

When to reach for it

spec-kit is well-suited to three scenarios GitHub officially names: greenfield projects, adding a substantial feature to an existing system (200+ LOC), and legacy modernization where "hidden knowledge" is the actual problem.2 The r/ClaudeCode community verdict (56-comment thread) is mixed but trends positive for larger work: "the best way of doing code in bigger projects," though one user spent a week building a trading bot MVP and two months fixing bugs afterward — a reminder that spec quality still determines implementation quality.10

For tasks under 30 minutes or files under 3, the overhead doesn't pay off — direct prompting or your agent's built-in plan mode is faster.

Skill metadata

Repo: github.com/github/spec-kit
Stars: 103K (as of 2026-05-19)
Forks: 9.1K
License: MIT
Current version: v0.8.8
Agents supported: 28 (Claude Code, Cursor, GitHub Copilot, Gemini CLI, Codex CLI, Windsurf, Devin, + 21 more)
Prerequisites: Python 3.11+, uv, Git, Linux/macOS/WSL2