Superpowers

obra/superpowers at 22f0b46

15 skills · 109 files shown of 236 · license: MIT · imported 2026-11-10

About

Superpowers is a software development method for coding agents, made by Jesse Vincent and Prime Radiant and packaged as 15 skills plus a short bootstrap that runs at the start of every session. The skills take a piece of work from a brainstormed design, through a written plan of small test-first tasks, to implementation by fresh subagents with a review after each task and a final review of the whole branch. What sets it apart is that the skills trigger on their own instead of waiting to be called, the same skills install into more than a dozen coding agents from this one repo, and the skill text is tuned with pressure tests and evals, including tables of the excuses agents use to skip a step.

How the repo is organized

All 15 skills sit side by side in skills/<name>/, each with its own SKILL.md and any prompts, references, or scripts it needs. The repo ships them as one plugin named superpowers, so skills refer to each other with that prefix, as in superpowers:writing-plans. There are no category folders; this page groups the skills the way the README’s “What’s Inside” section does (Testing, Debugging, Collaboration, Meta).

The workflow. Most skills form one chain: brainstorming produces an approved design doc, using-git-worktrees sets up an isolated branch, writing-plans turns the design into a task-by-task plan, and then subagent-driven-development or executing-plans carries it out, with test-driven-development inside every task and requesting-code-review after tasks. finishing-a-development-branch ends the chain with a merge, a pull request, or keeping the branch. The other skills (systematic-debugging, verification-before-completion, receiving-code-review, dispatching-parallel-agents, diagnosing-superpowers, writing-skills) are called from inside the chain or on their own. Skills save their outputs in the user’s project: designs in docs/superpowers/specs/, plans in docs/superpowers/plans/, and working files in a git-ignored .superpowers/ folder.

What runs automatically. The using-superpowers skill is the bootstrap. It tells the agent to check for a relevant skill before any response, and each harness gets it into the start of the session in its own way:

Claude Code runs hooks/hooks.json on startup, /clear, and compaction. The hook calls hooks/session-start through hooks/run-hook.cmd, and the script returns the text of skills/using-superpowers/SKILL.md as extra context. Cursor (hooks/hooks-cursor.json), Copilot CLI, and Muse run the same script.
OpenCode (.opencode/plugins/superpowers.js), Pi (.pi/extensions/superpowers.ts), and Hermes (.hermes-plugin/__init__.py) use small in-process plugins that insert the same text as a user message.
Gemini CLI loads it through GEMINI.md, and Kimi Code’s manifest names it as the session-start skill.
Codex, Devin, and Antigravity have no hook. They show the agent each skill’s description, and the using-superpowers description asks to be used at the start of every conversation.

Installing. Each harness has its own manifest at the repo root: .claude-plugin/ (Claude Code; Qwen Code and Factory Droid also read it), .codex-plugin/ and .agents/plugins/marketplace.json (Codex), .cursor-plugin/, .devin-plugin/, .kimi-plugin/, .antigravity-plugin/, .muse-plugin/, .hermes-plugin/, gemini-extension.json, and package.json (Pi, and OpenCode package installs). The README gives the install command for each harness. .version-bump.json with scripts/bump-version.sh keeps the version number, 7.0.2 at this commit, the same in all of them.

Shared pieces. Skills share files through relative paths. executing-plans runs subagent-driven-development’s scripts/sdd-workspace, scripts/task-brief, and scripts/review-package and uses requesting-code-review’s code-reviewer.md, so both ways of running a plan keep the same ledger in .superpowers/sdd/<plan>/ and a plan can switch between them partway. Skills are written with Claude Code’s tool names; the files in skills/using-superpowers/references/ map those names to the tools of Codex, Pi, Gemini, Antigravity, Hermes, and Muse.

Network use. The brainstorming skill’s optional browser companion loads the Prime Radiant logo from primeradiant.com with the Superpowers version in the URL, which the README describes as telemetry. Setting SUPERPOWERS_DISABLE_TELEMETRY, DISABLE_TELEMETRY, or CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC turns it off.

Skills

Collaboration

