tim-hub/powerball-harness / harness/skills/harness-ralph-loop
harness-ralph-loop
VerifiedRuns iterate-until-pass loops with ralph-worker agents in a worktree. Use when running [ralph]-marked tasks or looping until verify passes.
Harness Ralph Loop
Iterative-loop orchestrator for [ralph]-marked Plans.md tasks.
Spawns a fresh harness:ralph-worker subagent per attempt inside a single persistent worktree,
runs the Verify command authoritatively, and loops until both the <promise> text tag and verify exit 0 agree.
Quick Reference
| Subcommand / Argument | Behavior |
|---|---|
help | Print usage, philosophy, and link to prompt-best-practices.md |
<task-id> | Run the loop for a Plans.md task that has [ralph] marker |
--max-iter N | Override MaxIter (default: 10) |
--verify CMD | Override the Verify command from the task |
Execution Flow
See references/loop-flow.md for the complete orchestrator pseudocode.
Summary: On iteration 0 the orchestrator spawns a ralph-worker with isolation="worktree" to create the persistent worktree, capturing RALPH_WORKTREE from result.worktreePath. For iterations 1..N it fetches the EnterWorktree deferred-tool schema via ToolSearch, calls EnterWorktree(path=RALPH_WORKTREE), then spawns the next worker without the isolation param. After each iteration the orchestrator runs the Verify command itself (anti-tamper), compares the exit code against ralph-worker-report.v1.verify.exit_code, scans the final assistant message for <promise>…</promise>, and diffs the worktree to detect stuck iterations. The loop terminates on success or on any of the three hard-stop failure modes (FT-RALPH-01 STUCK, FT-RALPH-02 VERIFY-MISMATCH, FT-RALPH-03 MAX-ITER).
Help Subcommand
Running harness-ralph-loop help prints the following:
-
Overview — harness-ralph-loop is an iterative-loop orchestrator that spawns a fresh
ralph-workersubagent per attempt inside a single persistent worktree, runs the Verify command authoritatively, and loops until both the<promise>text tag and verify exit 0 agree. -
Philosophy bullets:
- Iteration > Perfection — let the loop refine; don't aim for perfect on the first try
- Failures Are Data — deterministically bad means tunable; each failure leaves context
- Operator Skill Matters — prompt quality is the primary lever, not model strength
- Persistence Wins — keep trying; the loop handles retry logic automatically
-
Prompt guidance pointer: For full prompt-writing guidance see
prompt-best-practices.md -
Task-pattern fit pointer: For task-pattern fit see
when-to-ralph.md
When to Use Ralph
See references/when-to-ralph.md for guidance on which tasks are Ralph-suitable and which are not.
Reference Files
| File | Purpose |
|---|---|
references/loop-flow.md | Full orchestrator pseudocode, prompt template, decision matrix, terminal-state handling |
references/when-to-ralph.md | When to use Ralph (task patterns, DoD quality checks) |
references/prompt-best-practices.md | Prompt writing best practices (A1–A4), philosophy bullets, learn-more links |
Related Skills and Agents
harness-plan— Emits[ralph]marker +Verify:line for suitable tasksharness-work— Detects[ralph]marker and routes to this skillharness:ralph-worker— The per-iteration worker agent this skill dispatches
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 469k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |