--- name: promote-design description: "Ingest an EXPECTED design-tool delivery (a Claude Design zip/folder answering promoted design-prompts briefs) in one atomic pass — place the prototype files, wire the entry point + resolver, record provenance, add registry rows, flip the boards — using the promote-design.js helper for the mechanical steps. Reserves design-sync for UNEXPECTED drift only. Usage: /promote-design [DB-id…]" argument-hint: " [DB-id… it fulfills — omit to infer from filenames]" --- > **Specialization:** Read `CLAUDE.md` first and bind every `<…>` placeholder and every "per `CLAUDE.md`" reference from it (prototype location + entry point + file pattern + route/step resolver, design-backlog + design-prompts board paths, sidecar convention, screen registry path). 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 and single writer** (Law 3) for ingesting a design-tool delivery you were **expecting** — the return leg of a design-prompts promotion. The courier steps (unpack, place, wire, hash, flip three boards) were previously manual and were exactly where board-vs-reality drift crept in; this command makes them one atomic, mostly-scripted pass. **The key distinction:** an *expected* delivery answers briefs you sent, so its delta is known at ingest — it never needs a `design-sync` drift sweep. `design-sync` remains the tool for *unexpected* prototype changes (a human freelancing in the design tool, a re-export with surprises). ## 1. Resolve the delivery and the briefs - `$ARGUMENTS[0]` is the delivery path (a zip or a folder). Remaining arguments are the `DB-…` ids it fulfills; if omitted, infer candidates by matching delivered filenames to the design-prompts board's expected outputs, and **confirm the mapping with the human** before proceeding (never guess silently). - Read the design-backlog + design-prompts boards. Every claimed id should be `◐ In Design` (or `☐` with a sent brief); flag anything else. ## 2. Dry-run the mechanical ingest Run the helper: ``` node .claude/workflows/promote-design.js \ --delivery --prototype --entry \ --pattern "" --report docs/APPROVAL_INBOX/_promote.json ``` (all values per `CLAUDE.md`; the helper defaults to **dry-run**). It classifies every candidate file `NEW | OVERWRITE | IDENTICAL | UNEXPECTED`, computes source hashes, checks each NEW file for a sidecar sibling, and proposes the entry-point include lines. Review its report: - **NEW matching a claimed brief** → proceed. - **OVERWRITE of an existing prototype source** → this is a *modification*, not a promotion. Do NOT apply it here — route it to `design-sync` (that is precisely a drift item, possibly contract-affecting, possibly wired). Expected deliveries add screens; they do not silently rewrite existing ones. - **UNEXPECTED** (matches the pattern but no claimed/inferable brief) → surface to the human: adopt (assign/author a backlog row retroactively) or set aside. Never place a screen with no paper trail. - **Missing sidecar** on a NEW file → note it; you will backfill in step 5. ## 3. Apply Re-run the helper with `--apply`. It places the NEW files + sidecars, inserts the entry-point include lines idempotently, and re-emits the report with final hashes. The **route/step resolver** entries are project-specific structure the script will not guess at: apply them yourself from the report's `resolverTodos` (the helper lists each new screen's route id + file so the edits are mechanical for you). ## 4. Verify the render (trust, then verify) Render the prototype entry point in an isolated headless browser and confirm every newly-wired route resolves and renders without console errors, styled (rule counts > 0). A broken route is a blocker to fix before any board flips — never flip boards ahead of a green render. ## 4b. Continuity delta check (a delivery batch is a journey event, not just files) A batch of new screens splices into journeys exactly like an in-repo build does — so before the boards flip, resolve the delivered screens' journey membership (the `journeys` field of their delivered sidecars; the brief's workflow otherwise) and re-run the `journey-continuity-audit` skill's **Phase-0 edge ledger** over those journeys: every delivered screen must have a live inbound edge (no orphans — if the design tool couldn't repoint the upstream CTA, that repoint is now YOUR wiring todo, or `design-sync`'s when the upstream screen is built), its primary CTA must resolve with the subject's context key carried, and zero new dead/legacy/wrong edges may appear. For a large batch (3+ screens on one journey) or any amber, dispatch `journey-auditor` scoped to the journey instead. **Boards flip only on green** (step 6 waits on this). ## 5. Backfill any missing sidecars For each NEW screen delivered without a `.uimap.json` sibling, author it now from the rendered screen + its brief per the **`contract-sidecar`** skill (`"born": "console"`), so no screen enters the registry sidecar-less. (Prevent recurrence: the design-prompts Global preamble's output contract requires the sidecar — if deliveries keep arriving without one, tighten the preamble, and note it in `LESSONS.md`.) ## 6. Integrate (single writer, one atomic pass) 1. **Screen registry**: a `☐` row per new screen (route, name, archetype, module) with provenance `born=console · brief= · hash=<…> · `. 2. **Boards**: each fulfilled design-backlog row → `✅ Designed ()`; design-prompts index synced; briefs kept for provenance. 3. **Memory trio**: `PROGRESS.md` activity line (delivery ref, files, rows); Insights/Lessons as usual. Because the flips are one pass anchored to the helper's report, the three boards cannot diverge from each other or from disk — the failure mode the old manual courier loop kept producing. ## 7. Report Summarize: files placed / skipped-identical / routed-to-design-sync / set-aside; wiring applied + render verification; sidecars delivered vs backfilled; registry + board deltas; anything needing the human.