tomrford/ralpher
Overview
This skill scaffolds a Ralph loop to run Codex in an autonomous while loop for iterative development. It generates a ralph/ directory with a run script, prompt, status, and summary files configured for repeated Codex executions. Use it to bootstrapped autonomous workflows with configurable max iterations and simple progress tracking.
How this skill works
The skill creates a ralph/ subdirectory and four files: run.sh (the loop driver), prompt.md (instructions Codex follows), status.md (status and memory), and an empty summary.md (iteration output). The run script executes Codex repeatedly, checks status.md for Done/Blocked/In Progress, prints summaries, and stops on completion, blockage, or after MAX_ITERATIONS. You provide spec filenames and optional MAX_ITERATIONS; the prompt references those specs and enforces quality gates and test writing.
When to use it
- You want an automated Codex-driven loop to iteratively implement or improve code.
- You need a repeatable scaffolding to run autonomous development cycles with progress tracking.
- You want to enforce quality gates (typecheck, lint, tests, format) every iteration.
- You need a simple on-disk status mechanism to decide when to stop the loop.
Best practices
- Place spec file paths relative to the project root when configuring the prompt.md reference.
- Make ralph/run.sh executable (chmod +x) and pass MAX_ITERATIONS when longer runs are expected.
- Keep status.md authoritative: set Status to Done/Blocked/In Progress and record key learnings under Memory.
- Require the agent to run full quality gates and produce tests or property-based checks where appropriate.
- Commit meaningful changes when tasks finish and write a one-line summary to summary.md each iteration.
Example use cases
- Scaffold an autonomous assistant to iteratively implement a new feature from specifications until all tasks are Done.
- Run an automated refactor loop that makes small changes, runs tests and linters, and records progress until completion.
- Set up continuous improvement cycles for documentation or test coverage driven by spec files.
- Triaging and resolving a backlog of small tasks where each Codex iteration picks the most important incomplete task.
FAQ
Update ralph/status.md first line to "Status: Done" or kill the process. The run script reads that line each iteration and exits when it sees Done.
How do I supply the spec files the agent should study?
Provide spec filenames (paths relative to project root) when asked to scaffold; the prompt.md is generated to reference those spec files. Ensure they are accessible from the project root.
