ralph-driven-development_skill

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.