Index of every page on this site: llms.txt
All skills
andrelandgraf avatar

/ralph-loop-workflow

@4449331
Run it yourself

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.

Use this Skill: https://skilld.dev/gh/andrelandgraf/fullstackrecipes/ralph-loop-workflow

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈64 tokens for metadata: the name and description. ≈1.5k when used: this file.

Description uses 3.2% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈257 characters, or 3.2%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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):

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

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts5mo3 checks · Risk SAFE
  • Gen Agent Trust Hub5mo

    This skill defines an autonomous development workflow called 'Ralph'. It guides an agent through a loop of task planning, implementation, and verification. It includes a robust preflight check to ensure developer tools (Vercel, Neon, GitHub, etc.) are correctly configured and authenticated before the loop begins. The skill provides clear safety guardrails, such as instructing the agent to never attempt interactive authentication on the user's behalf.

  • Socket5mo

    No alerts

  • Snyk5mo

    Risk: LOW · No issues

Signed by skilld at 4449331. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 weeks ago.

Steadyupdated 6 months ago

README badge

README badge for andrelandgraf/fullstackrecipes/ralph-loop-workflow