Ralph Overview

Ralph is Flow-Next’s repo-local autonomous harness.

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"]

Ralph exists because long-lived autonomous sessions accumulate failed attempts and stale assumptions. Flow-Next instead starts fresh, re-anchors, and gates progress on receipts.

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

Ralph is not the only autonomous driver: /flow-next:pilot is the in-session alternative — a single-tick conductor your host’s /loop or /goal drives, with transcript verdicts instead of receipts. The two are alternative drivers for the same pipeline and are never nested.

Initialize

/flow-next:ralph-init

This creates:

• scripts/ralph/ralph.sh
• scripts/ralph/ralph_once.sh
• scripts/ralph/config.env
• scripts/ralph/runs/

Always run one iteration before an overnight run:

scripts/ralph/ralph_once.sh

Good Ralph candidates

• 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 Ralph candidates

• 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.