agentsclimarketplace

Ralph runner

Skill linuxlewis/agent-skills/skills/ralph-runner

Run Ralph Wiggum autonomous coding loops. Use when user asks to run ralph, start autonomous coding, execute a PRD, implement features from a task list, or wants Claude Code to work through user stories iteratively.From its SKILL.md

Install
npx -y skills add linuxlewis/agent-skills --skill ralph-runner

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

  • no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
  • 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its file declares

Copied from the file, not written here

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

2.6 KB, as published. Nobody here has run it

Ralph Runner

Run autonomous AI coding loops that implement features from a PRD (Product Requirements Document) iteratively.

Prerequisites

  • Claude Code - claude --version
  • ralph-cli - ralph --version

Quick Start

# Check status of a PRD
ralph status prd.json

# Run the loop
ralph run prd.json

# With context files
ralph run prd.json --context AGENTS.md --context ./docs

# More iterations
ralph run prd.json --iterations 20

Workflow

1. Create PRD

Create a prd.json file with user stories:

{
  "project": "MyApp",
  "branchName": "ralph/feature-name",
  "description": "Feature description",
  "userStories": [
    {
      "id": "US-001",
      "title": "Add login form",
      "priority": 1,
      "passes": false
    }
  ]
}

2. Run Ralph

ralph run prd.json --context AGENTS.md

3. Monitor Progress

ralph status prd.json

How It Works

Each iteration:

  1. Reads prd.json, picks highest priority story where passes: false
  2. Spawns fresh Claude Code instance
  3. Claude implements that ONE story
  4. Runs quality checks (typecheck, lint, tests)
  5. If passing: commits, updates prd.json, appends to progress.txt
  6. Outputs <promise>COMPLETE</promise> when all done

Memory persists via:

  • Git history (commits)
  • progress.txt (learnings)
  • prd.json (status)

CLI Reference

ralph run <prd>

ralph run prd.json [options]

Options:
  -i, --iterations <n>    Max iterations (default: 10)
  -c, --context <paths>   Context files/dirs to include
  -p, --prompt <path>     Custom prompt template
  --headed                Show Claude output live
  --dry-run               Preview without running

ralph status [prd]

ralph status prd.json

Shows progress bar and story status.

PRD Format

See references/prd-format.md for complete format specification.

Best Practices

  1. Keep stories small - Each should complete in one context window
  2. Good acceptance criteria - Be specific about "done"
  3. Include typecheck - Add "Typecheck passes" to criteria
  4. Use context - Pass in AGENTS.md and relevant docs
  5. Check progress.txt - Contains learnings from previous iterations

Keep looking

Skills are one crate of 608,475. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.