--- 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. 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) 1. **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 > and re-run the command. 2. **Run impeccable's context loader once per session.** Execute the loader at `/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. 3. **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`. 4. **Read impeccable's command registry.** Parse `/skills/impeccable/scripts/command-metadata.json`. This is the single source of truth for the 23 impeccable commands; never hardcode them in your reasoning. 5. **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:` 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) | | `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 | | `uplift` | `stardust:uplift` | one-shot presales orchestrator (3 variants) | - `prototype` accepts `--cinematic` (or `--cinematic=`) 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`). - **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). ## 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: 1. Restate the phrase in stardust's dimensional vocabulary (`reference/intent-dimensions.md`). 2. Identify which axes the phrase moves and in which direction. 3. Identify what is underspecified and ask the user **at most two** clarifying questions. 4. Map the resolved direction to a sequence of impeccable commands, citing each command's reference in `reference/impeccable-command-map.md`. 5. Show the proposed plan to the user before executing. 6. 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): 1. Render in Playwright (file:// for static, or local dev server). 2. 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. 3. **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. 4. Save the final clean-pass screenshots to `stardust/validation//.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 `: - `../uplift/SKILL.md` — one-shot presales orchestrator: extract → tension/trait identification → 3-variant direction → prototype × 3 → open + summarize. - `../uplift/reference/what-if-candidates.md` — catalog of 8 worked captured-trait amplification candidates that B and C select from in Phase 2b — plus its § Extension rule admitting evidence-shaped `derived` candidates.