ralphify-spec

Translate a plain-English iterative task into a valid, runnable ralphify ralph directory — a RALPH.md with well-formed YAML frontmatter, useful command blocks, and a prompt body that follows the Ralph Wiggum method.

The user does not need to know how ralphify works. Do not explain frontmatter, placeholders, or shlex quirks to them. Translate their goal into a working ralph and hand them the suggested run command.

When this fits

Ralphs pay off for work where each iteration makes incremental progress and a stop condition tells the loop when to halt:

• climb test coverage to a threshold
• burn down lint or type-check errors
• port files from one language/framework to another
• resolve PR review comments one by one
• work through a queue of items until empty

If the task is one-shot ("add a button to this page", "explain this function"), a ralph adds nothing. Recommend a single-shot implementation and stop.

Workflow

1. Capture intent (2-3 questions, max)

Ask only what you cannot infer from the conversation or cwd. Skip questions the user already answered.

1. What does "done" look like for one full run? (coverage above 90%, zero

clippy warnings, all review threads resolved). Drives the stop condition and which commands the ralph surfaces each iteration.

1. Language and tools? Inspect pyproject.toml, Cargo.toml, or

package.json first; ask only if ambiguous.

1. Hard constraints? Files to leave alone, commit format, style guide.

Ask only if non-obvious.

Do not ask about command blocks, frontmatter fields, placeholders, or YAML. Translation is your job.

2. Pick a name and location

• Derive a kebab-case name (coverage-climber, ts-porter,

clippy-burndown) unless the user provided one. The validator (step 7) enforces the exact character set ralphify accepts.

• Default location: ralphs/NAME/ inside the current repo. Confirm only if

cwd is not a sensible home for it.

3. Scaffold from the canonical template, then rewrite

Start from ralphify's own template so the file parses:

ralph init ralphs/NAME

If ralph is not on PATH, fall back to ~/.local/bin/ralph (where uv tool install ralphify places it). After scaffolding, rewrite the file for the user's task — do not ship the stock template.

4. Design the frontmatter

references/schema.md is the authoritative schema reference. Read it when you need exact rules; do not re-derive from this skill body.

Default agent: detect from context — claude -p --dangerously-skip-permissions (Claude Code), gemini -p --yolo (Gemini CLI), or cursor-agent -p (Cursor). Ask which harness the user is on if it is not clear.

Set credit: false if the repo forbids automated commit trailers.

Default commands picks by stack:

• any repo: git-log → git log --oneline -10
• Python: tests → uv run pytest, lint → uv run ruff check .
• Rust: tests → cargo test, lint → cargo clippy --all-targets -- -D warnings
• Node/TS: tests → npm test, lint → npm run lint
• stop-condition probe: write a script (step 5), reference as ./check-done.sh

Add args only if the ralph is meant to be reusable across targets. Hardcode otherwise — generalizing later is cheap.

Guard scripts (short-circuit pattern)

When the ralph has a clear "all done" condition checkable before spinning up an agent, wrap the agent call in a guard script and point agent: at the script. See references/guards.md for the full pattern, including the iteration-cap and COMPLETE-sentinel guards every generated ralph must include.

Closer gate (burn-down-todos ralphs only)

When the loop pattern is burn-down-todos (a queue-driven ralph that fires a closer when the queue drains — open PRs, push the stack, tag a release), install both of the canonical scripts alongside RALPH.md in the ralph directory:

1. assets/next-issue.sh.template → next-issue.sh. The queue-read

script RALPH.template.md's commands.next-issue invokes every iteration. Its stdout (Path: … / QUEUE EMPTY / QUEUE READ ERROR) drives the mutual-exclusion decision in the Task block.

1. assets/closer-gate.sh.template → closer-gate.sh. The Guard 4

verdict gate the closer iteration must pass before any push, submit, PR creation, or COMPLETE sentinel.

Fill the same PLACEHOLDER_* markers in both (queue dir, glob, status field, planning branch), chmod +x them, and wire the closer block in RALPH.md to require CLOSER GATE PASS as step 1 of the closer. This is Guard 4 in references/guards.md; it exists because every observed failure of this ralph shape involved firing the closer in the same iteration as per-item work and emitting COMPLETE while items were still open.

5. Shell features belong in scripts

commands[].run is parsed with shlex.split. No pipes, &&, redirects, or $(...). For anything non-trivial, write a script in the ralph directory and reference it with ./name.sh:

commands:
  - name: coverage
    run: ./check-coverage.sh

• Make scripts executable (chmod +x).
• Scripts invoked via ./ prefix run with the ralph directory as cwd;

commands without the prefix run from the project root.

• Keep scripts short and single-purpose — the agent only sees their output.

6. Write the prompt body

Each iteration starts with a fresh context. The prompt must re-establish enough situation every time to be useful. Follow the canonical shape:

1. Role + loop awareness. "You are an autonomous {role} agent running

in a loop." Include {{ ralph.iteration }} under an ## Iteration header so the agent knows where it is — useful for "on final iteration, do cleanup" logic.

1. Context-reset acknowledgment. "Each iteration starts with a fresh

context. Your progress lives in the code and git." Stops the agent from trying to remember state.

1. Command output sections. Put {{ commands.<name> }} under

## <Title> headers. The agent only sees what the prompt shows it.

1. Task section. State exactly what one iteration of work is. Narrow

beats broad: "add tests for one untested function" beats "improve coverage". A fresh-context agent should pick a target and finish it within a single iteration.

