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 or plans:

   • docs/superpowers/specs/*.md
   • docs/superpowers/plans/*.md
   • docs/specs/*.md
   • docs/plans/*.md
   • SPEC.md, PRD.md, DESIGN.md, PLAN.md at project root
   • Any markdown file that looks like a feature spec or implementation plan

   If found: "I found a spec at {path}. Using it to generate stories."

   If NOT found, stop and tell the user:

   No spec or plan found. Agent Loop decomposes existing plans into stories — it doesn't create plans from scratch.

   Create a plan first, then re-run /agent-loop:run:

   • Describe your idea to Claude and ask it to write a spec
   • Use /plan if available
   • Or create a markdown file at docs/specs/ or SPEC.md

   The plan should describe what to build, the tech stack, and key requirements.

   STOP here. Do NOT ask the user to describe the project in a few sentences. Do NOT proceed without a spec file.

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:

Loop launched. Watch it live:

! tmux attach -t agent-loop

(Type the above — it opens the session right here in your terminal.)

• Detach (return to Claude Code): Ctrl+B then D
• Stop the loop: Ctrl+C
• Ask me "status" anytime and I'll check progress.

---

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.