# Waves Run

> Executes a master plan wave-by-wave: fans the largest unblocked task set out across parallel workers — an agent team (shared task list, teammate messaging) when enabled and the wave benefits, subagents otherwise — with worktree isolation and explicit file ownership, then merges, verifies live, updates the plan, and emits a coordinator blurb at the wave boundary. Use when running a plan, launching the next wave, orchestrating parallel agents, or spawning teammates for plan execution.

- Skill: `asunalabs/waves-run` (Agent Skill)
- Install (CLI): `npx skillmds@latest add asunalabs/waves-run`
- Raw SKILL.md: https://api.skillmd.com/api/skills/asunalabs/waves-run/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: asunalabs (https://skillmd.com/u/asunalabs)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/asunalabs/waves-run

---


# waves-run — wave-based parallel execution

## Preamble (run first)

```bash
"${CLAUDE_PLUGIN_ROOT}/scripts/waves-detect"
```

Read `plans/00-master.md` (the wave table + open questions + conventions), and
`${CLAUDE_PLUGIN_ROOT}/references/conventions.md` §2–§5. No master plan → run
`waves-plan` first. Unresolved blocking questions → stop and present them as
decision briefs (`${CLAUDE_PLUGIN_ROOT}/references/decision-briefs.md`); never
start a wave on guesses.

## Step 1 — select the wave

The largest set of tasks whose dependencies and gating conditions are met and
whose footprints don't conflict. Repo-disjoint tasks always parallel; same-repo
tasks parallel only via worktrees with disjoint file ownership.

## Step 2 — choose the execution backend

`waves-detect` prints `AGENT_TEAMS: enabled|disabled` and the
`execution_backend` config (`auto` | `teams` | `subagents`).

- **Teams** (only when enabled): lanes that benefit from cross-talk — parallel
  research/review with distinct lenses, competing-hypothesis debugging,
  cross-layer features, or multiple queued tasks per lane (teammates self-claim
  from the shared task list).
- **Subagents**: focused report-back lanes, small waves, sequential-ish work.
- `auto` = decide per wave; when it's a real toss-up, or spawning a team for
  the first time in a session, present it as a decision brief (backend, team
  size, model). Teams disabled but clearly beneficial → tell the user the env
  var (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`) and fall back to subagents.

Full mechanics, sizing, spawn-prompt template, troubleshooting:
`${CLAUDE_PLUGIN_ROOT}/references/agent-teams.md`.

## Step 3 — prepare isolation

For same-repo concurrency, create worktrees **before** spawning anyone
(`git worktree add ../<repo>-wt-<topic> -b feature/<topic> origin/<base>`;
branch base = PR target). Never delete primary checkouts.

## Step 4 — launch

**Both backends — every worker brief contains:** its task row(s) (deliverable +
exit check); the explicit owns / must-not-touch file list naming the other
workers' territory; the repo's `CLAUDE.md` + relevant `.claude/rules/*.md`
paths ("read before touching code"); worktree path; scratch file assignment
(`plans/notes/<plan#>-<topic>.md`); and the standing rules: no attribution
trailers, no `git push` without approval, heavy verification commands run once
by the committing agent only.

- **Subagent backend**: launch all agents of the wave at once (single message,
  multiple Agent calls). Model policy from config: `subagent_model_default` by
  default, `subagent_model_hard` only for genuinely hard tasks.
- **Team backend**: create one shared-list task per wave row with dependencies
  mirroring the table's gating; spawn 3–5 teammates named after their lanes;
  require plan approval for risky lanes (schema, deletions, deploy config,
  security). **The lead orchestrates and does not implement.**

Don't hold independent work back because another lane is slow.

## Step 5 — while the wave runs

- Serialised surfaces stay serialised: one worker per site/service's infra/env
  config, one deploy at a time per site.
- Early finisher unblocks follow-on work with no conflict → launch it; the
  wave boundary is for merge+verify, not a reason to idle.
- Team backend: nudge stalled teammates, fix lagging task statuses, and stop
  the lead from implementing tasks itself (see agent-teams.md troubleshooting).

## Step 6 — wave boundary ritual (all of it, every wave)

Copy this checklist and check items off as you complete them:

```
Wave <N> boundary:
- [ ] Merge worktree branches (conventions §4: -s ours BANNED; diff HEAD^1 AND HEAD^2; investigate unexpected deletions)
- [ ] Re-run each touched repo's suite (heavy gates once, by the committing agent)
- [ ] Verify live per task: real browser for UI (clean console), curls + logs for backend, out-of-browser checks for destructive effects
- [ ] Record evidence in each status cell: sha, test counts, verification method, caveats
- [ ] Wave closure note in Open items / parking lot; remove merged worktrees
- [ ] Blurb via waves-status (decisions needed flagged as briefs)
- [ ] Select and launch the next unblocked wave
```

Green suites alone never count as verified.

## Failure handling

A failed task doesn't block the wave's independent lanes. Record the failure
with evidence in the plan, park dependent tasks (`after <task>`), and either
relaunch with a corrected brief (or a replacement teammate) or surface to the
user as a decision brief if the failure implies a scope/design question.
Pushes that don't survive at tip are incidents — post-push survival check per
conventions §4.