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>

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

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

supercharge.sh

@@ -189,16 +189,67 @@ install_dependencies() {
         log_success "Git found: $(git --version)"
     fi
 
-    # Install Ralph Orchestrator if not present
+    # Install Ralph Orchestrator (Python package for /ralph autonomous agent)
-    if ! command -v ralph &> /dev/null; then
+    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
-            log_warn "pip3 not found. Skipping Ralph Orchestrator installation."
+                # 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_success "Ralph Orchestrator found"
+            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_warn "Ralph Orchestrator not available - /ralph command will use fallback mode"
     fi
 }