/auditing-upstream-drift

name: auditing-upstream-drift
description: Use when checking if beads-superpowers is outdated, before a plugin release, or when auditing for missing capabilities — covers upstream drift, test execution, documentation, plugin health, and content integrity

Auditing Upstream Drift

> **Maintainer-only skill for the [beads-superpowers](https://github.com/DollarDill/beads-superpowers) repository — not distributed.** > Before doing anything else: if the current repo is not beads-superpowers (no `.claude-plugin/plugin.json` whose `name` is `beads-superpowers`), say so and STOP — this skill audits that repo against its upstreams and is useless anywhere else.

This is the quality gate for the beads-superpowers plugin. It verifies everything — upstream staleness, test pass rates, documentation accuracy, plugin manifest validity, hook functionality, content integrity, and beads integration completeness.

**Iron Law:** NO PLUGIN RELEASE WITHOUT A FULL AUDIT FIRST. Audit findings with security or material-risk impact are never downgraded to make a release, and phases are never skipped for a date (Production-Grade Doctrine).

When to Use

• Before any plugin version bump or release
• Monthly (or after upstream releases of superpowers or beads)
• When a user reports a skill behaves differently than expected
• When beads adds new CLI features that skills should leverage
• After any bulk refactoring of skills or tests
• After merging upstream changes

Upstream Sources

| Source | Repository | Our Baseline | What We Track | |--------|-----------|-------------|---------------| | **Superpowers** | [obra/superpowers](https://github.com/obra/superpowers) | v6.2.0 | Skills content, new skills, hook structure, plugin manifest | | **Beads** | [gastownhall/beads](https://github.com/gastownhall/beads) | v1.1.2 | CLI commands, new features, bd prime format, deprecations |

Known Deliberate Divergences

These shared skills intentionally differ from upstream superpowers. When Phase 5 (Check 5.3) flags them as CHANGED, that is expected — do **not** revert them toward upstream. Adopt only upstream changes that don't reverse these decisions.

| Area / Skill | We do | Upstream does | Why | |---|---|---|---| | **All shared skills** | `bd` task tracking — beads is the ledger | `TodoWrite` / markdown TODOs | The fork's reason for existence: cross-session persistence | | **using-git-worktrees, finishing-a-development-branch** | `bd worktree` Iron Law; reject native-tool-first selection | native worktree tool first → `.worktrees/` → raw `git worktree` | native-first bypasses beads-DB sharing across worktrees (ADR-0014; audit finding #6) | | **finishing-a-development-branch** | Land the Plane (`bd close` → `bd dolt push` → `git push`) | no session-close ritual | core to the beads workflow | | **subagent-driven-development** | beads is the durable ledger; Parallel Batch Mode kept; `bd merge-slot` optional | markdown progress ledger | beads survives compaction; single orchestrator already serializes merges (ADR-0013, ADR-0012) | | **using-superpowers** | Claude Code tool names + per-CLI `references/` maps (trimmed to harness-specific content, superset of upstream's 3-file set) | fully vendor-neutral tool vocabulary | we ship multi-CLI adapters, not one neutral vocabulary (ADR-0006) | | **Beads integration** | CLI-only: call `bd` directly in skills + one SessionStart hook composing beads context (curated memories + a `bd prime` pointer); no beads Claude plugin or beads-mcp server | Claude plugin + MCP server | Lowest overhead; full `bd` command coverage; matches beads' own "CLI + hooks when shell is available" guidance (ADR-0017) | | **brainstorming, writing-plans** | stress-test (a fork-only skill) is offered at the approval gate via a 3-option "Approved + stress-test" gate folded into the upstream Approved/Needs-changes review gate | 2-option review gate; no stress-test (stress-test does not exist upstream) | stress-test is one of our 7 fork-unique skills; offering it at every spec/plan gate is intended fork behavior (ADR-0020) | | **using-superpowers + judgment/gate skills (doctrine class)** | fork-only Production-Grade Doctrine: canonical `## Production-Grade Doctrine` block in `using-superpowers` PLUS self-contained woven doctrine-floor lines (incl. the security floor) in judgment/gate skills | no such doctrine (obra/superpowers has none) | intended fork behavior (ADR-0023/0036/0040); on re-sync PRESERVE every woven doctrine-floor line; mark SKIP, not Conflict | | **using-superpowers + question-gate skills (ask-user class)** | fork-only ask-user convention: `## Asking the User` block in `using-superpowers`, self-contained consent lines at the 3 destructive gates (finishing-a-development-branch, document-release, using-git-worktrees), adapt parentheticals on the 6 JSON gate lead-ins, quirk rows in `references/{opencode,codex,pi}-tools.md` | upstream uses bare generic phrasing with no convention block (zero in-skill tool refs) | intended fork behavior (ADR-0041); on re-sync PRESERVE all four elements; mark SKIP, not Conflict | | **All shared skills (namespace)** | cross-skill references use `beads-superpowers:<skill>` | bare `superpowers:<skill>` | upstream's bare namespace points at the upstream plugin; in our fork it must carry our plugin name or it resolves to the wrong plugin (intended; mark SKIP, not Conflict) | | **brainstorming** | brainstorm session dir + auth-token files live under `.internal/brainstorm/` (self-ignored) | upstream uses `.superpowers/brainstorm/` | one canonical `.internal/` scratch root (spec 2026-06-30); `server.cjs` unchanged — do not revert the path on re-sync | | **Codex SessionStart hook** | keep it — still fires `using-superpowers` bootstrap + composed beads context | v6.1.0 removed theirs ("Codex reliably triggers skills on its own, and the bootstrap hook made the UX worse rather than better") | ours also carries composed beads context injection (curated memories + a `bd pri