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.

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, 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=<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).

• 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:

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.
• ../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>:

• ../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.