name: ralph-orchestrator description: This skill should be used when the user asks to "run ralph", "set up ralph", "create a PRD workflow", "use ralph-orchestrator", "autonomous coding loop", "hat-based agents", or mentions ralph tasks, ralph presets, ralph plan, or PRD-driven development. Provides guidance for ralph-orchestrator autonomous coding workflows. version: 0.1.0

Ralph Orchestrator

Ralph-orchestrator is an autonomous coding loop that coordinates specialized AI agents ("hats") to implement features from specifications.

Installation

brew install ralph-orchestrator

Core Concepts

The Hat System

Ralph uses specialized personas that take turns:

Task System

Tasks live in .agent/tasks.jsonl. The loop continues until all tasks are closed:

ralph task add "Implement feature" -p 1 -d "Description"
ralph task add "Blocked task" --blocked-by <task-id>
ralph task list
ralph task ready      # Show unblocked tasks
ralph task close <id>

Backpressure

Quality gates that reject work unless tests/lint/typecheck pass. Enforced via guardrails in ralph.yml.

Events

Hats communicate via events. Each hat triggers on specific events and publishes results:

ralph emit "build.done" "tests: pass, lint: pass"

Quick Start

# Initialize with a preset
ralph init --preset spec-driven --backend claude

# Create PROMPT.md with your task
echo "Build a rate limiter" > PROMPT.md

# Run
ralph run

Starting from a GitHub Issue

When you have a GitHub issue to implement, follow this workflow:

Option 1: Simple Issues (Single Task)

For straightforward issues that can be tackled in one sitting:

# Fetch the issue and create PROMPT.md
gh issue view 83 --repo owner/repo > PROMPT.md

# Or for cleaner output (body only):
gh issue view 83 --repo owner/repo --json title,body --jq '"# " + .title + "\n\n" + .body' > PROMPT.md

# Run Ralph
ralph run

Option 2: Complex Issues (Multiple Sub-tasks)

For issues with multiple components (like yours with SSE streaming, tunnel persistence, and S3 permissions):

# 1. Fetch the issue to a spec file
gh issue view 83 --repo owner/repo --json title,body --jq '"# " + .title + "\n\n" + .body' > specs/issue-83.md

# 2. Initialize with spec-driven preset
ralph init --preset spec-driven --backend claude

# 3. Point PROMPT.md at the spec
echo "Implement the fixes described in specs/issue-83.md" > PROMPT.md

# 4. Run - the Planner will break it into tasks
ralph run

Option 3: Using ralph plan (Interactive)

For when you want to review the plan before execution:

# Fetch issue content
gh issue view 83 --repo owner/repo --json body -q '.body' > specs/issue-83.md

# Interactive planning session
ralph plan "Fix issues in specs/issue-83.md"

# Review the tasks
ralph task list

# Then run
ralph run

Which Option to Choose?

Pro Tips

• Keep the issue link: Add <!-- Issue: https://github.com/owner/repo/issues/83 --> to your spec for traceability
• Scope down: If an issue has 3 unrelated problems, consider running Ralph 3 times on focused sub-specs
• Resume interrupted runs: ralph run --resume continues where you left off

Available Presets

View all presets:

ralph init --list-presets

Key presets:

• spec-driven - Spec Writer → Critic → Builder → Verifier
• feature - Builder → Reviewer cycle with backpressure
• documentation-first - README-driven development
• tdd-red-green - Test-driven development
• debug - Bug investigation workflow

Dotfiles Presets

Custom presets live in ~/.dotfiles/agents/skills/ralph-orchestrator/references/ (or via the ~/.dotfiles/claude/skills/ compatibility symlink):

• prd-to-code-assist.yml - Start from existing PRD, skip design debate

PRD-Driven Workflow

When you already have a detailed PRD and want to skip the design debate phase:

Quick Start (Existing PRD)

# Use the prd-to-code-assist preset from dotfiles
ralph run -c ~/.dotfiles/agents/skills/ralph-orchestrator/references/prd-to-code-assist.yml \
  --prompt "Implement specs/canvas/prd.md"

# Or copy to your project and customize
cp ~/.dotfiles/agents/skills/ralph-orchestrator/references/prd-to-code-assist.yml ./ralph.yml

prd-to-code-assist Workflow (5 hats)

File Organization

your-project/
├── specs/
│   └── {feature-name}/
│       ├── design.md      # Your PRD (copy or symlink)
│       ├── context.md     # Generated: codebase patterns
│       ├── plan.md        # Generated: implementation plan
│       └── tasks/
│           ├── task-01-*.code-task.md
│           └── task-02-*.code-task.md
└── ralph.yml

Full PDD Workflow (9 hats)

For rough ideas that need design refinement first, use pdd-to-code-assist:

ralph run -c presets/pdd-to-code-assist.yml --prompt "Build a rate limiter"

This adds Inquisitor → Architect → Design Critic before the implementation phase.

Evolutionary Meta-Orchestrator

The meta-orchestrator runs multiple approaches in parallel, grades them, identifies failure patterns, and evolves improved approaches until a target score is achieved.

Quick Start

# From any project with specs/ directory
~/.dotfiles/agents/skills/ralph-orchestrator/references/meta-orchestrator/run-meta.sh

# Or with custom config
~/.dotfiles/agents/skills/ralph-orchestrator/references/meta-orchestrator/run-meta.sh path/to/config.md

# Or run ralph directly
ralph run -c ~/.dotfiles/agents/skills/ralph-orchestrator/references/meta-orchestrator/ralph.yml

The 4 Hats

Configuration

Create .meta/config.md with:

