double-ralph

Name: double-ralph
Author: cbzehner

by @cbzehner in DevOps & Cloud

# Install this skill:

npx skills add cbzehner/claude-skill-double-ralph

Or install specific skill: npx add-skill https://github.com/cbzehner/claude-skill-double-ralph

# Description

Iterative implementation loop with review checkpoints. Use for multi-step tasks that benefit from chunked execution and verification. Adapts to project-specific conventions via .ralph.md guidance file.

# SKILL.md

name: double-ralph
description: Iterative implementation loop with review checkpoints. Use for multi-step tasks that benefit from chunked execution and verification. Adapts to project-specific conventions via .ralph.md guidance file.

Double Ralph: Iterative Implementation Loop

Execute work through iterative cycles with review checkpoints between chunks.

Invocation

/double-ralph [state-file]

Examples:
- /double-ralph plans/my-feature.md - Execute a plan file
- /double-ralph - Auto-detect state file per project guidance

Project Guidance

Double-ralph adapts to project-specific conventions via a .ralph.md file.

Finding .ralph.md

Search in order:
1. Git repository root: git rev-parse --show-toplevel then check for .ralph.md
2. Walk up from current directory: Check each parent until .ralph.md found or root reached
3. State file's directory: If state file provided, check its directory

# Get git project root
git rev-parse --show-toplevel 2>/dev/null

If No .ralph.md Found

Use AskUserQuestion to offer creating one:

"No .ralph.md found for this project. Would you like to create one?"
- Yes, help me create it - Ask design questions, generate .ralph.md
- Use defaults - Continue with plan-file conventions
- Skip for now - Continue without guidance

See examples/ in this skill's directory for templates and the README for guidance on crafting .ralph.md files.

The Loop

1. LOAD

Find and load .ralph.md if present (provides project-specific guidance)
Read the state file
Parse state according to guidance (or use default plan format)

Default format (when no .ralph.md):

---
status: pending  # pending | in_progress | complete | archived
gaps: []
edge_cases: []
progress: []
last_review: null
---

# Title

## Section 1
...

If file lacks frontmatter, add defaults.

2. ASSESS

Check completion status → if complete/archived, inform user and exit
Update status to in_progress if pending
Identify work units per guidance:
Default: ## headings not in progress array
Per guidance: acceptance criteria, issues, custom sections
Group related units if guidance suggests logical groupings
If all units complete → proceed to final review

3. SPAWN INNER LOOP

Use the Task tool to spawn a subagent:

Task(
  subagent_type: "general-purpose",
  description: "Implement: [work unit summary]",
  prompt: [see inner-prompt.md, include project guidance if present]
)

Inner loop works until:
- Work unit complete
- Blocked (needs decision, unclear requirement)
- ~15-20 turns (context management)
- Context feels heavy

Returns structured summary (see inner-prompt.md for format).

4. REVIEW

Review method per .ralph.md guidance. Default: magi synthesis.

/magi "Review this implementation work:

