loop-loop/skills/run/SKILL.md

name, description

name	description
run	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 "$(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:

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:

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

7. Tell the user to attach:

Loop running in tmux. To watch it live, run:

! tmux attach -t agent-loop

• Detach (return to Claude Code): Ctrl+B then D
• Stop the loop: Ctrl+C in the tmux session
• 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:

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.