Governing AI specs and plans in Git: five rules, drift gate, sources and checklist

TL;DR

• Commit AI-written specs and plans. Every tool already does it by default; the open question is governance.
• Give each squad one folder with a CODEOWNERS line, so a spec change requests a review from the code's owners.
• Put an ADR-style header on every shared spec: status, superseded-by, owner, touched paths, review date. Never rewrite an accepted spec into a new decision.
• Run a drift gate in CI: for every accepted spec, fail the build when a path it names no longer exists.
• Redirect the output path with one bold imperative line in CLAUDE.md, keep personal plans in CLAUDE.local.md and .git/info/exclude, and write on a branch, never on main.
• Spec only the work that crosses a squad boundary or will be read again in 90 days. Spec-driven runs cost about twice the time and three times the tokens.

What the sources say

The defaults: everybody commits

The Superpowers writing-plans skill saves plans to docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md, with a line underneath saying that user preferences for plan location override this default s1. The brainstorming skill writes the validated design to docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md and ends with "Commit the design document to git" s2. Spec Kit lays out specs/[branch-name]/ with spec.md, plan.md and tasks.md, numbered 001, 002, plus a constitution in memory/constitution.md s6. Kiro keeps .kiro/specs/ with one folder per feature and invites teams to "collaborate with team members on different features simultaneously" s8. Anthropic's playbook is explicit: "Every stage commits an artifact the next stage can read", "Commit the approved plan as plan.md", and "When implementation departs from the plan, update plan.md in the same commit" s5.

None of these documents says who owns a committed spec or when it stops being true. The three documented failures live in that gap.

Failure 1: the public leak

Issue 1690, opened 2026-06-05, reports that the default docs/superpowers/ location can leak internal plans into published documentation through Sphinx and Read the Docs s15. The project hit was okama, a Python library with 273 stars. Its fix commit re-added 5 plans and 3 specs, removed one .gitignore line and reads "track superpowers plans/specs in git, excluded from the Sphinx build" s21. Line 84 of docs/conf.py now has exclude_patterns = ["_build", "Thumbs.db", "superpowers"] s22. Today the folder holds 8 plans and 6 specs s15. The team kept the practice and fixed the build.

Failure 2: plans on main

Issue 1246, opened 2026-04-22 and still open, asks why the plan is committed before a development branch exists. One user reports "I'm getting 10 to 15 commits"; another: "Yes please, no plans and specs on main branch!" s16. The plugin does not enforce a branch rule; the checklist below does.

Failure 3: overrides the model skips

Issue 337 closed on 2026-03-10 with the maintainer's note that as of v5.0 the plugin honors your project's CLAUDE.md over its own defaults, example line: "Save plans to ~/.superpowers/plans/ instead of docs/plans/" s17. Issue 939, on v5.0.6, shows the limit: a CLAUDE.md "Output Paths" table was ignored and specs kept landing in docs/superpowers/specs/. The workaround that worked is a bold imperative line under the table: design specs MUST be saved to docs/design-docs/, NOT docs/superpowers/specs/ s18. Pull request 1020, which reordered the instruction, was closed without merging s19. The override is a prompt, not a setting: re-check it after each plugin release. For the plugin's own scratch files, issue 1780 was closed by v6.0.3 with a self-ignoring .superpowers/sdd/ folder that drops its own .gitignore containing * s20.

Personal versus shared

Claude Code documents the split: "For private per-project preferences that shouldn't be checked into version control, create a CLAUDE.local.md at the project root. It loads alongside CLAUDE.md and is treated the same way. Add CLAUDE.local.md to your .gitignore so it isn't committed" s3. Per-directory CLAUDE.md files load on demand, "Commit these files to the repository so teammates inherit them. Each directory's owner typically maintains its file", and a claudeMdExcludes setting hides other teams' files in a monorepo s4. Git gives three ignore layers, $XDG_CONFIG_HOME/git/ignore, $GIT_COMMON_DIR/info/exclude and .gitignore s24; the middle one hides a personal plans folder without touching a shared file. CODEOWNERS does the ownership half: "Code owners are automatically requested for review when someone opens a pull request that modifies code that they own" s23.

Lifecycle, like ADRs

Michael Nygard's 2011 post is the template: a decision "may be 'proposed' if the project stakeholders haven't agreed with it yet, or 'accepted' once it is agreed. If a later ADR changes or reverses a decision, it may be marked as 'deprecated' or 'superseded' with a reference to its replacement", and "If a decision is reversed, we will keep the old one around, but mark it as superseded" s9. Thoughtworks splits spec use into spec-first (written once for the task), spec-anchored (kept to evolve the feature) and spec-as-source (only the spec is edited), and its author adds: "I'd rather review code than all these markdown files" s10. Superpowers writes spec-first files and keeps them forever: drift by default.

Drift and the gate

The arXiv paper names the problem "silent spec-code drift -- code evolves, the specification does not, and the divergence becomes invisible until it is costly to repair" and proposes "a drift gate that makes spec-code divergence a blocking merge condition" s11. Spec Kit's own guide warns: "Do not leave a lower-level change in tasks.md or code if spec.md still says something different" s7. TrueFoundry puts the governance case bluntly: "forty-one specs and nine agent files aren't a tidiness problem", they are "forty-one unversioned behavior inputs and nine competing standing policies", and drift "is unavoidable in spec-first practice and managed in spec-anchored practice, but only if divergence is detectable". The same post suggests about 300 lines per spec and a budget of 150 to 200 standing instructions s13. One practitioner describes the manual version: "I've had to have Claude compare the spec files to the codebase and see if anything is missing" s26.

What it costs

