---
name: ralph-loop-workflow
description: Run a coding agent in an autonomous loop via a /ralph command, gated by a preflight check that every CLI is installed, linked, and authenticated. Use when driving long-running autonomous development from a wide, outcome-focused prompt.
title: ralph-loop-workflow
canonical_url: https://skilld.dev/gh/andrelandgraf/fullstackrecipes/ralph-loop-workflow
last_updated: 2026-11-01T08:03:20.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install andrelandgraf/fullstackrecipes/ralph-loop-workflow`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/ralph-loop-workflow`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/andrelandgraf/fullstackrecipes/ralph-loop-workflow) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/ralph-loop-workflow`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/ralph-loop-workflow --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/ralph-loop-workflow --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Ralph Loop Workflow

Run a coding agent in an autonomous loop that breaks a wide prompt into tasks and builds, tests, and ships each one.

## Prerequisites

Complete these setup recipes first:

- AI Coding Agent Configuration
- Code Health, Linting & Formatting
- Testing

### The Loop

Ralph maximizes how long the agent runs without human intervention. The goal is not a file format — it is keeping the agent able to plan, build, and verify on its own. The durable record of intent lives in the artifacts the agent produces: tests (executable acceptance criteria), user-facing docs, and a changelog for published libraries.

```
input prompt
  -> preflight check (CLIs installed, linked, authenticated)
  -> agent harness managed todo list (first-principles task breakdown)
  -> code + user-facing docs + changelog + tests
  -> verification (typecheck, fmt, fallow, browser, tests, deploy, prod check)
  -> iterate
```

Give the agent a wide, outcome-focused prompt and let its own harness manage the todo list — there is no separate user-story file to author or check off.

If no prompt is given, STOP and ask the user: "What outcome do you want the Ralph loop to drive toward? Give me a wide, outcome-focused prompt and I'll break it into tasks." Wait for their answer before continuing.

Run the preflight check once. If anything is missing or unauthenticated, report the exact fix commands and STOP — the loop does not start until everything is green. Then each iteration:

1. Read the current state of the codebase and any prior progress.
2. Break remaining work into tasks with first-principles thinking.
3. Pick the highest-priority task.
4. Implement it through the dev workflow: write tests, build, generate and migrate DB schema if needed, format.
5. Verify: typecheck, build, tests, and browser interaction at `http://localhost:3000`.
6. Debug and fix until verification passes.
7. Update user-facing docs and the changelog for any published artifacts.
8. Commit with a descriptive message and move to the next task.

Keep the dev server running (`bun run dev`). The agent works against a test database, so it can migrate freely. The loop ends when no tasks remain and all verification passes.

### What the Agent Needs

Nothing Ralph-specific to install — the loop depends on three things being in place:

- **Context** — how to work in this codebase (patterns, dev workflow, conventions), via `AGENTS.md`, configured MCP servers, and installed skills.
- **Tools** — to provision resources, run migrations, pull logs, and inspect deployments, via the project's MCP servers and CLIs. Give the agent the same tools you use.
- **Verification** — what extends autonomous runway. The agent must check its own work locally and in production:
  - **Code health** — `bun run typecheck`, `bun run fmt`, `bun run fallow`
  - **Tests** — `bun run test` against an isolated database branch (Playwright, integration, unit)
  - **Browser** — `agent-browser` to interact with the running app like a user
  - **Logs & deploys** — pull deployment and runtime logs to confirm changes shipped and work in production

When verification is trustworthy and self-serve, the agent catches and fixes its own regressions without a human in the loop.

### Preflight Check

Confirm the agent has everything before the first iteration, rather than discovering a missing credential halfway through. Don't assume a fixed list — infer the active infrastructure from the codebase, then check each tool:

1. **Discover the infra in use.** Read the MCP config (`.cursor/mcp.json`), the `better-env` `configSchema` declarations, and `package.json` scripts. Each configured service implies a CLI or token: Neon (`DATABASE_URL`), Vercel, Resend, Sentry, GitHub, Better Auth, etc.
2. **For each tool, verify install + link + auth** with a non-destructive command.
3. **Report a checklist** with a fix command for every red item.

Example checks (run only the ones the codebase uses):

```bash
agent-browser -v                                      # browser automation
vercel --version && vercel whoami && vercel project ls # installed + linked + auth
neonctl me                                            # Neon CLI authenticated
sentry-cli info                                       # token present and valid
gh auth status                                        # GitHub CLI for PRs, logs
bun run env:validate                                  # env vars match the schema
```

Stop if anything is red:

```
Preflight check
  [ok]   agent-browser            v1.4.2
  [ok]   vercel                   linked to acme/app, logged in as andre
  [fail] neon                     not authenticated
  [fail] DATABASE_URL             not set in .env.local
  [ok]   gh                       authenticated

2 issues block the loop. Run these, then re-run /ralph:

  neonctl auth                      # opens browser for OAuth
  bun run env:pull                  # pull DATABASE_URL from Vercel
```

For interactive OAuth (Vercel, Neon, GitHub), give the user the exact command to run themselves — don't attempt a browser login on their behalf. For anything fixable non-interactively (pulling env vars, setting a token), offer to run it. Start the loop only once every item is green.

### Steering the Loop

Keep the prompt wide and outcome-focused, then let the agent decompose it. Add direction by sharpening inputs, not micromanaging steps:

- **Sharper prompt** — state the outcome and constraints, not the steps.
- **Stronger tests** — failing tests are the most reliable signal that more work remains.
- **Better tools** — when the agent keeps getting stuck, it usually lacks a tool (an MCP server, CLI, or log access), not instructions.

### Background & References

- [Ralph - Geoffrey Huntley](https://ghuntley.com/ralph/) - Original concept and implementation
- [Effective Harnesses for Long-Running Agents - Anthropic](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents) - Engineering patterns for agent loops
- [Matt Pocock on Ralph](https://www.youtube.com/watch?v=_IK18goX4X8) - Video walkthrough
