anvil-dev-framework 0.1.6

package/docs/specifications/SPEC-ANV-VRW/component-04-ralph-wiggum.md

@@ -0,0 +1,604 @@
+---
+shard_id: SPEC-ANV-VRW/component-04
+parent: SPEC-ANV-VRW
+title: Ralph Wiggum Mode (/ralph)
+status: draft
+linear_issue: ANV-144, ANV-145
+priority: P1
+estimated_hours: 10-12
+dependencies:
+  - component-01-verify
+  - component-02-stop-gate
+research_sources:
+  - https://github.com/anthropics/claude-code/tree/main/plugins/ralph-wiggum
+  - https://github.com/frankbria/ralph-claude-code
+  - https://paddo.dev/blog/ralph-wiggum-autonomous-loops/
+  - https://dev.to/sivarampg/the-ralph-wiggum-approach-running-ai-coding-agents-for-hours-not-minutes-57c1
+---
+
+# Component 4: Ralph Wiggum Mode (`/ralph`)
+
+## Overview
+
+Long-running unattended execution mode based on Geoffrey Huntley's technique. Uses a bash loop with completion promises and stop hook interception for multi-hour autonomous sessions.
+
+> Geoffrey Huntley: "6 repos overnight", "$50k contract for $297"
+
+**Official Plugin**: `ralph-wiggum@claude-plugins-official` (Anthropic-maintained)
+
+---
+
+## Core Mechanism
+
+```bash
+# The Ralph Wiggum loop
+while :; do
+    cat PROMPT.md | npx --yes @anthropic/claude-code --print
+done
+```
+
+**Key Insight**: Each iteration sees the modified files and git history from previous runs. Claude autonomously improves by reading its own past work.
+
+---
+
+## Requirements
+
+| ID | Requirement | Priority | Acceptance Criteria |
+|----|-------------|----------|---------------------|
+| REQ-RW-100 | Create PROMPT.md with structured task format | P0 | Template generates valid prompt |
+| REQ-RW-101 | Implement completion promise pattern | P0 | Configurable promise detected |
+| REQ-RW-102 | Stop hook intercepts exit, restarts on incomplete | P0 | Loop continues until promise |
+| REQ-RW-103 | Maximum iterations safety (default: 50) | P0 | Hard limit prevents runaway |
+| REQ-RW-104 | Track iteration count and progress | P0 | State file updated each loop |
+| REQ-RW-105 | Single-item focus per iteration (critical) | P0 | Prompt enforces one item |
+| REQ-RW-106 | Context management via subagents | P1 | Research uses subagents |
+| REQ-RW-107 | Self-learning AGENT.md updates | P2 | Claude can update guidance |
+| REQ-RW-108 | **Circuit breaker** for stuck loops | P0 | Stops on no-change/repeated-error |
+| REQ-RW-109 | **Progress file** (`progress.txt`) | P0 | Appended each iteration |
+| REQ-RW-110 | **Git checkpoint** before restart | P1 | Auto-commit prevents lost work |
+| REQ-RW-111 | **Configurable promise** flag | P1 | `--completion-promise "TEXT"` |
+| REQ-RW-112 | **jq dependency** documentation | P1 | Windows/Git Bash warning |
+
+---
+
+## Circuit Breaker System (CRITICAL)
+
+Based on frankbria/ralph-claude-code implementation:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    CIRCUIT BREAKER                          │
+├─────────────────────────────────────────────────────────────┤
+│ Trigger Conditions (any one activates):                     │
+│                                                             │
+│ 1. 3 consecutive loops with NO file changes → STOP         │
+│ 2. 5+ loops repeating identical error pattern → STOP       │
+│ 3. Output volume declining >70% → STOP                      │
+│ 4. Claude reports "I'm stuck" or similar → STOP            │
+│                                                             │
+│ States:                                                     │
+│ • CLOSED  - Operating normally                              │
+│ • OPEN    - Broken, stops execution                         │
+│ • HALF    - Monitoring for recovery                         │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Progress File Pattern (CRITICAL)
+
+Each iteration MUST append to `progress.txt`:
+
+```markdown
+## Iteration 5 - 2026-01-07T14:30:00Z
+
+### Completed
+- Implemented OAuth callback handler
+- Added error handling for token refresh
+
+### Attempted (failed)
+- Tried to add session persistence (test failure)
+
+### Next
+- Fix session persistence test
+- Add logout endpoint
+
+### Blockers
+- None
+```
+
+**Purpose**: Prevents repeated mistakes by giving Claude visibility into past attempts.
+
+---
+
+## Git Checkpointing
+
+Before each iteration restart:
+
+```bash
+# Auto-checkpoint before restart
+git add -A
+git commit -m "ralph: checkpoint iteration $ITERATION" --allow-empty
+```
+
+**Why**: Lost progress is a common failure mode. Auto-checkpointing ensures recovery.
+
+---
+
+## Three-Phase Architecture
+
+Based on Ralph Wiggum's proven pattern:
+
+```
+Phase 1: Requirements → specs/*.md
+         User provides high-level requirements
+         Claude generates detailed specifications
+
+Phase 2: Specs → fix_plan.md (TODO list)
+         Specifications broken into atomic tasks
+         Each task is independently completable
+
+Phase 3: TODO items → Implementation (one at a time)
+         Loop processes one item per iteration
+         Commits on success, continues until done
+```
+
+---
+
+## Implementation Tasks
+
+### Task 1: Create Ralph Stop Hook
+**File**: `global/hooks/ralph_stop.sh`
+**Estimated**: 3 hours
+
+- [ ] Read iteration count from state file
+- [ ] Increment iteration counter
+- [ ] Check max iterations limit (50 default)
+- [ ] Scan transcript for configurable completion promise
+- [ ] Scan for `<fatal>` error signal
+- [ ] **Circuit breaker detection**:
+  - [ ] Track file changes (git diff --stat)
+  - [ ] Track error patterns (hash last 3 errors)
+  - [ ] Stop on 3 no-change loops
+  - [ ] Stop on 5 repeated error loops
+- [ ] **Git checkpoint** before restart
+- [ ] Return exit code (0 = allow, non-zero = restart)
+- [ ] Clean up state on completion
+
+### Task 2: Create Prompt Templates
+**File**: `global/templates/ralph/`
+**Estimated**: 2 hours
+
+- [ ] Create `PROMPT.md.template`
+- [ ] Create `fix_plan.md.template`
+- [ ] Create `progress.txt.template`
+- [ ] Implement variable substitution
+- [ ] Add iteration tracking variables
+- [ ] Include constraint reminders
+- [ ] **Add progress.txt update instructions**
+
+### Task 3: Create /ralph Skill
+**File**: `global/commands/ralph.md`
+**Estimated**: 2.5 hours
+
+- [ ] `start [description]` - Initialize Ralph mode
+- [ ] `status` - Show current progress
+- [ ] `stop` - Force exit Ralph mode
+- [ ] **`--completion-promise "TEXT"` flag**
+- [ ] **`--max-iterations N` flag**
+- [ ] Document critical constraints
+- [ ] Add examples and anti-patterns
+
+### Task 4: Create Execution Script
+**File**: `global/tools/ralph-loop.sh`
+**Estimated**: 1.5 hours
+
+- [ ] Set up bash loop
+- [ ] Feed PROMPT.md to Claude CLI
+- [ ] Handle exit codes
+- [ ] Implement restart logic
+- [ ] Add logging
+
+### Task 5: State Management
+**File**: `global/lib/ralph_state.py`
+**Estimated**: 1 hour
+
+- [ ] Store state in `.claude/ralph-state.json`
+- [ ] Track: iteration, last_action, remaining_items
+- [ ] Clean up on completion
+- [ ] Handle corruption gracefully
+
+---
+
+## PROMPT.md Template
+
+```markdown
+# Task: {task_name}
+
+## Objective
+{objective}
+
+## Current State
+- Iteration: {iteration_count}
+- Last action: {last_action}
+- Remaining items: {remaining_count}
+
+## Instructions
+1. **Read progress.txt** first - learn from previous iterations
+2. Read fix_plan.md for current TODO list
+3. Complete ONLY the first unchecked item
+4. Run tests after completion
+5. If tests pass, mark item complete in fix_plan.md
+6. **Update progress.txt** with what you did this iteration
+7. If all items complete, output: <promise>{completion_promise}</promise>
+
+## Progress Tracking (REQUIRED)
+After each iteration, append to progress.txt:
+```
+## Iteration {n} - {timestamp}
+### Completed: [what you finished]
+### Attempted: [what you tried but failed]
+### Next: [what to do next iteration]
+### Blockers: [anything blocking progress]
+```
+
+## Constraints
+- ONE item per iteration (critical)
+- Do not skip verification
+- Commit on each successful item
+- Use subagents for research (max 500)
+- Use only 1 agent for build/test
+- ALWAYS update progress.txt
+
+## Completion Signal
+When ALL items are done and tests pass:
+<promise>{completion_promise}</promise>
+
+## Fatal Error Signal
+If stuck or unrecoverable after multiple attempts:
+<fatal>Description of issue</fatal>
+```
+
+---
+
+## Stop Hook Implementation
+
+```bash
+#!/bin/bash
+# global/hooks/ralph_stop.sh
+# Ralph Wiggum stop hook with circuit breaker
+#
+# DEPENDENCY: jq (apt install jq / brew install jq)
+# WARNING: Windows/Git Bash users must install jq separately or use WSL
+
+set -euo pipefail
+
+TRANSCRIPT="$CLAUDE_TRANSCRIPT"
+MAX_ITERATIONS="${RALPH_MAX_ITERATIONS:-50}"
+COMPLETION_PROMISE="${RALPH_COMPLETION_PROMISE:-COMPLETE}"
+STATE_FILE=".claude/ralph-state.json"
+PROGRESS_FILE="progress.txt"
+
+# =============================================================================
+# State Management
+# =============================================================================
+
+init_state() {
+    if [[ ! -f "$STATE_FILE" ]]; then
+        echo '{"iteration":0,"no_change_count":0,"error_hashes":[],"last_diff_hash":""}' > "$STATE_FILE"
+    fi
+}
+
+read_state() {
+    jq -r ".$1 // \"$2\"" "$STATE_FILE" 2>/dev/null || echo "$2"
+}
+
+update_state() {
+    local key="$1" value="$2"
+    jq --arg v "$value" ".$key = \$v" "$STATE_FILE" > tmp.$$ && mv tmp.$$ "$STATE_FILE"
+}
+
+# =============================================================================
+# Circuit Breaker Detection
+# =============================================================================
+
+get_current_diff_hash() {
+    git diff --stat 2>/dev/null | md5sum | cut -d' ' -f1
+}
+
+check_circuit_breaker() {
+    local iteration="$1"
+
+    # Check 1: No file changes for 3 consecutive iterations
+    local current_hash
+    current_hash=$(get_current_diff_hash)
+    local last_hash
+    last_hash=$(read_state "last_diff_hash" "")
+
+    if [[ "$current_hash" == "$last_hash" ]]; then
+        local no_change_count
+        no_change_count=$(read_state "no_change_count" "0")
+        no_change_count=$((no_change_count + 1))
+        update_state "no_change_count" "$no_change_count"
+
+        if [[ $no_change_count -ge 3 ]]; then
+            echo "🔴 Circuit breaker: 3 iterations with no file changes"
+            return 1
+        fi
+    else
+        update_state "no_change_count" "0"
+        update_state "last_diff_hash" "$current_hash"
+    fi
+
+    # Check 2: Repeated error patterns (tracked via error_hashes in state)
+    # Implementation would compare last N error outputs
+
+    return 0
+}
+
+# =============================================================================
+# Git Checkpointing
+# =============================================================================
+
+git_checkpoint() {
+    local iteration="$1"
+    if git diff --quiet 2>/dev/null; then
+        return 0  # No changes to commit
+    fi
+    git add -A
+    git commit -m "ralph: checkpoint iteration $iteration" --no-verify 2>/dev/null || true
+}
+
+# =============================================================================
+# Main Logic
+# =============================================================================
+
+main() {
+    init_state
+
+    local iteration
+    iteration=$(read_state "iteration" "0")
+    iteration=$((iteration + 1))
+    update_state "iteration" "$iteration"
+
+    echo "🔄 Ralph Wiggum: Iteration $iteration"
+
+    # Safety: Max iterations
+    if [[ $iteration -ge $MAX_ITERATIONS ]]; then
+        echo "⚠️ Maximum iterations ($MAX_ITERATIONS) reached"
+        rm -f "$STATE_FILE"
+        exit 0
+    fi
+
+    # Check for completion promise
+    if grep -q "<promise>$COMPLETION_PROMISE</promise>" "$TRANSCRIPT" 2>/dev/null; then
+        echo "✅ Task complete after $iteration iterations"
+        rm -f "$STATE_FILE"
+        exit 0
+    fi
+
+    # Check for fatal error
+    if grep -q "<fatal>" "$TRANSCRIPT" 2>/dev/null; then
+        echo "❌ Fatal error detected"
+        rm -f "$STATE_FILE"
+        exit 0
+    fi
+
+    # Circuit breaker check
+    if ! check_circuit_breaker "$iteration"; then
+        echo "🔴 Circuit breaker activated - stopping loop"
+        rm -f "$STATE_FILE"
+        exit 0
+    fi
+
+    # Git checkpoint before restart
+    git_checkpoint "$iteration"
+
+    echo "🔄 Restarting iteration $((iteration + 1))..."
+    exit 1  # Block exit, trigger restart
+}
+
+main "$@"
+```
+
+### Dependencies Note
+
+**jq is required**: The stop hook uses `jq` for JSON state management.
+
+| Platform | Installation |
+|----------|--------------|
+| macOS | `brew install jq` |
+| Ubuntu/Debian | `apt install jq` |
+| Windows/Git Bash | Install manually or use WSL |
+
+**Known Issue**: Windows/Git Bash users report the plugin breaks without jq installed.
+
+---
+
+## /ralph Skill
+
+```markdown
+# /ralph - Ralph Wiggum Long-Running Mode
+
+> Enable long-running unattended execution with completion promises.
+
+## Arguments
+- `start [task-description]` - Initialize Ralph mode with task
+- `status` - Show current iteration and progress
+- `stop` - Force exit Ralph mode
+
+## Execution: /ralph start
+
+### Step 1: Create Task Structure
+Create PROMPT.md with:
+- Clear single objective
+- Current state tracking
+- Constraints and completion signal
+
+### Step 2: Enable Stop Hook
+Activate ralph_stop.sh hook that:
+- Checks for <promise>COMPLETE</promise>
+- Blocks exit if incomplete
+- Tracks iteration count
+- Has max iterations safety
+
+### Step 3: Create fix_plan.md
+Break task into atomic TODO items:
+- [ ] Item 1
+- [ ] Item 2
+- ...
+
+### Step 4: Start Loop
+Execute bash loop that:
+- Feeds PROMPT.md to Claude
+- Processes one item per iteration
+- Commits on success
+- Restarts until complete
+
+## Critical Rules
+1. **ONE item per loop** - Never try to do multiple items
+2. **Subagents for research** - Don't pollute main context
+3. **Commit on success** - Each item gets committed
+4. **Tests gate progress** - No marking complete without tests
+5. **500 research / 1 build** - Subagent ratio
+```
+
+---
+
+## State File Schema
+
+```json
+{
+  "task_name": "Implement OAuth",
+  "started_at": "2026-01-04T14:00:00Z",
+  "iteration": 5,
+  "last_action": "Completed OAuth callback handler",
+  "remaining_items": 3,
+  "total_items": 8,
+  "completed_items": [
+    "Set up OAuth provider config",
+    "Create login endpoint",
+    "Implement token exchange",
+    "Add session storage",
+    "Create callback handler"
+  ]
+}
+```
+
+---
+
+## Test Cases
+
+| Test Case | Setup | Expected |
+|-----------|-------|----------|
+| Simple task | 3-item fix_plan | Completes in 3 iterations |
+| Max iterations | Unfixable task | Stops at 50, logs warning |
+| Completion promise | All items done | Exits with success |
+| Custom promise | `--completion-promise "DONE"` | Detects custom promise |
+| Fatal error | `<fatal>` output | Exits immediately |
+| Resume after crash | Existing state file | Continues from last iteration |
+| **Circuit breaker: no changes** | 3 loops, no file changes | Stops, logs "no file changes" |
+| **Circuit breaker: repeated error** | 5 loops, same error | Stops, logs "repeated error" |
+| **Git checkpoint** | Loop with changes | Commits before restart |
+| **Progress file** | Any loop | progress.txt updated each iteration |
+
+---
+
+## Safety Mechanisms
+
+| Risk | Mitigation |
+|------|------------|
+| Infinite loop | Max iterations (50) |
+| Stuck loops | **Circuit breaker** (3 no-change, 5 repeated-error) |
+| Context explosion | Subagent usage |
+| Lost progress | **Git checkpointing** + commit on each item |
+| Repeated mistakes | **progress.txt** tracking |
+| Stuck state | Fatal error signal |
+| Resource exhaustion | Single build agent |
+| Runaway costs | Max iterations + circuit breaker |
+
+---
+
+## When to Use Ralph
+
+**Good Use Cases:**
+- ✅ Well-defined tasks with clear success criteria (tests pass, build succeeds)
+- ✅ Large-scale refactoring with measurable completion
+- ✅ Framework/dependency migrations (Jest→Vitest, etc.)
+- ✅ Test coverage expansion (reach X% coverage)
+- ✅ Greenfield projects where you can walk away overnight
+- ✅ TDD workflows: implement features to pass failing tests
+
+**Bad Use Cases:**
+- ❌ Ambiguous requirements ("make it better")
+- ❌ Architectural decisions requiring human judgment
+- ❌ Security-sensitive code (auth, payments, data handling)
+- ❌ Exploratory work ("figure out why it's slow")
+- ❌ Tasks with no objective success criteria
+- ❌ Production debugging
+
+---
+
+## Cost Considerations
+
+**Token Consumption Warning:**
+
+| Scenario | Estimated Cost |
+|----------|----------------|
+| 10-iteration loop, small codebase | $5-15 |
+| 50-iteration loop, medium codebase | $50-100+ |
+| 100+ iterations, large codebase | $200+ |
+
+**Best Practices:**
+1. Start conservative: `--max-iterations 10`
+2. Monitor costs during initial runs
+3. Use clear completion criteria to minimize wasted iterations
+4. Consider time-boxing (kill after N hours regardless)
+
+**On Claude Code subscription**: You'll hit usage limits faster with Ralph loops.
+
+---
+
+## Effective Prompt Engineering
+
+### Strong Prompt Example
+```
+Migrate all tests from Jest to Vitest.
+
+Requirements:
+- Update test file syntax
+- Update package.json scripts
+- Remove Jest dependencies, add Vitest
+- Run tests after migration
+
+Completion Criteria:
+- ALL tests passing
+- No Jest references remaining
+
+Output: <promise>MIGRATED</promise> when complete.
+```
+
+### Weak Prompt Example
+```
+Make it better.
+```
+
+**Key Insight**: Objective, measurable criteria (tests pass, build succeeds, coverage threshold) outperform subjective Claude self-assessment.
+
+---
+
+## Integration Points
+
+- **Trigger**: `/ralph start` command
+- **Input**: Task description, optional fix_plan.md
+- **Output**: Completed implementation with commits
+- **Dependencies**: component-01 (verify), component-02 (stop-gate)
+
+---
+
+## References
+
+- [Official Plugin](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/ralph-wiggum) - Anthropic-maintained
+- [frankbria/ralph-claude-code](https://github.com/frankbria/ralph-claude-code) - Circuit breaker implementation
+- [Geoffrey Huntley's Original](https://ghuntley.com/ralph/) - Technique origin
+- [Ralph Orchestrator](https://github.com/mikeyobrien/ralph-orchestrator) - Multi-AI coordination