This section provides low-level technical documentation for the Superpowers plugin infrastructure. It covers file system layout, configuration file formats, integration mechanisms, and version history. This material is intended for plugin developers, contributors implementing platform integrations, and users troubleshooting installation issues.
For information about the skills content and workflows, see Core Concepts. For platform-specific integration details, see Platform-Specific Features. For testing infrastructure, see Testing Infrastructure.
The Technical Reference documents the mechanical implementation of the Superpowers plugin system. This includes:
This page serves as a navigational overview. Individual subsections provide detailed specifications for each component.
The Superpowers system consists of two separate repositories with distinct responsibilities:
| Repository | Purpose | Location |
|---|---|---|
obra/superpowers | Plugin integration code, hooks, commands, platform-specific adapters | This repository |
obra/superpowers-skills | Skill content (markdown files), supporting scripts, examples | Cloned to local filesystem |
Sources: .claude-plugin/plugin.json1-14 .claude-plugin/marketplace.json1-21 RELEASE-NOTES.md discussion of dual repository design (v2.0.0), architecture diagrams showing repository separation
The plugin uses multiple configuration files that interact to provide cross-platform functionality:
Sources: RELEASE-NOTES.md25-27 (SessionStart hook sync), RELEASE-NOTES.md42-46 (Windows hook execution), architecture diagrams showing session lifecycle
The plugin repository uses a well-defined directory structure to organize different technical concerns:
| Directory | Purpose | Key Files | Platform |
|---|---|---|---|
.claude-plugin/ | Claude Code plugin metadata | plugin.json, marketplace.json | Claude Code |
.opencode/plugins/ | OpenCode integration code | superpowers.js | OpenCode |
.codex/ | Codex CLI integration | superpowers-codex | Codex |
hooks/ | Session lifecycle hooks | hooks.json, session-start.sh | Claude Code |
commands/ | User-facing slash commands | brainstorm.md, write-plan.md, execute-plan.md | Claude Code |
agents/ | Agent definitions | code-reviewer.md | All platforms |
lib/ | Shared utility code | skills-core.js, initialize-skills.sh | All platforms |
tests/ | Test suites | claude-code/, opencode/, subagent-driven-dev/ | Development |
Sources: RELEASE-NOTES.md690-707 (File changes v2.0.0), architecture diagrams showing repository structure
The plugin.json file provides essential metadata for Claude Code marketplace integration:
Superpowers follows semantic versioning with the following conventions:
| Version Type | Example | Meaning |
|---|---|---|
| Major | 4.0.0 | Breaking changes (workflow changes, skill consolidation) |
| Minor | 4.1.0 | New features (new skills, platform support) |
| Patch | 4.1.1 | Bug fixes, documentation updates |
The plugin version (.claude-plugin/plugin.json4) tracks the integration code. The skills repository versions independently with its own git history.
Sources: .claude-plugin/plugin.json1-14 RELEASE-NOTES.md1-3 (version headers)
The plugin provides three slash commands registered in Claude Code:
| Command | Source File | Invokes Skill | Flag |
|---|---|---|---|
/brainstorm | commands/brainstorm.md | superpowers:brainstorming | disable-model-invocation: true |
/write-plan | commands/write-plan.md | superpowers:writing-plans | disable-model-invocation: true |
/execute-plan | commands/execute-plan.md | superpowers:executing-plans | disable-model-invocation: true |
The disable-model-invocation: true flag (RELEASE-NOTES.md167-169) prevents Claude from invoking these commands autonomously. Users must invoke them manually. Claude can still invoke the underlying skills directly.
Sources: RELEASE-NOTES.md167-172 (slash commands user-only), architecture diagrams showing command flow
Agent definitions live in the agents/ directory as markdown files with YAML frontmatter:
The code-reviewer agent (agents/code-reviewer.md1-49) is included with the plugin and namespaced as superpowers:code-reviewer. Skills reference it in their workflows for automated code review.
Sources: agents/code-reviewer.md1-49 RELEASE-NOTES.md424-435 (code reviewer agent addition)
The plugin uses environment variables to locate resources across platforms:
| Variable | Purpose | Typical Value | Set By |
|---|---|---|---|
SUPERPOWERS_SKILLS_ROOT | Skills repository location | ~/.config/superpowers/skills | session-start.sh |
CLAUDE_PLUGIN_ROOT | Plugin installation directory | ~/.claude/plugins/superpowers | Claude Code |
OPENCODE_CONFIG_DIR | OpenCode config directory | ~/.config/opencode | OpenCode |
These variables enable path-independent references in scripts and allow platform-specific overrides.
Sources: RELEASE-NOTES.md663-665 (environment variables section)
The repository excludes certain directories from version control:
.worktrees/
.private-journal/
.claude/
.worktrees/ - Created by using-git-worktrees skill for isolated development branches.private-journal/ - User's private notes and experiments.claude/ - Local Claude Code cache and temporary filesSources: .gitignore1-4
The plugin has evolved through multiple major versions:
| Version | Date | Key Changes |
|---|---|---|
| v4.3.0 | 2026-02-12 | Brainstorming enforcement with hard gates, synchronous SessionStart hook |
| v4.2.0 | 2026-02-05 | Codex native skill discovery (removed bootstrap CLI), Windows fixes |
| v4.1.0 | 2026-01-23 | OpenCode native skills system, agent reset fix |
| v4.0.0 | 2025-12-17 | Two-stage code review, DOT flowcharts, skill consolidation |
| v3.0.0 | 2025-10-16 | First-party Anthropic skills system integration |
| v2.0.0 | 2025-10-12 | Skills repository separation (obra/superpowers-skills) |
See Release Notes for complete version history with detailed changes.
Sources: RELEASE-NOTES.md1-781 (complete release history)
Sources: RELEASE-NOTES.md33-38 (Codex native discovery), RELEASE-NOTES.md119-129 (OpenCode native skills), architecture diagrams showing multi-platform integration
Understanding breaking changes helps when upgrading or troubleshooting:
superpowers-codex bootstrap pattern replaced with native skill discovery via ~/.agents/skills/superpowers/ symlink (RELEASE-NOTES.md31-38)~/.codex/skills/ path deprecated - Use ~/.agents/skills/ insteadobra/superpowers-skills (RELEASE-NOTES.md565-575)Sources: RELEASE-NOTES.md31-32 RELEASE-NOTES.md248 RELEASE-NOTES.md265 RELEASE-NOTES.md471 RELEASE-NOTES.md564
For detailed specifications of individual components:
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.