ralph-driven-development

Automate Codex runs against ordered specs until a magic phrase signals completion.

60|8|Updated Dec 23, 2025

Search Tags:#automation #logging #Codex #plan.md #specs #RDD #spec-runner

Ready to run

npx skills add https://github.com/tomkrikorian/visionOSAgents --skill ralph-driven-development

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: ralph-driven-development
Source: https://github.com/tomkrikorian/visionOSAgents/tree/main/skills/ralph-driven-development
Command: npx skills add https://github.com/tomkrikorian/visionOSAgents --skill ralph-driven-development

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve?

Ralph Driven Development (RDD) automates running Codex against a sequence of specifications until a magic phrase signals completion, reducing manual task switching and cognitive load.

Core Features & Use Cases

Workflow setup: create plan.md, specs/ directory, and done.md to organize tasks and track progress.
Execution engine: iterate over ordered specs, invoke Codex, and commit progress when a spec is finished.
Progress tracking: logs agent runs to agent-run.log and records completed specs in done.md for resumable workflows.
Use Case: A team defines a plan and a series of specs; the runner processes each spec until completion, writing learnings to AGENTS.md.

Quick Start

uv run python scripts/ralph.py

Frequently Asked Questions about ralph-driven-development

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I automate running Codex against a sequence of specifications?▼

To automate Codex against specifications, define a plan.md and specs/ directory, then run the provided ralph.py script. The runner iterates over ordered specs, invoking Codex until a magic phrase signals completion and committing progress for resumable workflows.

What is Ralph Driven Development and how does it reduce manual task switching?▼

Ralph Driven Development (RDD) is an automated workflow that processes ordered specifications through Codex until a completion signal is triggered. It reduces manual task switching by logging runs to agent-run.log and tracking completed specs in done.md for resumable execution.

How do I track progress and handle interruptions during AI-driven development?▼

You track progress and handle interruptions by logging agent runs to agent-run.log and recording completed specifications in done.md. This enables resumable workflows so the runner can pick up exactly where it left off after any interruption.

Do I need specific files to set up an iterative AI development workflow?▼

Yes, setting up the workflow requires creating a plan.md to organize tasks, a specs/ directory for the ordered specifications, and a done.md file to track progress. These files enable the automated runner to process tasks sequentially and commit learnings to AGENTS.md.

Can I use this automated spec runner for team-based development workflows?▼

Yes, a team can define a plan and a series of specs for the runner to process. As each specification is completed, the runner commits progress and writes accumulated learnings to AGENTS.md, supporting collaborative AI-driven development.

What are the limitations of automating AI workflows with a magic phrase completion signal?▼

The runner relies on a specific magic phrase to signal spec completion, meaning incomplete or ambiguous AI outputs will not trigger the next phase. Workflows are constrained to the defined plan.md and specs/ structure, requiring manual intervention if the sequence deviates.