• Task specification — What to implement
• Approaches — Configs/scripts to run with ports
• Grading rubric — Categories, verification commands, scoring
• Critical requirements — Pass/fail gates
• Target score — When to stop iterating

Error Taxonomy

The analyzer classifies failures to enable targeted evolution:

Output Structure

.meta/
├── config.md                 # Task config (input)
├── scratchpad.md             # Running state
├── iteration.txt             # Current iteration number
├── results/
│   ├── grades-1.md           # Scores with evidence
│   ├── analysis-1.md         # Error classification + patterns
│   └── ...
└── approaches/
    ├── evolved-1/
    │   ├── ralph.yml         # Improved config
    │   └── CHANGELOG.md      # What changed and why
    └── ...

Example: PRD Implementation

See ~/.dotfiles/agents/skills/ralph-orchestrator/references/meta-orchestrator/examples/prd-implementation.md for a complete example config.

Creating Custom Presets

Edit ralph.yml:

cli:
  backend: "claude"

core:
  specs_dir: "./specs/"
  guardrails:
    - "Fresh context - re-read specs each iteration"
    - "Backpressure is law - tests must pass"

event_loop:
  starting_event: "task.start"
  completion_promise: "LOOP_COMPLETE"
  max_iterations: 100

hats:
  my_hat:
    name: "🔨 My Hat"
    triggers: ["my.event"]
    publishes: ["my.done"]
    instructions: |
      What this hat should do...

CLI Reference

ralph run                    # Run the loop
ralph run --resume           # Continue interrupted loop
ralph run --verbose          # Show full prompts
ralph run --dry-run          # Show config without running
ralph plan "idea"            # Interactive planning session
ralph task <subcommand>      # Task management
ralph emit "topic" "payload" # Publish event
ralph init --preset <name>   # Initialize preset
ralph clean                  # Clean up .agent/ files

Project Structure

your-project/
├── ralph.yml          # Configuration
├── PROMPT.md          # Task prompt
├── specs/             # Specifications
│   └── prd.md
└── .agent/
    ├── tasks.jsonl    # Task tracking
    ├── scratchpad.md  # Working memory
    └── memories.md    # Persistent learnings

Supported Backends

Ralph supports 7 backends:

• claude - Claude Code CLI
• amp - Amp (Sourcegraph)
• codex - OpenAI Codex
• gemini - Google Gemini CLI
• kiro - Kiro CLI
• copilot - GitHub Copilot
• opencode - OpenCode

Set backend:

ralph init --preset feature --backend claude

Two Task Systems

Ralph has two separate task systems — don't confuse them:

Code Tasks (ralph task)

Alias for ralph code-task. Uses the code-task-generator SOP to create structured task files:

ralph task "Add rate limiting to API endpoints"
# Creates tasks/add-rate-limiting.code-task.md

Runtime Tasks (ralph tools task)

Used by agents during runs to track work:

ralph tools task add "Implement feature" -p 1
ralph tools task list
ralph tools task ready      # Show unblocked tasks
ralph tools task close <id>

Usage Patterns & FAQ

Prompt File Location — Flexible

The prompt file does not need to be in the repo root. Precedence:

1. CLI inline: ralph run -p "inline text"
2. CLI file path: ralph run -P specs/my-feature.spec.md
3. Config event_loop.prompt (inline text in YAML)
4. Config event_loop.prompt_file (file path in YAML)
5. Default fallback: PROMPT.md in current directory

Pattern: Keep specs organized in specs/ and point to them:

ralph run -P specs/issue-83-fix.md

Adding Tasks Mid-Run — Not Supported

Tasks are loaded once at startup from .agent/tasks.jsonl. No file watching during execution.

Pattern: Interrupt → edit → restart:

# Ctrl+C to interrupt
vim .agent/tasks.jsonl
ralph run -P specs/my-feature.md

Parallel Workers — Not Supported

Ralph is single-threaded orchestration. One hat → one execution → next iteration. The philosophy is "agents are smart, let them do the work" — not "spawn many agents."

Editing Plans Mid-Execution — Supported by Design

This is explicitly supported via Ralph's tenets:

"Disk Is State, Git Is Memory" — Tasks are the handoff mechanism. "The Plan Is Disposable" — Regeneration costs one planning loop.

Pattern:

1. Interrupt the run (Ctrl+C or let iteration complete)
2. Edit .agent/tasks.jsonl — mark tasks complete, add new ones, change priorities
3. Edit the spec/prompt file if needed
4. Restart: ralph run -P specs/my-feature.md

Ralph re-reads everything fresh each run. No "recovery" logic needed — that's the "Fresh Context Is Reliability" tenet.

Lighter Planning — No Fast Variant

Two planning options exist, both full workflows:

• ralph plan — Full PDD methodology (interactive)
• ralph task — Code task generator (structured output)

Neither has a "quick mode." Per the tenets: "The Plan Is Disposable" — regeneration is cheap.

Pattern for quick iterations: Skip ralph plan, write a minimal spec directly:

echo "Fix the auth bug in login.ts:45" > PROMPT.md
ralph run

Additional Resources

Reference Files

• references/prd-preset.yml - Complete PRD-driven workflow preset
• references/workflow-diagram.md - Visual workflow documentation
• references/meta-orchestrator/ - Evolutionary meta-orchestrator preset
  • ralph.yml - Main config with 4 hats (Orchestrator, Grader, Analyzer, Evolver)
  • run-meta.sh - Entry point script
  • examples/prd-implementation.md - Example task config

Example Files

• examples/simple-prd.md - Example PRD for string utilities