AIDiveTen 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.
