Ralph Loop
Ralph is a standalone zx script that drives AI coding agents (Claude, Amp, Codex, OpenCode) through iterative development cycles. Write a task prompt, ralph handles everything else — environment discovery, context assembly, AI invocation, quality gates, git commits, and inter-iteration communication via a status report.
Routing
Determine what the user needs and consult the right reference:
| User wants to... | Reference |
|---|---|
| Write or refine a prompt (primary use case) | references/prompt-writing-guide.md — follow the Interactive Prompt-Writing Guide |
| Set up Docker environment | references/docker-setup.md |
| Initialize, run, or reset a loop | references/loop-lifecycle.md |
| Configure tool, iterations, or quality checks | references/config-reference.md |
| Understand or troubleshoot status reports | references/status-report-guide.md |
If the user describes something they want to build (a feature, fix, or task) without explicitly asking for setup — route to the prompt-writing guide.
Prompt Writing (Primary Workflow)
Follow the interactive guide in references/prompt-writing-guide.md. The short version:
- Clarify the Goal — specific, includes the "why". Ask if vague or ambiguous.
- Scope the Tasks — each ≈ one iteration. Split large, condense small.
- Discover Constraints — tools, off-limits files, conventions, references.
- Define "Done" — concrete commands and expected output.
Stop after each step to collect user input. Use AskUserQuestion for disambiguation.
Assemble the final prompt, present for review, then write to docs/ralph-loop/ralph-prompt.md.