---
description: "Start a Ralph loop tied to a workplan file — retires automatically when all tasks are done"
argument-hint: "<workplan-file> [--max-iterations N]"
allowed-tools: ["Read", "Bash(${CLAUDE_PLUGIN_ROOT}/scripts/check-done.sh:*)", "Bash(${CLAUDE_PLUGIN_ROOT}/scripts/setup.sh:*)"]
hide-from-slash-command-tool: "true"
---

# Ralph Workplan

Start a ralph loop driven by a workplan file. The loop retires automatically
when all tasks in the workplan are marked done.

## Usage

```
/ralph-workplan workplans/WP-0001-my-task.md
/ralph-workplan workplans/WP-0001-my-task.md --max-iterations 15
```

The workplan file must follow the format described in `workplan-spec.md`
(YAML frontmatter with `id`, `title`, `status` fields; tasks as fenced
`task` code blocks with `id` and `status`).

## Steps

Parse `$ARGUMENTS` to extract:
- `WORKPLAN_FILE` — the positional argument (required)
- `MAX_ITERATIONS` — value after `--max-iterations` (default: 20)

**Step 1 — Validate the workplan file exists**

If the file does not exist:
> "❌ Workplan file not found: $WORKPLAN_FILE"

Stop.

**Step 2 — Read the workplan frontmatter**

Read `$WORKPLAN_FILE`. Extract from the YAML frontmatter:
- `id` — workplan identifier
- `title` — workplan title
- `status` — current status

**Step 3 — Guard: check if already done**

Run:
```bash
"${CLAUDE_PLUGIN_ROOT}/scripts/check-done.sh" "$WORKPLAN_FILE"
```

Exit code 0 means the workplan is already done. If so:
> "✅ Workplan $ID ('$TITLE') is already done — all tasks complete.
>  Nothing to do. No ralph loop started."

Stop.

**Step 4 — Show current task summary**

Count the task blocks in the file (fenced blocks with language tag `task`).
Report:
> "📋 $ID — $TITLE
>  Tasks: X done, Y in progress, Z todo (N total)
>  Starting ralph loop (max $MAX_ITERATIONS iterations)..."

**Step 5 — Start the loop**

Run:
```bash
"${CLAUDE_PLUGIN_ROOT}/scripts/setup.sh" \
  "$WORKPLAN_FILE" "$ID" "$TITLE" "$MAX_ITERATIONS"
```

Then report:
> "🔄 Ralph loop active. The loop will feed the workplan prompt back on every
>  iteration. It retires when all tasks are done and the workplan status is
>  updated to 'done' in the file."