Ralph (deprecated)

Ralph runs the /flow-next:work loop overnight: a fresh agent session per iteration, multi-model review gates, auto-block on stuck tasks, and receipt-based proof-of-work. It is an external shell loop (ralph.sh) that needs no host loop primitive at all, so it is cron-able on a headless server.

Deprecated

A shell script calling /flow-next:pilot to build and /flow-next:land to ship, driven by a host loop or cron, does what this harness does, without the scripts/ralph/ scaffold, the guard-hook registration, or the second receipt plumbing. Ralph predates those primitives.

Nothing is removed and nothing breaks. Existing installs keep working and this page stays maintained as their reference. New setups should use pilot + land. See Running Lean.

flowchart TB
  Loop["External shell loop"] --> Fresh["Fresh agent session"]
  Fresh --> Ready["Next ready task"]
  Ready --> Work["Work"]
  Work --> Review["Review gate"]
  Review -->|SHIP| Next["Next task"]
  Review -->|NEEDS_WORK| Work
  Review -->|blocked| Stop["Stop and hand over"]

Long-lived autonomous sessions accumulate failed attempts and stale assumptions. Ralph starts a fresh session every iteration, re-anchors against repo state, and gates progress on receipts.

Should you still use it?

Ralph consumes specs that are already planned: it iterates plan-review → work → impl-review → completion review and never runs the planning fan-out. Reach for it when the run is long enough that fresh-session isolation matters (a multi-day backlog, where /loop jobs also expire after 7 days), when you want hook-enforced guardrails rather than prose ones, or when there is no interactive host to own the loop. Otherwise pilot covers more of the lifecycle with less scaffolding.

	Ralph	Pilot
Scope	fully planned spec → work → reviews (never plans)	ready spec → plan → reviews → work → [opt-in qa] → draft PR; opt-in backlog mode widens selection to the whole open backlog
Loop owner	External shell script (ralph.sh)	Host /loop or /goal
Session	Fresh per iteration	In-session ticks
Proof-of-work	Receipts on disk	PILOT_VERDICT lines in the transcript
Guard hooks	ralph-guard, DCG	None (FLOW_AUTONOMOUS, not FLOW_RALPH)
Stuck handling	Auto-block after N failures	Two strikes → spec unready
Best for	Overnight, unattended scale	In-session backlog draining

The two are alternative drivers for the same pipeline and are never nested: pilot refuses to run under FLOW_RALPH. Land picks up after either, at the open PR.

Ralph is optional, and so is every other loop. The main Flow-Next workflow is still spec, task graph, review, receipt, PR. Use Ralph when those artifacts are crisp enough that an autonomous loop can safely continue without product judgment.

Initialize

/flow-next:ralph-init

This scaffolds the repo-local harness under scripts/ralph/:

• scripts/ralph/ralph.sh
• scripts/ralph/ralph_once.sh
• scripts/ralph/ralphctl.py (pause / resume / stop / status, moved out of flowctl in 3.0)
• scripts/ralph/config.env
• scripts/ralph/runs/

…and registers the guard hooks into the PROJECT settings, with your platform’s consent prompt as the gate. Since 3.0 the plugin itself ships zero hooks. Nothing Ralph-related runs anywhere until ralph-init sets it up, and re-running /flow-next:setup can strip it back out. Upgrading from 2.x with an existing Ralph setup? Re-run /flow-next:ralph-init once - the old plugin-level hooks are gone and the guard will not fire without re-registration.

Always run one iteration interactively before an overnight run:

scripts/ralph/ralph_once.sh

Run and watch

scripts/ralph/ralph.sh                  # loop until the spec ships or the cap hits
scripts/ralph/ralph.sh --watch
scripts/ralph/ralph.sh --watch verbose

Watch mode keeps the Ralph terminal readable during a long run: it shows the current task, review state, receipts, and stop reason without a separate global TUI install.

