Setup Ralph Loop

Setup Ralph Loop

Create the local scripts and repo conventions needed to run Ralph safely.

Invocation Position

This is an infrastructure skill, not a normal feature-delivery stage.

Use /setup-ralph-loop when a project wants to run /execute in a repeatable HITL-to-AFK loop.

Auto-invocation: /execute automatically invokes this skill when it detects multi-slice GitHub-issue work (PRD, big-batch appetite, or multiple user stories) and no ralph-once.sh or ralph.sh exists in the repo root. This means the skill may be entered without the user explicitly calling it — the detection and invocation happen as a prerequisite step inside /execute.

Do not use it as part of the default feature pipeline. It prepares the repo so later /execute execution can run under Ralph with bounded iterations, explicit feedback loops, and durable GitHub-backed state.

What This Sets Up

• ralph-once.sh for one-iteration HITL Ralph
• ralph.sh for bounded AFK Ralph runs
• Optional package.json scripts for convenient invocation
• Repo-local loop prompts that tell Ralph to prefer the highest-risk unblocked slice, run feedback loops, and stop when work is done

Rules Before Setup

• Ralph is an execution mode for /execute, not a separate workflow.
• Start with HITL Ralph first. Only go AFK after the prompt, feedback loops, and quality bar are behaving well.
• Ralph's durable progress state in this workflow lives in GitHub issues, issue comments, and commits — not in progress.txt or other local task-state files.
• Each iteration should implement exactly one reviewable slice.
• Every AFK loop must be bounded. Do not generate an infinite loop.

Steps

1. Confirm task source and state model

Ask where Ralph should read work from.

Prefer this order:

1. GitHub issues with dependency relationships
2. Another durable backlog system the repo actually uses
3. A temporary fallback file only if the user explicitly wants it

If the repo uses GitHub issues, keep Ralph GitHub-native:

• open PRD issues define the end state
• slice issues define the current work queue
• issue comments carry exact errors or partial-progress context
• commits are the execution log

Do not introduce progress.txt as durable state unless the user explicitly chooses to deviate from the repo's GitHub-first model.

2. Detect feedback loops

Inspect the target repo before generating scripts.

Check for available commands in package.json or equivalent tooling:

• typecheck
• test
• lint
• build

Also note whether the repo already has:

• /setup-pre-commit
• container or sandbox tooling
• GitHub CLI configured

The generated Ralph prompt should only name feedback loops that actually exist.

3. Detect execution environment

Ask whether Ralph should run:

• in the current repo shell
• in a sandboxed shell or container
• through an existing task runner such as pnpm

Default recommendation:

• HITL first in the current repo
• AFK in a sandboxed or isolated environment when possible

4. Generate ralph-once.sh

Create a one-iteration script for supervised use first.

The script should:

• run exactly one Ralph iteration
• point Ralph at the task source
• compute the unblocked set in the script, and tell Ralph to pick the highest-risk slice from it
• tell Ralph to use /execute
• tell Ralph to run the repo's real feedback loops
• tell Ralph to stop after one reviewable slice

Suggested shape:

#!/bin/bash
set -e

# Compute the frontier in bash rather than asking the model to reconstruct it
# by reading `Blocked by` prose out of N issue bodies. Native GitHub issue
# dependencies (wired by /prd-to-issues §7) make this a lookup; filtering to
# OPEN blockers keeps it current with no bookkeeping.
#
# `gh issue list` excludes pull requests by definition, so no filter is
# needed. `state` is the GraphQL enum: uppercase OPEN, not REST's lowercase.
FRONTIER=$(gh issue list --state open --limit 100 --json number,blockedBy \
  --jq '[.[]
        | select([.blockedBy.nodes[] | select(.state == "OPEN")] | length == 0)
        | .number] | join(", ")')

if [ -z "$FRONTIER" ]; then
  echo "No unblocked issues — either all work is done, or the graph has a cycle."
  exit 0
fi

claude --message "Unblocked GitHub issues, takeable right now: $FRONTIER. Pick the highest-risk one of those that still needs implementation. Use /execute to implement exactly one reviewable slice. Run the repo's feedback loops. If all issue work is complete, say DONE and stop."

Adapt the prompt to the actual task source and available commands.

Handing the model a computed candidate set — rather than the instruction "respecting blocking relationships" — is the point of this shape. An instruction to honor a graph the model must first reconstruct from prose has no mechanism behind it, and its failure mode is a plausible-looking wrong slice rather than an error. AFK is the stage with nobody watching, so it is the stage least able to absorb that. Deterministic selection stays in bash; the judgment call the model is actually good at (which of these candidates is riskiest) stays in the prompt.

If the repo's slice issues predate native dependency wiring, $FRONTIER will list everything. Check before trusting it: if every open issue reports .blockedBy.totalCount == 0 while bodies carry prose Blocked by #N lines, no edge was ever written. Wire the edges first — see /prd-to-issues §7 — or the loop is back to guessing. AFK is the stage least able to absorb that, because nobody is watching the wrong slice get picked.

