From cd5c39811df0c0fe79fcae9659f8131f771fb3ef Mon Sep 17 00:00:00 2001 From: uroma Date: Fri, 23 Jan 2026 18:28:00 +0000 Subject: [PATCH] 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 --- README.md | 175 +++++++++++++++++++++++++++++++++++++++++++++++ requirements.txt | 19 +++++ supercharge.sh | 59 ++++++++++++++-- 3 files changed, 249 insertions(+), 4 deletions(-) create mode 100644 requirements.txt diff --git a/README.md b/README.md index fb1cb1e..5287134 100644 --- a/README.md +++ b/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 diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..218d8d6 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,19 @@ +# Python Dependencies for SuperCharged Claude Code +# Install with: pip install -r requirements.txt + +# Core: Ralph Orchestrator - Autonomous "Tackle Until Solved" agent loop +# Used by: /ralph command, ralphloop wrapper, autonomous iteration +ralph-orchestrator>=0.1.0 + +# Optional: YAML parsing for ralph configuration +# Used by: ralphloop script, agent sync scripts +pyyaml>=6.0 + +# Optional: jq alternative for JSON parsing in Python +# Used by: Some hooks and scripts that need JSON manipulation +# Install if you don't have jq installed: apt-get install jq + +# Development dependencies (optional) +# pytest>=7.0 +# black>=23.0 +# mypy>=1.0 diff --git a/supercharge.sh b/supercharge.sh index de29757..c639900 100755 --- a/supercharge.sh +++ b/supercharge.sh @@ -189,16 +189,67 @@ install_dependencies() { log_success "Git found: $(git --version)" fi - # Install Ralph Orchestrator if not present - if ! command -v ralph &> /dev/null; then + # Install Ralph Orchestrator (Python package for /ralph autonomous agent) + RALPH_INSTALLED=false + + # Check if ralph command exists + if command -v ralph &> /dev/null; then + log_success "Ralph Orchestrator found: $(ralph --version 2>/dev/null || echo 'installed')" + RALPH_INSTALLED=true + fi + + # Check if Python package is installed + if python3 -c "import ralph_orchestrator" 2>/dev/null; then + if [ "$RALPH_INSTALLED" = false ]; then + log_success "Ralph Orchestrator Python package found" + RALPH_INSTALLED=true + fi + fi + + # Install if not found + if [ "$RALPH_INSTALLED" = false ]; then log_info "Installing Ralph Orchestrator..." if command -v pip3 &> /dev/null; then - pip3 install ralph-orchestrator 2>/dev/null || log_warn "Failed to install Ralph Orchestrator" + # Try installing from requirements.txt if it exists in script dir + if [ -f "$SCRIPT_DIR/requirements.txt" ]; then + log_info "Installing from requirements.txt..." + pip3 install -r "$SCRIPT_DIR/requirements.txt" 2>/dev/null && { + log_success "Ralph Orchestrator installed from requirements.txt" + } || { + # Fallback to direct install + log_warn "requirements.txt install failed, trying direct install..." + pip3 install ralph-orchestrator pyyaml 2>/dev/null || { + log_error "Failed to install Ralph Orchestrator" + echo "" + echo -e "${YELLOW}Ralph Orchestrator is required for /ralph command${NC}" + echo "Install manually:" + echo " pip3 install ralph-orchestrator" + echo "" + echo "The /ralph command will not work without it." + } + } + else + # Direct install + pip3 install ralph-orchestrator pyyaml 2>/dev/null && { + log_success "Ralph Orchestrator installed" + } || { + log_warn "Failed to install Ralph Orchestrator" + } + fi else log_warn "pip3 not found. Skipping Ralph Orchestrator installation." + echo "" + echo -e "${YELLOW}Install pip3 first:${NC}" + echo " sudo apt-get install python3-pip" + echo " Then: pip3 install ralph-orchestrator" fi + fi + + # Verify installation + if command -v ralph &> /dev/null || python3 -c "import ralph_orchestrator" 2>/dev/null; then + log_success "Ralph Orchestrator ready for /ralph command" else - log_success "Ralph Orchestrator found" + log_warn "Ralph Orchestrator not available - /ralph command will use fallback mode" fi }