spec-and-loop 1.0.0 → 1.0.1

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.1",
   "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-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)
-    - opencode CLI installed (npm install -g opencode)
-    - jq CLI installed (apt install jq / brew install jq)
+    - ralph CLI installed (npm install -g @th0rgal/ralph-wiggum)
+    - opencode CLI installed (npm install -g opencode-ai)
 
 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,25 +140,23 @@ 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."
-        log_error "Please install opencode: npm install -g opencode"
+        log_error "Please install opencode: npm install -g opencode-ai"
         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"
 }
 
@@ -473,22 +510,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,112 +524,191 @@ 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'
+    echo "$prompt"
+}
+
+sync_tasks_to_ralph() {
+    local change_dir="$1"
+    local ralph_dir="$2"
     
-    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'
+    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 [[ ! -f "$tasks_file" ]]; then
+        log_error "Tasks file not found: $tasks_file"
+        return 1
     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 abs_tasks_file=$(realpath "$tasks_file" 2>/dev/null)
     
-    local injected_context
-    if injected_context=$(handle_context_injection "$ralph_dir"); then
-        prompt+=$'\n'
-        prompt+="## Injected Context"$'\n'
-        prompt+="$injected_context"$'\n'
+    # 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
     
-    echo "$prompt"
+    # 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
+        # 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_opencode() {
-    local prompt="$1"
+create_prompt_template() {
+    local change_dir="$1"
+    local template_file="$2"
     
-    log_verbose "Executing opencode CLI..."
+    log_verbose "Creating custom prompt template..."
     
-    if ! command -v opencode &> /dev/null; then
-        log_error "opencode CLI not found. Please install opencode."
-        return 1
-    fi
+    local abs_change_dir
+    abs_change_dir=$(realpath "$change_dir" 2>/dev/null)
     
-    local output
-    output=$(echo "$prompt" | opencode 2>&1)
-    local exit_code=$?
+    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
+
+{{context}}
+EOF
+    
+    sed -i "s|{{change_dir}}|$abs_change_dir|g" "$template_file"
     
-    echo "$output"
-    return $exit_code
+    log_verbose "Prompt template created: $template_file"
 }
 
-create_git_commit() {
-    local task_description="$1"
+restore_ralph_state_from_tasks() {
+    local tasks_file="$1"
+    local ralph_loop_file=".ralph/ralph-loop.state.json"
     
-    log_verbose "Creating git commit..."
+    if [[ ! -f "$ralph_loop_file" ]]; then
+        log_verbose "No Ralph state file found, nothing to restore"
+        return 0
+    fi
     
-    if ! git diff-index --quiet HEAD --; then
-        git add -A
-        git commit -m "$task_description" 2>&1
-        log_verbose "Git commit created"
-    else
-        log_verbose "No changes to commit"
+    # Count completed tasks in tasks.md
+    local completed_count=$(grep -c "^- \[x\]" "$tasks_file" 2>/dev/null || echo "0")
+    local next_iteration=$((completed_count + 1))
+    log_verbose "Found $completed_count completed tasks in tasks.md, setting iteration to $next_iteration"
+    
+    # Update Ralph state to resume from completed task
+    local updated_state
+    updated_state=$(jq --argjson state "$(cat "$ralph_loop_file")" --arg iter "$next_iteration" '
+        .iteration = $iter |
+        .active = true
+    ' 2>/dev/null)
+    
+    if [[ -n "$updated_state" ]]; then
+        log_verbose "Updated Ralph state: iteration set to $next_iteration"
+        echo "$updated_state" > "$ralph_loop_file"
     fi
 }
 
-execute_task_loop() {
-    local ralph_dir="$1"
+execute_ralph_loop() {
+    local change_dir="$1"
+    local ralph_dir="$2"
+    local tasks_file="$change_dir/tasks.md"
+    local max_iterations="${3:-50}"
     
-    log_info "Starting task execution loop..."
+    log_info "Starting Ralph Wiggum loop with open-ralph-wiggum..."
+    log_info "Max iterations: $max_iterations"
+    log_info "Change directory: $change_dir"
     
-    local total_tasks=${#TASKS[@]}
-    log_info "Total tasks to execute: $total_tasks"
+    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
     
-    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
+    local template_file="$ralph_dir/prompt-template.md"
     
-    log_info "Task execution loop complete"
+    sync_tasks_to_ralph "$change_dir" "$ralph_dir"
+    create_prompt_template "$change_dir" "$template_file"
+    
+    local prd_content
+    prd_content=$(generate_prd "$change_dir")
+    
+    # Restore Ralph state from tasks.md before running
+    restore_ralph_state_from_tasks "$tasks_file"
+    
+    log_info "Delegating to ralph CLI..."
+    ralph "$prd_content" \
+        --agent opencode \
+        --tasks \
+        --max-iterations "$max_iterations" \
+        --prompt-template "$template_file" \
+        --verbose-tools
+    
+    return $?
 }
 
 initialize_tracking() {
@@ -743,7 +850,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"
 }

package/scripts/setup.js

@@ -37,7 +37,7 @@ console.log('  ralph-run --change <name>       # Run ralph loop');
 console.log('  ralph-run                       # Auto-detect change');
 console.log('');
 console.log('Prerequisites:');
-console.log('  - openspec CLI: npm install -g openspec');
-console.log('  - opencode CLI: npm install -g opencode');
+console.log('  - openspec CLI: npm install -g @fission-ai/openspec@latest');
+console.log('  - opencode CLI: npm install -g opencode-ai (or see https://opencode.ai/install)');
 console.log('  - jq CLI: apt install jq / brew install jq');
 console.log('  - git: git init');