/prepare-migration

name: prepare-migration
description: Prepare a whole site for migration by orchestrating the prep cascade — a full-inventory crawl (extract --prep), page-type and module-catalog confirmation (direct --prep), archetype prototypes plus design canon (prototype --prep), and asset preparation — with confirmation gates between phases. Builds the typed page inventory, confirmed module catalog, and canon that `migrate` consumes. Use when the user wants to prepare or set up a full-site migration, run migration prep, confirm page types and modules before migrating a site, get a large site ready to migrate, or invokes `$stardust prepare-migration`. Trigger phrases include "prepare the migration", "migration prep", "set up the migration data", "get the site ready to migrate". Redesign-flow only — for same-design migrations `replica` runs its own preserve-mode prep cascade; never chain prepare-migration with replica. Not for running the migration itself (`migrate`) or converting a single page (`deploy`).
license: Apache-2.0
compatibility: Requires Node 22+, Playwright with Chromium resolvable from the project, playwright-cli on PATH, and the impeccable skill (github.com/pbakaus/impeccable) installed alongside stardust.

stardust:prepare-migration

Orchestrate the migrate-prep cascade. When the user commits to migrating an existing site, this skill runs the upstream phases (`extract`, `direct`, `prototype`) in their `--prep` modes, sequenced with confirmation gates so the user can confirm or refine the inferred catalog at each step.

`prepare-migration` is a **thin orchestrator** — it does not duplicate logic from the underlying skills; it invokes them and brokers the per-phase summaries. The substantive work lives in:

• `skills/extract/SKILL.md` § Prep mode
• `skills/direct/SKILL.md` § Prep mode
• `skills/prototype/SKILL.md` § Prep mode +

`reference/canon-extraction.md`

When prep is complete, the user runs `$stardust migrate` separately. The two-step boundary (`prepare-migration` then `migrate`) is intentional: it makes "I'm committing to migrate this site" a conscious gesture and keeps idempotency obvious.

Inputs

• `--from <phase>` — optional. Resume the cascade from a specific

phase. Values: `extract | direct | prototype | assets | dynamics`. Default starts from the earliest incomplete phase.

• `--skip-confirm` — optional. Skip the per-phase confirmation

gates. Useful for re-runs where the catalog is already settled. Default is to gate at every phase boundary. Hands-off mode (`skills/stardust/SKILL.md` § Hands-off mode, i.e. `state.json.handsOff: true`) implies `--skip-confirm`.

• `--canon-from <slug>` — optional. Forward to

`prototype --prep --canon-from <slug>` when that phase runs. Override the default canon-author (which is `home`).

• `--refine-module <module-id>` — optional. Re-enter Phase 2's

module-catalog step for one module — the target of `migrate`'s "bespoke slot crossing promotion threshold" hint. Promotes the recurring bespoke slot into that module's slot schema (`DESIGN.json.extensions.modules[]`), surfaces the change for confirmation, then stops; it does not re-run the full cascade. Affected pages are stale-flagged content-aware per `skills/stardust/reference/state-machine.md`.

Setup

1. Run the master skill's setup (`skills/stardust/SKILL.md` § Setup) — impeccable dep check, context loader, state read. **Flow guard.** This is the redesign flow's orchestrator. If `state.json.flow` is `replica`, refuse: print "never run `prepare-migration` before or after `replica`" and the switch command (`$stardust prepare-migration --switch-flow`, which marks the replica artefacts stale — master skill § Two migration flows). If `flow` is absent, resolve it first: a keep-design phrase in the ask ("1:1", "exact replica", "same design", "faithful", "re-platform") means this skill does not apply — say so and hand to `replica`; a plain migration ask gets the one keep-vs-redesign question (hands-off: default `redesign`, recorded in `direction.md`); then stamp `flow: "redesign"` (`skills/stardust/reference/state-machine.md` § Flow keys). (Recorded: "build a 1:1 migration plan" entered here on a plugin that already described both flows and ran the redesign cascade for two hours before `direct` was asked for an "exact replica".) 2. Verify `stardust/state.json` exists with at least one extracted page. If not, recommend `$stardust extract <url>` and stop. 3. Verify `stardust/direction.md` exists with an active direction. If not, recommend `$stardust direct` and stop. 4. Determine which phases are already complete by inspecting project state:

• **extract**: every page has a non-null `type` in `state.json`

and `current/pages/<slug>.json` carries a `slots` block.

• **direct**: `DESIGN.json.extensions.modules[]` entries all

have `status: confirmed`; `colorReservations` and `metadata` blocks present.

• **prototype**: every page-type has at least one approved

archetype; `stardust/canon/` populated; `DESIGN.json.extensions.canon` populated.

• **assets**: favicon variants in

`stardust/migrated/assets/`; fonts downloaded.

• **dynamics**: `stardust/dynamic-features.md` present with every

row carrying a disposition; `helix-query.yaml` present when any listing is index-backed (Phase 4.5 records "none" otherwise).

Resume from the earliest incomplete phase unless `--from` overrides.

Procedure

The cascade runs five phases sequentially. Each phase invokes its underlying skill via the harness's skill-invocation tool (see the master skill § Routing for how sub-skills are addressed), surfaces the phase's prep summary, then waits for user confirmation (unless `--skip-confirm` or hands-off mode) before advancing.

Phase 1 — extract --prep

Invoke the stardust `extract` skill with the argument `--prep`. Claude Code form: `Skill { skill: "stardust:extrac