5. Generate ralph.sh

Create a bounded AFK loop.

The script must:

• require an iteration count argument
• fail fast if no argument is given
• run one iteration per loop
• avoid while true
• keep the same task-picking logic as ralph-once.sh

Suggested shape:

#!/bin/bash
set -e

if [ -z "$1" ]; then
  echo "Usage: $0 <iterations>"
  exit 1
fi

for ((iteration=1; iteration<=$1; iteration++)); do
  # Recompute each iteration — closing a blocker un-gates its dependents,
  # so the frontier grows as the loop makes progress.
  FRONTIER=$(gh issue list --state open --limit 100 --json number,blockedBy \
    --jq '[.[]
          | select([.blockedBy.nodes[] | select(.state == "OPEN")] | length == 0)
          | .number] | join(", ")')

  if [ -z "$FRONTIER" ]; then
    echo "No unblocked issues — stopping after $((iteration - 1)) iteration(s)."
    break
  fi

  claude --message "Unblocked GitHub issues, takeable right now: $FRONTIER. Pick the highest-risk one of those that still needs implementation. Use /execute to implement exactly one reviewable slice. Run the repo's feedback loops. If all issue work is complete, say DONE and stop."

  echo "Ralph iteration $iteration complete."
done

Recomputing the frontier inside the loop is what makes the graph load-bearing across iterations: a slice that was blocked at iteration 1 becomes takeable the moment its blocker closes, with no edit to any issue body.

If the user wants, also add convenience scripts to package.json, for example:

{
  "scripts": {
    "ralph:once": "./ralph-once.sh",
    "ralph": "./ralph.sh 5"
  }
}

Use a small default iteration count if adding a package script.

6. Encode the quality bar explicitly

Make sure the generated loop prompt states the repo's quality expectations clearly.

The prompt should say Ralph must:

• implement one reviewable slice at a time
• run feedback loops each iteration
• avoid silent scope changes
• prefer risky slices early when unblocked
• leave exact error output in issue comments when blocked
• stop and escalate after repeated failure instead of retrying forever
• stop and escalate after repeated non-progress (plateau), not just repeated failure — non-progress means two consecutive iterations on the same slice where no unmet acceptance criterion, failing check, or unresolved unknown transitioned to resolved; one recovering iteration resets the counter. See /execute "AFK progress and plateau detection" and references/SYSTEM-OVERVIEW.md (bundled alongside this skill) for the full rule.
• after implementation, run review in /pre-merge loop-mode — an AFK iteration is finished when every review finding has a row in the PR's disposition ledger, not when the code is committed
• record findings; do not act on them. Loop-mode makes no commits and settles nothing: fixing, filing, accepting, and dropping are the operator's calls, made against the ledger in the morning
• never treat "the review came back clean" as the reason to stop — a loop that exits on clean reviews will produce clean reviews rather than better code

Do not add a review phase to ralph.sh yet. Loop-mode is entered from /execute Step 6's AFK exit, which is enough to prove it. Wiring it into the script as an explicit post-implementation phase is deferred until the loop has run HITL-first — the same HITL-before-AFK rule that governs Ralph itself (Step 8 below).

If the repo is clearly long-lived production code, say so explicitly in the prompt.

7. Verify the generated setup

Check:

• ralph-once.sh exists and is executable
• ralph.sh exists and is executable
• package.json scripts were added correctly, if requested
• the generated prompt references the real task source
• the generated prompt references only real feedback loops
• no progress.txt was introduced unless the user explicitly asked for it

On completion: Create the Ralph marker so enforcement hooks know setup was done.

mkdir -p "$CLAUDE_PROJECT_DIR/.claude" && touch "$CLAUDE_PROJECT_DIR/.claude/.ralph-checked"

8. Recommend first usage

Instruct the user to:

1. run ./ralph-once.sh first
2. review the result
3. refine the prompt if task selection or quality is off
4. only then run bounded AFK Ralph such as ./ralph.sh 5

Verification

Before considering setup complete, check:

• Ralph has a HITL entrypoint
• Ralph has a bounded AFK entrypoint
• The AFK loop does not run infinitely
• Task selection is risk-first, not just list-order-first
• The prompt uses /execute
• The prompt names real feedback loops from the repo
• Durable state remains GitHub-native unless the user explicitly chose otherwise

Handoff

• Expected input: a repo that wants repeatable Ralph execution around /execute
• Produces: working Ralph loop scripts and repo-local conventions for HITL-first, bounded AFK execution
• Supports downstream: /execute, /pre-merge, and GitHub-issue-based execution by making AFK work safer and more repeatable
• What comes next: return to normal feature work, first by trying ralph-once.sh, then by using bounded AFK Ralph when the setup proves reliable