GitHub Spec Kit: A Hands-On Review for 2026

7 min read
Spec-Driven DevelopmentSpec KitAIGitHubSoftware Engineering

GitHub Spec Kit is the most-starred spec-driven development framework on GitHub — 75,000+ stars, institutional backing, and support for 20+ AI coding agents. It's also the heaviest. After shipping three features with Spec Kit on real projects this quarter, I have a clearer sense of where it earns its weight and where it doesn't.

This review is what I'd tell a colleague asking "should we adopt Spec Kit?" If you want the quick answer: it depends on your team shape and your appetite for ceremony. For the comparison against GSD and OpenSpec, I wrote that post separately. Here I want to focus on Spec Kit on its own.

What Spec Kit Actually Is

Spec Kit is an agent-agnostic specification layer. You install it once, write your specs through a structured seven-phase pipeline, and then hand the resulting markdown to whatever AI coding agent your team uses — Copilot, Claude Code, Cursor, Windsurf, Gemini CLI, or one of the other 15+ supported tools.

The pitch is write specs once, execute anywhere. That's a real value proposition for teams where different engineers use different agents. Nobody gets locked into a single vendor's ecosystem. The specs belong to the repo, not the tool.

The trade-off: Spec Kit does not orchestrate execution. It's a specification framework, not an execution engine. When it's time to implement, your agent is on its own. No subagent spawning, no context pruning, no verification loop. Just well-structured markdown and a motivated agent.

The Seven-Phase Pipeline

Every Spec Kit feature moves through seven steps:

  1. Constitution — Project-wide principles established once per project
  2. Specify — Feature scope and requirements
  3. Clarify — Edge cases and unresolved questions
  4. Plan — Architecture and technical approach
  5. Tasks — Work breakdown into ordered tasks
  6. Analyze — Cross-artifact validation before execution
  7. Implement — Agent executes

Each phase is a slash command (/speckit.specify, /speckit.plan, etc.) that writes a specific markdown artifact into the repo's .specify/ directory. Phases feed each other — the plan references the specify output, the tasks reference the plan, and analyze cross-checks all upstream artifacts against each other.

The phased structure mirrors waterfall methodology, which has been the most-cited criticism. I'll address that directly later. For now, know that it's a deliberate design choice, not an oversight.

The Constitution: Spec Kit's Best Idea

Before you write a single feature spec, you write a Constitution. This is a file at .specify/constitution.md that captures the non-negotiable principles governing all downstream decisions.

# Project Constitution

## Principles
1. No feature ships without integration tests against a real database
2. All user-facing strings route through i18n — no hardcoded copy in components
3. API contracts are versioned; breaking changes require a new version path
4. Background jobs are idempotent and retry-safe by default

## Non-Negotiables
- Authentication uses Clerk; no custom auth code enters the repo
- Database migrations are one-way; no destructive rollbacks in production
- Secrets live in Vercel env vars or AWS Secrets Manager; never in code

Every subsequent phase — specify, plan, tasks — gets the constitution as context. The agent can't silently violate a constitutional principle because the framework re-surfaces the constitution on every step.

This is genuinely novel. GSD has PROJECT.md which plays a similar role, but it's less rigid. OpenSpec has no direct equivalent. Spec Kit's Constitution is the strongest governance primitive I've seen in any SDD tool, and it's the feature that makes Spec Kit worth considering for team environments where consistency matters more than speed.

Installing Spec Kit

Install is a one-liner, agent-agnostic:

npx @github/spec-kit@latest init

Answer a few prompts — which agent(s) you're using, which language(s) you work in — and Spec Kit scaffolds .specify/, drops the constitution stub, and registers slash commands with each registered agent.

For Claude Code users, Spec Kit adds the /speckit.* commands to .claude/commands/. For Cursor, it writes rules into .cursor/rules/. If you use multiple agents, install handles all of them in one go. Portability is visible from the first minute.

Shipping a Feature: What It Actually Feels Like

Here's the workflow for a feature I shipped with Spec Kit recently — a bulk-import tool for a client CRM.

Step 1 — Specify. I ran /speckit.specify "CSV bulk import for contacts". Spec Kit interviewed me: what columns does the CSV have, what validation rules apply, what happens on duplicate emails, how are errors reported back to the user? Output: a 350-line spec in .specify/features/csv-bulk-import/spec.md.

Step 2 — Clarify. /speckit.clarify reviewed the spec and flagged three unresolved edge cases. What about rows with valid email but invalid phone? What about trailing whitespace in headers? What about files larger than the 5MB API limit? I answered each in the spec. Output: spec grew to 480 lines.

