---
name: run
description: "Agent Loop — single entry point. Scaffolds .loop/ if missing, generates stories if no prd.json, then launches autonomous execution in tmux."
---

# /run — Agent Loop

Single entry point for the agent loop. Handles setup and planning interactively, then launches autonomous execution in a tmux session.

## Usage

```
/agent-loop:run                    # Full flow: setup → stories → launch
/agent-loop:run --skip-eval        # Skip evaluator pass
```

## Instructions

Follow this sequence. Each phase checks what exists and skips if already done.

---

## Phase 1: Scaffold (if needed)

Check if `.loop/config.json` exists.

**If it does NOT exist**, run the setup script:

Ask the user: **Mode?** (a) Implement (b) Explore (c) Fix — default is Implement.

Then run:

```bash
bash "$(ls -d ~/.claude/plugins/cache/agent-loop/agent-loop/*/setup.sh 2>/dev/null | head -1)" <mode>
```

Show the output. If setup fails, stop.

**If it already exists**, skip to Phase 2.

---

## Phase 2: Generate Stories (if needed)

Check if `.loop/prd.json` exists.

**If it does NOT exist**, generate it:

1. Search for existing specs:
   - `docs/superpowers/specs/*.md`
   - `docs/specs/*.md`
   - `SPEC.md`, `PRD.md`, `DESIGN.md` at project root

   If found: "I found a spec at `{path}`. Using it to generate stories."
   If not found: ask "What do you want to build? 1-3 sentences."

2. Read the project root and tech stack info.

3. Dispatch the **agent-loop:planner** agent:

```
Agent(
  subagent_type: "agent-loop:planner",
  prompt: "Generate prd.json and sprint contracts.\n\nMode: {mode}\nProject root: {path}\n\nSpec:\n{spec content}\n\nTech stack: {detected stack}",
  description: "Planning: generate stories"
)
```

4. After the planner finishes, read `.loop/prd.json` and present:

> **Stories generated — Review before running**
>
> 1. US-001: {title}
> 2. US-002: {title}
> ...
>
> **Review:**
> - `.loop/prd.json` — stories and acceptance criteria
> - `.loop/contracts/` — done conditions per story
>
> Let me know if you want changes, or say **go** to start the loop.

5. **STOP and wait for the user.** Do NOT start the loop automatically. The user must say "go", "start", "run", "looks good", or similar before proceeding to Phase 3.

**If `prd.json` already exists**, skip to Phase 3.

---

## Phase 3: Validate and Launch

1. Read `.loop/prd.json` and verify:
   - Has a `userStories` array (NOT `sprints`, `stories`, or `tasks`)
   - Each story has: `id`, `title`, `passes`, `priority`
   - If invalid, show the error and stop.

2. Read `.loop/config.json` for `mode`, `maxIterations`.

3. Verify `.loop/loop.sh` exists and is executable.

4. Parse arguments for any flags to pass through (e.g., `--skip-eval`).

5. Build the loop.sh command with any flags:

```bash
LOOP_CMD=".loop/loop.sh"
# Add --skip-eval if requested
# Add --max N if specified
```

6. Launch in tmux:

```bash
tmux new-session -d -s agent-loop -c <project_root> "$LOOP_CMD"
```

7. Report to the user:

> **Loop launched in tmux session `agent-loop`**
> - Stories: {total} to complete
> - Mode: {mode}
>
> **Monitor:**
> - Watch live: `tmux attach -t agent-loop`
> - Check progress: read `.loop/progress.md`
> - Check status: read `.loop/prd.json`
> - Stop the loop: `tmux kill-session -t agent-loop`
>
> I can also check on progress for you — just ask "how's it going?"

---

## Monitoring

If the user asks about progress (e.g., "status", "how's it going", "check progress"):

1. Read `.loop/prd.json` — count passed/failed/blocked stories
2. Read `.loop/progress.md` — show the latest session log entries
3. Capture recent tmux output:

```bash
tmux capture-pane -t agent-loop -p | tail -30
```

4. Report:

> **Loop Status**
> - Stories: {passed}/{total} complete, {blocked} blocked
> - Current: {last story from progress.md}
> - tmux session: {running/stopped}

---

## When Loop Completes

The tmux session exits when `loop.sh` finishes. If the user asks for a summary:

1. Read `.loop/prd.json` for final story statuses
2. Read `.loop/progress.md` for the full session log
3. Check git log for commits made during the run

Report the final status and suggest `/agent-loop:triage` if any stories are blocked.