Skip to content

Commit c8001af

Browse files
Kasper JungeKasper Junge
Kasper Junge
authored and
Kasper Junge
committed
.
1 parent 26f3dc7 commit c8001af

7 files changed

Lines changed: 274 additions & 6 deletions

File tree

‎agr.lock‎

Lines changed: 15 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,10 +11,6 @@ handle = "microsoft/playwright-cli/playwright-cli"
1111
source = "github"
1212
installed-name = "playwright-cli"
1313

14-
[[skill]]
15-
path = "skills/release"
16-
installed-name = "release"
17-
1814
[[skill]]
1915
handle = "computerlovetech/docs-audit"
2016
source = "github"
@@ -35,3 +31,18 @@ source = "github"
3531
commit = "9859f7bceb7a46af8482cabb9aa24e0d38a49413"
3632
content-hash = "sha256:fa1ce825fa7e11cd5aac55ee7eac5e9c918e3af113b7988fdbd281a319acc110"
3733
installed-name = "code-review"
34+
35+
[[skill]]
36+
path = "skills/ralphify-release"
37+
installed-name = "ralphify-release"
38+
39+
[[ralph]]
40+
path = "ralphs/bug-hunter"
41+
installed-name = "bug-hunter"
42+
43+
[[ralph]]
44+
handle = "computerlovetech/ralphs/improve-codebase"
45+
source = "github"
46+
commit = "70a0dabf5a59ae1a3acaf50a9e619c83e174a35f"
47+
content-hash = "sha256:0afc55d5b2d4061fa82c270a147c66c8bc21589ab62c47d9747ddb5f382c708d"
48+
installed-name = "improve-codebase"

‎agr.toml‎

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,33 @@
1+
# Source to fetch skills from
12
default_source = "github"
3+
4+
# Tools to install skills to (e.g. "claude", "cursor", "codex")
5+
tools = ["claude"]
6+
7+
# Primary tool for instruction sync (must be listed in tools)
8+
# default_tool = "claude"
9+
10+
# Default GitHub owner for short handles (e.g. "skill" resolves to "computerlovetech/skill")
11+
default_owner = "computerlovetech"
12+
13+
# Default GitHub repo for two-part handles (e.g. "owner/skill" resolves to "owner/skills/skill")
14+
default_repo = "skills"
15+
16+
# Sync instruction files across tools
17+
# sync_instructions = false
18+
19+
# Which tool's instruction file is the source of truth
20+
# canonical_instructions = "CLAUDE.md"
21+
222
dependencies = [
323
{path = "skills/brand-guidelines", type = "skill"},
424
{handle = "microsoft/playwright-cli/playwright-cli", type = "skill"},
5-
{path = "skills/release", type = "skill"},
625
{handle = "computerlovetech/docs-audit", type = "skill"},
726
{handle = "computerlovetech/setup-agent-workspace", type = "skill"},
827
{handle = "maragudk/code-review", type = "skill"},
28+
{path = "ralphs/bug-hunter", type = "ralph"},
29+
{path = "skills/ralphify-release", type = "skill"},
30+
{handle = "computerlovetech/ralphs/improve-codebase", type = "ralph"},
931
]
1032

1133
[[source]]

