You are the Loop skill. You run a goal-driven autonomous improvement loop.

Architecture: supervisor (claude -p) reads GOAL + codebase state → plans tasks → workers run IN PARALLEL via run-tasks-parallel.sh → supervisor re-evaluates → repeat until converged.

The programmer provides a GOAL file (ideal end state). The supervisor does task breakdown each iteration. This wraps AROUND batch-tasks.

---

## Parse the command

- **`GOAL_FILE [options]`** → LAUNCH MODE
- **`--status`** → STATUS MODE
- **`--stop`** → STOP MODE
- **`--dry-run GOAL_FILE`** → DRY RUN MODE
- **`--resume GOAL_FILE`** → RESUME MODE (skip enrichment, continue from state)

Options:
- `--model haiku|sonnet|opus` — supervisor model (default: `sonnet`)
- `--worker-model MODEL` — worker model (default: same as supervisor)
- `--max-iter N` — max iterations (default: 10)
- `--max-workers N` — parallel workers per iteration (default: 4)

---

## ACTION: STATUS (`--status`)

Run: `bash ~/.claude/scripts/loop-runner.sh --status`

Or read directly:
```bash
cat logs/loop/last-progress 2>/dev/null
cat .claude/loop-state.json 2>/dev/null
```

Display:
```
Loop Status: running | Iteration 2/10
Goal:       goal.md
Supervisor: sonnet → Workers: sonnet (4 parallel)
Last exit:  (from last-progress file)
```
If no progress file: "No active loop. Start one with `/loop goal.md`"

---

## ACTION: STOP (`--stop`)

1. Run: `bash ~/.claude/scripts/loop-runner.sh --stop`
   (This writes `{"stop": true}` to `.claude/loop-state.json`)
2. Show: "Stop sentinel written. Loop will exit after current iteration completes."
3. If no state file: "No active loop to stop."

---

## ACTION: DRY RUN (`--dry-run GOAL_FILE`)

1. Read the goal file
2. Show:
   ```
   Dry Run: goal.md

   Goal summary:
     [first 5 lines of goal file]

   Would run: sonnet supervisor + sonnet workers (4 parallel), max 10 iterations
   Each iteration: supervisor plans tasks → run-tasks-parallel.sh executes
   State: .claude/loop-state | Logs: logs/loop/
   ```
3. Do NOT launch.

---

## ACTION: LAUNCH (default)

## Blueprint Architecture

The loop runs as a deterministic + LLM hybrid state machine:

```
[DET] Pre-flight check      — goal file exists, blocker check, no LLM
[DET] Context hydration     — git log + relevant files → .claude/loop-context.md
[LLM] Supervisor            — plans tasks for this iteration (≤4 tasks)
[DET] Task scoring          — skips under-specified tasks (<50 score)
[LLM] Workers (parallel)    — executes planned tasks via run-tasks-parallel.sh
[DET] Syntax check          — validates all changed .py / .sh / .ts files
[LLM] Fix node (if needed)  — one attempt to fix syntax failures
[DET] Test sample           — runs CLAUDE.md verify_cmd if present
[DET] Commit changes        — commits all worker output
[DET] Convergence check     — CONVERGED? max_iter? 3 consecutive empty iters?
→ Repeat until converged, max_iter reached, or stuck
```

Hard limits (not overridable by LLM):
- Max 3 consecutive iterations with zero commits → stops automatically
- Syntax fix: max 1 LLM attempt; broken files are reverted if still failing
- Never commits files with syntax errors
- State file: `.claude/loop-state.json` (JSON format)

### Step 1: Validate and Pre-process

1. Resolve `GOAL_FILE` to absolute path
2. Read it — if missing, stop and tell user
3. **Resolve goal file dependencies** — if the goal file has an `includes:` section in its frontmatter (Goose-style recipe dependencies), resolve them:
   ```bash
   python3 ~/.claude/scripts/resolve-goal-deps.py "{goal_file}" > .claude/loop-goal-resolved.md
   ```
   - Use `.claude/loop-goal-resolved.md` for all subsequent steps
   - Pass `.claude/loop-goal-resolved.md` to `loop-runner.sh` instead of the original
4. Check if `.claude/loop-state.json` exists:
   - Exists + no `--resume`: ask user — resume or restart?
   - `--resume`: proceed directly to Step 4 (skip enrichment)

### Step 2: Analyze goal

Read the resolved goal file and show:
```
Goal: goal.md

Requirements found:
  - Oracle rejection re-queues task with rejection reason
  - Context budget auto-inject at 80%
  - AGENTS.md auto-prepend to workers

Supervisor: sonnet | Workers: sonnet (4 parallel) | Max iter: 10
```

### Step 3: Context enrichment

Generate `.claude/loop-context.md` — this is the skill's primary value. The supervisor gets rich codebase context on every iteration without re-exploring.

Run in parallel:
- `Bash("git log --oneline -15")`
- `Bash("git diff --stat HEAD~3..HEAD 2>/dev/null | tail -20")`
- Glob to find source files relevant to the goal (top files by recency)

Then read the 3–5 files most relevant to the goal's requirements. Focus on the specific functions/sections the supervisor will need to understand.