Skill	Summary	Files
brainstorming	Before any creative work, has the agent find out what the person wants and why through one question at a time, lay out two or three ways to build it, and write a design doc that must be approved before anything is built. It can open a browser “visual companion” to show mockups and collect clicks.	8
dispatching-parallel-agents	When there are two or more independent problems, such as test failures in unrelated files, has the agent send one focused subagent per problem at the same time and then check that their fixes do not conflict.	1
executing-plans	Has the agent carry out a written plan itself in the current session, task by task with TDD and a progress ledger, followed by one fresh review of the whole branch. Used when the user chooses inline execution or the harness has no subagent tool.	3
finishing-a-development-branch	When implementation is done, has the agent run the full test suite and then offer a fixed menu: merge locally, push and open a pull request, or keep the branch. It removes only worktrees that Superpowers created, and deletes work only after the user types “discard”.	1
receiving-code-review	When review feedback arrives, has the agent check each point against the codebase before acting, ask about unclear items first, push back with technical reasons when a point is wrong, and leave out performative agreement and thanks.	1
requesting-code-review	Has the agent send a reviewer subagent a filled-in template with what was built, the requirements, and the commit range, then fix Critical and Important findings before moving on. Used after each task, after major features, and before merging.	2
subagent-driven-development	Has the agent run a plan as a controller: a fresh implementer subagent per task, a review for spec compliance and quality after each, a capped fix loop, a progress ledger that survives compaction, and a final review of the whole branch. Used when carrying out a plan whose tasks are mostly independent.	15
using-git-worktrees	Before feature work or running a plan, has the agent check whether it is already in an isolated workspace, and if not, ask and then create one with the harness’s own worktree tool or with `git worktree add`. It then runs project setup and checks that the tests pass before work starts.	1
writing-plans	Given an approved spec, has the agent write an implementation plan for an engineer new to the codebase, with exact files, interfaces, and tests split into small TDD tasks, and check it against the spec. It ends by asking the user to choose subagent-driven or inline execution.	1

Debugging

Skill	Summary	Files
diagnosing-superpowers	When a Superpowers session went wrong, has the agent pin down the complaint with the user, read the session transcripts on disk, and write a report in which every finding cites a `path:line`, using seven analyst subagents in parallel. On request it also files or comments on a GitHub issue or builds a scrubbed bundle of the session for the maintainers.	20
systematic-debugging	For any bug, test failure, or unexpected behavior, makes the agent find the root cause in four phases (investigation, pattern analysis, hypothesis testing, implementation) before proposing a fix, and stop to question the design after three failed fixes.	6
verification-before-completion	Before the agent says that work is done, fixed, or passing, makes it run the command that proves the claim in that same message and read the output.	1

Testing

Skill	Summary	Files
test-driven-development	When writing any feature or bug fix, makes the agent write a failing test first, watch it fail, then write the least code that passes, and delete any code written before its test.	2

Skill	Summary	Files
using-superpowers	The bootstrap that hooks and plugins load at the start of every session. It tells the agent to invoke any skill that might apply before responding, even before clarifying questions, and points to the tool-name mapping for each harness.	8
writing-skills	Treats writing a skill as test-driven development for documentation: run pressure scenarios with subagents without the skill, record how they fail, write the skill against those failures, and close loopholes until agents comply. Used when creating, editing, or testing skills.	10

Repository files

File	What it does
README.md
LICENSE
.claude-plugin/plugin.json	Claude Code plugin manifest: name `superpowers`, version 7.0.2, description, author, homepage, MIT license, and keywords.
.claude-plugin/marketplace.json	A marketplace named `superpowers-dev`, owned by Jesse Vincent, that lists one plugin, `superpowers` 7.0.2, with source `./`, meaning this repo.
hooks/hooks.json	Claude Code hook config with one `SessionStart` hook for the `startup`, `clear`, and `compact` events.
hooks/session-start	Bash script, with no file extension, that reads `skills/using-superpowers/SKILL.md`, escapes it for JSON, wraps it in an `<EXTREMELY_IMPORTANT>` block that begins “You have superpowers.”, and prints it as extra context.
hooks/run-hook.cmd	A file that is both a Windows batch script and a bash script.
hooks/hooks-cursor.json	Cursor’s hook config (format version 1): on `sessionStart`, run `./hooks/run-hook.cmd session-start`.
.cursor-plugin/plugin.json	Cursor plugin manifest: name, display name, version 7.0.2, author, links, license, keywords, `skills: ./skills/`, and `hooks: ./hooks/hooks-cursor.json`.
.codex-plugin/plugin.json	Codex plugin manifest: version 7.0.2, `skills: ./skills/`, an empty `hooks` object, and an `interface` block with the display name, short and long descriptions, default prompts, a brand color, and icons from `assets/`.
.agents/plugins/marketplace.json	A marketplace named `superpowers-dev` in Codex’s format.
.devin-plugin/plugin.json	Devin CLI plugin manifest with name, version 7.0.2, description, author, links, license, and keywords.
.kimi-plugin/plugin.json	Kimi Code plugin manifest: `skills: ./skills/`, a `sessionStart` entry that loads the `using-superpowers` skill, and a long `skillInstructions` text that maps the skills’ actions to Kimi’s tools, for example asking questions with `AskUserQuestion`, todos with `TodoList`, and subagents with `Agent` using the `coder`, `explore`, or `plan` type.
.antigravity-plugin/plugin.json	Antigravity plugin manifest: name, display name, version 7.0.2, description, `assets/antigravity-logo.png` as logo, two suggested prompts, category, keywords, author, and license.
.muse-plugin/plugin.json	Muse plugin manifest (schema version 1).
.muse-plugin/marketplace.json	A `superpowers-dev` marketplace in the same format as `.claude-plugin/marketplace.json`, listing the one `superpowers` plugin from the repo root with a Muse-specific description.
.hermes-plugin/plugin.yaml	Hermes plugin manifest: name, version 7.0.2, description, author `obra`, and `provides_hooks` with `pre_llm_call`.
.hermes-plugin/init.py	Hermes plugin code.
gemini-extension.json	Gemini CLI extension manifest: name, description, version 7.0.2, and `contextFileName: GEMINI.md`.
GEMINI.md	Two `@` includes that pull `skills/using-superpowers/SKILL.md` and its Gemini tool mapping into Gemini CLI’s context.
package.json	Package manifest, version 7.0.2, with `main` set to `.opencode/plugins/superpowers.js` and a `pi` block that lists `.pi/extensions/superpowers.ts` as an extension and `./skills` as the skills folder.
.pi/extensions/superpowers.ts	Pi extension.
.opencode/plugins/superpowers.js	OpenCode plugin for both OpenCode 1.x and 2.x, with no dependencies.
index.js	One line that re-exports the default export of `.opencode/plugins/superpowers.js`.
.opencode/INSTALL.md	Install steps for OpenCode 1.x and 2.x.
docs/README.opencode.md	Longer guide to using Superpowers in OpenCode, linked from the README’s OpenCode section.
docs/README.kimi.md	Longer guide to using Superpowers in Kimi Code, linked from the README’s Kimi Code section.
docs/porting-to-a-new-harness.md	Maintainers’ guide to supporting a new coding agent.
docs/windows/polyglot-hooks.md	Explains the cross-platform design of `hooks/run-hook.cmd`.

