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.