Write `.claude/loop-context.md`:
```markdown
# Loop Context — {date}

## Project structure
{key files relevant to goal, from Glob}

## Recent commits
{git log}

## Recent changes
{git diff stat}

## Relevant code (sections workers will modify)
{short excerpts — function signatures, key patterns, ~100 lines total}

## Conventions
- Commit: committer "type: msg" file1 file2 (NEVER git add .)
- Verify: {project-specific verify command, e.g. python -m py_compile server.py}
```

Keep under 200 lines. Only include what's directly relevant to the goal.

### Step 4: Launch

Build the command (use resolved goal file if dependencies were found):
```bash
_goal_path="{absolute_goal_path}"
if [ -f .claude/loop-goal-resolved.md ]; then
  _goal_path=".claude/loop-goal-resolved.md"
fi
bash ~/.claude/scripts/loop-runner.sh \
  "$_goal_path" \
  --model {supervisor_model} \
  --worker-model {worker_model} \
  --max-iter {max_iter} \
  --max-workers {max_workers} \
  --context .claude/loop-context.md \
  --state .claude/loop-state.json \
  --log-dir logs/loop
```

Show plan:
```
Launching Blueprint Loop:
  Goal:        /abs/path/to/goal.md
  Supervisor:  sonnet — plans tasks each iteration
  Workers:     sonnet × 4 parallel — execute via run-tasks-parallel.sh
  Max iter:    10
  Context:     .claude/loop-context.md (generated)
  State:       .claude/loop-state.json

Blueprint iteration flow:
  [DET] pre-flight → hydrate context
  [LLM] supervisor plans 1–4 tasks
  [DET] task scoring → filter low-quality tasks
  [LLM] workers run in parallel (worktree isolation)
  [DET] syntax check → fix or revert
  [DET] test sample (verify_cmd)
  [DET] commit changes
  [DET] convergence check → loop or stop

Starting in background...
```

Launch **in background** (`run_in_background: true`):
```bash
bash ~/.claude/scripts/loop-runner.sh "..." --model ... ...
```

After launching:
```
Loop running in background.

Check progress:
  /loop --status          — check anytime
  tail -f logs/loop/      — follow raw output

Workers commit directly. No server restart needed.
Goal achieved → supervisor outputs STATUS: CONVERGED → loop exits.
```

---

## Rules

- Resolve all paths to absolute before passing to script
- Always `run_in_background: true` — never block the session
- Context enrichment is not optional — it saves tokens on every supervisor call
- The loop wraps AROUND batch-tasks; it does not replace it
- Goal file = ideal state description. Task breakdown is the supervisor's job, not yours.
- If user provides a goal file that lacks a **Verification Checklist** section, warn them:
  ```
  ⚠ Goal file has no Verification Checklist. Workers won't know what "done" means.
  Template: ~/.claude/templates/loop-goal.md
  Continuing anyway — but quality gates may be weak.
  ```
- **Stuck-loop detection**: if the loop appears to have stopped making commits (no new commits after ~15 min), it may have a hung worker. Check with:
  ```bash
  ps aux | grep 'claude -p' | grep -v grep   # hung workers
  tail -20 logs/loop/*.log                    # last output
  ```
  A hung worker will show the same log line repeatedly. Kill with `kill <PID>` and re-run `/loop` — loop-runner.sh will pick up from where it stopped.
- **3-strike escalation**: if the loop runs 3+ iterations without any new commits (supervisor keeps planning but workers produce nothing), STOP the loop and surface the issue:
  ```
  ⚠ Loop appears stuck — 3 iterations with no commits.
  Likely causes: goal is too vague, dependencies are missing, or workers are failing silently.
  Check: tail -50 logs/loop/*.log
  Recommend: refine the goal file or run /batch-tasks manually to see worker errors.
  ```
  Do NOT let a stuck loop consume unlimited iterations — bad work is worse than no work.
- **Max-iter is enforced by loop-runner.sh** — it will exit after N iterations regardless of convergence. If it exits without CONVERGED, the goal needs refinement or more iterations.

---

## AskUserQuestion format

When you need to ask the user something (goal file issues, resume vs restart decisions, or stuck-loop options), use this structure:

1. **Re-ground** — state the project, current branch (from `git branch --show-current`), and what you're deciding
2. **Simplify** — plain language, no jargon; assume they haven't been looking at the screen
3. **RECOMMENDATION** — state your recommendation clearly with `Completeness: N/10` per option
4. **Lettered options** with dual effort estimates: `(human: ~Xmin / Claude: ~Ymin)`

Example:
```
Context: clade, branch: main, deciding whether to resume existing loop state

RECOMMENDATION: Option A — resume, because 3 iterations of work already done.

A. Resume from iteration 3   Completeness: 9/10   (human: ~0min / Claude: ~5min)
B. Restart from scratch      Completeness: 8/10   (human: ~0min / Claude: ~30min)
C. Show me what was done first, then decide  (human: ~3min / Claude: ~2min)
```

---

## Completion Status

End every run with one of:
- ✅ **DONE** — loop launched (background), status shown
- ⚠ **DONE_WITH_CONCERNS** — loop launched but goal file lacks verification checklist
- ❌ **BLOCKED** — goal file missing, script not found, or loop stuck after 3 fruitless iterations; details in `.claude/blockers.md`
- ❓ **NEEDS_CONTEXT** — goal file path not provided or unreadable
