---
name: run
description: Execute the generator-evaluator loop interactively inside Claude Code. Dispatches subagents with full visibility and intervention capability. Run /agent-loop:init and /agent-loop:plan first.
---

# /run — Execute Agent Loop Inside Claude Code

Run the generator-evaluator loop natively in Claude Code using subagents. Unlike `loop.sh` (headless), this gives you full visibility into each agent's work and the ability to intervene at any point.

## Usage

```
/agent-loop:run                    # Run until all stories pass or max iterations
/agent-loop:run 3                  # Run at most 3 iterations
/agent-loop:run --skip-eval        # Skip evaluator (generator marks stories done)
/agent-loop:run --story US-003     # Run only a specific story
```

## Prerequisites

- `.loop/config.json` exists (run `/agent-loop:init` first)
- `.loop/prd.json` exists with stories (run `/agent-loop:plan` first)

## Instructions

When the user invokes `/loop-run`, follow this orchestration sequence exactly.

### Step 0: Parse Arguments

- If a number is provided, use it as max iterations. Otherwise read `maxIterations` from `.loop/config.json`.
- If `--skip-eval` is provided, skip the evaluator pass.
- If `--story <ID>` is provided, only work on that specific story.

### Step 1: Load State

1. Read `.loop/config.json` — get `mode`, `maxIterations`, `evalRetries`, `scopeBudgets`
2. Read `.loop/prd.json` — get the story list and their statuses
3. Check `.loop/progress.md` exists; if not, create it from `.loop/templates/progress.md.template`

Report to the user:

> **Loop Ready**
> - Mode: {mode}
> - Stories: {passed}/{total} complete
> - Max iterations: {N}
> - Eval: {on/off}
>
> Starting loop. You can interrupt me at any time to adjust course.

### Step 2: Iteration Loop

For each iteration (1 to max iterations):

#### 2a. Find Next Story

Find the highest-priority story in `prd.json` where `passes` is `false` and `blocked` is not `true`. If `--story` was specified, use that story instead.

**If no actionable story remains:**
- If all stories have `passes: true` → report success and stop
- If some stories are `blocked: true` → report which are blocked and suggest `/agent-loop:triage`
- Stop the loop

#### 2b. Report Iteration Start

Tell the user:
> **Iteration {N}/{max} — {story.id}: {story.title}**

If the story has `[REJECTED]` entries in its `notes` field, summarize the previous feedback so the user has context.

#### 2c. Assemble Generator Prompt

Read these files and concatenate them with `---` separators:
1. `.loop/prompts/generator/_base.md`
2. `.loop/prompts/generator/{mode}.md`

Then substitute these template variables in the assembled text:
- `{{MAX_FILES_TO_READ}}` → from `config.scopeBudgets.{mode}.maxFilesToRead`
- `{{MAX_LINES_TO_WRITE}}` → from `config.scopeBudgets.{mode}.maxLinesToWrite`
- `{{MAX_FILES_TO_MODIFY}}` → from `config.scopeBudgets.{mode}.maxFilesToModify`
- `{{MODE}}` → the mode
- `{{ITERATION}}` → current iteration number
- `{{MAX_ITERATIONS}}` → max iterations
- `{{LOOP_DIR}}` → path to `.loop/` directory
- `{{PROJECT_ROOT}}` → project root path
- `{{CURRENT_STORY_ID}}` → the story ID being worked on

#### 2d. Capture Pre-Generator Git State

Run `git rev-parse HEAD` and save it. This is needed for the evaluator's diff.

#### 2e. Dispatch Generator Agent

Use the **Agent tool** to launch the generator:

```
Agent(
  prompt: <assembled generator prompt>,
  description: "Generator: {story.id}",
  subagent_type: "general-purpose",
  mode: "auto"
)
```

**IMPORTANT:** Use `mode: "auto"` so the user can see tool calls but isn't prompted for every action. If the user has expressed a preference for more control, use `mode: "default"` instead.

Wait for the agent to complete. The Agent tool returns the generator's final output.

#### 2f. Check for Completion Signal

If the generator output contains `<promise>COMPLETE</promise>`, report all stories complete and stop.

#### 2g. Skip Evaluator (if configured)

If `--skip-eval` was specified or `config.skipEval` is true, skip to step 2j.

#### 2h. Assemble Evaluator Prompt

Read these files and concatenate them:
1. `.loop/prompts/evaluator/_base.md`
2. `.loop/prompts/evaluator/{mode}.md`

Substitute the same template variables as the generator, plus:
- `{{PRE_GENERATOR_SHA}}` → the git SHA captured in step 2d
- `{{CURRENT_STORY_ID}}` → the story ID

#### 2i. Dispatch Evaluator Agent

Use the **Agent tool** to launch the evaluator:

```
Agent(
  prompt: <assembled evaluator prompt>,
  description: "Evaluator: {story.id}",
  subagent_type: "general-purpose",
  mode: "auto"
)
```

Wait for completion. Parse the verdict from the output:

- Look for `<verdict>PASS</verdict>` → story passes
- Look for `<verdict>REJECT</verdict>` → story rejected; extract reason from `<rejection_reason>...</rejection_reason>`
- No verdict tag found → treat as REJECT (fail-safe)

#### 2j. Update State Based on Verdict

**On PASS (or skip-eval):**
1. Update `.loop/prd.json` — set `passes: true` for the story
2. Report to user: ✓ **{story.id} PASSED**

**On REJECT:**
1. Update `.loop/prd.json`:
   - Keep `passes: false`
   - Increment `rejections` count
   - Append `[REJECTED] {reason}` to `notes`
2. Report to user: ✗ **{story.id} REJECTED** — {reason}
3. Check if `rejections` >= `evalRetries` from config:
   - If yes: set `blocked: true` in prd.json, append `[BLOCKED]` to notes
   - Report: ⚠ **{story.id} BLOCKED** — rejected {N} times, needs human review

#### 2k. Append Progress Entry

Append to `.loop/progress.md`:

```markdown
### {story.id} — {story.title}
Date: {current date and time}
Iteration: {N}
Verdict: {PASS/REJECT/SKIP-EVAL}

---
```

#### 2l. Report Iteration Summary

Show current story counts: `{passed}/{total} stories complete`

If there are more iterations and more stories, continue to the next iteration.

### Step 3: Loop Exit

When the loop ends (all stories done, max iterations, or all remaining blocked), report:

> **Loop Complete**
> - Iterations used: {N}
> - Stories: {passed}/{total} complete, {blocked} blocked
> - {Suggest `/agent-loop:triage` if anything is blocked or incomplete}

### Error Handling

- If an Agent subagent fails or returns empty output, log a warning and continue to the next iteration. Do NOT stop the loop for a single agent failure.
- If `prd.json` cannot be parsed, stop immediately and report the error.
- If the user interrupts (denies a tool call, says "stop", etc.), gracefully end the loop and report current status.

### Key Differences from loop.sh

| Feature | loop.sh | /loop-run |
|---------|---------|-----------|
| Execution | Headless (`claude --print`) | Visible in Claude Code |
| Intervention | Kill the process | Deny tool calls, chat mid-loop |
| Permissions | `--dangerously-skip-permissions` | User-controlled |
| Context | Fresh process per agent | Fresh Agent subagent per agent |
| State updates | Shell functions | Claude Code reads/writes files directly |