Ralph Loop

Ralph Loop

Operate an autonomous implementation loop as a resumable state machine, not a one-shot prompt. Preserve negative knowledge, make progress machine-readable, and distinguish completed implementation chunks from completed review/documentation/test hooks.

First-use operator journey

When a user asks how to start, preflight the repository instead of explaining sprint internals first:

1. Confirm a Git repository; Bash, Git, jq, and Python 3; an explicit harness, model, and reasoning

choice (or a fully owned custom command); positive sprint and per-chunk turn budgets; an explicit tracked-or-local state choice; a durable SPEC.md or equivalent; and credible fast chunk plus comprehensive sprint validation commands. Node.js/npm and npx are required when the skill still needs to be installed or updated.

1. Read repository agent instructions and the spec before choosing commands or planning work.
2. Ensure just is available and install the project recipe import without overwriting an existing

justfile; then initialize or upgrade the deterministic runtime with reviewed choices.

1. Break the spec into dependency-ordered sprints, create only the first sprint under

.ralph/sprints/, set CURRENT_SPRINT, and validate the complete setup.

1. Tell the operator what to review and stop before running. Invoking .ralph/loop.sh starts the

autonomous loop; do not add or require a redundant authorization boolean.

Do not ask the operator to hand-build .ralph/ or sprint files. Use $ralph-loop for the complete lifecycle or ambiguous Ralph requests. Prefer $ralph-sprint, $ralph-status, or $ralph-review when the requested operation is already clear; all four skills share this runtime and its invariants.

Deterministic runtime

Bootstrap the human interface from the project repository:

npx zacharygcook/zach-ralph-method

The installer delegates to the upstream Skills CLI, installs all four Ralph skills, then safely adds the versioned recipe import to a new or existing project justfile. For agent-owned or noninteractive package management, the underlying command is:

npx skills add zacharygcook/zach-ralph-method

The CLI detects the active coding agent and creates a project-local skill copy containing the instructions, installer, and runtime templates. Use --agent only to target a specific agent; --agent '*' deliberately creates adapter copies for every supported client. Run the bundled scripts/ralph launcher from the detected skill directory; it selects Python 3.11+ from either the python3 or python command.

Prefer just init, just upgrade, just validate, just status, just run, just next, just marathon, and just resume in operator-facing instructions. just run deliberately pauses after one sprint; just next advances exactly once; just marathon explicitly authorizes continuous prepared-sprint execution. Keep fully explicit launcher commands for agents and automation.

For a repository that already has skills-lock.json, refresh the package before upgrading the project runtime:

npx skills update ralph-loop ralph-sprint ralph-status ralph-review --project
/scripts/ralph upgrade --repo 

Use npx skills experimental_install to restore pinned project skills from a committed lockfile on another machine. npx skills owns skill packaging; the bundled runtime command owns stateful .ralph/ initialization, migration, validation, and status because the package manager does not run arbitrary lifecycle hooks.

Install the bundled hardened Bash runtime only when the user asks to initialize or repair Ralph:

/scripts/ralph init --repo  --agent  --model '' --reasoning-effort '' --state-mode  --max-sprint-iterations  --max-chunk-iterations  --chunk-validation-command '' --sprint-validation-command ''

For a parent directory containing independent child Git repositories, use multi-repo mode:

/scripts/ralph init --repo  --mode multi-repo --repos   --primary-repo  --agent  --model '' --reasoning-effort '' --state-mode  --max-sprint-iterations  --max-chunk-iterations  --chunk-validation-command '' --sprint-validation-command ''

Initialization is non-destructive: when .ralph/ already exists, init enters the same safe upgrade path as upgrade and preserves configuration and sprint state. Harness, model, reasoning effort, sprint turn budget, and per-chunk turn budget are operator choices with no defaults. Interactive initialization and upgrade prompt for missing choices; noninteractive callers must pass them explicitly. Disable a hook explicitly when it is genuinely outside the repository's workflow; skipped hooks remain visible in the manifest.

Upgrade an existing runtime without replacing operator configuration, sprints, logs, or scratchpad state. Usually the stored validation configuration makes upgrade --repo sufficient. Legacy RALPH_TEST_COMMAND values migrate to the sprint gate; if validation configuration is missing, supply the commands or explicitly disable the relevant gate:

/scripts/ralph upgrade --repo  --chunk-validation-command '' --sprint-validation-command ''

Validate installed runtime, fingerprints, configuration, and sprint structure with:

/scripts/ralph validate --repo 
/scripts/ralph status --repo 

Use --agent custom --agent-command '' for another client. The trusted command receives RALPH_PROMPT_FILE and RALPH_PROJECT_ROOT. Never place secrets in config.env; Bash sources it as code. Runtime adapters support Codex, Claude Code, Grok Build, Amp, OpenCode, and Factory Droid, but verify the installed CLI's current flags before a live autonomous run.

A repository may call the same fast command from its existing pre-commit system for earlier feedback. That hook complements Ralph; it never replaces the independent gate because hooks can be absent, bypassed, or inappropriate for slow and multi-repository validation. Ralph does not install Husky or another language-specific hook manager.

Route the Task

• First use from a spec: [references/first-run.md](references/first-run.md)
• New setup or reliability audit: [references/initialize.md](references/initialize.md)
• Turn a spec into dependent sprints: [references/spec-breakdown.md](references/spec-breakdown.md)
• Create or validate a sprint folder: [references/sprint.md](references/sprint.md)
• Design chunks.json: [references/chunks.md](references/chunks.md)
• Determine real completion: [references/status.md](references/status.md)
• Critically review a sprint: [references/review.md](references/review.md)

Read only the references needed for the requested operation.

Shared Invariants

• Chunks are sequential, bounded, and have concrete acceptance criteria plus validation commands.
• Completion markers are candidates: accept exactly one next sequential chunk only after the configured fast validation and chunk-owned commit evidence pass.
• Failed chunk validation resets only that claim, records structured evidence, and gives the next fresh context a repair handoff through SCRATCHPAD.md.
• Artifact paths are accurate because downstream hooks depend on them.
• Every sprint has persistent scratchpad memory; agents read it first and append decisions, dead ends, and discoveries before exiting.
• Manifests represent resumable phases and hook status explicitly.
• Review, documentation, and final validation hooks are idempotent and leave durable completion markers.
• Hook runtime state belongs under the run log, outside sprint work products.
• Signals and interrupted exits reconcile state instead of silently losing completed work.
• A sprint is not complete merely because implementation chunks pass; required post-sprint hooks must also finish.
• Final sprint validation runs after review and documentation mutations; optional E2E runs last.
• Automatic broad Git staging is off. Do not enable RALPH_AUTO_COMMIT=I_ACCEPT_GIT_ADD_ALL in a

repository with concurrent dirty work; prefer agent-created scoped commits.

• tracked state mode commits only .ralph/ after successful sprint hooks and asks hook agents to

commit their own scoped project changes. local mode excludes .ralph/ from Git entirely. Never silently choose between them for a new installation.

• Multi-repo chunks name a configured child repository or all; manifests retain independent start

and end commit ranges, and agents commit separately inside each changed repository.

Adapt filenames when a repository uses an equivalent orchestration convention, but preserve these semantics.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: zacharygcook
• Source: zacharygcook/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.