v0.1 draft

Ralph Loops Specification

An open proposed format for packaging autonomous agent loops as portable directories. Not a standard — breaking changes go through the canonical repository.

1. Definition

A Ralph Loop is a directory containing one required file — RALPH.md — and zero or more optional bundled files. The directory itself is the unit of portability: share it as a git subdirectory, a standalone repo, or an archive.

2. Structure

The package root is the directory containing RALPH.md. No subdirectory layout is required beyond that file. Example:

bug-hunter/
├── RALPH.md
├── README.md
└── prompts/
    └── edge-cases.md

A package may bundle scripts, prompts, templates, fixtures, reference docs, or any other files the agent needs. Runtimes MUST resolve bundled file references relative to the package root and reject path traversal that escapes it.

3. RALPH.md structure

RALPH.md consists of optional YAML frontmatter followed by a markdown body:

---
agent: claude -p --dangerously-skip-permissions
commands:
  - name: tests
    run: uv run pytest -x
  - name: lint
    run: uv run ruff check .
args:
  - bug_report
---

# Bug Hunter

Reproduce, localize, and patch the reported bug.

## Bug report
{{ args.bug_report }}

## Test results
{{ commands.tests }}

## Lint
{{ commands.lint }}

## Instructions

1. Read the bug report above.
2. Write a failing test to reproduce the bug.
3. Localize the root cause.
4. Make the smallest useful fix.
5. Run tests and lint. Commit only if everything passes.

4. Metadata fields

The frontmatter supports exactly three fields:

Field	Type	Meaning
`agent`	string	The command to run (e.g., `claude -p`).
`commands`	list of objects	Each object has a `name` (referenced in the body via `{{ commands.<name> }}`) and a `run` (shell command to execute).
`args`	list of strings	Argument names that become CLI flags, referenced in the body via `{{ args.<name> }}`.

Frontmatter is optional. A package with no frontmatter is valid but minimally described.

5. Markdown body

The body is agent-facing instructions. The format does not impose structure on it. Recommended sections: Goal, Context, Loop, Constraints, Validation, Exit Conditions.

The canonical specification lives in ralphloops/ralphloops/specification. This page tracks the current published draft.