ralph

Ralph — Autonomous Agent Loop

Ralph runs iteratively until all PRD stories are complete. Each iteration: picks highest priority story, implements, runs quality checks, commits if passing, updates progress, repeats.

When to Use

• Large features that exceed a single context window
• Multi-story PRDs that need consistent implementation
• Tasks requiring repeated verification and commit cycles
• Long-running development that benefits from persistence across interruptions

Do NOT Use When

• Task is a one-shot fix completable in a single edit — just edit the file
• You haven't written a PRD yet — write the PRD first, then run Ralph against it
• The work spans fewer than 3 stories — single-iteration verification is enough
• You need to explore or plan before committing to scope — use a planning skill first; Ralph is for execution, not discovery
• You want manual control over each iteration — run quality checks yourself, no need for Ralph's loop

Prerequisites

• Git repository
• PRD document (markdown format)
• jq installed (brew install jq on macOS)

Workflow

1. Create a PRD

Generate a detailed requirements document using the PRD skill:

Load the prd skill and create a PRD for [your feature description]

Output saved to tasks/prd-[feature-name].md

CRITICAL — refine generic criteria before iteration begins. Auto-generated PRD scaffolds often produce generic acceptance criteria like ["Implementation is complete", "Code compiles without errors"]. These are theater — Ralph cannot prove a story passes against criteria that don't actually constrain it. Replace every generic criterion with a concrete, testable statement before moving to step 2.

• Bad: "Function is implemented correctly"
• Good: "Function parseUserInput(s) returns {ok: true, value} for valid s and {ok: false, error} for invalid s, asserted by tests/parse-user-input.test.ts"
• Bad: "Code compiles"
• Good: "TypeScript compiles with no errors (npm run build) AND lsp diagnostics show 0 errors on src/parse-user-input.ts"