‎docs/blog/posts/the-ralph-format.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
---
2+
date: 2026-04-04
3+
categories:
4+
- Standards
5+
authors:
6+
- kasper
7+
description: A short manifest defining the ralph format — a single-file, skill-like spec for autonomous agent loops.
8+
keywords: ralph format, ralph spec, RALPH.md, autonomous agent loop format, agent harness spec, ralph standard
9+
---
10+
11+
# The Ralph Format
12+
13+
A **ralph** is a directory with a `RALPH.md` file in it. `RALPH.md` defines an autonomous agent loop: the agent to run, the commands to run between iterations, and the prompt to pipe in.
14+
15+
That's the whole format.
16+
17+
<!-- more -->
18+
19+
## Minimal example
20+
21+
```markdown
22+
---
23+
agent: claude -p
24+
commands:
25+
- name: tests
26+
run: uv run pytest -x
27+
---
28+
29+
Fix the failing tests.
30+
31+
{{ commands.tests }}
32+
```
33+
34+
Each iteration: run the commands, fill the `{{ commands.<name> }}` placeholders with their output, pipe the assembled prompt to the agent, repeat.
35+
36+
## The spec
37+
38+
`RALPH.md` is a markdown file with YAML frontmatter and a prompt body.
39+
40+
**Frontmatter fields:**
41+
42+
| Field | Required | Description |
43+
|---|---|---|
44+
| `agent` | yes | Command to run. Anything that reads a prompt on stdin. |
45+
| `commands` | no | List of `{name, run}` (plus optional `timeout`). Output fills `{{ commands.<name> }}` placeholders. |
46+
| `args` | no | List of argument names. Values fill `{{ args.<name> }}` placeholders and become CLI flags. |
47+
48+
**Body:** markdown with `{{ placeholders }}`. Unmatched placeholders resolve to empty strings.
49+
50+
**Placeholders:**
51+
52+
- `{{ commands.<name> }}` — output of a command (stdout + stderr, regardless of exit code)
53+
- `{{ args.<name> }}` — value of a CLI argument
54+
- `{{ ralph.name }}`, `{{ ralph.iteration }}`, `{{ ralph.max_iterations }}` — runtime metadata
55+
56+
## Directory form
57+
58+
`RALPH.md` on its own is enough. But a ralph is a directory so it can bundle anything the loop needs:
59+
60+
```
61+
bug-hunter/
62+
├── RALPH.md # required
63+
├── check-coverage.sh # command script (optional)
64+
├── coding-guidelines.md # context for the agent (optional)
65+
└── test-data.json # supporting file (optional)
66+
```
67+
68+
Commands whose `run` starts with `./` resolve relative to the ralph directory, so bundled scripts just work. The directory is the unit of sharing.
69+
70+
## A realistic example
71+
72+
```markdown
73+
---
74+
agent: claude -p --dangerously-skip-permissions
75+
commands:
76+
- name: tests
77+
run: uv run pytest -x
78+
- name: lint
79+
run: uv run ruff check .
80+
- name: git-log
81+
run: git log --oneline -10
82+
args:
83+
- focus
84+
---
85+
86+
You are an autonomous bug-hunting agent running in a loop.
87+
Each iteration starts with fresh context.
88+
89+
## Tests
90+
{{ commands.tests }}
91+
92+
## Lint
93+
{{ commands.lint }}
94+
95+
## Recent commits
96+
{{ commands.git-log }}
97+
98+
## Task
99+
100+
Find and fix one real bug in this codebase. {{ args.focus }}
101+
102+
Rules:
103+
- One bug per iteration
104+
- Write a failing regression test before fixing
105+
- Do not change unrelated code
106+
- Commit with `fix: resolve <description>`
107+
```
108+
109+
## The runtime
110+
111+
The format is the spec. A runtime executes it. [Ralphify](https://github.com/computerlovetech/ralphify) is the reference runtime:
112+
113+
```bash
114+
uv tool install ralphify
115+
ralph run ./bug-hunter --focus "authentication"
116+
```
117+
118+
Anything that implements the loop — read `RALPH.md`, resolve placeholders, pipe to the agent, repeat — is a conforming runtime.
119+
120+
## Why a format
121+
122+
Everyone writing ralph loops ends up with the same scaffolding: a markdown prompt, a few shell commands that surface state between iterations, a while-loop that ties them together. A format turns that scaffolding into something you can share, version, and install.
123+
124+
Ralphs are to the outer loop what [skills](https://agentskills.io/) are to the inner loop. A skill guides an agent inside a session. A ralph defines what runs *between* sessions.
125+
126+
See also: [RALPH.md — a markdown format for autonomous agent loops](the-ralph-standard.md) — the longer thinking piece behind the format.

‎ralphs/bug-hunter/RALPH.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
---
2+
agent: claude -p --dangerously-skip-permissions
3+
commands:
4+
- name: tests
5+
run: uv run pytest -x
6+
- name: types
7+
run: uv run ty check
8+
- name: lint
9+
run: uv run ruff check .
10+
- name: git-log
11+
run: git log --oneline -10
12+
args:
13+
- focus
14+
---
15+
16+
# Bug Hunter
17+
18+
You are an autonomous bug-hunting agent running in a loop. Each
19+
iteration starts with a fresh context. Your progress lives in the
20+
code and git.
21+
22+
## Test results
23+
24+
{{ commands.tests }}
25+
26+
## Type checking
27+
28+
{{ commands.types }}
29+
30+
## Lint
31+
32+
{{ commands.lint }}
33+
34+
## Recent commits
35+
36+
{{ commands.git-log }}
37+
38+
If tests, types, or lint are failing, fix that before hunting for new bugs.
39+
40+
## Task
41+
42+
Find and fix a real bug in this codebase.
43+
{{ args.focus }}
44+
45+
Each iteration:
46+
47+
1. **Read code** — pick a module and read it carefully. Look for
48+
edge cases, off-by-one errors, missing validation, incorrect
49+
error handling, race conditions, or logic errors.
50+
2. **Write a failing test** — prove the bug exists with a test that
51+
fails on the current code.
52+
3. **Fix the bug** — make the test pass with a minimal fix.
53+
4. **Verify** — all existing tests must still pass.
54+
55+
## Rules
56+
57+
- One bug per iteration
58+
- The bug must be real — do not invent hypothetical issues
59+
- Always write a regression test before fixing
60+
- Do not change unrelated code
61+
- Commit with `fix: resolve <description>`

skills/release/SKILL.md renamed to skills/ralphify-release/SKILL.md

File renamed without changes.

‎tasks/README.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# Live peek code review — task list
2+
3+
Tasks generated from a competitive review of the uncommitted live-peek feature (the `p` toggle for agent output streaming). Each task is self-contained so a fresh agent context can pick one up without needing the others.
4+
5+
**Pick them up in order.** Some later tasks build on earlier ones (e.g. `medium-01` depends on the capability signal introduced in `critical-01`).
6+
7+
## Critical — must fix before merge
8+
9+
| # | Task | Original IDs |
10+
|---|---|---|
11+
| 1 | [Capture strategy three-way branch](critical-01-capture-strategy-three-way-branch.md) | C1 + M1 |
12+
| 2 | [`_pump_stream` exception containment](critical-02-pump-stream-exception-handling.md) | C2 + M9 |
13+
| 3 | [`stdin.write` timeout enforcement](critical-03-stdin-write-timeout.md) | C3 |
14+
| 4 | [Bounded reader-thread joins in `finally`](critical-04-bounded-reader-thread-joins.md) | C4 + C5 + M3 |
15+
16+
## High
17+
18+
| # | Task | Original IDs |
19+
|---|---|---|
20+
| 5 | [Echo output + Live spinner coordination](high-01-echo-output-live-spinner-coordination.md) | H1 + M8 |
21+
| 6 | [`_read_agent_stream` deadline + readahead](high-02-read-agent-stream-deadline-and-buffering.md) | H2 + H3 |
22+
| 7 | [Test helpers pid=12345 hazard](high-03-test-helpers-pid-hazard.md) | H4 |
23+
| 8 | [Peek discoverability (`--help`, startup hint)](high-04-peek-discoverability.md) | H5 |
24+
25+
## Medium
26+
27+
| # | Task | Original IDs |
28+
|---|---|---|
29+
| 9 | [Filter `AGENT_OUTPUT_LINE` events when no subscriber](medium-01-agent-output-line-event-filtering.md) | M2 |
30+
| 10 | [`returncode=None` semantic change — document](medium-02-returncode-semantic-change-docs.md) | M4 |
31+
| 11 | [Keypress listener: EINTR / SIGTSTP / SIGCONT](medium-03-keypress-signal-handling.md) | M5 |
32+
| 12 | [Peek lock discipline](medium-04-peek-lock-discipline.md) | M6 + M7 |
33+
| 13 | [Console emitter handler interleaving](medium-05-console-emitter-handler-interleaving.md) | M10 |
34+
35+
## How to use
36+
37+
Each task file contains:
38+
- **Problem** — what's wrong and where (file:line)
39+
- **Why it matters** — concrete failure mode
40+
- **Fix direction** — not a prescription, but the shape the fix should take
41+
- **Done when** — checklist for completion
42+
- **Context** — code snippets / surrounding gotchas the agent will need
43+
44+
Run `uv run pytest && uv run ruff check . && uv run ruff format --check . && uv run ty check` after every task. Any new behavior needs a regression test.
45+
46+
## Out of scope
47+
48+
Low-severity / nit findings (`.gitignore` `.ralphify/`, CHANGELOG wording, `docs/llms-full.txt` stale copy, dumb-terminal check, import ordering, case-sensitive `p`, slow test markers, free-threaded Python compatibility) are tracked in the review transcript but not in individual task files — they can be swept up in a single follow-up PR.

‎uv.lock‎

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)