GitHub Spec Kit — Spec-Driven Development: Write the Spec First, Let the AI Coding Agent Do the Right Job

On a Friday afternoon, you hand Claude Code a request that sounds perfectly clear: “add login to the app.” An hour later, the agent returns a complete login system — JWT with Redis, plus a rewrite of the auth middleware that was already working fine. Your app uses session cookies with PostgreSQL; there is no Redis in your infrastructure.

The agent was not weak — it was missing a spec acting as a contract before any code was written. With nothing defining “correct”, it had to guess. Spec Kit fills that gap.

When an AI Coding Agent Writes Code Very Fast — in the Wrong Direction

A request like “build a login feature” hides dozens of implicit decisions: which mechanism, stored where, what validation, how errors are handled. Left unwritten, the agent chooses for you — and reviewing then takes longer than writing by hand. Longer prompts do not fix this: a prompt disappears after the session and cannot be versioned or reviewed like code. You need a spec stored in the repo to check finished code against: that is Spec-Driven Development.

What Is GitHub Spec Kit?

Spec Kit, or Specify CLI, is the repo github/spec-kit, licensed MIT, with 147,881 stars and 13,270 forks as of 2026-11-06. The latest release is v1.3.1 (2026-11-05); the project also made GitHub Trending on 2026-11-05. Spec-Driven Development (SDD) means: write the spec first, make a plan, split it into tasks, let the agent implement, then check against the spec until it converges — Converged. It is not an AI model, not an IDE, and it does not run tests for you — it is a process framework plus prompt templates for the agent you already use, across 40+ integrations.

Three Independent Entry Points

• Build a feature (SDD): constitution → specify → plan → tasks → implement → converge.
• Fix a bug: install with specify extension add bug, then run in the agent’s chat, e.g. /speckit-bug-assess "Submitting an empty password crashes the login form." slug=login-crash, then /speckit-bug-fix slug=login-crash and /speckit-bug-test slug=login-crash. Reports live in .specify/bugs/login-crash/; the final verdict is verified, partial, or failed.
• Assess an idea: install with specify extension add assess, then run /speckit-assess-intake through /speckit-assess-decide — the decision is go, needs-clarification, or kill.

All three share one philosophy: write it down first, verify afterwards — a kill with a recorded reason is still a useful result.

Spec Kit fits backend/full-stack developers, DevOps/SRE engineers, and anyone who already uses an AI coding agent regularly on medium and large tasks, especially teams needing a shared spec to review before coding. It is overkill for a one-off 20-line script or a five-minute fix. For AI coding-agent methods, see the Superpowers article; for switching providers, see the cc-switch article.

Architecture: the Spec Is Markdown Files, the Agent Is the Executor

specify-cli is a thin scaffolder: it installs prompt templates and initializes the project structure, not a runtime that executes code. All process state lives in Markdown files under .specify/: shared principles in .specify/memory/constitution.md; each feature in its own .specify/specs/<NNN>-<feature-name>/ directory with spec.md (WHAT plus measurable acceptance criteria), plan.md (HOW — architecture, tech stack), and tasks.md (an ordered checklist). As Markdown in the repo, they are versioned with Git and reviewable like code. The SDD commands run in the agent’s chat, not in the terminal, one at a time, reviewing the result before moving on.

Data Flow and the Converge Loop

flowchart TD
    A["Vague user idea"] --> B["Constitution<br/>.specify/memory/constitution.md"]
    B --> C["Specify<br/>.specify/specs/001-.../spec.md: WHAT + acceptance criteria"]
    C --> D["Plan<br/>plan.md: HOW, architecture"]
    D --> E["Tasks<br/>tasks.md: ordered checklist"]
    E --> F["Implement<br/>Agent edits code task by task"]
    F --> G["Converge<br/>Check code against spec"]
    G -->|Not Converged: record the exact drift| F
    G -->|Converged| H["Done: code checked against spec"]
    I["Bug-fix: verify → verified / partial / failed"]
    J["Idea-assessment: go / needs-clarification / kill"]
    I -. shares the spec → verify → verdict mechanism .-> G
    J -. a go result becomes a spec .-> C

Each step produces a concrete Markdown artifact; the agent is only the executor, the spec is the source of truth. The Implement ↔ Converge loop is the verification loop, and the stopping point is Converged.

Technical Dependencies and Limits

Requirements: Python 3.11 or later, uv, and a supported AI coding agent, on Linux, macOS, or Windows. Spec Kit supports 40+ integrations, including Claude Code (claude), GitHub Copilot (copilot), Codex CLI (codex), Cursor (cursor-agent), Gemini CLI (gemini), opencode, DeepSeek Harness (dsh), plus none and generic — managed with specify integration install/switch/status <key>. The real dependency is the agent: the same spec can yield two different implementations from two agents.

Three limits, stated plainly. First, no execution sandbox, test runner, or built-in CI — converge checks the implementation against the spec, but it does not replace the project’s test suite or human review. Second, prompts are Markdown templates, so interpretation can drift across agents and versions. Third, releases move fast (v1.2.6 → v1.3.1 in three days) — check the docs for your exact version.

Installing and Running SDD for the First Time

Prerequisites: Python 3.11+, uv, a logged-in AI coding agent, and a new project or clean Git repo. Not tested hands-on here; cross-checked against the official v1.3.1 documentation.

Install specify-cli and Initialize a Project

uv tool install specify-cli
specify init my-project --integration copilot
cd my-project