1. Stop condition. A <promise>COMPLETE</promise> sentinel the agent

prints when the loop's "done" condition is met. After ralph run exits, the runner wrapper in scripts/run.sh scans the captured log for this marker and exits 0 if found; otherwise it flags the run as a cap-hit failure. (No mid-run early termination — ralph runs to its natural end.)

1. Rules. Bulleted list — what to avoid, what to always do.
2. Commit conventions. One commit per iteration; format (Conventional

Commits or repo style); push or not.

For burn-down-todos ralphs, the Task section MUST be a mutual-exclusion block: per-item work, closer, and recovery are three distinct iteration shapes selected by the queue-read output (Path: … / QUEUE EMPTY / QUEUE READ ERROR). Per-item iterations end with an explicit STOP marker (ITERATION DONE: <id>); the closer iteration begins with Guard 4's closer-gate.sh and refuses to proceed without CLOSER GATE PASS. assets/RALPH.template.md ships the canonical shape — copy it, fill the placeholders, and do not let per-item and closer steps run in the same iteration.

HTML comments (<!-- ... -->) are stripped before piping to the agent — safe for maintenance notes, never wastes tokens.

7. Validate with the bundled script

Run the bundled validator against the draft. It is the gate — do not skip, do not mentally re-implement what it checks:

uv run --with pyyaml python scripts/validate.py PATH/TO/RALPH.md

(Adjust the script path to wherever this skill lives in your harness.)

It enforces the schema rules in references/schema.md — required fields, name regex, shlex safety, placeholder coverage, agent on PATH, timeout type. Exit 0 = clean (warnings advisory), 1 = errors that must be fixed, 2 = environment problem.

Pay attention to warnings — declared-but-unused commands or args are cleanup signals.

8. Wire the runner wrapper

Copy this skill's scripts/run.sh into the generated ralph directory as a sibling of RALPH.md (or symlink it as ralphs/NAME/run.sh). Keeping the wrapper inside the ralph dir means the run command is self-contained and the wrapper travels with the ralph if the dir is moved or shared. The wrapper enforces the iteration-cap rule the bare ralph run does not:

• Refuses to start if -n / --max-iterations is missing — every generated

ralph must declare a cap.

• Prints a startup banner with the cap value so the human knows the ceiling.
• After ralph run exits, scans the captured log for

<promise>COMPLETE</promise> and exits 0 if found; otherwise exits non-zero with a CAP HIT WITHOUT COMPLETE banner — silent continuation is forbidden. (No mid-run early termination; ralph runs to its natural end at cap, error, or --stop-on-error.)

See references/guards.md for the full guard contract.

9. Report back

Show the user:

1. File tree of the created directory.
2. One sentence describing what a single iteration does.
3. Suggested first run: `ralphs/NAME/run.sh ralphs/NAME -n 50 -t 1800

-s -l ralphs/NAME/logs — 50 iterations, 30-minute timeout, stop on error, logs captured. The wrapper path matches step 8's "copy into the ralph dir" instruction; the second ralphs/NAME is the ralph dir argument the wrapper forwards to ralph run. Starting with -n 50` lets them see the loop work before going unbounded — and the wrapper refuses to drop the cap entirely.

What not to do

• Do not invent frontmatter fields ralphify does not support. Schema is

small on purpose — anything outside agent, commands, args, credit is noise.

• Do not pipe or chain commands in run:. Use a script.
• Do not leave placeholders without a matching declaration — they render

as literal text and confuse the agent.

• Do not ask the user about ralphify internals. If they wanted to write

YAML, they would not be here.

• Do not default to -n unbounded on first run. Start with -n 50. The

runner wrapper enforces this.

• Do not omit the <promise>COMPLETE</promise> sentinel. Loops without an

explicit terminator burn tokens until the cap and exit ambiguously.

• Do not generate a burn-down-todos RALPH.md whose Task block lets the

closer fire in the same iteration as per-item work. The iteration is one shape or the other (or recovery) — never two at once. Per-item step STOPS with ITERATION DONE: <id>; the closer waits for CLOSER GATE PASS before any push or COMPLETE step. Skipping this shape is the failure mode Guard 4 exists to prevent.

Bundled scripts

# Validate a draft RALPH.md against the v0.3.0 schema.
#   exit 0 = clean, 1 = errors, 2 = environment problem
uv run --with pyyaml python scripts/validate.py PATH/TO/RALPH.md

# Wrap `ralph run` so the iteration cap is mandatory and the COMPLETE
# sentinel decides the exit code. Forwards every other flag to ralph run.
scripts/run.sh PATH/TO/RALPH_DIR -n 50 -t 1800 -s -l PATH/TO/RALPH_DIR/logs

References

• references/schema.md — read when you need the exact frontmatter

rule (v0.3.0): required fields, regex constraints, default values.

• references/guards.md — read when designing the guard story for a

new ralph: iteration cap, COMPLETE sentinel, closer gate (Guard 4), pre-agent short-circuit, canonical next-issue.sh, common bugs.

• assets/RALPH.template.md — copy into the new ralph dir as the

starting point for burn-down-todos loops; fill the PLACEHOLDER_* markers in place.

• assets/next-issue.sh.template — copy alongside RALPH.md for

burn-down-todos ralphs; the queue-read script the template's commands.next-issue invokes every iteration.

• assets/closer-gate.sh.template — copy alongside RALPH.md for

burn-down-todos ralphs; fills in queue dir, glob, status field, and planning branch and gates the closer (Guard 4).