stardust

What this skill does

# 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.

## 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 is `distill`, `extract`, `direct`, `prototype`,
  `migrate`, or `uplift`.** Delegate to the matching sub-command
  (`stardust:<name>` skill). Pass remaining args through.
  - `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.**

## 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, sample distillation
artifacts, 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.
- Force a re-run on stale pages without explicit user opt-in.
- Crawl an existing site beyond the user