---
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. Kill any existing agent-loop tmux session, then launch detached:

```bash
tmux kill-session -t agent-loop 2>/dev/null; tmux new-session -d -s agent-loop -c <project_root> "$LOOP_CMD"
```

7. Open the tmux session for the user. Try platform-specific methods:

**macOS** (check `uname` = Darwin):
```bash
osascript -e 'tell application "Terminal" to do script "tmux attach -t agent-loop"'
```

**Linux/other** — cannot open a terminal programmatically. Tell the user:
```
! tmux attach -t agent-loop
```

8. Tell the user:

> **Loop launched.**
> - **Detach** (keep loop running): `Ctrl+B` then `D`
> - **Stop the loop**: `Ctrl+C` in the tmux window
> - **Reattach later**: `tmux attach -t agent-loop`
> - Ask me "status" anytime and I'll check progress for you.

---

## 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.