---
name: run
description: Execute the generator-evaluator loop interactively inside Claude Code. Dispatches subagents with full visibility. 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. You see every tool call and can 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 pass
/agent-loop:run --story US-003     # Run only a specific story
```

## Instructions

Follow this orchestration sequence exactly.

### Step 0: Validate Prerequisites

1. Check `.loop/config.json` exists. If not: tell user to run `/agent-loop:init` and stop.
2. Check `.loop/prd.json` exists. If not: tell user to run `/agent-loop:plan` and stop.
3. **Validate prd.json schema.** Read the file and verify:
   - Has a `userStories` array (NOT `sprints`, `stories`, or `tasks`)
   - Each story has: `id`, `title`, `passes`, `priority`
   - If validation fails, show the error and stop. Do NOT attempt to fix it automatically.
4. Check prompts exist. Look for `.loop/prompts/generator/_base.md` in these locations (first match wins):
   - `.loop/prompts/` (local project copy)
   - `${CLAUDE_PLUGIN_ROOT}/prompts/` (plugin install)
   - `~/.claude/plugins/cache/agent-loop/agent-loop/*/prompts/` (plugin cache)

   Save the resolved prompt base path for later use. If no prompts found, tell user to run `/agent-loop:init` and stop.

### Step 1: Parse Arguments and Load State

- Parse arguments: number → max iterations, `--skip-eval`, `--story <ID>`
- Read `.loop/config.json` for defaults
- Read `.loop/prd.json` for story list

Report:

> **Loop Ready**
> - Mode: {mode}
> - Stories: {passed}/{total} complete
> - Max iterations: {N}
> - Eval: {on/off}
>
> Starting. Interrupt me at any time.

### Step 2: Iteration Loop

For each iteration (1 to max iterations):

#### 2a. Find Next Story

Find the story with the lowest `priority` number where `passes` is `false` and `blocked` is not `true`. If `--story` was specified, use that story.

**If no actionable story remains:**
- All `passes: true` → report success and stop
- Some `blocked: true` → report which and suggest `/agent-loop:triage`
- Stop the loop

#### 2b. Report Iteration Start

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

If the story has `[REJECTED]` in its `notes`, summarize the feedback.

#### 2c. Assemble Generator Prompt

Read and concatenate with `---` separator:
1. `{prompt_base_path}/generator/_base.md`
2. `{prompt_base_path}/generator/{mode}.md`

Substitute template variables:
- `{{MAX_FILES_TO_READ}}` → from config scopeBudgets
- `{{MAX_LINES_TO_WRITE}}` → from config scopeBudgets
- `{{MAX_FILES_TO_MODIFY}}` → from config scopeBudgets
- `{{MODE}}` → mode from config
- `{{ITERATION}}` → current iteration
- `{{MAX_ITERATIONS}}` → max iterations
- `{{LOOP_DIR}}` → absolute path to `.loop/`
- `{{PROJECT_ROOT}}` → project root absolute path
- `{{CURRENT_STORY_ID}}` → story ID

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

Run `git rev-parse HEAD` and save the SHA.

#### 2e. Dispatch Generator Agent

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

Wait for completion.

#### 2f. Check for Completion Signal

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

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

If `--skip-eval` or `config.skipEval` is true, skip to 2j and treat as PASS.

#### 2h. Assemble Evaluator Prompt

Read and concatenate:
1. `{prompt_base_path}/evaluator/_base.md`
2. `{prompt_base_path}/evaluator/{mode}.md`

Substitute same variables plus:
- `{{PRE_GENERATOR_SHA}}` → SHA from step 2d
- `{{CURRENT_STORY_ID}}` → story ID

#### 2i. Dispatch Evaluator Agent

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

Parse the verdict:
- `<verdict>PASS</verdict>` → PASS
- `<verdict>REJECT</verdict>` → REJECT, extract `<rejection_reason>...</rejection_reason>`
- No verdict tag → REJECT (fail-safe)

#### 2j. Update State

**On PASS:**
1. Read `.loop/prd.json`, set `passes: true` for the story, write it back
2. Report: **{story.id} PASSED**

**On REJECT:**
1. Read `.loop/prd.json`, increment `rejections`, append `[REJECTED] {reason}` to `notes`, write back
2. Report: **{story.id} REJECTED** — {reason}
3. If `rejections >= evalRetries`: set `blocked: true`, append `[BLOCKED]` to notes
   - Report: **{story.id} BLOCKED** — rejected {N} times, needs human review

#### 2k. Append Progress

Append to `.loop/progress.md`:

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

---
```

#### 2l. Report and Continue

Show: `{passed}/{total} stories complete`

Continue to next iteration.

### Step 3: Loop Exit

> **Loop Complete**
> - Iterations used: {N}
> - Stories: {passed}/{total} complete, {blocked} blocked

If incomplete, suggest `/agent-loop:triage`.

### Error Handling

- Agent fails or empty output → warn and continue to next iteration
- prd.json unparseable → stop immediately
- User says "stop" → end loop, report current status