# Ralph Superpowers Integration

Complete integration of oh-my-opencode and superpowers features into Ralph for Claude Code CLI.

## Integrated Features

### From oh-my-opencode:

**Agents (10 total):**
- **Sisyphus** - Primary orchestrator (Claude Opus 4.5)
- **Atlas** - Master orchestrator
- **Oracle** - Consultation, debugging (GPT 5.2)
- **Librarian** - Docs, GitHub search
- **Explore** - Fast codebase grep
- **Multimodal-Looker** - PDF/image analysis (Gemini 3 Flash)
- **Prometheus** - Strategic planning

**Lifecycle Hooks (31 total):**
- agent-usage-reminder
- anthropic-context-window-limit-recovery
- atlas (main orchestrator)
- auto-slash-command
- auto-update-checker
- background-notification
- claude-code-hooks
- comment-checker
- compaction-context-injector
- delegate-task-retry
- directory-agents-injector
- directory-readme-injector
- edit-error-recovery
- empty-task-response-detector
- interactive-bash-session
- keyword-detector
- non-interactive-env
- prometheus-md-only
- question-label-truncator
- ralph-loop
- rules-injector
- session-recovery
- sisyphus-junior-notepad
- start-work
- task-resume-info
- think-mode
- thinking-block-validator
- todo-continuation-enforcer
- tool-output-truncator

**Built-in MCPs:**
- websearch (Exa)
- context7 (docs)
- grep_app (GitHub)

**Tools (20+):**
- LSP support
- AST-Grep
- Delegation system
- Background task management

### From superpowers:

**Skills (14 total):**
- brainstorming - Interactive design refinement
- writing-plans - Detailed implementation plans
- executing-plans - Batch execution with checkpoints
- subagent-driven-development - Fast iteration with two-stage review
- test-driven-development - RED-GREEN-REFACTOR cycle
- systematic-debugging - 4-phase root cause process
- verification-before-completion - Ensure it's actually fixed
- requesting-code-review - Pre-review checklist
- receiving-code-review - Responding to feedback
- using-git-worktrees - Parallel development branches
- finishing-a-development-branch - Merge/PR decision workflow
- dispatching-parallel-agents - Concurrent subagent workflows
- using-superpowers - Introduction to the skills system
- writing-skills - Create new skills

**Commands (3):**
- /superpowers:brainstorm - Interactive design refinement
- /superpowers:write-plan - Create implementation plan
- /superpowers:execute-plan - Execute plan in batches

**Agents (1):**
- code-reviewer - Code review specialist

## Installation

### For Claude Code CLI

```bash
# Install Ralph with all superpowers
cd ~/.claude/skills
git clone https://github.com/YOUR-USERNAME/ralph-superpowers.git
```

### Configuration

Create `~/.claude/config/ralph.json`:

```json
{
  "superpowers": {
    "enabled": true,
    "skills": {
      "brainstorming": true,
      "writing-plans": true,
      "executing-plans": true,
      "subagent-driven-development": true,
      "test-driven-development": true,
      "systematic-debugging": true,
      "verification-before-completion": true,
      "requesting-code-review": true,
      "receiving-code-review": true,
      "using-git-worktrees": true,
      "finishing-a-development-branch": true,
      "dispatching-parallel-agents": true
    },
    "hooks": {
      "atlas": true,
      "claude-code-hooks": true,
      "ralph-loop": true,
      "todo-continuation-enforcer": true
    },
    "agents": {
      "sisyphus": true,
      "oracle": true,
      "librarian": true,
      "explore": true,
      "prometheus": true
    },
    "mcps": {
      "websearch": true,
      "context7": true,
      "grep_app": true
    }
  }
}
```

## Usage

### Basic Workflow

```
1. /ralph "Build a new feature"
   → Ralph invokes brainstorming skill
   → Refines requirements through questions
   → Presents design in sections

2. User approves design
   → Ralph invokes writing-plans skill
   → Creates detailed implementation plan
   → Breaks into 2-5 minute tasks

3. User approves plan
   → Ralph invokes subagent-driven-development
   → Executes tasks with two-stage review
   → Continues until complete

4. Throughout process
   → test-driven-development enforces TDD
   → systematic-debugging handles issues
   → requesting-code-review between tasks
```

### With Multi-Agent Mode

```bash
RALPH_MULTI_AGENT=true \
RALPH_SUPERPOWERS_ENABLED=true \
/ralph "Complex task with multiple components"
```

### Individual Skill Invocation

