Initial commit
This commit is contained in:
Zhongwei Li
33
commands/cancel-ralph.md
Normal file
33
commands/cancel-ralph.md
Normal file
@@ -0,0 +1,33 @@
|
||||
---
|
||||
name: cancel-ralph
|
||||
description: "Cancel active Ralph Wiggum loop"
|
||||
allowed-tools: ["Bash"]
|
||||
hide-from-slash-command-tool: "true"
|
||||
---
|
||||
|
||||
# Cancel Ralph
|
||||
|
||||
```bash
|
||||
bash -c '
|
||||
STATE_FILE=$(find .claude -maxdepth 1 -name "ralph-loop-*.local.md" -type f 2>/dev/null | head -1)
|
||||
if [[ -n "$STATE_FILE" ]] && [[ -f "$STATE_FILE" ]]; then
|
||||
ITERATION=$(grep "^iteration:" "$STATE_FILE" | sed "s/iteration: *//")
|
||||
SESSION_ID=$(grep "^session_id:" "$STATE_FILE" | sed "s/session_id: *//" | tr -d "\"")
|
||||
echo "FOUND_LOOP=true"
|
||||
echo "ITERATION=$ITERATION"
|
||||
echo "SESSION_ID=$SESSION_ID"
|
||||
echo "STATE_FILE=$STATE_FILE"
|
||||
else
|
||||
echo "FOUND_LOOP=false"
|
||||
fi
|
||||
'
|
||||
```
|
||||
|
||||
Check the output above:
|
||||
|
||||
1. **If FOUND_LOOP=false**:
|
||||
- Say "No active Ralph loop found."
|
||||
|
||||
2. **If FOUND_LOOP=true**:
|
||||
- Use Bash to remove the state file shown in STATE_FILE
|
||||
- Report: "Cancelled Ralph loop (session: SESSION_ID, was at iteration ITERATION)"
|
||||
127
commands/help.md
Normal file
127
commands/help.md
Normal file
@@ -0,0 +1,127 @@
|
||||
---
|
||||
name: help
|
||||
description: "Explain 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 | claude-code --continue
|
||||
done
|
||||
```
|
||||
|
||||
The same prompt is fed to Claude repeatedly. The "self-referential" aspect comes from Claude seeing its own previous work in the files and git history, not from feeding output back as input.
|
||||
|
||||
**Each iteration:**
|
||||
1. Claude receives the SAME prompt
|
||||
2. Works on the task, modifying files
|
||||
3. Tries to exit
|
||||
4. Stop hook intercepts and feeds the same prompt again
|
||||
5. Claude 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-wiggum:ralph-loop <PROMPT> [OPTIONS]
|
||||
|
||||
Start a Ralph loop in your current session.
|
||||
|
||||
**Usage:**
|
||||
```
|
||||
/ralph-wiggum:ralph-loop "Refactor the cache layer" --max-iterations 20
|
||||
/ralph-wiggum: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 `.claude/ralph-loop-{session-id}.local.md` state file (unique per session)
|
||||
2. You work on the task
|
||||
3. When you try to exit, stop hook intercepts
|
||||
4. Same prompt fed back
|
||||
5. You see your previous work
|
||||
6. Continues until promise detected or max iterations
|
||||
|
||||
---
|
||||
|
||||
### /ralph-wiggum:cancel-ralph
|
||||
|
||||
Cancel an active Ralph loop (removes the loop state file).
|
||||
|
||||
**Usage:**
|
||||
```
|
||||
/ralph-wiggum:cancel-ralph
|
||||
```
|
||||
|
||||
**How it works:**
|
||||
- Checks for active loop state file (`.claude/ralph-loop-{session-id}.local.md`)
|
||||
- Removes the state file
|
||||
- Reports cancellation with session ID and iteration count
|
||||
|
||||
---
|
||||
|
||||
## Key Concepts
|
||||
|
||||
### Completion Promises
|
||||
|
||||
To signal completion, Claude must output a `<promise>` tag:
|
||||
|
||||
```
|
||||
<promise>TASK COMPLETE</promise>
|
||||
```
|
||||
|
||||
The stop hook looks for this specific tag. Without it (or `--max-iterations`), Ralph runs infinitely.
|
||||
|
||||
### Self-Reference Mechanism
|
||||
|
||||
The "loop" doesn't mean Claude talks to itself. It means:
|
||||
- Same prompt repeated
|
||||
- Claude's work persists in files
|
||||
- Each iteration sees previous attempts
|
||||
- Builds incrementally toward goal
|
||||
|
||||
## Example
|
||||
|
||||
### Interactive Bug Fix
|
||||
|
||||
```
|
||||
/ralph-wiggum: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
|
||||
61
commands/ralph-loop.md
Normal file
61
commands/ralph-loop.md
Normal file
@@ -0,0 +1,61 @@
|
||||
---
|
||||
name: ralph-loop
|
||||
description: "Start Ralph Wiggum loop in current session"
|
||||
argument-hint: "PROMPT [--max-iterations N] [--completion-promise TEXT]"
|
||||
allowed-tools: ["Bash(${CLAUDE_PLUGIN_ROOT}/scripts/setup-ralph-loop.sh)"]
|
||||
hide-from-slash-command-tool: "true"
|
||||
---
|
||||
|
||||
# Ralph Loop Command
|
||||
|
||||
Execute the setup script to initialize the Ralph loop:
|
||||
|
||||
```bash
|
||||
bash -c '
|
||||
# Disable glob expansion to prevent command injection from user-provided prompts
|
||||
set -f
|
||||
"'"${CLAUDE_PLUGIN_ROOT}"'/scripts/setup-ralph-loop.sh" "'"$ARGUMENTS"'"
|
||||
SETUP_EXIT_CODE=$?
|
||||
set +f
|
||||
|
||||
# If setup failed, do not continue with promise display
|
||||
if [ $SETUP_EXIT_CODE -ne 0 ]; then
|
||||
exit $SETUP_EXIT_CODE
|
||||
fi
|
||||
|
||||
# Extract and display completion promise if set (find session-based state file)
|
||||
STATE_FILE=$(find .claude -maxdepth 1 -name "ralph-loop-*.local.md" -type f 2>/dev/null | head -1)
|
||||
if [ -n "$STATE_FILE" ] && [ -f "$STATE_FILE" ]; then
|
||||
PROMISE=$(grep "^completion_promise:" "$STATE_FILE" | sed "s/completion_promise: *//" | sed "s/^\"\(.*\)\"$/\1/")
|
||||
if [ -n "$PROMISE" ] && [ "$PROMISE" != "null" ]; then
|
||||
echo ""
|
||||
echo "═══════════════════════════════════════════════════════════"
|
||||
echo "CRITICAL - Ralph Loop Completion Promise"
|
||||
echo "═══════════════════════════════════════════════════════════"
|
||||
echo ""
|
||||
echo "To complete this loop, output this EXACT text:"
|
||||
echo " <promise>$PROMISE</promise>"
|
||||
echo ""
|
||||
echo "STRICT REQUIREMENTS (DO NOT VIOLATE):"
|
||||
echo " ✓ Use <promise> XML tags EXACTLY as shown above"
|
||||
echo " ✓ The statement MUST be completely and unequivocally TRUE"
|
||||
echo " ✓ Do NOT output false statements to exit the loop"
|
||||
echo " ✓ Do NOT lie even if you think you should exit"
|
||||
echo ""
|
||||
echo "IMPORTANT - Do not circumvent the loop:"
|
||||
echo " Even if you believe you are stuck, the task is impossible,"
|
||||
echo " or you have been running too long - you MUST NOT output a"
|
||||
echo " false promise statement. The loop is designed to continue"
|
||||
echo " until the promise is GENUINELY TRUE. Trust the process."
|
||||
echo ""
|
||||
echo " If the loop should stop, the promise statement will become"
|
||||
echo " true naturally. Do not force it by lying."
|
||||
echo "═══════════════════════════════════════════════════════════"
|
||||
fi
|
||||
fi
|
||||
'
|
||||
```
|
||||
|
||||
Please work on the task. When you try to exit, the Ralph loop will feed the SAME PROMPT back to you for the next iteration. You'll see your previous work in files and git history, allowing you to iterate and improve.
|
||||
|
||||
CRITICAL RULE: If a completion promise is set, you may ONLY output it when the statement is completely and unequivocally TRUE. Do not output false promises to escape the loop, even if you think you're stuck or should exit for other reasons. The loop is designed to continue until genuine completion.
|
||||
Reference in New Issue
Block a user