Initial commit: Ralph Wiggum plugin for OpenCode

command/cancel-ralph.md

@@ -0,0 +1,28 @@
+---
+description: Cancel the active Ralph Wiggum loop
+---
+
+# Cancel Ralph Loop
+
+To cancel the Ralph loop, perform these steps:
+
+1. Check if the Ralph state file exists at `ralph-loop.local.md`
+
+2. If the file does NOT exist:
+   - Report: "No active Ralph loop found."
+
+3. If the file EXISTS:
+   - Read the file to get the current iteration number from the `iteration:` field in the frontmatter
+   - Delete the file `ralph-loop.local.md`
+   - Report: "Cancelled Ralph loop (was at iteration N)" where N is the iteration value
+
+Execute:
+```bash
+if [ -f ralph-loop.local.md ]; then
+  ITERATION=$(grep '^iteration:' ralph-loop.local.md | sed 's/iteration: *//')
+  rm ralph-loop.local.md
+  echo "Cancelled Ralph loop (was at iteration $ITERATION)"
+else
+  echo "No active Ralph loop found."
+fi
+```

command/ralph-help.md

@@ -0,0 +1,126 @@
+---
+description: Explain the Ralph Wiggum technique and available commands
+---
+
+# Ralph Wiggum Plugin Help
+
+Please explain the following to the user:
+
+## What is the Ralph Wiggum Technique?
+
+The Ralph Wiggum technique is an iterative development methodology based on continuous AI loops, pioneered by Geoffrey Huntley.
+
+**Core concept:**
+```bash
+while :; do
+  cat PROMPT.md | opencode --continue
+done
+```
+
+The same prompt is fed to the AI repeatedly. The "self-referential" aspect comes from the AI seeing its own previous work in the files and git history, not from feeding output back as input.
+
+**Each iteration:**
+1. AI receives the SAME prompt
+2. Works on the task, modifying files
+3. Completes its response
+4. Plugin intercepts idle state and feeds the same prompt again
+5. AI sees its previous work in the files
+6. Iteratively improves until completion
+
+The technique is described as "deterministically bad in an undeterministic world" - failures are predictable, enabling systematic improvement through prompt tuning.
+
+## Available Commands
+
+### /ralph-loop <PROMPT> [OPTIONS]
+
+Start a Ralph loop in your current session.
+
+**Usage:**
+```
+/ralph-loop "Refactor the cache layer" --max-iterations 20
+/ralph-loop "Add tests" --completion-promise "TESTS COMPLETE"
+```
+
+**Options:**
+- `--max-iterations <n>` - Max iterations before auto-stop
+- `--completion-promise <text>` - Promise phrase to signal completion
+
+**How it works:**
+1. Creates `.opencode/ralph-loop.local.md` state file
+2. You work on the task
+3. When you finish responding, the plugin intercepts
+4. Same prompt fed back
+5. You see your previous work
+6. Continues until promise detected or max iterations
+
+---
+
+### /cancel-ralph
+
+Cancel an active Ralph loop (removes the loop state file).
+
+**Usage:**
+```
+/cancel-ralph
+```
+
+**How it works:**
+- Checks for active loop state file
+- Removes `.opencode/ralph-loop.local.md`
+- Reports cancellation with iteration count
+
+---
+
+## Key Concepts
+
+### Completion Promises
+
+To signal completion, the AI must output a `<promise>` tag:
+
+```
+<promise>TASK COMPLETE</promise>
+```
+
+The plugin looks for this specific tag. Without it (or `--max-iterations`), Ralph runs infinitely.
+
+### Self-Reference Mechanism
+
+The "loop" doesn't mean the AI talks to itself. It means:
+- Same prompt repeated
+- AI's work persists in files
+- Each iteration sees previous attempts
+- Builds incrementally toward goal
+
+## Example
+
+### Interactive Bug Fix
+
+```
+/ralph-loop "Fix the token refresh logic in auth.ts. Output <promise>FIXED</promise> when all tests pass." --completion-promise "FIXED" --max-iterations 10
+```
+
+You'll see Ralph:
+- Attempt fixes
+- Run tests
+- See failures
+- Iterate on solution
+- In your current session
+
+## When to Use Ralph
+
+**Good for:**
+- Well-defined tasks with clear success criteria
+- Tasks requiring iteration and refinement
+- Iterative development with self-correction
+- Greenfield projects
+
+**Not good for:**
+- Tasks requiring human judgment or design decisions
+- One-shot operations
+- Tasks with unclear success criteria
+- Debugging production issues (use targeted debugging instead)
+
+## Learn More
+
+- Original technique: https://ghuntley.com/ralph/
+- Ralph Orchestrator: https://github.com/mikeyobrien/ralph-orchestrator

command/ralph-loop.md

@@ -0,0 +1,80 @@
+---
+description: Start a Ralph Wiggum loop for iterative development
+---
+
+# Ralph Loop Command
+
+You are starting a Ralph Wiggum loop. This is an iterative development technique where you work on the same task repeatedly, seeing your previous work in files and git history.
+
+## Setup Instructions
+
+Execute the following steps to initialize the Ralph loop:
+
+1. Parse the arguments from: `$ARGUMENTS`
+
+   Arguments format: `<PROMPT> [--max-iterations N] [--completion-promise TEXT]`
+
+   - Extract the main prompt (everything that isn't a flag or flag value)
+   - Extract `--max-iterations` value if provided (default: 0 for unlimited)
+   - Extract `--completion-promise` value if provided (default: null)
+
+2. Create the state file at `ralph-loop.local.md` (in the project root) with this exact format:
+
+```markdown
+---
+active: true
+iteration: 1
+max_iterations: <MAX_ITERATIONS_VALUE>
+completion_promise: <COMPLETION_PROMISE_VALUE_OR_null>
+started_at: "<CURRENT_ISO_TIMESTAMP>"
+---
+
+<THE_PROMPT_TEXT>
+```
+
+3. Output the activation message:
+
+```
+Ralph loop activated!
+
+Iteration: 1
+Max iterations: <N or "unlimited">
+Completion promise: <TEXT or "none (runs forever)">
+
+The Ralph plugin will now monitor for session idle events. When you complete
+your response, the same prompt will be fed back to continue the loop.
+
+To stop the loop:
+- Output <promise>YOUR_PROMISE</promise> if a completion promise is set
+- Wait for max iterations to be reached
+- Run /cancel-ralph to cancel manually
+```
+
+4. If a completion promise is set, display this critical warning:
+
+```
+CRITICAL - Ralph Loop Completion Promise
+
+To complete this loop, output this EXACT text:
+  <promise>YOUR_PROMISE_HERE</promise>
+
+STRICT REQUIREMENTS:
+  - Use <promise> XML tags EXACTLY as shown above
+  - The statement MUST be completely and unequivocally TRUE
+  - Do NOT output false statements to exit the loop
+  - Do NOT lie even if you think you should exit
+
+IMPORTANT: Even if you believe you're stuck or the task is impossible,
+you MUST NOT output a false promise. The loop continues until the
+promise is GENUINELY TRUE.
+```
+
+5. Now begin working on the task from the prompt. The Ralph plugin will automatically continue feeding you the same prompt when you complete your response.
+
+## Example Usage
+
+```
+/ralph-loop Build a REST API for todos --completion-promise "DONE" --max-iterations 20
+/ralph-loop Fix the auth bug --max-iterations 10
+/ralph-loop Refactor the cache layer
+```