Automated checks

The import scripts ran these checks on every shown file. They look for patterns that deserve a close read, such as hidden characters, wording that tries to override an agent, or commands that download and run code. A flag does not mean a file is malicious, and no flag does not mean it is safe.

Check	What it looks for	Flagged files
Prompt-injection wording	Wording often used to override an agent’s instructions or keep the user uninformed.	skills/brainstorming/visual-companion.md, skills/using-git-worktrees/SKILL.md
Touches credentials	Mentions SSH keys, cloud credentials, keychains, or token variables.	skills/systematic-debugging/SKILL.md
Runs automatically	Hooks run on agent events, such as session start or before a tool call, without the user asking.	hooks/hooks.json, hooks/session-start, hooks/run-hook.cmd, hooks/hooks-cursor.json
Hidden HTML comment	A comment that rendered Markdown hides. The page shows it as text.	skills/brainstorming/visual-companion.md (6)
Changes agent or shell settings	Mentions files that change how an agent or shell behaves, such as agent settings, CLAUDE.md, AGENTS.md, shell profiles, or scheduled jobs.	skills/diagnosing-superpowers/prompts/request-conflicts.md, skills/using-superpowers/SKILL.md, skills/using-superpowers/references/hermes-tools.md, skills/using-superpowers/references/muse-tools.md, skills/writing-skills/references/testing-skills-with-subagents.md, skills/writing-skills/references/CLAUDE_MD_TESTING.md (2), docs/porting-to-a-new-harness.md (6)

Other files in the repo

These files are listed but not shown. Each name links to the file on GitHub.

Tests

Tests for the plugin’s code and wiring, in bash, Node, and Python: the brainstorm server, the SDD and executing-plans scripts, each harness’s manifest and bootstrap, the hook scripts, shell lint, and limits on skill size and layout. Some scripts drive Claude Code headlessly to check that skills trigger. docs/testing.md explains that tests of agent behavior live in a separate repo, superpowers-evals, cloned into evals/.

80 files

Release and packaging scripts

Maintainer tools. bump-version.sh sets the version in every file that .version-bump.json lists and checks for stale version strings, package-codex-plugin.sh builds an archive for upload to OpenAI’s Codex plugin portal, sync-to-codex-plugin.sh opens a pull request that copies the plugin into Prime Radiant’s fork of OpenAI’s plugins repo, render-antigravity-logo.sh draws the Antigravity logo, and lint-shell.sh runs ShellCheck on the shell scripts.

6 files

Icons and logos

Images that the plugin manifests use: the Codex manifest shows app-icon.png and superpowers-small.svg, and the Antigravity manifest shows antigravity-logo.png.

3 files

Contributor rules and project history

AGENTS.md is a contributor guide addressed to AI agents, listing what a pull request must contain and what the maintainers reject. The .github folder holds the issue and pull request templates and a funding link, CODE_OF_CONDUCT.md is the code of conduct, and RELEASE-NOTES.md is the changelog up to v7.0.2.

9 files

Git and lint settings

Repository settings: line-ending rules that keep shell scripts and the polyglot hook working, ignored folders such as .worktrees/, .superpowers/, and the cloned evals/ harness, and pre-commit lint checks for that evals code.

3 files

Design specs and plans

Design documents and implementation plans for past changes to Superpowers itself, such as the visual brainstorming server, OpenCode support, and the SDD workspace. docs/superpowers/specs/ is the same place the brainstorming skill saves design docs in a user’s project.

26 files