/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 stardust: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". Not for running the migration itself (stardust:migrate) or converting a single page (stardust:deploy).
license: Apache-2.0

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 | dynamic-blocks`. 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. 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.

• **dynamic-blocks**: `stardust/dynamic-blocks-map.md` and

`helix-query.yaml` present — only required when the inventory contains listing blocks (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 Skill tool, 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:

Skill {
  skill: "stardust:extract",
  args: "--prep"
}

The underlying skill runs the standard extract procedure with the five `--prep` overlays (lift cap, page typing, module candidates, typed slots, prep summary).

On completion, surface the summary verbatim and gate:

Confirm and continue? (yes / refine "<phrase>")

User options:

• **`yes`** — advance to Phase 2.
• **`refine "<phrase>"`** — re-invoke `extract --prep` with the

refinement (e.g., "type news/* slugs as listing not article", "exclude /search and /404 from inventory"). Re-surface summary; loop.

Provenance guard (between Phase 1 and Phase 2)

Before invoking `direct --prep`, validate every page in the inventory via `validateProvenance(page)` per `skills/stardust/reference/state-machine.md` § Provenance validation. Abort the cascade with the helper's error if any page lacks live-render evidence. This is the cascade-level defense against the failure mode where `extract --prep` (or its delegated sub-agent) silently synthesized one or more page records — extract's own write-time refusal is the primary guard, but the cascade adds a second check between phases so the synthesis bug recurring under a different rationale cannot quietly contaminate the rest of the run.

The same guard runs implicitly inside Phase 2, 3, and 4 (each underlying skill's setup calls `validateProvenance()` per its own SKILL.md) — but surfacing it here as an explicit cascade step makes the abort happ