Back to prompts

Ralph Loop Bootstrap

Set up a self-perpetuating RALPH LOOP with GitHub Actions, state files, and guard constraints.

Ralph Loop Updated Jan 15, 2026
Your task: set up a self-perpetuating **RALPH LOOP** in the current repo, modeled after the reference "ralph" repo pattern.

## Outcome
Create the minimal files + GitHub Actions workflow so the loop can run one iteration at a time:
- read state from files
- choose exactly one story
- implement minimal change
- enforce guard constraints
- commit + push
- push re-triggers the workflow until no todo stories remain or PAUSED is true

## Non-negotiables
- One story per run. Small commits.
- Never commit if guard fails.
- Keep `AGENTS.md` short (~70 lines). Only include repeated-footgun info.
- Persistent memory is ONLY repo files + git commits (no hidden memory).
- Prefer docs-only scaffolding first; don't add deps unless a story requires it.

## Create these files (if missing)
- `AGENTS.md`
- `.opencode/opencode.json`
- `scripts/ralph/prd.json`
- `scripts/ralph/progress.txt`
- `scripts/ralph/constraints.json`
- `scripts/ralph/failure.json`
- `scripts/ralph/guard.sh` (diff guard enforcing constraints)
- `.github/workflows/ralph.yml`
- `README.md` (briefly explains the RALPH LOOP + how to run)

## RALPH LOOP rules (how to operate each iteration)
1) Load `AGENTS.md` and state files in `scripts/ralph/`
2) If `- PAUSED: true` → exit immediately
3) In `prd.json`, pick the first story with `"status": "todo"` (or highest priority todo)
4) Mark it `"doing"`
5) Implement minimal changes to satisfy the story acceptance criteria
6) Run verification (if the story specifies commands; otherwise keep docs-only)
7) Run `bash scripts/ralph/guard.sh scripts/ralph/constraints.json`
8) If green:
   - mark story `"done"` in `prd.json`
   - append learnings to `progress.txt`
   - commit + push with a bot identity
9) If failure:
   - update `failure.json` (increment consecutiveFailures, store run URL + timestamp)
   - if failures exceed `MAX_FAILURE_RETRIES`, set `- PAUSED: true` in `AGENTS.md`
   - commit + push failure state so the next run can retry (unless paused)

## Initial PRD requirements
Initialize `scripts/ralph/prd.json` with 3–6 tiny stories:
- S1: Boot Ralph automation scaffold (files + workflow)
- S2: Add/verify diff guard in CI
- S3: Make README describe how to run
(keep them small enough for one run each)

## Workflow requirements
- Trigger on `workflow_dispatch` AND on pushes to `AGENTS.md` and `scripts/ralph/**`
- Auto-run only on bot pushes (manual dispatch always allowed)
- Use a PAT secret for checkout/push (do not hardcode tokens)
- Install Node + jq + OpenCode
- Run exactly one agent iteration with OpenCode using:
  `AGENTS.md`, `prd.json`, `progress.txt`, `constraints.json`, `failure.json`
- Validate JSON, run guard, then commit + push

Now implement the scaffold in this repo.

How to use this prompt

  1. Copy the prompt using the button above
  2. Paste it into your preferred AI coding assistant
  3. Adjust any placeholders or context as needed
  4. Let the agent implement the changes