Review gates

Configure in scripts/ralph/config.env:

REQUIRE_PLAN_REVIEW=1
PLAN_REVIEW=codex
WORK_REVIEW=codex

Supported review backends include RepoPrompt, Codex, Copilot, Cursor, and none. Production Ralph runs should use a real review backend.

The execution contract

Ralph does not invent new scope. Each loop must:

1. Re-read the spec and ready task.
2. Check current git state.
3. Execute only the ready work.
4. Run configured review.
5. Record receipt state.
6. Stop on blocker, missing requirement, or unsafe ambiguity.

flowchart LR
  Ready["Ready task"] --> Execute["Fresh execution"]
  Execute --> Review["Review backend"]
  Review --> Receipt["Receipt"]
  Receipt -->|pass| Continue["Continue"]
  Receipt -->|block| Human["Human handover"]

Stop conditions:

• Review verdict is not shippable.
• Required command or tool is unavailable.
• The ready task requires a decision outside the spec.
• The selected spec has no tasks yet: flowctl next reports reason: needs_tasks and the iteration stops typed as NEEDS_TASKS. Ralph consumes planned specs, so plan the spec — or, when it is genuinely too small to plan, take the no-plan route (interactively, or mark the spec with flowctl spec set-no-plan and run /flow-next:work) — and start the run again.
• Git state is unexpectedly dirty.
• Evidence cannot be produced.
• Iteration cap is reached.

A clean stop is success. It preserves the handover so a human can decide the next step.

Guardrails

• Fresh context. Each iteration starts from a fresh agent session, then re-anchors against repo state.
• Receipt gates. Ralph does not trust a model saying “done”. It checks receipts written by review commands.
• Multi-model review. Implementation is checked by a different model through the configured backend, and introduced findings gate the verdict.
• No autonomous product decisions. /flow-next:strategy, /flow-next:prospect, /flow-next:chart, and /flow-next:capture are user-triggered surfaces; Ralph does not decide what to build. Chart can be driven by a host loop for its unattended evidence routes, but an attended decision (prototype, interview) terminates CHART_VERDICT=NEEDS_HUMAN rather than answering itself, which is the same consent boundary one stage earlier.

flowchart TB
  Spec["Reviewed spec"] --> Ready["Ready task only"]
  Ready --> Fresh["Fresh session"]
  Fresh --> Evidence["Evidence commands"]
  Evidence --> Receipt["Review receipt"]
  Receipt --> Continue["Continue or stop"]

Five decisions stay human-owned. Ralph does not decide whether a feature belongs in the product, whether a risky migration is acceptable, whether to merge, whether to ignore a security finding, or whether undocumented behavior is acceptable. Those belong in the spec, the review notes, or your merge decision.

Good and bad candidates

Good:

• Mechanical follow-through after a reviewed spec.
• Multi-task docs or test expansion with clear acceptance criteria.
• Refactors with bounded file ownership and strong tests.
• Dependency-ordered work where failures can block cleanly.

Bad:

• Ambiguous product decisions.
• UI taste work without fresh screenshots and review.
• Security-sensitive changes without human review before implementation.
• Specs with many [inferred] requirements.
• Work where tests cannot verify the outcome.

If the spec needs judgment, run /flow-next:interview or /flow-next:plan-review first.

Production defaults

• Require plan review for risky specs.
• Require implementation review with a real backend.
• Keep iteration caps low until the repo has strong tests.
• Prefer one spec branch per Ralph run.
• Review generated PR bodies before merge.

In teams, run Ralph after product and technical ownership have already happened:

/flow-next:interview fn-1 --scope=business
/flow-next:interview fn-1 --scope=technical
/flow-next:plan-review fn-1
scripts/ralph/ralph_once.sh

Ralph is an execution loop, so it is not a substitute for product clarification. It is powerful when the workflow is already disciplined, and without crisp specs and review gates it only makes drift faster.