paseo/skills/loop/SKILL.md

---
name: loop
description: Run a task in a worker→judge loop until acceptance criteria are met. Use when the user says "loop", "loop this", "keep trying until", or wants iterative autonomous execution.
user-invocable: true
---

# Loop Skill

You are setting up an autonomous worker→judge loop. A worker agent implements the plan, then a judge agent independently verifies the plan was implemented to the letter.

**User's arguments:** $ARGUMENTS

---

## Prerequisites

Load the **Paseo skill** first — it contains the CLI reference for all agent commands.

## What Is a Loop

A loop is two roles — **worker** and **judge** — running in alternation:

1. **Worker** receives the plan and implements it (fresh agent each iteration)
2. **Judge** receives the same plan and independently verifies it was implemented correctly, emitting a structured verdict: `{ criteria_met: boolean, reason: string }`
3. If `criteria_met` is false, a new worker is launched with the latest judge failure reason (latest only, not full history)
4. Loop exits when the judge says `criteria_met: true` or max iterations are reached

The judge verifies the **entire plan** — every step, every file change, every acceptance criterion. It does NOT suggest fixes or provide guidance. It only reports facts.

## Live Steering

Each loop run persists state in:

```text
~/.paseo/loops/<loop-id>/
  plan.md
  last_reason.md
  history.log
```

Behavior:
- `plan.md` is read immediately before launching each worker and each judge.
- `last_reason.md` stores only the latest judge failure reason (not accumulated history).
- `history.log` appends per-iteration operational records.

Edits to `plan.md` are picked up on the next worker/judge launch without restarting the loop.

## Parsing Arguments

Parse `$ARGUMENTS` to determine:

1. **Plan** — the full implementation plan (context, steps, acceptance criteria, constraints — all in one document)
2. **Worker model** — who does the work (default: Codex `gpt-5.4`)
3. **Judge model** — who verifies (default: Claude `sonnet`)
4. **Name** — a short name for tracking iterations
5. **Max iterations** — safety cap (default: 10)
6. **Worktree** — whether to run in an isolated git worktree

### Examples

```
/loop
→ Agent derives plan from conversation context

/loop the provider list bug
→ Plan: full context about the bug, steps to fix, acceptance criteria
   Name: provider-list-fix

/loop until tests pass
→ Plan: make the failing tests pass, acceptance criteria: all tests pass
   Name: fix-tests

/loop in a worktree
→ Same as above but all agents run in a shared worktree
```

## Using the Script

The loop is implemented as a bash script at `~/.agents/skills/loop/bin/loop.sh`.

```bash
~/.agents/skills/loop/bin/loop.sh \
  --plan "The full implementation plan" \
  --name "short-name" \
  --max-iterations 10 \
  --worker-provider codex \
  --worker-model gpt-5.4 \
  --judge-provider claude \
  --judge-model sonnet
```

### Arguments

| Flag | Required | Default | Description |
|---|---|---|---|
| `--plan` | Yes* | — | Full implementation plan (given to both worker and judge) |
| `--plan-file` | Yes* | — | Read the plan from a file |
| `--name` | Yes | — | Name prefix for agents (`name-work-N`, `name-verify-N`) |
| `--max-iterations` | No | 10 | Safety cap on iterations |
| `--worktree` | No | — | Worktree name. Created on first use, reused for all subsequent agents. |
| `--worker-provider` | No | `codex` | `codex` or `claude` |
| `--worker-model` | No | provider default | Model for worker |
| `--judge-provider` | No | `claude` | `codex` or `claude` |
| `--judge-model` | No | provider default | Model for judge |
| `--thinking` | No | `medium` | Thinking level for worker |

\* Provide exactly one of `--plan` or `--plan-file`.

### How the Plan Is Used

The same plan is given to both the worker and the judge, wrapped in XML tags:

**Worker receives:**
```
Implement the following plan exactly as specified.

<plan>
[your plan here]
</plan>
```

If a previous iteration failed, the worker also receives:
```
<previous-verification-failure>
[judge's failure reason from last iteration]
</previous-verification-failure>
```

**Judge receives:**
```
Verify that every step of the plan has been implemented to the letter.

<plan>
[your plan here]
</plan>
```

### Agent Naming

Agents are named `{name}-work-{N}` and `{name}-verify-{N}` so the caller can track iterations:

```
fix-bug-work-1     # First worker attempt
fix-bug-verify-1   # First judge check
fix-bug-work-2     # Second worker attempt (with failure context)
fix-bug-verify-2   # Second judge check
```

### Worktree Support

When `--worktree` is passed, all workers and judges run in the same git worktree. The worktree is created on the first agent launch and reused for all subsequent agents (the `--worktree` flag on `paseo run` is idempotent — if the worktree exists, the agent runs in it without creating a new one).

No `--base` is needed in the loop script — it automatically uses the current branch as the base.

```bash
~/.agents/skills/loop/bin/loop.sh \
  --plan-file /tmp/my-plan.md \
  --name "feature-x" \
  --worktree "feature-x"
```

## Your Job

1. **Understand the task** from the conversation context and `$ARGUMENTS`
2. **Write the plan** — comprehensive, self-contained (the worker has zero context). The plan should include:
   - Task description and context
   - Relevant files and what they do
   - Implementation steps (ordered, concrete)
   - Acceptance criteria (factual, verifiable)
   - Constraints (what NOT to do)
3. **Choose models** — default: Codex worker + Claude sonnet judge
4. **Choose a name** — short, descriptive
5. **Run the script** — call `loop.sh` with all the arguments

### Steering Guidance

- Prefer tightening or clarifying the plan when important requirements are missing.
- Rework acceptance criteria when they are causing dead loops or are not independently verifiable.
- Avoid weakening user-defined criteria unless the user explicitly asks for that change.
- Keep the plan self-contained so the loop can succeed without relying on iterative reasoning context.

### Writing a Good Plan

The plan is the single source of truth for both the worker and the judge. It must be:

1. **Self-contained** — The worker starts with zero context. Everything needed is in the plan.
2. **Specific** — Name files, functions, types. "Update the handler" is useless. "In `src/handlers/auth.ts`, modify the `handleLogin` function to..." is useful.
3. **Ordered** — Steps should be in implementation order.
4. **Verifiable** — Every step and criterion must be independently checkable by the judge.

**Good plan elements:**
- "File `src/utils.ts` exports a function named `formatDate`"
- "Running `npm test` exits with code 0"
- "The component at `src/ProviderList.tsx` renders a list of providers from the API response"
- "Typecheck passes (`npm run typecheck`)"
- "`npm run typecheck` passes"

**Bad plan elements:**
- "The code is clean" (subjective)
- "The implementation is correct" (vague)
- "It works" (unverifiable)

### Skill Stacking

You can instruct the worker to use other skills in the plan:

```bash
~/.agents/skills/loop/bin/loop.sh \
  --plan "Use the /committee skill to plan and then fix the provider list bug. The bug is..." \
  --name "provider-fix"
```

### Composing with Handoff

A handoff can launch a loop in a worktree:

```
/handoff a loop in a worktree
```

The handoff skill writes a prompt telling the new agent to use `/loop`, and the loop runs inside the worktree.