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

  .