# Wave Planner

> Plan and execute large multi-step, multi-stack changes with contract-first waves, parallel worker ownership, user approval gates, ordered integration, and final verification/docs updates. Use only when the task spans multiple areas (for example frontend, backend, tests, errors, docs) or has dependency-heavy sequencing.

- Skill: `asm3r96/wave-planner` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add asm3r96/wave-planner`
- Raw SKILL.md: https://api.skillmd.com/api/skills/asm3r96/wave-planner/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: asm3r96 (https://skillmd.com/u/asm3r96)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/asm3r96/wave-planner

---


# Wave Planner

Create and run a Wave-Driven Development plan for large, cross-stack tasks.

## Objective

Produce:
- Vision and scope boundaries
- Decision Log
- Wave 0 contracts
- Wave 1..N parallel implementation waves
- Integration wave
- Final verification wave
- Documentation update step
- Ready-to-send worker prompts and execution checklist

## Workflow

1. Decide whether to use this skill:
- Use only if work is large, multi-step, and touches multiple parts/stacks.
- If not large enough, do not use this skill.
2. Ask for Gate 1 user approval before planning:
- Send a short reason: "I recommend Wave method because <short reason>. Do you agree?"
- Stop until user accepts or declines.
3. If accepted, draft the plan:
- Clarify done criteria and out-of-scope.
- Build Decision Log (naming, API shape, error model, logging, tests, style constraints).
- Define Wave 0 contracts first (types/interfaces/schemas, boundaries, API shapes, constants, flags/migrations).
- Because worker execution uses `gpt-5.4-mini`, make the plan unusually clear and concrete so smaller agents can execute reliably without guessing.
- Save the plan by default inside `.planning/`; create the folder if it does not exist.
- Use a clear feature-based filename for the plan.
4. Choose wave and agent count with balancing rules:
- Prefer 1-2 waves unless more waves are clearly needed to avoid conflicts or sequencing problems.
- Use the minimum number of waves that still avoids conflicts.
- Group independent tasks into the same wave.
- Move dependency-bound tasks to later waves.
- Keep each worker task medium-sized (not tiny and not overloaded).
- Ensure each worker has explicit file/module ownership.
5. Produce a one-line execution preview before full detail:
- One line per wave.
- One line per worker with task summary.
6. Produce the full plan with complete shared context:
- Include full vision and all waves so each worker sees global intent.
- Include worker-specific goals, files, constraints, and verification.
- Include explicit wave order for execution (Wave 0, then Wave 1..N, then Integration, then Final Verification, then Docs).
- Make each worker prompt highly specific: exact ownership, exact files/modules, exact handoff format, exact verification steps, and any important non-goals.
- By default, save the full plan to the plan file and do not dump the full plan in chat unless the user explicitly asks.
7. Ask for Gate 2 user approval before execution:
- "Plan is ready. Execute now?"
- Stop until user accepts or declines.
8. If accepted, execute with Codex swarm/subagents:
- Spawn one named Codex subagent per worker in the current wave.
- Use `gpt-5.4-mini` for those worker subagents.
- The main Codex agent controls the subagents, assigns ownership, monitors progress, validates handoffs, and decides when a wave is complete.
- Run subagents in parallel inside a wave, but execute waves sequentially.
- Wait for all subagents in the wave to finish and validate handoffs before starting the next wave.
- Close finished subagents after completion.
9. After all waves:
- Main agent reviews merged result and runs verification tests.
- Main agent updates existing docs if needed, or adds new docs for new features.
- Follow existing documentation format and conventions.
- Main agent updates the original plan file status to `Completed` or `Blocked`.
- Main agent adds final verification notes to the original plan file.
- If the project has a status-tracking document or progress board, update it during closeout so completed work and remaining open work stay accurate.

## Global Rules

- Gating rule: planning and execution require explicit user approvals (Gate 1 and Gate 2).
- Ownership rule: workers edit only assigned files.
- Dependency rule: if outside scope is needed, return a Dependency Note instead of editing.
- Consistency rule: follow existing repo patterns; do not invent new architecture unless requested.
- Verifiability rule: each worker includes at least one concrete verification method.
- Ordering rule: wave order is strict; do not start next wave early.
- Subagent rule: one named Codex subagent per worker; close finished subagents.
- Planning quality rule: because workers default to `gpt-5.4-mini`, the main plan must be detailed, concrete, and unambiguous enough that workers do not need to invent missing structure.
- Plan-location rule: save plans in `.planning/` by default and create the folder if needed.
- Worker-context rule: every worker must read the original plan file first for the full picture before editing.
- Handoff rule: every worker must append its handoff into the original plan file, not only reply in-session.
- Deduplication rule: if a worker reports more than once, keep one clean final handoff entry in the plan file.
- Commit-scope rule: before committing, inspect git status and commit only the files that belong to the planned task.
- Verification-scope rule: run targeted checks first, then broader checks; report unrelated pre-existing failures clearly as outside the feature scope.
- Status-tracking rule: if the project uses a status-tracking doc, board, or changelog-in-progress, update it as part of closeout so project status reflects what was completed and what remains open.
- Docs rule: docs update is mandatory in final step (update existing docs or add new).

## Model Routing Configuration

Use Codex built-in subagents for execution.

Rules:
- Default all worker/subagent execution to `gpt-5.4-mini`.
- The main Codex agent remains responsible for planning, orchestration, integration, and final verification.
- Prefer a very strong plan, strict ownership, and clear contracts over increasing model size.
- Assume smaller workers perform best when instructions are explicit, scoped, and testable; plan accordingly.
- If a task is unusually complex and `gpt-5.4-mini` is clearly insufficient, pause and ask the user before using a stronger model.
- Do not use per-task model routing by default; prefer `gpt-5.4-mini` unless the user approves an exception.

## Mandatory Worker Handoff Format

1. Summary (1-3 lines)
2. Files changed (exact list)
3. Patch/diffs (or exact edits)
4. How to test (commands + expected result)
5. Risks/TODOs/Dependency Notes
6. Main plan log entry (what to append to shared execution log)
7. Completion marker: `WAVE {WAVE_ID} / {AGENT_NAME} DONE`

## Output Contract

Always output the final plan using this section order:
- A) Vision
- B) Decision Log
- C) Contracts (Wave 0)
- D) Waves (1..N with agents)
- E) Integration + Final Verification + Docs
- F) Worker prompts
- G) Execution checklist (Codex subagents + wave order)

Use templates from `templates/` when helpful.

## Final Response Contract

After execution, keep the user-facing summary short by default and include:
- what was implemented
- where the plan file lives
- what tests/checks passed
- what is still failing, blocked, or outside scope