Spec-Kit vs vibe coding workflow: the edge cases every guide skips.

The frame everyone repeats, and what it gets wrong

Most articles on this topic say roughly the same thing. Vibe coding is fast but undisciplined; spec-driven is slow but durable; vibe is for prototypes, spec is for production; teams should "graduate" from one to the other. That is not wrong on average, but it hides three things that decide the actual answer for the turn you are on.

First, the deliverables are different categories of thing. A Spec-Kit phase produces text. An mk0r turn produces a running app at a URL plus a git SHA. Text and a URL are not interchangeable. If your next decision needs a clickable artifact, the markdown will not help; if your next decision needs a contract two humans can argue on, the SHA will not help.

Second, the relevant axis is not discipline, it is decision phase. Discovery ("is this worth building?") and build ("what exactly does this do?") are different questions. The right tool depends on which question you are asking, not on how serious you are.

Third, vibe coding is not non-spec. mk0r runs a 2,438-line spec on every prompt; you just did not write it. The disagreement is about who maintains the spec, not whether one exists.

What each workflow actually puts on disk

The cleanest way to see the difference is to count the artifacts each workflow produces for the same starter prompt: "build me a habit tracker."

# After /speckit.constitution

.specify/memory/constitution.md

# After /speckit.specify

.specify/specs/habit-tracker/spec.md

# After /speckit.plan

.specify/specs/habit-tracker/plan.md
.specify/specs/habit-tracker/data-model.md
.specify/specs/habit-tracker/contracts/api-spec.json
.specify/specs/habit-tracker/research.md
.specify/specs/habit-tracker/quickstart.md

# After /speckit.tasks

.specify/specs/habit-tracker/tasks.md

# Files of running code so far: 0

Neither column is the "right" answer in the abstract. The left is what you want before three people need to agree on what is being built. The right is what you want before you know whether the thing should exist.

Toggle between the two workflows

Same starter prompt, two pipelines, two definitions of "done with turn one."

The anchor fact: one SHA per turn, on every prompt

mk0r's history stack is not metaphor. The function commitTurn() at src/core/e2b.ts:1759 runs the literal three-line shell script git add -A, git commit -q -m '…', git rev-parse HEAD inside the sandbox VM after every successful prompt. The SHA goes onto a per-session historyStack, with undoTurn(), redoTurn(), and jumpToSha() as siblings in the same file.

That is the structural difference, in one sentence. Spec-Kit's deliverable is markdown a human reads and reviews. mk0r's deliverable is a SHA a human (or another agent) can check out and run. Both are real artifacts; neither is a substitute for the other.

The surprise: mk0r is also spec-driven

The vibe-vs-spec writeups talk as if the choice is between writing a spec and not writing one. That is not the choice on offer.

mk0r runs a 2,438-line spec on every prompt. It lives in the public repo at src/core/vm-claude-md.ts, and the platform writes it into /root/.claude/CLAUDE.md inside the sandbox VM. The agent reads it before it touches a file. The contents include code-quality rules, styling rules, design constraints, copywriting rules, browser-testing rules, file-organization rules, env-var pitfalls, and VM guardrails. None of that is invented per session; it is platform-maintained, versioned, applied to every project built on the product.

The agent is going to read a spec on every turn. The only question is whether you wrote one for this project (Spec-Kit lane) or whether the platform wrote one for every project (mk0r lane). For prototypes, the platform spec is the right level. For production code your team has to maintain, a project-level spec on top of (or instead of) the platform one is.

The edge cases each workflow misses

Below are six situations where the "vibe for prototypes, spec for production" rule of thumb is not enough. For each one the choice is not about discipline; it is about which deliverable the next person in the loop needs.

How to actually sequence them on a real project

Treat them as phases, not alternatives. The honest sequence for most projects is:

1. Vibe code the discovery phase. Open mk0r, type a sentence, see what comes back. Iterate by talking. The deliverable here is a per-turn SHA stack you can fork from, and a working URL you can show a friend or a customer to find out if the idea is real. Do not write a constitution.md for an idea you have not validated.
2. Promote to a spec when more than one human is involved. The moment a PM, a designer, or a second engineer needs to agree on what to build, the deliverable shifts from "clickable artifact" to "reviewable contract." That is when Spec-Kit (or any spec workflow) earns its overhead. The cost of writing the spec is now amortized over multiple humans reviewing it.
3. Use the vibe artifact as input to the spec. The mk0r prototype is not throwaway in this sequence. It is the most concrete possible input to /speckit.specify: an agent reading the prototype can extract user stories from working code, where it would otherwise have to invent them from a paragraph of text. Discovery feeds build.
4. Run implementation under whichever loop has better verification. For UI work, mk0r's Playwright MCP screenshots the rendered page on every turn; for backend work, Spec-Kit's tasks.md gives the agent a checklist that maps to tests. Pick the loop whose verification step matches the work.

The article that frames this as a binary choice is selling either Spec-Kit or vibe coding, not advising you. Both tools survive the year because they answer different questions.

One-file tour, if you want to verify the mk0r side