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.

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.