Skip to content

docs: center docs on the five jobs and the ralph loops format #52

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kasperjunge merged 1 commit into from
Jun 8, 2026
Merged

docs: center docs on the five jobs and the ralph loops format #52

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
165 changes: 63 additions & 102 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,13 +9,14 @@
<a href="https://ralphify.co/docs/"><img src="https://img.shields.io/badge/docs-ralphify.co%2Fdocs-blue" alt="Documentation"></a>
</p>

**A ralph is a directory that defines an autonomous agent loop.** It bundles a prompt, commands, and any files your agent needs. Ralphify is the CLI runtime that executes them.
**Ralphify runs ralph loops.**

A **ralph loop** is a portable directory that defines an autonomous agent loop — a prompt, the commands to run between iterations, and any files the agent needs. It's an open format ([ralphloops.io](https://ralphloops.io/)): one required file, `RALPH.md`. Ralphify is the CLI that runs it.

```
grow-coverage/
├── RALPH.md # the prompt (only required file)
├── check-coverage.sh # command that runs each iteration
└── testing-conventions.md # context for the agent
├── RALPH.md # the loop definition (required)
└── check-coverage.sh # a command that runs each iteration
```

```markdown
Expand All @@ -26,11 +27,8 @@ commands:
run: ./check-coverage.sh
---

You are an autonomous coding agent working in a loop.
Each iteration, write tests for one untested module, then stop.

Follow the conventions in testing-conventions.md.

## Current coverage

{{ commands.coverage }}
Expand All @@ -40,147 +38,110 @@ Follow the conventions in testing-conventions.md.
ralph run grow-coverage # loops until Ctrl+C
```

That's it. One directory. One command. The agent loops — running commands, building a fresh prompt with the latest output, and piping it to your agent. Every iteration starts with clean context and current data.
Each iteration starts with a **fresh context window** and **current data**: ralphify runs the commands, fills in the `{{ placeholders }}`, pipes the prompt to your agent, and loops. Walk away, come back to a pile of commits.

*Works with any agent CLI. Swap `claude -p` for Codex, Aider, or your own — just change the `agent` field.*

## Why loops

A single agent run can fix a bug or write a function. But the real leverage is **sustained, autonomous work** — campaigns that run for hours, chipping away at a goal one commit at a time while you do something else.

Ralph loops give you:

- **Incremental progress in small chunks.** Each iteration does one thing, tests it, and commits. Small changes are easier to review and safer to ship.
- **Fresh context every iteration.** No context window bloat. The agent starts clean each loop and sees the current state of the codebase — including everything it changed last iteration.
- **Continuous work toward a goal.** The loop keeps running until you hit Ctrl+C or it reaches the iteration limit. Walk away, come back to a pile of commits.
- **No micromanagement.** Define the goal once in the prompt, tune with commands that feed live data back in. The agent figures out what to do next.
- **The prompt is a tuning knob.** When the agent does something dumb, add a rule. Like putting up a sign: "SLIDE DOWN, DON'T JUMP."

### What people build ralphs for

| Ralph | What it does |
|---|---|
| **grow-coverage** | Write tests for untested modules, one per iteration, until coverage hits the target |
| **security-audit** | Hunt for vulnerabilities — scan, find, fix, verify, repeat |
| **clear-backlog** | Work through a TODO list or issue tracker, one task per loop |
| **write-docs** | Generate documentation for undocumented modules, one at a time |
| **improve-codebase** | Find and fix code smells, refactor patterns, modernize APIs |
| **migrate** | Incrementally migrate files from one framework or pattern to another |
| **research** | Deep-dive into a topic — gather sources, synthesize, and build a knowledge base |
| **bug-hunter** | Run the test suite, find edge cases, write regression tests |
| **perf-sweep** | Profile, find bottlenecks, optimize, benchmark, repeat |

The ralph format is intentionally simple — if you've written a skill file or a GitHub Action, you already know how it works. YAML frontmatter for config, markdown body for the prompt, `{{ commands.name }}` placeholders for live data.

## Install

```bash
uv tool install ralphify # recommended
```

Or if you don't have `uv`:

```bash
pipx install ralphify # isolated install via pipx
pip install ralphify # plain pip (use a virtualenv or --user)
pipx install ralphify # or pipx
pip install ralphify # or pip (use a virtualenv)
```

Any of these gives you the `ralph` command.

