Dev Loop

---
name: "Team: Dev Loop"
description: Spawn an implementer + verifier (+ optional planner) team that iterates on a scoped change until a deterministic check passes. Lead stays light.
category: Agent Teams
tags: [agent-teams, implementation, build-loop]
---

Implementation team with a deterministic verifier in the loop. Use when you
have a scoped change that can be proven done by *running a tool* (tests,
linter, typecheck, schema check, build). Not for review or design work — see
`team:debate` and `team:battle-test` for those.

**Input** (`$ARGUMENTS`): a free-form scope description. The lead reads it,
inspects the relevant files, and decides whether a planner round is needed.

## When this fits

- Refactor with tests as the contract.
- New feature where the slice is small and the check is automated.
- Migration where the verifier is "old and new produce the same output".
- Anything where success collapses to a single shell command exiting 0.

If the verifier is "looks good to me" — wrong skill.

The team can also start *before* the slice is fully defined. Spawn `planner`
first, ask "what's the next sensible slice here?", then derive impl tasks
from the planner's answer. impl and runner sitting idle while planner reads
the codebase is fine — they cost ~nothing while idle.

## Lead does not gate-keep teammates

When the user gives a clear instruction for a specific teammate — "send
this command to the planner", "have impl do X", "ask runner to re-run" —
forward it. Do not second-guess whether the activity "fits the loop
shape". The teammates have their own judgment. If the planner is asked to
do orientation work or run a catchup command, that *is* planner work, not
a violation of the skill.

Refuse only when the instruction would break a hard rule (lead writes
code, runner edits files, scope wall crossed, etc.). Everything else
routes through.

## Pre-flight (lead)

1. Confirm `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` is set. If not, refuse.
2. Read the files in scope end-to-end. The lead must understand the domain
   well enough to mediate when something goes off the rails.
3. Identify the verifier command. It must exit 0 on success, non-0 on
   failure. Smoke-test it once before spawning the team.
4. Decide: is the slice clear enough to brief `impl` directly, or do you
   want a `planner` round first? Only spawn the planner when *you* can't
   confidently shape the work yourself — opus tokens are the expensive ones.

## Roles

| Name | `subagent_type` | `model` | Tools | Job |
|------|-----------------|---------|-------|-----|
| `planner` (optional) | `Plan` | opus | Read, Grep, Glob, WebFetch | Single-shot: propose the slice, name what to test/build, hand back. |
| `impl` | `implementer` | sonnet | Read, Edit, Write, Bash | Claim impl tasks in order, write code, ping `runner` when ready. |
| `runner` | `verifier` | haiku | Read, Bash | Run the verifier command, report PASS or FAIL excerpt. Never edits. |

Spawn via the `Agent` tool with `team_name`, `name`, `subagent_type`, and
`model`. The subagent types above are pre-installed; check the Agent tool's
own list before assuming a type exists.

## Mechanics — what does the work

Use the team task list (`TaskCreate` / `TaskUpdate` / `TaskList`), not your
prose, to choreograph. The point is that `addBlockedBy` makes the runner
self-trigger when impl finishes, with no polling from the lead.

1. `TeamCreate` with a short `team_name`.
2. Create one task per logical impl step. Last task: "Run verifier and
   report". Use `addBlockedBy` to chain.
3. Spawn `impl` and `runner` (and `planner` if needed). Each spawn prompt
   should reference: their task IDs, the communication protocol below, the
   file boundaries, and "do not touch X".
4. After spawn, the lead **stops** until a teammate sends a real message.
   Idle notifications are not events to react to.

## Communication protocol (bake into spawn prompts)

- impl finishes its tasks, then `SendMessage` runner: `"Phase N ready. Run task #X."`
- runner runs the verifier:
  - PASS → `SendMessage impl "PASS — <one line>. Output tail: ..."`, mark
    runner's task completed, go idle.
  - FAIL → `SendMessage impl` with exit code, failing test names, last ~40
    lines. Keep status `in_progress`. Go idle.
- impl on FAIL: fix, then `SendMessage runner "Fixed: <one-liner>. Re-run task #X."`
- Loop until PASS.

The lead is not in this loop. If the loop stops moving (both idle, no
PASS), then the lead investigates.

### Mandatory checkpoint rule for impl (bake into impl spawn prompt)

Long phases hit per-turn budgets. When that happens, impl finishes its
turn gracefully — which from the harness's view is "idle" — but it has
not handed off to runner. The watchdog can't tell that apart from a dead
agent. Defend against this in the impl prompt:

> After every 2 sub-tasks completed: `SendMessage` lead with one line
> "P<n> progress: <ids> done, on <next>". Never end a turn idle without
> first sending a message. If you have nothing else to say, send "Still
> working on X.Y, will checkpoint after next sub-task." Silence is the
> only failure signal the lead has — silent ≈ replaced.

Also bake routing into the impl prompt explicitly:

> When you write "Run task #N" or "Phase N ready", the recipient is
> `runner`, NOT `team-lead`. Lead is not the verifier — runner is.

Without these two clauses, expect repeat failures: silent stalls and
work-product messages mis-routed to lead.

## Worker discipline (bake into spawn prompts)

Three rules every spawn prompt must include verbatim. Workers ignore vague
guidance, so the exact wording matters.

**1. Canonical task IDs only.** Never call `TaskCreate`. The lead creates
tasks once and hands you the IDs in the spawn brief. You only call
`TaskUpdate(taskId=<id>, status=in_progress|completed)`. Creating a new
task with the same name as an existing one breaks the dependency chain
(the verifier `blockedBy` the original ID never unblocks) and forces lead
cleanup. Past-run sy