| name | ralph-loop |
| description | Use when the user asks to "write a ralph prompt", "build something with ralph", "create a ralph loop", "set up ralph", "initialize ralph", "start a new ralph project", "run ralph", "configure ralph", "instantiate a ralph loop", or describes a feature, task, or project they want to build autonomously. The primary workflow is an interactive prompt-writing guide that helps users craft high-quality task prompts through structured clarification. Also covers setup, initialization, and execution. |
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.
