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.
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)
| 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 |
Before generating commands, assess feature complexity from the ### Implementation Approach / #### Build Sequence section:
**Files to Create:** / **Files to Modify:**)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-loop <path-to-spec-or-uat> [options]
| 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 |
CRITICAL: Ralph requires either a PROMPT.md file OR an inline prompt string. It does NOT read spec files directly from the -p flag.
# This passes a FILE PATH as prompt text — Ralph won't read the file!
ralph run -p features/p89_swipeable_card_view.md
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."
--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 |
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
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:
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).
Read the spec file and extract:
- [ ] checkboxes, success criteria, "must", "should", "will" statementsauth, payment, migration, security, breaking change, RLSDecision 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):
/dev (unified workflow, auto-finds UAT)/dev or Ralph Orchestrator (both work well)The input can be a spec file or UAT file. Detect by:
UAT-X.Y patterns, scorecard tables with ⬜/✅/❌From spec files, extract:
From UAT files, extract:
UAT-X.Y entriesIf 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.mdIf UAT doesn't exist: Suggest generating it, but don't auto-generate. Let user decide based on complexity.
| Complexity | UAT Recommendation |
|---|---|
| Simple (<8 req) | "UAT optional — spec has clear success criteria" |
| Medium (8-15 req) | "Consider: /generate-uat {spec_path} for structured tracking" |
| Complex (15+ req) | "Recommended: /generate-uat {spec_path} before starting" |
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:
If the one-liner fails, THEN suggest creating a PROMPT.md as 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>"
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:**
Requirements: 12 | Risk: none | Recommendation: /dev
/dev features/p89_swipeable_card_view.md
Auto-finds features/uat/p89.md, runs verification.
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:**
Requirements: 3 | Risk: none | Recommendation: /dev
/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:
ralph.yml with backend settingsThe AI will still read CLAUDE.md through Claude Code's normal context loading.
Worktree options:
ralph.yml — Share config across worktrees (recommended)ralph init --backend claude in each one