ralph-wiggum-loop
Multi-step autonomous plan execution with bounded iteration (max 10), state persistence, dependency checking, error retry with exponential backoff, and human escalation on failure. The "Ralph Wiggum loop" enables AI agents to execute complex multi-step plans autonomously while maintaining safety bounds and progress tracking. Includes MCP action invocation, step dependency validation, graceful error recovery, and comprehensive audit logging. Use engines with retry logic, (3) creating bounded loops with state persistence, (4) handling step dependencies in workflows, (5) implementing human escala
npx skills add majiayu000/claude-skill-registry --skill ralph-wiggum-loop --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
What it does
Implements a bounded autonomous execution pattern for multi-step plans with a hard limit of 10 iterations, state persistence to enable restart after crashes, and dependency checking so steps execute in the correct order. It includes retry logic with exponential backoff for transient failures and a path for human escalation on permanent failures. It handles MCP action invocation, file creation in vault, and human notification actions as step types. It logs progress to the plan (marking steps as completed) and to escalation vaults when needed.
How it works
- Initialization: loads a Plan.md and initializes ExecutionState with iterations_remaining set to max_iterations (default 10) and current_step starting at 1. If a prior state exists at vault/In_Progress/{plan_id}/state.md, it loads that state instead.
- Execution loop: while iterations_remaining > 0, it selects the current step and checks dependencies. If dependencies are not met, it marks the step blocked, escalates, and stops.
- Step execution: based on action_type, it performs MCP actions via execute_mcp_action, or creates vault files via execute_file_creation, or notifies humans via execute_human_notification.
- Dependency check: verifies all dependencies for a step are completed (via dependent step entries).
- Error handling: on step failure, it performs retry with exponential backoff up to 3 retries. If retries fail, it escalates and marks the plan blocked, writing escalation details to vault/Needs_Action.
- Completion handling: when all steps are completed, it marks Plan.md as completed, moves it to vault/Done, cleans up state, and updates a dashboard.
- State persistence: after each significant action, it saves ExecutionState to vault/In_Progress/{plan_id}/state.md.
When to use it
Use when you need autonomous multi-step task execution with safety bounds, clear progress tracking, and explicit human escalation for blocked or failed tasks. Suitable for plan-based workflows with explicit step dependencies and retry requirements.
What it can touch
- MCP actions: invokes MCP servers to perform steps (execute_mcp_action) and logs the outcome.
- Vault: creates files and directories (execute_file_creation, human notification files under vault/Needs_Action).
- Plan file: updates Plan.md to mark steps as completed or failed (mark_step_complete, handle_step_failure).
- Escalation artifacts: writes vault/Needs_Action/* escalation documents for blocked or max-iteration cases.
- Plan dashboard: calls update_dashboard upon completion.
Caveats
- The max iterations are fixed to 10 by default; altering requires code changes and may affect behavior.
- Dependency checking relies on explicit step dependency declarations within the plan; misconfigurations can cause blocking escalations.
- Exponential backoff retry uses fixed parameters (5s base, doubling each retry) and a hard cap of 3 retries per step.
- Escalation content and paths assume certain Vault structure; failures may occur if paths are missing or permissions are restricted.
# Ralph Wiggum Loop ## What is the Ralph Wiggum Loop? > "I'm helping! I'm helping! I'm helping!" — Ralph Wiggum The Ralph Wiggum loop is a **bounded autonomous execution pattern** that allows AI agents to execute multi-step plans with: - **Max 10 iterations** (prevents infinite loops) - **State persistence** (restartable on crash) - **Dependency checking** (steps execute in correct order) - **Retry with backoff** (handles transient failures) - **Human escalation** (blocks on permanent failures) **Named after Ralph Wiggum** because the agent enthusiastically attempts tasks repeatedly but has a hard limit to prevent runaway behavior. --- ## Architecture ``` Plan.md (approved) → Plan Executor (plan_executor.py) ↓ Initialize ExecutionState (iterations_remaining=10) ↓ ┌─────────────┴─────────────┐ ↓ ↓ Check Dependencies Execute Step ↓ ↓ All met? Success? ───→ Mark [x], decrement iteration │ │ No No (retry 3x) ↓ ↓ Mark blocked Mark [!], escalate ↓ ↓ Escalate to vault/Needs_Action/ vault/Needs_Action/ ↓ iterations_remaining == 0? ───→ Escalate (max iterations) │ No ↓ Next Step ──→ Loop back ``` --- ## Quick Start ### 1. Plan Structure ```markdown <!-- vault/Plans/PLAN_client_onboarding_00
- What is the Ralph Wiggum Loop?
- Architecture
- Quick Start
- 1. Plan Structure
- 2. Plan Executor Implementation
- Plan Watcher
- Safety Features
- Bounded Iterations
- State Persistence
- Dependency Validation
- Testing
- Configuration
- Troubleshooting
- Key Files
What does the ralph-wiggum-loop skill do?
Multi-step autonomous plan execution with bounded iteration (max 10), state persistence, dependency checking, error retry with exponential backoff, and human escalation on failure. The "Ralph Wiggum loop" enables AI agents to execute complex multi-step plans autonomously while maintaining safety bounds and progress tracking. Includes MCP action invocation, step dependency validation, graceful error recovery, and comprehensive audit logging. Use engines with retry logic, (3) creating bounded loops with state persistence, (4) handling step dependencies in workflows, (5) implementing human escala
How do I install it?
Run `npx skills add majiayu000/claude-skill-registry --skill ralph-wiggum-loop --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From majiayu000/claude-skill-registry, a repository with 534 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.