stardust

name stardust description Guided multi-page redesign of an existing website through a four-phase pipeline — extract (crawl and capture the current site), direct (set a visual direction), prototype (generate redesigned HTML), and migrate (emit a deployable static site). Tracks progress incrementally per page in stardust/state.json so redesigns are resumable. Delegates the per-page design craft (typography, spacing, color, layout, motion) to the impeccable skill. Use when the user wants to redesign, revamp, modernize, or restyle an existing site they can point to by URL, run the extract/direct/prototype/migrate flow, or resume a multi-page redesign. Also routes the same-design migration flow (replica) and the donor-design flow (reskin). Not for designing a brand-new site from scratch or one-off single-component edits. license Apache-2.0 stardust You are operating the stardust skill: a guided redesign of an existing website. The user's job is to say what they want; your job is to reason about what that means, propose a plan, and execute it through a small set of sub-commands that delegate the actual design work to impeccable . Setup (run before anything else) Verify impeccable is installed. Stardust has a hard dependency on impeccable and ships no fallbacks. Look for the impeccable skill in any of the standard harness directories the project uses ( .claude/skills/ , .agents/skills/ , .cursor/skills/ , etc.). If it is not installed, stop and tell the user: Stardust requires impeccable. Install it from https://github.com/pbakaus/impeccable and re-run the command. Version hint (advisory, never blocking). Stardust deliberately pins NO impeccable version — the design craft should always be the current one — and Claude Code only announces plugin updates through marketplace auto-update, which is off by default for third-party marketplaces such as impeccable's. So, once per session, run node <plugin>/skills/stardust/scripts/impeccable-version-check.mjs (add --local <impeccable-dir> when impeccable lives in a harness skills directory rather than the plugin registry) and surface its one output line to the user verbatim when it reports a newer version; it prints the two update commands. Any other outcome (current, unknown, offline) is noise — do not mention it, and never stop or degrade a run over it. Run impeccable's context loader once per session. Execute the loader at <harness>/skills/impeccable/scripts/load-context.mjs . Its JSON output tells you whether PRODUCT.md and DESIGN.md exist at the project root (these are the target state for stardust). Skip the loader if it already ran in this session's history. Read stardust's state. Read stardust/state.json if present ( reference/state-machine.md defines the schema). Note which pages are extracted , directed , prototyped , approved , or migrated . Read impeccable's command registry. Parse <harness>/skills/impeccable/scripts/command-metadata.json . This is the single source of truth for the 23 impeccable commands; never hardcode them in your reasoning. Status ledger. Every stardust skill appends a phase-transition line to stardust/status.jsonl at each phase start/end, per reference/run-status.md . Routing Once setup is done, route on the user's input: No argument. Render the state report described in reference/state-machine.md : project state, per-page status table, recommended next command, with reasoning. Do not write anything. First word names a sub-skill. Delegate to the matching stardust:<name> skill and pass remaining args through. The master skill routes all sibling sub-skills: keyword sub-skill owns extract stardust:extract crawl + capture the current site direct stardust:direct resolve the visual direction prototype stardust:prototype per-page redesign prototypes migrate stardust:migrate full-site platform-agnostic static HTML prepare-migration stardust:prepare-migration the migrate-prep cascade (prep phases, assets, dynamic-blocks gate) — redesign flow only replica stardust:replica same-design migration (re-platform, keep the current design) — runs its own preserve-mode prep, then hands off to migrate/deploy/rollout reskin stardust:reskin byte-faithful content re-laid onto a separately defined donor design system deploy stardust:deploy one page → EDS blocks + DA delivery rollout stardust:rollout whole migrated site → EDS, with coverage + delivery gates diff stardust:diff prototype ↔ build fidelity probes (pixel + structural) audit stardust:audit three-perspective site audit — design tensions, SEO/technical, LLM visibility — scored report + findings ledger qa stardust:qa read-only post-deploy QA sweep of the live site — routing, fidelity, template conformance, rendering, visual regression, SEO, links, a11y, perf — findings report only, never fixes uplift stardust:uplift one-shot presales orchestrator (3 variants) prototype accepts --cinematic (or --cinematic=<register> ) to layer a brand-faithful motion register on top of the static prototype (per skills/prototype/reference/motion-registers.md ). uplift is the one-shot presales orchestrator: takes a URL and produces three differentiated variants (one fully cinematic) without further user coordination. Use when the user wants to skip the extract/direct/prototype chain (per skills/uplift/SKILL.md ). Migration to EDS — pick ONE of two flows, never mix them. See § Two migration flows below before answering any "how do I migrate X" question; the routing answer differs by whether the design is kept. First word is anything else (a freeform phrase). Treat it as a redesign intent. Load reference/intent-reasoning.md and follow the procedure step by step. Do not execute any impeccable or stardust command before showing the resolved plan to the user (under hands-off mode, the plan is recorded in stardust/direction.md instead of awaiting confirmation — see § Hands-off mode). Two migration flows — pick one, never mix When the user wants to migrate a site to AEM Edge Delivery (or any clean front end), the FIRST question is whether the design is kept or changed. That answer selects the flow; the downstream chain is shared. Redesign while migrating: extract → direct → prototype , or in one orchestrated step prepare-migration (the prep cascade with confirmation gates) → migrate → deploy (one-page pilot) / rollout (whole site). Keep the current design (re-platform): replica → migrate → deploy / rollout . replica subsumes the prep cascade in preserve mode — extract --prep is its Phase 1, a mechanical direction-preservation step replaces direct --prep , and gated archetype recreation (measured source-fidelity gate per breakpoint) replaces prototype --prep . Never run prepare-migration before or after replica ; there is no separate prep step in this flow. New design from a donor, same content: reskin — content is byte-gated, design comes from another live site or local prototypes. State the chosen flow explicitly in the first response to a migration question, including the fact that replica needs no prepare-migration step, so the user never has to ask which prep applies. Hands-off mode Activated by --hands-off on any stardust invocation, or by an explicit user phrase ("fully hands-off", "no approval gates", "run autonomously"). On activation, stamp state.json.handsOff: true (schema note in reference/state-machine.md § Hands-off keys) and append an activation line to stardust/direction.md . The mode removes waiting , not validation : every quality gate in the pipeline still runs at full strength; what changes is who resolves the interactive pauses. Under hands-off, every interactive gate across the pipeline auto-resolves: gate hands-off resolution direct clarifying questions derive the answers from the captured evidence ( stardust/current/ ), and state each as a named assumption in direction.md prototype brief-confirmation waits skip; proceed on the authored brief prototype approval granted by the agent's own judgment only after all quality gates pass (craft bar, validation loop, motion gates); recorded as approvedBy: "hands-off" on the page's approved history entry in state.json prepare-migration phase gates behave as --skip-confirm rollout runs full-auto end-to-end Defaults under hands-off (override only when the invocation says otherwise): One canonical direction. No variant fan-out — commit to a single direction and record the rationale in direction.md . Volume caps as reasoned proposals. Default 100 pages overall, 20 per template . Roster priority: (1) every page linked from the header and footer, (2) section landing/overview pages, (3) a representative spread of detail pages across all templates. State the chosen caps in direction.md . Commit at the end of each phase when the project is a git repo. Before the FIRST such commit, run the token-hygiene check that deploy § Token hygiene (#16) specifies: .gitignore must cover .env , .env.* , and qa/ before anything is committed — in the happy path the first commit lands at the end of the audit phase, long before deploy's SKILL.md is ever read, and a tracked .env poisons every later push (stardust-style e2e finding: GH013 push rejection + history rewrite at deploy time). Hard blockers remain stops. An unreachable source site, an expired DA_TOKEN that cannot be recovered, or a signal-absent brand surface (extract captured no usable brand signal even after a re-run) are not judgment calls — state the blocker precisely, append event: "blocked" to stardust/status.jsonl , and halt. Never guess around a hard blocker. Quality gates NEVER weaken under hands-off. Provenance validation, the validation loop, fidelity gates, delivery gates, and rollout's optimize gate all run unchanged. Hands-off changes who answers , not what must pass . The "open and reasoned" principle Stardust does not ship a closed intent → commands lookup. Every freeform phrase is reasoned about in public. You must: Restate the phrase in stardust's dimensional vocabulary ( reference/intent-dimensions.md ). Identify which axes the phrase moves and in which direction. Identify what is underspecified and ask the user at most two clarifying questions. Map the resolved direction to a sequence of impeccable commands, citing each command's reference in reference/impeccable-command-map.md . Show the proposed plan to the user before executing. After execution, record the resolved direction, axes, commands, and reasoning in stardust/direction.md with a stardust provenance block. Worked examples of this procedure live in reference/intent-examples.md . Per-page state and "stale on direction change" Pages have lifecycle states ( extracted | directed | prototyped | approved | migrated ). When the user's direction changes after some pages have already been prototyped or migrated, mark those pages stale; do not auto-re-run. The user opts in to re-prototyping or re-migrating explicitly. Details in reference/state-machine.md . Artifacts you read and write Stardust state lives under stardust/ . Impeccable's PRODUCT.md / DESIGN.md / DESIGN.json live at the project root and represent the target state. The current (extracted) state lives under stardust/current/ . Full layout in reference/artifact-map.md . Provenance Every artifact stardust writes carries a provenance block as the first line or first key, declaring: which sub-command wrote it, against which user input, what was synthesized vs. authored, and what other artifacts were read. Format conventions in reference/artifact-map.md . Journal rule A multi-session stardust project benefits from a chronological journal that records the prompt history, decisions, and open questions across turns — separate from the state machine and from per-artifact provenance. State.json records what is , provenance records why an artifact says what it says , but neither captures the narrative arc of how the project got here . The journal does. Maintain stardust/journal.md per the format in reference/journal-format.md . On every prompt execution that resulted in a non-trivial write (any direct , prototype , migrate , or substantial iteration), append an entry before ending the turn. The journal is append-only . If a prior entry turns out wrong, write a new entry that corrects it; do not edit history. This preserves the reasoning trace and lets reviewers see how decisions evolved. The journal is project-scoped and human-facing — it lives at the same level as the impeccable PRODUCT.md, not under stardust/current/ or stardust/canon/ . Treat it as the shared narrative layer over stardust's state machine. When the user invokes stardust at the start of a new session, the journal is read first (along with state.json) — its last 3-5 entries carry the "where did we leave off" context that the state machine doesn't. Validation rule Every artifact stardust writes that a human will eyeball — proposed HTML, brand-review.html, the migrated site — runs through a recursive validate- and-fix loop before being marked done. The principle: type checks and test suites verify code correctness; only browser rendering verifies feature correctness. For HTML the user will see (prototypes, migrated pages, the brand-review HTML): Render in Playwright (file:// for static, or local dev server). Capture at three viewports — desktop 1440×900 , tablet 768×1024 , mobile 390×844 : Full-page screenshot. Browser console messages (errors + warnings). Network failures (4xx / 5xx / aborted requests, missing assets). Uncaught JS exceptions + unhandled promise rejections. Layout sanity: no horizontal overflow; key landmarks present and non-empty. a11y quick-pass: alt text, input labels, heading order, contrast on text-over-image. Interaction smoke: hover an interactive card, scroll-trigger fires, nav opens/closes, primary CTA reachable by keyboard. If any issue is found, fix it and re-run the loop. Iterate recursively until either (a) no issues remain or (b) the fix needs user input — in which case surface the question and stop. Do not report a task complete with known issues outstanding. Save the final clean-pass screenshots to stardust/validation/<artifact>/<viewport>.png so reviewers can compare without re-running. Per-sub-skill validation specifics live in each skill's reference docs — notably extract/reference/playwright-recipe.md (the canonical recipe), prototype/reference/motion-validation.md (motion-specific gates), and prototype/SKILL.md Phases 2.5–2.8 (the critique / audit / adapt / motion gate cascade). What stardust never does Invent design opinions that contradict impeccable's hard rules. Defer to impeccable. Execute a redesign plan without showing it first (hands-off mode records the plan in stardust/direction.md instead of waiting — § Hands-off mode). Force a re-run on stale pages without explicit user opt-in. Crawl an existing site beyond the user's confirmed page cap (an explicit --pages list is itself the confirmed scope — listed pages are never dropped; the crawler warns rather than truncates when the list exceeds --max ). Emit platform-specific output from migrate . migrate emits platform-agnostic static HTML; the EDS conversion and delivery are owned by the stardust:deploy (one page) and stardust:rollout (whole site) sub-skills, routed above. References reference/intent-dimensions.md — the axes redesigns move along. reference/intent-reasoning.md — the procedure for handling a freeform phrase. reference/intent-examples.md — worked examples (8-12) of the reasoning style. reference/impeccable-command-map.md — when to reach for each of the 23 impeccable commands. reference/state-machine.md — page lifecycle, stale rules, state report format. reference/artifact-map.md — every file stardust reads or writes, with ownership and provenance shape. reference/divergence-toolkit.md — anti-mediocrity device. Default-moves list, deterministic seed, font decks, role-naming rule. Consumed by direct (when authoring target tokens) and prototype (when generating variants). reference/token-contract.md — :root CSS custom-property contract every prototype and migrated page must expose. The token interface between stardust and any downstream consumer. reference/data-attributes.md — structural data-* vocabulary applied to sections in every prototype and migrated page. The structural lingua franca between stardust sub-commands and downstream tools. reference/journal-format.md — stardust/journal.md entry format. Append-only chronological log; the shared narrative layer over the state machine. reference/run-status.md — the stardust/status.jsonl phase-transition contract every skill appends to. The deterministic progress surface for any harness. reference/learnings.md — the per-run learnings ledger contract ( stardust/learnings.md ). rollout's report phase writes it; plugin maintainers harvest pending entries into skill diffs. Cinematic-feature references (cross-cutting) Owned by prototype/ because the cinematic feature is scoped to prototype rendering, but cited by direct (when selecting a register), uplift (when picking C's register), and migrate (when copying motion assets through): ../prototype/reference/motion-registers.md — five brand-faithful motion personalities ( arrival , kinetic-display , live-systems , editorial , kinetic-grid ) and the selection heuristic that maps PRODUCT.md Brand Personality traits to a register. ../prototype/reference/motion-stack.md — technology choice: Lenis + CSS keyframes + rAF + IntersectionObserver. Why not GSAP. Bundle policy. ../prototype/reference/motion-attributes.md — data-* vocabulary the runtime consumes ( [data-anim] , [data-tile-anim] , [data-countup] , [data-flip] , [data-fill] , [data-split] , [data-parallax] ). ../prototype/reference/motion-runtime.md — the canonical inline runtime script that powers every cinematic prototype. ../prototype/reference/motion-validation.md § Pass 6 — cinematic-mode validation gates (Lenis boot, reduced-motion fallback, scroll-jack, three-position screenshots, register-match, motion C-cliff detector). Uplift-feature references Owned by uplift/ . Cited by master routing when delegating /stardust:uplift <URL> :