If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/obra/superpowers shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — 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

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live obra/superpowers repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/obra/superpowers.

What it runs against: a local clone of obra/superpowers — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in obra/superpowers | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 33 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of obra/superpowers. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/obra/superpowers.git
#   cd superpowers
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of obra/superpowers and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "obra/superpowers(\\.git)?\\b" \\
  && ok "origin remote is obra/superpowers" \\
  || miss "origin remote is not obra/superpowers (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "CLAUDE.md" \\
  && ok "CLAUDE.md" \\
  || miss "missing critical file: CLAUDE.md"
test -f "skills/using-superpowers/SKILL.md" \\
  && ok "skills/using-superpowers/SKILL.md" \\
  || miss "missing critical file: skills/using-superpowers/SKILL.md"
test -f ".opencode/plugins/superpowers.js" \\
  && ok ".opencode/plugins/superpowers.js" \\
  || miss "missing critical file: .opencode/plugins/superpowers.js"
test -f "hooks/hooks.json" \\
  && ok "hooks/hooks.json" \\
  || miss "missing critical file: hooks/hooks.json"
test -f "skills/subagent-driven-development/SKILL.md" \\
  && ok "skills/subagent-driven-development/SKILL.md" \\
  || miss "missing critical file: skills/subagent-driven-development/SKILL.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 33 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~3d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/obra/superpowers"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

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.

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).

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.

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.

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.

• 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.

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)

• 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

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.

• 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/

• 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

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

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.

• 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.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.