home / skills / zpankz / mcp-skillset / ralph-invoke

ralph-invoke skill

needs review

/ralph-invoke

This skill empowers Claude to autonomously run iterative Ralph loops to complete complex tasks efficiently.

npx playbooks add skill zpankz/mcp-skillset --skill ralph-invoke

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

3.7 KB

---
name: ralph-invoke
description: |
  Allows Claude to directly start Ralph-Wiggum autonomous loops without user commands.
  Use when user asks to "start a ralph loop", "run ralph", "keep working until done",
  or when a complex task would benefit from multiple iterations.
allowed-tools: Read, Bash
model: haiku
context: fork
agent: ralph-domain-agent
user-invocable: false
---

# Ralph Invoke Skill

**Allows Claude to directly start Ralph-Wiggum autonomous loops without user commands.**

## Prerequisites

The `ralph-wiggum` plugin must be installed and enabled:
```
/plugin install ralph-wiggum@claude-code-plugins
/plugin enable ralph-wiggum@claude-code-plugins
```

## Triggers

Use this skill when:
- User asks to "start a ralph loop" or "run ralph"
- User wants autonomous iteration on a task
- User says "keep working until done" or "iterate until complete"
- A complex task would benefit from multiple iterations
- User explicitly requests Claude to invoke ralph

## How to Start a Ralph Loop

Run this bash command:

```bash
"$HOME/.claude/plugins/cache/claude-code-plugins/ralph-wiggum/1.0.0/scripts/setup-ralph-loop.sh" \
  "<TASK_DESCRIPTION>" \
  --max-iterations <N> \
  --completion-promise "<PROMISE_TEXT>"
```

### Parameters

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| TASK_DESCRIPTION | Yes | - | The task to work on |
| --max-iterations | Recommended | unlimited | Safety limit (use 20-100) |
| --completion-promise | Recommended | null | Text to output when truly done |

### Example Invocations

**Simple task:**
```bash
"$HOME/.claude/plugins/cache/claude-code-plugins/ralph-wiggum/1.0.0/scripts/setup-ralph-loop.sh" \
  "Fix all TypeScript type errors" \
  --max-iterations 50 \
  --completion-promise "ALL_ERRORS_FIXED"
```

**Complex refactor:**
```bash
"$HOME/.claude/plugins/cache/claude-code-plugins/ralph-wiggum/1.0.0/scripts/setup-ralph-loop.sh" \
  "Migrate all API handlers to the new v2 pattern" \
  --max-iterations 100 \
  --completion-promise "MIGRATION_COMPLETE"
```

## How the Loop Works

1. **Claude runs the setup script** → Creates state file at `.claude/ralph-loop.local.md`
2. **Claude works on the task** → Normal operation
3. **Claude tries to exit** → Stop hook intercepts
4. **Hook re-injects prompt** → Claude continues with same task
5. **Repeat** until:
   - Max iterations reached, OR
   - Claude outputs `<promise>PROMISE_TEXT</promise>`

## Completing the Loop

When the task is genuinely complete, output the completion promise in XML tags:

```
<promise>ALL_ERRORS_FIXED</promise>
```

**CRITICAL RULES:**
- Only output the promise when the statement is TRUE
- Do NOT lie to exit the loop
- Do NOT output false promises even if stuck
- Trust the process - if stuck, iterate and try differently

## Canceling a Loop

If needed, cancel with:
```bash
rm .claude/ralph-loop.local.md
```

Or use: `/ralph-wiggum:cancel-ralph`

## Best Practices

1. **Always set --max-iterations** - Prevents runaway costs (50-100 is reasonable)
2. **Use specific completion promises** - "ALL_TESTS_PASS" not "DONE"
3. **Include success criteria in task** - Be explicit about what "done" means
4. **Monitor progress** - `head -10 .claude/ralph-loop.local.md`
5. **Start small** - Test with 3-5 iterations first

## Cost Warning

Autonomous loops consume tokens rapidly. A 50-iteration loop can cost $50-100+ in API usage. Always use --max-iterations as a safety net.

## Why This Skill Exists

The official ralph-wiggum plugin requires users to run `/ralph-loop` commands. This skill enables Claude to invoke loops directly, enabling:
- Claude-initiated iteration on complex tasks
- Programmatic loop triggers from other skills/agents
- Automated workflows without manual commands

Overview

This skill lets Claude directly start Ralph-Wiggum autonomous loops without requiring the user to run plugin commands. It launches and manages an iterative loop that keeps working on a complex task until explicit completion criteria are met or a safety iteration limit is reached. Use it to automate multi-pass workflows that benefit from repeated refinement.

How this skill works

The skill runs a setup script that creates a local loop state file and starts Claude in an iterative loop. Each time Claude would normally exit, a hook re-injects the task prompt so work continues for another iteration. The loop stops only when the configured max-iterations is reached or when Claude outputs the exact completion promise wrapped in <promise>...</promise> tags.

When to use it

User asks to “start a ralph loop”, “run ralph”, or “keep working until done”.
A complex task requires multiple iterations or progressive refinement.
You want autonomous, unattended retries until a measurable success criterion is met.
You need programmatic invocation of an iterative agent from other skills or automation.
When monitoring and cost control can be applied (use max-iterations).

Best practices

Always provide a clear, specific task description including explicit success criteria.
Set --max-iterations to a reasonable safety limit (50–100 recommended; test smaller first).
Use a precise completion promise string like ALL_TESTS_PASS or MIGRATION_COMPLETE.
Monitor progress by inspecting the local state file (e.g., head -10 .claude/ralph-loop.local.md).
Start with a small iteration count (3–5) to validate behavior before scaling up.

Example use cases

Fix all TypeScript type errors across a repository with iterative passes and targeted tests.
Migrate API handlers to a new pattern and re-run validation across files until migration criteria met.
Run a multi-pass refactor that requires repeated linting, tests, and code adjustments.
Iteratively improve documentation until a defined quality checklist is satisfied.
Automate large QA or test-flake triage by retrying fixes until tests are stable.

FAQ

How do I stop a running loop?

Remove the state file (rm .claude/ralph-loop.local.md) or issue the cancel command /ralph-wiggum:cancel-ralph.

What exactly ends the loop?

The loop ends when max-iterations is reached or when Claude outputs the exact completion promise inside <promise>...</promise> tags and that promise is true.

How do I avoid runaway costs?

Always set --max-iterations, start small, and monitor the state file and iteration count. Estimate token costs before large runs.