@the-bearded-bear/claude-craft 3.0.2 → 3.1.0

package/Tools/Ralph/README.md

@@ -0,0 +1,303 @@
+# Ralph Wiggum - Continuous AI Agent Loop
+
+Ralph Wiggum is a methodology and tool for running Claude in a continuous loop until a task is complete. It provides structured completion detection through Definition of Done (DoD) validation, safety mechanisms via circuit breakers, and progress tracking through git checkpoints.
+
+## Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  RALPH LOOP                                                  │
+│                                                              │
+│  while (iterations < max && !complete) {                     │
+│      response = claude("--continue", session_id, prompt)     │
+│      complete = checkDoD(response)                           │
+│      if (circuitBreaker.triggered()) break                   │
+│      createCheckpoint(iteration)                             │
+│      prompt = response  // feedback loop                     │
+│  }                                                           │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Quick Start
+
+### Via CLI
+
+```bash
+# Basic usage
+npx @the-bearded-bear/claude-craft ralph "Implement user authentication"
+
+# With configuration
+npx @the-bearded-bear/claude-craft ralph --config=ralph.yml "Fix the login bug"
+
+# Resume session
+npx @the-bearded-bear/claude-craft ralph --continue=ralph-1704067200-a1b2
+```
+
+### Via Command in Claude Code
+
+```bash
+/common:ralph-run "Implement user authentication"
+```
+
+### Direct Script
+
+```bash
+./Tools/Ralph/ralph.sh "Implement user authentication"
+./Tools/Ralph/ralph.sh --lang=fr --verbose "Corriger le bug de connexion"
+```
+
+## Configuration
+
+Create `ralph.yml` in your project root or `.claude/ralph.yml`:
+
+```yaml
+version: "1.0"
+
+session:
+  max_iterations: 25
+  timeout: 600000  # 10 minutes per iteration
+  delay_between_iterations: 1000
+
+circuit_breaker:
+  enabled: true
+  no_file_changes_threshold: 3
+  repeated_error_threshold: 5
+  output_decline_threshold: 70
+
+checkpointing:
+  enabled: true
+  async: true
+  branch_prefix: "ralph/"
+
+definition_of_done:
+  checklist:
+    - id: tests
+      name: "All tests pass"
+      type: command
+      command: "docker compose exec app npm test"
+      required: true
+
+    - id: lint
+      name: "No lint errors"
+      type: command
+      command: "docker compose exec app npm run lint"
+      required: true
+
+    - id: completion
+      name: "Claude signals completion"
+      type: output_contains
+      pattern: "<promise>COMPLETE</promise>"
+      required: true
+```
+
+## Definition of Done (DoD)
+
+The key improvement over simple completion markers. DoD validates task completion through multiple criteria:
+
+### Validator Types
+
+| Type | Description | Example |
+|------|-------------|---------|
+| `command` | Run shell command, check exit code | `npm test` |
+| `output_contains` | Check Claude output for pattern | `<promise>COMPLETE</promise>` |
+| `file_changed` | Check if files matching pattern changed | `*.md` |
+| `hook` | Run existing Claude hook script | `quality-gate.sh` |
+| `human` | Prompt user for confirmation | Interactive gate |
+
+### Example Checklist
+
+```yaml
+definition_of_done:
+  checklist:
+    # Automated tests
+    - id: tests
+      name: "All tests pass"
+      type: command
+      command: "docker compose exec app npm test"
+      required: true
+
+    # Code quality
+    - id: lint
+      name: "No lint errors"
+      type: command
+      command: "docker compose exec app npm run lint"
+      required: true
+
+    # Completion signal
+    - id: completion
+      name: "Claude signals completion"
+      type: output_contains
+      pattern: "<promise>COMPLETE</promise>"
+      required: true
+
+    # Integration with existing hooks
+    - id: quality_gate
+      name: "Quality gate passes"
+      type: hook
+      script: ".claude/hooks/quality-gate.sh"
+      required: true
+
+    # Documentation (optional)
+    - id: docs
+      name: "Documentation updated"
+      type: file_changed
+      pattern: "*.md"
+      required: false
+
+    # Human approval (optional)
+    - id: review
+      name: "Manual review approved"
+      type: human
+      prompt: "Does the implementation look correct? (y/n):"
+      required: false
+```
+
+## Circuit Breaker
+
+Safety mechanism to prevent infinite loops:
+
+| Trigger | Default Threshold | Description |
+|---------|-------------------|-------------|
+| No file changes | 3 iterations | Stops if no files modified |
+| Repeated errors | 5 iterations | Stops on error loops |
+| Output decline | 70% | Stops if output shrinks significantly |
+| Max iterations | 25 | Hard limit |
+
+## Git Checkpointing
+
+Automatic git commits after each iteration:
+
+- **Recovery**: Restore to previous state if needed
+- **History**: Track progress through iterations
+- **Review**: Inspect what changed at each step
+
+Configuration:
+
+```yaml
+checkpointing:
+  enabled: true
+  async: true  # Non-blocking
+  branch_prefix: "ralph/"
+  commit_message_template: "checkpoint: Ralph iteration {iteration}"
+```
+
+## File Structure
+
+```
+Tools/Ralph/
+├── ralph.sh                    # Main entry point
+├── lib/
+│   ├── session.sh              # Session management
+│   ├── loop.sh                 # Core iteration loop
+│   ├── dod-validator.sh        # DoD validation
+│   ├── circuit-breaker.sh      # Safety mechanism
+│   └── checkpoint.sh           # Git checkpointing
+├── templates/
+│   └── ralph.yml.template      # Default configuration
+└── README.md                   # This file
+
+Tools/i18n/ralph/
+├── en.sh                       # English messages
+├── fr.sh                       # French messages
+├── es.sh                       # Spanish messages
+├── de.sh                       # German messages
+└── pt.sh                       # Portuguese messages
+```
+
+## CLI Options
+
+```
+ralph.sh [options] <prompt>
+
+Options:
+  --config=<file>       Path to ralph.yml configuration
+  --continue=<id>       Resume existing session
+  --max-iterations=<n>  Maximum iterations (default: 25)
+  --timeout=<ms>        Timeout per iteration (default: 600000)
+  --verbose             Enable verbose output
+  --dry-run             Show what would be done without executing
+  --lang=<code>         Language (en, fr, es, de, pt)
+  --help                Show help message
+```
+
+## Integration
+
+### With Existing Hooks
+
+Ralph can leverage existing Claude hooks:
+
+```yaml
+definition_of_done:
+  checklist:
+    - id: quality_gate
+      type: hook
+      script: ".claude/hooks/quality-gate.sh"
+      required: true
+```
+
+### With Sprint Development
+
+```bash
+# In sprint workflow
+/project:sprint-dev 1
+# Ralph handles each task until DoD passes
+```
+
+### With TDD Coach
+
+Ralph follows TDD principles:
+1. Write failing test (RED)
+2. Implement minimum code to pass (GREEN)
+3. Refactor while keeping tests green (REFACTOR)
+
+## Session Files
+
+Ralph creates a `.ralph/` directory in your project:
+
+```
+.ralph/
+├── sessions/
+│   └── ralph-1704067200-a1b2/
+│       ├── state.json          # Session state
+│       ├── metrics.json        # Iteration metrics
+│       ├── session.log         # Execution log
+│       └── last_output.txt     # Last Claude response
+```
+
+## Best Practices
+
+1. **Clear task description**: Provide specific, actionable tasks
+2. **Configure DoD**: Define completion criteria in `ralph.yml`
+3. **Use TDD**: Write tests first, let Ralph implement
+4. **Monitor progress**: Watch iteration output for issues
+5. **Set reasonable limits**: Adjust max_iterations for task complexity
+6. **Use Docker**: Run commands in Docker for consistency
+
+## Troubleshooting
+
+### Ralph stops immediately
+- Check if prompt is provided
+- Verify `ralph.yml` is valid YAML
+
+### Circuit breaker triggers too early
+- Increase thresholds in configuration
+- Check if task is making actual progress
+
+### DoD never passes
+- Verify commands work manually
+- Check required vs optional criteria
+- Ensure completion marker is output by Claude
+
+## Related
+
+- `/common:ralph-run` - Command to start Ralph from Claude Code
+- `@ralph-conductor` - Agent for Ralph orchestration
+- `/common:fix-bug-tdd` - TDD-based bug fixing
+- `/project:sprint-dev` - Sprint development with TDD
+
+## Credits
+
+Inspired by:
+- [anthropics/claude-code/plugins/ralph-wiggum](https://github.com/anthropics/claude-code)
+- [frankbria/ralph-claude-code](https://github.com/frankbria/ralph-claude-code)
+- [mikeyobrien/ralph-orchestrator](https://github.com/mikeyobrien/ralph-orchestrator)

package/Tools/Ralph/lib/checkpoint.sh

@@ -0,0 +1,238 @@
+#!/bin/bash
+# =============================================================================
+# Ralph Wiggum - Git Checkpointing Module
+# Creates git checkpoints for recovery and history tracking
+# =============================================================================
+
+# Checkpointing configuration
+CP_ENABLED="${CP_ENABLED:-true}"
+CP_ASYNC="${CP_ASYNC:-true}"
+CP_BRANCH_PREFIX="${CP_BRANCH_PREFIX:-ralph/}"
+CP_COMMIT_TEMPLATE="${CP_COMMIT_TEMPLATE:-checkpoint: Ralph iteration {iteration}}"
+
+# =============================================================================
+# Initialization
+# =============================================================================
+
+init_checkpointing() {
+    # Check if git is available
+    if ! command -v git &> /dev/null; then
+        CP_ENABLED=false
+        print_verbose "Git not found, checkpointing disabled"
+        return 1
+    fi
+
+    # Check if we're in a git repository
+    if ! git rev-parse --git-dir &> /dev/null; then
+        CP_ENABLED=false
+        print_verbose "Not in a git repository, checkpointing disabled"
+        return 1
+    fi
+
+    # Load config if available
+    if [[ -n "$CONFIG_FILE" && -f "$CONFIG_FILE" ]] && command -v yq &> /dev/null; then
+        local enabled=$(yq e '.checkpointing.enabled // ""' "$CONFIG_FILE" 2>/dev/null)
+        [[ "$enabled" == "false" ]] && CP_ENABLED=false
+
+        local async=$(yq e '.checkpointing.async // ""' "$CONFIG_FILE" 2>/dev/null)
+        [[ "$async" == "false" ]] && CP_ASYNC=false
+
+        local prefix=$(yq e '.checkpointing.branch_prefix // ""' "$CONFIG_FILE" 2>/dev/null)
+        [[ -n "$prefix" ]] && CP_BRANCH_PREFIX="$prefix"
+
+        local template=$(yq e '.checkpointing.commit_message_template // ""' "$CONFIG_FILE" 2>/dev/null)
+        [[ -n "$template" ]] && CP_COMMIT_TEMPLATE="$template"
+    fi
+
+    print_verbose "Checkpointing initialized:"
+    print_verbose "  - Enabled: $CP_ENABLED"
+    print_verbose "  - Async: $CP_ASYNC"
+    print_verbose "  - Branch prefix: $CP_BRANCH_PREFIX"
+
+    return 0
+}
+
+# =============================================================================
+# Create Checkpoint
+# =============================================================================
+
+create_checkpoint() {
+    local session_id="$1"
+    local iteration="$2"
+
+    if [[ "$CP_ENABLED" != "true" ]]; then
+        return 0
+    fi
+
+    # Check for changes to commit
+    if [[ -z "$(git status --porcelain 2>/dev/null)" ]]; then
+        print_verbose "No changes to checkpoint"
+        return 0
+    fi
+
+    # Generate commit message
+    local commit_msg="${CP_COMMIT_TEMPLATE/\{iteration\}/$iteration}"
+    commit_msg="${commit_msg/\{session_id\}/$session_id}"
+
+    if [[ "$CP_ASYNC" == "true" ]]; then
+        # Run checkpoint in background
+        _create_checkpoint_async "$session_id" "$iteration" "$commit_msg" &
+        print_verbose "${MSG_CHECKPOINT_CREATING} (async)"
+    else
+        # Run checkpoint synchronously
+        _create_checkpoint_sync "$session_id" "$iteration" "$commit_msg"
+    fi
+}
+
+# =============================================================================
+# Synchronous Checkpoint
+# =============================================================================
+
+_create_checkpoint_sync() {
+    local session_id="$1"
+    local iteration="$2"
+    local commit_msg="$3"
+
+    print_verbose "${MSG_CHECKPOINT_CREATING}"
+
+    # Stage all changes
+    git add -A 2>/dev/null
+
+    # Create commit
+    local commit_hash
+    commit_hash=$(git commit -m "$commit_msg" 2>/dev/null && git rev-parse --short HEAD)
+
+    if [[ -n "$commit_hash" ]]; then
+        print_verbose "${MSG_CHECKPOINT_CREATED}: $commit_hash"
+        log_session "$session_id" "INFO" "Checkpoint created: $commit_hash"
+    else
+        print_verbose "${MSG_CHECKPOINT_FAILED}"
+        log_session "$session_id" "WARN" "Checkpoint failed"
+    fi
+}
+
+# =============================================================================
+# Asynchronous Checkpoint
+# =============================================================================
+
+_create_checkpoint_async() {
+    local session_id="$1"
+    local iteration="$2"
+    local commit_msg="$3"
+
+    # Create a lock file to prevent concurrent checkpoints
+    local lock_file="/tmp/ralph-checkpoint-$session_id.lock"
+
+    # Try to acquire lock
+    if ! mkdir "$lock_file" 2>/dev/null; then
+        # Another checkpoint is in progress
+        return 0
+    fi
+
+    # Cleanup function
+    cleanup() {
+        rmdir "$lock_file" 2>/dev/null
+    }
+    trap cleanup EXIT
+
+    # Stage all changes
+    git add -A 2>/dev/null
+
+    # Create commit
+    git commit -m "$commit_msg" 2>/dev/null
+
+    # Log result
+    if [[ $? -eq 0 ]]; then
+        local commit_hash=$(git rev-parse --short HEAD 2>/dev/null)
+        log_session "$session_id" "INFO" "Async checkpoint created: $commit_hash"
+    fi
+
+    cleanup
+}
+
+# =============================================================================
+# Restore from Checkpoint
+# =============================================================================
+
+restore_checkpoint() {
+    local session_id="$1"
+    local commit_hash="$2"
+
+    if [[ "$CP_ENABLED" != "true" ]]; then
+        print_error "Checkpointing is disabled"
+        return 1
+    fi
+
+    print_info "${MSG_CHECKPOINT_RESTORING}"
+
+    # Verify commit exists
+    if ! git cat-file -e "$commit_hash" 2>/dev/null; then
+        print_error "Commit not found: $commit_hash"
+        return 1
+    fi
+
+    # Create a backup branch of current state
+    local backup_branch="ralph-backup-$(date +%s)"
+    git branch "$backup_branch" 2>/dev/null
+
+    # Reset to the checkpoint
+    if git reset --hard "$commit_hash" 2>/dev/null; then
+        print_success "${MSG_CHECKPOINT_RESTORED}"
+        log_session "$session_id" "INFO" "Restored to checkpoint: $commit_hash (backup: $backup_branch)"
+        return 0
+    else
+        print_error "${MSG_CHECKPOINT_FAILED}"
+        return 1
+    fi
+}
+
+# =============================================================================
+# List Checkpoints
+# =============================================================================
+
+list_checkpoints() {
+    local session_id="$1"
+
+    if [[ "$CP_ENABLED" != "true" ]]; then
+        echo "[]"
+        return
+    fi
+
+    # Find commits matching the checkpoint pattern
+    local commits
+    commits=$(git log --oneline --grep="checkpoint: Ralph" 2>/dev/null | head -20)
+
+    if [[ -n "$commits" ]]; then
+        echo "$commits" | while read -r line; do
+            local hash=$(echo "$line" | cut -d' ' -f1)
+            local msg=$(echo "$line" | cut -d' ' -f2-)
+            echo "{\"hash\":\"$hash\",\"message\":\"$msg\"}"
+        done | jq -s '.'
+    else
+        echo "[]"
+    fi
+}
+
+# =============================================================================
+# Create Branch for Session
+# =============================================================================
+
+create_session_branch() {
+    local session_id="$1"
+    local branch_name="${CP_BRANCH_PREFIX}${session_id}"
+
+    if [[ "$CP_ENABLED" != "true" ]]; then
+        return 1
+    fi
+
+    # Check if branch already exists
+    if git show-ref --verify --quiet "refs/heads/$branch_name" 2>/dev/null; then
+        # Switch to existing branch
+        git checkout "$branch_name" 2>/dev/null
+    else
+        # Create new branch
+        git checkout -b "$branch_name" 2>/dev/null
+    fi
+
+    print_verbose "${MSG_CHECKPOINT_BRANCH}: $branch_name"
+}