spec-and-loop 1.0.0

package/QUICKSTART.md

@@ -0,0 +1,236 @@
+# Quick Start Guide
+
+Get up and running with **spec-and-loop** in 5 minutes!
+
+## Prerequisites
+
+Install these tools (one-time setup):
+
+```bash
+# 1. Install openspec (OpenSpec CLI)
+npm install -g openspec
+
+# 2. Install opencode (agentic coding assistant)
+npm install -g opencode
+
+# 3. Install jq (command-line JSON processor)
+# Ubuntu/Debian:
+sudo apt install jq
+
+# macOS:
+brew install jq
+
+# 4. Git (if not already installed)
+git init
+```
+
+## Installation
+
+```bash
+npm install -g spec-and-loop
+```
+
+**Prerequisites:** Install openspec and opencode:
+```bash
+npm install -g openspec opencode
+```
+
+## Quick Demo (5 Minutes)
+
+```bash
+# 1. Create a test project
+mkdir demo-project
+cd demo-project
+git init
+
+# 2. Initialize OpenSpec
+openspec init
+
+# 3. Create a new change
+opsx-new add-hello-world
+
+# 4. Fast-forward through artifact creation
+opsx-ff
+
+# 5. Run the ralph loop (executes tasks with opencode)
+ralph-run --change add-hello-world
+```
+
+**That's it!** The script will:
+- Read your OpenSpec artifacts (proposal, specs, design, tasks)
+- Execute each task with full context using opencode
+- Create a git commit after each task
+- Track progress in tasks.md
+
+## What Just Happened?
+
+1. **Created a spec** with OpenSpec
+   - `proposal.md`: Why you're adding this feature
+   - `specs/*/spec.md`: Detailed requirements
+   - `design.md`: Technical decisions
+   - `tasks.md`: Implementation tasks as checkboxes
+
+2. **Executed tasks** with opencode
+   - Each task got full context (proposal + specs + design + git history)
+   - Git commits created after each task
+   - Task checkboxes marked as complete
+
+3. **Iterated** until all tasks done
+   - Errors from previous tasks inform subsequent tasks
+   - Each task builds on the previous commit
+   - Full granular git history
+
+## Verify Your Work
+
+```bash
+# Check the git history (one commit per task!)
+git log --oneline
+
+# See the change files
+ls -la openspec/changes/add-hello-world/
+
+# View the generated PRD (internal use)
+cat openspec/changes/add-hello-world/.ralph/PRD.md
+```
+
+## Common Commands
+
+### OpenSpec Commands
+
+```bash
+openspec init                  # Initialize in current directory
+openspec new <name>             # Start a new change
+openspec continue <name>         # Continue working on change
+openspec ff <name>              # Fast-forward artifact creation
+openspec apply <name>           # Apply change (implementation)
+openspec archive <name>          # Archive completed change
+```
+
+### Ralph Loop Commands
+
+```bash
+ralph-run                      # Auto-detect most recent change and run
+ralph-run --change <name>      # Run for specific change
+ralph-run --verbose            # Run with debug output
+ralph-run --help                # Show help message
+```
+
+## Real-World Example
+
+```bash
+# 1. Initialize in your project
+cd my-web-app
+git init
+openspec init
+
+# 2. Create a feature
+openspec new user-authentication
+
+# 3. Go through the workflow
+# - Create proposal: Why add auth?
+# - Create specs: Login flow, password reset, OAuth
+# - Create design: Use JWT, store hashed passwords
+# - Create tasks: 15 checkboxes for implementation
+
+# 4. Fast-forward to create all artifacts
+openspec ff user-authentication
+
+# 5. Execute the implementation
+ralph-run --change user-authentication
+
+# 6. Watch the magic happen!
+# [INFO] Found 15 tasks to execute
+# [INFO] Executing task 1/15: Create User model
+# ✓ Complete
+# [INFO] Executing task 2/15: Implement password hashing
+# ✓ Complete
+# ...
+
+# 7. Verify the implementation
+git log --oneline      # 15 commits, one per task
+git diff HEAD~15        # See full implementation
+```
+
+## Troubleshooting
+
+### "openspec CLI not found" or "opencode CLI not found"
+
+```bash
+npm install -g openspec opencode
+```
+
+### "jq CLI not found"
+
+```bash
+# Ubuntu/Debian
+sudo apt install jq
+
+# macOS
+brew install jq
+```
+
+### "Not a git repository"
+
+```bash
+git init
+```
+
+### "command not found: ralph-run"
+
+**Problem:** npm bin directory not in PATH
+
+**Solution:**
+```bash
+# Add to ~/.bashrc or ~/.zshrc
+export PATH="$PATH:$(npm root -g)/.bin"
+
+# Reload shell
+source ~/.bashrc
+```
+
+### "No tasks to execute"
+
+**Problem:** All tasks already complete!
+
+**Solution:**
+```bash
+# Check tasks.md
+grep "^\- \[x\]" openspec/changes/my-feature/tasks.md
+
+# Or create a new change
+opsx-new another-feature
+```
+
+## Features at a Glance
+
+| Feature | Description |
+|---------|-------------|
+| **Structured Planning** | OpenSpec workflow: proposal → specs → design → tasks |
+| **Agentic Execution** | opencode executes tasks with full context |
+| **Iterative Loop** | Each task builds on previous commits |
+| **Error Propagation** | Failures inform subsequent tasks |
+| **Granular History** | One git commit per task |
+| **Auto-Resume** | Interrupted? Run again—picks up where left off |
+| **Context Injection** | Inject custom instructions during execution |
+
+## Next Steps
+
+1. **Read the full README.md** for detailed documentation
+2. **Try a real feature** in your project
+3. **Explore the .ralph/** directory to see internal state
+4. **Check out .hidden/** directory for advanced guides
+
+## Resources
+
+- [Full README](./README.md) - Comprehensive documentation
+- [OpenSpec](https://openspec.ai) - Specification workflow
+- [opencode](https://opencode.ai) - Agentic coding assistant
+- [open-ralph-wiggum](https://github.com/Th0rgal/open-ralph-wiggum) - Iterative execution loop
+
+## Need Help?
+
+- Check the **Troubleshooting** section above
+- Review the **Full README.md** for detailed info
+- Check **.hidden/** directory for advanced guides
+
+Happy coding! 🚀

package/README.md

@@ -0,0 +1,344 @@
+# Spec and Loop
+
+OpenSpec + Ralph Loop integration for iterative development with opencode.
+
+**[🚀 Quick Start Guide](./QUICKSTART.md)** - Get up and running in 5 minutes!
+
+## Why This Exists
+
+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:
+
+```bash
+npm install -g openspec opencode
+```
+
+## Quick Start
+
+**[🚀 Get Started in 5 Minutes](./QUICKSTART.md)**
+
+```bash
+# 1. Initialize OpenSpec in your project
+openspec init
+
+# 2. Create a new change
+openspec new add-user-auth
+
+# 3. Fast-forward through artifact creation
+openspec ff add-user-auth
+
+# 4. Run the ralph loop (executes tasks with opencode)
+ralph-run --change add-user-auth
+```
+
+For detailed step-by-step instructions, see [QUICKSTART.md](./QUICKSTART.md).
+
+## Quick Start
+
+```bash
+# 1. Initialize OpenSpec in your project
+openspec init
+
+# 2. Create a new change
+openspec new add-user-auth
+
+# 3. Fast-forward through artifact creation
+openspec ff add-user-auth
+
+# 4. Run the ralph loop (executes tasks with opencode)
+ralph-run --change add-user-auth
+```
+
+Or auto-detect the most recent change:
+
+```bash
+ralph-run
+```
+
+## Prerequisites
+
+Before using spec-and-loop, ensure you have:
+
+1. **Node.js & npm** - For package installation
+   ```bash
+   node --version  # Should be 14+
+   npm --version   # Should be 6+
+   ```
+
+2. **openspec** - OpenSpec CLI for specification workflow
+   ```bash
+   npm install -g openspec
+   ```
+
+3. **opencode** - Agentic coding assistant
+   ```bash
+   npm install -g opencode
+   ```
+
+4. **jq** - Command-line JSON processor
+   ```bash
+   # Ubuntu/Debian
+   sudo apt install jq
+
+   # macOS
+   brew install jq
+   ```
+
+5. **git** - Version control (for commits per task)
+   ```bash
+   git init
+   ```
+
+For complete installation instructions, see [QUICKSTART.md](./QUICKSTART.md).
+
+## Commands
+
+### OpenSpec Commands
+
+- `openspec init` - Initialize OpenSpec in current directory
+- `openspec new <name>` - Start a new change
+- `openspec ff <name>` - Fast-forward artifact creation
+- `openspec continue <name>` - Continue working on change
+- `openspec apply <name>` - Apply change (implementation)
+- `openspec archive <name>` - Archive a completed change
+
+### Ralph Loop Commands
+
+- `ralph-run --change <name>` - Run the ralph loop for a specific change
+- `ralph-run` - Auto-detect most recent change and run
+
+## How It Works
+
+### Step 1: Create Spec with OpenSpec
+
+```bash
+openspec new my-feature
+openspec ff my-feature
+```
+
+This creates:
+- **proposal.md**: Why you're making this change
+- **specs/<capability>/spec.md**: Detailed requirements for each capability
+- **design.md**: Technical decisions and architecture
+- **tasks.md**: Implementation tasks as checkboxes
+
+**Example tasks.md:**
+```markdown
+## Implementation
+
+- [ ] Create database schema
+- [ ] Implement API endpoints
+- [ ] Write unit tests
+- [ ] Add documentation
+```
+
+### Step 2: Run Ralph Loop
+
+```bash
+ralph-run --change my-feature
+```
+
+**What happens:**
+
+1. **Validation**: Checks for required OpenSpec artifacts
+2. **PRD Generation**: Converts proposal + specs + design → PRD format (for internal use)
+3. **Task Execution**: For each incomplete task:
+   - Generates context-rich prompt (task + specs + design + git history + errors)
+   - Runs `opencode` with the prompt
+   - Creates git commit with task description
+   - Marks task complete in tasks.md
+4. **Completion**: All tasks done, errors cleared
+
+### Step 3: Monitor Progress
+
+```bash
+# Check remaining tasks
+grep "^- \[ \]" openspec/changes/my-feature/tasks.md
+
+# View git commits
+git log --oneline
+
+# See errors (if any failed)
+cat openspec/changes/my-feature/.ralph/errors.md
+```
+
+## Example Workflow
+
+```bash
+# 1. Plan feature with OpenSpec
+openspec new user-auth
+openspec ff user-auth
+
+# 2. Execute with Ralph
+ralph-run --change user-auth
+
+# Output:
+# [INFO] Found 15 tasks to execute
+# [INFO] Executing task 1/15: Create User model with password field
+# ✓ Complete
+# [INFO] Executing task 2/15: Implement password hashing
+# ✓ Complete
+# ...
+
+# 3. Verify implementation
+git log --oneline  # 15 commits, one per task
+git diff HEAD~15   # See full implementation
+```
+
+## Features at a Glance
+
+| Feature | Description |
+|---------|-------------|
+| **Structured Planning** | OpenSpec workflow: proposal → specs → design → tasks |
+| **Agentic Execution** | opencode executes tasks with full context |
+| **Iterative Loop** | Each task builds on previous commits |
+| **Error Propagation** | Failures inform subsequent tasks |
+| **Granular History** | One git commit per task |
+| **Auto-Resume** | Interrupted? Run again—picks up where left off |
+| **Context Injection** | Inject custom instructions during execution |
+
+For detailed feature descriptions, see below.
+
+## Features
+
+### Ralph Wiggum + Agentic Coding
+
+- **Iterative refinement**: Each task builds on previous commits with full context
+- **Error propagation**: Failures inform subsequent iterations—don't repeat mistakes
+- **Granular history**: Commit per task makes debugging and rollback easy
+- **Context awareness**: AI sees proposal, specs, design, git history, and errors
+
+### OpenSpec + opencode Synergy
+
+| OpenSpec | opencode | Together |
+|----------|----------|----------|
+| Structured planning | Agentic execution | Plan → Execute loop |
+| Human-readable specs | AI-understandable context | Full context propagation |
+| Task breakdown | Task implementation | Automatable workflow |
+
+### Script Features
+
+- **Auto-resume**: Interrupted? Run again—picks up where left off
+- **Context injection**: Inject custom instructions during execution
+- **Error recovery**: Errors propagate to guide subsequent tasks
+- **Bidirectional tracking**: Tasks.md and .ralph/tracking.json stay synced
+- **Idempotent**: Run multiple times safely
+
+## Advanced Usage
+
+### Context Injection
+
+Inject custom instructions during execution:
+
+```bash
+# Create injection file
+echo "Use Redis instead of Memcached" > openspec/changes/my-feature/.ralph/.context_injection
+
+# Next opencode invocation includes:
+## Injected Context
+Use Redis instead of Memcached
+```
+
+### Verbose Mode
+
+For debugging:
+
+```bash
+ralph-run --verbose --change my-feature
+```
+
+### View Generated PRD
+
+```bash
+cat openspec/changes/my-feature/.ralph/PRD.md
+```
+
+### Manually Inject Context
+
+```bash
+echo "Consider performance implications" > openspec/changes/my-feature/.ralph/.context_injection
+```
+
+## Architecture
+
+This package integrates:
+- **OpenSpec**: Structured specification workflow
+- **opencode**: Agentic coding assistant for task execution
+- **Ralph Loop**: Iterative development with commits per task, error tracking
+
+### Context Propagation
+
+Each task execution includes:
+- **Task description**: What to implement
+- **Proposal summary**: Why this change matters
+- **Relevant specs**: Requirements to satisfy
+- **Design decisions**: Architectural constraints
+- **Git history**: Last 10 commits (what's already done)
+- **Previous errors**: What failed before (to avoid repeating)
+
+### Task Tracking
+
+Bidirectional synchronization:
+- **tasks.md**: Human-readable checkboxes `[ ]` → `[x]`
+- **.ralph/tracking.json**: Machine-readable state
+- **Atomic updates**: Both succeed or both fail
+- **Stable IDs**: Line numbers persist across script runs
+
+### File Structure
+
+```
+openspec/changes/<name>/
+├── proposal.md          # Your "why"
+├── design.md            # Your "how"
+├── tasks.md             # Your "what" (checkboxes)
+└── specs/               # Your requirements
+    ├── auth/
+    │   └── spec.md
+    └── api/
+        └── spec.md
+└── .ralph/             # Internal state (auto-generated)
+    ├── PRD.md                    # Generated from artifacts
+    ├── tracking.json             # Task completion state
+    ├── errors.md                 # Failure history
+    ├── context-injections.md      # Manual injections log
+    └── .context_injection        # Pending injection
+```
+
+## Troubleshooting
+
+For common issues and solutions, see [QUICKSTART.md#troubleshooting](./QUICKSTART.md#troubleshooting).
+
+**Quick fixes:**
+
+```bash
+# opencode not found?
+npm install -g opencode
+
+# jq not found?
+sudo apt install jq  # or: brew install jq
+
+# Not a git repository?
+git init
+
+# command not found: ralph-run?
+export PATH="$PATH:$(npm root -g)/.bin"
+```
+
+## Resources
+
+- [OpenSpec](https://openspec.ai) - Structured specification workflow
+- [open-ralph-wiggum](https://github.com/Th0rgal/open-ralph-wiggum) - Iterative execution loop
+- [opencode](https://opencode.ai) - Agentic coding assistant
+
+## License
+
+MIT

package/bin/ralph-run

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+
+const path = require('path');
+const { execSync } = require('child_process');
+
+const scriptPath = path.join(__dirname, '..', 'scripts', 'ralph-run.sh');
+const args = process.argv.slice(2).map(arg => `"${arg.replace(/"/g, '\\"')}"`).join(' ');
+
+try {
+  execSync(`bash "${scriptPath}" ${args}`, { stdio: 'inherit' });
+} catch (err) {
+  process.exit(err.status || 1);
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "spec-and-loop",
+  "version": "1.0.0",
+  "description": "OpenSpec + Ralph Loop integration for iterative development with opencode",
+  "main": "index.js",
+  "bin": {
+    "ralph-run": "./bin/ralph-run"
+  },
+  "scripts": {
+    "postinstall": "node scripts/setup.js"
+  },
+  "dependencies": {
+    "openspec": "^1.0.0"
+  },
+  "keywords": [
+    "openspec",
+    "ralph-wiggum",
+    "opencode",
+    "iterative-development",
+    "agentic-coding"
+  ],
+  "author": "",
+  "license": "GPL-3.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ncheaz/spec-and-loop.git"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "README.md",
+    "QUICKSTART.md"
+  ],
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "os": [
+    "darwin",
+    "linux"
+  ]
+}

package/scripts/ralph-run.sh

@@ -0,0 +1,751 @@
+#!/bin/bash
+
+set -e
+trap 'handle_error $?' EXIT
+
+VERSION="1.0.0"
+CHANGE_NAME=""
+ERROR_OCCURRED=false
+
+handle_error() {
+    local exit_code=$1
+    if [[ $exit_code -ne 0 ]]; then
+        ERROR_OCCURRED=true
+        log_error "Script failed with exit code: $exit_code"
+        log_error "Use --verbose flag for more debugging information"
+    fi
+}
+VERBOSE=false
+SHOW_HELP=false
+
+usage() {
+    cat << EOF
+ralph-run - OpenSpec + Ralph Loop integration for iterative development with opencode
+
+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
+
+EXAMPLES:
+    ralph-run                                    # Auto-detect most recent change
+    ralph-run --change my-feature                # Execute specific change
+    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)
+
+EOF
+}
+
+parse_arguments() {
+    while [[ $# -gt 0 ]]; do
+        case $1 in
+            --change)
+                CHANGE_NAME="$2"
+                shift 2
+                ;;
+            --verbose|-v)
+                VERBOSE=true
+                shift
+                ;;
+            --help|-h)
+                SHOW_HELP=true
+                shift
+                ;;
+            *)
+                echo "Error: Unknown option: $1"
+                usage
+                exit 1
+                ;;
+        esac
+    done
+
+    if [[ "$SHOW_HELP" == true ]]; then
+        usage
+        exit 0
+    fi
+}
+
+log_verbose() {
+    if [[ "$VERBOSE" == true ]]; then
+        echo "[VERBOSE] $*"
+    fi
+}
+
+log_info() {
+    echo "[INFO] $*"
+}
+
+log_error() {
+    echo "[ERROR] $*" >&2
+}
+
+validate_git_repository() {
+    log_verbose "Validating git repository..."
+
+    if ! git rev-parse --git-dir > /dev/null 2>&1; then
+        log_error "Not a git repository. Please run this script within a git repository."
+        log_error "Run: git init"
+        exit 1
+    fi
+
+    log_verbose "Git repository validated"
+}
+
+validate_dependencies() {
+    log_verbose "Validating dependencies..."
+
+    # 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"
+        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"
+}
+
+validate_openspec_artifacts() {
+    local change_dir="$1"
+    
+    log_verbose "Validating OpenSpec artifacts..."
+    
+    local required_files=(
+        "proposal.md"
+        "tasks.md"
+        "design.md"
+    )
+    
+    for file in "${required_files[@]}"; do
+        if [[ ! -f "$change_dir/$file" ]]; then
+            log_error "Required artifact not found: $file"
+            exit 1
+        fi
+        log_verbose "Found artifact: $file"
+    done
+    
+    if [[ ! -d "$change_dir/specs" ]]; then
+        log_error "Required directory not found: specs/"
+        exit 1
+    fi
+    log_verbose "Found directory: specs/"
+    
+    log_info "All OpenSpec artifacts validated"
+}
+
+setup_ralph_directory() {
+    local change_dir="$1"
+    local ralph_dir="$change_dir/.ralph"
+    
+    log_verbose "Setting up .ralph directory..."
+    
+    if [[ ! -d "$ralph_dir" ]]; then
+        mkdir -p "$ralph_dir"
+        log_verbose "Created .ralph directory: $ralph_dir"
+    fi
+    
+    echo "$ralph_dir"
+}
+
+auto_detect_change() {
+    local changes_dir="openspec/changes"
+    
+    if [[ ! -d "$changes_dir" ]]; then
+        log_error "OpenSpec changes directory not found: $changes_dir"
+        exit 1
+    fi
+    
+    log_verbose "Auto-detecting most recently modified change..."
+    
+    local latest_change=""
+    local latest_time=0
+    
+    for change_dir in "$changes_dir"/*; do
+        if [[ -d "$change_dir" ]]; then
+            local tasks_file="$change_dir/tasks.md"
+            if [[ -f "$tasks_file" ]]; then
+                local mod_time=$(stat -c %Y "$tasks_file" 2>/dev/null || echo 0)
+                if [[ $mod_time -gt $latest_time ]]; then
+                    latest_time=$mod_time
+                    latest_change=$(basename "$change_dir")
+                fi
+            fi
+        fi
+    done
+    
+    if [[ -z "$latest_change" ]]; then
+        log_error "No changes found with tasks.md in $changes_dir"
+        exit 1
+    fi
+    
+    log_verbose "Auto-detected change: $latest_change"
+    printf "%s" "$latest_change"
+}
+
+read_openspec_artifacts() {
+    local change_dir="$1"
+    
+    log_verbose "Reading OpenSpec artifacts..."
+    
+    local proposal_content=""
+    local specs_content=""
+    local design_content=""
+    
+    if [[ -f "$change_dir/proposal.md" ]]; then
+        proposal_content=$(cat "$change_dir/proposal.md")
+        log_verbose "Read proposal.md"
+    fi
+    
+    if [[ -d "$change_dir/specs" ]]; then
+        while IFS= read -r -d '' spec_file; do
+            local spec_name=$(basename "$(dirname "$spec_file")")
+            specs_content+="$spec_name/spec.md"$'\n'
+            specs_content+="$(cat "$spec_file")"$'\n'$'\n'
+            log_verbose "Read spec: $spec_name/spec.md"
+        done < <(find "$change_dir/specs" -name "spec.md" -print0 | sort -z)
+    fi
+    
+    if [[ -f "$change_dir/design.md" ]]; then
+        design_content=$(cat "$change_dir/design.md")
+        log_verbose "Read design.md"
+    fi
+    
+    declare -g OPENSPEC_PROPOSAL="$proposal_content"
+    declare -g OPENSPEC_SPECS="$specs_content"
+    declare -g OPENSPEC_DESIGN="$design_content"
+}
+
+generate_prd() {
+    local change_dir="$1"
+    
+    log_verbose "Generating PRD from OpenSpec artifacts..."
+    
+    local prd_content=""
+    
+    prd_content+="# Product Requirements Document"$'\n'$'\n'
+    prd_content+="*Generated from OpenSpec artifacts*"$'\n'$'\n'
+    
+    prd_content+="## Proposal"$'\n'$'\n'
+    prd_content+="$OPENSPEC_PROPOSAL"$'\n'$'\n'
+    
+    prd_content+="## Specifications"$'\n'$'\n'
+    prd_content+="$OPENSPEC_SPECS"$'\n'$'\n'
+    
+    prd_content+="## Design"$'\n'$'\n'
+    prd_content+="$OPENSPEC_DESIGN"$'\n'
+    
+    echo "$prd_content"
+}
+
+write_prd() {
+    local ralph_dir="$1"
+    local prd_content="$2"
+    
+    log_verbose "Writing PRD.md to .ralph/ directory..."
+    
+    echo "$prd_content" > "$ralph_dir/PRD.md"
+    
+    log_verbose "PRD.md written to $ralph_dir/PRD.md"
+}
+
+parse_tasks() {
+    local change_dir="$1"
+    local tasks_file="$change_dir/tasks.md"
+    
+    log_verbose "Parsing tasks from tasks.md..."
+    
+    declare -g TASKS=()
+    declare -g TASK_IDS=()
+    declare -g TASKS_MD5=""
+    
+    if [[ -f "$tasks_file" ]]; then
+        TASKS_MD5=$(md5sum "$tasks_file" | cut -d' ' -f1)
+    fi
+    
+    log_verbose "Parsing tasks from tasks.md..."
+    
+    declare -g TASKS=()
+    declare -g TASK_IDS=()
+    
+    local line_number=0
+    while IFS= read -r line; do
+        ((line_number++)) || true
+        
+        if [[ "$line" == "- [ ]"* ]]; then
+            local task_desc="${line#- [ ] }"
+            TASKS+=("$task_desc")
+            TASK_IDS+=("$line_number")
+            log_verbose "Found incomplete task (line $line_number): $task_desc"
+        fi
+    done < "$tasks_file"
+    
+    log_verbose "Found ${#TASKS[@]} incomplete tasks"
+}
+
+check_tasks_modified() {
+    local change_dir="$1"
+    local original_md5="$2"
+    local tasks_file="$change_dir/tasks.md"
+    
+    if [[ ! -f "$tasks_file" ]]; then
+        return 1
+    fi
+    
+    local current_md5
+    current_md5=$(md5sum "$tasks_file" | cut -d' ' -f1)
+    
+    if [[ "$current_md5" != "$original_md5" ]]; then
+        return 0
+    fi
+    
+    return 1
+}
+
+format_error_entry() {
+    local task_id="$1"
+    local task_description="$2"
+    local error_output="$3"
+    
+    local timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+    
+    echo "---"
+    echo "Timestamp: $timestamp"
+    echo "Task ID: $task_id"
+    echo "Task: $task_description"
+    echo ""
+    echo "Error Output:"
+    echo "$error_output"
+    echo ""
+}
+
+append_error() {
+    local ralph_dir="$1"
+    local task_id="$2"
+    local task_description="$3"
+    local error_output="$4"
+    
+    local errors_file="$ralph_dir/errors.md"
+    
+    log_verbose "Appending error to errors.md..."
+    
+    local error_entry
+    error_entry=$(format_error_entry "$task_id" "$task_description" "$error_output")
+    
+    echo "$error_entry" >> "$errors_file"
+}
+
+read_errors() {
+    local ralph_dir="$1"
+    local limit="${2:-10}"
+    
+    local errors_file="$ralph_dir/errors.md"
+    
+    if [[ ! -f "$errors_file" ]]; then
+        return 0
+    fi
+    
+    log_verbose "Reading errors from errors.md..."
+    
+    tail -n "$limit" "$errors_file"
+}
+
+clear_errors() {
+    local ralph_dir="$1"
+    
+    local errors_file="$ralph_dir/errors.md"
+    
+    if [[ -f "$errors_file" ]]; then
+        rm "$errors_file"
+        log_verbose "Cleared errors.md"
+    fi
+}
+
+archive_errors() {
+    local ralph_dir="$1"
+    
+    local errors_file="$ralph_dir/errors.md"
+    
+    if [[ ! -f "$errors_file" ]]; then
+        return 0
+    fi
+    
+    local timestamp=$(date -u +"%Y%m%d_%H%M%S")
+    local archive_file="$ralph_dir/errors_${timestamp}.md"
+    
+    cp "$errors_file" "$archive_file"
+    log_verbose "Archived errors to $archive_file"
+}
+
+handle_context_injection() {
+    local ralph_dir="$1"
+    
+    local injection_file="$ralph_dir/.context_injection"
+    
+    if [[ -f "$injection_file" ]]; then
+        local injected_context
+        injected_context=$(cat "$injection_file")
+        rm "$injection_file"
+        echo "$injected_context"
+        return 0
+    fi
+    
+    return 1
+}
+
+initialize_context_injections() {
+    local ralph_dir="$1"
+    
+    local injections_file="$ralph_dir/context-injections.md"
+    
+    if [[ ! -f "$injections_file" ]]; then
+        echo "# Context Injections" > "$injections_file"
+        echo "" >> "$injections_file"
+        log_verbose "Created context-injections.md"
+    fi
+}
+
+validate_script_state() {
+    local change_dir="$1"
+    
+    log_verbose "Validating script state..."
+    
+    local required_dirs=(
+        ".ralph"
+    )
+    
+    for dir in "${required_dirs[@]}"; do
+        if [[ ! -d "$change_dir/$dir" ]]; then
+            log_verbose "Required directory not found: $dir (will be created)"
+        fi
+    done
+    
+    local required_files=(
+        "tasks.md"
+        "proposal.md"
+        "design.md"
+    )
+    
+    for file in "${required_files[@]}"; do
+        if [[ ! -f "$change_dir/$file" ]]; then
+            log_error "Required file not found: $file"
+            return 1
+        fi
+    done
+    
+    log_verbose "Script state validated"
+    return 0
+}
+
+get_git_history() {
+    local limit="${1:-10}"
+    
+    log_verbose "Retrieving git history (last $limit commits)..."
+    
+    local git_history=""
+    git_history=$(git log -n "$limit" --pretty=format:"%h|%ad|%an|%s" --date=iso 2>/dev/null || echo "")
+    
+    if [[ -z "$git_history" ]]; then
+        log_verbose "No git history found"
+        return
+    fi
+    
+    echo "$git_history"
+}
+
+gather_opencode_context() {
+    local task_description="$1"
+    
+    log_verbose "Gathering 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"
+}
+
+generate_opencode_prompt() {
+    local task_description="$1"
+    local ralph_dir="$2"
+    
+    log_verbose "Generating 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+="$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"
+    
+    log_verbose "Executing opencode CLI..."
+    
+    if ! command -v opencode &> /dev/null; then
+        log_error "opencode CLI not found. Please install opencode."
+        return 1
+    fi
+    
+    local output
+    output=$(echo "$prompt" | opencode 2>&1)
+    local exit_code=$?
+    
+    echo "$output"
+    return $exit_code
+}
+
+create_git_commit() {
+    local task_description="$1"
+    
+    log_verbose "Creating git commit..."
+    
+    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"
+    fi
+}
+
+execute_task_loop() {
+    local ralph_dir="$1"
+    
+    log_info "Starting task execution loop..."
+    
+    local total_tasks=${#TASKS[@]}
+    log_info "Total tasks to execute: $total_tasks"
+    
+    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
+    
+    log_info "Task execution loop complete"
+}
+
+initialize_tracking() {
+    local ralph_dir="$1"
+    local tracking_file="$ralph_dir/tracking.json"
+    
+    log_verbose "Initializing tracking..."
+    
+    if [[ ! -f "$tracking_file" ]]; then
+        log_verbose "Creating tracking.json..."
+        echo '{"tasks":{}}' > "$tracking_file"
+    fi
+    
+    echo "$tracking_file"
+}
+
+read_tracking() {
+    local tracking_file="$1"
+    
+    log_verbose "Reading tracking.json..."
+    
+    if [[ -f "$tracking_file" ]]; then
+        cat "$tracking_file"
+    else
+        echo '{"tasks":{}}'
+    fi
+}
+
+update_task_checkbox() {
+    local change_dir="$1"
+    local task_id="$2"
+    local complete="$3"
+    
+    log_verbose "Updating task checkbox (line $task_id, complete=$complete)..."
+    
+    local tasks_file="$change_dir/tasks.md"
+    local temp_file=$(mktemp)
+    
+    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"
+        fi
+    done < "$tasks_file"
+    
+    mv "$temp_file" "$tasks_file"
+}
+
+update_tracking() {
+    local tracking_file="$1"
+    local task_id="$2"
+    local complete="$3"
+    
+    log_verbose "Updating tracking.json (task $task_id, complete=$complete)..."
+    
+    local status="pending"
+    if [[ "$complete" == "true" ]]; then
+        status="complete"
+    fi
+    
+    local tracking_json
+    tracking_json=$(cat "$tracking_file")
+    
+    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":{}}')
+    
+    echo "$updated_json" > "$tracking_file"
+}
+
+update_task_status_atomic() {
+    local change_dir="$1"
+    local task_id="$2"
+    local complete="$3"
+    local tracking_file="$4"
+    
+    log_verbose "Updating task status atomically..."
+    
+    local tasks_file="$change_dir/tasks.md"
+    local tasks_backup="${tasks_file}.bak"
+    local tracking_backup="${tracking_file}.bak"
+    
+    cp "$tasks_file" "$tasks_backup"
+    cp "$tracking_file" "$tracking_backup"
+    
+    update_task_checkbox "$change_dir" "$task_id" "$complete"
+    update_tracking "$tracking_file" "$task_id" "$complete"
+    
+    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
+    fi
+    
+    rm "$tasks_backup"
+    rm "$tracking_backup"
+    
+    log_verbose "Atomic update successful"
+    return 0
+}
+
+main() {
+    parse_arguments "$@"
+
+    log_verbose "Starting ralph-run v$VERSION"
+    log_verbose "Change name: ${CHANGE_NAME:-<auto-detect>}"
+
+    validate_git_repository
+    validate_dependencies
+    
+    if [[ -z "$CHANGE_NAME" ]]; then
+        CHANGE_NAME=$(auto_detect_change)
+        log_info "Auto-detected change: $CHANGE_NAME"
+    fi
+    
+    local change_dir="openspec/changes/$CHANGE_NAME"
+    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"
+    
+    read_openspec_artifacts "$change_dir"
+    local prd_content=$(generate_prd "$change_dir")
+    write_prd "$ralph_dir" "$prd_content"
+    
+    parse_tasks "$change_dir"
+    
+    log_info "PRD generation complete"
+    log_info "Found ${#TASKS[@]} tasks to execute"
+    
+    execute_task_loop "$ralph_dir"
+    
+    log_info "ralph-run.sh initialized successfully"
+}
+
+main "$@"

package/scripts/setup.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+console.log('Setting up spec-and-loop...');
+
+// Get the installation directory
+const installDir = __dirname;
+const ralphRunScript = path.join(installDir, 'ralph-run.sh');
+
+console.log(`Installation directory: ${installDir}`);
+
+// Make ralph-run.sh executable
+if (fs.existsSync(ralphRunScript)) {
+  try {
+    execSync(`chmod +x "${ralphRunScript}"`);
+    console.log('✓ Made ralph-run.sh executable');
+  } catch (err) {
+    console.warn(`Could not make ralph-run.sh executable: ${err.message}`);
+  }
+} else {
+  console.error(`Error: ralph-run.sh not found at ${ralphRunScript}`);
+  process.exit(1);
+}
+
+console.log('');
+console.log('spec-and-loop setup complete!');
+console.log('');
+console.log('Usage:');
+console.log('  cd /path/to/your/project');
+console.log('  openspec init                    # Initialize OpenSpec');
+console.log('  openspec new <name>             # Create a new change');
+console.log('  openspec ff <name>              # Fast-forward artifacts');
+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('  - jq CLI: apt install jq / brew install jq');
+console.log('  - git: git init');