This page describes the overall structure of obra/superpowers, its major components, and how it integrates with multiple AI coding platforms. It covers scope at the system level; see child pages for subsystem detail: Dual Repository Design, Skills Repository Management, Multi-Platform Integration, Session Lifecycle and Bootstrap, Skills Discovery and Resolution, and Tool Mapping Layer.
Superpowers is a single repository that simultaneously acts as a plugin for Claude Code, Cursor, OpenCode, and Codex. It provides:
The central design goal is that agents automatically discover and invoke skills without user intervention. The session bootstrap and skills discovery mechanisms exist to support that goal.
Sources: README.md1-15 .claude-plugin/plugin.json1-13 .cursor-plugin/plugin.json1-18
The diagram below maps high-level system concepts to their concrete code entities.
Diagram: Superpowers Component Map
Sources: .claude-plugin/plugin.json1-13 .cursor-plugin/plugin.json1-18 RELEASE-NOTES.md325-337
| Path | Contents |
|---|---|
skills/ | Skill library — one subdirectory per skill, each containing a SKILL.md file and optional supporting files |
agents/ | Agent definitions bundled with the plugin (currently code-reviewer.md) |
commands/ | Slash command definitions: brainstorm.md, write-plan.md, execute-plan.md |
hooks/ | Session hook configuration (hooks.json), polyglot wrapper (run-hook.cmd), and bootstrap script (session-start) |
lib/ | Shared JavaScript module: skills-core.js |
.claude-plugin/ | Claude Code plugin manifest (plugin.json) and marketplace descriptor (marketplace.json) |
.cursor-plugin/ | Cursor plugin manifest (plugin.json) |
.opencode/ | OpenCode JavaScript plugin (plugins/superpowers.js) and installation files |
.codex/ | Codex installation instructions and configuration |
tests/ | Test suites organized by platform and concern |
docs/ | Platform-specific documentation |
Sources: .cursor-plugin/plugin.json14-17 README.md133-141
Each platform has a different plugin API. The diagram below shows how the four supported platforms connect to shared components.
Diagram: Per-Platform Integration Points
Sources: .claude-plugin/plugin.json1-13 .cursor-plugin/plugin.json1-18 RELEASE-NOTES.md140-155 RELEASE-NOTES.md325-337
| Platform | Manifest file | Hook mechanism | Skills path | Bootstrap delivery |
|---|---|---|---|---|
| Claude Code | .claude-plugin/plugin.json | hooks/hooks.json SessionStart | skills/ (in repo) | hooks/session-start outputs JSON with hookSpecificOutput.additionalContext |
| Cursor | .cursor-plugin/plugin.json | hooks/hooks.json SessionStart | skills/ (in repo) | hooks/session-start outputs additional_context field |
| OpenCode | .opencode/plugins/superpowers.js | experimental.chat.system.transform | ~/.config/opencode/skills/superpowers/ symlink | getBootstrapContent() injects into system prompt |
| Codex | .codex/ (install only) | Native skill discovery | ~/.agents/skills/superpowers/ symlink | Skills read directly by Codex agent runtime |
Sources: RELEASE-NOTES.md7-10 RELEASE-NOTES.md137-165 RELEASE-NOTES.md54-59 RELEASE-NOTES.md140-143
lib/skills-core.js is a shared ES module used by both the OpenCode plugin and (historically) the Codex integration. It centralizes:
extractFrontmatter — parses YAML frontmatter from SKILL.md filesfindSkillsInDir — recursively scans a directory for SKILL.md filesresolveSkillPath — resolves a skill name to its file path using priority rulescheckForUpdates — checks the skills git repo for upstream updatesstripFrontmatter — removes the YAML block from skill content before deliveryThe OpenCode plugin (.opencode/plugins/superpowers.js) imports from this module. Codex previously used it too but now relies on native skill discovery, eliminating the runtime Node.js dependency.
Sources: RELEASE-NOTES.md335-336 RELEASE-NOTES.md54-59 RELEASE-NOTES.md155-156
When a skill name is requested, the system resolves it against three locations in priority order:
project-local > personal > superpowers (built-in)
| Tier | Claude Code path | OpenCode path | Notes |
|---|---|---|---|
| Project-local | ./.claude/skills/ | ./.opencode/skills/ | Per-project overrides |
| Personal | ~/.claude/skills/ | ~/.config/opencode/skills/ | User-specific skills |
| Superpowers | skills/ (repo) | ~/.config/opencode/skills/superpowers/ | Built-in library |
The superpowers: namespace prefix bypasses project and personal tiers, forcing resolution directly to the built-in library. This is used in skill cross-references (e.g., superpowers:brainstorming) to prevent accidental overriding of core workflow skills.
Sources: RELEASE-NOTES.md383-386 RELEASE-NOTES.md325-335
Diagram: Architectural Layers (bottom-up)
Sources: README.md1-15 .cursor-plugin/plugin.json14-17 RELEASE-NOTES.md325-337
Single-repo for skills and plugin. As of the current version, skills live alongside the plugin in the same repository (skills/). An earlier architecture (v2.0) separated them into obra/superpowers and obra/superpowers-skills; this was later consolidated. See Dual Repository Design for details on the historical split and its rationale.
Polyglot hook wrapper. Claude Code and Cursor hooks execute via hooks/run-hook.cmd, a single file that is valid both as a Windows CMD script and a Unix bash script. This eliminates the need for platform-specific hook files. See Session Lifecycle and Bootstrap for the bootstrap content format.
No runtime dependency for Codex. Codex integration uses the platform's native skill discovery (~/.agents/skills/) rather than a Node.js bootstrap CLI. Earlier versions required superpowers-codex as a runtime executable; this was removed in v4.2.0.
Tool mapping via bootstrap content. Skills reference Claude Code tools (TodoWrite, Task, Skill). For OpenCode, getBootstrapContent() injects a mapping table into the system prompt that translates these to OpenCode equivalents (update_plan, @mention, native skill tool). This keeps skill content platform-agnostic. See Tool Mapping Layer.
Sources: RELEASE-NOTES.md576-583 RELEASE-NOTES.md11-23 RELEASE-NOTES.md54-59 RELEASE-NOTES.md104-106
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.