SuperCharged-Claude-Code-Upgrade/skills/ralph/SUPERPOWERS_INTEGRATION.md

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

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

Configuration

Create ~/.claude/config/ralph.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

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

Individual Skill Invocation

# 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

# 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?

# Check skill status
/ralph --status

# Verify superpowers enabled
echo $RALPH_SUPERPOWERS_ENABLED

# Reinitialize Ralph
/ralph --reinit

Agents not available?

# List available agents
/ralph --list-agents

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

MCPs not working?

# 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