asunalabs waves-run — wave-based parallel execution
Preamble (run first)
"${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_defaultby default,subagent_model_hardonly 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.