---
name: wave-coordination
description: >-
  Team-pattern mechanics for a multi-screen build under ui-architect's GEAR 2 —
  who merges parallel screen-composition-agent branches and when, PR/branch mechanics,
  shared-file conflict rules for shared-foundation shapes, and how to size a
  wave. Use when planning or running a GEAR-2 dispatch: "how do two parallel
  screen-composition-agent branches come back together", "who merges", "how big should
  a wave be", "what happens when two screens touch the same shared file". NOT
  for picking a project's shape (project-scaffolding, which this skill's conflict
  rules build on) or composing one screen (screen-composition).
disable-model-invocation: false
user-invocable: false
---

# wave-coordination — bring parallel branches back together on purpose

> **Claude-only seat.** This skill dispatches a Claude Code subagent (the Agent tool) — under Codex, run the equivalent work inline instead (gh#1888).

ui-architect's GEAR 2 dispatches one screen-composition-agent per screen, serial within a wave or
in isolated worktrees when a wave's screens build in parallel (`ui-architect.md`'s GEAR-2
paragraph names only worktree isolation and wave gating). The sections below are the mechanics it
never wrote — who merges, into what, when a wave is done, how big it should be, and shared-file
conflicts. Rationale for each rule: [`references/mechanics-rationale.md`](references/mechanics-rationale.md).

Name check: `ui-architect` here is the shipped whole-deliverable coordinator (gh#1183) — NOT
ADR-0040's Ladder-walker of the same name. Before authoring, renaming, reusing, or citing any
factory seat name, or quoting the ADR-0040 roster or a moved interim name — load
[references/seat-roster-names.md](references/seat-roster-names.md) (ADR-0047's disambiguation).

## The four questions this skill answers

1. **Integration** — who merges each branch, when, into what.
2. **PR mechanics** — one PR per screen, gated by surface-qa-agent, plus a wave-level PR.
3. **Conflict rules** — who owns a shared-foundation file, and how a collision resolves.
4. **Wave sizing** — how many screens a wave should hold before gating.

## Parallel-branch integration — who merges, when, into what

Each screen in a parallel wave gets its own isolated worktree and branch, one
screen-composition-agent dispatch per branch — isolation is per-dispatch, never per-wave.
Nobody merges branch-to-branch:

1. ui-architect opens (or reuses) one **wave-integration branch** (`wave/<n>-<slug>`, off the
   coordinator's own working branch — never `main` directly) before dispatching the wave's screens.
2. Every screen-composition-agent in the wave branches off that wave-integration branch, not off
   each other and not off `main`.
3. A screen's branch merges back into the wave-integration branch only after ITS OWN
   surface-qa-agent gate passes (generator ≠ critic). A screen that fails review does not merge;
   its finding routes back to the seat that caused it (`ui-architect.md`'s Failure-branches rule),
   and the wave waits.
4. Once every screen has merged, THAT branch advances — as the PR for a single-wave build, or as
   the base the next wave forks from (never the stale pre-wave point). The next wave forks once
   this wave's PR has merged (sequential); if still open, it forks from the still-open
   wave-integration branch instead (stacked).
5. ui-architect never merges with a bare local `git merge` run blind — only after the reviewer
   gate, and only fast-forward or a real three-way merge, never a force-push discarding history.

A serial wave (no parallel worktrees) skips steps 1–2's forking mechanics — one
screen-composition-agent dispatch commits straight onto the wave-integration branch, gated the
same way before the next screen starts.

## PR mechanics — keeping the "tracked, mergeable" promise

- **One PR per screen**, targeting the wave-integration branch (never `main` directly) — not one
  giant end-of-wave PR that hides which screen broke review.
- Each screen PR states: the Orientation Record/Domain Plan it built from, its surface-qa-agent
  VerifyProof result, and any shared file it touched (feeds the conflict rule below).
- When every screen has merged, ui-architect opens ONE wave-level PR from the wave-integration
  branch into the branch the coordinator was dispatched against (or `main`, on the final wave) —
  per-screen PRs stay as its merged history, not separate asks on the maintainer.
- The wave-level PR names every screen it carries, links each screen's VerifyProof, and states
  the wave number and size.

## Conflict rules — shared-foundation shapes

Two screens in the SAME wave both touching a shared-foundation file (`project-scaffolding`'s
third shape) is a **planning defect, not a merge accident** — full owner-naming, escalation, and
discovery mechanics live in [mechanics-rationale.md](references/mechanics-rationale.md)
§Conflict rules. Verdict: name the file's owner before the wave starts; a real collision escalates
to app-planning-agent to replan (never a silent second-merge-wins, never ui-architect picking a
side); an undetected-but-overlapping pair is caught at the second screen's reviewer gate. Single-
surface and rollup shapes carry no shared file, so this class doesn't apply by construction.

## Wave sizing

A wave is sized by how many screens one surface-qa-agent gate can hold accountable, not by how
many screens are left in the plan:

- **Default: 2–4 screens per wave** — enough to make isolated-worktree parallelism worth the
  mechanics above; small enough that findings stay attributable to a specific screen.
- **Shrink to 1 (fully serial)** when the wave's screens share so much surface that the conflict
  rule above would fire on nearly every pair — the mechanics cost more than the parallelism saves.
- **Never exceed the plan's own natural groupings** — sizing trims WITHIN a planned wave, it
  never re-groups the plan.
- A wave that keeps failing its reviewer gate on the same finding twice escalates to
  app-planning-agent per the Failure-branches rule — never split smaller as a workaround for an
  unresolved design question.
