tim-hub/powerball-harness/harness-ralph-loop

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

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:

1. Overview — harness-ralph-loop is an iterative-loop orchestrator that spawns a fresh

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.

1. 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

1. Prompt guidance pointer:

For full prompt-writing guidance see `prompt-best-practices.md`

1. 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

Related Skills and Agents

• harness-plan — Emits [ralph] marker + Verify: line for suitable tasks
• harness-work — Detects [ralph] marker and routes to this skill
• harness:ralph-worker — The per-iteration worker agent this skill dispatches