---
name: ralph-loop
description: Iterative AI development loop with MCP validation, progress tracking, and completion promises.
argument-hint: "[-m N] [-c TEXT] [-v] <task description>"
---

<objective>
Execute the Ralph Weegund technique - an iterative development methodology where the same prompt is fed repeatedly until completion. Uses progressive step loading with MCP validation and progress persistence.
</objective>

<quick_start>
**Basic usage:**

```bash
/ralph-loop implement user authentication
```

**With completion promise:**

```bash
/ralph-loop -c "COMPLETE" refactor the cache layer
```

**With max iterations:**

```bash
/ralph-loop -m 20 -c "TESTS PASS" add comprehensive tests
```

**Verbose mode:**

```bash
/ralph-loop -v -c "DONE" fix all linting errors
```

**Flags:**

- `-m N` (max): Maximum iterations before auto-stop
- `-c TEXT` (complete): Completion promise text
- `-v` (verbose): Detailed logging

See `<parameters>` for complete flag list.
</quick_start>

<parameters>

<flags>
**Flags:**
| Short | Long | Description |
|-------|------|-------------|
| `-m N` | `--max-iterations N` | Maximum iterations (default: 50) |
| `-c TEXT` | `--completion-promise TEXT` | Text that signals completion |
| `-v` | `--verbose` | Enable detailed logging |
| `-r` | `--resume` | Resume from previous state |
</flags>

<examples>
```bash
# Basic loop
/ralph-loop implement feature X

# With completion signal
/ralph-loop -c "ALL TESTS PASS" fix failing tests

# Limited iterations with completion
/ralph-loop -m 10 -c "REFACTOR COMPLETE" clean up auth module

# Resume previous loop
/ralph-loop -r

# Verbose mode
/ralph-loop -v -m 25 -c "DONE" implement CRUD for products
```
</examples>

<parsing_rules>
**Argument parsing:**

1. `-m N` or `--max-iterations N` -> `{max_iterations}` = N
2. `-c TEXT` or `--completion-promise TEXT` -> `{completion_promise}` = TEXT
3. `-v` or `--verbose` -> `{verbose_mode}` = true
4. `-r` or `--resume` -> `{resume_mode}` = true
5. Remainder -> `{task_description}`
</parsing_rules>

</parameters>

<ralph_concept>
**Core concept:**

The same prompt is fed to Claude repeatedly. The "self-referential" aspect comes from Claude seeing its own previous work in files and git history.

**Each iteration:**
1. Claude receives the SAME prompt
2. Works on the task, modifying files
3. Checks completion criteria
4. If not complete: saves progress, iteration count increments
5. Claude sees previous work in the files
6. Iteratively improves until completion promise is output

**Completion signal:**
```
<promise>{completion_promise}</promise>
```

The loop only stops when this exact tag is output or max iterations reached.
</ralph_concept>

<workflow>
**Standard flow:**
1. Parse flags and task description
2. Verify MCP servers are available (MANDATORY)
3. Initialize .ralph/ structure and state files
4. Load current task from prd.json (or create initial tasks)
5. Execute ONE task per iteration
6. Commit changes, update progress
7. Check completion criteria
8. If complete: generate final report
</workflow>

<state_variables>
**Persist throughout all steps:**

| Variable | Type | Description |
|----------|------|-------------|
| `{task_description}` | string | The prompt/task to execute |
| `{max_iterations}` | number | Maximum iterations allowed |
| `{completion_promise}` | string | Text that signals completion |
| `{verbose_mode}` | boolean | Enable detailed logging |
| `{resume_mode}` | boolean | Resume from previous state |
| `{current_iteration}` | number | Current iteration count |
| `{tasks_completed}` | number | Number of tasks completed |
| `{tasks_total}` | number | Total tasks in prd.json |

</state_variables>

<mcp_requirements>
**MANDATORY MCP Validation:**

Before ANY work, verify MCP servers:

1. **SmartStack MCP** - `mcp__smartstack__validate_conventions`
2. **Context7 MCP** - `mcp__plugin_context7_context7__resolve-library-id`

**If ANY MCP unavailable:**
- DO NOT proceed
- Log failure to `.ralph/logs/`
- Output error message
- Suggest: `smartstack check-mcp`

**Throughout work, use:**
- `mcp__smartstack__validate_conventions` - Before commits
- `mcp__smartstack__check_migrations` - Before EF Core changes
- `mcp__smartstack__scaffold_extension` - For code generation
</mcp_requirements>

<entry_point>

**FIRST ACTION:** Load `steps/step-00-init.md`

</entry_point>

<step_files>
**Progressive loading - only load current step:**

| Step | File | Purpose |
|------|------|---------|
| 00 | `steps/step-00-init.md` | Parse args, verify MCP, initialize state |
| 01 | `steps/step-01-task.md` | Load current task from prd.json |
| 02 | `steps/step-02-execute.md` | Execute ONE task |
| 03 | `steps/step-03-commit.md` | Commit, update prd.json/progress.txt |
| 04 | `steps/step-04-check.md` | Check completion, decide next action |
| 05 | `steps/step-05-report.md` | Generate final report |

</step_files>

<file_structure>
**Ralph creates these files:**

```
.ralph/
├── prd.json          # Task list with status
├── progress.txt      # Persistent memory between iterations
├── logs/
│   └── {timestamp}.log
└── reports/
    └── {feature-name}.md
```

**prd.json structure:**
```json
{
  "feature": "{task_description}",
  "created": "2024-01-01T00:00:00Z",
  "max_iterations": 50,
  "completion_promise": "COMPLETE",
  "tasks": [
    { "id": 1, "description": "Task 1", "passes": false },
    { "id": 2, "description": "Task 2", "passes": false }
  ]
}
```
</file_structure>

<execution_rules>

- **Load one step at a time** - Only load the current step file
- **VERIFY MCP FIRST** - Never skip MCP validation
- **ONE TASK PER ITERATION** - Don't batch tasks
- **COMMIT AFTER EACH TASK** - Atomic progress
- **UPDATE progress.txt** - Persist learnings
- **NEVER fake completion** - Only output promise when truly done
</execution_rules>

<success_criteria>

- All tasks in prd.json have `passes: true`
- MCP validations pass
- Git commits atomic per task
- Completion promise output when genuinely complete
- Final report generated in `.ralph/reports/`
</success_criteria>

<available_commands>
**Related commands:**
- `/ralph-loop:cancel-ralph` - Cancel active loop
- `/ralph-loop:help` - Show documentation
</available_commands>
