stardust

# 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 > <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. 2. **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. 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 `<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. 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:<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, dynamics 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 | | `dynamics` | `stardust:dynamics` | the dynamic surface of a migration — detect, classify, triage, implement, verify (APIs, search, forms, modals, media, tags, client-rendered, sheet data); migration-bound, invoked by prepare-migration / replica / migrate / rollout or standalone on an already-migrated site | | `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. - **Both migration flows carry the dynamic surface by default.** The pre-import gate (`prepare-migration` 4.5 / `replica` Phase 2, with `migrate` as the safety net) runs `stardust:dynamics` Phases 1–3 so every API, search box, form, modal, player, tag and client-rendered surface gets a disposition before import; `rollout` D2 implements the reproducible rows and `qa` replays parity. Never for redesign-only work (`uplift`, a bare `extract`): dynamics is a migration concern. 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 | | `dynamics` owner decisions (backend, tags on the new host, datasource ownership, locale scope) | ship the interim tier, record each decision by name in `dynamic-features.md` and the parity report, continue; regulated-pii forms stay blocked | 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/<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.