ralph_skill

Overview

This skill implements a self-referential completion loop for AI CLI tools that re-runs the agent on the same task across turns until a concrete completion signal is detected or a max iteration cap is reached. It is designed to drive autonomous, multi-turn workflows where each iteration sees the current file and git state while the conversational context is cleared between turns. Use it to enforce verifiable completion criteria and let the agent self-correct over repeated passes.

How this skill works

You invoke the skill once with a task prompt and optional flags (completion promise and max iterations). After each agent turn an AfterAgent hook inspects the agent output for the configured completion promise (e.g., <promise>DONE</promise>). If the promise is missing and the iteration limit is not reached, the hook starts a fresh agent turn with the original prompt and cleared conversational context so the agent evaluates the current workspace state and improves its output. The loop stops when the promise appears, the max iterations is hit, or you cancel the loop.

When to use it

• Long-running implementation tasks that tend to stop early and need repeated refinement
• Autonomous multi-turn workflows that must self-correct without manual intervention
• Workflows where a verifiable completion signal is required before stopping
• TDD-style cycles where tests are run, failures are analyzed, and fixes are reattempted
• Refactors or incremental migrations that must converge across iterations

Best practices

• Provide a clear, verifiable completion promise via --completion-promise (e.g., TASK_COMPLETE)
• Always set --max-iterations as a safety hatch to prevent infinite loops
• Structure prompts to guide work → verify → debug cycles so iterations are meaningful
• Run in sandbox / dry-run mode initially and use YOLO (-y) if you trust tool execution
• Rely on file and git state for persistence; avoid embedding state in the prompt

Example use cases

• Implement a feature via TDD: loop until tests pass and output <promise>TESTS_PASSED</promise>
• Incrementally refactor an authentication module with a 20-iteration cap
• Build a REST API for todos and stop when CRUD endpoints pass tests and output TASK_COMPLETE
• Run autonomous repair passes on a flaky test suite until stability is detected
• Run a multi-step setup or deployment script that needs repeated verification