## Quickstart
---

Scaffold a ralph and start experimenting:
## The five things you do with ralphify

```bash
ralph scaffold my-ralph
```
Everything in ralphify is one of these five jobs. That's the whole tool.

Edit `my-ralph/RALPH.md`, then run it:
### 1. Write a ralph

A ralph is a directory with a `RALPH.md` file. Scaffold one:

```bash
ralph run my-ralph # loops until Ctrl+C
ralph run my-ralph -n 5 # run 5 iterations then stop
ralph scaffold my-ralph
```

### What `ralph run` does

Each iteration:
1. **Runs commands** — executes all commands in the ralph, captures output
2. **Builds prompt** — reads the RALPH.md body, replaces `{{ commands.<name> }}` placeholders with fresh output
3. **Pipes to agent** — runs the agent command with the assembled prompt on stdin
4. **Repeats** — goes back to step 1 with updated data
`RALPH.md` is YAML frontmatter + a markdown prompt. The only required field is `agent`:

### What it looks like
```markdown
---
agent: claude -p --dangerously-skip-permissions
---

Read TODO.md, pick the top unfinished task, implement it fully, commit, then stop.
One task per iteration. No placeholder code.
```
$ ralph run grow-coverage -n 3

▶ Running: grow-coverage
1 command · max 3 iterations
### 2. Feed it live data

── Iteration 1 ──
Commands: 1 ran
✓ Iteration 1 completed (52.3s)
`commands` run before each iteration. Their output replaces `{{ commands.<name> }}` in the prompt, so the agent always sees the current state — test results, coverage, git log, lint output:

```markdown
---
agent: claude -p --dangerously-skip-permissions
commands:
- name: tests
run: uv run pytest -x
---

── Iteration 2 ──
Commands: 1 ran
✗ Iteration 2 failed with exit code 1 (23.1s)
## Test results

── Iteration 3 ──
Commands: 1 ran
✓ Iteration 3 completed (41.7s)
{{ commands.tests }}

──────────────────────
Done: 3 iterations — 2 succeeded, 1 failed
If tests are failing, fix them before starting new work.
```

## The ralph format
When the agent breaks a test, the next iteration sees the failure and fixes it. That's the self-healing feedback loop.

A **ralph** is a directory containing a `RALPH.md` file. Everything the ralph needs lives in that directory — scripts, reference docs, test data, whatever the agent might need.
### 3. Run the loop

```bash
ralph run my-ralph # loops until Ctrl+C
ralph run my-ralph -n 5 # run 5 iterations then stop
```
my-ralph/
├── RALPH.md # the prompt (required)
├── check-coverage.sh # script (optional)
├── style-guide.md # reference doc (optional)
└── test-data.json # any supporting file (optional)
```

**RALPH.md** has YAML frontmatter for configuration and a markdown body that becomes the prompt:

| Frontmatter field | Required | Description |
|---|---|---|
| `agent` | Yes | The agent command to run |
| `commands` | No | List of commands (name + run) whose output fills `{{ commands.<name> }}` placeholders |
| `args` | No | Declared argument names for `{{ args.<name> }}` placeholders |
| `credit` | No | Append co-author trailer instruction to prompt (default: `true`) |

**Commands** run before each iteration. Their output replaces `{{ commands.<name> }}` placeholders in the prompt. Use them for test results, coverage reports, git history, lint output — anything that changes between iterations.
Each iteration: run commands → assemble the prompt → pipe it to the agent → repeat with fresh context.

## The technique
### 4. Steer it while it runs

The Ralph Wiggum technique works because:
The prompt body is re-read from disk every iteration. Edit `RALPH.md` while the loop runs and the agent follows your new rules on the next cycle. When it does something dumb, add a sign:

- **One thing per loop.** The agent picks the most important task, implements it, tests it, and commits. Then the next iteration starts fresh.
- **Fresh context every time.** No context window bloat. Each loop starts clean and reads the current state of the codebase.
- **Progress lives in git.** Code, commits, and a plan file are the only state that persists between iterations. If something goes wrong, `git reset --hard` and run more loops.
```markdown
## Rules

