GitHub Spec Kit wants specifications to replace your source code

The Backlash Against Vibe Coding

For a brief moment, vibe coding felt like liberation. Tell an agent what you want, watch it hallucinate a full stack, and fix the bugs later. The phenomenon is seductive because it delivers velocity without accountability, shipping features that work in the demo but erode under maintenance. Then the bill arrived. IBM’s analysis frames the hangover clearly: localized fixes break broader functionality, new features ignore architectural conventions, and developers burn thousands of tokens patching errors that a clear specification would have prevented. Context drifts, fragments, and calcifies into technical debt at machine speed.

GitHub Spec Kit arrived in this hangover. Released in September 2025 and accumulating roughly 50,000 stars within a couple of months, it is Microsoft’s open-source attempt to impose discipline on agentic workflows. It does not ask developers to write less; it asks them to write differently, and earlier.

Specifications as Source Code

Spec-Driven Development is not merely writing a document first. In the Spec Kit formulation, specifications become executable artifacts—the shared source of truth from which implementation plans, tasks, and ultimately code are generated. The methodology splits work into seven stages: Constitution, Specify, Clarify, Plan, Tasks, Implement, and Validate. The constitution establishes governing principles; the specification captures user journeys and outcomes; the plan locks in stack and architecture; tasks decompose the work into isolated, testable items; and implementation executes them.

GitHub describes this as version control for your thinking. Because specs are decoupled from implementation, the toolkit supports multi-variant development—producing parallel implementations in different languages or design directions from the same intent. The specification is the primary artifact; code is a last-mile byproduct.

This is the genuinely special bet. Most AI coding tools treat the prompt as a transient input and the codebase as the accumulated reality. Spec Kit inverts that: the spec is the reality, and the codebase is a generated view. This inversion challenges the default assumption of modern development—that the repository is the ground truth and documentation is a lagging annotation. By making the spec the ground truth, Spec Kit attempts to solve the alignment problem at the root: if the agent and the human disagree, the spec mediates, not the diff. Maintenance happens by updating the specification and regenerating, rather than hand-editing files that have drifted from original intent.

The Machinery of Intent

Spec Kit’s machinery is agent-agnostic. It ships as the Specify CLI, which bootstraps a project by downloading official templates for more than thirty AI coding agents, from GitHub Copilot and Claude Code to Gemini CLI and Codex. Once initialized, the project exposes commands mapped to each SDD phase—establishing principles, defining requirements, drafting technical plans, decomposing work, and executing implementation. The agent is treated as a literal-minded pair programmer that requires unambiguous instructions rather than vibes.

Under the hood, the template system is layered and resolved at runtime. Core templates define the default SDD workflow. Extensions add new commands and capabilities—Jira integration, post-implementation review, V-Model test traceability—while presets override templates to enforce organizational standards, compliance formats, or even whimsical terminology overrides without changing the underlying workflow. Project-local overrides sit at the top of the stack. If multiple presets or extensions provide the same command, the highest-priority version wins, and removal automatically restores the next candidate. This architecture suggests GitHub expects enterprises to fork and customize the process, not merely adopt a rigid methodology out of the box.

A Crowded Cathedral

Spec Kit did not emerge in a vacuum. It is one of several frameworks attempting to formalize SDD. Tessl, launched around the same period, defines specs—not code—as the primary artifact using structured, testable language for agent generation. Amazon Kiro offers a lighter-weight, spec-first approach focused on individual tasks or user stories within VS Code, generating Requirements, Design, and Tasks documents. The AI Unified Process takes a stakeholder-centric route, beginning with system use cases and actor interactions before any implementation thinking begins.

Thoughtworks distinguishes three levels of maturity: spec-first, spec-anchored, and spec-as-source. Spec Kit operates at the highest level, spec-as-source, which is also the least common and the hardest to retrofit onto existing codebases. Birgitta Böckeler notes that evaluating these tools is time-consuming and that real-world brownfield adoption remains an open question.

Martinelli.ch draws a sharper distinction between task-driven, developer-centric SDD—exemplified by Spec Kit and Kiro—and stakeholder-centric SDD. The task-driven model, the author argues, blurs the boundary between problem space and solution space early because the specification emerges from implementation thinking. It is effective for prototypes, internal tools, and well-scoped features, but risky for long-lived business-critical systems where misalignment between stakeholders and implementation is costlier than slow code generation.

The Weight of Discipline

The skepticism is not merely theoretical. A recent evaluation by Scott Logic tested Spec Kit on a brownfield Progressive Web App, recreating a deleted track-management feature of roughly one thousand lines. The author described extensive markdown documents, long agent run-times, and unexpected friction, ultimately questioning whether the approach is practical compared to existing techniques and likening it to reinvented waterfall.

That critique lands where Spec Kit is weakest. The methodology demands significant upfront effort in clarifying intent, validating plans against real-world constraints, and auditing intermediate artifacts before any implementation code is accepted. In greenfield projects, this overhead may pay for itself by reducing rework. In brownfield systems, where the existing codebase is the only specification that ever mattered, introducing Spec Kit means reverse-engineering intent into formal specs before moving forward—a tax many teams will not pay.

Moreover, the risk of spec rot is real. IBM notes that traditional spec-first documents often grow outdated as software evolves. Spec Kit claims its specs are living documents, but living documents require gardeners. If the specification is the source of truth, its maintenance becomes a religious obligation, not a chore.

Where This Lands

Spec Kit’s explicit experimental goals hint at its intended audience: enterprise constraints, mission-critical applications, compliance requirements, and design-system governance. These are environments where vibe coding is already forbidden, where regulatory traceability is non-negotiable, and where the cost of architectural drift is measured in millions. For those teams, a structured, reviewable, evolvable specification layer may be worth the upfront friction.

For everyone else, Spec Kit functions as a provocation. It forces the recognition that large language models, for all their fluency, are not mind readers. They are pattern-matching engines that benefit enormously from structured context, explicit guardrails, and validated intent. The toolkit’s real impact may be cultural rather than technical: it gives teams a vocabulary to demand clarity before automation. Whether they adopt the full seven-stage liturgy or merely borrow its concepts, the project has already succeeded in reframing the debate. The question is no longer whether AI can write code, but whether humans can write intent clear enough to let it.