The bake-off is one experiment and its author says so, but the direction holds across all three. So: spec the architectural path, keep the bounded path bounded, and follow the two lines practitioners repeat, "don t spec too big / read the generated specs" s26.

Do this Monday

• Create docs/specs/<squad>/ per squad and add one CODEOWNERS line per folder pointing at that squad's reviewers.
• Add one bold imperative line to the project CLAUDE.md: plans and specs MUST be saved under docs/specs/<squad>/, NOT docs/superpowers/. Run one brainstorm and check where the file landed.
• Move personal plans to a folder listed in .git/info/exclude and keep per-developer preferences in CLAUDE.local.md, itself ignored.
• Put a header on every shared spec: status (proposed, accepted, superseded), superseded-by, owner, paths, review-by.
• Write the drift gate: for each spec with status: accepted, extract the paths it names and fail the pull request when one is missing. About fifteen lines of shell or Python.
• Add a branch rule: no spec or plan commit lands on main outside a pull request.
• If the repo publishes docs with Sphinx or similar, add the specs folder to exclude_patterns today.
• Set the size budget: a spec stays near 300 lines, and only work crossing a squad boundary or read again in 90 days gets one.

Go further

• Read the three spec-use categories (spec-first, spec-anchored, spec-as-source) before choosing a header scheme; the lifecycle only matters for spec-anchored files s10.
• The arXiv paper goes beyond path checks to a full drift-enforced architecture; useful once the fifteen-line gate feels too coarse s11.
• Spec Kit's guide names three evolution flows (Flow-Forward, Living Spec, Flow-Back) that map onto the same-commit rule s7.
• The playbook suggests a hook to enforce plan and diff synchronization; the Reddit thread on it has 43 points and 27 comments of field reports s5, s27.
• TrueFoundry's argument that a spec change is a policy change, so it belongs behind an eval gate with run metadata, is the next step after CI path checks s13.
• Follow the two open issues, 1246 (plans on main) and 939 (ignored overrides); when either closes, one rule in this pack becomes a plugin default s16, s18.
• Marmelab's full write-up explains why the 1,300 lines appeared and where Spec Kit does pay off s14.

Sources

• Superpowers writing-plans skill, GitHub. Why read it: the exact default path and the one-line override clause you are relying on.
• Superpowers brainstorming skill, GitHub. Why read it: where specs land and the step that commits them.
• Claude Code memory, Anthropic. Why read it: CLAUDE.local.md is the sanctioned place for personal preferences.
• Claude Code: working in large codebases, Anthropic. Why read it: per-directory files, owners and claudeMdExcludes for monorepos.
• The AI-native SDLC playbook, Anthropic. Why read it: the audit-trail argument and the same-commit rule, from the vendor.
• Spec Kit repository, GitHub. Why read it: a per-branch spec layout to compare with the per-squad one.
• Spec Kit: evolving specs, GitHub. Why read it: the clearest statement that spec and code must not disagree.
• Kiro specs best practices, Kiro. Why read it: a feature-folder layout built for parallel squads.
• Documenting architecture decisions, Michael Nygard. Why read it: the status vocabulary the header borrows.
• Spec-driven development: the tools, Thoughtworks. Why read it: the spec-first versus spec-anchored distinction that decides what to keep.
• The Spec Growth Engine, arXiv. Why read it: the formal case for a blocking drift gate.
• OpenSpec bake-off discussion, GitHub. Why read it: the only side-by-side cost figures, with the author's own caveats.
• Spec-driven development for AI agents, TrueFoundry. Why read it: specs as versioned policy, and the 300-line budget.
• Spec-driven development: waterfall strikes back, Marmelab. Why read it: what 1,300 lines of spec for one trivial feature looks like.
• Superpowers issue 1690, GitHub. Why read it: the leak report, step by step.
• Superpowers issue 1246, GitHub. Why read it: the main-branch complaint, still open.
• Superpowers issue 337, GitHub. Why read it: the maintainer's statement that CLAUDE.md wins since v5.0.
• Superpowers issue 939, GitHub. Why read it: the override that failed and the wording that worked.
• Superpowers pull request 1020, GitHub. Why read it: the attempted fix, closed unmerged.
• Superpowers issue 1780, GitHub. Why read it: how the plugin self-ignores its scratch folder.
• okama fix commit, GitHub. Why read it: a real team choosing to keep specs and exclude them from the build.
• okama docs/conf.py, GitHub. Why read it: the one-line Sphinx exclusion to copy.
• About code owners, GitHub Docs. Why read it: the review-request mechanism the ownership rule leans on.
• gitignore documentation, Git. Why read it: info/exclude is the personal ignore layer most developers forget.
• We tried spec-driven development for months, Reddit r/SpecDrivenDevelopment. Why read it: a team-scale cost report with no vendor behind it.
• Does spec-driven development actually work for you?, Reddit r/ClaudeCode. Why read it: the sizing and read-the-spec advice from daily users.
• Has anyone tried Anthropic's AI-native SDLC playbook?, Reddit r/ClaudeCode. Why read it: field reports on the playbook in real repos.

FAQ

Do I need all five rules on day one?

No. The CLAUDE.md redirect and the Sphinx exclusion take ten minutes. Add CODEOWNERS and the header when a spec first crosses squads, and the drift gate once an accepted spec has aged a sprint.

What does the drift gate miss?

Changed behaviour. It only checks that a named path still exists, so an inverted condition passes. Pair it with the same-commit rule and review.

Why not just gitignore the folder?

Because the agent that reads the spec later needs it, and the audit trail only works if the middle pieces are versioned. The okama team tried the gitignore and reverted to committing with a build exclusion.