# 5 Rules To Stop AI Specs From Rotting In Your Repo

Video: https://www.youtube.com/watch?v=IKfUxgO0apE
Article: https://aidive.dev/videos/spec-plan-governance/
Published: 2026-09-14

## Chapters

- [0:00](https://www.youtube.com/watch?v=IKfUxgO0apE&t=0s) Ten developers, one docs folder
- [0:44](https://www.youtube.com/watch?v=IKfUxgO0apE&t=44s) Every tool commits the files
- [1:44](https://www.youtube.com/watch?v=IKfUxgO0apE&t=104s) Three ways it goes wrong
- [3:29](https://www.youtube.com/watch?v=IKfUxgO0apE&t=209s) Rule 1: one home per squad, with owners
- [4:42](https://www.youtube.com/watch?v=IKfUxgO0apE&t=282s) Rule 2: personal versus shared
- [6:02](https://www.youtube.com/watch?v=IKfUxgO0apE&t=362s) Rule 3: a lifecycle, like ADRs
- [7:30](https://www.youtube.com/watch?v=IKfUxgO0apE&t=450s) Rule 4: a drift gate in CI
- [8:45](https://www.youtube.com/watch?v=IKfUxgO0apE&t=525s) Rule 5: a size budget, and the cost
- [9:57](https://www.youtube.com/watch?v=IKfUxgO0apE&t=597s) Verdict: commit, then govern

## TL;DR

- Commit AI-written specs and plans, but govern them: one folder per squad with a CODEOWNERS line, a status header like an ADR, a CI gate that fails when an accepted spec names a missing path, and a size budget.
- Superpowers, Spec Kit, Kiro and Anthropic's playbook all commit specs by default; none of them says who owns the file or when it is dead, which is how Okama's eight internal plans ended up public on Read the Docs.
- Redirect plans with one bold imperative line in CLAUDE.md (a paths table gets skipped), keep personal plans in CLAUDE.local.md and .git/info/exclude, and write everything on a branch, never on main.
- Only accepted specs get the drift check; superseded and proposed ones are skipped, and a same-commit rule keeps the plan travelling with the diff that broke it.
- Spec-driven runs cost about twice the time and three times the tokens in the OpenSpec bake-off, so write a spec only when work crosses a squad boundary or will be read again in 90 days.

## Ten developers, one docs folder

Superpowers is a Claude Code plugin (286,000 GitHub stars) whose skills write specs and implementation plans as markdown files and commit them to the repository. By default every one of those files lands in a single folder, `docs/superpowers/`. In June the maintainers of Okama, a Python finance library, discovered that eight implementation plans an agent had written there, committed exactly as the plugin intends, had been rendered as public web pages on Read the Docs. They noticed after the release.

Now scale that up: a front-end team of ten developers, four squads, one repository, and every developer generating these files. Three questions land on the lead's desk. What exactly do we version? Is drift a problem when a spec names a path deleted two sprints ago? And who governs the folder? The Okama leak was not caused by committing. It was caused by committing without a rule. This article gives you five.

## Every tool commits the files

Superpowers never asks whether to commit. Line 18 of its planning skill saves every plan under `docs/superpowers/plans/`, dated, one file per feature. The brainstorming skill writes the design document and commits it in the same step, before you have seen the plan.

This is not a Superpowers quirk. Every major spec-driven tool makes the same choice:

| Tool | Publisher | Where specs live |
|---|---|---|
| Superpowers (286,000 stars) | obra | `docs/superpowers/`, one folder for everything |
| Spec Kit (136,000 stars) | GitHub | one numbered folder per feature, on that feature's branch |
| Kiro | Amazon | `.kiro/specs/`, one folder per feature |
| AI-native SDLC playbook | Anthropic | one committed artifact per stage: intent, spec, plan, diff, review findings, incident record |

Kiro sells per-feature folders as a way for teammates to collaborate on different features at once. Anthropic's playbook, published in August, goes further: every stage commits an artifact the next stage can read. So the question was never whether to commit, and where is answered by every tool. Who owns the file, and when it is dead, are not. That gap is what the five rules cover.

## Three ways it goes wrong

Committed plans fail in three distinct ways.

**Failure 1: the docs generator.** A documentation build that renders every markdown file under `docs/`, whether a table of contents lists it or not, ships the plans folder along with the manual. That is exactly what happened to Okama.

**Failure 2: the branch.** Superpowers issue 1246 reports that the brainstorm commits the plan straight to `main`. One user counts 10 to 15 commits per session, a new one every few changes. The thread's request fits in one line: no plans and specs on the main branch.

**Failure 3: drift.** Spec drift is the quiet failure: the code evolves and the spec does not. Birgitta Böckeler at Thoughtworks names three levels of spec-driven development:

| Level | Meaning |
|---|---|
| Spec-first | Written, used once |
| Spec-anchored | Kept and maintained for the feature's life |
| Spec-as-source | The human only ever edits the spec |

Superpowers writes spec-first documents and keeps them forever. By default you get spec-anchored storage with first-draft maintenance: nobody updates the file, and an agent reads it next quarter as truth. TrueFoundry puts it plainly: drift is unavoidable in spec-first practice and managed in spec-anchored practice, but only if divergence is detectable.

A repository holding 41 specs and 9 agent files does not have a tidiness problem. It has 41 unversioned behavior inputs. Böckeler's own reaction: she would rather review code than all these markdown files. A plan nobody loads again is clutter. A plan an agent loads is an instruction, and a stale one is a wrong instruction.

## Rule 1: one home per squad, with owners

Rule 1: the folder has an owner, and the owner is a squad, not the plugin. Since version 5, Superpowers honors instructions in your project's `CLAUDE.md` over its own defaults. Say where plans go and they go there.

A table of paths is not enough, though. In issue 939, a user wrote an output-paths table and the model followed the concrete path in the skill and skipped the table. The skill's own override note is a parenthesis. One bold, imperative line fixed it on the first attempt: specs must be saved here, not there, with the default named as the thing to avoid.

The layout is one folder per squad (checkout, search, accounts, design-system), each with its own specs and plans. In a monorepo, put the line in the package's own `CLAUDE.md`. Claude Code loads a subdirectory's file on demand when it reads there, and the documentation says each directory's owner typically maintains its file. Engineers who never installed the plugin are unaffected: the line only fires when a skill asks where to save.

Then let the platform enforce ownership. One CODEOWNERS line per squad folder, and every spec review lands with the people who will live with it. One caveat: the override is a prompt, not a setting. Check the first spec after every plugin release.

## Rule 2: personal versus shared

Rule 2: not every plan is a team artifact. The first person to ask Superpowers for a configurable location (issue 337) said it best: plan files can be personal working documents rather than project artifacts.

The personal side has a file made for it. `CLAUDE.local.md` sits next to the shared file, loads after it, and the documentation tells you to git-ignore it yourself. Your redirect to a private folder lives there and nobody else sees it. For the folder itself, Git has an ignore file that never touches the shared tree: `.git/info/exclude` is per clone, never committed, and needs no pull request. The plugin already does this for its own scratch space: since version 6.0.3 its working directory drops a `.gitignore` containing `*` inside itself, so it is self-ignoring without touching a tracked file.

The shared side is whatever passed the review gate the brainstorm already runs: spec written, review requested, approved by a second person. Approved, it moves into the squad folder. Not approved, it stays local. Both are written on a branch, never on `main`. Two lines in the shared `CLAUDE.md` do it: treat specs and plans as the start of a feature, and create the worktree before writing them.

One limit: a git-ignored plan does not travel. The Okama maintainers tried ignoring the folder first and reverted, because plans stopped syncing between machines and agents. Personal means personal.

## Rule 3: a lifecycle, like ADRs

Rule 3: a spec has a status, and a dead spec says so. The idea is 15 years old. Michael Nygard, in 2011, proposed keeping architecture decision records (ADRs) in the repository, one numbered file each. A decision is proposed, then accepted. When a later record changes it, the old one is marked deprecated or superseded with a reference to its replacement. If a decision is reversed, the old record is kept but marked superseded.

Applied to specs, every shared spec opens with a five-line header the agent already reads:

| Field | Purpose |
|---|---|
| status | proposed, accepted, superseded |
| superseded-by | the replacing spec |
| owner | the squad |
| touches | the paths the spec makes claims about |
| review date | when it was last checked |

Never edit an accepted spec into a different decision. Write the next one, point it back, and the history stays honest. One exception, stated in Anthropic's playbook: when implementation departs from the plan, update the plan in the same commit. The plan travels with the diff that broke it, and a hook can enforce it.

Spec Kit names three ways a spec can live. Flow-forward: a new folder per feature, old ones kept as history. Living spec: the spec is the contract and the rest regenerates. Flow-back: the build reshapes the spec. Their rule is not to leave a change in tasks or code if the spec still says something different. That is choosing spec-anchored on purpose.

The limit: a status is metadata a human sets. The agent will not mark its own spec superseded unless your `CLAUDE.md` tells it to, and even then the review has to notice.

## Rule 4: a drift gate in CI

Rule 4: a spec that lies about the tree fails the build. The paper that named the problem, published in June, calls it silent spec-code drift: code evolves, the specification does not, and the divergence stays invisible until it is costly to repair. Its answer is a drift gate, a blocking merge condition.

The check is smaller than it sounds. For every spec whose header says accepted, pull the paths it names, in backticks or in the touches line, and test that each one exists. Missing path, failing build, with the spec's name in the log. Superseded and proposed files are skipped: only accepted specs make claims about the tree, so only accepted specs get checked. TrueFoundry frames it as a scheduled diff rather than post-incident archaeology: a spec is scaffold, and a spec change is a policy change.

People already run the manual version. One commenter has Claude compare the spec files to the codebase and file tickets for what is missing. The script does that on every pull request, for free.

The second guard is the one Okama shipped: exclude the folder from the docs build. One line in the Sphinx configuration keeps the files in Git but out of the HTML.

The limit: a path check catches deleted files, not changed behavior. A spec can name every existing file and still describe an API that is gone. That is what review and the same-commit rule are for.

## Rule 5: a size budget, and the cost

Rule 5: most work does not deserve a spec. The evidence on spec-driven overhead is consistent:

| Experiment | Result |
|---|---|
| Marmelab, Spec Kit on a feature that shows the current date | 8 files, 1,300 lines of specification text |
| OpenSpec bake-off, same requirements with a spec tool vs Claude Code alone | 50% more code, 50% more cyclomatic complexity, twice as long, three times the cost |
| A team running spec-driven development for months | 2 to 3 times the tokens, about twice as long, large coordination cost for changes that needed none; no proof the code improved |

The bake-off is one experiment, not a benchmark, and its author says so. But the direction holds. So the rule: write a spec when the work crosses a squad boundary or will be read again in 90 days. Everything else is a prompt.

Superpowers already sorts every request into three paths: spike, bounded, architectural. Only the architectural path writes a spec. Keep the bounded path bounded, and keep the spec near 300 lines. Practitioners add two lines: don't spec too big, and read the generated specs.

The limit cuts both ways. The same bake-off found three gaps the plain run missed. The spec buys coverage, not speed. Pay for it where coverage matters.

## Verdict: commit, then govern

Back to the lead's three questions. What do we version: approved specs and plans, on a branch, in the squad's folder. Drift: a status header and a CI gate. Governance: owners and a size rule.

Five rules, and none of them is enforced by a tool today. The override issue is open. The main-branch issue is open. The pull request that reordered the instruction was closed without merging. The team that got burned kept the practice: 8 plans and 6 specs, committed, excluded from the docs build.

Böckeler's objection stands. With a status header and a size budget, you read only the accepted specs, and fewer of them. What you get back is what Anthropic's playbook calls the audit trail: who asked for what, what the agent produced, and who approved it.

This is process, not tooling: a `CLAUDE.md` file, a CODEOWNERS file, a header, and a fifteen-line script. And if the team will not review a CODEOWNERS request, they will not review a spec either. In that case the `.gitignore` was the honest choice.

## FAQ

### Should I commit Superpowers specs and plans to Git?

Yes, but with rules. Every spec-driven tool (Superpowers, Spec Kit, Kiro, Anthropic's playbook) commits them by default. Commit approved specs on a feature branch in a squad-owned folder, keep personal drafts out of the shared tree, and exclude the folder from the docs build.

### How do I change where Superpowers saves plans?

Since version 5 the plugin honours your project's CLAUDE.md over its own defaults. Use one bold imperative line naming the new path and the default path to avoid; a table of output paths was skipped by the model in issue 939. Re-check the first spec after every plugin release, since the override is a prompt, not a setting.

### What is spec drift in spec-driven development?

Spec drift is when the code evolves and the committed spec does not, so an agent that later reads the spec receives a wrong instruction. Thoughtworks distinguishes spec-first (used once), spec-anchored (maintained) and spec-as-source; Superpowers writes spec-first files and keeps them forever, which produces drift by default.

### How do I detect spec drift in CI?

Add a drift gate: for every spec whose header says accepted, extract the paths it names and fail the build if any path no longer exists. It is about fifteen lines of script and runs on every pull request. It catches deleted files, not changed behaviour, so pair it with review and a same-commit update rule.

### How should AI specs be versioned, like ADRs?

Give each shared spec a header with status, superseded-by, owner, touched paths and review date. Never edit an accepted spec into a different decision: write the next one and point it back, as Michael Nygard's architecture decision records do. The only exception is updating the plan in the same commit that departs from it.

### Is spec-driven development worth the cost?

Not for most work. The OpenSpec bake-off produced 50% more code and complexity, took twice as long and cost three times as much as plain Claude Code, while catching three gaps the plain run missed. Reserve specs for work that crosses a squad boundary or will be read again in 90 days, and keep them near 300 lines.

## Sources

- [Superpowers writing-plans skill](https://github.com/obra/superpowers/blob/main/skills/writing-plans/SKILL.md) — GitHub
- [Claude Code memory (CLAUDE.md, CLAUDE.local.md)](https://code.claude.com/docs/en/memory) — Anthropic
- [The AI-native SDLC playbook](https://claude.com/blog/the-ai-native-sdlc-playbook) — Anthropic
- [Spec Kit: evolving specs](https://github.com/github/spec-kit/blob/main/docs/guides/evolving-specs.md) — GitHub
- [Documenting architecture decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions.html) — Michael Nygard
- [Spec-driven development: the tools](https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html) — Thoughtworks
- [Silent spec-code drift](https://arxiv.org/abs/2606.27045) — arXiv
- [OpenSpec bake-off discussion](https://github.com/Fission-AI/OpenSpec/discussions/1159) — GitHub