RepoPilot

obra/superpowers

An agentic skills framework & software development methodology that works.

Healthy

Healthy across all four use cases

HealthyDependency

Permissive license, no critical CVEs, actively maintained — safe to depend on.

HealthyFork & modify

Has a license, tests, and CI — clean foundation to fork and modify.

HealthyLearn from

Documented and popular — useful reference codebase to read through.

HealthyDeploy as-is

No critical CVEs, sane security posture — runnable as-is.

  • ⚠Concentrated ownership — top contributor handles 63% of recent commits
  • ⚠No CI workflows detected
  • ✓Last commit 3d ago
  • ✓10 active contributors
  • ✓MIT licensed
  • ✓Tests present

Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests

Informational only. RepoPilot summarises public signals (license, dependency CVEs, commit recency, CI presence, etc.) at the time of analysis. Signals can be incomplete or stale. Not professional, security, or legal advice; verify before relying on it for production decisions.

Want this for your own repo?

Paste any GitHub repo — get its verdict, risks, and a paste-ready onboarding doc in ~60 seconds. Free, no sign-up.

Embed the "Healthy" badge

Paste into your README — live-updates from the latest cached analysis.

Variant:
RepoPilot: Healthy
[![RepoPilot: Healthy](https://repopilot.app/api/badge/obra/superpowers)](https://repopilot.app/r/obra/superpowers)

Paste at the top of your README.md — renders inline like a shields.io badge.

▸Preview social card

This card auto-renders when someone shares https://repopilot.app/r/obra/superpowers on X, Slack, or LinkedIn.

Ask AI about obra/superpowers

Grounded in the actual source code. Pick a starter question or write your own.

What does this repo do, in one paragraph?How would I get started using it?What are the main alternatives?Show me the entry point.
Or write your own question

Onboarding doc

Onboarding: obra/superpowers

Generated by RepoPilot · 2026-07-04 · Source

Verdict

Healthy — Healthy across all four use cases

  • Last commit 3d ago
  • 10 active contributors
  • MIT licensed
  • Tests present
  • ⚠ Concentrated ownership — top contributor handles 63% of recent commits
  • ⚠ No CI workflows detected

Computed from maintenance signals — commit recency, contributor breadth, bus factor, license, CI, tests

TL;DR

Superpowers is a multi-agent coding framework that installs as a plugin into AI coding assistants (Claude Code, Codex CLI/App, Gemini CLI, Cursor, OpenCode) and injects a structured software development methodology — spec-first design, TDD-enforced implementation planning, and subagent-driven-development — directly into the agent's behavior via AGENTS.md/CLAUDE.md/GEMINI.md instruction files and platform-specific plugin manifests. It solves the problem of LLM coding agents jumping straight to code without planning, by forcing a spec → plan → subagent execution loop with review checkpoints. See architecture tab.

LLM-derived; treat as a starting point, not verified fact.

Who it's for

Developers who use AI coding agents (especially Claude Code) for non-trivial software projects and want disciplined, autonomous multi-hour coding sessions without the agent going off-rails; also contributors who want to add support for new AI agent harnesses (e.g. new plugin adapters).

LLM-derived; treat as a starting point, not verified fact.

Maturity & risk

The repo is at v5.1.0 with active development visible in dated design docs spanning from late 2025 through April 2026, and has a structured release notes file (RELEASE-NOTES.md) and a .version-bump.json tracking versioning. No CI config or test directory is visible in the file structure, which is a gap. Given the version number, active planning docs, and multi-platform support, it is actively developed but not production-hardened in the traditional sense — more of a living methodology artifact.

Single-maintainer risk is real — Jesse (obra) appears to be the sole author, with a GitHub Sponsors link in .github/FUNDING.yml. There are no automated tests or CI pipelines visible in the file structure, meaning regressions in shell scripts or plugin JS could go undetected. The project's value is tightly coupled to the behavior of third-party AI agents (Claude, Codex, Gemini) whose APIs and plugin systems can change without notice, as evidenced by the dedicated Codex App compatibility plan at docs/superpowers/plans/2026-03-23-codex-app-compatibility.md.

LLM-derived; treat as a starting point, not verified fact.

Active areas of work

Active work visible includes a worktree rototill redesign (docs/superpowers/plans/2026-04-06-worktree-rototill.md and matching spec), Codex App compatibility work (2026-03-23), a zero-dependency brainstorm server (2026-03-11), and a visual brainstorming refactor (2026-02-19). The most recent plan is the worktree rototill from April 2026, suggesting active architectural evolution of how parallel agent worktrees are managed.

LLM-derived; treat as a starting point, not verified fact.

Get running

git clone https://github.com/obra/superpowers.git && cd superpowers

No npm install needed — no node_modules dependencies

To install into Claude Code:

/plugin install superpowers@claude-plugins-official

Or to use directly from clone, point your agent harness at the local plugin manifest

Daily commands: There is no dev server. The 'runtime' is the AI agent itself. To test changes locally, point your agent harness at the local plugin path. For OpenCode specifically, the entry point is .opencode/plugins/superpowers.js. For Cursor, hooks are loaded from hooks/hooks.json.

Map of the codebase

  • CLAUDE.md — Primary agent instruction file that bootstraps the entire Superpowers methodology for Claude Code — defines how the agent behaves from session start.
  • skills/using-superpowers/SKILL.md — Meta-skill that teaches the agent how to discover and load all other skills — the entry point for the skills framework itself.
  • .opencode/plugins/superpowers.js — The OpenCode plugin entry point (also the npm package main) — the only runtime JavaScript in the repo, used to inject skills into OpenCode.
  • hooks/hooks.json — Defines lifecycle hooks (e.g. session-start) that wire Superpowers into agent tool calls across supported platforms.
  • skills/subagent-driven-development/SKILL.md — Core development methodology skill — describes the parallel subagent TDD workflow that is the heart of the Superpowers approach.
  • skills/writing-plans/SKILL.md — Defines the plan-writing convention every contributor must follow; all implementation work flows through this structure.
  • AGENTS.md — Agent-agnostic bootstrap instructions used by platforms like Codex — mirrors CLAUDE.md for non-Claude agents.

How to make changes

Add a new Skill

  1. Create a new directory under skills/ named after your skill using kebab-case (e.g. skills/my-new-skill/) (skills/my-new-skill/SKILL.md)
  2. Write the SKILL.md following the conventions in existing skills — include a purpose statement, when to use it, and step-by-step instructions for the agent (skills/my-new-skill/SKILL.md)
  3. Register the skill in the meta-skill so agents know it exists and when to load it (skills/using-superpowers/SKILL.md)
  4. If the skill needs supporting prompts for subagent roles, add markdown prompt files in the skill directory (e.g. my-role-prompt.md) (skills/my-new-skill/my-role-prompt.md)

Add support for a new AI agent platform

  1. Create a plugin manifest directory named .<platform>-plugin/ with a plugin.json following the pattern of existing plugin manifests (.claude-plugin/plugin.json)
  2. Write a platform-specific bootstrap markdown file in the repo root (e.g. MYPLATFORM.md) mirroring CLAUDE.md structure — point it to skills/using-superpowers/SKILL.md (CLAUDE.md)
  3. If the platform supports lifecycle hooks, add a hooks configuration file (e.g. hooks/hooks-myplatform.json) referencing the session-start hook (hooks/hooks.json)
  4. Document installation steps in README.md under a new platform section (README.md)

Add a new subagent role prompt

  1. Identify which skill the new role belongs to and navigate to that skill's directory (skills/subagent-driven-development/SKILL.md)
  2. Create a new markdown file named <role>-prompt.md in the skill directory, following the pattern of existing role prompts (skills/subagent-driven-development/implementer-prompt.md)
  3. Reference the new prompt file from the parent SKILL.md so the orchestrating agent knows to inject it when spawning that role (skills/subagent-driven-development/SKILL.md)

Add a design document or plan for a new feature

  1. Write a plan document under docs/superpowers/plans/ with a date-prefixed filename (e.g. YYYY-MM-DD-feature-name.md) following the writing-plans skill conventions (skills/writing-plans/SKILL.md)
  2. Write the corresponding spec/design document under docs/superpowers/specs/ with the same date-prefixed name (docs/superpowers/specs/2026-04-06-worktree-rototill-design.md)
  3. If the plan requires a brainstorming session, use the brainstorming skill and save outputs alongside the plan (skills/brainstorming/SKILL.md)

Why these technologies

  • Markdown (SKILL.md files) — LLMs consume plain text natively — markdown skill files are directly readable by any AI agent without any parsing layer, making the framework universally portable across all supported platforms.
  • Zero-dependency Node.js (server.cjs) — The brainstorming server uses only Node.js built-ins (http, fs, path) so it runs in any environment without npm install, keeping the tool lightweight and eliminating dependency management overhead.
  • Platform plugin manifests (plugin.json per platform) — Each

Traps & gotchas

The hooks/run-hook.cmd file indicates Windows support exists but is handled separately — Windows users must use the batch runner, not the shell scripts directly (see docs/windows/polyglot-hooks.md). The package.json has "type": "module" so superpowers.js uses ESM syntax; any Node.js version below 14 will break it. There are no npm dependencies, but the plugin manifests (.claude-plugin/marketplace.json) reference external marketplace registries that could go stale. Platform plugin APIs (especially Codex App) have had breaking changes requiring dedicated compatibility work, so testing against the latest harness version is essential.

Architecture

Concepts to learn

  • Subagent-driven development — The core execution model of Superpowers — spawning child agents per task and reviewing their output — is what enables autonomous multi-hour runs without drift
  • Git worktrees — The 2026-04-06 worktree rototill plan reveals Superpowers uses git worktrees to isolate parallel subagent work; understanding worktrees is essential to understanding that architecture
  • YAGNI (You Aren't Gonna Need It) — Explicitly called out in AGENTS.md as a core principle enforced during plan generation, shaping what the agent is allowed to implement
  • Red/Green TDD (Test-Driven Development) — Superpowers enforces true red/green TDD in its implementation plans, meaning agents must write failing tests before implementation code
  • Agent instruction injection via AGENTS.md — The mechanism by which Superpowers works — placing AGENTS.md / CLAUDE.md in a repo root causes compliant agent harnesses to load those instructions automatically at startup
  • Plugin manifest registries — Superpowers distributes via multiple competing plugin marketplace systems (Claude's official, Superpowers' own, Codex's), each with their own JSON manifest schema under .claude-plugin/, .codex-plugin/, .cursor-plugin/

Related repos

  • anthropics/claude-code — Primary harness Superpowers is built for; plugin system used by .claude-plugin/ manifests
  • openai/codex — Second major target harness, with dedicated .codex-plugin/ support and Codex App compatibility plans
  • paul-gauthier/aider — Close alternative: an agentic coding assistant with its own methodology/conventions, solves the same 'disciplined AI coding' problem
  • continuedev/continue — Ecosystem alternative: IDE-integrated coding agent with plugin/slash command extensibility similar to Superpowers' hook system
  • obra/superpowers-marketplace — Companion repo: the Superpowers plugin marketplace registry referenced directly in the README installation instructions

PR ideas

Click to expand

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add a GitHub Actions CI workflow to lint and validate all SKILL.md files and plugin manifests

The repo has multiple plugin manifests (.claude-plugin/plugin.json, .codex-plugin/plugin.json, .cursor-plugin/plugin.json, gemini-extension.json) and SKILL.md files under skills/. There is no .github/workflows/ directory visible in the file tree, meaning there is zero automated validation. A CI workflow that (1) validates JSON syntax of all plugin manifests, (2) checks that every skills/*/SKILL.md exists and is non-empty, and (3) runs package.json scripts would catch regressions when contributors add new skills or update manifests.

  • [ ] Create .github/workflows/ci.yml triggered on pull_request and push to main
  • [ ] Add a job that runs node --input-type=module or jq to validate JSON files: .claude-plugin/plugin.json, .claude-plugin/marketplace.json, .codex-plugin/plugin.json, .cursor-plugin/plugin.json, gemini-extension.json
  • [ ] Add a job step that iterates over skills/*/SKILL.md and asserts each file exists and has content > 0 bytes
  • [ ] Add a job step that runs npm install && npm test (or whichever script is defined in package.json) to exercise .opencode/plugins/superpowers.js
  • [ ] Add a badge to README.md pointing to the new workflow

Add unit tests for .opencode/plugins/superpowers.js (the only runtime JS entry point)

package.json declares main as .opencode/plugins/superpowers.js, making it the sole runtime entry point for the OpenCode plugin integration. The file structure shows no test directory and no test-related files anywhere in the repo. Because this file is what every OpenCode user actually executes, even basic smoke tests (does it export the expected hooks? does it fail gracefully when config is missing?) would dramatically improve contributor confidence and catch breakage from the brainstorming server scripts it likely wires together (skills/brainstorming/scripts/server.cjs, helper.js, start-server.sh).

  • [ ] Create a tests/ directory at the repo root and add tests/superpowers.test.js using Node's built-in node:test runner (zero new dependencies, consistent with the zero-dep philosophy in docs/superpowers/plans/2026-03-11-zero-dep-brainstorm-server.md)
  • [ ] Write a test that imports .opencode/plugins/superpowers.js and asserts the exported object has the shape expected by the OpenCode plugin API (as documented in .opencode/INSTALL.md and docs/README.opencode.md)
  • [ ] Write a test that verifies the plugin does not throw on import when optional env vars are absent
  • [ ] Write a test that verifies skills/brainstorming/scripts/helper.js exports its utility functions correctly
  • [ ] Add "test": "node --test tests/*.test.js" to the scripts section of package.json

Extract the brainstorming server startup/shutdown logic from shell scripts into a single cross-platform Node.js script, replacing start-server.sh and stop-server.sh

skills/brainstorming/scripts/ contains start-server.sh and stop-server.sh — bash-only scripts that break on Windows without WSL. The repo already acknowledges Windows complexity (docs/windows/polyglot-hooks.md, hooks/run-hook.cmd) and has a zero-dep server design doc (docs/superpowers/plans/2026-03-11-zero-dep-brainstorm-server.md). Replacing these two shell scripts with a single manage-server.js (using only node:child_process, node:fs, node:path) would remove the bash dependency, make the brainstorming skill work natively on Windows, and consolidate the duplicated process-management logic that currently lives across start-server.sh, stop-server

Good first issues

  1. Add automated shell script linting (e.g. shellcheck via GitHub Actions) — no CI exists and the repo is majority Shell code with no static analysis. 2. Write a docs/windows/codex-compatibility.md parallel to docs/windows/polyglot-hooks.md covering Codex App Windows-specific quirks, which the 2026-03-23 plan implies are an open issue. 3. Add a CONTRIBUTING.md documenting the plan→spec→implementation doc convention used under docs/superpowers/plans/ and docs/superpowers/specs/, since this workflow is non-obvious to new contributors.

Top contributors

Click to expand
  • @obra — 63 commits
  • @jesse — 13 commits
  • @arittr — 10 commits
  • [@Drew Ritter](https://github.com/Drew Ritter) — 7 commits
  • @savvyinsight — 2 commits

Recent commits

Click to expand
  • f2cbfbe — Release v5.1.0 (#1468) (obra)
  • e7a2d16 — Require session transcript for new-harness PRs (Jesse Vincent)
  • 6efe32c — Use committed Codex plugin files in sync script (obra)
  • b557648 — formatting (obra)
  • 9f42444 — formatting (obra)
  • 99e4c65 — reorder installs (obra)
  • a5dd364 — README updates for Codex, other cleanup (obra)
  • c4bbe65 — Some terminology cleanups (obra)
  • 34c17ae — sync-to-codex-plugin: seed interface.defaultPrompt (#1180) (arittr)
  • f9b088f — Merge pull request #1165 from obra/mirror-codex-plugin-tooling (obra)

Security observations

Click to expand
  • High · Potential XSS via Unsanitized HTML in Brainstorming Frame Template — skills/brainstorming/scripts/frame-template.html, skills/brainstorming/scripts/server.cjs. The file 'skills/brainstorming/scripts/frame-template.html' is a server-rendered or dynamically generated HTML template. If user-controlled or agent-generated content is injected into this template without proper sanitization or escaping, it could lead to Cross-Site Scripting (XSS) attacks. Combined with a local HTTP server (server.cjs), any injected script could execute in the user's browser context. Fix: Ensure all dynamic content inserted into HTML templates is properly HTML-escaped. Use a Content Security Policy (CSP) header in server.cjs responses. Avoid using innerHTML or equivalent patterns with untrusted data. Prefer text content injection over HTML injection.
  • High · Local HTTP Server with Potential Missing Security Headers — skills/brainstorming/scripts/server.cjs. The file 'skills/brainstorming/scripts/server.cjs' implements a local HTTP server (likely Node.js using CommonJS). Local development servers frequently omit security headers such as Content-Security-Policy, X-Frame-Options, X-Content-Type-Options, and CORS restrictions. If the server binds to 0.0.0.0 instead of 127.0.0.1, it may be accessible to other hosts on the local network, expanding the attack surface. Fix: Ensure the server explicitly binds to 127.0.0.1 (localhost only). Add security headers to all responses: Content-Security-Policy, X-Content-Type-Options: nosniff, X-Frame-Options: DENY. Implement strict CORS policies. Validate and sanitize all input parameters in request handlers.
  • High · Potential Arbitrary Command Execution via Shell Scripts — skills/brainstorming/scripts/start-server.sh, skills/brainstorming/scripts/stop-server.sh, skills/systematic-debugging/find-polluter.sh, scripts/bump-version.sh. Shell scripts such as 'skills/brainstorming/scripts/start-server.sh', 'skills/brainstorming/scripts/stop-server.sh', 'skills/systematic-debugging/find-polluter.sh', and 'scripts/bump-version.sh' may accept or interpolate external input (e.g., environment variables, arguments) into shell commands without proper quoting or sanitization. This is a common source of command injection vulnerabilities. Fix: Audit all shell scripts for unquoted variable expansions and external input interpolation. Use double-quoted variables ("$VAR") consistently. Avoid eval and dynamic command construction from external input. Consider replacing shell scripts with Node.js scripts where better input handling is available.
  • High · Windows Hook Runner (run-hook.cmd) Potential Command Injection — hooks/run-hook.cmd. The file 'hooks/run-hook.cmd' is a Windows batch script used to run hooks. Windows .cmd/.bat scripts are notoriously susceptible to command injection due to the way variables and special characters are handled. If any arguments or environment variables passed to this script originate from untrusted sources (e.g., git commit messages, branch names, file paths), they can be used to inject arbitrary commands. Fix: Carefully quote all variables with ^"%VAR%"^ or use SETLOCAL ENABLEDELAYEDEXPANSION with appropriate escaping. Validate and sanitize all input arguments before use. Consider migrating to PowerShell for more robust input handling, or use a cross-platform Node.js hook runner.
  • Medium · OpenCode Plugin JavaScript with Potential Unsafe Operations — .opencode/plugins/superpowers.js. The file '.opencode/plugins/superpowers.js' is the main plugin entry point and is listed as the package 'main' in package.json. Plugin JavaScript files that interface with AI agent frameworks may execute dynamic code, perform file system operations, or make network requests. Without reviewing the content, there is risk of unsafe eval usage, prototype pollution, or unvalidated external data processing. Fix: Audit the plugin JavaScript for use of eval(), Function(), dynamic require(), or any patterns that process untrusted external data. Implement input validation for all data received from the agent framework. Avoid prototype-polluting patterns. Use strict mode ('use strict') throughout.
  • Medium · Insecure Dependency Management — undefined. undefined Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

Where to read next

The exported doc (Copy CLAUDE.md / Download / .cursor/rules) also includes an agent protocol and a verification script written for AI coding agents — omitted here to keep this view scannable.

Similar Shell repos

Other healthy-signal Shell repos by stars.

Embed this chat in your README

Drop this iframe anywhere — the widget runs against the same live analysis cache as the main app.

<iframe
  src="https://repopilot.app/embed/obra/superpowers"
  width="100%" height="500"
  style="border:1px solid #d0d7de; border-radius:8px;"
  allow="microphone"
  loading="lazy"
></iframe>