@wavilikhin/ralph-wiggum 0.1.0

package/README.md

@@ -0,0 +1,340 @@
+# Ralph Wiggum
+
+Autonomous coding loop for [OpenCode](https://opencode.ai). One task, one commit, fresh context per iteration.
+
+```
+  ____       _       _       __        ___                       
+ |  _ \ __ _| |_ __ | |__    \ \      / (_) __ _ _   _ _   _ _ __ 
+ | |_) / _` | | '_ \| '_ \    \ \ /\ / /| |/ _` | | | | | | | '_ \
+ |  _ < (_| | | |_) | | | |    \ V  V / | | (_| | |_| | |_| | | | |
+ |_| \_\__,_|_| .__/|_| |_|     \_/\_/  |_|\__, |\__,_|\__,_|_| |_|
+              |_|                          |___/                   
+```
+
+## What is this?
+
+Ralph Wiggum runs OpenCode in a loop, where each iteration:
+
+1. Starts with **fresh context** (new `opencode run` process)
+2. Picks **exactly one task** from your implementation plan
+3. Implements it and runs **validation gates** (lint, test, build)
+4. Creates **exactly one commit** (local only, no push)
+5. Repeats until all tasks are complete
+
+This approach keeps context focused and produces clean, atomic commits.
+
+## Model Requirements
+
+> **Warning**: Ralph Wiggum requires the latest generation of AI models to work reliably.
+> 
+> The autonomous loop requires models capable of:
+> - Following complex multi-step instructions precisely
+> - Making exactly one commit per iteration
+> - Running validation commands and fixing failures
+> - Updating state files accurately
+>
+> **Recommended models:**
+> - `anthropic/claude-opus-4-20250514`
+> - `openai/gpt-5.2`
+>
+> Using older or less capable models will likely result in failed iterations.
+
+## Prerequisites
+
+- [OpenCode CLI](https://opencode.ai) installed and configured
+- Node.js 18+
+- Git repository
+- **AGENTS.md file in your repo root** (see below)
+
+```bash
+# Verify opencode is working
+opencode --version
+
+# List available models
+opencode models
+```
+
+### AGENTS.md Requirement
+
+Ralph Wiggum expects your repository to have a well-configured `AGENTS.md` file at the root. This file tells the AI agent how to validate changes in your project.
+
+Your `AGENTS.md` must include:
+
+1. **Validation commands** - How to run formatting, linting, type checking, and tests
+2. **Project structure** - Overview of your codebase layout
+3. **Coding standards** - Any conventions the agent should follow
+
+Example minimal `AGENTS.md`:
+
+```markdown
+## Validation Commands
+
+Run these commands to validate changes:
+
+1. Format: `npm run format`
+2. Lint: `npm run lint`
+3. Typecheck: `npm run typecheck`
+4. Test: `npm test`
+
+## Project Structure
+
+- `src/` - Source code
+- `tests/` - Test files
+```
+
+See [OpenCode AGENTS.md documentation](https://opencode.ai/docs/agents-md) for best practices.
+
+## Quick Start
+
+### 1. Initialize in your repo
+
+```bash
+cd your-project
+npx ralph-wiggum init
+```
+
+This creates a `.ralph/` directory with:
+- `PROMPT.md` - Instructions for the AI agent (has mandatory + customizable sections)
+- `IMPLEMENTATION_PLAN.md` - Your task list template
+- `run.sh` - The loop runner
+- `logs/` - Directory for iteration logs
+
+### 2. Fill in your implementation plan
+
+Edit `.ralph/IMPLEMENTATION_PLAN.md` with your tasks:
+
+```markdown
+## Phase 1: Foundation
+
+- [ ] Set up project structure with src/ and tests/ directories
+- [ ] Add TypeScript configuration
+- [ ] Create initial CI pipeline
+
+## Phase 2: Core Implementation
+
+- [ ] Implement user authentication module
+- [ ] Add database connection layer
+- [ ] Create REST API endpoints
+```
+
+Use the checkbox format (`- [ ]` / `- [x]`) - the agent marks tasks complete as it works.
+
+### 3. Run the loop
+
+```bash
+.ralph/run.sh --max-iterations 20 --model anthropic/claude-opus-4-20250514
+```
+
+The loop runs until:
+- All tasks are complete (agent outputs `<promise>COMPLETE</promise>`)
+- Max iterations reached
+- You press Ctrl+C
+
+## CLI Options
+
+```bash
+.ralph/run.sh [options]
+
+Options:
+  --max-iterations N    Maximum iterations (default: 50)
+  --model MODEL         Model to use (default: anthropic/claude-opus-4-20250514)
+  --variant NAME        Optional variant name for opencode
+  --verbose             Enable verbose logging (keeps full opencode output)
+  --help                Show help
+
+Environment variables:
+  RALPH_MAX_ITERATIONS  Default max iterations
+  RALPH_MODEL           Default model
+```
+
+## Logging
+
+Ralph Wiggum maintains two types of logs in `.ralph/logs/`:
+
+### Status Log (`.ralph/logs/ralph.log`)
+
+Always written. Contains iteration status with timestamps:
+
+```
+[2025-01-19 14:30:15] [ITER] === Iteration 1/20 STARTED ===
+[2025-01-19 14:32:47] [ITER] === Iteration 1 FINISHED: SUCCESS (152s) - feat: add user auth module ===
+[2025-01-19 14:32:48] [ITER] === Iteration 2/20 STARTED ===
+```
+
+Use this to monitor progress:
+
+```bash
+# Watch progress in real-time
+tail -f .ralph/logs/ralph.log
+```
+
+### Verbose Logs (`.ralph/logs/ralph_iter_N.log`)
+
+Full opencode output per iteration. By default, these are deleted after successful iterations. Use `--verbose` to keep them:
+
+```bash
+.ralph/run.sh --verbose --max-iterations 10
+```
+
+On failure, the iteration log is always preserved for debugging.
+
+## Examples
+
+### Run with Claude Opus 4
+
+```bash
+.ralph/run.sh --max-iterations 10 --model anthropic/claude-opus-4-20250514
+```
+
+### Run with GPT-5.2
+
+```bash
+.ralph/run.sh --max-iterations 10 --model openai/gpt-5.2
+```
+
+### Run with environment variables
+
+```bash
+export RALPH_MODEL="anthropic/claude-opus-4-20250514"
+export RALPH_MAX_ITERATIONS=30
+.ralph/run.sh
+```
+
+### Dry run (single iteration)
+
+```bash
+.ralph/run.sh --max-iterations 1
+```
+
+### Debug mode (verbose + single iteration)
+
+```bash
+.ralph/run.sh --verbose --max-iterations 1
+```
+
+## How It Works
+
+```
+                       .ralph/run.sh
+                            |
+                            v
+        +---------------------------------------+
+        |         Iteration N                   |
+        |  +----------------------------------+ |
+        |  | 1. Record git HEAD              | |
+        |  | 2. Run: opencode run ...        | |
+        |  | 3. Agent reads PROMPT.md        | |
+        |  | 4. Agent picks ONE task         | |
+        |  | 5. Agent implements + validates | |
+        |  | 6. Agent commits (local only)   | |
+        |  | 7. Check: exactly 1 commit?     | |
+        |  | 8. Check: working tree clean?   | |
+        |  | 9. Check: COMPLETE marker?      | |
+        |  +----------------------------------+ |
+        +---------------------------------------+
+                            |
+               +------------+------------+
+               v                         v
+         [COMPLETE]                 [Continue]
+          Exit 0                   Iteration N+1
+```
+
+Each iteration is a fresh `opencode run` process, so the agent:
+- Has no memory of previous iterations
+- Must re-read PROMPT.md, AGENTS.md, IMPLEMENTATION_PLAN.md
+- Stays focused on one task at a time
+
+## File Structure
+
+After initialization, your repo will have:
+
+```
+your-project/
+├── .ralph/
+│   ├── PROMPT.md              # Agent instructions (edit [CUSTOMIZABLE] sections)
+│   ├── IMPLEMENTATION_PLAN.md # Your task list (fill this in)
+│   ├── run.sh                 # Loop runner script
+│   └── logs/
+│       ├── ralph.log          # Iteration status log
+│       └── ralph_iter_N.log   # Per-iteration logs (verbose/error only)
+├── AGENTS.md                  # Your validation commands (required, you create this)
+└── .gitignore                 # Updated to ignore .ralph/logs/
+```
+
+### .ralph/PROMPT.md
+
+Contains instructions the agent follows each iteration. Has two types of sections:
+
+- **[MANDATORY] sections**: Core loop mechanics - don't modify these
+- **[CUSTOMIZABLE] sections**: Add project-specific context, quality standards
+
+### .ralph/IMPLEMENTATION_PLAN.md
+
+Your task list. Structure it in phases:
+
+```markdown
+## Phase 1: Foundation
+- [ ] Task 1
+- [x] Task 2 (completed)
+
+## Phase 2: Core
+- [ ] Task 3
+
+## Discovered Tasks
+<!-- Agent adds tasks here as it finds them -->
+```
+
+### AGENTS.md (your file, repo root)
+
+Your project's agent configuration. Must exist in repo root before running.
+
+## Safety Features
+
+- **Local only**: Never pushes to remote
+- **One commit per iteration**: Enforced by the loop
+- **Clean working tree**: Verified after each iteration
+- **Max iterations**: Hard stop to prevent runaway loops
+- **Validation gates**: All must pass before commit
+
+## Troubleshooting
+
+### "opencode CLI not found"
+
+Install OpenCode:
+```bash
+npm install -g opencode
+```
+
+### "AGENTS.md not found"
+
+Create an `AGENTS.md` file in your repo root with validation commands. See the [AGENTS.md Requirement](#agentsmd-requirement) section.
+
+### "No commit was created"
+
+The agent must create exactly one commit per iteration. Check `.ralph/logs/ralph_iter_N.log` to see what happened. Common causes:
+- Validation gates failed
+- Agent got stuck on a complex task
+- Task was already complete
+- Model not capable enough (try a more advanced model)
+
+### "Working tree is not clean"
+
+The agent left uncommitted changes. This usually means validation failed. Check the log and fix manually, then restart.
+
+### Loop never completes
+
+- Check if tasks in `.ralph/IMPLEMENTATION_PLAN.md` are achievable
+- Ensure validation commands in AGENTS.md are correct
+- Try running with `--verbose --max-iterations 1` to debug a single iteration
+- Consider using a more capable model
+
+### Iterations failing consistently
+
+This often indicates the model isn't capable enough for autonomous operation. Try:
+- Using `anthropic/claude-opus-4-20250514` or `openai/gpt-5.2`
+- Simplifying tasks in IMPLEMENTATION_PLAN.md
+- Adding more context to AGENTS.md
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@wavilikhin/ralph-wiggum",
+  "version": "0.1.0",
+  "description": "Autonomous coding loop for OpenCode - one task, one commit, fresh context per iteration",
+  "type": "module",
+  "bin": {
+    "ralph-wiggum": "./src/cli.js"
+  },
+  "files": [
+    "src/",
+    "templates/"
+  ],
+  "keywords": [
+    "opencode",
+    "ai",
+    "autonomous",
+    "coding",
+    "agent",
+    "loop"
+  ],
+  "author": "wavilikhin",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wavilikhin/ralph-wiggum.git"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/cli.js

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, copyFileSync, chmodSync } from "fs";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const TEMPLATES_DIR = join(__dirname, "..", "templates");
+
+const RED = "\x1b[31m";
+const CYAN = "\x1b[36m";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const BOLD = "\x1b[1m";
+const RESET = "\x1b[0m";
+const DIM = "\x1b[2m";
+
+function printBanner() {
+  console.log(`
+${CYAN}${BOLD}  ____       _       _       __        ___                       
+ |  _ \\ __ _| |_ __ | |__    \\ \\      / (_) __ _ _   _ _   _ _ __ 
+ | |_) / _\` | | '_ \\| '_ \\    \\ \\ /\\ / /| |/ _\` | | | | | | | '_ \\
+ |  _ < (_| | | |_) | | | |    \\ V  V / | | (_| | |_| | |_| | | | |
+ |_| \\_\\__,_|_| .__/|_| |_|     \\_/\\_/  |_|\\__, |\\__,_|\\__,_|_| |_|
+              |_|                          |___/                   ${RESET}
+${DIM}  Autonomous coding loop for OpenCode${RESET}
+`);
+}
+
+function printUsage() {
+  console.log(`${BOLD}Usage:${RESET}
+  npx ralph-wiggum init    Scaffold ralph-wiggum files in .ralph/ directory
+  npx ralph-wiggum help    Show this help message
+`);
+}
+
+function checkAgentsMd(targetDir) {
+  const agentsPath = join(targetDir, "AGENTS.md");
+  return existsSync(agentsPath);
+}
+
+function printNextSteps(hasAgentsMd) {
+  console.log(`
+${GREEN}${BOLD}Files created successfully!${RESET}
+
+${YELLOW}${BOLD}Next steps:${RESET}
+`);
+
+  if (!hasAgentsMd) {
+    console.log(`${RED}${BOLD}[REQUIRED]${RESET} Create AGENTS.md in your repo root:
+   ${DIM}This file must contain your validation commands (lint, test, build).${RESET}
+   ${DIM}The agent reads this file to know how to validate changes.${RESET}
+   ${DIM}See: https://opencode.ai/docs/agents-md${RESET}
+`);
+  } else {
+    console.log(`${GREEN}[OK]${RESET} AGENTS.md found in repo root
+`);
+  }
+
+  console.log(`${BOLD}1.${RESET} Fill in your implementation plan:
+   ${DIM}Edit ${CYAN}.ralph/IMPLEMENTATION_PLAN.md${RESET}${DIM} with your tasks using the checkbox format${RESET}
+
+${BOLD}2.${RESET} (Optional) Customize the prompt:
+   ${DIM}Edit ${CYAN}.ralph/PROMPT.md${RESET}${DIM} - mandatory sections are marked, customize the rest${RESET}
+
+${BOLD}3.${RESET} Run the loop:
+   ${CYAN}.ralph/run.sh --max-iterations 10 --model anthropic/claude-opus-4-20250514${RESET}
+
+${YELLOW}${BOLD}Important:${RESET} This tool works best with the latest generation models.
+${DIM}Recommended: anthropic/claude-opus-4-20250514 or openai/gpt-5.2${RESET}
+
+${YELLOW}Available loop options:${RESET}
+  --max-iterations N    Maximum iterations before stopping (default: 50)
+  --model provider/m    Model to use (default: anthropic/claude-opus-4-20250514)
+  --variant name        Optional variant name passed to opencode
+  --verbose             Enable verbose logging (full opencode output)
+
+${DIM}Logs are written to ${CYAN}.ralph/logs/ralph.log${RESET}${DIM} (iteration status)${RESET}
+${DIM}Verbose logs: ${CYAN}.ralph/logs/ralph_iter_N.log${RESET}${DIM} (full output per iteration)${RESET}
+
+${DIM}The loop stops automatically when all tasks are complete (<promise>COMPLETE</promise>)${RESET}
+`);
+}
+
+function copyTemplate(templateName, destPath, options = {}) {
+  const templatePath = join(TEMPLATES_DIR, templateName);
+  
+  if (!existsSync(templatePath)) {
+    console.error(`Template not found: ${templateName}`);
+    process.exit(1);
+  }
+
+  if (existsSync(destPath) && !options.overwrite) {
+    console.log(`${YELLOW}Skipping${RESET} ${destPath} (already exists)`);
+    return false;
+  }
+
+  const destDir = dirname(destPath);
+  if (!existsSync(destDir)) {
+    mkdirSync(destDir, { recursive: true });
+  }
+
+  copyFileSync(templatePath, destPath);
+  
+  if (destPath.endsWith(".sh")) {
+    chmodSync(destPath, "755");
+  }
+  
+  console.log(`${GREEN}Created${RESET} ${destPath}`);
+  return true;
+}
+
+function ensureGitignore(targetDir) {
+  const gitignorePath = join(targetDir, ".gitignore");
+  const logsEntry = ".ralph/logs/";
+  
+  if (existsSync(gitignorePath)) {
+    const content = readFileSync(gitignorePath, "utf-8");
+    if (!content.includes(logsEntry)) {
+      writeFileSync(gitignorePath, content.trimEnd() + "\n" + logsEntry + "\n");
+      console.log(`${GREEN}Updated${RESET} .gitignore (added .ralph/logs/)`);
+    } else {
+      console.log(`${YELLOW}Skipping${RESET} .gitignore (.ralph/logs/ already ignored)`);
+    }
+  } else {
+    writeFileSync(gitignorePath, logsEntry + "\n");
+    console.log(`${GREEN}Created${RESET} .gitignore`);
+  }
+}
+
+function initCommand(targetDir) {
+  const ralphDir = join(targetDir, ".ralph");
+  
+  console.log(`${BOLD}Initializing ralph-wiggum in ${ralphDir}${RESET}\n`);
+
+  // Create .ralph directory
+  if (!existsSync(ralphDir)) {
+    mkdirSync(ralphDir, { recursive: true });
+  }
+
+  // Copy templates into .ralph/
+  copyTemplate("PROMPT.md", join(ralphDir, "PROMPT.md"));
+  copyTemplate("IMPLEMENTATION_PLAN.md", join(ralphDir, "IMPLEMENTATION_PLAN.md"));
+  copyTemplate("ralph-loop.sh", join(ralphDir, "run.sh"));
+
+  // Create logs directory inside .ralph/
+  const logsDir = join(ralphDir, "logs");
+  if (!existsSync(logsDir)) {
+    mkdirSync(logsDir, { recursive: true });
+    writeFileSync(join(logsDir, ".gitkeep"), "");
+    console.log(`${GREEN}Created${RESET} .ralph/logs/.gitkeep`);
+  }
+
+  // Update .gitignore to ignore .ralph/logs/
+  ensureGitignore(targetDir);
+
+  const hasAgentsMd = checkAgentsMd(targetDir);
+  printNextSteps(hasAgentsMd);
+}
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+printBanner();
+
+switch (command) {
+  case "init":
+    initCommand(process.cwd());
+    break;
+  case "help":
+  case "--help":
+  case "-h":
+  case undefined:
+    printUsage();
+    break;
+  default:
+    console.error(`Unknown command: ${command}\n`);
+    printUsage();
+    process.exit(1);
+}

package/templates/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,60 @@
+# Implementation Plan
+
+> **Instructions**: Fill in your tasks below using the checkbox format.
+> The AI agent will pick one task per iteration, implement it, and mark it complete.
+
+---
+
+## Definition of Done
+
+A task is complete when:
+- [ ] Implementation is finished
+- [ ] All validation gates pass (see AGENTS.md)
+- [ ] Code is committed locally
+
+---
+
+## Phase 1: Foundation
+<!-- Core setup, dependencies, project structure -->
+
+- [ ] Task 1: Description here
+- [ ] Task 2: Description here
+
+---
+
+## Phase 2: Core Implementation  
+<!-- Main features and functionality -->
+
+- [ ] Task 3: Description here
+- [ ] Task 4: Description here
+
+---
+
+## Phase 3: Integration
+<!-- Connecting components, APIs, external services -->
+
+- [ ] Task 5: Description here
+
+---
+
+## Phase 4: Polish
+<!-- Error handling, edge cases, UX improvements -->
+
+- [ ] Task 6: Description here
+
+---
+
+## Phase 5: Validation
+<!-- Final testing, documentation, cleanup -->
+
+- [ ] Task 7: Description here
+
+---
+
+## Discovered Tasks
+<!-- Agent will add tasks here as they're discovered during implementation -->
+
+---
+
+## Notes & Learnings
+<!-- Agent will add notes here about decisions made, blockers found, etc. -->

package/templates/PROMPT.md

@@ -0,0 +1,115 @@
+# Ralph Wiggum - Single Iteration Prompt
+
+> This file instructs the AI agent on what to do in ONE iteration of the autonomous loop.
+> Sections marked [MANDATORY] must not be modified. Sections marked [CUSTOMIZABLE] can be adjusted.
+
+---
+
+## [MANDATORY] Orientation Phase
+
+Before doing anything:
+
+1. **Read `AGENTS.md`** - contains validation commands (lint, test, build) you MUST run
+2. **Read `IMPLEMENTATION_PLAN.md`** - contains the task list with priorities and completion status
+3. **Search the codebase** before assuming anything is missing - use grep/glob to verify
+
+---
+
+## [MANDATORY] Task Selection
+
+Pick **exactly ONE** task from `IMPLEMENTATION_PLAN.md`:
+
+- Choose the highest-priority incomplete item (marked `- [ ]`)
+- If multiple items have the same priority, pick the one that unblocks others
+- Do NOT work on multiple tasks in a single iteration
+
+---
+
+## [MANDATORY] Implementation + Validation
+
+1. **Implement** the selected task completely
+2. **Run ALL validation gates** from `AGENTS.md`:
+   - Formatting
+   - Linting  
+   - Type checking
+   - Tests
+3. **Fix any failures** before proceeding - do not leave broken code
+4. Iterate until all gates pass
+
+---
+
+## [MANDATORY] State Persistence
+
+After implementation is validated:
+
+1. **Update `IMPLEMENTATION_PLAN.md`**:
+   - Mark the completed task: `- [ ]` → `- [x]`
+   - Add any discovered follow-up tasks to the appropriate phase
+   - Update any notes or learnings
+
+---
+
+## [MANDATORY] Commit (Local Only)
+
+Create exactly ONE commit for this iteration:
+
+```bash
+git add -A
+git commit -m "<type>: <concise description of what was done>"
+```
+
+Rules:
+- **Do NOT push** - local commits only
+- **Exactly ONE commit** per iteration
+- Use conventional commit format: `feat:`, `fix:`, `refactor:`, `docs:`, `test:`, `chore:`
+
+---
+
+## [MANDATORY] Completion Check
+
+**Only if ALL of the following are true:**
+- Every task in `IMPLEMENTATION_PLAN.md` is marked `[x]`
+- All validation gates pass
+- No pending follow-up tasks remain
+
+**Then output exactly:**
+
+```
+<promise>COMPLETE</promise>
+```
+
+**Otherwise, do NOT output this marker.** The loop will continue with a fresh context.
+
+---
+
+## [CUSTOMIZABLE] Project-Specific Context
+
+<!-- Add any project-specific instructions here -->
+<!-- Examples: -->
+<!-- - Preferred coding patterns -->
+<!-- - Architecture decisions to follow -->
+<!-- - Files/directories to avoid modifying -->
+<!-- - Special considerations for this codebase -->
+
+---
+
+## [CUSTOMIZABLE] Quality Standards
+
+<!-- Define your quality bar here -->
+<!-- Examples: -->
+<!-- - Test coverage requirements -->
+<!-- - Documentation requirements -->
+<!-- - Performance considerations -->
+<!-- - Security considerations -->
+
+---
+
+## Summary
+
+Each iteration you must:
+1. Orient (read AGENTS.md, IMPLEMENTATION_PLAN.md)
+2. Pick ONE task
+3. Implement + validate (all gates must pass)
+4. Update IMPLEMENTATION_PLAN.md
+5. Make exactly ONE local commit
+6. Output `<promise>COMPLETE</promise>` only when truly done

package/templates/ralph-loop.sh

@@ -0,0 +1,344 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Ralph Wiggum Loop - Autonomous coding loop for OpenCode
+# Each iteration: fresh context, one task, one commit
+
+# Get the directory where this script is located
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# Go up one level to get to the repo root
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+#=============================================================================
+# Configuration
+#=============================================================================
+
+MAX_ITERATIONS="${RALPH_MAX_ITERATIONS:-50}"
+MODEL="${RALPH_MODEL:-anthropic/claude-opus-4-20250514}"
+VARIANT=""
+VERBOSE=false
+
+# All ralph files are in .ralph/
+RALPH_DIR="$SCRIPT_DIR"
+LOGS_DIR="$RALPH_DIR/logs"
+LOG_FILE="$LOGS_DIR/ralph.log"
+PROMPT_FILE="$RALPH_DIR/PROMPT.md"
+PLAN_FILE="$RALPH_DIR/IMPLEMENTATION_PLAN.md"
+
+#=============================================================================
+# Colors
+#=============================================================================
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+CYAN='\033[0;36m'
+BOLD='\033[1m'
+DIM='\033[2m'
+NC='\033[0m'
+
+#=============================================================================
+# Logging
+#=============================================================================
+
+log_to_file() {
+    local level="$1"
+    local message="$2"
+    local timestamp
+    timestamp=$(date '+%Y-%m-%d %H:%M:%S')
+    echo "[$timestamp] [$level] $message" >> "$LOG_FILE"
+}
+
+log_info() {
+    echo -e "${CYAN}[INFO]${NC} $1"
+    log_to_file "INFO" "$1"
+}
+
+log_success() {
+    echo -e "${GREEN}[OK]${NC} $1"
+    log_to_file "OK" "$1"
+}
+
+log_warn() {
+    echo -e "${YELLOW}[WARN]${NC} $1"
+    log_to_file "WARN" "$1"
+}
+
+log_error() {
+    echo -e "${RED}[ERROR]${NC} $1"
+    log_to_file "ERROR" "$1"
+}
+
+log_iteration_start() {
+    local iter="$1"
+    local max="$2"
+    log_to_file "ITER" "=== Iteration $iter/$max STARTED ==="
+    echo -e "${BOLD}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+    echo -e "${BOLD}  Iteration $iter / $max${NC}"
+    echo -e "${BOLD}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${NC}"
+    echo ""
+}
+
+log_iteration_end() {
+    local iter="$1"
+    local status="$2"
+    local commit_msg="$3"
+    local duration="$4"
+    log_to_file "ITER" "=== Iteration $iter FINISHED: $status (${duration}s) - $commit_msg ==="
+}
+
+#=============================================================================
+# Helper Functions
+#=============================================================================
+
+print_banner() {
+    echo -e "${CYAN}${BOLD}"
+    echo '  ____       _       _       __        ___                       '
+    echo ' |  _ \ __ _| |_ __ | |__    \ \      / (_) __ _ _   _ _   _ _ __ '
+    echo ' | |_) / _` | | '"'"'_ \| '"'"'_ \    \ \ /\ / /| |/ _` | | | | | | | '"'"'_ \'
+    echo ' |  _ < (_| | | |_) | | | |    \ V  V / | | (_| | |_| | |_| | | | |'
+    echo ' |_| \_\__,_|_| .__/|_| |_|     \_/\_/  |_|\__, |\__,_|\__,_|_| |_|'
+    echo '              |_|                          |___/                   '
+    echo -e "${NC}"
+    echo -e "${DIM}  Autonomous coding loop for OpenCode${NC}"
+    echo ""
+}
+
+print_usage() {
+    echo "Usage: $0 [options]"
+    echo ""
+    echo "Options:"
+    echo "  --max-iterations N    Maximum iterations (default: $MAX_ITERATIONS)"
+    echo "  --model MODEL         Model to use (default: $MODEL)"
+    echo "  --variant NAME        Variant name for opencode"
+    echo "  --verbose             Enable verbose logging (full opencode output)"
+    echo "  --help                Show this help"
+    echo ""
+    echo "Environment variables:"
+    echo "  RALPH_MAX_ITERATIONS  Default max iterations"
+    echo "  RALPH_MODEL           Default model"
+    echo ""
+    echo "Logs:"
+    echo "  .ralph/logs/ralph.log           Iteration status (always written)"
+    echo "  .ralph/logs/ralph_iter_N.log    Full opencode output (verbose mode or on error)"
+    echo ""
+    echo "Example:"
+    echo "  $0 --max-iterations 10 --model anthropic/claude-opus-4-20250514"
+}
+
+check_prerequisites() {
+    if ! command -v opencode &> /dev/null; then
+        log_error "opencode CLI not found. Install it first:"
+        echo "  npm install -g opencode"
+        exit 1
+    fi
+
+    if [[ ! -f "$PROMPT_FILE" ]]; then
+        log_error "PROMPT.md not found at $PROMPT_FILE"
+        log_error "Run 'npx ralph-wiggum init' first."
+        exit 1
+    fi
+
+    if [[ ! -f "$PLAN_FILE" ]]; then
+        log_error "IMPLEMENTATION_PLAN.md not found at $PLAN_FILE"
+        log_error "Run 'npx ralph-wiggum init' first."
+        exit 1
+    fi
+
+    if [[ ! -f "$REPO_ROOT/AGENTS.md" ]]; then
+        log_error "AGENTS.md not found in repo root."
+        echo ""
+        echo "Ralph Wiggum requires an AGENTS.md file with your validation commands."
+        echo "This file tells the agent how to lint, test, and build your project."
+        echo ""
+        echo "Create AGENTS.md with at minimum:"
+        echo "  - Formatting command"
+        echo "  - Linting command"
+        echo "  - Type checking command (if applicable)"
+        echo "  - Test command"
+        echo ""
+        echo "See: https://opencode.ai/docs/agents-md"
+        exit 1
+    fi
+
+    if ! git -C "$REPO_ROOT" rev-parse --git-dir > /dev/null 2>&1; then
+        log_error "Not in a git repository."
+        exit 1
+    fi
+
+    if [[ -n "$(git -C "$REPO_ROOT" status --porcelain)" ]]; then
+        log_warn "Uncommitted changes detected. Consider committing or stashing first."
+        echo ""
+        git -C "$REPO_ROOT" status --short
+        echo ""
+        read -p "Continue anyway? [y/N] " -n 1 -r
+        echo
+        if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+            exit 1
+        fi
+    fi
+}
+
+#=============================================================================
+# Parse Arguments
+#=============================================================================
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --max-iterations)
+            MAX_ITERATIONS="$2"
+            shift 2
+            ;;
+        --model)
+            MODEL="$2"
+            shift 2
+            ;;
+        --variant)
+            VARIANT="$2"
+            shift 2
+            ;;
+        --verbose)
+            VERBOSE=true
+            shift
+            ;;
+        --help|-h)
+            print_usage
+            exit 0
+            ;;
+        *)
+            log_error "Unknown option: $1"
+            print_usage
+            exit 1
+            ;;
+    esac
+done
+
+#=============================================================================
+# Main Loop
+#=============================================================================
+
+print_banner
+
+log_info "Configuration:"
+echo -e "  ${DIM}Max iterations:${NC} $MAX_ITERATIONS"
+echo -e "  ${DIM}Model:${NC} $MODEL"
+echo -e "  ${DIM}Verbose:${NC} $VERBOSE"
+echo -e "  ${DIM}Repo root:${NC} $REPO_ROOT"
+[[ -n "$VARIANT" ]] && echo -e "  ${DIM}Variant:${NC} $VARIANT"
+echo ""
+
+check_prerequisites
+
+mkdir -p "$LOGS_DIR"
+
+# Initialize log file
+echo "========================================" >> "$LOG_FILE"
+echo "Ralph Wiggum Loop Started: $(date '+%Y-%m-%d %H:%M:%S')" >> "$LOG_FILE"
+echo "Model: $MODEL" >> "$LOG_FILE"
+echo "Max Iterations: $MAX_ITERATIONS" >> "$LOG_FILE"
+echo "Repo: $REPO_ROOT" >> "$LOG_FILE"
+echo "========================================" >> "$LOG_FILE"
+
+log_info "Starting autonomous loop..."
+log_info "Status log: $LOG_FILE"
+echo ""
+
+# Change to repo root for git operations
+cd "$REPO_ROOT"
+
+for i in $(seq 1 "$MAX_ITERATIONS"); do
+    ITER_START=$(date +%s)
+    ITER_LOG_FILE="$LOGS_DIR/ralph_iter_${i}.log"
+    
+    log_iteration_start "$i" "$MAX_ITERATIONS"
+
+    BEFORE_HEAD=$(git rev-parse HEAD)
+    log_info "HEAD before: ${DIM}${BEFORE_HEAD:0:8}${NC}"
+
+    OPENCODE_CMD=(
+        opencode run
+        --model "$MODEL"
+        --file "$PROMPT_FILE"
+        --file "$PLAN_FILE"
+    )
+    
+    if [[ -n "$VARIANT" ]]; then
+        OPENCODE_CMD+=(--variant "$VARIANT")
+    fi
+    
+    OPENCODE_CMD+=("Follow the attached PROMPT.md. Use AGENTS.md for validation commands and IMPLEMENTATION_PLAN.md for task selection. Do exactly one task and one commit.")
+
+    log_info "Running opencode..."
+    
+    set +e
+    if [[ "$VERBOSE" == true ]]; then
+        OUTPUT=$("${OPENCODE_CMD[@]}" 2>&1 | tee "$ITER_LOG_FILE")
+    else
+        OUTPUT=$("${OPENCODE_CMD[@]}" 2>&1)
+        echo "$OUTPUT" > "$ITER_LOG_FILE"
+    fi
+    EXIT_CODE=$?
+    set -e
+
+    ITER_END=$(date +%s)
+    ITER_DURATION=$((ITER_END - ITER_START))
+
+    if [[ $EXIT_CODE -ne 0 ]]; then
+        log_error "opencode exited with code $EXIT_CODE"
+        log_error "Check log: $ITER_LOG_FILE"
+        log_iteration_end "$i" "FAILED" "opencode error" "$ITER_DURATION"
+        exit 1
+    fi
+
+    if echo "$OUTPUT" | grep -q '<promise>COMPLETE</promise>'; then
+        echo ""
+        log_success "All tasks complete!"
+        echo ""
+        echo -e "${GREEN}${BOLD}Loop finished successfully after $i iteration(s)${NC}"
+        log_iteration_end "$i" "COMPLETE" "all tasks done" "$ITER_DURATION"
+        log_to_file "INFO" "=== LOOP COMPLETED SUCCESSFULLY ==="
+        exit 0
+    fi
+
+    AFTER_HEAD=$(git rev-parse HEAD)
+    log_info "HEAD after: ${DIM}${AFTER_HEAD:0:8}${NC}"
+
+    if [[ "$BEFORE_HEAD" == "$AFTER_HEAD" ]]; then
+        log_error "No commit was created in this iteration!"
+        log_error "The agent must create exactly one commit per iteration."
+        log_error "Check log: $ITER_LOG_FILE"
+        log_iteration_end "$i" "FAILED" "no commit created" "$ITER_DURATION"
+        exit 1
+    fi
+
+    COMMIT_COUNT=$(git rev-list --count "$BEFORE_HEAD".."$AFTER_HEAD")
+    if [[ "$COMMIT_COUNT" -ne 1 ]]; then
+        log_error "Expected 1 commit, but $COMMIT_COUNT were created!"
+        log_iteration_end "$i" "FAILED" "multiple commits" "$ITER_DURATION"
+        exit 1
+    fi
+
+    if [[ -n "$(git status --porcelain)" ]]; then
+        log_error "Working tree is not clean after iteration!"
+        echo ""
+        git status --short
+        log_iteration_end "$i" "FAILED" "dirty working tree" "$ITER_DURATION"
+        exit 1
+    fi
+
+    COMMIT_MSG=$(git log -1 --format='%s')
+    log_success "Commit created: $COMMIT_MSG"
+    log_iteration_end "$i" "SUCCESS" "$COMMIT_MSG" "$ITER_DURATION"
+    
+    if [[ "$VERBOSE" != true ]]; then
+        rm -f "$ITER_LOG_FILE"
+    fi
+    
+    echo ""
+done
+
+echo ""
+log_warn "Max iterations ($MAX_ITERATIONS) reached without completion."
+log_warn "Check IMPLEMENTATION_PLAN.md for remaining tasks."
+log_to_file "WARN" "=== LOOP STOPPED: MAX ITERATIONS REACHED ==="
+exit 1