168 lines
4.4 KiB
Markdown
168 lines
4.4 KiB
Markdown
---
|
|
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.
|