diff --git a/MASTER-PROMPT.md b/MASTER-PROMPT.md index 432d4da..c688310 100644 --- a/MASTER-PROMPT.md +++ b/MASTER-PROMPT.md @@ -479,17 +479,191 @@ Vision tools from @z_ai/mcp-server are automatically available. --- -## Step 6: Configure Hooks-Based Auto-Triggering (Optional) +## Step 6: Configure Ralph CLI Autonomous Looping (Advanced - Optional) -Create hooks.json for additional auto-triggering: +Source: https://github.com/iannuttall/ralph + +**What Ralph Provides:** +Ralph is an autonomous agent orchestration tool that creates infinite loops until task completion. Unlike single-pass PROACTIVELY agents, Ralph maintains state across multiple iterations and coordinates agents through complex workflows. + +**Key Differences:** +- **PROACTIVELY Agents**: Single-pass coordination, one interaction +- **Ralph CLI**: Infinite looping, stateful, autonomous until done + +### Installation: + +Install Ralph CLI: +npm install -g @iannuttall/ralph + +Verify installation: +ralph --version + +### Create Ralph Auto-Trigger Hook: + +mkdir -p ~/.claude/hooks +cat > ~/.claude/hooks/ralph-auto-trigger.sh << 'EOF' +#!/bin/bash + +# Ralph Auto-Trigger Hook +# Automatically starts Ralph loop when user requests something +# Set RALPH_AUTO_MODE environment variable to control behavior: +# "always" - Always start Ralph for every request +# "agents" - Only start Ralph for agent requests (default) +# "off" - Disable auto-trigger + +set -euo pipefail + +# Read hook input from stdin +HOOK_INPUT=$(cat) + +# Get the user prompt from hook input +USER_PROMPT=$(echo "$HOOK_INPUT" | jq -r '.prompt // empty') + +# Check if auto-trigger is enabled (default: agents) +RALPH_AUTO_MODE="${RALPH_AUTO_MODE:-agents}" + +# Exit if auto-trigger is disabled +if [[ "$RALPH_AUTO_MODE" == "off" ]]; then + exit 0 +fi + +# Exit if Ralph is already active +RALPH_STATE_FILE=".claude/ralph-loop.local.md" +if [[ -f "$RALPH_STATE_FILE" ]]; then + exit 0 +fi + +# Check if this is an agent request (list of known agents) +KNOWN_AGENTS="frontend-developer|backend-architect|mobile-app-builder|ai-engineer|devops-automator|rapid-prototyper|test-writer-fixer|studio-coach|studio-producer|sprint-prioritizer|experiment-tracker|whimsy-injector|joker|trend-researcher|tiktok-strategist|feedback-synthesizer|ui-ux-pro-max" + +# Determine if we should start Ralph +START_RALPH=false + +case "$RALPH_AUTO_MODE" in + "always") + # Start Ralph for everything + START_RALPH=true + ;; + "agents") + # Check if prompt mentions an agent or uses agent-like language + if echo "$USER_PROMPT" | grep -qiE "use (the |a )?($KNOWN_AGENTS) agent|launch ($KNOWN_AGENTS)|agent:|delegate to|run (the |a )?($KNOWN_AGENTS)" || \ + echo "$USER_PROMPT" | grep -qiE "build|create|implement|develop|fix|add|refactor|optimize"; then + START_RALPH=true + fi + ;; +esac + +if [[ "$START_RALPH" == "true" ]]; then + # Create Ralph state file with default settings + mkdir -p .claude + + cat > "$RALPH_STATE_FILE" <&2 + echo " Mode: $RALPH_AUTO_MODE" >&2 + echo " Ralph will loop this request indefinitely." >&2 + echo " Set RALPH_AUTO_MODE=off to disable, or use /cancel-ralph to stop." >&2 +fi + +exit 0 +EOF + +chmod +x ~/.claude/hooks/ralph-auto-trigger.sh + +### Configure Hooks: + +Create hooks.json to enable Ralph auto-trigger: cat > ~/.claude/hooks.json << 'EOF' { - "userPromptSubmitHook": "test-writer-fixer@agent", - "toolOutputHook": "whimsy-injector@agent" + "description": "User hooks for Ralph auto-trigger", + "hooks": { + "UserPromptSubmit": [ + { + "hooks": [ + { + "type": "command", + "command": "/home/uroma/.claude/hooks/ralph-auto-trigger.sh", + "timeout": 5 + } + ] + } + ] + } } EOF -Note: PROACTIVELY agents (studio-coach, experiment-tracker) work automatically without hooks. +Note: Replace "/home/uroma" with your actual home directory if different. + +### What This Provides: + +**Autonomous Looping:** +- Ralph keeps iterating until task completion +- State preserved in `.claude/ralph-loop.local.md` +- Can handle complex multi-step workflows + +**Control Modes:** + +# Mode 1: Auto-loop only for agent requests (default) +export RALPH_AUTO_MODE="agents" + +# Mode 2: Auto-loop for everything +export RALPH_AUTO_MODE="always" + +# Mode 3: Disable auto-loop +export RALPH_AUTO_MODE="off" + +### How It Works: + +1. You request: "Build a TikTok app in 2 weeks" +2. Hook detects agent language +3. Ralph creates state file and starts loop +4. Ralph iterates through agents: + - Iteration 1: rapid-prototyper builds MVP + - Iteration 2: tiktok-strategist plans viral features + - Iteration 3: frontend-developer builds UI + - Continues until Ralph is satisfied +5. Ralph updates `.claude/ralph-loop.local.md` each iteration +6. Stop with: /cancel-ralph command or delete state file + +### Canceling Ralph: + +If Ralph is looping and you want to stop: + +# Method 1: Use cancel command +/cancel-ralph + +# Method 2: Delete state file +rm .claude/ralph-loop.local.md + +# Method 3: Disable auto-mode +export RALPH_AUTO_MODE="off" + +### Ralph vs PROACTIVELY Agents: + +| Feature | Ralph CLI | PROACTIVELY Agents | +|---------|-----------|-------------------| +| **Execution** | Multi-loop iterations | Single interaction | +| **State** | Persisted in file | Context only | +| **Control** | Manual stop required | Automatic | +| **Complexity** | Handles complex workflows | Quick coordination | +| **Setup** | Requires hook + script | Built-in to agents | + +**You can use BOTH together:** +- Use Ralph for complex, multi-step projects +- Use PROACTIVELY agents for quick tasks +- Set RALPH_AUTO_MODE="agents" for hybrid approach --- @@ -509,7 +683,13 @@ tldr --help # 3. Verify TLDR indexing tldr status . -# 4. Test Claude Code +# 4. Verify Ralph CLI (if installed) +ralph --version + +# 5. Verify Ralph hook +ls -la ~/.claude/hooks/ralph-auto-trigger.sh + +# 6. Test Claude Code claude --version Expected results: @@ -518,6 +698,7 @@ Expected results: - ✅ MCP tools accessible - ✅ TLDR indexed current directory - ✅ Settings configured +- ⚠️ Ralph CLI (optional - verify if installed in Step 6) --- @@ -531,9 +712,10 @@ Organized across 8 departments with PROACTIVELY auto-triggering - 3 web/GitHub tools (@z_ai/coding-helper) - 18 code analysis tools (llm-tldr) -### Two Auto-Triggering Systems -- PROACTIVELY keyword (context-aware) -- Hooks-based (event-driven) +### Three Auto-Triggering Systems +- **PROACTIVELY keyword** (context-aware, built into agents) +- **Ralph CLI** (autonomous looping, optional advanced setup) +- **Hooks-based** (event-driven, for Ralph integration) ### Complete Integration Benefits