spec-and-loop 1.0.0 → 1.0.2

package/QUICKSTART.md

@@ -8,10 +8,10 @@ Install these tools (one-time setup):
 
 ```bash
 # 1. Install openspec (OpenSpec CLI)
-npm install -g openspec
+npm install -g @fission-ai/openspec@latest
 
 # 2. Install opencode (agentic coding assistant)
-npm install -g opencode
+npm install -g opencode-ai
 
 # 3. Install jq (command-line JSON processor)
 # Ubuntu/Debian:
@@ -32,7 +32,7 @@ npm install -g spec-and-loop
 
 **Prerequisites:** Install openspec and opencode:
 ```bash
-npm install -g openspec opencode
+npm install -g @fission-ai/openspec@latest opencode-ai
 ```
 
 ## Quick Demo (5 Minutes)
@@ -47,10 +47,10 @@ git init
 openspec init
 
 # 3. Create a new change
-opsx-new add-hello-world
+openspec new add-hello-world
 
 # 4. Fast-forward through artifact creation
-opsx-ff
+openspec ff
 
 # 5. Run the ralph loop (executes tasks with opencode)
 ralph-run --change add-hello-world
@@ -156,7 +156,7 @@ git diff HEAD~15        # See full implementation
 ### "openspec CLI not found" or "opencode CLI not found"
 
 ```bash
-npm install -g openspec opencode
+npm install -g @fission-ai/openspec@latest opencode-ai
 ```
 
 ### "jq CLI not found"
@@ -198,7 +198,7 @@ source ~/.bashrc
 grep "^\- \[x\]" openspec/changes/my-feature/tasks.md
 
 # Or create a new change
-opsx-new another-feature
+openspec new another-feature
 ```
 
 ## Features at a Glance

package/README.md

@@ -8,41 +8,35 @@ OpenSpec + Ralph Loop integration for iterative development with opencode.
 
 OpenSpec provides excellent structure for planning (proposal → specs → design → tasks) but leaves execution manual. Ralph Wiggum's iterative development loop (execute → commit → repeat) is powerful but requires PRD format instead of OpenSpec specs.
 
-**This utility bridges the gap**: use OpenSpec for planning, then automatically execute tasks with full context using opencode agentic coding assistant.
-
 ## Installation
 
 ```bash
 npm install -g spec-and-loop
 ```
 
-**Prerequisites:** You need openspec and opencode installed:
+**Prerequisites:** You need OpenSpec and the OpenCode AI agent installed:
 
 ```bash
-npm install -g openspec opencode
+# Install OpenSpec and OpenCode (recommended)
+npm install -g @fission-ai/openspec@latest opencode-ai
 ```
 
-## Quick Start
-
-**[🚀 Get Started in 5 Minutes](./QUICKSTART.md)**
+Alternative OpenCode install methods (if you prefer):
 
 ```bash
-# 1. Initialize OpenSpec in your project
-openspec init
+# npm (recommended)
+npm install -g opencode-ai
 
-# 2. Create a new change
-openspec new add-user-auth
+# Install script (general use)
+curl -fsSL https://opencode.ai/install | bash
 
-# 3. Fast-forward through artifact creation
-openspec ff add-user-auth
+# Homebrew (macOS / Linux)
+brew install anomalyco/tap/opencode
 
-# 4. Run the ralph loop (executes tasks with opencode)
-ralph-run --change add-user-auth
+# Windows: use WSL and install via one of the Linux methods above
 ```
 
-For detailed step-by-step instructions, see [QUICKSTART.md](./QUICKSTART.md).
-
-## Quick Start
+**[🚀 Get Started in 5 Minutes](./QUICKSTART.md)**
 
 ```bash
 # 1. Initialize OpenSpec in your project
@@ -58,30 +52,28 @@ openspec ff add-user-auth
 ralph-run --change add-user-auth
 ```
 
-Or auto-detect the most recent change:
+For detailed step-by-step instructions, see [QUICKSTART.md](./QUICKSTART.md).
 
-```bash
-ralph-run
-```
+<!-- Duplicate Quick Start removed; see QUICKSTART.md for full instructions -->
 
 ## Prerequisites
 
 Before using spec-and-loop, ensure you have:
 