The first installs the CLI as an isolated tool via uv; the second scaffolds the project and configures the integration. Verify with specify --help and check .specify/ was created.

Run the 6-Step SDD Flow in the Agent Chat

Open the agent in the project directory, run each command in chat, and review before moving on:

1. /speckit-constitution — record project principles: language, architecture, security, test standards.
2. /speckit-specify — describe the feature in plain language, with measurable acceptance criteria; the agent writes spec.md.
3. /speckit-plan — the agent proposes architecture and stack; approve it before any code.
4. /speckit-tasks — split the plan into an ordered checklist.
5. /speckit-implement — the agent implements task by task.
6. /speckit-converge — check the implementation against the spec and plan; repeat until it reports Converged. Then re-read the spec, run tests and lint, and review the diff.

Common Mistakes

• Running /speckit-* in the terminal instead of the agent chat. These are agent skills, not shell commands.
• A vague spec without acceptance criteria. Go back to specify and add measurable criteria first.
• The agent drifting from the spec during implement. Stop, run converge, record the drift, then fix the spec or task.

Backup and Rollback

There is no automatic rollback — Spec Kit only generates Markdown files and code. Your safety net is Git: before /speckit-implement, commit a clean state including .specify/; commit separately after each step. If an implementation drifts beyond repair, git revert that commit, keep the spec, and implement again.

Technical Assessment

Strengths. The spec becomes living documentation: versioned with Git, reviewable, with decisions no longer scattered across chat history. Agent-agnostic with 40+ integrations: switching agents or providers does not lose the process, because the spec — not chat history or agent configuration — is portable. Converge gives a verified stopping point, and the task checklist reduces drift on large tasks.

Weaknesses and hidden costs. Writing a spec and plan has real overhead for small tasks, and the process demands the discipline to review them — skip the review and SDD degenerates into a longer prompt, with converge reduced to the agent confirming its own work. Final quality still depends on the agent and the spec’s clarity. No independent data proves how much SDD reduces rework or speeds things up, and Markdown templates can drift across agents and versions.

Security and operations. Spec, plan, and tasks are files in the repo: never write secrets, tokens, credentials, or customer data into a spec. Review artifact diffs like code reviews — a connection string in plan.md is as dangerous as one in source code. Community extensions and catalogs are not audited: treat an unfamiliar extension like an unfamiliar dependency and review its code before running specify extension add. The artifacts are lightweight, needing no new server; the real cost is tokens, runtime, and review time.

Comparison With Alternatives in the Same Scope

Direct prompting is fastest for small tasks but worst for control and drift. Superpowers complements Spec Kit as a methodology, not a replacement CLI (details in the Superpowers article), while plan mode is convenient but locks you to one agent. Other SDD tools exist, but I have not cross-checked their official documentation, so they are not in this table. Verdict: Spec Kit wins on portability, loses on overhead for tiny tasks.

Real-World Use Cases

Enterprise / backend team: add an API endpoint with a spec recording the contract, validation, and acceptance criteria; reviewers check spec.md and plan.md first.

DevOps / SRE: spec a deployment script or manifest, with rollback and environment variables in the plan; converge checks the checklist before production.

Homelab / self-hosting: spec a self-hosted service — ports, volumes, backup, environment variables — stored with the repo and docker-compose file.

Personal AI workflow: use idea-assessment (go/needs-clarification/kill) to drop ideas before coding; use the bug-fix extension to fix bugs with a verdict instead of guessing.

IT admin: specify an internal tool — import/export, permissions, logging — before asking an agent to write it, so handover does not depend on the prompt author.

Conclusion

It fits developers and teams who already use AI coding agents regularly, work on medium and large tasks, and need documentation and a verified stopping point. It does not fit one-off tasks, trivial fixes, people who use no agent yet, or teams with no time to review specs. In my view, the greatest value is not in the implement step — any agent can write code — but in the constitution, specify, and plan steps. Next step in 30 minutes: install specify-cli, init a trial project, write a short constitution, then run SDD for a small feature with measurable acceptance criteria until it reports Converged.

Lessons Learned

1. A spec must have measurable acceptance criteria, otherwise converge has nothing to check against.
2. Approve the plan before implementing: skipping this step removes SDD’s control value.
3. /speckit-* commands run in the agent chat, not the terminal.
4. You can switch agents because the spec is portable Markdown, but final quality still follows the agent.
5. Community extensions and catalogs must be code-reviewed before use — they are not audited.
6. Releases are moving fast (v1.3.0 → v1.3.1 in just two days) — check the docs for the exact version in use.

Verification Scope

Checked: 2026-11-06, against the official README and docs of github/spec-kit v1.3.1 and the GitHub API. Verified: repo, MIT license, star/fork counts, Python 3.11+ and uv, install and init commands, the 6 SDD commands, 40+ integrations, and the three entry points with their verdicts and decisions. The 6-step SDD flow is the default; bug-fix and idea-assessment are opt-in extensions (specify extension add bug / assess). Numbers are configuration and point-in-time figures, not benchmarks. Not tested: installing and running SDD — the guide only cross-checks the documentation.

References

• Official repo: github/spec-kit
• Documentation: github.github.io/spec-kit
• Release history: github/spec-kit releases
• Integrations list: github.github.io/spec-kit/integrations
• Related on phamnam.me: Superpowers — a programming method for AI coding agents, cc-switch — switching AI coding agent providers