home / skills / supercent-io / skills-template / ralph-loop

ralph-loop skill

safe

This skill enforces completion by looping until the task finishes, injecting continuations and signaling DONE or custom promises.

npx playbooks add skill supercent-io/skills-template --skill ralph-loop

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

Files (1)

SKILL.md

2.1 KB

---
name: ralph-loop
description: Self-referential completion loop for OpenCode. Re-injects continuation prompts until the task is fully complete with a completion promise.
allowed-tools: [Read, Write, Bash, Grep, Glob]
tags: [opencode, ralph-loop, ultrawork, loop, completion]
platforms: [OpenCode, Claude, Gemini, Codex]
version: 1.0.0
source: sst/opencode + code-yeongyu/oh-my-opencode
---

# ralph-loop - Completion Enforcement Loop

## When to use this skill

- Long-running implementation tasks that tend to stop early
- Tasks that need strict completion signaling
- Workflows using `ultrawork` / `ulw` in OpenCode
- Sessions where the agent must continue until exact completion

---

## 1. Core Command Pattern

Use the built-in command form:

```text
/ralph-loop "<task description>" [--completion-promise=TEXT] [--max-iterations=N]
```

Defaults:
- Completion promise: `DONE`
- Max iterations: `100`

---

## 2. How the Loop Behaves

1. Starts with your task prompt.
2. On each idle cycle, verifies whether the assistant output contains:

```xml
<promise>DONE</promise>
```

3. If not found, injects a continuation prompt and increments iteration.
4. Stops only when:
   - Completion promise is detected, or
   - Max iterations is reached, or
   - You run `/cancel-ralph`.

---

## 3. Practical Usage

### Standard run

```text
/ralph-loop "Refactor auth module and finish all tests"
```

### Custom promise

```text
/ralph-loop "Migrate API clients to v2" --completion-promise=SHIP_IT
```

### Bounded iteration run

```text
/ralph-loop "Fix flaky CI tests" --max-iterations=20
```

### Cancel active loop

```text
/cancel-ralph
```

---

## 4. Integration Notes for skills-template

- Keep this skill as an operational guide for OpenCode workflows.
- Pair with orchestration skills (for example, `ohmg`) when tasks require delegation.
- Require explicit completion tags in final responses to avoid premature stop.

---

## Quick Reference

| Action | Command |
|--------|---------|
| Start loop | `/ralph-loop "task"` |
| Custom promise | `/ralph-loop "task" --completion-promise=TEXT` |
| Iteration cap | `/ralph-loop "task" --max-iterations=N` |
| Cancel | `/cancel-ralph` |

Overview

This skill enforces completion by looping on a task until an explicit completion promise appears in the assistant output. It reinjects continuation prompts automatically and stops only when a configured promise tag is detected, a max iteration limit is reached, or a cancel command is issued. The skill is designed for long-running or easily-truncated workflows that require strict finish signaling.

How this skill works

You start the loop with a single command containing the task description and optional parameters for the completion promise and max iterations. On each cycle the skill checks the assistant output for a matching completion tag (for example <promise>DONE</promise>). If the tag is missing it sends a continuation prompt and counts another iteration. The loop terminates when the promise is found, iterations hit the cap, or you cancel the loop.

When to use it

Long implementation tasks that often stop mid-way
Workflows that require explicit completion confirmation
Sessions using ultrawork / ulw where orchestration must continue until finish
Automated tasks that must retry or continue until a final tag appears
Complex refactors, migrations, or test suites that need full coverage

Best practices

Choose a clear, unlikely-to-appear-by-accident completion promise (e.g., DONE or SHIP_IT).
Set a reasonable max-iterations to avoid runaway loops; defaults are safe but adjust for task complexity.
Include explicit final-state instructions so the assistant knows when to emit the completion tag.
Combine with orchestration skills when delegating subtasks to other agents or services.
Monitor loop progress and use the cancel command to stop if behavior diverges from expectations.

Example use cases

Refactor a module and require a final <promise>DONE</promise> once all tests pass.
Migrate API clients and insist on a SHIP_IT tag when all endpoints are updated.
Run multi-step CI fix sessions where intermittent outputs can cause premature completion.
Large documentation generation where the loop continues until the final completeness tag is present.
Repeat a flaky test-fix cycle until a definitive completion marker is returned.

FAQ

What is the default completion promise?

The default promise is DONE, represented as <promise>DONE</promise> in output.

How do I stop the loop manually?

Run the cancel command to halt an active loop immediately using /cancel-ralph.