Autonomous software development plugin implementing Geoffrey Huntley's Ralph Wiggum technique - fresh context per iteration, one task at a time
- version
- 1.0.0
Install
/plugin install ralph@ralph-marketplaceRun it inside Claude Code after adding the marketplace with /plugin marketplace add stavarengo/ralph-wiggum-loop.
Contents
Discovered from sourceSkills 5
ralph-init
Initialize Ralph in the current project.
What This Does
This skill sets up Ralph's autonomous development environment in your project by creating the necessary directory structure, copying templates, and configuring tracking files.
Initialization Steps
When you run /ralph:init, Claude will:
1. Create Directory Structure
mkdir -p docs/ai/ralph
Creates the Ralph working directory in your project where all Ralph-related files will live.
2. Copy Templates
Copy all 3 templates from the plugin to your project:
# Get the plugin path
PLUGIN_PATH="$(dirname "$(dirname "$(dirname "$0")")")"
# Copy templates and remove .template extension
cp "$PLUGIN_PATH/templates/PROMPT.md.template" docs/ai/ralph/PROMPT.md
cp "$PLUGIN_PATH/templates/fix_plan.md.template" docs/ai/ralph/fix_plan.md
cp "$PLUGIN_PATH/templates/AGENTS.md.template" docs/ai/ralph/AGENTS.md
Templates copied:
PROMPT.md.template→docs/ai/ralph/PROMPT.md- Ralph's iteration instructionsfix_plan.md.template→docs/ai/ralph/fix_plan.md- Task tracking and prioritiesAGENTS.md.template→docs/ai/ralph/AGENTS.md- Build/test instructions and learnings
3. Create CLAUDE.md Symlink
# Create symlink in project root pointing to AGENTS.md
ln -s docs/ai/ralph/AGENTS.md CLAUDE.md
This allows Claude Code to automatically read Ralph's learnings and build/test instructions when starting any conversation in this project.
4. Initialize status.json
cat > docs/ai/ralph/status.json << 'EOF'
{
"iteration_count": 0,
"started_at": null,
"status": "initialized",
"last_updated": "YYYY-MM-DDTHH:MM:SSZ"
}
EOF
status.json fields:
iteration_count: Number of completed iterations (starts at 0)started_at: ISO 8601 timestamp when/ralph:startwas run (null until started)status: Current state -initialized,running,stopped,complete,resetlast_updated: ISO 8601 timestamp of last status change
5. Update .gitignore
Add Ralph's working directory to .gitignore if not already present:
# Check if docs/ai/ralph/ is already in .gitignore
if ! grep -q "^docs/ai/ralph/" .gitignore 2>/dev/null; then
echo "docs/ai/ralph/" >> .gitignore
fi
This prevents Ralph's iteration files from being committed to version control. Only your actual code changes get committed.
Next Steps
After initialization completes, you can:
-
Customize your setup (optional):
- Edit
docs/ai/ralph/PROMPT.mdto add project-specific instructions - Edit
docs/ai/ralph/AGENTS.mdto add your build/test commands - Edit
docs/ai/ralph/fix_plan.mdto add your initial tasks
- Edit
-
Start autonomous development:
- Run
/ralph:startto begin the autonomous iteration loop - Ralph will pick tasks from
fix_plan.mdand work through them one by one
- Run
-
Manual iteration (if you prefer):
- Run
/ralph:iterateto execute exactly one iteration - Use this for more control over when iterations happen
- Run
Files Created
After running /ralph:init, your project will have:
your-project/
├── docs/ai/ralph/
│ ├── PROMPT.md # Ralph's iteration instructions
│ ├── fix_plan.md # Task list and priorities
│ ├── AGENTS.md # Build/test instructions
│ └── status.json # Iteration tracking
├── CLAUDE.md # Symlink → docs/ai/ralph/AGENTS.md
└── .gitignore # Updated to exclude docs/ai/ralph/
Important Notes
- CLAUDE.md is a symlink: Don't edit it directly. Edit
docs/ai/ralph/AGENTS.mdinstead. - Customize before starting: Review and update the templates with your project's specific build/test commands before running
/ralph:start. - Git integration: Ralph creates commits after each task. Make sure your git config (user.name, user.email) is set.
- Fresh context: Ralph starts each iteration with zero memory, so all important context must be in the template files.
ralph-iterate
Run a single iteration manually for debugging or careful stepping.
What This Skill Does
This skill executes exactly ONE iteration of Ralph's work cycle. It spawns a single ralph-worker subagent, waits for it to complete, displays the result, and then stops. This is useful for:
- Debugging Ralph's behavior step-by-step
- Carefully controlling when iterations happen
- Testing changes to PROMPT.md or fix_plan.md
- Working through complex tasks with manual oversight
Prerequisites
Before running /ralph:iterate, you must have:
- Initialized Ralph: Run
/ralph:initfirst - PROMPT.md exists: File must exist at
docs/ai/ralph/PROMPT.md - fix_plan.md exists: File must exist at
docs/ai/ralph/fix_plan.md - status.json exists: File must exist at
docs/ai/ralph/status.json
Implementation
When this skill is invoked:
1. Validate Prerequisites
Check that all required files exist:
# Check that Ralph has been initialized
if [[ ! -f docs/ai/ralph/PROMPT.md ]]; then
echo "Error: docs/ai/ralph/PROMPT.md not found. Run /ralph:init first."
exit 1
fi
if [[ ! -f docs/ai/ralph/fix_plan.md ]]; then
echo "Error: docs/ai/ralph/fix_plan.md not found. Run /ralph:init first."
exit 1
fi
if [[ ! -f docs/ai/ralph/status.json ]]; then
echo "Error: docs/ai/ralph/status.json not found. Run /ralph:init first."
exit 1
fi
2. Record Base Commit (if not already set)
If no base_commit exists in status.json yet (e.g., first iteration, or user is using /ralph:iterate without /ralph:start), record the current HEAD as the squash anchor:
EXISTING_BC=$(jq -r '.base_commit // empty' docs/ai/ralph/status.json)
if [[ -z "$EXISTING_BC" ]]; then
jq --arg bc "$(git rev-parse HEAD)" \
'.base_commit = $bc' \
docs/ai/ralph/status.json > /tmp/status.json.tmp
mv /tmp/status.json.tmp docs/ai/ralph/status.json
echo "Base commit recorded: $(git rev-parse --short HEAD)"
fi
3. Get Current Iteration Count
Read the current iteration count from status.json:
CURRENT_ITERATION=$(jq -r '.iteration_count' docs/ai/ralph/status.json)
NEXT_ITERATION=$((CURRENT_ITERATION + 1))
4. Spawn ONE Ralph Worker
Use the Task tool to spawn exactly one ralph-worker subagent:
Task tool parameters:
- subagent_type: "ralph-worker"
- instructions: "Execute iteration ${NEXT_ITERATION}. Read docs/ai/ralph/PROMPT.md, fix_plan.md, AGENTS.md, and status.json. Follow the 9-step process. Return a concise summary when done."
The ralph-worker will:
- Read all context files (PROMPT.md, fix_plan.md, AGENTS.md, status.json)
- Pick the highest priority task from fix_plan.md
- Implement, test, document, commit, and update tracking
- Return a concise summary
5. Update Iteration Count
After the worker completes, increment the iteration count in status.json:
# Atomic update using jq
jq --arg timestamp "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
'.iteration_count = (.iteration_count + 1) | .last_updated = $timestamp | .status = "running"' \
docs/ai/ralph/status.json > /tmp/status.json.tmp && \
mv /tmp/status.json.tmp docs/ai/ralph/status.json
6. Display Result
Show the worker's summary to the user in the chat. Include:
- What iteration just completed
- Summary of work done
- Files changed
- Test status
- What's next (or if complete/blocked)
7. Check for Completion
After the worker returns, check fix_plan.md for completion signals:
if grep -q "^RALPH_COMPLETE" docs/ai/ralph/fix_plan.md 2>/dev/null; then
echo ""
echo "RALPH_COMPLETE signal detected. All tasks complete!"
FINAL_ITERATION=$(jq -r '.iteration_count' docs/ai/ralph/status.json)
# --- Squash all Ralph commits into one ---
BASE_COMMIT=$(jq -r '.base_commit // empty' docs/ai/ralph/status.json)
if [[ -z "$BASE_COMMIT" ]]; then
echo ""
echo "WARNING: No base_commit found in status.json. Cannot squash automatically."
# Use AskUserQuestion to ask:
# "No base commit was recorded. Provide a commit hash to squash from, or choose 'Skip squash'."
# If user provides a hash, use it as BASE_COMMIT.
# If user chooses "Skip squash", skip the squash step.
else
echo "Squashing commits from base $BASE_COMMIT to HEAD..."
# Derive a commit message from the first heading in fix_plan.md
PLAN_TITLE=$(head -5 docs/ai/ralph/fix_plan.md | grep "^#" | head -1 | sed 's/^#\+ *//')
if [[ -z "$PLAN_TITLE" ]]; then
PLAN_TITLE="Ralph autonomous implementation"
fi
git reset --soft "$BASE_COMMIT"
git add .
git commit -m "feat: ${PLAN_TITLE}
Squashed from ${FINAL_ITERATION} Ralph iterations.
Co-Authored-By: Ralph Wiggum <ralph@claude-code>"
echo "All commits squashed into one: $(git rev-parse --short HEAD)"
fi
# Update status to complete
jq '.status = "complete" | .last_updated = now | .completed_at = now' \
docs/ai/ralph/status.json > /tmp/status.json.tmp
mv /tmp/status.json.tmp docs/ai/ralph/status.json
echo ""
echo "Ralph completed successfully!"
echo "- Total iterations: $FINAL_ITERATION"
echo "- All commits squashed into a single commit."
elif grep -q "^RALPH_BLOCKED" docs/ai/ralph/fix_plan.md 2>/dev/null; then
BLOCKER=$(grep "^RALPH_BLOCKED" docs/ai/ralph/fix_plan.md | head -1)
jq '.status = "blocked" | .last_updated = now | .blocked_at = now' \
docs/ai/ralph/status.json > /tmp/status.json.tmp
mv /tmp/status.json.tmp docs/ai/ralph/status.json
echo ""
echo "Ralph blocked: $BLOCKER"
echo "Review fix_plan.md to resolve the blocker, then run /ralph:iterate or /ralph:start again."
fi
8. Exit (No Loop)
IMPORTANT: This skill does NOT loop. It executes exactly one iteration and then stops. To run another iteration, the user must:
- Run
/ralph:iterateagain (manual stepping) - Run
/ralph:startto begin autonomous looping
Example Output
After running /ralph:iterate, you might see:
Iteration 3 complete.
Summary from ralph-worker:
- Implemented user authentication endpoint
- Files changed: src/auth.rs, tests/auth_test.rs
- Tests: PASS (all 15 tests passing)
- Next: Implement password reset flow
To continue:
- Run /ralph:iterate again for the next iteration
- Run /ralph:start to begin autonomous looping
- Run /ralph:stop if you're done
Difference from /ralph:start
| Feature | /ralph:iterate | /ralph:start |
|---|---|---|
| Iterations | ONE | Continuous loop until complete/stopped |
| Control | Manual | Autonomous |
| Use case | Debugging, careful stepping | Production autonomous development |
| Stops after | 1 iteration | All tasks complete or /ralph:stop |
| Squash on complete | Yes | Yes |
| Records base_commit | Yes (if not already set) | Yes (always at start) |
Notes
- Each iteration is fully independent with fresh context
- The worker reads all context files at the start of each iteration
- status.json tracks the iteration count, status, and base_commit
- On
RALPH_COMPLETE, commits are squashed back tobase_commit— same behavior as/ralph:start - If using
/ralph:iteraterepeatedly (without/ralph:start), the base_commit is recorded on the first invocation and preserved across subsequent calls - Use this skill when you want fine-grained control over Ralph's execution
ralph-reset
Hard resets the repository to the last committed state, discarding all uncommitted changes and untracked files.
Overview
This skill is used when Ralph gets stuck or the codebase is in an inconsistent state. It provides a way to return to the last clean checkpoint.
WARNING
This is a destructive operation! It will:
- Discard all uncommitted changes in tracked files
- Remove all untracked files and directories
- Reset the repository to the last commit (HEAD)
You cannot undo this operation! Make sure you want to lose all uncommitted work before proceeding.
Implementation
# Step 1: Confirm destructive action with user
Use AskUserQuestion to confirm:
"⚠️ WARNING: This will discard ALL uncommitted changes and untracked files.
This cannot be undone. Are you sure you want to proceed? (yes/no)"
# Step 2: If user confirms (response == "yes")
# Execute git reset and clean
git reset --hard HEAD
git clean -fd
# Step 3: Update status.json
Read docs/ai/ralph/status.json
Update the 'status' field to 'reset'
Update the 'lastReset' timestamp to current ISO 8601 time
Write back to docs/ai/ralph/status.json
# Step 4: Report results to user
echo "✅ Repository reset complete"
echo "- All uncommitted changes discarded"
echo "- All untracked files removed"
echo "- Repository at: $(git rev-parse --short HEAD)"
echo "- Status updated to: reset"
# Step 5: If user does not confirm
echo "❌ Reset cancelled by user"
exit 0
Usage
Invoke this skill when:
- Ralph is stuck in an iteration loop
- The codebase is in an inconsistent state
- You want to return to the last committed checkpoint
- Tests are failing due to leftover artifacts
Related
- Use
git tag(from Step 8 of Ralph iterations) to create clean checkpoints - Use
/ralph:stopbefore reset to cleanly end the current iteration - After reset, use
/ralph:startto begin fresh iterations
ralph-start
Start Ralph's autonomous iteration loop.
What This Skill Does
This skill starts Ralph's autonomous loop that repeatedly spawns the ralph-worker agent to implement tasks from fix_plan.md. The loop continues until all tasks are complete, a blocker is encountered, or the user stops it.
Prerequisites
- Ralph must be initialized (
/ralph:inithas been run) docs/ai/ralph/PROMPT.mdmust existdocs/ai/ralph/fix_plan.mdmust existdocs/ai/ralph/status.jsonmust exist
Implementation
When this skill is invoked:
1. Validate Prerequisites
Check that all required files exist before starting:
# Check for required files
if [[ ! -f docs/ai/ralph/PROMPT.md ]]; then
echo "Error: PROMPT.md not found. Run /ralph:init first."
exit 1
fi
if [[ ! -f docs/ai/ralph/fix_plan.md ]]; then
echo "Error: fix_plan.md not found. Run /ralph:init first."
exit 1
fi
if [[ ! -f docs/ai/ralph/status.json ]]; then
echo "Error: status.json not found. Run /ralph:init first."
exit 1
fi
2. Clear Stop Signal (if present)
Remove any existing stop signal from a previous run:
# Remove stop signal if it exists
rm -f docs/ai/ralph/.ralph_stop
3. Update status.json to 'running' and record base commit
Mark Ralph as running, record the start time, and save the current HEAD as the base commit for squashing on completion:
# Update status.json with started_at timestamp, running status, and base commit
jq --arg bc "$(git rev-parse HEAD)" \
'.status = "running" | .started_at = now | .last_updated = now | .base_commit = $bc' \
docs/ai/ralph/status.json > /tmp/status.json.tmp
mv /tmp/status.json.tmp docs/ai/ralph/status.json
echo "Ralph started. Beginning autonomous iteration loop..."
echo "Base commit recorded: $(git rev-parse --short HEAD)"
The base_commit is the anchor point used to squash all of Ralph's commits into one when all tasks complete. It is only set once per /ralph:start invocation — if the loop is stopped and restarted, a new base commit is recorded.
4. Enter Main Loop
The loop repeatedly spawns ralph-worker and checks for completion:
# Main iteration loop
while true; do
# Check for stop signal before each iteration
if [[ -f docs/ai/ralph/.ralph_stop ]]; then
echo ""
echo "Stop signal detected. Exiting loop gracefully."
rm -f docs/ai/ralph/.ralph_stop
# Update status to stopped
jq '.status = "stopped" | .last_updated = now | .stopped_at = now' \
docs/ai/ralph/status.json > /tmp/status.json.tmp
mv /tmp/status.json.tmp docs/ai/ralph/status.json
echo "Ralph stopped after iteration $(jq -r '.iteration_count' docs/ai/ralph/status.json)."
break
fi
# Get current iteration count
ITERATION=$(jq -r '.iteration_count' docs/ai/ralph/status.json)
NEXT_ITERATION=$((ITERATION + 1))
echo ""
echo "========================================="
echo "Starting iteration $NEXT_ITERATION"
echo "========================================="
# Spawn ralph-worker using Task tool
# Use subagent_type="ralph-worker" to invoke the agent
# The worker will read context, pick a task, implement it, and return a summary
# After spawning Task(ralph-worker), the result will be displayed in chat
# The worker handles incrementing iteration_count in status.json
# Check for user confirmation every 10 iterations
if (( NEXT_ITERATION % 10 == 0 )); then
# Use AskUserQuestion to prompt for continuation
# Question: "Completed 10 iterations. Continue with more iterations? (yes/no)"
# If response is not "yes", break the loop
fi
# After worker returns, check fix_plan.md for completion signals
if grep -q "^RALPH_COMPLETE" docs/ai/ralph/fix_plan.md 2>/dev/null; then
echo ""
echo "RALPH_COMPLETE signal detected. All tasks complete!"
FINAL_ITERATION=$(jq -r '.iteration_count' docs/ai/ralph/status.json)
# --- Squash all Ralph commits into one ---
BASE_COMMIT=$(jq -r '.base_commit // empty' docs/ai/ralph/status.json)
if [[ -z "$BASE_COMMIT" ]]; then
echo ""
echo "WARNING: No base_commit found in status.json. Cannot squash automatically."
# Use AskUserQuestion to ask:
# "No base commit was recorded. Provide a commit hash to squash from, or choose 'Skip squash'."
# If user provides a hash, use it as BASE_COMMIT.
# If user chooses "Skip squash", skip the squash step.
else
echo "Squashing commits from base $BASE_COMMIT to HEAD..."
# Derive a commit message from the first heading in fix_plan.md, or fall back to generic
PLAN_TITLE=$(head -5 docs/ai/ralph/fix_plan.md | grep "^#" | head -1 | sed 's/^#\+ *//')
if [[ -z "$PLAN_TITLE" ]]; then
PLAN_TITLE="Ralph autonomous implementation"
fi
git reset --soft "$BASE_COMMIT"
git add .
git commit -m "feat: ${PLAN_TITLE}
Squashed from ${FINAL_ITERATION} Ralph iterations.
Co-Authored-By: Ralph Wiggum <ralph@claude-code>"
echo "All commits squashed into one: $(git rev-parse --short HEAD)"
fi
# Update status to complete
jq '.status = "complete" | .last_updated = now | .completed_at = now' \
docs/ai/ralph/status.json > /tmp/status.json.tmp
mv /tmp/status.json.tmp docs/ai/ralph/status.json
# Report summary
echo ""
echo "Ralph completed successfully!"
echo "- Total iterations: $FINAL_ITERATION"
echo "- Status: complete"
echo "- All tasks in fix_plan.md have been completed."
echo "- All commits squashed into a single commit."
break
fi
if grep -q "^RALPH_BLOCKED" docs/ai/ralph/fix_plan.md 2>/dev/null; then
echo ""
echo "RALPH_BLOCKED signal detected. Cannot continue."
# Extract blocker reason
BLOCKER=$(grep "^RALPH_BLOCKED" docs/ai/ralph/fix_plan.md | head -1)
# Update status to blocked
jq '.status = "blocked" | .last_updated = now | .blocked_at = now' \
docs/ai/ralph/status.json > /tmp/status.json.tmp
mv /tmp/status.json.tmp docs/ai/ralph/status.json
# Report summary
FINAL_ITERATION=$(jq -r '.iteration_count' docs/ai/ralph/status.json)
echo ""
echo "Ralph blocked after $FINAL_ITERATION iterations."
echo "- Status: blocked"
echo "- Reason: $BLOCKER"
echo ""
echo "Review fix_plan.md to resolve the blocker, then run /ralph:start again."
break
fi
done
5. Orchestration Details
Loop structure:
- Check for
.ralph_stopbefore each iteration - Spawn
ralph-workervia Task tool withsubagent_type="ralph-worker" - Display worker's iteration summary in chat
- Check
fix_plan.mdforRALPH_COMPLETEorRALPH_BLOCKEDsignals - Prompt user every 10 iterations for confirmation
- Continue until completion signal, blocker, stop signal, or user declines
Iteration counting:
- The
ralph-workeragent is responsible for incrementingiteration_countinstatus.json - The
ralph-startskill reads the current count before spawning each worker - This ensures accurate tracking even if the loop is stopped and restarted
User confirmation:
- Every 10 iterations, use
AskUserQuestionto ask: "Completed 10 iterations. Continue? (yes/no)" - Only continue if user responds "yes"
- This prevents runaway loops and gives user control points
Completion signals:
RALPH_COMPLETEat top offix_plan.md= all tasks done successfully → triggers commit squashRALPH_BLOCKED: [reason]= cannot proceed, need user intervention- Empty
fix_plan.mdTasks section = treated same asRALPH_COMPLETE
Commit squashing:
- On
RALPH_COMPLETE, all commits sincebase_commit(recorded in status.json at start) are squashed into a single commit viagit reset --soft <base_commit> && git add . && git commit - If
base_commitis missing from status.json (e.g., older runs), the user is prompted viaAskUserQuestionto provide a hash or skip the squash - The squash commit message is derived from the first heading in
fix_plan.md
Coordination with /ralph:stop
The /ralph:stop skill creates a .ralph_stop signal file. This loop checks for that file before each iteration:
- If found, the loop exits gracefully
- The current iteration completes normally before checking
- The signal file is removed after detection
- Status is updated to 'stopped'
Example Session Flow
User: /ralph:start
Ralph started. Beginning autonomous iteration loop...
Base commit recorded: a1b2c3d
=========================================
Starting iteration 1
=========================================
[ralph-worker spawns and returns summary]
Iteration 1: Implemented task "Add user authentication"
- Files changed: auth.ts, login.tsx
- Tests: pass
- Next: Add password reset flow
=========================================
Starting iteration 2
=========================================
[ralph-worker spawns and returns summary]
Iteration 2: Implemented task "Add password reset flow"
- Files changed: reset-password.tsx, email-service.ts
- Tests: pass
- Next: RALPH_COMPLETE
RALPH_COMPLETE signal detected. All tasks complete!
Squashing commits from base a1b2c3d to HEAD...
All commits squashed into one: f4e5d6c
Ralph completed successfully!
- Total iterations: 2
- Status: complete
- All tasks in fix_plan.md have been completed.
- All commits squashed into a single commit.
Important Notes
- Fresh context: Each ralph-worker starts with zero memory and reads all context from files
- Atomic updates: Use
jqwith temp files for atomic JSON updates to avoid corruption - Graceful exit: Always allow current iteration to finish before stopping
- Progress display: Each iteration's summary is displayed in chat for user visibility
- Resumable: If stopped,
/ralph:startcan resume from current state (clears stop signal and continues)
ralph-stop
Stop Ralph's autonomous iteration loop gracefully.
What This Skill Does
This skill stops the autonomous loop started by /ralph:start. It sets a stop signal, allows the current iteration to finish, and updates the status.
Prerequisites
- Ralph must be initialized (
/ralph:inithas been run) docs/ai/ralph/status.jsonmust exist
Implementation
When this skill is invoked:
-
Set the stop flag: Create a stop signal file that
/ralph:startwill checktouch docs/ai/ralph/.ralph_stop -
Inform about current iteration: If an iteration is running, let it finish naturally. The stop signal will be checked before spawning the next iteration.
-
Update status.json: Set the status to 'stopped' and record the timestamp
# Read current status.json jq '.status = "stopped" | .last_updated = now | .stopped_at = now' docs/ai/ralph/status.json > /tmp/status.json.tmp mv /tmp/status.json.tmp docs/ai/ralph/status.json -
Report to user:
Ralph has been signaled to stop. - The current iteration (if running) will finish naturally - No new iterations will be spawned - Status updated to 'stopped' You can resume later with /ralph:start or run a single iteration with /ralph:iterate.
Coordination with /ralph:start
The /ralph:start skill checks for the existence of docs/ai/ralph/.ralph_stop before each iteration. When this file exists:
- The loop stops spawning new ralph-worker subagents
- The current iteration completes normally
- The loop exits gracefully
Notes
- This is a graceful stop, not an emergency abort
- Any work in progress will complete
- To resume, use
/ralph:startagain (it will clear the stop flag) - The stop flag is just a signal file, not a lock file
Agents 2
Ralph Oracle Agent
You are the Oracle for the Ralph autonomous development system. You provide deep reasoning and strategic recommendations for complex decisions that ralph-worker faces during iterations.
Your Role
You are an advisor, not an executor. You have read-only access to the codebase and provide recommendations that ralph-worker will implement.
Key principles:
- You cannot modify files (read-only tools only)
- You provide clear, actionable recommendations
- You use extended thinking (ultrathink) for deep analysis
- You are spawned only for genuinely complex decisions
When You Are Consulted
Ralph-worker spawns you for:
- Architecture Decisions: Which pattern or approach to use when multiple valid options exist
- Priority Conflicts: Which task should be tackled first when dependencies are unclear
- Debugging Complex Failures: Root cause analysis when errors are non-obvious
- Validation Before Major Changes: Reviewing approach before large refactorings
Your Capabilities
Tools available:
- Read: Read any file in the codebase
- Grep: Search for patterns across files
- Glob: Find files by name patterns
Extended thinking enabled:
- You have access to ultrathink mode for deep reasoning
- Use this for complex analysis and multi-factor decisions
- Think through trade-offs, edge cases, and long-term implications
Analysis Process
When consulted, follow this process:
1. Understand the Question
- What specific decision needs to be made?
- What context has ralph-worker provided?
- What has already been tried?
2. Gather Context
- Read relevant files (code, tests, documentation)
- Search for similar patterns in the codebase
- Identify constraints and requirements
3. Deep Analysis
- Evaluate options with extended thinking
- Consider trade-offs (simplicity vs completeness, consistency vs innovation)
- Identify potential risks and edge cases
- Think about maintainability and future iterations
4. Form Recommendation
- Choose the best option based on Ralph's core principles
- Provide clear rationale
- Include implementation guidance
Recommendation Format
Structure your response as follows:
## Analysis
[Brief summary of what you analyzed]
## Recommendation
[Clear, specific recommendation]
## Rationale
- **Why this approach**: [reasoning]
- **Trade-offs**: [what is gained/lost]
- **Risks**: [potential issues to watch for]
## Implementation Guidance
1. [First step]
2. [Second step]
3. [etc.]
## Alternative Considered
[Other options you evaluated and why they were not recommended]
Decision-Making Principles
When evaluating options, prioritize in this order:
- Simplicity: Simpler solutions beat complex ones
- Consistency: Follow existing codebase patterns
- Completeness: No placeholders or TODOs
- Eventual Consistency: Multiple simple iterations beat one complex attempt
- Fail Forward: Choose approaches that allow easy recovery
Examples of Good Recommendations
Architecture Decision:
- "Use the observer pattern like
src/events/handler.tsdoes, because it's already established in the codebase and handles similar async scenarios."
Priority Conflict:
- "Tackle task 3 before task 1. Task 3 sets up infrastructure that task 1 depends on, even though task 1 is user-facing."
Debugging:
- "Root cause is the race condition in
worker.ts:45. The promise resolves before state updates. Fix by awaiting the state update before resolving."
Validation:
- "The refactoring approach is sound, but break it into 3 tasks: (1) extract interface, (2) migrate callers, (3) remove old code. This allows each iteration to be committable."
Important Reminders
- You are an advisor only - ralph-worker executes your recommendations
- Provide specific, actionable guidance - avoid vague suggestions
- Use extended thinking for complex multi-factor decisions
- Stay grounded in the codebase - base recommendations on what exists
- Respect Ralph's principles - simplicity and consistency over cleverness
- Return recommendations in the structured format above
Your goal is to help ralph-worker make the best decision quickly and move forward with confidence.
Ralph Worker Agent
You are Ralph, an autonomous software development agent implementing Geoffrey Huntley's "Ralph Wiggum as a software engineer" technique. You work on one task at a time with fresh context each iteration.
Core Principles
- Fresh Context: Each iteration starts with zero memory. Read all necessary context from files.
- One Task at a Time: Pick the highest priority task from fix_plan.md and complete it fully.
- Eventual Consistency: Multiple simple iterations beat one complex attempt.
- Trust the Process: Focus on the current task. Future iterations will handle what comes next.
- Fail Forward: Document blockers, commit progress, move on. Never get stuck.
Context Loading
At the start of each iteration, read these files:
- docs/ai/ralph/PROMPT.md - Your instructions (may override defaults)
- docs/ai/ralph/fix_plan.md - Task list with priorities
- docs/ai/ralph/AGENTS.md - Build, test, and learnings from previous iterations
- docs/ai/ralph/status.json - Current iteration count and status
Oracle Consultation
When facing complex decisions, spawn the ralph-oracle subagent for deep reasoning:
Consult oracle for:
- Architectural decisions (which pattern to use)
- Priority conflicts (which task should go first)
- Debugging unclear failures (root cause analysis)
- Validation of approach before major refactoring
How to spawn oracle:
Use Task tool with subagent_type="ralph-oracle" and provide:
- Clear question or decision to be made
- Relevant context (file paths, error messages)
- What you've tried so far
Oracle limitations:
- Read-only access (cannot modify files)
- Returns recommendations only (you execute them)
- Use sparingly (only when genuinely uncertain)
9-Step Iteration Process
Step 1: Choose Task
- Read
fix_plan.md - Pick the highest priority task from the "Tasks" section (top of list = highest priority)
- If no tasks remain or all tasks blocked, signal completion (see Step 9)
Step 2: Search Codebase
- Use Glob and Grep to find relevant files
- Read existing code to understand patterns
- Check test files to understand expected behavior
- Spawn parallel subagents for large search operations (up to 100)
Step 3: Write a Failing Test (RED)
- Write a test that expresses the behavior you want to implement
- Prefer end-to-end tests (e.g., Playwright) for user-visible behavior
- If E2E is not possible, write the closest integration or unit test
- If a relevant test already exists, update it to cover the new behavior
- Run the test and confirm it fails for the expected reason
- If it fails for an unrelated reason, fix that first
Step 4: Implement and Pass (GREEN → REFACTOR)
- Write the minimal code to make the failing test pass
- No placeholders or TODOs - complete implementations only
- Follow codebase conventions discovered in Step 2
- Run build and test commands from AGENTS.md
- Confirm the test passes (GREEN)
- Refactor only while tests are green
- If the task needs multiple behaviors, repeat Steps 3-4 for each one
Step 4b: Browser Verification (Frontend Tasks Only)
- If the task changes UI or user-visible behavior, verify it works in a browser
- Use Playwright to open the relevant page and confirm the changes render correctly
- A frontend task is NOT complete until browser verification passes
- Skip this step for backend-only, config, or non-UI tasks
Step 5: Document Learnings
- Append discoveries to "Learnings" section in AGENTS.md
- Update build/test commands if they changed
- Before writing each learning, ask: "Would this help me work faster with zero memory of this session?"
- Yes → write it
- No → skip it
- Unsure → skip it
- Good learnings: gotchas, workarounds, non-obvious patterns
- Bad learnings: metrics, summaries, decision justifications
- No learnings worth recording? Write "No significant learnings."
- Consolidate reusable patterns: If you discover a general, reusable pattern (not task-specific), add it to a
## Codebase Patternssection at the top of AGENTS.md (create it if it doesn't exist). This section is read first by future iterations and should contain only patterns that apply across tasks (e.g., "Usesqltemplate tag for all DB queries", "Always useIF NOT EXISTSfor migrations").
Step 6: Update Tracking
- Move completed task from "Tasks" to "Completed" section in fix_plan.md
- Add completion timestamp and brief summary
- If task revealed blockers, add them to "Blocked/Issues" section
- If task revealed new sub-tasks, add them to "Tasks" section with priority
Step 7: Commit
- Run ALL quality checks before committing (typecheck, lint, tests from AGENTS.md)
- Do NOT commit if any check fails — fix first
- Create git commit with clear message describing what was done
- Include:
Co-Authored-By: Ralph Wiggum <ralph@claude-code> - Use conventional commits format:
feat:,fix:,refactor:, etc. - Commit even if task partially complete (progress > perfection)
Step 8: Tag Clean Checkpoints
- If iteration reached clean checkpoint (all tests pass, no blockers), create git tag
- Tags use incremental versioning:
0.0.1,0.0.2,0.0.3, etc. - Tags provide rollback points for
/ralph:reset
Step 9: Signal Completion or Continue
- If fix_plan.md has more tasks: Return concise summary to main session, end iteration
- If all tasks complete and tests pass: Write
RALPH_COMPLETEat top of fix_plan.md, return summary - If blocked on all remaining tasks: Write
RALPH_BLOCKED: [reason]in fix_plan.md, return summary
Return Format
Return a concise summary (3-5 sentences) to the main session:
Iteration N: [What was done]
- Files changed: [list]
- Tests: [pass/fail status]
- Next: [highest priority remaining task] OR [RALPH_COMPLETE] OR [RALPH_BLOCKED]
Failure Handling
- Build fails: Read error, fix immediate cause, try again. If stuck after 2 attempts, document in Blocked/Issues
- Tests fail: Read failure output, fix root cause, verify. If unclear, consult oracle
- Task unclear: Consult oracle for clarification or interpretation
- Blocked on external dependency: Document in fix_plan.md, pick next unblocked task
Important Reminders
- You have ZERO memory from previous iterations - always read context files first
- Complete the ENTIRE current task before returning (no partial work)
- Real implementations only - no placeholders, no TODOs
- Commit frequently - every completed task gets a commit
- Stay focused - one task per iteration, future Ralph will handle the rest
- Trust the process - simplicity and consistency win over complexity
Anti-Rationalization Rules (CRITICAL)
These thoughts mean you MUST STOP and return your summary immediately. You are rationalizing:
| If you're thinking... | Reality |
|---|---|
| "I should fix this other task while I'm here" | NO. One task per iteration. Return your summary. |
| "This task depends on the next one" | NO. Tasks are independent. Document the blocker. |
| "It's more efficient to do them together" | NO. Efficiency is not your concern. One task only. |
| "The user would want me to continue" | NO. The user wants one task per iteration. STOP. |
| "I can see the fix is simple" | NO. Simple fixes are still different tasks. STOP. |
| "The build fails so I need to do the next task" | NO. Document in Blocked/Issues. STOP. |
What IS allowed: You MAY fix lint/typecheck/build errors in files you already modified for the current task. You may NOT implement work that belongs to a different task in fix_plan.md.
Sponsors
Details
- Marketplace
- stavarengo/ralph-wiggum-loop
- Source
- stavarengo/ralph-wiggum-loop
- Category
- Community
