> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/obra/superpowers/llms.txt
> Use this file to discover all available pages before exploring further.

# System Architecture

> Understanding how Superpowers components work together

# System Architecture

Superpowers is a modular system built around composable skills, hooks, plugins, commands, and agents that work together to provide a complete development workflow.

## Core Components

<CardGroup cols={2}>
  <Card title="Skills" icon="wand-magic-sparkles">
    Reusable workflow modules that guide agents through specific tasks like TDD, debugging, and brainstorming.
  </Card>

  <Card title="Hooks" icon="link">
    Lifecycle event handlers that inject context at specific points, like session start.
  </Card>

  <Card title="Plugins" icon="puzzle-piece">
    Platform-specific packages that register Superpowers with different AI coding tools.
  </Card>

  <Card title="Commands" icon="terminal">
    Slash commands that invoke skills directly (e.g., `/brainstorm`).
  </Card>

  <Card title="Agents" icon="robot">
    Specialized subagents for specific tasks like code review.
  </Card>

  <Card title="Skills Core" icon="gear">
    Core library for skill discovery, resolution, and loading.
  </Card>
</CardGroup>

## How Components Fit Together

```mermaid theme={null}
graph TD
    A[Platform: Claude Code/Cursor/OpenCode] --> B[Plugin]
    B --> C[Hooks System]
    B --> D[Skills Discovery]
    B --> E[Commands Registration]
    B --> F[Agents Registration]
    
    C --> G[SessionStart Hook]
    G --> H[Context Injection]
    
    D --> I[Skills Core Library]
    I --> J[Personal Skills]
    I --> K[Superpowers Skills]
    I --> L[Project Skills]
    
    E --> M[/brainstorm Command]
    E --> N[/write-plan Command]
    E --> O[/execute-plan Command]
    
    F --> P[code-reviewer Agent]
    
    H --> Q[Active Session]
    J --> Q
    K --> Q
    L --> Q
    M --> Q
    N --> Q
    O --> Q
    P --> Q
```

## Directory Structure

Superpowers follows a consistent structure across all platforms:

```
superpowers/
├── .claude-plugin/           # Claude Code plugin manifest
│   ├── plugin.json          # Package metadata + paths
│   └── marketplace.json     # Marketplace configuration
├── .cursor-plugin/           # Cursor plugin manifest
│   └── plugin.json          # Package metadata + paths
├── .codex/                   # Codex installation instructions
│   └── INSTALL.md
├── .opencode/                # OpenCode plugin + instructions
│   ├── INSTALL.md
│   └── plugins/
│       └── superpowers.js   # OpenCode plugin implementation
├── skills/                   # Skills library
│   ├── brainstorming/
│   │   └── SKILL.md         # Skill definition with frontmatter
│   ├── test-driven-development/
│   ├── systematic-debugging/
│   └── .../
├── hooks/                    # Hooks configuration + scripts
│   ├── hooks.json           # Hook definitions
│   ├── run-hook.cmd         # Cross-platform wrapper
│   └── session-start        # SessionStart hook script
├── commands/                 # Slash commands
│   ├── brainstorm.md        # /brainstorm command
│   ├── write-plan.md        # /write-plan command
│   └── execute-plan.md      # /execute-plan command
├── agents/                   # Specialized subagents
│   └── code-reviewer.md     # Code review agent
├── lib/                      # Core libraries
│   └── skills-core.js       # Skills discovery & resolution
└── docs/                     # Documentation
    ├── README.codex.md
    ├── README.opencode.md
    └── plans/
```

## Skills System

### Skill Discovery

The skills system uses **`lib/skills-core.js`** to discover and resolve skills from multiple sources:

<Steps>
  <Step title="Find SKILL.md Files">
    Recursively searches configured directories for `SKILL.md` files (up to 3 levels deep):

    ```javascript theme={null}
    // From lib/skills-core.js:62
    function findSkillsInDir(dir, sourceType, maxDepth = 3) {
      const skills = [];
      // Recursively finds all SKILL.md files
      // Extracts frontmatter (name, description)
      // Returns array of skill metadata
    }
    ```
  </Step>

  <Step title="Extract Frontmatter">
    Each skill has YAML frontmatter with metadata:

    ```markdown theme={null}
    ---
    name: brainstorming
    description: Use when creating features - explores requirements before implementation
    ---

    # Brainstorming Ideas Into Designs
    [skill content...]
    ```

    The `extractFrontmatter()` function parses this to get the skill's name and description.
  </Step>

  <Step title="Skill Resolution with Shadowing">
    Skills are resolved with priority order (personal > superpowers):

    ```javascript theme={null}
    // From lib/skills-core.js:108
    function resolveSkillPath(skillName, superpowersDir, personalDir) {
      // 1. Try personal skills first (unless superpowers: prefix)
      // 2. Fall back to superpowers skills
      // 3. Return skill file path + metadata
    }
    ```

    This allows users to **override** superpowers skills with their own versions.
  </Step>