Read the full writeup: [Ralph Wiggum as a "software engineer"](https://ghuntley.com/ralph/)
- Do NOT delete failing tests — fix the underlying code instead.
```

## Share ralphs
### 5. Share and install ralphs

Use [agr](https://github.com/computerlovetech/agr) to install shared ralphs from GitHub:
A ralph is just a directory in the [ralph loops format](https://ralphloops.io/), so it's portable — version it in git, share it, install it. Use [agr](https://github.com/computerlovetech/agr) to install one from GitHub:

```bash
agr add owner/repo/grow-coverage # install a ralph from GitHub
agr add owner/repo/grow-coverage # install a ralph
ralph run grow-coverage # run it by name
```

Ralphs installed by agr go to `.agents/ralphs/` and are automatically discovered by `ralph run`.
---

## Why loops

A single agent run can fix a bug or write a function. The leverage of a ralph loop is **sustained, autonomous work** — running for hours, one commit at a time, while you do something else.

- **Fresh context every iteration.** No context-window bloat. The agent starts clean and reads the current state of the codebase.
- **Commands as feedback.** Live data feeds back into the prompt each loop, so the agent self-corrects.
- **Steer with a text file.** Edit the prompt mid-run to redirect a running agent.
- **Progress lives in git.** Every iteration commits. `git log` shows what happened; `git reset` rolls it back.

Read the original writeup: [Ralph Wiggum as a "software engineer"](https://ghuntley.com/ralph/).

## Documentation

Full documentation at **[ralphify.co/docs](https://ralphify.co/docs/)** — getting started tutorial, format spec, cookbook, CLI reference, and troubleshooting.
Full docs at **[ralphify.co/docs](https://ralphify.co/docs/)** — getting started, the loop lifecycle, CLI reference, and cookbook. The format spec lives at **[ralphloops.io](https://ralphloops.io/)**.

## Requirements

Expand Down
2 changes: 1 addition & 1 deletion docs/cookbook.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ keywords: ralphify cookbook, autonomous coding recipes, RALPH.md examples, docum
!!! tldr "TL;DR"
8 copy-pasteable ralph loops: [autoresearch](#autoresearch), [codebase improvement](#codebase-improvement), [documentation](#documentation-loop), [bug hunting](#bug-hunter), [deep research](#deep-research), [code migration](#code-migration), [security scanning](#security-scan), and [test coverage](#test-coverage). Each is a real, runnable example from the `examples/` directory.

Copy-pasteable setups for common autonomous workflows. Each recipe is a real, runnable ralph from the [`examples/`](https://github.com/computerlovetech/ralphify/tree/main/examples) directory.
Once you know [the five things you do with ralphify](index.md#the-five-things-you-do-with-ralphify), these are starting points to copy. Each recipe is a real, runnable ralph loop from the [`examples/`](https://github.com/computerlovetech/ralphify/tree/main/examples) directory.

All recipes use **Claude Code** as the agent. To use a different agent, swap the `agent` field — see [Using with Different Agents](agents.md).

Expand Down
76 changes: 76 additions & 0 deletions docs/diary/2026-06-08-simplify-docs-five-jobs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
# Diary: Simplify docs around the five jobs and the ralph loops format

Drastically simplify the README and MkDocs documentation so newcomers can understand ralphify fast. Two positioning shifts: (1) ralphify is the **runtime for the ralph loops format** (the open spec at [ralphloops.io](https://ralphloops.io/)), not "an AI tool"; (2) center everything on the five things you actually *do* with ralphify, rather than a sprawl of example use cases.

## Step 1: Reframe README and docs landing around the five jobs

**Author:** main

### Prompt Context

**Verbatim prompt:** "Okay so we need to drastically simplify the documentation, the mkdocs documentation and the readme file. We need to center around the five most valuable jobs to be done that Ralph can do. We also need to make it clear to people that it is using ralphloops.io not AI. Ralph loops that I owe in the standard format. Please identify the five jobs to be done that Ralph can help with and make them very clear and upfront in the documentation because there's way too much now. Simplify it so people can understand it and it will be easy to understand and get started with. Please go do"

**Interpretation:** Cut the documentation down and make it center on five clearly-stated jobs-to-be-done, presented upfront. Stop marketing ralphify as a generic "AI tool" and make clear it runs ralph loops — a standardized, portable format.

**Inferred intent:** Lower the comprehension barrier for new users. The docs had grown heavy with "autonomous AI coding agent" SEO phrasing and eight cookbook recipes, which buried the simple core: ralphify runs ralph loops, and there are only a handful of things you do with it.

### What I did

Started by surveying the existing docs surface: `mkdocs.yml` nav, `/README.md`, `/docs/index.md`, `/docs/getting-started.md`, `/docs/how-it-works.md`, and `/docs/cookbook.md`.

I initially assumed the "five jobs" were five example *use cases* (grow coverage, fix bugs, migrate, etc.) and asked the user to confirm a set via `AskUserQuestion`. The user corrected two things that changed the whole approach:

1. The five jobs are **not** example use cases — they're the five things you do to *create and run ralph loops* (the mechanics of using the tool).
2. The format is the one defined at **https://ralphloops.io/** — a standard format the user owns. Ralphify *uses* that format.

I fetched ralphloops.io via `WebFetch` to ground the framing: the ralph loops format is "a lightweight specification for packaging autonomous agent workflows as portable directories," centered on a single required `RALPH.md` file with agent definition, commands, arguments, and instructions.

With that, I defined the five jobs as the spine of the docs:

1. **Write a ralph** — scaffold a `RALPH.md`
2. **Feed it live data** — `commands` → `{{ commands.<name> }}` placeholders (self-healing feedback)
3. **Run the loop** — `ralph run`
4. **Steer it while it runs** — edit the prompt mid-run
5. **Share and install ralphs** — portable directories / `agr`

Then I rewrote:
- `/README.md` — rewrote around "Ralphify runs ralph loops" + the five jobs, with a link to ralphloops.io as the format spec. Stripped "autonomous AI coding agent" SEO phrasing.
- `/docs/index.md` — rewrote the landing page; the five jobs are now a card grid, each linking to the relevant page. Title/description/keywords reframed around "ralph loops" and ralphloops.io.
- `/docs/getting-started.md` — retitled and reframed the intro around the five jobs; dropped AI-heavy SEO from frontmatter.
- `/docs/cookbook.md` — reframed the intro so recipes are clearly *secondary* starting points you reach for after learning the five jobs.

Verified with `uv run mkdocs build --strict` — exit 0.

### Why

The user's two corrections are positioning decisions: ralphify is a *runtime for an open format*, and the docs should teach the *mechanics* of that format rather than parade use cases. Leading both the README and the docs home with the same five-job structure gives a single, repeated mental model. Linking ralphloops.io in both places makes the "it's a format, not just a tool" point concrete.

### What worked

The card-grid layout in `index.md` (reusing the existing `grid cards` Material extension already used on the page) maps cleanly to five jobs with one icon + one CTA each. The strict build passed first try after the rewrites, so no broken internal links or snippet references.

### What didn't work

My first `AskUserQuestion` call failed validation:

```
InputValidationError: Too big: expected array to have <=4 items (path: questions[0].options)
```

I had put 8 options on the "which five jobs" question; the tool caps options at 4. I reworked it into preset bundles. More importantly, the *premise* of that question was wrong — the user rejected the "example use cases" framing entirely, which is the real lesson, not the validation error.

### What I learned

The "five jobs to be done" are a product-narrative device, not a feature list: they're the verbs of using ralphify (write / feed / run / steer / share). The user thinks of ralphify as an implementation of the ralphloops.io format — that ownership of the format is central to how it should be marketed.

### What was tricky

The original prompt was voice-transcribed and garbled: "it is using ralphloops.io not AI. Ralph loops that I owe in the standard format." Decoding that into "ralphify uses the ralph loops format (ralphloops.io), a standard format the user owns — don't market it as a generic AI tool" required a clarifying round. Worth the round-trip; guessing wrong would have meant rewriting the rewrite.

### What warrants review

Look at `/README.md` and `/docs/index.md` first — they carry the new positioning and the five-job structure; check the framing reads the way the user wants. Confirm the five chosen jobs are the right five (write / feed / run / steer / share). The deeper reference pages (`how-it-works.md`, `cli.md`, `api.md`, `quick-reference.md`, `troubleshooting.md`) were left intact and are now secondary — verify nothing in them contradicts the new lead narrative. The nav in `mkdocs.yml` was not pruned.

### Future work

Potential follow-ups that fell out of the work but were not done: pruning/restructuring the `mkdocs.yml` nav to match the five-job spine; possibly folding `how-it-works.md` into getting-started; trimming the cookbook to fewer recipes. The `ralphs/example/` untracked directory present in the working tree is unrelated to this change and was left alone.
Loading
Loading