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 uses a unified repository architecture to consolidate platform shims and the skills library into a single codebase, simplifying installation and versioning.
The system consists of:
.claude-plugin/plugin.json, hooks/hooks.json, and .codex-plugin/plugin.json that register Superpowers with various AI environments. [.claude-plugin/plugin.json1-20] [RELEASE-NOTES.md47-48]hooks/ (e.g., hooks/session-start) that inject bootstrap context and the using-superpowers meta-skill at the start of every session. [RELEASE-NOTES.md7-8] [RELEASE-NOTES.md18-20]skills/ that define workflows like brainstorming, writing-plans, and subagent-driven-development. [README.md189-202] [.claude-plugin/plugin.json3-4]The central design goal is that agents automatically discover and invoke skills. By providing a using-superpowers skill as the entry point, the agent is instructed to check the skills/ directory before performing any task.
Sources: .claude-plugin/plugin.json1-20 RELEASE-NOTES.md18-22 README.md189-202
Diagram: Repository Structure and Platform Entry Points
Sources: .claude-plugin/plugin.json1-20 RELEASE-NOTES.md10-12 RELEASE-NOTES.md25-26 RELEASE-NOTES.md36-37
Each platform has a different plugin API. Superpowers abstracts these differences so core skills remain portable. Recent updates focus on native skill discovery where possible (e.g., Codex and Pi).
Diagram: Platform Integration Points and Code Entities
Sources: RELEASE-NOTES.md7-8 RELEASE-NOTES.md68-71 README.md185-187 RELEASE-NOTES.md25-26
| Platform | Entry point | Hook mechanism | Bootstrap delivery | Special requirements |
|---|---|---|---|---|
| Claude Code | .claude-plugin/plugin.json | SessionStart Hook | hooks/session-start | Official marketplace support [README.md38-45] |
| Codex | .codex-plugin/plugin.json | Native Discovery | Manifest hooks: {} | Avoids auto-discovery fallback [RELEASE-NOTES.md7-8] |
| Pi | pi install | Session Extension | using-superpowers | Injected after compaction [README.md185-187] |
| Antigravity | agy plugin install | SessionStart Hook | First message bootstrap | Verified via React Todo test [RELEASE-NOTES.md70-71] |
| Kimi Code | /plugins install | Manifest | Plugin Marketplace | Manifest-based registration [README.md151-155] |
using-superpowers BootstrapThe using-superpowers skill is injected into every session. In v6.1.0, this bootstrap was compressed to lower per-session token costs, replacing complex diagrams with prose while maintaining the "Red Flags" rationalization and user-instruction precedence. [RELEASE-NOTES.md18-20]
Subagent-Driven Development (SDD) uses a self-ignoring .superpowers/sdd/ directory in the working tree for scratch files (task briefs, reports, progress ledgers). This architecture avoids protected paths like .git/ which are denied by some harnesses like Claude Code. [RELEASE-NOTES.md36-37]
Codex integrations use a deterministic "portal" package created by package-codex-plugin.sh. This script normalizes timestamps and verifies that every skill includes required OpenAI metadata, ensuring consistent behavior across marketplace and manual installs. [RELEASE-NOTES.md10-12]
The review architecture has been streamlined from two reviewers (spec and quality) into a single task-reviewer-prompt.md. This change makes the review process cheaper and stricter by reducing model-choice overhead. [RELEASE-NOTES.md53-55 RELEASE-NOTES.md61-62]
Unified Repository. Consolidation ensures platform manifests and skill logic never drift. The repository serves as the source of truth for all supported harnesses. [README.md32-34]
Harness-Agnostic Skills. Skills are written in markdown to be vendor-neutral. Platform-specific nuances are handled by the tool-mapping layer and harness-specific references rather than modifying core skill logic. [RELEASE-NOTES.md21-22 RELEASE-NOTES.md57-58]
Local Worktree Isolation. The system enforces the use of git worktrees for development to ensure a clean baseline and prevent uncommitted changes from polluting the agent's context. [README.md192-193]
Strict Contributor Protocol. To maintain architectural integrity, the repo enforces a 94% PR rejection rate, requiring human review of all diffs and session transcripts for new harness integrations. [CLAUDE.md7-12 CLAUDE.md72-74]
Sources: RELEASE-NOTES.md10-62 README.md32-193 CLAUDE.md7-74
Refresh this wiki