</Steps>

### Skill Invocation Flow

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Agent
    participant SkillTool
    participant SkillsCore
    participant Filesystem
    
    User->>Agent: "Let's build a new feature"
    Agent->>Agent: Check using-superpowers skill
    Note over Agent: Recognizes: needs brainstorming
    Agent->>SkillTool: Invoke skill tool: "brainstorming"
    SkillTool->>SkillsCore: resolveSkillPath("brainstorming")
    SkillsCore->>Filesystem: Check ~/.config/opencode/skills/brainstorming
    Filesystem-->>SkillsCore: Not found
    SkillsCore->>Filesystem: Check superpowers/skills/brainstorming
    Filesystem-->>SkillsCore: Found SKILL.md
    SkillsCore-->>SkillTool: Return path + metadata
    SkillTool->>Filesystem: Read SKILL.md
    Filesystem-->>SkillTool: Return content
    SkillTool->>SkillsCore: stripFrontmatter(content)
    SkillsCore-->>SkillTool: Return clean content
    SkillTool-->>Agent: Inject skill content into context
    Agent->>User: "I'm using brainstorming skill to..."
```

## Plugin Architecture

### Platform Differences

<Accordion title="Claude Code & Cursor (Marketplace)">
  These platforms have built-in plugin marketplaces and automatic installation:

  * **Registration**: Via plugin marketplace commands
  * **Distribution**: Git repository URLs
  * **Updates**: Automatic via `/plugin update`
  * **Hooks**: Automatically registered from `hooks.json`
  * **Skills**: Automatically discovered from `skills/` directory
</Accordion>

<Accordion title="OpenCode (Manual + Plugin)">
  OpenCode uses a hybrid approach with manual setup + plugin code:

  * **Registration**: Manual symlink to `~/.config/opencode/plugins/superpowers.js`
  * **Distribution**: Manual git clone
  * **Updates**: Manual `git pull`
  * **Skills**: Manual symlink to `~/.config/opencode/skills/superpowers`
  * **Bootstrap**: Plugin injects context via system prompt transform

  See [Plugin System](/development/plugin-system) for implementation details.
</Accordion>

<Accordion title="Codex (Manual Symlink)">
  Codex uses native skill discovery without plugins:

  * **Registration**: Symlink to `~/.agents/skills/superpowers`
  * **Distribution**: Manual git clone
  * **Updates**: Manual `git pull`
  * **Skills**: Discovered automatically via symlink
  * **No hooks**: Codex doesn't support hooks system
</Accordion>

## Commands System

Commands are simple wrappers that invoke skills directly:

```markdown theme={null}
---
description: "Use before creative work - explores requirements and design"
disable-model-invocation: true
---

Invoke the superpowers:brainstorming skill and follow it exactly
```

Commands provide:

* **Convenience**: `/brainstorm` instead of manually invoking skill tool
* **Discoverability**: Listed in platform command menus
* **Consistency**: Same interface across platforms

## Agents System

Agents are specialized subagents with specific roles:

```markdown theme={null}
---
name: code-reviewer
description: Reviews completed work against plan and coding standards
model: inherit
---

# Agent instructions...
```

Key features:

* **Isolated context**: Fresh agent per invocation
* **Specialized knowledge**: Role-specific instructions
* **Model inheritance**: Uses same model as parent
* **Structured output**: Consistent review format

## Hook System Integration

Hooks integrate with platform lifecycle events. See [Hooks System](/development/hooks-system) for details.

## Key Design Principles

<Note>
  **Modularity**: Each component (skill, hook, command, agent) is independent and composable.
</Note>

<Note>
  **Platform Abstraction**: Core skills work across all platforms; only installation differs.
</Note>

<Note>
  **User Override**: Personal skills always shadow superpowers skills, enabling customization.
</Note>

<Note>
  **Automatic Triggering**: Skills activate based on context, not explicit invocation.
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="Hooks System" icon="link" href="/development/hooks-system">
    Learn how hooks inject context at session start
  </Card>

  <Card title="Plugin System" icon="puzzle-piece" href="/development/plugin-system">
    Understand plugin manifests and distribution
  </Card>

  <Card title="Creating Skills" icon="wand-magic-sparkles" href="/guides/creating-skills">
    Write your own custom skills
  </Card>

  <Card title="Contributing" icon="code-pull-request" href="/contributing">
    Contribute to Superpowers
  </Card>
</CardGroup>