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 is designed as a multi-platform plugin that bridges a single skills library across various AI environments. It utilizes a shared skills/ directory and platform-specific entry points. As of v6.1.0, the architecture has shifted away from external hooks for platforms with native skill discovery (like Codex) to reduce UX friction.
Sources: .claude-plugin/plugin.json1-20 RELEASE-NOTES.md7-9 RELEASE-NOTES.md25-27 README.md36-186
The plugin uses multiple configuration files that interact to provide cross-platform functionality. Recent versions (v6.0.0+) have focused on vendor-neutral tool calls and optimized bootstrap payloads to lower per-session token costs.
Sources: RELEASE-NOTES.md18-22 RELEASE-NOTES.md7-8 .claude-plugin/plugin.json1-4 README.md186
The repository layout organizes platform-specific integrations and shared skill logic. Note that scratch files for Subagent-Driven Development (SDD) have moved from .git/ to .superpowers/ to avoid protection errors in Claude Code.
| Directory | Purpose | Key Files |
|---|---|---|
.claude-plugin/ | Claude Code plugin metadata and marketplace info | plugin.json, marketplace.json |
.codex-plugin/ | Codex-specific metadata for native skill discovery | plugin.json |
.superpowers/sdd/ | SDD scratch files (Task briefs, reports, progress ledger) | sdd-workspace helper |
hooks/ | Session lifecycle hooks and cross-platform wrappers | hooks.json, run-hook.cmd, session-start |
skills/ | The core library of AI workflows and task templates | using-superpowers/, brainstorming/, writing-plans/ |
tests/ | Test suites for skills and infrastructure | run-skill-tests.sh, test-helpers.sh |
scripts/ | Maintenance and packaging utilities | package-codex-plugin.sh, bump-version.sh |
For a full breakdown of the repository layout, see Directory Structure.
Sources: RELEASE-NOTES.md36-38 RELEASE-NOTES.md12 RELEASE-NOTES.md7-8 .claude-plugin/plugin.json1-20 README.md190-204
The plugin.json file provides essential metadata for marketplace integration. Superpowers follows semantic versioning. The readSuperpowersVersion() function provides a fallback to .codex-plugin/plugin.json when package.json is absent in packaged environments.
For details on configuration schemas, see Configuration Files. For the full evolution of the project, see Release History.
Sources: .claude-plugin/plugin.json1-20 RELEASE-NOTES.md3-4 RELEASE-NOTES.md48
The SessionStart hook remains the primary entry point for context injection on many platforms, though Codex now uses native discovery with an explicit hooks: {} to disable the auto-discovery fallback.
using-superpowers bootstrap.using-git-worktrees skill now defaults to local .worktrees/ within the project instead of a global configuration directory (RELEASE-NOTES.md62-63).For a deep dive into the hook lifecycle, see Hooks System.
Sources: RELEASE-NOTES.md7-8 RELEASE-NOTES.md18-22 RELEASE-NOTES.md62-63 README.md186
The plugin relies on environment variables for path resolution and platform-specific logic:
| Variable | Purpose |
|---|---|
CLAUDE_PLUGIN_ROOT | Root directory of the installed plugin in Claude Code. |
CURSOR_PLUGIN_ROOT | Root directory in Cursor; used for platform detection. |
SUPERPOWERS_SKILLS_ROOT | Path to the core skills library used for discovery. |
For a complete reference, see Environment Variables.
Sources: RELEASE-NOTES.md18-22 README.md180-184
~/.config/superpowers/worktrees/ is deprecated in favor of project-local .worktrees/ (RELEASE-NOTES.md62-63).spec-reviewer-prompt.md and code-quality-reviewer-prompt.md are replaced by a single task-reviewer-prompt.md (RELEASE-NOTES.md61).For migration paths and a list of legacy commands, see Deprecated Commands.
Sources: RELEASE-NOTES.md30-31 RELEASE-NOTES.md61-63
The project has evolved through several major architectural phases:
For the comprehensive log of changes, see Release History.
Refresh this wiki