I Wrote 238 Specs and Never Read One Again

Right now the SpecKit Companion repo holds 94 spec folders, 238 markdown files, and 15,225 lines of specification.

I haven't reopened a single one of them since it was marked complete.

That's not laziness. It's the honest outcome of running spec-driven development on something real for long enough. Somewhere around spec forty, I stopped believing the folder had answers in it, and I never went back. The specs folder had become write-only: a place things go, not a place anyone reads.

That's a problem spec-driven development creates. It doesn't solve it.

What spec-kit gets right

Give GitHub's spec-kit its due, because the part it owns is the hard part.

It forces the decision onto paper before the code exists. I wrote up that whole loop in Stop Vibe Coding, Start Shipping. Specify, plan, tasks, implement, and each phase drags something out of your head that you'd otherwise leave implicit and discover later, usually while debugging. A vague requirement dies at the specify step instead of becoming two hundred lines of wrong implementation.

That worked. It's precisely why there are 94 of them.

What nobody warns you about is what 94 completed specs do to a repository.

Specs don't just accumulate. They start to lie.

Building SpecKit Companion wasn't a tidy sequence of new features. It was rewrites. Refactors. Deletions. Decisions I made in March and reversed in June.

Take one concrete thread: how a task gets marked complete, and how the time it took gets tracked. I've iterated on that many times. Each iteration produced its own spec, with its own acceptance criteria, its own functional requirements, and its own record of what I believed at that moment.

So when I go looking for "how does task completion actually work," there's no answer in that folder. There are five specs that touch it. Four are superseded. Nothing in any of them says which.

This is the part that gets missed when people talk about spec-driven development. A spec is a snapshot of intent at a moment. Snapshots don't update. Put 94 of them in a folder and you don't have documentation, you have an archaeology site, and every layer contradicts the one above it.

My first fix was the obvious one: extract the durable parts into docs/. That helped for about a month. Then the docs drifted too, because a hand-maintained abstraction has exactly the same problem plus a second place to look. I'm moving away from that now.

The part I got wrong

I assumed the cost of all this was mine. I couldn't find things, so I stopped looking, and I treated that as a personal filing failure.

Then I looked at what my agent was doing.

Before living specs, when I asked Claude to work on a feature, it read the codebase. Not the specs. The code, plus whatever scattered documents it could find, reconstructing intent from implementation every single session. 94 specs sat right there in the repo, describing exactly what it was working out from scratch, and it went around them.

Of course it did. I'd have done the same. Faced with 238 files and no way to tell which are current, reading the code is the rational move.

So the folder wasn't just unread by me. It was unread by the machine that produced it.

Here's the line I'd put on a wall: a spec that nothing reads isn't documentation, it's exhaust.

Once I saw it that way, the question changed shape. It stopped being "how do I organize my specs" and became "what does the agent load before it starts."

Before, on the left: the agent sweeps past a grid of dim, closed spec cards and reads the whole codebase instead. After, on the right: three living specs load first, and a single thin line continues to the code, labeled "locate only." The point of the picture is the thickness of those two paths into the code.

There are two extensions, and only one of them is a GUI

Before the mechanism, a clarification, because this is the single most common misunderstanding about SpecKit Companion and it matters for everything below.

It reads as a VS Code thing. It isn't.

The VS Code extension is the GUI. The sidebar, per-spec status, the pipeline rail, the Resume button, inline review. It's the half you look at.

The spec-kit extension installs into spec-kit itself and runs on the command line. It records the lifecycle, right-sizes the pipeline, assembles commands from nodes, and extracts living specs. There's no editor involved.

Neither one has to call the other. The command-line half writes a plain .spec-context.json into each spec directory, and the GUI reads it. That file is the entire handoff, and it's ordinary JSON, so anything else can read it too.

Two panels, one file between them, and no arrow going directly from one panel to the other. That gap is deliberate.

Which means: living specs, drift detection, and the run record are all produced by the command-line half. If you never open VS Code, you still get every one of them.

I'll own the confusion. I started with the GUI and the product outgrew it, and the naming still carries that history. One asymmetry is worth stating plainly while we're here: the GUI doesn't support every AI provider yet. The spec-kit extension does, matching stock spec-kit's set.

Living specs invert the read order

A living spec is one spec per capability, not one per change. Checkout. Auth. Billing. In this repo: core, spec viewer, AI providers, and eleven others. 14 files, 3,112 lines, against 238 files and 15,225 lines of feature specs.

The feature specs didn't go anywhere. They got demoted. They're the artifacts of the work now, the record of what happened during a run, rather than the record of what's true. That distinction is the whole thing.

The extraction step is the part that earns it. It isn't a copy. When a feature ships, the extraction compares the living spec against the code and reconciles both, so what lands describes what the code actually does rather than what the feature spec hoped it would do.

Then the read order flips. The agent loads the living spec first, and reads code only to locate where the capability lives, not to work out what it does.

