ralphy

name

ralphy

description

Autonomous AI coding orchestration using the Ralph Wiggum technique and Ralphy CLI. This skill should be used when running AI agents in continuous loops until tasks complete, orchestrating multi-task development with PRD/YAML files, configuring parallel agent execution, or implementing the Ralph Wiggum autonomous development methodology. Triggers on mentions of ralphy, ralph, autonomous loops, PRD-driven development, or multi-agent orchestration.

Ralphy & Ralph Wiggum Technique

Ralphy is an autonomous AI coding orchestrator that runs agents on tasks until done. Built on Geoffrey Huntley's Ralph Wiggum technique - a continuous loop methodology where AI agents iterate until completion.

Quick Reference

# Single task
ralphy "add dark mode"

# From PRD/YAML
ralphy --prd PRD.md
ralphy --yaml tasks.yaml

# Parallel execution
ralphy --parallel --max-parallel 5

# With branches and PRs
ralphy --branch-per-task --create-pr

Core Concepts

The Ralph Wiggum Technique

The foundational principle: run an AI agent in a loop until the job is done.

# Minimal form
while :; do cat PROMPT.md | claude ; done

Key insight: Failures inform improvements. When Ralph fails, tune the prompts like a guitar - add specific guidance based on observed failure patterns.

Three-Phase Architecture

1. Requirements Definition: Discuss project, identify Jobs to Be Done (JTBD), break into topics
2. Planning Loop: Gap analysis between specs and code, generate IMPLEMENTATION_PLAN.md
3. Building Loop: Implement tasks, validate with tests, commit on success

Ralphy CLI Usage

Task Sources

Markdown PRD (checkbox format):

## Tasks
- [ ] create auth system
- [ ] add dashboard
- [x] completed task (skipped)

YAML format:

tasks:
  - title: create auth
    completed: false
    parallel_group: 1
  - title: add dashboard
    completed: false
    parallel_group: 2

GitHub Issues:

ralphy --github owner/repo --github-label "ready"

Parallel Execution

Run multiple agents simultaneously with isolation:

ralphy --parallel              # 3 agents default
ralphy --parallel --max-parallel 5
ralphy --parallel --sandbox    # Lightweight sandboxes for large repos

Each agent gets:

• Isolated worktree or sandbox
• Unique branch: ralphy/agent-N-task-slug
• Independent execution context

Parallel Groups in YAML control execution order:

tasks:
  - title: Create User model
    parallel_group: 1
  - title: Create Post model
    parallel_group: 1    # Runs with above
  - title: Add relationships
    parallel_group: 2    # Waits for group 1

Branch Workflow

ralphy --branch-per-task           # One branch per task
ralphy --branch-per-task --create-pr   # Plus pull requests
ralphy --branch-per-task --draft-pr    # Draft PRs
ralphy --base-branch main          # Branch from specific base

Engine Selection

ralphy "task"                      # Claude Code (default)
ralphy --opencode "task"           # OpenCode
ralphy --cursor "task"             # Cursor
ralphy --codex "task"              # Codex
ralphy --qwen "task"               # Qwen-Code
ralphy --copilot "task"            # GitHub Copilot

Model override:

ralphy --model sonnet "task"
ralphy --sonnet "task"             # Shortcut

Pass args to engine:

ralphy --claude "task" -- --no-permissions-prompt

Project Configuration

Initialize with auto-detection:

ralphy --init

Creates .ralphy/config.yaml:

project:
  name: "my-app"
  language: "TypeScript"
  framework: "Next.js"

commands:
  test: "npm test"
  lint: "npm run lint"
  build: "npm run build"

rules:
  - "use server actions not API routes"
  - "follow error pattern in src/utils/errors.ts"

boundaries:
  never_touch:
    - "src/legacy/**"
    - "*.lock"

capabilities:
  browser: "auto"

notifications:
  discord_webhook: "https://discord.com/..."
  slack_webhook: "https://hooks.slack.com/..."

Add rules dynamically:

ralphy --add-rule "always use TypeScript strict mode"

CLI Flags Reference

Flag	Purpose
--prd PATH	Task file/folder (default: PRD.md)
--yaml FILE	YAML task file
--github REPO	Use GitHub issues
--parallel	Run parallel agents
--max-parallel N	Max agents (default: 3)
--sandbox	Lightweight sandboxes vs worktrees
--branch-per-task	One branch per task
--create-pr	Create pull requests
--draft-pr	Create draft PRs
--no-merge	Skip auto-merge in parallel
--no-tests	Skip tests
--no-lint	Skip linting
--fast	Skip tests and lint
--no-commit	Don't auto-commit
--max-iterations N	Stop after N tasks
--max-retries N	Retries per task (default: 3)
--dry-run	Preview only
--browser	Enable browser automation
-v, --verbose	Debug output

The Ralph Loop Pattern

For advanced usage implementing the full Ralph Wiggum technique:

See references/ralph_loop_pattern.md for:

• Complete file structure
• PROMPT_plan.md and PROMPT_build.md templates
• Context management strategies
• Backpressure mechanisms
• Plan regeneration triggers

Security Considerations

Critical: Running with --dangerously-skip-permissions requires sandboxing.

• Always set --max-iterations (e.g., 20-50) to prevent runaway costs
• Run in sandboxed environments (Docker, Fly Sprites, E2B)
• Use minimum viable API key access
• Escape hatches: Ctrl+C stops loop, git reset --hard reverts

Best Practices

1. Start with clear specs: Well-defined PRD items lead to better outcomes
2. Use parallel groups: Organize dependent tasks to run efficiently
3. Set boundaries: Protect critical files in config
4. Add project rules: Guide consistent patterns
5. Monitor iterations: Watch for loops that aren't progressing
6. Iterate on prompts: When Ralph fails, tune the guidance

Troubleshooting

Agent stuck in loop: Check if task is too vague. Add specific acceptance criteria.

Merge conflicts in parallel: Use --no-merge and resolve manually, or let AI resolve.

Rate limits: Ralphy detects and defers tasks on quota errors.

Tests failing: Ensure commands.test in config matches your test runner.