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

Usage

code

/generate-ralph-loop <path-to-spec-or-uat> [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)

bash

# 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

bash

# 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:

bash

ralph --version

If not installed, include installation instructions in output:

code

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)

bash

ralph init --backend claude

This creates ralph.yml config file.

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

•

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

bash

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

•
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 Orchestrator + suggest chunking

Output order (most to least recommended):

•Simple specs: /dev (unified workflow, auto-finds UAT)
•Medium specs: /dev or Ralph Orchestrator (both work well)
•Complex specs: Ralph Orchestrator (fresh context each iteration)

Step 2: Read and Parse Input File

The input can be a spec file or UAT file. Detect by:

•UAT files: contain UAT-X.Y patterns, scorecard tables with ⬜/✅/❌
•Spec files: contain "Success Criteria", "Components", "Solution" sections

From spec files, extract:

•Feature name — From heading or filename
•Success criteria — Bullet points under "Success Criteria" section
•Components — Listed components to implement
•Key decisions — From "Key Design Decisions" or similar sections

From UAT files, extract:

•Feature name — From heading or filename
•Test count — Count all UAT-X.Y entries
•Current score — Count ✅ vs total tests
•Categories — List of category headings

Step 3: Find or Generate UAT

If given a spec, look for UAT:

•{spec_basename}_uat.md
•{spec_basename}_acceptance_tests.md

If given a UAT, look for spec:

•{uat_basename}.md (e.g., p61.md from p61_uat.md)
•{uat_basename}_tech_spec.md

If UAT doesn't exist: Call /generate-uat {spec_path} to create it before generating the Ralph command. UAT gives Ralph concrete checkboxes to verify against.

Step 4: Generate Ralph Orchestrator Command

Output the simple one-liner only:

bash

ralph run --no-tui -p "Implement {FEATURE_NAME} per {SPEC_PATH}. {BRIEF_CONTEXT}. {UAT_CLAUSE}. Before complete: run /bmad:bmm:workflows:code-review and /design-audit, fix all issues."

Where:

•{BRIEF_CONTEXT} = 1-2 sentences max (key components, constraints)
•{UAT_CLAUSE} = "Verify against {uat_path}" (if UAT exists)

Always include quality gates: /bmad:bmm:workflows:code-review and /design-audit

Keep it short. Ralph will read the spec file for details.

DO NOT output:

•Long PROMPT.md heredocs
•Detailed success criteria lists
•Step-by-step implementation orders
•Component breakdowns

If the one-liner fails, THEN suggest creating a PROMPT.md as fallback.

Step 5: Generate Deprecated Internal Command (Fallback)

Only if --internal flag used or spec is very simple:

code

---

## ⚠️ Deprecated: Internal /ralph-loop

The internal `/ralph-loop` runs inside Claude's context window, which compacts over long loops.
Use Ralph Orchestrator instead for reliable iteration.

**If you still want to use internal loop (simple tasks only):**

/ralph-loop "{PROMPT}" --max-iterations {MAX_ITERATIONS} --completion-promise "<promise>{FEATURE_NAME} COMPLETE</promise>"

Step 6: Output Format

Keep output minimal:

code

# {FEATURE_NAME} — Development Command

**Requirements:** {N} | **Risk:** {keywords or "none"} | **Recommendation:** {/dev | Ralph}

---

## Option 1: /dev (recommended for most cases)

/dev {SPEC_PATH}

code


Auto-finds UAT, runs verification, handles parallelization.

## Option 2: Ralph (for long/complex features)

```bash
ralph run --no-tui -p "{SHORT_PROMPT}"

Stop: Ctrl+C (graceful) or pkill -f ralph (force kill)

When to use Ralph over /dev: 10+ iterations expected, context might degrade.

code


That's it. No long setup instructions, no heredocs, no component lists.

## Edge Cases

| Scenario | Behavior |
|----------|----------|
| Spec not found | Error with suggestion to check path |
| No success criteria in spec | Warning: "No explicit success criteria found. Consider adding a Success Criteria section." Generate command anyway using inferred criteria from description. |
| Very simple spec (<8 req) | Recommend `/dev` (auto-finds UAT, interactive) |
| Medium spec (8-15 req) | Recommend `/dev` or Ralph (both work well) |
| Very complex spec (20+ req) | Recommend Ralph + chunking: "Consider breaking into smaller features." |
| Ralph not installed | Include installation instructions: `npm install -g @anthropic-ai/ralph-cli` |
| `--internal` flag | Output internal /ralph-loop command (with deprecation warning) |
| `--prompt-file` flag | Generate PROMPT.md file in project root instead of inline command |
| UAT file provided | Use UAT for structured tracking (update scorecard during iteration) |

## Example 1: Medium Spec (with UAT)

**Input:**

/generate-ralph-loop features/p89_swipeable_card_view.md

code


**Output:**

P89 Swipeable Card View

Requirements: 12 | Risk: none | Recommendation: /dev

Option 1: /dev (recommended)

code

/dev features/p89_swipeable_card_view.md

Auto-finds features/p89_uat.md, runs verification.

Option 2: Ralph (if expecting many iterations)

bash

ralph run --no-tui -p "Implement P89 Swipeable Card View per features/p89_swipeable_card_view.md. Verify against features/p89_uat.md. Before complete: run /bmad:bmm:workflows:code-review and /design-audit, fix all issues."

Stop: Ctrl+C or pkill -f ralph

code


## Example 2: Spec without UAT

**Input:**

/generate-ralph-loop features/p85_event_verification_flow.md

code


**Behavior:**
1. No `features/p85_uat.md` found
2. Calls `/generate-uat features/p85_event_verification_flow.md` to create it
3. Then outputs command with UAT reference

## Example 3: Simple Spec

**Input:**

/generate-ralph-loop features/p95_fix_button_color.md

code


**Output:**

P95 Fix Button Color

Requirements: 3 | Risk: none | Recommendation: /dev

Run

code

/dev features/p95_fix_button_color.md

Simple task — /dev will handle it interactively.

code


---

## Operational Notes

### Stopping Ralph

| Method | When to use |
|--------|-------------|
| `Ctrl+C` | During execution — graceful stop |
| `pkill -f ralph` | From another terminal — force kill |

### Initialization Reminder

Before running Ralph for the first time in a worktree:

```bash
ralph init --backend claude

What --backend claude does:

•Configures Ralph to use Claude as the AI backend (vs. GPT, Gemini, etc.)
•Creates ralph.yml with backend settings
•Does NOT read CLAUDE.md — it just sets which AI provider to use

The AI will still read CLAUDE.md through Claude Code's normal context loading.

Worktree options:

•Commit ralph.yml — Share config across worktrees (recommended)
•Init per worktree — Run ralph init --backend claude in each one

Generate Ralph Loop

Why Ralph Orchestrator over internal /ralph-loop?

Usage

Parameters

Important: How to Run Ralph

❌ WRONG (common mistake)

✅ CORRECT Methods

Why --no-tui?

Workflow

Step 0: Check Ralph Orchestrator Installation

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

Step 1: Analyze Spec Complexity (Smart Recommendation)

Step 2: Read and Parse Input File

Step 3: Find or Generate UAT

Step 4: Generate Ralph Orchestrator Command

Step 5: Generate Deprecated Internal Command (Fallback)

Step 6: Output Format

P89 Swipeable Card View

Option 1: /dev (recommended)

Option 2: Ralph (if expecting many iterations)

P95 Fix Button Color

Run

Why `--no-tui`?