superpowers-plus
AI coding assistants skip the practices that keep bugs out of production. They implement the first idea without weighing alternatives, patch symptoms instead of finding root causes, and declare work done without verifying it. Asking them to behave better in a system prompt doesn't hold: under context pressure, the instructions get forgotten.
superpowers-plus is 125 skills that make an assistant follow those practices, plus the machinery that enforces them from outside the model. Skills give the assistant a procedure: reproduce before fixing, generate three designs before picking one, send a diff to parallel specialist reviewers. Lifecycle hooks and git commit gates check the result. Git runs those gates whether or not the assistant remembers to ask for review.
It builds on Jesse Vincent's obra/superpowers. Superpowers teaches an agent how to work; superpowers-plus adds more skills and the hooks and gates that make the work hard to skip. It also covers non-coding work: documents, wikis, issue tracking, research.
Quick Start
Requires bash 4+, git, and Node.js 18+. macOS ships bash 3.2, so run brew install bash first.
git clone https://github.com/bordenet/superpowers-plus.git && cd superpowers-plus
bash install.sh # skills, hooks, and runtime
bash tools/install-hooks.sh # git commit and push gates
Then tell your assistant what you're doing:
| You say... | What happens |
|---|
| "Debug this test failure" | systematic-debugging requires a root cause before any fix |
| "Build a new feature for X" | feature-development runs brainstorm, debate, plan, TDD, review, verify |
"Review this code" or /sp-cr-battery | code-review-battery starts with one combined reviewer and dispatches up to 7 parallel reviewers when the diff calls for specialists |
| "I keep getting the same error" | think-twice hands the problem to a fresh sub-agent with no shared context |
| "Check for security issues" | repo-security-scan covers secrets, dependencies, risky patterns, and config |
| "I'm about to commit" | unified-commit-gate runs lint/build/test, style, review, language, and IP audit |
Full install options (Claude Code plugin, Codex, OpenCode, MCP server, Windows/WSL) are in docs/INSTALLATION.md.
Claude Desktop
The Claude Desktop app has three tabs. bash install.sh sets up the Code tab and builds the skill ZIPs for Chat and Cowork, which you upload once.
| Tab | What you get | Extra steps |
|---|
| Code | Everything Claude Code gets: all 125 skills, lifecycle hooks, and approval guardrails | None beyond the Quick Start. The Code tab runs the same engine as the Claude Code CLI and reads the same ~/.claude/ skills, hooks, and settings |
| Chat and Cowork | Eleven of the skills, the ones whose core steps work without a shell or this repo: brainstorming, debate, plan writing, AI slop detection and rewriting, and others | Upload the ZIPs that install.sh builds (below) |
| Chat (optional) | Read access to all 125 skills through the find_skills, use_skill, and match_skills tools | Add the MCP server to claude_desktop_config.json. Skills that run repo scripts or depend on hooks won't fully work in Chat |
Code tab. Local sessions load ~/.claude/skills/ and the hooks in ~/.claude/settings.json, so they behave the same as Claude Code in a terminal. The git commit and push gates run in any repo where tools/install-hooks.sh has installed them, whichever app made the commit. Cloud sessions don't read ~/.claude/, and an SSH session reads the remote machine's copy, so run install.sh there too.
Chat and Cowork. These tabs load skills from your claude.ai account instead of ~/.claude/skills/. claude.ai has no upload API, so uploading is the one manual step:
- Run
bash install.sh (or bash tools/package-for-claude.sh on its own). It writes one ZIP per skill to ~/superpowers-plus-claude-desktop/.
- In the Desktop app, open Customize in the sidebar (or go to claude.ai/customize/skills) and upload each
.zip.
- Turn each skill on.
The packager applies claude.ai's upload rules for you. It names the file SKILL.md, includes each skill's reference files, and keeps only the six frontmatter fields claude.ai accepts, because any other field makes the upload fail. It also adds a note telling Claude to skip any step that needs this repo's scripts, since Chat and Cowork don't have a copy of the repo. After bash install.sh --upgrade, the output names the ZIPs that changed. Upload only those again, replacing the older copies in Customize.
Uploaded skills follow your claude.ai account into Chat, Cowork, cloud sessions, and Claude Code sessions signed in with that account. On a machine where install.sh already put the same skills in ~/.claude/skills/, Claude Code loads both copies. It uses the local one and keeps the uploaded one as /anthropic-skills:<name>, and both take up context and compete for the same prompts. If you mostly work in the Code tab, leave the uploaded copies off.
The other skills aren't packaged because their main steps call other skills, run scripts from this repo, or depend on hooks and git gates. The list is in tools/claude-desktop-skills.json.
What Changes
"This test started failing after yesterday's change. Fix it."
Without: edit code -> test passes -> "Done."
With: reproduce -> find the root cause -> test hypotheses -> isolate
-> smallest fix -> verify -> review the diff -> commit gates
Enforcement Outside the Model
Most skill libraries are prompt text. If the model drops the instruction, nothing notices. superpowers-plus puts the checks where the model can't skip them:
- Git hooks run the commit gate chain on every
git commit and git push. Changes to skills/ need a passing code-review sentinel tied to the reviewed content before the commit goes through.
- Claude Code lifecycle hooks (including SessionStart, UserPromptSubmit, PreCompact, and PreToolUse) route prompts to skills, save a resume prompt before context compaction, block pushes and branch deletions until a human approves them in the session, and stop commits made under the wrong git identity.
- CI repeats the IP scan on the PR title and body, because a squash merge builds its commit message from those fields, not from any local commit.
The AI-Harness: Instruction Context as a Budget
Every skill an agent loads stays in its context window and is re-sent on every model call. superpowers-plus treats that context as a budgeted resource and runs a closed loop over it:
| Stage | Artifact | Role |
|---|
| Sensor | tools/skill-size-audit.sh | Ranks every skill.md by size and fails when one exceeds the fleet threshold |
| Actuator | kernel-split | Splits a large skill into a small always-loaded kernel and an on-demand reference |
| Regulator | artifact-budgets | Byte budgets against a committed baseline, so a skill that shrank today can't quietly regrow |
Measured results so far, from the reduction ledger:
| Skill | Before | Kernel after | Reduction |
|---|
| progressive-harsh-review | 18,018 B | 8,493 B | 52% |
| debate | 13,660 B | 7,703 B | 43% |
| context-ferry | 10,688 B | 7,122 B | 33% (below the 40% target; safety rules kept resident) |
One rule outranks the byte savings: hard gates and "never" rules always stay in the kernel. That rule is enforced by review, not assumed: review caught all three of these splits moving or deleting safety content (anti-rubber-stamping rules, a required search step, a write-back procedure), and each was restored. Design: docs/harness/README.md.
Standout Skills
| Skill | What it does |
|---|
| code-review-battery | Starts with one combined reviewer (defects, guardrails, standards) and dispatches up to 7 specialist reviewers in parallel when the diff signals design, performance, security, or shell risk. A bug-path verifier joins in bug-fix mode. Configurable quality bar |
| debate | Three or more options, a comparison matrix, then a red-team pass on the winner before committing to a design |
| systematic-debugging | Reproduce, hypothesize, isolate, fix. No fix until the investigation is complete |
| feature-development | The full lifecycle as one orchestrated sequence, so no phase gets skipped |
| llm-skill-review | Reviews skills as infrastructure that models execute: determinism, shell portability, tool contracts, cross-agent behavior |
| context-ferry | Writes a self-contained resume prompt before context compaction, so long sessions keep their state |
| detecting-ai-slop | Scores text 0-100 for machine-generated patterns across lexical, structural, semantic, and stylometric signals |
|
All 125 skills: docs/SKILLS.md. How they connect: docs/SKILL_TAXONOMY.md.
Platform Support
| Platform | Support |
|---|
| Claude Code | Full: skills, lifecycle hooks, commit and push gates, approval guardrails |
| Augment Code | Full: skills, routing, commit and push gates, MCP integrations |
| Codex, OpenCode | Skills, via the platform install guides. Git gates work with any assistant because git runs them; Claude Code lifecycle hooks do not apply |
| Gemini CLI | No installer. GEMINI.md points Gemini at the repo's agent guidance |
| Claude Desktop | Code tab: same as Claude Code. Chat and Cowork: eleven uploadable skills. Chat can also reach all skills through the MCP server. See Claude Desktop |
| Other MCP clients | Skills exposed as find_skills, use_skill, and match_skills tools |
What's Included
| Domain | Examples |
|---|
| engineering | Code review battery, debate, TDD, systematic debugging, feature lifecycle, commit gates |
| productivity | Task tracking, plan-and-execute, think-twice, adversarial search, context-ferry |
| writing | AI slop detection and rewriting, professional-language audit, table discipline, plain-language explanations |
| wiki | Publishing pipeline with link verification, credential scanning, and fact-checking |
| observability | Completeness checks, evolution loop, audit validation, diagnostics |
| issue-tracking | Authoring, editing, verification, link checks |
| security | Repo scanning, CVE scanning, IP protection, instruction guard |
| research | Research integration, expert interviewing |
| experimental | Self-prompting patterns |
Building on It
obra/superpowers (Jesse Vincent, MIT)
└── superpowers-plus (this repo)
└── your-org-skills (private overlay)
All 14 obra/superpowers skills are bundled here, nine of them hardened with extra enforcement gates; upstream changes are merged periodically. Teams can add a private repo on top that shadows or extends these skills with their own issue tracker, wiki, and conventions. See the Enterprise Adopters Guide, including its security checklist for overlays.
Documentation
License
MIT
