SKILL

---
name: generate-ralph-loop
description: Generate commands for Ralph Orchestrator (external tool) or Claude Code's internal /ralph-loop. Reads a spec or UAT file, analyzes complexity, and outputs ready-to-run commands. Primary output is Ralph Orchestrator (solves context compaction). Internal /ralph-loop is deprecated fallback for simple tasks.
when_to_use: "After /generate-tests, when setting up iterative AI dev loops for complex features."
version: 1.0.0
---

# Generate Ralph Loop

Generate ready-to-run commands for iterative AI development loops.

**Primary output:** Ralph Orchestrator commands (external tool, no context compaction)
**Fallback:** Claude Code's internal `/ralph-loop` (deprecated, for simple tasks only)

## Why Ralph Orchestrator over internal /ralph-loop?

| Aspect | Ralph Orchestrator (external) | /ralph-loop (internal) |
|--------|------------------------------|------------------------|
| Context | Fresh each iteration | Compacts over time |
| State | Files (`.agent/memories.md`) | Degrades with compaction |
| Long loops | ✅ Reliable | ❌ Forgets earlier work |
| Setup | Requires `ralph` CLI installed | Built into Claude Code |
| Best for | Complex features, 10+ iterations | Simple tasks, <5 iterations |

## Complexity Check

Before generating commands, assess feature complexity from the `### Implementation Approach` / `#### Build Sequence` section:
- Count **files** to create + modify (from `**Files to Create:**` / `**Files to Modify:**`)
- Count **concerns** (distinct system layers: DB, service, UI, API, tests each = 1)
- Count **build steps** (numbered items in Build Sequence)

**If 5+ files OR 3+ concerns OR 6+ steps:**

> "This feature exceeds ralph-loop's effective range (5+ files or 6+ steps).
> Recommend: run /decompose first to create a task manifest, then /dev will orchestrate per-task subagents — each with fresh context, no compaction risk.
> Ralph-loop works best for medium features (3–5 files, 3–5 steps)."

Stop and output the recommendation above. Do not generate a ralph command.

**If the spec already has `## Implementation Tasks`** (decompose already ran):
- Generate ralph commands from the task manifest, one loop per task
- Each loop covers one task's files, spec refs, and verification step
- Use the task title as the loop description

---

## Usage

/generate-ralph-loop [options]

## Parameters

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `<path>` | Yes | - | Path to spec file (e.g., `features/p89_swipeable_card_view.md`) or UAT file |
| `--spec` | No | auto-detect | Path to tech spec (overrides auto-detection) |
| `--uat` | No | auto-detect | Path to UAT file (if separate from spec) |
| `--max-iterations` | No | 30 | Safety limit for iterations |
| `--preset` | No | spec-driven | Ralph preset: `spec-driven`, `tdd-red-green`, `feature` |
| `--internal` | No | false | Force output of internal /ralph-loop (deprecated) |
| `--prompt-file` | No | false | Generate PROMPT.md file instead of inline command |

## Important: How to Run Ralph

**CRITICAL:** Ralph requires either a PROMPT.md file OR an inline prompt string. It does NOT read spec files directly from the `-p` flag.

### ❌ WRONG (common mistake)
```bash
# This passes a FILE PATH as prompt text — Ralph won't read the file!
ralph run -p features/p89_swipeable_card_view.md

✅ CORRECT Methods

Method 1: Create PROMPT.md file (recommended)

# Step 1: Create PROMPT.md with your task
echo "Implement P89 per features/p89_swipeable_card_view.md" > PROMPT.md

# Step 2: Run Ralph (it reads PROMPT.md automatically)
ralph run --no-tui

Method 2: Inline prompt with task description

# Pass the DESCRIPTION, not the file path
ralph run --no-tui -p "Implement P89 Swipeable Card View per features/p89_swipeable_card_view.md. Create ViewToggle, CardStack components."

Why --no-tui?

The TUI (terminal UI) has compatibility issues with some terminals like Ghostty. Use --no-tui for reliable text output that works everywhere.

Flag	When to use
ralph run	Standard terminals (iTerm2, Terminal.app)
ralph run --no-tui	Ghostty, or if TUI shows blank/blinking screen

Workflow

Step 0: Check Ralph Orchestrator Installation

First, verify Ralph Orchestrator is available:

ralph --version

If not installed, include installation instructions in output:

Note: Ralph Orchestrator not detected.
Install with: npm install -g @ralph-orchestrator/ralph-cli
Or: brew install ralph-orchestrator

Step 0.5: Initialize Ralph (one-time per project)

ralph init --backend claude

This creates ralph.yml config file.

Worktree tip: If you use git worktrees, you have two options:

1. Commit ralph.yml to git — all worktrees share the same config:

   ralph init --backend claude
   git add ralph.yml
   echo ".agent/" >> .gitignore  # Keep memories per-worktree
   git commit -m "chore: add ralph config"
   

2. Init per worktree — run ralph init --backend claude in each worktree separately

Recommended: Commit ralph.yml, gitignore .agent/ (memories/tasks are session-specific).

Step 1: Analyze Spec Complexity (Smart Recommendation)

Read the spec file and extract:

• Requirements count — Count - [ ] checkboxes, success criteria, "must", "should", "will" statements
• Risk keywords — auth, payment, migration, security, breaking change, RLS
• Integration points — External APIs, DB schema changes, third-party services
• Component count — New components listed in spec

Decision logic:

Condition	Recommendation
Requirements < 8 AND no risk keywords AND integrations < 2	/dev (simple, interactive)
Requirements < 15 AND minimal risk	/dev or Ralph Orchestrator
Complex (15+ req, risk keywords, many integrations)	Ralph
```