plan-wave v1.2A

Immutable. This exact content never changes and is served at /api/v1/blob/7a0d57c5f886c955.

---
name: plan-wave
description: Develops an implementation plan ready for wave-orchestration to execute. Takes the user's goal or rough plan as input, mines the codebase for facts, grills the user one question at a time for the decisions, drafts the planning/ artifacts (task DAG, wave table, worker prompt template, state file), then reviews its own plan on two axes before seeking approval. Use when the user wants to turn a feature idea, master plan, or backlog into a wave-orchestration execution plan.
license: MIT
metadata:
  author: Andrew G. Brown (https://github.com/brownag)
  version: 1.2
  source_repo: aigb-skills
  source_path: skills/plan-wave/SKILL.md
---
# Plan-Wave: author the plan that wave-orchestration executes

Produces the `planning/` artifact set that the **wave-orchestration** skill consumes: `EXECUTION_PLAN_N.md` (task directed acyclic graph + wave table + per-task specs), `PROMPT_TEMPLATE_N.md` (worker prompt), and `STATE_N.md` (scaffold). The output contract -- task-spec fields, right-sizing rules, wave rules -- is defined by wave-orchestration; read that skill first and treat it as the spec this plan must conform to.

Here, `N` is the next available orchestration number. For example, orchestration plan 3 uses `EXECUTION_PLAN_3.md`, `PROMPT_TEMPLATE_3.md`, and `STATE_3.md`.

Division of labor with the user, borrowed from **grilling**: *facts* come from the codebase -- look them up, never ask. *Decisions* belong to the user -- put each one to them and wait. Nothing is executed here; this skill ends at an approved plan.

## Phase 1 -- Intake (embed the user's input)

The user's input -- a goal sentence, a master-plan document, a TODO backlog, scattered notes, links -- is the seed. Read every referenced document in full. Then restate it as a structured **Goal & Scope** block that will head EXECUTION_PLAN_N.md:

- Goal (one paragraph, in the user's own terms)
- In scope: workstreams named in the input
- Out of scope: things the input mentions but defers (make deferrals explicit -- silent scope growth is the thing waves punish worst)
- Verbatim constraints the user stated (quote them; do not paraphrase away requirements)

Everything the user gave you must land somewhere: in the Goal block, in a task spec, or in an explicit out-of-scope line. If a sentence of their input maps to none of those, that's a gap to raise in Phase 3.

## Phase 2 -- Codebase reconnaissance (facts, not questions)

Before asking the user anything, establish from the repo(s):

- Entry-point files and their sizes (`wc -l`) -- oversized files dictate the grep-anchor rule and often the parallelization boundaries
- Test infrastructure: commands, suites, how e2e servers bind (shared ports and resources decide whether suites can ever run concurrently)
- Conventions files (AGENTS.md, CONTRIBUTING, existing plan docs) and any prior TODO/state files recording what already shipped
- Architecture Decision Records: scan `docs/decisions/README.md` and active ADRs (`status: Accepted`) to discover enduring architectural constraints and conventions
- The current green baseline per suite (run them if cheap; otherwise note as a pre-wave-1 step)
- Existing code that new work should pattern-match (candidate "reference implementations" for task specs)
- For multi-repo plans: each repo's location, build/test commands, and which tasks cross the boundary

Record findings as a short recon log -- they become anchors, acceptance commands, and hazard warnings in the task specs.

## Phase 3 -- Grill the user (decisions, one at a time)

Interview per the **grilling** skill's method: one question per message, a recommended answer with each, walk the design tree resolving dependent decisions in order. Do not batch questions; do not proceed to drafting until the tree is walked. Typical decision branches for a wave plan:

1. Priority and ordering between workstreams when the DAG allows either
2. Scope calls the input left open (which panels/endpoints/platforms count?)
3. Technology choices with no codebase precedent (storage format, new deps)
4. Architectural alignment or superseding: if any scope item contradicts an active ADR in `docs/decisions/`, explicitly resolve whether the plan supersedes that ADR or complies with it
5. Parallelism appetite: max concurrent workers, worktree tolerance, whether cross-repo work may interleave
6. Worker/escalation models and budget (which small model, escalate to what)
7. Acceptance bar: which suites must be green per wave, what's deferred to manual/device testing
8. Anything from Phase 1 that mapped to no task and no deferral

Record each answer as a dated decision line -- these go in EXECUTION_PLAN_N.md so workers and future orchestrators inherit the *why*, not just the *what*. If an accepted ADR is to be superseded upon implementation, record the target ADR ID explicitly.

## Phase 4 -- Draft the artifacts

Write, in the target repo's `planning/` directory, conforming to wave-orchestration's contract:

1. **EXECUTION_PLAN_N.md** -- Goal & Scope block (Phase 1), decision log (Phase 3), wave/dependency table, hazard notes from recon, and one spec per task with the required fields: id, repo, files-in-scope, depends-on, spec prose, constraints ("do not touch"), grep anchors, acceptance + targeted test command. Apply the right-sizing rules (<=12-step micro-plan, explicit scope, anchors not whole-file reads, named reference implementations, pairwise-disjoint files within a wave).
2. **PROMPT_TEMPLATE_N.md** -- instantiate wave-orchestration's worker skeleton with this repo's conventions files, test commands, and gate messages. Include pointer to [[git-workflow-standards]](../../git-workflow-standards/SKILL.md) for commit discipline (conventional format, one sentence, no phase/wave numbers).
3. **STATE_N.md** -- baseline checklist (from recon), wave board with every task `pending`, empty task-reports section.

## Phase 5 -- Review the plan (code-review-2axis, applied to a plan)

Before showing the user, review the draft along two axes, in the spirit of the **code-review-2axis** skill -- as two independent passes (parallel sub-agents when available, so neither pass anchors on the other):

- **Spec axis** -- does the plan faithfully cover the input? Every requirement from Phase 1 traces to a task or an explicit deferral; every Phase 3 decision is honored; no task invents work the user never asked for.
- **Standards axis** -- does every task conform to wave-orchestration's rules? Right-sized; files-in-scope honest (grep for hidden coupling -- two tasks "in different files" that both edit a shared registry are one task or two waves); acceptance mechanically checkable; wave table's disjointness claims true; escalation and serial-suite rules present.

Fix findings, then re-check anything structural (a task split in review can change the wave table).

## Phase 6 -- User approval loop

Present: the wave table, a one-line-per-task summary, the decision log, and anything the review flagged as judgment calls. Then ask for approval -- plainly, e.g. "Does this plan look right? Reply yes to finalize, or tell me what to change." Revise and re-present until approved. Do not start execution: the handoff on approval is a single closing pointer --

> Plan approved and written to `planning/`. To execute, invoke
> **wave-orchestration** (say "run wave 1") in this or any fresh session.