The portable version of this: if I build the next feature without spec-kit at all, in a plain prompt, the living specs still answer what the capability requires. They aren't tied to the workflow that produced them.

You can keep them centrally in a capabilities/ folder, or colocated next to the code they describe. One reversible command moves between the two.

The sidebar carries per-capability test coverage and a drift flag. That drift flag is the next question.

Four questions that follow

Once specs are readable again, four things you couldn't ask before become askable.

Are they still true?

Living specs are updated by the Companion commands. So work done outside them, a quick fix in a plain prompt on a Friday, leaves requirements that nothing recorded.

Drift detection is the answer to that gap. It flags the capability whose source files have moved since its spec was last committed. The repair command then re-reads the actual code changes, compares them against the living spec, and adjusts it.

You turn it on per repo, it only ever adds to a spec, and a flag never blocks a run. A drift flag is information, not a gate.

Can I verify one run?

The intent, the approach, the decisions, and the requirements end up spread across seven artifacts and four phases. Knowing whether any of it was actually fulfilled means reading all of them, which nobody does.

The Overview is one page that answers it: why the spec exists, its constraints, the decisions made with the alternatives they rejected, each verified check alongside the command that proves it, and a requirement-to-test coverage table.

The rejected alternatives matter more than they sound like they should. A decision on its own tells you what was chosen. A decision with its rejected alternatives tells you the consequences were considered.

Months later, this is the page that tells you in about ten seconds whether a spec is even relevant to what you're looking for.

That is one page scrolling, not a montage of several. The reason it's a recording and not a screenshot is that no single frame holds it. And the per-phase timings are wall-clock, not estimates.

How do I correct one?

The old way was to describe the correction out loud. "Remember in that file, around line forty, that decision should be different." Then hope the model finds the line you meant.

Inline review comments are the pull request review I already know how to do. Read the artifact, comment on the specific line, hit Refine, and the pending comments dispatch to the AI as an in-place edit of the source. The model decides the scope: rewrite the artifact, or reconsider that one line.

There's a second use I didn't design, which came from a user. Some comments aren't for the AI at all. They're notes on why a decision was made, left for the next person reading the spec. Those never get dispatched.

I abandon reviews halfway more often than I finish them, so comments save as you type and commit with the repo. The half-done one is still there next session, or on the other machine.

Three states in one view: a pending comment, one already applied, and the composer open on line four. Each sits indented under the line it belongs to, the way a pull request comment sits under its line of code. That layout is the argument. The context action beside the box is worth noting too: some corrections are a whole instruction, and some are just "suggest removing this line".

Does a renamed button need all of this?

Here's stock spec-kit's honest failure. Every change gets the full pipeline, so every change becomes a decision about whether to use spec-kit at all. Two files to touch, and you reach for a plain prompt instead.

I hit this constantly with small things. Moving a button in the sidebar. Adding a context menu item. Renaming something.

Fast mode classifies the change and collapses the pipeline for the small ones. But the reason I still run the pipeline for a renamed button is different from the reason you'd expect. My workflow already does the review, opens the PR, waits for it, and merges. Skipping the pipeline means hand-prompting all four of those again, every time.

Auto mode composes with it. For a change I genuinely don't need to review the spec, plan, and design for, it runs from issue link to PR without stopping, and fast mode is what makes that quick rather than ceremonial.

The measured version, from a benchmark across both workflows: Companion specs run roughly 60 to 68% leaner and write zero throwaway side files at any size. Correctness was a tie, with every cell in both workflows shipping a passing build against an all-green regression suite and a 5.0 out of 5 independent-judge rubric. The variable is ceremony, not whether the feature works.

Where it still loses

The two-extension confusion above is the real adoption cost, and I haven't solved it, only explained it.

Living specs adoption on an existing codebase is the part I'm least sure of. There's a brownfield adoption path, but it needs more feedback than it's had. Usage is nowhere near OpenSpec's, and I don't have enough signal yet to know which parts of it are wrong.

The customization claim needs an honest edge too. Every part of the process is configurable: the steps, the templates, the artifacts, the hooks, which skills attach where. I built that deliberately, because every SDD framework I tried boxed me into its own commands, and I walked through building one from scratch in Build Your Own SDD Workflow and Custom Workflows. But everything being configurable means there's more to configure, and the default path has to be good enough that most people never touch it. I'm not certain it is yet.

What I'd take from this

The useful question in spec-driven development isn't how much spec you write. It's what gets read afterward, and by whom.

94 specs nobody opened taught me that better than 14 that get loaded every session.

Both halves are MIT-licensed and the docs are at speckit-companion.dev, if you want to try the read-order thing on your own repo.

There are three threads here I cut short to keep this one readable: adopting living specs on a codebase that already exists, what the fast-mode short circuit actually decides, and running auto mode end to end. Each is its own piece, and I'll write them next.