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] 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.