--- name: design-sync description: "In-repo prototype-DRIFT remediation. Dispatches design-sync agent(s) over a scope (whole registry, a module, a route set, or an existing plan file), presents the routed re-sync plan at ONE checkpoint, then as single writer EXECUTES the whole plan end-to-end — cosmetic/structural nudges through the reconstructor's re-sync mode (wiring preserved), contract-affecting changes through spec-architect + dependent-workflow re-enrich, NEW screens through reconstruct-sweep, REMOVED screens to a human decision — and closes with a post-execution /journey-audit over the flagged journeys. The full-executor sibling of /build-workflow for drift; the motor for the design-sync agent's advisory plan. Usage: /design-sync " argument-hint: " (empty = periodic full-registry drift sweep)" --- > **Specialization:** Read `CLAUDE.md` first and bind every `<…>` placeholder and every "per `CLAUDE.md`" reference from it (prototype location + entry point + source glob + framework prefix, the route→source mapping, the design-system prefix + stylesheet, the reconstruction-workflow doc + reconstruction command, the screen registry + workflow registry paths, the approval-inbox path, the module map, the concurrency cap, and the priority/golden journeys). This file hard-codes no project value. If a needed value is missing from `CLAUDE.md`, STOP-and-ask. See `SPECIALIZE.md`. You are the **orchestrator** for in-repo prototype-drift remediation and the **single writer** (Law 3) of everything it changes. The `design-sync` agent is **advisory** — it diffs the updated prototype against each screen's recorded provenance and returns a routed re-sync plan (writing only its plan file); **you** dispatch it, get approval, and execute every routed fix. Read the `design-sync` agent's contract (`.claude/agents/design-sync.md`) first — its "routed re-sync plan" output is this command's worklist. **Precedence (Law 1) — never invert.** The **updated rendered prototype is the new contract** (rendered > spec > screenshot > draft md). Built code and existing specs are the *stale* side until reconciled. A change the spec or wiring cannot absorb without a human decision (a removal, a contract conflict, an ambiguous diff) is a **STOP-and-surface**, never a silent rebuild. ## 1. Resolve scope Parse `$ARGUMENTS`: - `all` (or empty) → every screen in the screen registry (a periodic full-registry drift sweep). - one or more **module codes** (per `CLAUDE.md §module-map`) → those modules' screens. - one or more **routes / screen names** → those screens. - a path to an **existing `*_design-sync.md` plan** in the approval inbox → **skip triage and execute that plan** (the resume / re-apply path). Use this to run a plan a prior sweep produced but did not finish. For a triage scope, assemble the dispatch packet: the prototype entry point + source glob, each in-scope screen's recorded provenance (`last_synced` + source hash, from its spec / `_UIMAP.md` + registry row), and the screen registry. Skip nothing the agent skips (pipeline-born screens whose hash still matches birth-provenance, and graduated screens, are out of drift scope by definition — the agent handles that). ## 2. Dispatch design-sync (parallel, capped per `CLAUDE.md`) One `design-sync` agent per module / natural scope-shard, concurrently (cap per `CLAUDE.md`; default 8). Agents only read the prototype + code and write their own plan file to the approval inbox — safe to parallelize. Retry a failure ≤2 times (Law 11), then file it in the approval inbox and continue. When the scope was a single plan file, skip this step. ## 3. Merge + present at ONE checkpoint, then STOP Collect the agents' plans and merge into one drift table. If two shards touched the same route (shared screens), keep the higher-blast-radius row. Present, grouped by impact: ``` Drift scope: <…> Compared: prototype ↔ provenance Summary: NEW · MODIFIED · REMOVED · UNCHANGED Per screen: | | | impact | wired | journeys <…> | action ``` **Ask which rows to adopt.** Propose a default batch: **all cosmetic/structural MODIFIED rows with preserve-wiring** (the safe, mechanical re-syncs). **Itemize for explicit human sign-off**, never auto-adopt: - every **REMOVED** row (with its inbound-edge count), - every **contract-affecting** row, and *a fortiori* any change touching the append-only `Contracts` surface — that is a **foundation-gated human event**. ## 4. Execute the approved plan (single writer — full executor) Run the routed plan the agent produced, ordered so **seeds + contract changes land before the siblings/workflows that depend on them**: - **Cosmetic / structural MODIFIED** → dispatch the project's **reconstruction command in re-sync mode** (per `CLAUDE.md`; `screen-reconstructor` re-sync) once per screen, carrying the **precise delta** + the **preserve-wiring** flag so the reconstructor modifies surgically and never rebuilds a wired screen from scratch. 1:1 fidelity is the bar (Law 1). - **Contract-affecting** → dispatch **`spec-architect`** to re-reconcile the module/screen (`_MODULE.md` · `_UIMAP.md` · `_DB_SCHEMA.md`), then run the reconstructor re-sync, then **re-wire via `module-wirer`** wherever the contract surface actually moved (new field/CTA/param/role gate/live element). Mark every dependent `_WORKFLOW.md` for re-enrich (its next `/build-workflow` picks it up). A change touching the append-only `Contracts` surface stops here for a human — surface it, do not apply. - **NEW** → add `☐` rows to the screen registry, then run the project's reconstruction as a **seed-safe reconstruct-sweep** batch (no two seedless screens share a module). - **REMOVED** → **human decision** (retire vs keep vs intentional). **Never** delete a removed screen's code, data, or migration — surface it and stop on that row. Between agents, retry ≤2 (Law 11); a fix that fails twice is filed in the approval inbox and the rest of the plan continues. ## 5. Flip the registries (single-writer, additive) Apply the plan's "registry updates" yourself (the agent never does): affected `✅ → ◐` with a `resync: ` note; new `☐` rows for NEW screens; `WORKFLOW_REGISTRY` rows for the re-enrich workflows reset to needs-enrich. Make **narrow, uniquely-anchored, per-row** edits (re-read the region first) — several drift fixes may land at once and a section rewrite clobbers a peer. ## 6. Post-execution continuity delta check Run **`/journey-audit `** over the plan's **journeys to re-audit** — **after** executing the plan, never during (a half-applied edge reads as a gap). Drift is **not adopted** until those ledgers are green: a MODIFIED screen can silently flip an edge `OK → DEAD-END/WRONG`, a NEW screen can orphan, a removal severs inbound edges. A newly-opened dead edge is a defect, not done — loop it back through §4. ## 7. Integrate the paper trail `PROGRESS.md` activity line (drift scope, rows adopted/handed-off/deferred, the continuity verdict); graduate Insights → `INSIGHTS.md`, Lessons → `LESSONS.md`. Keep the agents' plan files in the approval inbox as provenance. After a fold-in that moved the code tree, **re-index the code-discovery graph** (orchestrator-only, per `CLAUDE.md §0`). ## Concurrency safety **Do not run `/design-sync` in parallel with an active `/build-workflow` or `/build-wave` sweep** — both are single-writers to the screen/workflow registries and the specs; concurrent writes corrupt rows or clobber peers. Safe windows: **between waves**, or **right after a prototype re-export**. The pattern that always works: prototype re-export → `/design-sync ` → human adopt → then resume `/build-workflow` / `/build-wave`. ## Invariants - **Single writer:** only you write screens, specs, registries, and memory; the `design-sync` agent writes only its plan file. - **Full executor:** the whole routed plan is carried out here — reconstruct re-sync, spec-architect re-reconcile + workflow re-enrich, NEW reconstruct-sweep, REMOVED → human — closed by a post-exec `/journey-audit`. - **Preserve wiring:** every already-wired MODIFIED screen is re-synced surgically, never rebuilt. - **Human-gated by construction:** REMOVED screens and `Contracts`-surface changes never auto-apply. - **No auto-delete:** a removed screen's code/data/migration is surfaced for a decision, never deleted. - **Capped autonomy (Law 11):** ≤2 retries per agent/fix, then file and continue. - **Capped concurrency** per `CLAUDE.md` (default ≤8). - **Not adopted until green:** the drift is complete only when the post-execution journey ledgers pass.