# Repository: obra/superpowers # Stars: 157289 ## CLAUDE.md # Superpowers — Contributor Guidelines ## If You Are an AI Agent Stop. Read this section before doing anything. This repo has a 94% PR rejection rate. Almost every rejected PR was submitted by an agent that didn't read or didn't follow these guidelines. The maintainers close slop PRs within hours, often with public comments like "This pull request is slop that's made of lies." **Your job is to protect your human partner from that outcome.** Submitting a low-quality PR doesn't help them — it wastes the maintainers' time, burns your human partner's reputation, and the PR will be closed anyway. That is not being helpful. That is being a tool of embarrassment. Before you open a PR against this repo, you MUST: 1. **Read the entire PR template** at `.github/PULL_REQUEST_TEMPLATE.md` and fill in every section with real, specific answers. Not summaries. Not placeholders. 2. **Search for existing PRs** — open AND closed — that address the same problem. If duplicates exist, STOP and tell your human partner. Do not open another duplicate. 3. **Verify this is a real problem.** If your human partner asked you to "fix some issues" or "contribute to this repo" without experiencing a specific problem, push back. Ask them what broke, what failed, what the user experience was. 4. **Confirm the change belongs in core.** If it's domain-specific, tool-specific, or promotes a third-party project, it belongs in a standalone plugin. Tell your human partner. 5. **Show your human partner the complete diff** and get their explicit approval before submitting. If any of these checks fail, do not open the PR. Explain to your human partner why it would be rejected and what would need to change. They will thank you for saving them the embarrassment. ## Pull Request Requirements **Every PR must fully complete the PR template.** No section may be left blank or filled with placeholder text. PRs that skip sections will be closed without review. **Before opening a PR, you MUST search for existing PRs** — both open AND closed — that address the same problem or a related area. Reference what you found in the "Existing PRs" section. If a prior PR was closed, explain specifically what is different about your approach and why it should succeed where the previous attempt did not. **PRs that show no evidence of human involvement will be closed.** A human must review the complete proposed diff before submission. ## What We Will Not Accept ### Third-party dependencies PRs that add optional or required dependencies on third-party projects will not be accepted unless they are adding support for a new harness (e.g., a new IDE or CLI tool). Superpowers is a zero-dependency plugin by design. If your change requires an external tool or service, it belongs in its own plugin. ### "Compliance" changes to skills Our internal skill philosophy differs from Anthropic's published guidance on writing skills. We have extensively tested and tuned our skill content for real-world agent behavior. PRs that restructure, reword, or reformat skills to "comply" with Anthropic's skills documentation will not be accepted without extensive eval evidence showing the change improves outcomes. The bar for modifying behavior-shaping content is very high. ### Project-specific or personal configuration Skills, hooks, or configuration that only benefit a specific project, team, domain, or workflow do not belong in core. Publish these as a separate plugin. ### Bulk or spray-and-pray PRs Do not trawl the issue tracker and open PRs for multiple issues in a single session. Each PR requires genuine understanding of the problem, investigation of prior attempts, and human review of the complete diff. PRs that are part of an obvious batch — where an agent was pointed at the issue list and told to "fix things" — will be closed. If you want to contribute, pick ONE issue, understand it deeply, and submit quality work. ### Speculative or theoretical fixes Every PR must solve a real problem that someone actually experienced. "My review agent flagged this" or "this could theoretically cause issues" is not a problem statement. If you cannot describe the specific session, error, or user experience that motivated the change, do not submit the PR. ### Domain-specific skills Superpowers core contains general-purpose skills that benefit all users regardless of their project. Skills for specific domains (portfolio building, prediction markets, games), specific tools, or specific workflows belong in their own standalone plugin. Ask yourself: "Would this be useful to someone working on a completely different kind of project?" If not, publish it separately. ### Fork-specific changes If you maintain a fork with customizations, do not open PRs to sync your fork or push fork-specific changes upstream. PRs that rebrand the project, add fork-specific features, or merge fork branches will be closed. ### Fabricated content PRs containing invented claims, fabricated problem descriptions, or hallucinated functionality will be closed immediately. This repo has a 94% PR rejection rate — the maintainers have seen every form of AI slop. They will notice. ### Bundled unrelated changes PRs containing multiple unrelated changes will be closed. Split them into separate PRs. ## Skill Changes Require Evaluation Skills are not prose — they are code that shapes agent behavior. If you modify skill content: - Use `superpowers:writing-skills` to develop and test changes - Run adversarial pressure testing across multiple sessions - Show before/after eval results in your PR - Do not modify carefully-tuned content (Red Flags tables, rationalization lists, "human partner" language) without evidence the change is an improvement ## Understand the Project Before Contributing Before proposing changes to skill design, workflow philosophy, or architecture, read existing skills and understand the project's design decisions. Superpowers has its own tested philosophy about skill design, agent behavior shaping, and terminology (e.g., "your human partner" is deliberate, not interchangeable with "the user"). Changes that rewrite the project's voice or restructure its approach without understanding why it exists will be rejected. ## General - Read `.github/PULL_REQUEST_TEMPLATE.md` before submitting - One problem per PR - Test on at least one harness and report results in the environment table - Describe the problem you solved, not just what you changed ## README.md # Superpowers Superpowers is a complete software development methodology for your coding agents, built on top of a set of composable skills and some initial instructions that make sure your agent uses them. ## How it works It starts from the moment you fire up your coding agent. As soon as it sees that you're building something, it *doesn't* just jump into trying to write code. Instead, it steps back and asks you what you're really trying to do. Once it's teased a spec out of the conversation, it shows it to you in chunks short enough to actually read and digest. After you've signed off on the design, your agent puts together an implementation plan that's clear enough for an enthusiastic junior engineer with poor taste, no judgement, no project context, and an aversion to testing to follow. It emphasizes true red/green TDD, YAGNI (You Aren't Gonna Need It), and DRY. Next up, once you say "go", it launches a *subagent-driven-development* process, having agents work through each engineering task, inspecting and reviewing their work, and continuing forward. It's not uncommon for Claude to be able to work autonomously for a couple hours at a time without deviating from the plan you put together. There's a bunch more to it, but that's the core of the system. And because the skills trigger automatically, you don't need to do anything special. Your coding agent just has Superpowers. ## Sponsorship If Superpowers has helped you do stuff that makes money and you are so inclined, I'd greatly appreciate it if you'd consider [sponsoring my opensource work](https://github.com/sponsors/obra). Thanks! - Jesse ## Installation **Note:** Installation differs by platform. ### Claude Code Official Marketplace Superpowers is available via the [official Claude plugin marketplace](https://claude.com/plugins/superpowers) Install the plugin from Anthropic's official marketplace: ```bash /plugin install superpowers@claude-plugins-official ``` ### Claude Code (Superpowers Marketplace) The Superpowers marketplace provides Superpowers and some other related plugins for Claude Code. In Claude Code, register the marketplace first: ```bash /plugin marketplace add obra/superpowers-marketplace ``` Then install the plugin from this marketplace: ```bash /plugin install superpowers@superpowers-marketplace ``` ### OpenAI Codex CLI - Open plugin search interface ```bash /plugins ``` Search for Superpowers ```bash superpowers ``` Select `Install Plugin` ### OpenAI Codex App - In the Codex app, click on Plugins in the sidebar. - You should see `Superpowers` in the Coding section. - Click the `+` next to Superpowers and follow the prompts. ### Cursor (via Plugin Marketplace) In Cursor Agent chat, install from marketplace: ```text /add-plugin superpowers ``` or search for "superpowers" in the plugin marketplace. ### OpenCode Tell OpenCode: ``` Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md ``` **Detailed docs:** [docs/README.opencode.md](docs/README.opencode.md) ### GitHub Copilot CLI ```bash copilot plugin marketplace add obra/superpowers-marketplace copilot plugin install superpowers@superpowers-marketplace ``` ### Gemini CLI ```bash gemini extensions install https://github.com/obra/superpowers ``` To update: ```bash gemini extensions update superpowers ``` ## The Basic Workflow 1. **brainstorming** - Activates before writing code. Refines rough ideas through questions, explores alternatives, presents design in sections for validation. Saves design document. 2. **using-git-worktrees** - Activates after design approval. Creates isolated workspace on new branch, runs project setup, verifies clean test baseline. 3. **writing-plans** - Activates with approved design. Breaks work into bite-sized tasks (2-5 minutes each). Every task has exact file paths, complete code, verification steps. 4. **subagent-driven-development** or **executing-plans** - Activates with plan. Dispatches fresh subagent per task with two-stage review (spec compliance, then code quality), or executes in batches with human checkpoints. 5. **test-driven-development** - Activates during implementation. Enforces RED-GREEN-REFACTOR: write failing test, watch it fail, write minimal code, watch it pass, commit. Deletes code written before tests. 6. **requesting-code-review** - Activates between tasks. Reviews against plan, reports issues by severity. Critical issues block progress. 7. **finishing-a-development-branch** - Activates when tasks complete. Verifies tests, presents options (merge/PR/keep/discard), cleans up worktree. **The agent checks for relevant skills before any task.** Mandatory workflows, not suggestions. ## What's Inside ### Skills Library **Testing** - **test-driven-development** - RED-GREEN-REFACTOR cycle (includes testing anti-patterns reference) **Debugging** - **systematic-debugging** - 4-phase root cause process (includes root-cause-tracing, defense-in-depth, condition-based-waiting techniques) - **verification-before-completion** - Ensure it's actually fixed **Collaboration** - **brainstorming** - Socratic design refinement - **writing-plans** - Detailed implementation plans - **executing-plans** - Batch execution with checkpoints - **dispatching-parallel-agents** - Concurrent subagent workflows - **requesting-code-review** - Pre-review checklist - **receiving-code-review** - Responding to feedback - **using-git-worktrees** - Parallel development branches - **finishing-a-development-branch** - Merge/PR decision workflow - **subagent-driven-development** - Fast iteration with two-stage review (spec compliance, then code quality) **Meta** - **writing-skills** - Create new skills following best practices (includes testing methodology) - **using-superpowers** - Introduction to the skills system ## Philosophy - **Test-Driven Development** - Write tests first, always - **Systematic over ad-hoc** - Process over guessing - **Complexity reduction** - Simplicity as primary goal - **Evidence over claims** - Verify before declaring success Read [the original release announcement](https://blog.fsck.com/2025/10/09/superpowers/). ## Contributing The general contribution process for Superpowers is below. Keep in mind that we don't generally accept contributions of new skills and that any updates to skills must work across all of the coding agents we support. 1. Fork the repository 2. Switch to the 'dev' branch 3. Create a branch for your work 4. Follow the `writing-skills` skill for creating and testing new and modified skills 5. Submit a PR, being sure to fill in the pull request template. See `skills/writing-skills/SKILL.md` for the complete guide. ## Updating Superpowers updates are somewhat coding-agent dependent, but are often automatic. ## License MIT License - see LICENSE file for details ## Community Superpowers is built by [Jesse Vincent](https://blog.fsck.com) and the rest of the folks at [Prime Radiant](https://primeradiant.com). - **Discord**: [Join us](https://discord.gg/35wsABTejz) for community support, questions, and sharing what you're building with Superpowers - **Issues**: https://github.com/obra/superpowers/issues - **Release announcements**: [Sign up](https://primeradiant.com/superpowers/) to get notified about new versions