v0.1 draft

Ralph Loops Specification

This document defines the Ralph Loops format: a directory-based, portable package format for Ralph-style autonomous agent loops. It is an open proposed format, not a standard. Breaking changes go through an RFC process in the canonical repository.

1. Definition

A Ralph Loop is a directory-based package with:

one required file: RALPH.md
zero or more optional bundled files and subdirectories

A loop package may contain scripts, templates, fixtures, reference materials, sample inputs, plans, checklists, or any other files that help a compatible runtime execute the loop.

2. Required entrypoint

Each Ralph Loop package MUST contain a file named:

RALPH.md

This file is the canonical entrypoint for the package.

3. Package root

The package root is the directory containing RALPH.md. All relative paths in the format are resolved relative to the package root unless otherwise specified.

4. Allowed structure

There are no required subdirectories beyond RALPH.md. Example:

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

5. RALPH.md file structure

RALPH.md consists of:

optional YAML frontmatter
markdown body content

---
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.

6. 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` (identifier used in the body via `{{ commands.<name> }}`) and a `run` (shell command or script path to execute).
`args`	list of strings	Argument names that become CLI flags. Referenced in the body via `{{ args.<name> }}`.

If frontmatter is omitted entirely, runtimes MAY still load the loop, but the package is considered minimally described.

7. Markdown body semantics

The format deliberately avoids over-structuring the markdown body. Compatible runtimes MUST treat the body as agent-facing instructions, not as a strict AST.

Recommended sections: Goal, Context, Loop, Constraints, Validation, Exit Conditions, Recovery / Failure Handling, Notes for the Agent.

8. Optional bundled files

A package may include scripts, prompts, templates, examples, fixtures, plans, checklists, JSON/YAML config, reference docs, or generated examples. Compatible runtimes MUST allow the agent to reference these files relative to the loop package root.

9. Path resolution rules

All paths in metadata are relative to the package root unless they are absolute URIs. Runtimes MUST:

normalize relative paths safely
reject path traversal that escapes the package root
treat missing referenced files as package errors or warnings

10. Discovery model

A compatible runtime SHOULD be able to discover Ralph Loops by scanning directories for RALPH.md. Discovery options may include local loop directories, project-local loop packages, installed shared loop packages, and registry-downloaded packages.

11. Execution contract

The format does not mandate one universal runtime execution engine. However, a compatible runtime SHOULD, at minimum:

locate RALPH.md
parse metadata if present
load the markdown body
make bundled resources available
resolve referenced relative files safely
expose runtime-specific execution behavior consistently

12. Compatibility classes

Level	Name	Capability
1	Reader	Can discover and parse a Ralph Loop package.
2	Executor	Can execute loop instructions and load bundled files.
3	Publisher	Can package, validate, and publish Ralph Loops for reuse.

13. Validation rules

A valid v0.1 package MUST:

contain RALPH.md
use valid UTF-8 text for RALPH.md
contain parseable YAML if frontmatter is present
not reference missing required entry files if declared in metadata
not contain path traversal references in metadata

14. Packaging and distribution

A Ralph Loop package may be distributed as a git repository subdirectory, a standalone repository, a tarball or zip archive, or a registry package. The directory itself is the unit of portability.

15. Versioning

The specification itself is versioned through the RFC process in the canonical repository. Breaking changes require an RFC and explicit compatibility notes.

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