## Work Summary
[inner loop's returned summary]

## Work Unit
[what was being implemented]

## Evaluate
1. Implementation correctness - Does it work? Tests pass?
2. Alignment - Did the work match the intended unit?
3. Gap discovery - Any new gaps, edge cases, or TODOs?
4. Completeness - Is the overall work fully realized?

Return structured assessment:
- verdict: pass | fail | needs_work
- gaps_discovered: [list]
- edge_cases_discovered: [list]
- remaining_work: [description]
- recommendation: continue | needs_human_input | archive
- rationale: [brief explanation]"

Fallback: If magi unavailable, perform the review yourself.

5. UPDATE STATE

Update the state file per guidance:
- Default: Update frontmatter arrays (gaps, edge_cases, progress)
- Per guidance: Check off criteria, append to sections, etc.

Set review timestamp.

6. ROUTE

Based on review recommendation:

continue: Go to step 2.

needs_human_input:
- Use AskUserQuestion to surface the decision
- Present: what was attempted, what needs clarification, options
- After response → step 2

archive (or equivalent completion):
- Verify no remaining gaps/issues per guidance
- Mark complete and move/archive per guidance
- If issues remain → inform user, continue to step 2

Completion Criteria

The loop completes when:
1. Review assesses work as "fully realized"
2. No remaining gaps or blockers
3. Per-guidance completion signals sent (if applicable)

Error Handling

Scenario	Action
Magi unavailable	Self-review (continue functioning)
Inner loop blocked	Surface via AskUserQuestion
State file parse error	Show error, ask user to fix
No .ralph.md	Offer to create or use defaults

Manual Control

Interrupt anytime. State file preserves progress. Resume with /double-ralph [state-file].

Reference

inner-prompt.md - Inner loop subagent template
examples/ - Example .ralph.md files for different project types
examples/README.md - Guide for crafting .ralph.md files
docs/ARCHITECTURE.md - Full architecture documentation

# README.md

Double Ralph

Iterative implementation loops with review checkpoints. What could possibly go wrong?

"More Ralphs is always better, rite?"

An outer Ralph orchestrates. Inner Ralphs implement. Magi reviews.
It's Ralphs all the way down.

        ┌──────────────────────────┐
        │      OUTER RALPH         │
        │    (the orchestrator)    │
        │            │             │
        │            ▼             │
        │   ┌────────────────┐     │
        │   │  INNER RALPH   │     │
        │   │  (does work)   │     │
        │   └────────────────┘     │
        │            │             │
        │            ▼             │
        │      /magi review        │
        │            │             │
        │            ▼             │
        │    repeat until done     │
        │    (or until chaos)      │
        └──────────────────────────┘

Why?

Long tasks lose context. Claude forgets what it was doing 47 tool calls ago. Double Ralph fixes this by:

Chunking work - Inner Ralphs work on one unit at a time
Reviewing progress - Magi checks each chunk before continuing
Persisting state - Everything saved to file, so you can stop and resume

It's like having a responsible adult supervise the hyperactive code monkeys.

Prerequisites

Works best with magi installed for reviews. Falls back to self-review if unavailable (Ralph reviewing Ralph's work—totally objective).

Installation

From Marketplace

/plugin marketplace add cbzehner/claude-skill-double-ralph
/plugin install double-ralph@cbzehner

Manual Installation

cd ~/.claude/skills/
git clone https://github.com/cbzehner/claude-skill-double-ralph.git double-ralph

Usage

/double-ralph [state-file]

Point it at a plan or task file and watch the Ralphs go:

You: /double-ralph plans/auth-system.md

Claude: [Outer Ralph reads the plan]
        [Spawns Inner Ralph for Section 1]
        [Inner Ralph builds stuff, runs tests]
        [Inner Ralph returns: "I did things!"]
        [Magi reviews: "The things are acceptable."]
        [Outer Ralph updates plan, moves to Section 2]
        [Repeat until victory or /triple-ralph]

Project Guidance (.ralph.md)

Double-ralph adapts to your project's conventions via a .ralph.md file at your repo root.

What It Does

Without .ralph.md: Uses default plan-file conventions (YAML frontmatter + ## sections).

With .ralph.md: Adapts to your project's way of doing things:
- Where state files live
- How to identify work units (sections, acceptance criteria, issues)
- When and how to review
- How to signal completion

Creating One

Run /double-ralph without a .ralph.md and you'll be offered the choice to create one. The skill asks questions about your project and generates a starter file.

Or see examples/ for templates:
- plan-based.ralph.md - Traditional plan files with ## sections
- task-based.ralph.md - Task files with acceptance criteria (launchpad-style)
- github-issues.ralph.md - GitHub issues as work units
- minimal.ralph.md - Simplest possible configuration

See examples/README.md for a guide on crafting your own.

Example .ralph.md

# .ralph.md - My Project

## State Files
Tasks in `.tasks/` with YAML frontmatter and acceptance criteria.

## Work Units
Each unchecked criterion is a work unit. Group related criteria.

## Review
Self-review after each unit. Magi review before completion.

## Completion
When all criteria met: signal done via `/done`.

Default State Format

When no .ralph.md is found, uses YAML frontmatter + markdown sections:

---
status: pending  # pending | in_progress | complete | archived
gaps: []         # things we discovered we need
edge_cases: []   # things that might explode
progress: []     # sections completed
last_review: null
---

# My Feature Plan

## Section 1: The Setup
What to build...

## Section 2: The Hard Part
The actual work...

Frontmatter gets added automatically if missing.

The Loop

┌─────────────────────────────────────────────────────────┐
│                     OUTER RALPH                         │
│                                                         │
│  1. LOAD    → Find .ralph.md, read state file           │
│  2. ASSESS  → Find next incomplete work unit            │
│  3. SPAWN   → Inner Ralph implements it                 │
│  4. REVIEW  → Magi (or self) checks the work            │
│  5. UPDATE  → Save progress per guidance                │
│  6. ROUTE   → Continue | Ask human | Complete           │
│                                                         │
│  Inner Ralph exits when:                                │
│  • Work unit complete                                   │
│  • Hit a blocker                                        │
│  • ~15-20 turns (context getting heavy)                 │
│  • Existential crisis                                   │
└─────────────────────────────────────────────────────────┘

Completion

Work gets marked complete when:
1. Review says "this is done"
2. AND no gaps remain
3. AND per-guidance completion signals sent

Until then, the Ralphs keep Ralphing.

Error Handling

Problem	Solution
Magi unavailable	Ralph reviews Ralph (it's fine)
Inner Ralph blocked	Asks you for help
State file broken	Shows error, asks you to fix it
No .ralph.md	Offers to create one or uses defaults
Triple Ralph attempted	inconceivable

Files

double-ralph/
├── SKILL.md              # The actual skill
├── inner-prompt.md       # Template for Inner Ralph
├── README.md             # You are here
├── LICENSE               # MIT (Ralphs are free)
├── docs/
│   └── ARCHITECTURE.md   # The serious documentation
├── examples/
│   ├── README.md         # Guide for crafting .ralph.md
│   ├── plan-based.ralph.md
│   ├── task-based.ralph.md
│   ├── github-issues.ralph.md
│   ├── minimal.ralph.md
│   └── example-plan.md   # A sample plan file
└── plans/
    └── archived/         # Where completed plans go to rest

Manual Override

Interrupt anytime. State is saved to file. Come back later and /double-ralph picks up where it left off. The Ralphs are patient.

License

MIT

"What could go wrong?" — Everyone, right before finding out

# Supported AI Coding Agents

This skill is compatible with the SKILL.md standard and works with all major AI coding agents:

⚡ Amp 🚀 Antigravity 🤖 Claude Code 🦀 Clawdbot 📝 Codex ▶️ Cursor 🤖 Droid 💎 Gemini CLI 🐙 GitHub Copilot 🪿 Goose 📊 Kilo Code 🔧 Kiro CLI 💻 OpenCode 🦘 Roo Code 🌲 Trae 🏄 Windsurf

Learn more about the SKILL.md standard and how to use these skills with your preferred AI coding agent.

double-ralph

# Description

# SKILL.md

Double Ralph: Iterative Implementation Loop

Invocation

Project Guidance

Finding .ralph.md

If No .ralph.md Found

The Loop

1. LOAD

2. ASSESS

3. SPAWN INNER LOOP

4. REVIEW

5. UPDATE STATE

6. ROUTE

Completion Criteria

Error Handling

Manual Control

Reference

# README.md

Double Ralph

Why?

Prerequisites

Installation

From Marketplace

Manual Installation

Usage

Project Guidance (.ralph.md)

What It Does

Creating One

Example .ralph.md

Default State Format

The Loop

Completion

Error Handling

Files

Manual Override

License

# Related Skills

# Supported AI Coding Agents

Confirm

Submit a Skill