ralph-loop

Ralph Loop

Overview

Generate a ready-to-run bash script that runs an AI coding CLI in a loop. Align with the Ralph playbook flow:

1. Define requirements → JTBD → topics of concern → specs/*.md
2. PLANNING loop → create/update IMPLEMENTATION_PLAN.md (no implementation)
3. BUILDING loop → implement tasks, run tests (backpressure), update plan, commit

The loop persists context via PROMPT.md + AGENTS.md (loaded every iteration) plus the on-disk plan/specs.

Workflow

1) Collect inputs (ask if missing)

• Goal / JTBD (what outcome is needed)
• CLI (codex, claude-code, opencode, goose, other)
• Mode: PLANNING, BUILDING, or BOTH
• Completion condition
  • Promise phrase (string to detect), or
  • Test/command to run each iteration, or
  • Plan sentinel (e.g., a line STATUS: COMPLETE in IMPLEMENTATION_PLAN.md)
• Max iterations
• Sandbox choice (none | docker | other) + security posture
• Backpressure commands (tests/lints/build) to embed in AGENTS.md
• Auto‑approve flags (ask explicitly)
  • Codex: --full-auto
  • Claude Code: --dangerously-skip-permissions

2) Phase 1 — Requirements → specs

If the user wants “full Ralph” (or unclear requirements), do this before the loop:

• Break the JTBD into topics of concern (1 topic = 1 spec file).
• For each topic, draft specs/<topic>.md.
• Use subagents to load URLs or existing docs into context for spec quality.
• Keep specs short and testable.

3) Phase 2/3 — PROMPT.md + AGENTS.md

• Context loaded each iteration: PROMPT.md + AGENTS.md.
• AGENTS.md should include:
  • project test commands (backpressure)
  • build/run instructions
  • any operational learnings
• PROMPT.md should reference:
  • specs/*.md
  • IMPLEMENTATION_PLAN.md
  • any relevant project files/dirs

4) Two prompt templates (PLANNING vs BUILDING)

Create two prompts and swap PROMPT.md based on mode.

PLANNING prompt (no implementation):

You are running a Ralph PLANNING loop for: <JTBD/GOAL>.

Read specs/* and the current codebase. Do a gap analysis and update IMPLEMENTATION_PLAN.md only.
Rules:
- Do NOT implement.
- Do NOT commit.
- Prioritize tasks and keep plan concise.
- If requirements are unclear, write clarifying questions into the plan.

Completion:
If the plan is complete, add line: STATUS: COMPLETE

BUILDING prompt:

You are running a Ralph BUILDING loop for: <JTBD/GOAL>.

Context:
- specs/*
- IMPLEMENTATION_PLAN.md
- AGENTS.md (tests/backpressure)

Tasks:
1) Pick the most important task from IMPLEMENTATION_PLAN.md.
2) Investigate relevant code (don’t assume missing).
3) Implement.
4) Run the backpressure commands from AGENTS.md.
5) Update IMPLEMENTATION_PLAN.md (mark done + notes).
6) Update AGENTS.md if you learned new operational details.
7) Commit with a clear message.

Completion:
If all tasks are done, add line: STATUS: COMPLETE

5) Build the per‑iteration command

• Codex: codex exec <FLAGS> "$(cat PROMPT.md)"
  • Requires git repo.
• Claude Code: claude <FLAGS> "$(cat PROMPT.md)"
• OpenCode: opencode run "$(cat PROMPT.md)"
• Goose: goose run "$(cat PROMPT.md)" (ask if they want the Goose recipe)

If the CLI is unknown, ask for the exact command to run each iteration.

6) Output a copy‑paste script

Provide either a minimal loop or a controlled loop with max iters + stop conditions.

Minimal loop (Geoff style):

while :; do cat PROMPT.md | claude ; done

Controlled loop (recommended):

#!/usr/bin/env bash
set -euo pipefail

PROMISE='...'
MAX_ITERS=...
CLI_FLAGS="..."  # optional
PLAN_SENTINEL='STATUS: COMPLETE'
TEST_CMD='...'   # optional

if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
  echo "❌ Run this inside a git repo."
  exit 1
fi

touch PROMPT.md AGENTS.md IMPLEMENTATION_PLAN.md
LOG_FILE=".ralph/ralph.log"
mkdir -p .ralph

CLI_CMD="..." # e.g. "codex exec" or "claude"

for i in $(seq 1 "$MAX_ITERS"); do
  echo -e "\n=== Ralph iteration $i/$MAX_ITERS ===" | tee -a "$LOG_FILE"

  $CLI_CMD $CLI_FLAGS "$(cat PROMPT.md)" | tee -a "$LOG_FILE"

  if [[ -n "${TEST_CMD}" ]]; then
    echo "Running tests: $TEST_CMD" | tee -a "$LOG_FILE"
    bash -lc "$TEST_CMD" | tee -a "$LOG_FILE"
  fi

  if grep -Fq "$PROMISE" "$LOG_FILE" || grep -Fq "$PLAN_SENTINEL" IMPLEMENTATION_PLAN.md; then
    echo "✅ Completion detected. Stopping." | tee -a "$LOG_FILE"
    exit 0
  fi

done

echo "❌ Max iterations reached without completion." | tee -a "$LOG_FILE"
exit 1

Safety/Sandbox Guidance (must mention)

• Running with --dangerously-skip-permissions or --full-auto implies trust + risk.
• Recommend a sandbox (docker/e2b/fly) with minimal credentials and restricted network.
• Escape hatches: Ctrl+C to stop; git reset --hard to revert.

Guardrails

• If requirements are unclear, insist on specs before BUILDING.
• If the plan looks stale/wrong, regenerate it (PLANNING loop).
• If backpressure commands are missing, ask for them and add to AGENTS.md.