237b307262
## Ralph Skill - Complete Python Implementation - __main__.py: Main entry point for Ralph autonomous agent - agent_capability_registry.py: Agent capability registry (FIXED syntax error) - dynamic_agent_selector.py: Dynamic agent selection logic - meta_agent_orchestrator.py: Meta-orchestration for multi-agent workflows - worker_agent.py: Worker agent implementation - ralph_agent_integration.py: Integration with Claude Code - superpowers_integration.py: Superpowers framework integration - observability_dashboard.html: Real-time observability UI - observability_server.py: Dashboard server - multi-agent-architecture.md: Architecture documentation - SUPERPOWERS_INTEGRATION.md: Integration guide ## Framework Integration Status - ✅ codebase-indexer (Chippery): Complete implementation with 5 scripts - ✅ ralph (Ralph Orchestrator): Complete Python implementation - ✅ always-use-superpowers: Declarative skill (SKILL.md) - ✅ auto-superpowers: Declarative skill (SKILL.md) - ✅ auto-dispatcher: Declarative skill (Ralph framework) - ✅ autonomous-planning: Declarative skill (Ralph framework) - ✅ mcp-client: Declarative skill (AGIAgent/Agno framework) ## Agent Updates - Updated README.md with latest integration status - Added framework integration agents Token Savings: ~99% via semantic codebase indexing 🤖 Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>
329 lines
9.3 KiB
Markdown
329 lines
9.3 KiB
Markdown
# 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
|