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 wherever the harness installs skills or plugins: the skill list the harness exposes to you, project skill directories (`.claude/skills/`, `.agents/skills/`, `.cursor/skills/`, `.github/skills/`), or the harness's plugin cache (Claude Code: `~/.claude/plugins/cache/`; GitHub Copilot: `~/.copilot/installed-plugins/*/impeccable/skills/impeccable`). 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 harnesses do not announce third-party plugin updates by default (Claude Code's marketplace auto-update is off for third-party marketplaces such as impeccable's; Copilot has no update notice). 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 update command for the harness it found impeccable in. Any other outcome (current, unknown, offline) is noise — do not mention it, and never stop or degrade a run over it. 2. **Check the target-state files.** `PRODUCT.md` and `DESIGN.md` at the project root are the *target* state for stardust; check whether they exist (a directory listing is enough). Do not run impeccable's context loader (`scripts/impeccable context`) here: it emits directives for impeccable's own flow (init, new-work, detector, update checks) that do not apply to stardust's setup, and impeccable runs it itself whenever stardust invokes an impeccable command. Skip if already known from 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 24 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`. 6. **Project hygiene** (idempotent). Write `stardust/.gitignore` from `reference/stardust.gitignore` if absent; never edit a project's copy. In a git repo: root `.gitignore` covers `.env` / `.env.*` (managed `# >>> stardust` block), `.hlxignore` if present lists `stardust/`, and `git check-ignore -q stardust/state.json` must fail — if it passes, stop and name the rule. Offer, never write, LFS above 50 MB of tracked binaries under `stardust/`. Details in `reference/artifact-map.md` § Versioning. ## 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. The same applies to any **resume**: a new session on a project that has `stardust/state.json`, "continue", "where are we", or a resume driven by a memory file. Start with the state report (it names the flow and the last gate numbers), then enter the next phase **through its skill** — the procedure drives, not memory. (Recorded: a 144-hour resume session invoked no stardust skill at all, re-read the procedure through `grep`, and followed whatever the previous context remembered.) - **First word names a sub-skill.** Delegate to the matching sub-skill and pass remaining args through. Sub-skills are named by their bare skill name below; how to address one depends on the harness. Claude Code namespaces plugin skills as `stardust:<name>` (Skill tool); GitHub Copilot and other harnesses that flatten plugin skills expose the bare `<name>`. If the harness has no skill-invocation tool, read the sub-skill's `SKILL.md` and follow it inline. Never confuse the stardust `extract` and `audit` skills with impeccable's `extract` and `audit` commands, which are always written `$impeccable <command>`. The master skill routes **all** sibling sub-skills: | keyword | owns | |---|---| | `extract` | crawl + capture the current site | | `direct` | resolve the visual direction | | `prototype` | per-page redesign prototypes | | `migrate` | full-site platform-agnostic static HTML | | `prepare-migration` | the migrate-prep cascade (prep phases, assets, dynamics gate) — **redesign flow only** | | `replica` | same-design migration (re-platform, keep the current design) — runs its own preserve-mode prep, then hands off to migrate/deploy/rollout | | `reskin` | byte-faithful content re-laid onto a separately defined donor design system | | `deploy` | one page → EDS blocks + DA delivery | | `rollout` | whole migrated site → EDS, with coverage + delivery gates | | `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` | prototype ↔ build fidelity probes (pixel + structural) | | `audit` | three-perspective site audit — design tensions, SEO/technical, LLM visibility — scored report + findings ledger | | `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` | 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 the stardust `dynamics` skill 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. **Choosing, and recording the choice.** Read the ask before any sub-skill loads: - **Keep-design phrases select `replica` without a question:** "exact replica", "1:1", "pixel-perfect", "faithful", "same design", "keep the current design", "as is", "re-platform only", "migrate keeping the design", or a direction phrase that pins every axis unchanged (`ia-fidelity: verbatim` with palette, type and density all pinned). - **Redesign phrases select the redesign flow:** "redesign", "modernise", "refresh", "new look", "rethink", "reimagine" — any phrase that moves a design axis. - **Anything else** ("migrate X to EDS", "build a migration plan for X") asks the one keep-vs-redesign question — the only question this section asks. Under hands-off it is not asked: a keep-design phrase selects `replica`, otherwise `redesign`, recorded as a named assumption in `direction.md`. Stamp the choice in `state.json` as `flow` / `flowChosenAt` / `flowSource` (`reference/state-machine.md` § Flow keys) before delegating. The sub-skills enforce it: `migrate`, `deploy`, `rollout` and a migration-intent `extract` refuse to start a migration on a project with `state.json` and no `flow`; `prepare-migration` refuses under `flow: replica` and `replica` under `flow: redesign`. Switching is explicit — `$stardust replica --switch-flow` / `$stardust prepare-migration --switch-flow` — and marks the old flow's prototyped or migrated pages stale (§ Per-page state). **Planning aids belong to one flow.** Redesign: the `prepare-migration` plan and its phase gates, the canon, module catalogs, template plans of the "learn the template, then compile" kind. Keep-design: `replica`'s inconsistency register and `progress.json`, the archetype gate ledgers, `rollout` waves. A redesign procedure or plan template inside a replica run — or the reverse — is a routing defect: refuse it, or flag it in `direction.md` and hand back to this section. (Recorded: a same-design migration adopted a redesign-only "train the template, then compile" plan and spent an hour, 45 turns and 36 M tokens before reverting it; another loaded `prepare-migration` for a keep-design ask on a plugin that already described the two flows — description without a guard did not hold.) 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`. - **Delegate by file pointer, read by section.** A brief to a delegated agent names the files and sections it needs (`state.json`, the page's schema, the phase's SKILL.md sections); it never inlines reference docs. Reference documents are read by heading and line range, not end to end. Instruments that can stall run under their shipped deadline (replica `gate.sh`, `pixel-compare --timeout`) — never under an agent-authored `sleep N; kill` loop — and long steps write a progress file the coordinator polls instead of blocking on the agent. (Field evidence, 2026-09: in one recorded run the two conversion agents the harness watchdog killed carried the fattest briefs and whole-document reads, and a lean re-dispatch finished the same pages; that conversion lost 89 minutes to a blind wait and 30 to fixed sleeps.) - **Wait discipline: never park the conversation past the prompt-cache window.** Anything expected to run longer than about 2 minutes — a gate round over several pages, a crawl, a batch push, a capture set, a delegated agent — runs in the background and writes a progress or summary file; the coordinator never runs it in the foreground and never covers it with one long `sleep`. While it runs, do independent work; when there is none, check back with one short read of the progress file **at most every 4 minutes** — never a fixed `sleep` of 5 minutes or more, and never a blocking "wait for the agent's output" call with a long timeout. The number is not taste: the prompt cache expires after 5 idle minutes, and at the 500–900k-token contexts a migration reaches, every expiry re-writes the whole prefix at write price (12× a cached read). Field data, 48 sessions: a foreground wait of ≤ 4 minutes missed the cache in ~10 % of cases, ≥ 5 minutes in 85–87 %; 572 such agent-side waits re-wrote 325 M tokens — 46 % of everything those sessions wrote to the cache. Ending the turn to wait for a completion notification helps the user, not the cache: a notification that arrives after 5 minutes misses too (137 recorded), so prefer short checks for waits under ~45 minutes and end the turn only when the wait is longer or the user should decide. (Claude Code: `run_in_background: true` on the shell call, the harness posts a task notification when it exits; `promptCacheTtl: "1h"` in settings.json stretches the window to an hour at 1.6× write price — an owner setting, worth it for any multi-hour session.) - **Commit at the end of each phase** when the project is a git repo. Before the FIRST such commit, re-run Setup step 6 — the first commit lands at the end of the audit phase, long before deploy's SKILL.md is read, and a tracked `.env` poisons every later push (GH013 + 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`. **Write boundary.** Stardust writes to `stardust/`, the impeccable target files at the project root, and the EDS project (only via `deploy`, `rollout`, `dynamics`). Run-only files — logs, harness page, pre-renders, script copies, drafts — go under `stardust/.work/<skill>/`; the root `scripts/` and `qa/` are not stardust's. Anything written elsewhere is a bug in that skill. **Versioning.** Everything under `stardust/` is committed except what `reference/stardust.gitignore` lists: screenshots, four heavy folders (`current/assets/`, `replica/gates/`, `migrated/assets/`, `rollout/qa/`), `.work/`, run residue, session state. Per-directory table and what a clone without `current/assets/` can and cannot do: `reference/artifact-map.md`