Add Ralph Orchestrator dependency documentation and improved installation
Added comprehensive Ralph Orchestrator integration documentation:
1. requirements.txt
- ralph-orchestrator (core dependency for /ralph command)
- pyyaml (for config parsing)
- Comments explaining each dependency
2. Updated supercharge.sh
- Enhanced Ralph installation with dual detection:
* Checks for 'ralph' command in PATH
* Checks for ralph_orchestrator Python package
- Installs from requirements.txt if available
- Falls back to direct pip install
- Provides helpful error messages with installation instructions
- Confirms successful installation with detailed status
3. Updated README.md with new section "Ralph Orchestrator"
- What is Ralph Orchestrator and how it works
- Installation methods (automatic, manual, system-wide)
- Detailed breakdown of our Ralph integration:
* bin/ralphloop wrapper script (6,290 bytes, 223 lines)
* skills/ralph/ Claude Code skill
* skills/brainstorming/ multi-AI integration
* hooks/ralph-auto-trigger.sh automatic triggering
* hooks/qwen-consult.sh Qwen AI consultation
- File structure created by Ralph
- Environment variables reference
- Troubleshooting guide
- Ralph Orchestrator source links
The /ralph command will now work properly on:
- This machine (ralph already installed)
- Fresh clones (supercharge.sh auto-installs ralph-orchestrator)
- Any machine with pip3 available
Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
uroma
175
README.md
175
README.md
@@ -605,6 +605,181 @@ This skill provides...
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Ralph Orchestrator - Autonomous "Tackle Until Solved" Agent
|
||||
|
||||
### What is Ralph Orchestrator?
|
||||
|
||||
**Ralph Orchestrator** is a Python package that enables autonomous agent looping - the "Tackle Until Solved" capability that powers the `/ralph` command in this package.
|
||||
|
||||
### How Ralph Works
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ Ralph Orchestrator │
|
||||
│ "Tackle Until Solved" │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ 1. Analyze Task ──────> 2. Generate Approach │
|
||||
│ │ │ │
|
||||
│ ▼ ▼ │
|
||||
│ 3. Execute Step ──────> 4. Validate Result │
|
||||
│ │ │ │
|
||||
│ │ Complete? ────────No──┤ │
|
||||
│ │ │ │
|
||||
│ │ Yes ▼ │
|
||||
│ └────────────────> 5. Output Solution │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Ralph Dependency
|
||||
|
||||
| Component | Status | Notes |
|
||||
|-----------|--------|-------|
|
||||
| **Python Package** | Required | `ralph-orchestrator` |
|
||||
| **System Command** | Optional | `ralph` CLI (if installed) |
|
||||
| **Fallback Mode** | Available | Creates project files without running loop |
|
||||
|
||||
### Installation Methods
|
||||
|
||||
**Option 1: Automatic (via supercharge.sh)**
|
||||
```bash
|
||||
./supercharge.sh
|
||||
# Automatically installs ralph-orchestrator via pip3
|
||||
```
|
||||
|
||||
**Option 2: Manual Installation**
|
||||
```bash
|
||||
# Install Python package
|
||||
pip3 install ralph-orchestrator
|
||||
|
||||
# OR install from requirements.txt in this repo
|
||||
pip3 install -r requirements.txt
|
||||
```
|
||||
|
||||
**Option 3: System-Wide Installation**
|
||||
```bash
|
||||
# Install for all users
|
||||
sudo pip3 install ralph-orchestrator
|
||||
|
||||
# This creates the 'ralph' command system-wide
|
||||
```
|
||||
|
||||
### How We Built the Ralph Integration
|
||||
|
||||
Our Ralph integration consists of several components working together:
|
||||
|
||||
#### 1. **bin/ralphloop** - Python Wrapper Script
|
||||
- **Size**: 6,290 bytes (223 lines)
|
||||
- **Purpose**: Standalone wrapper for Ralph Orchestrator
|
||||
- **Features**:
|
||||
- Creates `.ralph/` project structure
|
||||
- Generates `PROMPT.md` with task description
|
||||
- Creates `ralph.yml` configuration
|
||||
- Streams Ralph output in real-time
|
||||
- Handles interrupts gracefully (Ctrl+C)
|
||||
|
||||
```python
|
||||
# Key components:
|
||||
- check_dependencies() # Verifies ralph installation
|
||||
- create_ralph_project() # Creates .ralph/ directory
|
||||
- run_ralph_loop() # Executes autonomous iteration
|
||||
```
|
||||
|
||||
#### 2. **skills/ralph/** - Claude Code Skill
|
||||
- **Purpose**: Integrates Ralph with Claude Code's `/ralph` command
|
||||
- **Trigger**: User types `/ralph "task description"`
|
||||
- **Flow**:
|
||||
1. Receives task from user
|
||||
2. Sets `RALPH_AUTO=true` environment variable
|
||||
3. Delegates to `brainstorming` skill with Ralph mode
|
||||
4. Ralph runs autonomous iterations until complete
|
||||
|
||||
#### 3. **skills/brainstorming/** - Multi-AI Brainstorming
|
||||
- **Purpose**: Creative thinking with Ralph integration
|
||||
- **Modes**:
|
||||
- **Direct Mode**: Quick ideation (simple tasks)
|
||||
- **Ralph Mode**: Autonomous iteration (complex tasks)
|
||||
- **Auto-Trigger**: Task complexity automatically determines mode
|
||||
|
||||
#### 4. **hooks/ralph-auto-trigger.sh** - Automatic Triggering
|
||||
- **Purpose**: Auto-starts Ralph for complex tasks
|
||||
- **Triggers**: Agent requests, development keywords
|
||||
- **Modes**:
|
||||
- `RALPH_AUTO_MODE=always` - Every request
|
||||
- `RALPH_AUTO_MODE=agents` - Agent/dev tasks only (default)
|
||||
- `RALPH_AUTO_MODE=off` - Disabled
|
||||
|
||||
#### 5. **hooks/qwen-consult.sh** - Qwen AI Integration
|
||||
- **Purpose**: Multi-AI consultation with Qwen
|
||||
- **Modes**:
|
||||
- `QWEN_CONSULT_MODE=always` - Every request
|
||||
- `QWEN_CONSULT_MODE=delegate` - Keyword-triggered (default)
|
||||
- `QWEN_CONSULT_MODE=off` - Disabled
|
||||
|
||||
### File Structure Created by Ralph
|
||||
|
||||
```
|
||||
.ralph/
|
||||
├── PROMPT.md # Task description with success criteria
|
||||
├── ralph.yml # Configuration (agent, max_iterations, etc.)
|
||||
├── state.json # Progress tracking
|
||||
└── iterations/
|
||||
├── 001.md # First iteration output
|
||||
├── 002.md # Second iteration output
|
||||
├── ...
|
||||
└── final.md # Validated final result
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `RALPH_AGENT` | `claude` | AI agent to use (claude, gemini, kiro, q, auto) |
|
||||
| `RALPH_MAX_ITERATIONS` | `100` | Maximum iterations before giving up |
|
||||
| `RALPH_MAX_RUNTIME` | `14400` | Maximum runtime in seconds (4 hours) |
|
||||
| `RALPH_AUTO_MODE` | `agents` | Auto-trigger mode (always, agents, off) |
|
||||
| `QWEN_CONSULT_MODE` | `delegate` | Qwen consultation mode |
|
||||
| `AUTO_SUPERPOWERS` | `true` | Auto-inject superpowers context |
|
||||
|
||||
### Troubleshooting Ralph
|
||||
|
||||
**Ralph command not found:**
|
||||
```bash
|
||||
# Check if Python package is installed
|
||||
python3 -c "import ralph_orchestrator; print('OK')"
|
||||
|
||||
# If not, install it
|
||||
pip3 install ralph-orchestrator
|
||||
```
|
||||
|
||||
**Ralph won't start:**
|
||||
```bash
|
||||
# Check ralphloop is executable
|
||||
ls -la ~/.claude/skills/bin/ralphloop
|
||||
chmod +x ~/.claude/skills/bin/ralphloop
|
||||
|
||||
# Check Python 3 is available
|
||||
python3 --version
|
||||
```
|
||||
|
||||
**Loop not running (fallback mode):**
|
||||
```bash
|
||||
# This is expected if ralph-orchestrator isn't installed
|
||||
# The script still creates project files for manual use
|
||||
cat .ralph/PROMPT.md
|
||||
cat .ralph/ralph.yml
|
||||
```
|
||||
|
||||
### Ralph Orchestrator Source
|
||||
|
||||
- **GitHub**: https://github.com/mikeyobrien/ralph-orchestrator
|
||||
- **PyPI**: https://pypi.org/project/ralph-orchestrator/
|
||||
- **Author**: Mike O'Brien
|
||||
- **License**: MIT
|
||||
|
||||
---
|
||||
|
||||
## 📄 License
|
||||
|
||||
MIT License - See [LICENSE](LICENSE) file for details
|
||||
|
||||
Reference in New Issue
Block a user