```bash
# Brainstorm design
/ralph:brainstorm "I want to add user authentication"

# Create plan
/ralph:write-plan

# Execute plan
/ralph:execute-plan

# Debug systematically
/ralph:debug "The login isn't working"

# Code review
/ralph:review
```

## Environment Variables

```bash
# Superpowers
RALPH_SUPERPOWERS_ENABLED=true           # Enable all superpowers
RALPH_BRAINSTORMING_ENABLED=true          # Enable brainstorming
RALPH_TDD_ENABLED=true                    # Enable test-driven development
RALPH_SYSTEMATIC_DEBUGGING=true           # Enable systematic debugging

# Hooks
RALPH_HOOK_ATLAS=true                     # Enable Atlas orchestrator
RALPH_HOOK_CLAUDE_CODE_HOOKS=true         # Enable Claude Code hooks
RALPH_HOOK_RALPH_LOOP=true                # Enable Ralph Loop
RALPH_HOOK_TODO_ENFORCER=true             # Enable todo continuation

# Agents
RALPH_AGENT_SISYPHUS=true                 # Enable Sisyphus
RALPH_AGENT_ORACLE=true                   # Enable Oracle
RALPH_AGENT_LIBRARIAN=true                 # Enable Librarian

# MCPs
RALPH_MCP_WEBSEARCH=true                  # Enable web search MCP
RALPH_MCP_CONTEXT7=true                   # Enable context7 MCP
RALPH_MCP_GREP_APP=true                   # Enable GitHub grep MCP
```

## Architecture

```
┌─────────────────────────────────────────────┐
│                  Ralph Core                  │
│         (Orchestration & Selection)          │
└──────────────────┬──────────────────────────┘
                   │
     ┌─────────────┼─────────────┬─────────────┐
     │             │             │             │
┌────▼────┐  ┌────▼────┐  ┌────▼────┐  ┌────▼────┐
│ Skills  │  │  Hooks  │  │ Agents  │  │  MCPs   │
└─────────┘  └─────────┘  └─────────┘  └─────────┘

Skills:
  • brainstorming          → /ralph:brainstorm
  • writing-plans          → /ralph:write-plan
  • executing-plans        → /ralph:execute-plan
  • subagent-driven-dev    → Auto-invoked
  • test-driven-development → Auto-invoked
  • systematic-debugging   → /ralph:debug
  • verification           → Auto-invoked
  • code-review            → /ralph:review

Hooks:
  • atlas (orchestrator)   → Manages multi-agent workflows
  • claude-code-hooks       → Claude Code compatibility
  • ralph-loop              → Autonomous iteration
  • todo-enforcer          → Ensures task completion

Agents:
  • sisyphus                → Primary orchestrator
  • oracle                  → Debugging consultant
  • librarian               → Docs & codebase search
  • explore                 → Fast grep
  • prometheus              → Strategic planning

MCPs:
  • websearch (Exa)         → Web search
  • context7                → Documentation search
  • grep_app                → GitHub code search
```

## File Structure

```
~/.claude/
├── skills/
│   └── ralph/
│       ├── SKILL.md                    # Main skill file
│       ├── superpowers/
│       │   ├── integration.py         # Superpowers integration
│       │   ├── skills/                # Imported skills
│       │   ├── hooks/                 # Imported hooks
│       │   ├── agents/                # Imported agents
│       │   └── mcps/                  # Imported MCPs
│       ├── contains-studio/
│       │   ├── agents/                # Contains-studio agents
│       │   └── integration.py         # Agent integration
│       └── multi-agent/
│           ├── orchestrator.py        # Meta-agent
│           ├── worker.py              # Worker agents
│           └── observability/          # Monitoring
├── commands/
│   └── ralph.md                       # /ralph command
└── config/
    └── ralph.json                     # Configuration
```

## Troubleshooting

**Skills not triggering?**
```bash
# Check skill status
/ralph --status

# Verify superpowers enabled
echo $RALPH_SUPERPOWERS_ENABLED

# Reinitialize Ralph
/ralph --reinit
```

**Agents not available?**
```bash
# List available agents
/ralph --list-agents

# Check agent configuration
cat ~/.claude/config/ralph.json | jq '.agents'
```

**MCPs not working?**
```bash
# Check MCP status
/ralph --mcp-status

# Test MCP connection
/ralph --test-mcp websearch
```

## License

MIT License - see LICENSE for details.

## Credits

- **oh-my-opencode**: https://github.com/code-yeongyu/oh-my-opencode
- **superpowers**: https://github.com/obra/superpowers
- **contains-studio/agents**: https://github.com/contains-studio/agents
