# Waves Plan

> Turn a goal, spec, review, or clip-to-plan output into an executable master plan: ≤3-4h tasks with exit checks, dependency analysis, lane ownership, and a wave schedule. Gated on resolving open questions first — never plans on guesses. Use when breaking down work, writing plans/00-master.md, or converting a clip-to-plan result.

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

---


# waves-plan — task breakdown & wave scheduling

## Preamble (run first)

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

Read `${CLAUDE_PLUGIN_ROOT}/references/conventions.md` (§1, §2, §5) and the
`CLAUDE.md` + rule files of every repo the plan will touch. If there is no
workspace, run `waves-init` first.

## Input sources

- A goal/spec from the user or workspace docs.
- A `clip-to-plan` result: treat its code-traced findings as candidate tasks;
  re-verify file paths against the actual checkouts before scheduling.
- An existing plan needing the next phase.

## GATE 1 — open questions before tasks

List every decision the plan depends on that is not locked. For each: state a
**proposed default** and **who must confirm** (user now, or the coordinator via
a flagged blurb item). Ask the user's share immediately as **decision briefs**
(`${CLAUDE_PLUGIN_ROOT}/references/decision-briefs.md`) — batched, one
recommended option each, honest tradeoffs.
**Do not emit a plan whose tasks depend on an unresolved question**;
park dependent tasks behind the question in the wave schedule instead
(`after decisions` status), exactly like `Open questions (blocking Wave 1 start)`
in the master plan format.

## Task breakdown rules

- Every task ≤ `task_max_hours` (config, default 3–4h). Split anything bigger.
- Every task has: id (`<wave><letter>`, e.g. `2B`), repo (or `docs` / `—` for
  external/human), owner (agent / engineer / coordinator), **named deliverable**,
  and an **exit check stated up front** — the concrete command/URL/observation that
  proves it done on the running stack (green suites alone never qualify).
- Tasks inside one plan are sequential; parallelism happens **between** tasks of a
  wave, split by repo first, then by disjoint file ownership.
- Name shared mutable surfaces (spec files, registries, translation indexes) and
  assign one owner for the duration.
- Deploys and infra/env config edits: one task per site/service, serialised.
- Note kill criteria where a workstream might be cut ("if X fails, ship only Y").

## Wave scheduling

Group tasks into waves: **each wave = the largest set with no unresolved
dependencies or ownership conflicts.** Don't trickle; don't let an independent task
wait on a slow lane. Mark same-repo concurrency for worktrees. Record gating
conditions explicitly ("after 3D", "after coordinator signs off contract").

If agent teams are enabled (`waves-detect` prints it), size lanes for them:
~5–6 tasks per lane keeps a teammate productive and lets the lead reassign work
(see `${CLAUDE_PLUGIN_ROOT}/references/agent-teams.md`); the backend itself is
chosen per wave at execution time by `waves-run`.

## Output

Write/update `plans/00-master.md` following
`${CLAUDE_PLUGIN_ROOT}/templates/00-master.md.tmpl` (7-column wave table, locked
decisions, open questions with defaults+confirmers, conventions block). Follow-on
plans get decimal numbers (`05.1`); numbers are never reused. Then summarize for the
user: wave count, parallelism per wave, open questions blocking Wave 1, and offer
`/waves-run` to execute.