Generate Ralph Loop

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 <path-to-spec-or-uat> [options]

Parameters

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)

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

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:

Output order (most to least recommended):

1. Simple specs: /dev (unified workflow, auto-finds UAT)
2. Medium specs: /dev or Ralph Orchestrator (both work well)
3. 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:

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

From UAT files, extract:

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

Step 3: Find or Suggest UAT

If given a spec, look for UAT (check in order):

• features/uat/p{N}.md (e.g., features/uat/p89.md for p89_swipeable_card_view.md)
• {spec_basename}_acceptance_tests.md (legacy fallback)

If given a UAT, look for spec:

• features/p{N}_*.md (e.g., features/p61_*.md from features/uat/p61.md)
• {uat_basename}_tech_spec.md

If UAT doesn't exist: Suggest generating it, but don't auto-generate. Let user decide based on complexity.

Step 4: Generate Ralph Orchestrator Command

Output the simple one-liner only:

ralph run --no-tui -p "Implement {FEATURE_NAME} per {SPEC_PATH}. {BRIEF_CONTEXT}. {UAT_CLAUSE}. Before complete: run /bmad:bmm:workflows:code-review and /finish, 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 /finish

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:

---

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

# {FEATURE_NAME} — Development Command

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

---

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

/dev {SPEC_PATH}

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.

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 @ralph-orchestrator/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

**Output:**

P89 Swipeable Card View

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

Option 1: /dev (recommended)

/dev features/p89_swipeable_card_view.md

Auto-finds features/uat/p89.md, runs verification.

Option 2: Ralph (if expecting many iterations)

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

Stop: Ctrl+C or pkill -f ralph

## Example 2: Spec without UAT (medium complexity)

**Input:**

/generate-ralph-loop features/p85_event_verification_flow.md

**Behavior:**
1. No `features/uat/p85.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

**Output:**

P95 Fix Button Color

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

Run

/dev features/p95_fix_button_color.md

Simple task — /dev will handle it interactively.

---

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

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