-1. **Node.js & npm** - For package installation
+1. **Node.js** - For package installation
    ```bash
-   node --version  # Should be 14+
-   npm --version   # Should be 6+
+   node --version  # Should be >=24
    ```
 
 2. **openspec** - OpenSpec CLI for specification workflow
    ```bash
-   npm install -g openspec
+   npm install -g @fission-ai/openspec@latest
    ```
 
 3. **opencode** - Agentic coding assistant
    ```bash
-   npm install -g opencode
+   # Install via npm
+   npm install -g opencode-ai
    ```
 
 4. **jq** - Command-line JSON processor
@@ -321,7 +313,7 @@ For common issues and solutions, see [QUICKSTART.md#troubleshooting](./QUICKSTAR
 
 ```bash
 # opencode not found?
-npm install -g opencode
+npm install -g opencode-ai
 
 # jq not found?
 sudo apt install jq  # or: brew install jq
@@ -341,4 +333,4 @@ export PATH="$PATH:$(npm root -g)/.bin"
 
 ## License
 
-MIT
+GPL-3.0

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "spec-and-loop",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "OpenSpec + Ralph Loop integration for iterative development with opencode",
   "main": "index.js",
   "bin": {
-    "ralph-run": "./bin/ralph-run"
+    "ralph-run": "bin/ralph-run"
   },
   "scripts": {
     "postinstall": "node scripts/setup.js"
   },
   "dependencies": {
-    "openspec": "^1.0.0"
+    "@fission-ai/openspec": "latest"
   },
   "keywords": [
     "openspec",
@@ -23,7 +23,7 @@
   "license": "GPL-3.0",
   "repository": {
     "type": "git",
-    "url": "https://github.com/ncheaz/spec-and-loop.git"
+    "url": "git+https://github.com/ncheaz/spec-and-loop.git"
   },
   "files": [
     "bin/",

package/scripts/ralph-monitor.sh

@@ -0,0 +1,96 @@
+#!/bin/bash
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CHANGE_NAME="${1:-auto-detect}"
+
+if [[ "$CHANGE_NAME" == "auto-detect" ]]; then
+    # Auto-detect most recent change
+    CHANGE_NAME=$(ls -t openspec/changes/ 2>/dev/null | head -1)
+    if [[ -z "$CHANGE_NAME" ]]; then
+        echo "No changes found in openspec/changes/"
+        exit 1
+    fi
+fi
+
+TASKS_FILE="$SCRIPT_DIR/../openspec/changes/$CHANGE_NAME/tasks.md"
+RALPH_STATE="$SCRIPT_DIR/../.ralph/ralph-loop.state.json"
+
+if [[ ! -f "$TASKS_FILE" ]]; then
+    echo "Tasks file not found: $TASKS_FILE"
+    exit 1
+fi
+
+clear
+while true; do
+    clear
+    
+    echo "======================================================================="
+    echo " Ralph Progress Monitor - Change: $CHANGE_NAME"
+    echo "======================================================================="
+    echo ""
+    
+    # Progress bar
+    total=$(grep -c "^- \[" "$TASKS_FILE" 2>/dev/null) || total=0
+    completed=$(grep -c "^- \[x\]" "$TASKS_FILE" 2>/dev/null) || completed=0
+    in_progress=$(grep -c "^- \[\/\]" "$TASKS_FILE" 2>/dev/null) || in_progress=0
+    
+    remaining=$((total - completed - in_progress))
+    
+    if [[ $total -gt 0 ]]; then
+        progress=$((completed * 100 / total))
+        echo " Progress: $completed/$total tasks completed ($progress%)"
+        echo " Status:  $in_progress in progress, $remaining remaining"
+        
+        # Simple progress bar
+        filled=$((completed * 50 / total))
+        bar=$(printf '#%.0s' $(seq 1 $filled))
+        empty=$(printf '.%.0s' $(seq 1 $((50 - filled))))
+        echo "          |$bar$empty|"
+    fi
+    echo ""
+    
+    # Ralph state
+    if [[ -f "$RALPH_STATE" ]]; then
+        echo " Ralph State:"
+        jq -r ' 
+            "   Iteration: \(.iteration)/\(.maxIterations)",
+            "   Active: \(.active)",
+            "   Mode: \(.tasksMode // "N/A")",
+            "   Prompt: \(.completionPromise // "N/A")"
+        ' "$RALPH_STATE" 2>/dev/null || echo "   Unable to read state"
+        echo ""
+    fi
+    
+    # Current task
+    echo " Current Task:"
+    current_task=$(grep -n "^- \[\/\]" "$TASKS_FILE" 2>/dev/null | head -1)
+    if [[ -n "$current_task" ]]; then
+        echo "   $current_task"
+    else
+        # Show next incomplete task
+        next_task=$(grep -n "^- \[ \]" "$TASKS_FILE" 2>/dev/null | head -1)
+        if [[ -n "$next_task" ]]; then
+            echo "   Next: $next_task"
+        else
+            echo "   No current task (idle)"
+        fi
+    fi
+    echo ""
+    
+    # Recent completed tasks (last 3)
+    echo " Recently Completed:"
+    grep "^- \[x\]" "$TASKS_FILE" 2>/dev/null | tail -3 | sed 's/^- \[x\] /   /'
+    echo ""
+    
+    # File status
+    echo " Last Updated: $(stat -c "%y" "$TASKS_FILE" 2>/dev/null | cut -d'.' -f1)"
+    echo ""
+    
+    echo "======================================================================="
+    echo " Press Ctrl+C to exit | Refreshing in 2 seconds..."
+    echo "======================================================================="
+    
+    sleep 2
+done

package/scripts/ralph-run.sh

@@ -1,11 +1,44 @@
 #!/bin/bash
 
 set -e
-trap 'handle_error $?' EXIT
 
 VERSION="1.0.0"
+
+# Add Bun to PATH if installed
+if [[ -d "$HOME/.bun/bin" ]]; then
+    export PATH="$HOME/.bun/bin:$PATH"
+fi
+
 CHANGE_NAME=""
+MAX_ITERATIONS=""
 ERROR_OCCURRED=false
+CLEANUP_IN_PROGRESS=false
+
+# Trap signals for proper cleanup
+cleanup() {
+    # Prevent multiple cleanup calls
+    if [[ "$CLEANUP_IN_PROGRESS" == "true" ]]; then
+        return 0
+    fi
+    CLEANUP_IN_PROGRESS=true
+    
+    local exit_code=$1
+    log_info "Cleaning up..."
+    
+    # NOTE: We do NOT kill ralph/bun processes here because:
+    # 1. Ralph runs synchronously in the foreground
+    # 2. Ctrl+C (SIGINT) naturally propagates to child processes
+    # 3. Using pkill -f "bun" is DANGEROUS - it matches gnome-session-binary!
+    # 4. Using pkill -f "ralph" could kill other user processes
+    # The shell's process group handling ensures clean termination.
+    
+    if [[ $exit_code -ne 0 ]]; then
+        log_error "Script terminated with exit code: $exit_code"
+    fi
+    exit $exit_code
+}
+
+trap 'cleanup $?' EXIT INT TERM QUIT
 
 handle_error() {
     local exit_code=$1
@@ -26,20 +59,22 @@ USAGE:
     ralph-run [OPTIONS]
 
 OPTIONS:
-    --change <name>     Specify the OpenSpec change to execute (default: auto-detect)
-    --verbose, -v       Enable verbose mode for debugging
-    --help, -h          Show this help message
+    --change <name>          Specify the OpenSpec change to execute (default: auto-detect)
+    --max-iterations <n>     Maximum iterations for Ralph loop (default: 50)
+    --verbose, -v            Enable verbose mode for debugging
+    --help, -h               Show this help message
 
 EXAMPLES:
     ralph-run                                    # Auto-detect most recent change
     ralph-run --change my-feature                # Execute specific change
+    ralph-run --max-iterations 100             # Limit loop to 100 iterations
     ralph-run --verbose                          # Run with debug output
 
 PREREQUISITES:
     - Git repository (git init)
     - OpenSpec artifacts created (openspec init, opsx-new, opsx-ff)
+    - ralph CLI installed (npm install -g @th0rgal/ralph-wiggum)
     - opencode CLI installed (npm install -g opencode)
-    - jq CLI installed (apt install jq / brew install jq)
 
 EOF
 }
@@ -51,6 +86,10 @@ parse_arguments() {
                 CHANGE_NAME="$2"
                 shift 2
                 ;;
+            --max-iterations)
+                MAX_ITERATIONS="$2"
+                shift 2
+                ;;
             --verbose|-v)
                 VERBOSE=true
                 shift
@@ -75,12 +114,12 @@ parse_arguments() {
 
 log_verbose() {
     if [[ "$VERBOSE" == true ]]; then
-        echo "[VERBOSE] $*"
+        echo "[VERBOSE] $*" >&2
     fi
 }
 
 log_info() {
-    echo "[INFO] $*"
+    echo "[INFO] $*" >&2
 }
 
 log_error() {
@@ -101,7 +140,15 @@ validate_git_repository() {
 
 validate_dependencies() {
     log_verbose "Validating dependencies..."
-
+    
+    # Check for ralph
+    if ! command -v ralph &> /dev/null; then
+        log_error "ralph CLI not found."
+        log_error "Please install open-ralph-wiggum: npm install -g @th0rgal/ralph-wiggum"
+        exit 1
+    fi
+    log_verbose "Found: ralph"
+    
     # Check for opencode
     if ! command -v opencode &> /dev/null; then
         log_error "opencode CLI not found."
@@ -109,17 +156,7 @@ validate_dependencies() {
         exit 1
     fi
     log_verbose "Found: opencode"
-
-    # Check for jq
-    if ! command -v jq &> /dev/null; then
-        log_error "jq CLI not found."
-        log_error "Please install jq:"
-        log_error "  Ubuntu/Debian: apt install jq"
-        log_error "  macOS: brew install jq"
-        exit 1
-    fi
-    log_verbose "Found: jq"
-
+    
     log_verbose "All dependencies validated"
 }
 
@@ -250,7 +287,16 @@ generate_prd() {
     prd_content+="$OPENSPEC_SPECS"$'\n'$'\n'
     
     prd_content+="## Design"$'\n'$'\n'
-    prd_content+="$OPENSPEC_DESIGN"$'\n'
+    prd_content+="$OPENSPEC_DESIGN"$'\n'$'\n'
+    
+    # Add current task context for Ralph to use in commits
+    local task_context
+    task_context=$(get_current_task_context "$change_dir")
+    
+    if [[ -n "$task_context" ]]; then
+        prd_content+="## Current Task Context"$'\n'$'\n'
+        prd_content+="$task_context"$'\n'$'\n'
+    fi
     
     echo "$prd_content"
 }
@@ -473,22 +519,13 @@ get_git_history() {
 gather_opencode_context() {
     local task_description="$1"
     
-    log_verbose "Gathering opencode context..."
+    log_verbose "Gathering minimal opencode context..."
     
     local context=""
     
     context+="## Task"$'\n'
     context+="$task_description"$'\n'$'\n'
     
-    context+="## Proposal Summary"$'\n'
-    context+="$(echo "$OPENSPEC_PROPOSAL" | head -20)"$'\n'$'\n'
-    
-    context+="## Design Decisions"$'\n'
-    context+="$(echo "$OPENSPEC_DESIGN" | head -30)"$'\n'$'\n'
-    
-    context+="## Specifications"$'\n'
-    context+="$(echo "$OPENSPEC_SPECS" | head -50)"$'\n'$'\n'
-    
     echo "$context"
 }
 
@@ -496,227 +533,357 @@ generate_opencode_prompt() {
     local task_description="$1"
     local ralph_dir="$2"
     
-    log_verbose "Generating opencode prompt..."
+    log_verbose "Generating minimal opencode prompt..."
     
     local context
     context=$(gather_opencode_context "$task_description")
     
     local prompt=""
-    prompt+="You are implementing a task as part of an OpenSpec change."$'\n'$'\n'
+    prompt+="Implement this task:"$'\n'
     prompt+="$context"$'\n'
     
-    prompt+="## Recent Git History"$'\n'
-    local git_history
-    git_history=$(get_git_history 10)
-    if [[ -n "$git_history" ]]; then
-        echo "$git_history" | while IFS='|' read -r hash date author message; do
-            prompt+="- $hash ($date $author): $message"$'\n'
-        done
-    fi
-    prompt+=$'\n'
-    
-    prompt+="## Error History"$'\n'
-    local errors_file="$ralph_dir/errors.md"
-    if [[ -f "$errors_file" ]]; then
-        prompt+="$(cat "$errors_file" | tail -50)"$'\n'
-    else
-        prompt+="(No previous errors)"$'\n'
-    fi
-    prompt+=$'\n'
-    
-    prompt+="## Instructions"$'\n'
-    prompt+="Implement the task above. Use the context provided to understand the requirements and any relevant design decisions."$'\n'
-    prompt+="If there are previous errors, use them to guide your implementation to avoid repeating mistakes."$'\n'
-    
-    local injected_context
-    if injected_context=$(handle_context_injection "$ralph_dir"); then
-        prompt+=$'\n'
-        prompt+="## Injected Context"$'\n'
-        prompt+="$injected_context"$'\n'
-    fi
-    
     echo "$prompt"
 }
 
-execute_opencode() {
-    local prompt="$1"
+sync_tasks_to_ralph() {
+    local change_dir="$1"
+    local ralph_dir="$2"
     
-    log_verbose "Executing opencode CLI..."
+    local tasks_file="$change_dir/tasks.md"
+    local ralph_tasks_file=".ralph/ralph-tasks.md"
+    local old_ralph_tasks_file="$change_dir/.ralph/ralph-tasks.md"
     
-    if ! command -v opencode &> /dev/null; then
-        log_error "opencode CLI not found. Please install opencode."
+    if [[ ! -f "$tasks_file" ]]; then
+        log_error "Tasks file not found: $tasks_file"
         return 1
     fi
     
-    local output
-    output=$(echo "$prompt" | opencode 2>&1)
-    local exit_code=$?
+    local abs_tasks_file=$(realpath "$tasks_file" 2>/dev/null)
     
-    echo "$output"
-    return $exit_code
-}
-
-create_git_commit() {
-    local task_description="$1"
-    
-    log_verbose "Creating git commit..."
+    # Clean up old Ralph tasks file in change directory if exists
+    if [[ -f "$old_ralph_tasks_file" ]]; then
+        log_verbose "Removing old Ralph tasks file from change directory: $old_ralph_tasks_file"
+        rm "$old_ralph_tasks_file"
+    fi
     
-    if ! git diff-index --quiet HEAD --; then
-        git add -A
-        git commit -m "$task_description" 2>&1
-        log_verbose "Git commit created"
+    # Use symlink so Ralph and openspec-apply-change work on the SAME file
+    if [[ -L "$ralph_tasks_file" ]]; then
+        log_verbose "Symlink exists, ensuring it points to correct location"
+        local current_target=$(readlink -f "$ralph_tasks_file" 2>/dev/null || echo "")
+        
+        if [[ "$current_target" != "$abs_tasks_file" ]]; then
+            log_verbose "Updating symlink to point to new change directory"
+            ln -sf "$abs_tasks_file" "$ralph_tasks_file"
+        fi
+    elif [[ -f "$ralph_tasks_file" ]]; then
+        # File exists but is not a symlink - replace with symlink
+        log_verbose "Replacing regular file with symlink to openspec tasks..."
+        rm "$ralph_tasks_file"
+        ln -sf "$abs_tasks_file" "$ralph_tasks_file"
     else
-        log_verbose "No changes to commit"
+        # No file exists - create new symlink
+        log_verbose "Creating symlink from .ralph/ralph-tasks.md to openspec tasks..."
+        ln -sf "$abs_tasks_file" "$ralph_tasks_file"
     fi
+    
+    log_verbose "Symlink configured: $ralph_tasks_file -> $abs_tasks_file"
 }
 
-execute_task_loop() {
-    local ralph_dir="$1"
+create_prompt_template() {
+    local change_dir="$1"
+    local template_file="$2"
     
-    log_info "Starting task execution loop..."
+    log_verbose "Creating custom prompt template..."
     
-    local total_tasks=${#TASKS[@]}
-    log_info "Total tasks to execute: $total_tasks"
+    local abs_change_dir
+    abs_change_dir=$(realpath "$change_dir" 2>/dev/null)
     
-    for i in "${!TASKS[@]}"; do
-        local task_description="${TASKS[$i]}"
-        local task_id="${TASK_IDS[$i]}"
-        
-        log_info "Executing task $((i+1))/$total_tasks: $task_description"
-        
-        local prompt
-        prompt=$(generate_opencode_prompt "$task_description" "$ralph_dir")
-        
-        local output
-        output=$(execute_opencode "$prompt")
-        local exit_code=$?
-        
-        if [[ $exit_code -eq 0 ]]; then
-            log_info "Task completed successfully"
-            create_git_commit "$task_description"
-        else
-            log_error "Task failed with exit code: $exit_code"
-            log_error "Output: $output"
-            break
-        fi
-    done
+    cat > "$template_file" << 'EOF'
+# Ralph Wiggum Task Execution - Iteration {{iteration}} / {{max_iterations}}
+
+Change directory: {{change_dir}}
+
+## OpenSpec Artifacts Context
+
+Include full context from openspec artifacts in {{change_dir}}:
+- Read {{change_dir}}/proposal.md for the overall project goal
+- Read {{change_dir}}/design.md for the technical design approach
+- Read {{change_dir}}/specs/*/spec.md for the detailed specifications
+
+## Task List
+
+{{tasks}}
+
+## Instructions
+
+1. **Identify** current task:
+   - Find any task marked as [/] (in progress)
+   - If no task is in progress, pick the first task marked as [ ] (incomplete)
+   - Mark the task as [/] in the tasks file before starting work
+
+2. **Implement** task using openspec-apply-change:
+   - Use the /opsx-apply skill to implement the current task
+   - Read the relevant openspec artifacts for context (proposal.md, design.md, specs)
+   - Follow the openspec workflow to complete the task
+   - The openspec-apply-change skill will implement changes and update task status automatically
+
+3. **Complete** task:
+   - Verify that the implementation meets the requirements
+   - When the task is successfully completed, mark it as [x] in the tasks file
+   - Output: `<promise>{{task_promise}}</promise>`
+
+4. **Continue** to the next task:
+   - The loop will continue with the next iteration
+   - Find the next incomplete task and repeat the process
+
+## Critical Rules
+
+- Work on ONE task at a time from the task list
+- Use openspec-apply-change (/opsx-apply) for implementation
+- ONLY output `<promise>{{task_promise}}</promise>` when the current task is complete and marked as [x]
+- ONLY output `<promise>{{completion_promise}}</promise>` when ALL tasks are [x]
+- Output promise tags DIRECTLY - do not quote them, explain them, or say you "will" output them
+- Do NOT lie or output false promises to exit the loop
+- If stuck, try a different approach
+- Check your work before claiming completion
+
+## CRITICAL: Git Commit Format (MANDATORY)
+
+When making git commits, you MUST use this EXACT format:
+
+```
+Ralph iteration <N>: <brief description of work completed>
+
+Tasks completed:
+- [x] <task.number> <task description text>
+- [x] <task.number> <task description text>
+...
+```
+
+**Requirements:**
+1. Use iteration number from Ralph's state (e.g., "Ralph iteration 7")
+2. Include a BRIEF description summarizing what was done
+3. List ALL completed tasks with their numbers and full descriptions
+4. Use the EXACT format: "- [x] <task.number> <task description>"
+5. Read the "## Completed Tasks for Git Commit" section from the PRD for the task list
+
+**FORBIDDEN:**
+- DO NOT use generic messages like "work in progress" or "iteration N"
+- DO NOT skip task numbers
+- DO NOT truncate task descriptions
+- DO NOT create commits without task information
+
+**Example:**
+```
+Ralph iteration 7: Implement unit tests for response processing
+
+Tasks completed:
+- [x] 11.6 Write unit test for personality state management
+- [x] 11.7 Write unit test for personality validation
+- [x] 11.8 Write unit test for system prompt validation
+```
+
+{{context}}
+EOF
     
-    log_info "Task execution loop complete"
+    sed -i "s|{{change_dir}}|$abs_change_dir|g" "$template_file"
+    
+    log_verbose "Prompt template created: $template_file"
 }
 
-initialize_tracking() {
-    local ralph_dir="$1"
-    local tracking_file="$ralph_dir/tracking.json"
+restore_ralph_state_from_tasks() {
+    local tasks_file="$1"
+    local ralph_loop_file=".ralph/ralph-loop.state.json"
     
-    log_verbose "Initializing tracking..."
-    
-    if [[ ! -f "$tracking_file" ]]; then
-        log_verbose "Creating tracking.json..."
-        echo '{"tasks":{}}' > "$tracking_file"
+    if [[ ! -f "$ralph_loop_file" ]]; then
+        log_verbose "No Ralph state file found, nothing to restore"
+        return 0
     fi
     
-    echo "$tracking_file"
-}
-
-read_tracking() {
-    local tracking_file="$1"
+    # Read current iteration from state file - don't use completed task count
+    local current_iteration
+    current_iteration=$(jq -r '.iteration // 0' "$ralph_loop_file" 2>/dev/null || echo "0")
     
-    log_verbose "Reading tracking.json..."
+    # Count completed tasks for informational purposes only
+    local completed_count=$(grep -c "^- \[x\]" "$tasks_file" 2>/dev/null || echo "0")
+    log_verbose "Found $completed_count completed tasks in tasks.md (iteration $current_iteration)"
     
-    if [[ -f "$tracking_file" ]]; then
-        cat "$tracking_file"
+    # Read maxIterations from state file
+    local max_iterations
+    max_iterations=$(jq -r '.maxIterations // 50' "$ralph_loop_file" 2>/dev/null || echo "50")
+    
+    # Only update iteration if it's 0 or missing (fresh start)
+    if [[ $current_iteration -eq 0 ]]; then
+        log_verbose "Setting initial iteration to 1 (max: $max_iterations)"
+        local updated_state
+        updated_state=$(jq --argjson state "$(cat "$ralph_loop_file")" '
+            .iteration = 1 |
+            .active = true
+        ' 2>/dev/null)
+        
+        if [[ -n "$updated_state" ]]; then
+            echo "$updated_state" > "$ralph_loop_file"
+        fi
     else
-        echo '{"tasks":{}}'
+        log_verbose "Ralph state preserved at iteration $current_iteration"
     fi
 }
 
-update_task_checkbox() {
+get_current_task_context() {
     local change_dir="$1"
-    local task_id="$2"
-    local complete="$3"
+    local tasks_file="$change_dir/tasks.md"
     
-    log_verbose "Updating task checkbox (line $task_id, complete=$complete)..."
+    if [[ ! -f "$tasks_file" ]]; then
+        echo ""
+        return
+    fi
     
-    local tasks_file="$change_dir/tasks.md"
-    local temp_file=$(mktemp)
+    log_verbose "Reading current task context from tasks.md..."
     
+    local context=""
+    local found_task=false
+    local all_completed_tasks=""
+    local current_task_desc=""
+    
+    while IFS= read -r line; do
+        if [[ "$line" =~ ^-\ \[/\] ]]; then
+            # Found in-progress task - extract description
+            current_task_desc="${line#- [/] }"
+            found_task=true
+            break
+        elif [[ "$line" =~ ^-\ \[\ \] ]] && [[ "$found_task" == "false" ]]; then
+            # Found incomplete task - extract description
+            current_task_desc="${line#- [ ] }"
+            found_task=true
+            break
+        fi
+    done < "$tasks_file"
+    
+    # Also collect all completed tasks for commit message
     local line_number=0
     while IFS= read -r line; do
         ((line_number++)) || true
-        
-        if [[ $line_number -eq $task_id ]]; then
-            if [[ "$complete" == "true" ]]; then
-                echo "${line/- \[ \]/- [x]}" >> "$temp_file"
-            else
-                echo "${line/- \[x\]/- [ ]}" >> "$temp_file"
-            fi
-        else
-            echo "$line" >> "$temp_file"
+        if [[ "$line" =~ ^-\ \[x\] ]]; then
+            # Use the full line as-is to preserve task number and description
+            all_completed_tasks+="$line"$'\n'
         fi
     done < "$tasks_file"
     
-    mv "$temp_file" "$tasks_file"
+    if [[ "$found_task" == "true" ]]; then
+        context="## Current Task"$'\n'
+        context+="- $current_task_desc"$'\n'
+    fi
+    
+    if [[ -n "$all_completed_tasks" ]]; then
+        context+="## Completed Tasks for Git Commit"$'\n'
+        context+="$all_completed_tasks"
+    fi
+    
+    echo "$context"
 }
 
-update_tracking() {
-    local tracking_file="$1"
-    local task_id="$2"
-    local complete="$3"
+setup_output_capture() {
+    local ralph_dir="$1"
     
-    log_verbose "Updating tracking.json (task $task_id, complete=$complete)..."
+    log_verbose "Setting up output capture..."
     
-    local status="pending"
-    if [[ "$complete" == "true" ]]; then
-        status="complete"
-    fi
+    # Create timestamped output directory in /tmp
+    local timestamp=$(date +"%Y%m%d_%H%M%S")
+    local output_dir="/tmp/ralph-run-$timestamp"
     
-    local tracking_json
-    tracking_json=$(cat "$tracking_file")
+    mkdir -p "$output_dir"
+    log_info "Output directory: $output_dir"
     
-    local updated_json
-    updated_json=$(echo "$tracking_json" | jq --arg id "$task_id" --arg status "$status" '.tasks[$id] = {status: $status}' 2>/dev/null || echo '{"tasks":{}}')
+    # Store output directory path in Ralph directory for reference
+    echo "$output_dir" > "$ralph_dir/.output_dir"
     
-    echo "$updated_json" > "$tracking_file"
+    echo "$output_dir"
 }
 
-update_task_status_atomic() {
+cleanup_old_output() {
+    log_verbose "Cleaning up old Ralph output directories..."
+    
+    # Keep last 3 Ralph output directories, delete older ones
+    find /tmp -type d -name "ralph-run-*" -mtime +7d 2>/dev/null | while read old_dir; do
+        log_verbose "Removing old output directory: $old_dir"
+        rm -rf "$old_dir"
+    done
+}
+
+execute_ralph_loop() {
     local change_dir="$1"
-    local task_id="$2"
-    local complete="$3"
-    local tracking_file="$4"
+    local ralph_dir="$2"
+    local max_iterations="${3:-50}"
     
-    log_verbose "Updating task status atomically..."
+    log_info "Starting Ralph Wiggum loop with open-ralph-wiggum..."
+    log_info "Max iterations: $max_iterations"
+    log_info "Change directory: $change_dir"
     
-    local tasks_file="$change_dir/tasks.md"
-    local tasks_backup="${tasks_file}.bak"
-    local tracking_backup="${tracking_file}.bak"
+    if ! command -v ralph &> /dev/null; then
+        log_error "ralph CLI not found."
+        log_error "Please install open-ralph-wiggum: npm install -g @th0rgal/ralph-wiggum"
+        return 1
+    fi
     
-    cp "$tasks_file" "$tasks_backup"
-    cp "$tracking_file" "$tracking_backup"
+    local template_file="$ralph_dir/prompt-template.md"
     
-    update_task_checkbox "$change_dir" "$task_id" "$complete"
-    update_tracking "$tracking_file" "$task_id" "$complete"
+    # Clean up old output directories and setup new one
+    cleanup_old_output
+    local output_dir=$(setup_output_capture "$ralph_dir")
     
-    if [[ ! -f "$tasks_file" ]] || [[ ! -f "$tracking_file" ]]; then
-        log_error "Update failed: files not found"
-        mv "$tasks_backup" "$tasks_file"
-        mv "$tracking_backup" "$tracking_file"
-        return 1
+    sync_tasks_to_ralph "$change_dir" "$ralph_dir"
+    create_prompt_template "$change_dir" "$template_file"
+    
+    # Generate PRD and write to file
+    local prd_content
+    prd_content=$(generate_prd "$change_dir")
+    echo "$prd_content" > "$ralph_dir/PRD.md"
+    
+    # Get current task context for Ralph to use in commits
+    local task_context
+    task_context=$(get_current_task_context "$change_dir")
+    
+    # Create context injection file for Ralph
+    local context_file="$ralph_dir/.context_injection"
+    if [[ -n "$task_context" ]]; then
+        log_verbose "Writing task context injection..."
+        echo "$task_context" > "$context_file"
     fi
     
-    rm "$tasks_backup"
-    rm "$tracking_backup"
+    # Restore Ralph state from tasks.md before running
+    restore_ralph_state_from_tasks "$change_dir/tasks.md"
     
-    log_verbose "Atomic update successful"
-    return 0
+    # Initialize context injections file for Ralph to read context
+    initialize_context_injections "$ralph_dir"
+    
+    # Output files
+    local stdout_log="$output_dir/ralph-stdout.log"
+    local stderr_log="$output_dir/ralph-stderr.log"
+    
+    log_info "Delegating to ralph CLI..."
+    log_info "Capturing output to: $output_dir"
+    
+    # Run Ralph and capture output to both console and files
+    {
+        ralph --prompt-file "$ralph_dir/PRD.md" \
+            --agent opencode \
+            --tasks \
+            --max-iterations "$max_iterations" \
+            --prompt-template "$template_file" \
+            --verbose-tools
+    } > >(tee "$stdout_log") 2> >(tee "$stderr_log")
+    
+    return $?
 }
 
+
+
 main() {
     parse_arguments "$@"
-
+    
     log_verbose "Starting ralph-run v$VERSION"
     log_verbose "Change name: ${CHANGE_NAME:-<auto-detect>}"
-
+    
     validate_git_repository
     validate_dependencies
     
@@ -729,7 +896,6 @@ main() {
     validate_openspec_artifacts "$change_dir"
     validate_script_state "$change_dir"
     local ralph_dir=$(setup_ralph_directory "$change_dir")
-    local tracking_file=$(initialize_tracking "$ralph_dir")
     
     log_info "Change directory: $change_dir"
     log_info "Ralph directory: $ralph_dir"
@@ -743,7 +909,9 @@ main() {
     log_info "PRD generation complete"
     log_info "Found ${#TASKS[@]} tasks to execute"
     
-    execute_task_loop "$ralph_dir"
+    local max_iterations="${MAX_ITERATIONS:-50}"
+    
+    execute_ralph_loop "$change_dir" "$ralph_dir" "$max_iterations"
     
     log_info "ralph-run.sh initialized successfully"
 }