Ralph Workflow

Ralph is a structured coding loop. You write specs with acceptance criteria, Ralph runs a coding agent against them, validates the output, and iterates until everything passes. It's the difference between "build me a thing" and "here's exactly what I need, with tests to prove it works."

The Loop

1. Write specs -- detailed requirements with Given/When/Then acceptance criteria
2. Create ralph.yml -- config for the project
3. Run Ralph -- it spawns a coding agent, runs the spec, validates
4. Iterate -- implement -> test -> validate -> fix, until all criteria pass

Setup Prompt

Set up the Ralph workflow for spec-driven development:

1. Before coding anything, write detailed specs with:
   - Clear requirements
   - Acceptance criteria (Given/When/Then format)
   - Design system docs if relevant
   - Tech stack decisions

2. Create a ralph.yml config for the project

3. Run Ralph in a PTY session with the spec

4. Ralph loops: implement -> test -> validate -> fix until all
   acceptance criteria pass

5. Report results back to me

Key principle: front-load the documentation. Better specs = better
code on the first pass. Spend 30% of the time on specs and 70%
on implementation, not the other way around.

What I Learned

• Write spec docs before starting Ralph. It works dramatically better with detailed specs.
• Include design system docs -- colors, spacing, component patterns. Reduces iteration.
• Given/When/Then format for acceptance criteria. Unambiguous.
• Ralph can run for a long time. Use background mode with generous timeouts.
• You can chain tasks -- e.g., "fix broken tests, then build CRM feature, then add admin dashboard."