Step 3 — Plan. /speckit.plan took the clarified spec and produced an architectural plan: upload to S3, queue a background job, parse with Papa Parse, validate per-row, insert in batches of 500, report errors via a status endpoint. 290 lines of plan.md.

Step 4 — Tasks. /speckit.tasks broke the plan into 14 ordered tasks. Each task had a scope, dependencies, acceptance criteria.

Step 5 — Analyze. /speckit.analyze cross-checked spec, plan, and tasks. It flagged that the spec mentioned a dry-run mode that had no corresponding task. I added it. The analyze step is where Spec Kit shines — it catches exactly the kind of drift that sinks longer features.

Step 6 — Implement. /speckit.implement handed the full artifact bundle to Claude Code, which then worked through tasks one at a time. Here Spec Kit stepped back — no orchestration, just trust.

Total elapsed time from specify to a passing implementation: about 4 hours. Of that, roughly 2.5 hours were spec work and 1.5 hours were implementation. That ratio flipped from what I'm used to with lighter tools like OpenSpec, where specs take 30 minutes and implementation takes the rest.

What Spec Kit Gets Right

  • Agent portability. Same specs, any agent. This isn't hypothetical — I've handed Spec Kit change folders between Claude Code and Cursor mid-feature and had both pick up seamlessly.
  • The Constitution. Governance primitive nothing else has. Teams with shared standards benefit immediately.
  • Cross-artifact analysis. /speckit.analyze is the most thorough validation step in any SDD tool. It catches drift between spec, plan, and tasks that would otherwise surface as implementation bugs.
  • Team scalability. Because execution is delegated, five engineers can work on five Spec Kit features in parallel without coordinating on a central orchestrator.
  • Enterprise backing. GitHub maintains it. That's a real signal for teams evaluating long-term viability.

What Spec Kit Gets Wrong

  • Ceremony tax is steep. A Scott Logic team benchmarked Spec Kit at 3.5 hours versus 23 minutes with iterative prompting for the same feature. That's roughly a 9x multiplier. For small changes — a bug fix, a copy update, a one-line config change — Spec Kit is the wrong tool.
  • Markdown explosion. My CSV import feature produced 2,100 lines of specification for what ended up as 600 lines of TypeScript. The ratio stops feeling useful somewhere around 3:1. Specs exist to reduce ambiguity, not to pad the repo.
  • No execution orchestration. Once implement kicks off, Spec Kit is uninvolved. If context rot degrades the agent's output on task 8 of 14, Spec Kit doesn't help. GSD's anchor-pruning is the answer to this problem, and Spec Kit has nothing analogous.
  • Waterfall feel is real. The seven-phase pipeline is inherently sequential. If requirements change during implementation, you're meant to loop back through the phases. In practice, teams skip the loop and let specs drift from reality — the exact failure mode SDD is supposed to prevent.
  • Maintenance turnover. A key original developer left GitHub for Anthropic in late 2025. The project continues, but velocity has shifted. Worth watching.

When Spec Kit Is The Right Tool

Spec Kit fits best when:

  • You work in a team where engineers use different AI agents
  • You need shared governance that all features must respect
  • Your features are large and high-risk — the kind where a 9x spec:implementation ratio is still cheap compared to the cost of getting it wrong
  • You have PMs or stakeholders who review specs before implementation starts
  • You're in a regulated environment where auditable specs matter

Spec Kit fits poorly when:

  • You're a solo developer shipping fast
  • Most of your work is small, iterative changes
  • Your team agrees on a single agent (e.g., everyone uses Claude Code)
  • You're in a startup where speed-to-learning beats spec fidelity

Spec Kit vs GSD vs OpenSpec, In One Line Each

  • Spec Kit — Write specs once, execute anywhere. Heavy but portable.
  • OpenSpec — Lightweight changes for brownfield codebases. Minimal overhead.
  • GSD — Full execution orchestration for Claude Code. Deepest integration, narrowest agent support.

The longer comparison is in this post. For the methodology itself, start with the introduction to spec-driven development.

The Verdict

Spec Kit is the best answer to "we're a team, we use multiple agents, we need consistency." It is the wrong answer to "I'm a solo dev shipping a landing page." Match the tool to the shape of your work, not to its star count.

For me, Spec Kit lives in my toolbox for client engagements where the team is heterogeneous. On my own projects I use GSD because Claude Code is my daily driver and orchestration matters more than portability. On legacy client work I use OpenSpec because the onboarding command solves a problem the others don't.

Three tools, three answers. Pick the one whose design philosophy matches your constraints today.

Check out my tools and stack for the full setup I run alongside Spec Kit on team projects.

Using Spec Kit or evaluating it? Reach out — I'm always trading notes on how these frameworks feel in production.