Ralph

ralph — Queue Drain Launcher

This skill is a launcher for the Ralph drain script (scripts/ralph-loop.mjs in this plugin). It does not run a loop in the current session. It helps you configure the right invocation, previews what will be processed, and emits the exact command to run.

The actual loop runs as a separate Node process. Each iteration spawns a fresh claude -p in its own git worktree (via Claude Code's -w flag), claims one item from the TO queue, and works it to terminal per the item's schema. Outcome is signaled via a RALPH_OUTCOME: JSON marker that the script parses for circuit-breaker decisions.

Why a separate script, not a slash-command loop? Per Geoff Huntley's canonical Ralph: the value comes from carving off small bits of work into independent context windows. Each iteration is a fresh process — fresh context, fresh worktree, isolated logs, clean exit codes. The skill-as-orchestrator pattern (one session, internal loop) accumulates context within a session and doesn't preserve fresh-context isolation. For autonomous cadence, compose with /loop: /loop 30m node scripts/ralph-loop.mjs --filter "tag=bug-fix".

Step 1 — Resolve the filter

Determine what subset of the queue to drain.

If $ARGUMENTS is non-empty, parse it as a filter expression. Supported keys:

Multiple keys combine with AND (space-separated). Examples: tag=bug-fix priority=high, type=quick-fix, parentId=89d02e32, ancestorId=<projectRootId>.

Project-scoped default: when a project rootId is known (the ## Project Scope section of the session context injected by the SessionStart hook, or the project-level config's project.rootId), default the filter to include ancestorId=<rootId> unless the user explicitly asks to drain across all projects (e.g., "ralph everything", "drain across all projects"). This keeps the Step 3 preview scoped to the current project when multiple project roots share one database. A personal root (## Personal Scope, or the user-level config) never defaults the filter: it only anchors new items.

Known limitation — ancestorId is preview-only. The Step 3 preview uses query_items, which supports ancestorId. The actual per-iteration claim (claim_item, driven by iteration-prompt.md) does not support ancestorId — its selector only understands tag, type, priority, and parentId (see that file's filter-key table). So a filter like ancestorId=<projectRootId> will scope what you see in the preview but is silently dropped when translated for the actual drain — iterations will still claim from the whole queue unless the filter also includes a parentId/tag/type that discriminates the project's items. If precise per-project draining matters, prefer tagging or typing items distinctly per project until claim_item gains ancestorId support.

If $ARGUMENTS is empty, ask the user via AskUserQuestion:

◆ Ralph loop — what should I drain?
  1. Bug-fix backlog (tag=bug-fix)
  2. Quick fixes (type=quick-fix)
  3. Tech debt container (parentId=<lookup>)
  4. Anything in queue (no filter)
  5. Custom filter — specify

If the user picks "Tech debt container", search via FTS: query_items(operation="search", query="Tech Debt", limit=5) and use the resulting UUID. (FTS mode triggers when query is present; depth is a list-mode-only filter and is ignored in FTS mode.)

Step 2 — Resolve bounds

Set sensible loop bounds. Show defaults and let the user adjust.

◆ Loop bounds (default in parens):
  Max iterations:           10
  Gate-failure budget:      3 consecutive
  Error budget:             2 consecutive
  Per-iteration USD cap:    $5
  Claim TTL per iteration:  1800s (30 min)
  Model:                    sonnet
  Cleanup on terminal:      smart (remove if no commits/changes; preserve otherwise)
  Resume continuations:     2 per iteration (0 disables)

  Adjust any?  Reply "ok" to use defaults.

If the user adjusts, capture the overrides. Common patterns:

• High-volume drain: --max 30
• Low-confidence run: --gate-budget 1 --error-budget 1
• Architecture-heavy items: --model opus --budget 15
• Preserve every worktree (debugging-heavy session): --no-cleanup
• Disable resume-on-marker-less-exit (treat every marker-less clean exit as an immediate error, the old behavior): --max-continuations 0
• Give a flaky agent more room to find its footing: --max-continuations 4

Step 3 — Preview the queue

Show what the loop will see. Use query_items with the resolved filter to display the first 5 candidates and the total count:

query_items(operation="search", role="queue", claimStatus="unclaimed", limit=10, ...)

Pass ancestorId="<rootId>" in ... when a project rootId (not a personal root) is known (resolved above) and the filter didn't already override scope — this gives an accurate project-scoped preview, subject to the preview-only limitation noted in Step 1.

Display:

◆ Queue preview — filter: tag=bug-fix priority=high
  Total claimable: 7 items
  First 5 by priority:
    ◉ d4fc7b2e  Fix duplicate UUID race in claim_item            (high)
    ◉ 92da8e9a  Gate response includes stale guidance            (high)
    ◉ 0c916953  subagent-start hook double-advance               (high)
    ◉ 00769317  advance_item applied:false contradicts DB        (medium)
    ◉ 2e4c9e77  create_work_tree dependency semantics            (low)

If the count is zero, tell the user nothing matches and stop here. If the count exceeds the iteration cap by a lot, mention that subsequent runs would pick up the rest.

Step 4 — Emit the command

Print the exact command to run. The user copies and pastes it.

◆ Ready to launch. Run this command:

  node claude-plugins/task-orchestrator/scripts/ralph-loop.mjs \
    --filter "tag=bug-fix priority=high" \
    --max 10 \
    --budget 5 \
    --ttl 1800 \
    --model sonnet

  → Spawns one `claude -p --worktree=ralph-...` per iteration
  → Each iteration is fresh context, isolated worktree
  → Logs print live as iterations run
  → An iteration that exits cleanly with no RALPH_OUTCOME marker is resumed
    in place (`claude -p --resume`, same worktree) up to `--max-continuations`
    times (default 2) before it's counted as an error — add
    `--max-continuations <n>` to adjust, or `--max-continuations 0` to disable
  → Final summary lists outcomes and preserved worktrees

  For autonomous cadence (re-run every 30 min until empty):
    /loop 30m node claude-plugins/task-orchestrator/scripts/ralph-loop.mjs --filter "tag=bug-fix priority=high"

  Dry-run first to verify the iteration command:
    node claude-plugins/task-orchestrator/scripts/ralph-loop.mjs --dry-run --filter "tag=bug-fix priority=high"

Adjust the path if the user is in a different working directory — the script lives at claude-plugins/task-orchestrator/scripts/ralph-loop.mjs relative to the project root.

If the user wants the skill to launch the script directly (rather than emit a command), suggest using the Bash tool — but flag the tradeoff:

⚠ Running the script via Bash from this session means the loop output streams
   into our conversation transcript. That works for short drains but burns
   context on long ones. For drains over 5 iterations, prefer running the
   command in a separate terminal so this session stays free for other work.

Step 5 — Post-run handoff

After the script finishes (the user reports back with the summary, or pastes the output), help interpret the outcomes:

For preserved worktrees from gate-blocked or errored iterations:

# inspect
git -C <repo-path> worktree list | grep ralph-

# resume manually with /status-progression on the item ID
# or clean up after inspection
git -C <repo-path> worktree remove ralph-<id>

Outcomes & exit codes (script reference)

The iteration agent emits RALPH_OUTCOME: {...} as its final message. The loop driver maps each status to circuit-breaker behavior:

skip includes resource-lease contention. When advance_item rejects a transition into WORK with errorCode: "resource_unavailable" (transient — a shared resource the item declares via a resources: trait is currently held by another item), the iteration prompt releases its claim on that item and emits skip naming the contended key, rather than retrying the same item or treating it as an error. This is deliberate: a resource_unavailable rejection is expected contention, not a failure of this iteration, and the lock is not going to free up within the iteration's own lifetime — the next iteration should pick a different item, not spin against the same lock. See Workflow Guide §11 — Resource Leasing for the full contention/retry model.

The script's own exit code:

Composition with other tools

Examples

Example 1: Drain the bug-fix queue

User: "ralph the bug-fix backlog"

$ARGUMENTS = "tag=bug-fix"

Step 1 parses the filter: tag=bug-fix.

Step 2 uses defaults (max=10, budgets=3/2, $5/iter, sonnet).

Step 3 shows 7 claimable items, top 5 by priority.

Step 4 emits:

node claude-plugins/task-orchestrator/scripts/ralph-loop.mjs \
  --filter "tag=bug-fix" \
  --max 10

User runs it. Each iteration spawns a fresh claude -p --worktree=ralph-<id> with the iteration prompt. The agent uses claim_item selector mode to atomically find and claim one item (a single MCP call — no race window), invokes /schema-workflow to drive it through whatever phases its schema declares, commits changes, and exits with the outcome marker.

5 iterations later: 3 terminal, 1 gate-blocked (a required note couldn't be filled — e.g., needed external context the iteration didn't have), 1 errored (test failure unrelated to the fix). Loop exits when consecutive gate failures hit the budget (3) or queue empties — whichever comes first.

Example 2: Scheduled overnight drain

User wants the queue drained periodically.

After Step 4 emits the standard command, suggest:

/loop 1h node claude-plugins/task-orchestrator/scripts/ralph-loop.mjs --filter "tag=bug-fix priority=high"

The /loop skill schedules it. Every hour, the script runs. If the queue is empty, it exits within seconds. If items appear (e.g., from CI or other agents), they get drained on the next tick.

Example 3: One-shot drain of a specific container

User: "ralph everything in tech debt"

Step 1 searches for "Tech Debt", finds container 89d02e32. Filter resolves to parentId=89d02e32.

Step 4 emits:

node claude-plugins/task-orchestrator/scripts/ralph-loop.mjs \
  --filter "parentId=89d02e32" \
  --max 20

Smart cleanup is on by default — worktrees with no commits or uncommitted changes (e.g., from items whose schema only required note-fills) get auto-removed; worktrees with real diffs are preserved for review/push.

Troubleshooting

Problem: the script reports error: could not read iteration prompt

Cause: The script expects iteration-prompt.md at ../skills/ralph/iteration-prompt.md relative to its own location. The repo layout may have shifted, or the script was copied elsewhere.

Solution: Verify both files exist in the plugin layout: claude-plugins/task-orchestrator/scripts/ralph-loop.mjs and claude-plugins/task-orchestrator/skills/ralph/iteration-prompt.md. Don't move them independently.

Problem: every iteration ends with error: iteration agent exited cleanly without RALPH_OUTCOME marker (after N continuation(s))

Cause: The iteration agent isn't following the prompt — it keeps ending its turn without emitting the outcome marker, even after the loop driver resumed it in place (claude -p --resume <session_id>, same worktree) via --max-continuations. The (after N continuation(s)) suffix tells you how many resumes were tried before giving up; without the suffix, no continuation was attempted at all (immediate marker-less exit, or --max-continuations 0). Likely the agent ran out of budget, hit a tool restriction, or ignored the prompt's exit instructions even when explicitly told to continue.

Solution: Run with --dry-run and inspect the prompt that would be sent. If the prompt looks correct, raise --budget (some iterations need more headroom) or raise --max-continuations to give the agent more resume attempts. If it persists across continuations, run one iteration manually with claude -p --worktree=test-1 --append-system-prompt-file skills/ralph/iteration-system-prompt.md "$(cat skills/ralph/iteration-prompt.md)" to debug interactively.

Problem: claim contention — every iteration gets skip or idle because all candidates are already claimed

Cause: Stale claims from a crashed previous run, or another worker is already draining. TTL is the recovery mechanism.

Note: With selector mode, claim_item returns none_eligible (kind=transient, with a retryAfterMs hint and an aggregate excluded breakdown) when queue items match the filter but are all currently claimed (or dependency-blocked, or under a claimed ancestor) — rather than the permanent queue_empty outcome, and rather than an already_claimed error. The iteration treats this as an idle exit, and the loop driver backs off and retries rather than exiting the drain.

Solution: Check query_items(operation="search", claimStatus="claimed") to see who holds claims. If they're all from a crashed ralph-<pid>-<ts> actor, wait for TTL expiry (default 30 min per the loop's settings) or release them via claim_item(releases=[...]) if you know they're stale.

Note: Ralph workers skip sub-items of in-progress features (ancestor-claim filtering)

When a fleet agent claims a feature using the hybrid topology (Scenario D in the Fleet Deployment Guide), the feature's child tasks are automatically protected from Ralph workers with broad selectors. A Ralph drain using role=queue will see none_eligible (transient — reported under excluded.ancestorClaimed) for any candidate whose ancestor is currently claimed by a different agent — this is the correct and desired behavior, not a bug. Ralph workers naturally focus on top-level claimable work; items inside an in-progress orchestration session are shielded. There is no depth-0/no-parent filter today — omitting parentId in a claim_item selector means unrestricted matching across all depths, it does not restrict to top-level items (same limitation as the ancestorId preview-only gap noted in Step 1). If precise top-level-only draining matters, use the workaround: tag or type top-level items distinctly (e.g., tag=top-level or a dedicated type) so the selector can discriminate them without a depth filter.

Problem: the iteration agent dispatches subagents (Agent tool) and that's confusing the loop

Cause: The iteration prompt doesn't forbid subagents, but they add complexity (the iteration agent's worktree is the dispatched subagent's working directory too).

Solution: Subagent dispatch within an iteration is allowed and sometimes useful (e.g., for parallel reads). It's fine as long as the iteration agent collects subagent results, fills notes, and emits the outcome marker as its own final message. If subagents are causing context bloat, edit the iteration prompt to discourage them.