Ralph Driven Development (RDD)

Description and Goals

Ralph Driven Development (RDD) is a spec runner that repeatedly invokes Codex (or other agents) over ordered specs until a magic phrase signals completion. It automates the execution of development tasks by running an AI agent against a sequence of specifications until each one is completed.

Goals

• Automate development workflow by running AI agents against specifications
• Track progress through ordered specs and completion markers
• Enable resumable workflows that can continue after interruptions
• Provide customizable runner configuration for different agents and workflows
• Support structured development with plan, specs, and completion tracking

What This Skill Should Do

When setting up or operating an RDD workflow, this skill should:

1. Guide workflow setup – Help you create plan.md, specs directory, and done.md files
2. Configure the runner – Show how to customize ralph.py for your agent and workflow
3. Execute specs – Run the agent against ordered specifications until completion
4. Track progress – Monitor completion status and log agent runs
5. Handle interruptions – Enable resuming workflows after breaks or errors

Use this skill when setting up or operating an RDD workflow with plan.md, specs/, done.md, agent-run.log, and a ralph.py runner.

Information About the Skill

What You Have

• docs/specifications.md: the product plan and architecture overview.
• docs/tasks/0001-...: incremental work units.
• scripts/ralph.py: Python runner (execute directly from the skill folder).

Quick Start (Python + uv)

uv run python scripts/ralph.py

How It Works

1. Read docs/tasks/ for spec files and sort by filename order.
2. Skip completed specs listed in docs/done.md.
3. Invoke Codex with a prompt that:
   • follows the spec,
   • commits on completion,
   • records useful learnings in AGENTS.md,
   • prints the magic phrase when done.
4. Move to the next spec only after the magic phrase appears.
5. Sleep on usage limit errors until reset, then retry.

Progress Tracking

• Show live console output:
  • [start] when a spec begins,
  • [done] when a spec completes,
  • [retry] when no magic phrase is found,
  • [skip] when a spec is already in docs/done.md.
• Append full logs to docs/logs/agent-run.log.
• Append completed specs to docs/done.md.

Resume After Interruptions

Rerun the script; it skips specs already listed in docs/done.md.

Customize Defaults

Python + uv

uv run python scripts/ralph.py \
  --magic-phrase SPEC_COMPLETE \
  --codex-exe codex \
  --codex-args "exec --dangerously-bypass-approvals-and-sandbox -m gpt-5.2-codex"

Troubleshooting

• Handle usage limits by sleeping until reset time and retrying.
• Inspect docs/logs/agent-run.log for repeated failures.
• Ensure codex is on PATH if not found.

Where to Start

Create the plan in docs/specifications.md and some docs/tasks/... files for incremental work, then run the runner. Start at the first spec not listed in docs/done.md.