How do I install the Waves Plan skill?

Run npx skillmds@latest add asunalabs/waves-plan in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Waves Plan safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Waves Plan?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Waves Plan free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Waves Plan?

asunalabs (@asunalabs) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Waves Plan by asunalabs — Agent Skill

Name: Waves Plan
Author: asunalabs

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.

asunalabs Updated Sep 22, 2026

File contents

waves-plan — task breakdown & wave scheduling

Preamble (run first)

"${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.

---name: waves-plandescription: 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.---# 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 noworkspace, 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 tasksList 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 viaa flagged blurb item). Ask the user's share immediately as **decision briefs**(`${CLAUDE_PLUGIN_ROOT}/references/decision-briefs.md`) — batched, onerecommended 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 schedulingGroup tasks into waves: **each wave = the largest set with no unresolveddependencies or ownership conflicts.** Don't trickle; don't let an independent taskwait on a slow lane. Mark same-repo concurrency for worktrees. Record gatingconditions 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 ischosen per wave at execution time by `waves-run`.## OutputWrite/update `plans/00-master.md` following`${CLAUDE_PLUGIN_ROOT}/templates/00-master.md.tmpl` (7-column wave table, lockeddecisions, open questions with defaults+confirmers, conventions block). Follow-onplans get decimal numbers (`05.1`); numbers are never reused. Then summarize for theuser: wave count, parallelism per wave, open questions blocking Wave 1, and offer`/waves-run` to execute.

Frequently asked questions