home / skills / tomkrikorian / visionosagents / ralph-driven-development

ralph-driven-development skill

unsafe

This skill guides you to set up and operate Ralph Driven Development workflows, tailoring plan, specs, and completion tracking for efficient AI-driven coding.

npx playbooks add skill tomkrikorian/visionosagents --skill ralph-driven-development

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

3.5 KB

---
name: ralph-driven-development
description: Guide and tooling for Ralph Driven Development (RDD), a spec runner that repeatedly invokes Codex (or other agents) over ordered specs until a magic phrase signals completion. Use when setting up or operating an RDD workflow with plan.md, specs/, done.md, agent-run.log, and a ralph.py runner, or when customizing the runner CLI and prompt contract.
---

# 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)

```bash
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

```bash
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`.

Overview

This skill guides and provides tooling for Ralph Driven Development (RDD), a spec-runner workflow that repeatedly invokes an AI agent over ordered specs until a magic phrase signals completion. It helps you set up plan.md, specs (docs/tasks), done.md, and a runnable ralph.py to automate, track, and resume agent-driven work cycles.

How this skill works

The runner reads ordered spec files from docs/tasks, skips those listed in docs/done.md, and invokes your agent (e.g., Codex) with a prompt contract that requires a commit and prints a configured magic phrase on completion. Console markers and a persistent log record [start], [done], [retry], and [skip] events and append completed specs to docs/done.md. The runner handles rate-limit sleep/retry and can be customized via CLI flags.

When to use it

Setting up a reproducible AI-driven development pipeline for incremental tasks.
Automating repetitive agent runs across ordered specs until explicit completion.
Resuming interrupted work without re-running completed tasks.
Experimenting with prompt contracts and agent configurations for codex-like models.
Tracking agent progress with human-readable logs and completion markers.

Best practices

Author small, focused spec files in docs/tasks with deterministic filenames for ordering.
Define a clear magic phrase and require the agent to print it only when the spec is truly complete.
Keep docs/done.md machine-appended only; use it as the single source of completed work to enable resumption.
Log full agent output to docs/logs/agent-run.log for postmortem and troubleshooting.
Use CLI flags to pin the agent binary, model args, and magic phrase for consistent runs.

Example use cases

Bootstrapping a visionOS feature set by iterating tasks in docs/tasks until each spec prints SPEC_COMPLETE.
Running daily maintenance or migration steps where each step must confirm completion explicitly.
Testing prompt contract changes by rerunning only unfinished specs after adjusting ralph.py or arguments.
Recovering from API rate limits automatically: the runner sleeps and retries until the agent can proceed.

FAQ

How do I resume after the process was interrupted?

Rerun the runner; it reads docs/done.md and skips any specs already listed, continuing from the next unfinished spec.

What if the agent never prints the magic phrase?

The runner emits [retry] and logs the full output to docs/logs/agent-run.log. Inspect logs, refine the prompt contract, and re-run the spec.