From stardust
Orchestrate the migrate-prep cascade — extract --prep → direct --prep → prototype --prep → assets prep — with confirmation gates between phases. Builds the data structure migrate consumes.
How this skill is triggered — by the user, by Claude, or both
Slash command
/stardust:prepare-migrationThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Orchestrate the migrate-prep cascade. When the user commits to
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 modeskills/direct/SKILL.md § Prep modeskills/prototype/SKILL.md § Prep mode +
reference/canon-extraction.mdWhen 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.
--from <phase> — optional. Resume the cascade from a specific
phase. Values: extract | direct | prototype | assets. 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.--canon-from <slug> — optional. Forward to
prototype --prep --canon-from <slug> when that phase runs.
Override the default canon-author (which is home).Run the master skill's setup (skills/stardust/SKILL.md
§ Setup) — impeccable dep check, context loader, state read.
Verify stardust/state.json exists with at least one extracted
page. If not, recommend $stardust extract <url> and stop.
Verify stardust/direction.md exists with an active direction.
If not, recommend $stardust direct and stop.
Determine which phases are already complete by inspecting project state:
type in state.json
and current/pages/<slug>.json carries a slots block.DESIGN.json.extensions.modules[] entries all
have status: confirmed; colorReservations and metadata
blocks present.stardust/canon/ populated;
DESIGN.json.extensions.canon populated.stardust/migrated/assets/; fonts downloaded.Resume from the earliest incomplete phase unless --from
overrides.
The cascade runs four 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)
before advancing.
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.Invoke:
Skill {
skill: "stardust:direct",
args: "--prep"
}
The underlying skill runs five --prep overlays (type catalog
confirmation, module catalog finalization, color reservations,
direction re-evaluation, brand metadata defaults).
Surface the summary and gate. User options match Phase 1
(yes / refine "<phrase>").
Invoke:
Skill {
skill: "stardust:prototype",
args: "--prep" + (canonFromSlug ? " --canon-from " + canonFromSlug : "")
}
The underlying skill fills page-type gaps (one approved archetype
per type) and writes canon back per
skills/prototype/reference/canon-extraction.md. First approval
establishes canon; subsequent approvals extend it (with conflicts
logged as deviations by default).
This phase typically takes the longest — each archetype goes through the full prototype loop (shape brief, craft, viewer, iterate, approve). Stream progress to the user as each archetype lands.
Surface the summary and gate.
Generate or download asset variants needed for the migrated site. This phase has no underlying SKILL — it runs as a small image- processing + download routine.
Favicon variants. From the canonical favicon at
stardust/current/assets/favicon.<ext>, generate:
stardust/migrated/assets/favicon-512.pngstardust/migrated/assets/apple-touch-icon.png (180×180)stardust/migrated/assets/icon-192.png,
icon-512.png (manifest sizes)Font downloads. Scan stardust/canon/canon.css (and
stardust/canon/header.html / footer.html) for @font-face
rules with external URLs. For each:
stardust/migrated/assets/fonts/<basename-with-hash>.<ext>.@font-face url(...) reference in canon files
to the local path.metadata-override warning per page).Brand-asset audit. Verify the logo, favicon, and any
media files referenced by canon module renderings are
present in stardust/current/assets/. Surface missing assets
to the user.
Surface summary and final gate:
assets prep complete
====================
Favicon variants: favicon-512.png, apple-touch-icon.png, icon-192.png, icon-512.png
Font downloads: 4 files (HarmoniaSans 4 weights)
Brand assets: all present
Migrate-readiness: confirmed
→ Run `$stardust migrate` to apply canon to every page in inventory.
prepare-migration complete
==========================
Phase 1 (extract --prep): 127 pages, 7 types, 8 module candidates
Phase 2 (direct --prep): types & modules confirmed; metadata set
Phase 3 (prototype --prep): 6 archetypes approved; canon written
Phase 4 (assets prep): favicon variants + fonts + brand assets ready
Next: $stardust migrate
prepare-migration writes nothing directly — every artifact is
written by the underlying skill or by Phase 4's image/download
routine. After the cascade runs, the project state has:
| Artifact | Phase that wrote it |
|---|---|
state.json.pages[].type | extract --prep |
current/pages/<slug>.json § slots | extract --prep |
DESIGN.json.extensions.modules[] (status: confirmed) | extract --prep + direct --prep |
DESIGN.json.extensions.colorReservations[] | direct --prep |
DESIGN.json.extensions.metadata | direct --prep |
stardust/canon/ (header, footer, css, modules/) | prototype --prep |
DESIGN.json.extensions.canon | prototype --prep |
stardust/migrated/assets/favicon-* | assets prep |
stardust/migrated/assets/fonts/ | assets prep |
stardust/state.json (per-page status updates) | each underlying phase |
$stardust extract <url> and stop.$stardust direct and stop.$stardust prepare-migration --from <phase>.reference/canon-extraction.md. If the user wants to override
per-conflict (promote to canon / reject and re-iterate / log as
deviation), surface during the phase's confirmation gate rather
than at runtime. A future --strict-canon flag could refuse
approvals that conflict; not in v0.2.Per skills/stardust/reference/state-machine.md: stardust does
not lock. Two concurrent prepare-migration runs on the same
project are last-write-wins and likely to corrupt canon. Document
this in the user report; do not engineer around it.
Re-running prepare-migration after partial completion resumes
from the earliest incomplete phase (or the explicit --from
phase). Each underlying skill is itself idempotent — already-
typed pages are not re-typed, already-confirmed modules are not
re-proposed, already-approved archetypes are not re-prototyped,
already-generated favicon variants are not re-generated.
Re-running after full completion is a no-op unless inputs changed (extract found new pages, direction was edited, the canon-author prototype was re-iterated, etc.).
skills/extract/SKILL.md § Prep modeskills/direct/SKILL.md § Prep modeskills/prototype/SKILL.md § Prep modeskills/prototype/reference/canon-extraction.md — the
five-step extraction procedure prototype --prep performs on
approvalskills/migrate/SKILL.md — the consumer of every data
structure this cascade preparesnotes/migrate-template-canon-refactor.md — design plan and
rationaleskills/stardust/reference/state-machine.md — page typing,
stale-flagging cascadeskills/stardust/reference/artifact-map.md — file structure,
DESIGN.json.extensions shapeCreates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub paolomoz/stardust-2 --plugin stardust