prototype

# stardust:prototype For each `directed` page, render a **proposed redesign** as a self-contained static HTML file at `stardust/prototypes/<slug>-proposed.html`. Open the file in the browser; iterate via chat-driven impeccable commands ("make the hero bolder", "tighten the cup-note grid"). Mark `approved` once the user signs off in the conversation. `prototype` is not a renderer of its own design — it composes the target spec written by `direct` (`PRODUCT.md`, `DESIGN.md`, `DESIGN.json`, `stardust/direction.md`) onto the page content captured by `extract` (`stardust/current/pages/<slug>.json`). Visual creativity is delegated to `$impeccable craft` and the iteration commands (`bolder`, `quieter`, `distill`, `polish`, `colorize`, `typeset`, `layout`, `adapt`, `animate`, `delight`, `overdrive`, `impeccable`). ## Inputs - `<slug>` — optional positional. Prototype just this page. Without it, prototype every `directed` page that is not `stale`. - `--all` — prototype every `directed` page including stale ones. - `--prep` — optional. Run in **migrate-prep mode**: fill page-type gaps (prototype one representative archetype per type) and, on approval, write canon back to `stardust/canon/` and `DESIGN.json.extensions.canon`. See § Prep mode below and `reference/canon-extraction.md`. Typically invoked via the `prepare-migration` orchestrator. - `--canon-from <slug>` — optional. Override the default canon- author (which is the first approved prototype, typically `home`). Used when a different page should establish the design canon. - `--publish-sample <slug>` — submit the named slug to the stardust showcase. Triggers the publish-sample sub-flow documented in `reference/publish-sample.md`: eligibility checks, file staging, PR creation against the upstream stardust repo. Requires `gh` installed and authenticated. The showcase is a visual demonstration, not a deployable site — placeholder content is allowed and recorded in the PR body's § Unsourced content section. Design-quality gates stay strict: refuses on unjustified anti-toolbox hits, `:root` token contract failure, data-attributes contract failure, or impeccable hard-rule violations. P0/P1 critique findings warn but don't refuse. The showcase publishes via GitHub Pages on merge. - `--cinematic` — optional. Layer a cinematic motion register on top of the static prototype. The register is read from `DESIGN.json.extensions.motion.register` (written by `direct`); if absent, the prototype phase picks one using the same heuristic per `reference/motion-registers.md` § Selection heuristic. Output filename is `<slug>-cinematic.html` (alongside the static `<slug>-proposed.html`, never replacing it). Triggers the cinematic gates in motion validation (`reference/motion-validation.md` § Pass 6). - `--cinematic=<register>` — optional. Same as `--cinematic` but forces a specific register (`arrival`, `kinetic-display`, `live-systems`, `editorial`, `kinetic-grid`). The override is recorded in `_provenance.motion.registerSource = "user-override"` so reviewers can spot when direction's heuristic was bypassed. ### No opt-outs `prototype` does not carry `--no-*` or `--skip-*` flags. The quality gates (critique, audit, mobile-adapt audit, anti-toolbox audit, content-sourcing scan) are the product — they're not optional. If a gate refuses a file, the remediation is to fix the file or override the gate by editing the file directly, not to pass a flag that silently lowers the bar. Manual chat overrides ("ship as-is", "accept the P1 findings") are still available; the agent records the override verbatim in `_provenance` so downstream consumers see the explicit acknowledgement. ## Setup 0. **Playwright re-probe (mandatory first step).** `--no-save` playwright installs from earlier phases are pruned by any later real `npm i` (extract SKILL.md § Setup → `--no-save` installs are ephemeral). Before any rendering step, probe `node -e "import('playwright').then(()=>process.exit(0))"` from the project root and re-install (`npm i -D playwright --no-save --legacy-peer-deps`) on failure. 1. Run the master skill's setup (`skills/stardust/SKILL.md` § Setup). 2. Verify `stardust/state.json` exists and contains at least one `directed` page. If not, recommend `$stardust direct` and stop. 3. Verify the project-root `DESIGN.md` and `DESIGN.json` exist. If not, the direction was not fully authored — recommend `$stardust direct` and stop. 4. Verify `stardust/direction.md` has an active (not pending) direction. Pending directions block prototype. 5. **Validate provenance on every page in scope.** Call `validateProvenance(page)` per `skills/stardust/reference/state-machine.md` § Provenance validation for every page that this run will render (the single `<slug>` argument when present, otherwise every non-stale `directed`/`prototyped`/`approved` page). Abort with the helper's error when any page lacks live-render evidence — re-running `prototype` against a synthesized page record silently propagates the synthesis into the rendered prototype. Surface `Provenance OK on N pages` once the check passes. 6. Read `stardust/current/DESIGN.md` (the descriptive snapshot of the existing site, used as a fallback reference during render when the proposed file needs to mirror an aspect of the captured surface). ## Delegation mechanic `prototype` does **not** author `<slug>-proposed.html` directly. The heavy creative lift is delegated to `$impeccable craft`, and (when needed) the structural plan to `$impeccable shape`. Spelling out the mechanic matters because the carve-out documented in `skills/stardust/reference/artifact-map.md` (where stardust authors `PRODUCT.md`, `DESIGN.md`, `DESIGN.json`, `current/PRODUCT.md`, `current/DESIGN.md` directly, treating impeccable's references as *format specs*, not runtime commands) is **load-bearing for those five files only**. It does NOT extend to: - `stardust/prototypes/<slug>-proposed.html` — must be authored by `$impeccable craft`, not by stardust direct authoring. - Iteration on the proposed file — must be driven through a chat-driven invocation of an explicit impeccable command (per the iteration paths section). - Structural planning when a page is complex enough to need it — `$impeccable shape`. The proximate cause of past content fabrication was the agent over-generalizing the direct-authoring carve-out to the proposed HTML. Don't. ### Invoking impeccable Impeccable is a skill, not a CLI. Invoke it through the harness's skill-invocation tool, passing the sub-command and its args as the skill's argument string, mirroring the slash-command form. In Claude Code the plugin namespaces it as `impeccable:impeccable`: ``` Skill { skill: "impeccable:impeccable", args: "craft <feature-description>" } ``` In GitHub Copilot and other harnesses that flatten plugin skills the skill is named `impeccable` and takes the same argument string (`craft <feature-description>`). Every Claude Code `Skill { ... }` example in this skill translates the same way. Sub-commands referenced from this skill are all routed through the same skill: `craft`, `shape`, plus the iteration commands (`bolder`, `quieter`, `distill`, `polish`, `colorize`, `typeset`, `layout`, `adapt`, `animate`, `delight`, `overdrive`, `impeccable`). When impeccable is **not** available (CLI-only environments, plugin uninstalled, sandbox without skill access), stop and tell the user impeccable is required for prototype rendering. Recommend installing the impeccable plugin. Do not fall back to direct authoring of `<slug>-proposed.html` — the validation contract craft enforces (anti-toolbox audit, divergence rules, type ratios, content sourcing hierarchy) is not reproducible by direct authoring, and falling back silently ships unverified output. Stardust's job inside Phase 2 is therefore: - Compose the inputs craft needs (page content from `current/pages/<slug>.json`, target spec from `DESIGN.md` / `DESIGN.json`, hard constraints from `direction.md`, content sourcing rules from `reference/proposed-file-shell.md` § Content sourcing hierarchy). - Invoke craft through the skill-invocation tool. - Validate the result against the contract (`:root` block, data attributes, divergence audit, impeccable hard rules, content sourcing). If validation fails, refuse to write — never paper over craft output the agent thinks is "close enough." The proposed file is whatever craft writes plus the validation report; it is not stardust's authored artifact. ## Procedure ### Phase 1 — Plan the prototype (page-shape brief) For each page in scope: 1. Read `stardust/current/pages/<slug>.json` for the page's structure and content. 2. Read `stardust/current/_brand-extraction.json` for system components and cross-promo data (the page's site-wide repeated surfaces). 3. Read `stardust/direction.md` Active section for the resolved direction, divergence inputs, and command sequence. 4. Read project-root `DESIGN.md` + `DESIGN.json` for the target site system — tokens, abstract component vocabulary, named system-component roles. The site system tells the agent *what the design language is*; this Phase decides *how it deploys to this specific page*. 5. **Author `stardust/prototypes/<slug>-shape.md`** — the per-page compositional brief. Format spec: `reference/page-shape-brief.md`. The brief carries the section list, layout strategy, key states, interaction model, structural data attributes, and the unsourced-content list (bridge to the placeholder contract). Author directly — no interview, no impeccable invocation; this is stardust's reasoning about how the system deploys to this page given this content. 6. Show the brief to the user and wait for confirmation before moving to Phase 2. The user can edit the brief in place (rearrange sections, kill open questions, change composition decisions); re-rendering Phase 2 will rebuild the proposed file from the edited brief. **Hands-off compliance.** When `state.json.handsOff` is true, the shape brief is still authored and validated but the user-confirmation wait is skipped — the brief is its own record. Approval (Phase 5) under hands-off follows the mode's contract defined in `skills/stardust/SKILL.md` § Hands-off mode. `$impeccable shape` is **not** invoked in v0.2 (see `reference/page-shape-brief.md` § Authoring procedure for the rationale; revisit if per-page hand-authoring proves insufficient across sites). The brief decouples site-level concerns (in DESIGN.md) from page-level deployment (per-page brief). A direction change invalidates the system; existing briefs are content-aware-stale only when the system change makes their composition impossible. This recalibration of stale-flagging is documented in `skills/stardust/reference/state-machine.md` § Stale flagging. #### Brief-time disciplines (validator-enforced) Five disciplines fire when the brief is authored. The brief validator rejects briefs missing any of them; failure surfaces the specific rule violated and stops Phase 1 before Phase 2 renders anything. The disciplines exist to prevent the AI-slop failure mode where a brief with only `(DESIGN tokens) + (captured content)` as input produces template-shaped output regardless of brand. **Discipline 1 — Captured-source lineage per section.** Every section in `## Sections` declares its captured-source origin. Forms: - *"subscription-card-on-bay (consolidates captured banner 2 + dual-card right of `pages/home.json#landmarks[hero]`)"* — derived from one or more captured surfaces - *"site-wide system-component (carried from `_brand-extraction.json #systemComponents[kind=footer]`)"* — chrome inherited from the brand-surface - *"direction-authorized new"* — composed against direction.md, not derived from a captured source (require a one-line note naming which direction movement justifies the new section) Sections without lineage are rejected. The lineage list lives in `_provenance.capturedSourceLineage` in the brief and propagates to the rendered file. **Discipline 2 — Anti-template pass.** For each captured component pattern the page deploys (cards / banners / search rows / CTA bands / hero composition), the brief considers 2–3 layout alternatives and picks the most differentiated. Curated default-patterns-to-escape flags reflex picks: - hero-then-bands silhouette (the universal AI silhouette) - 5-up image-card grid as category nav - nav-icon glyphs (search / cart / account) in a typographic register - centered-stack hero with two-button CTA pair - captured-shape mirror-translated into new tokens The brief justifies any reach for a default-pattern with a captured-source citation that makes the pattern brand-appropriate (e.g., *"5-up grid preserved because the captured site's grid IS the brand's signature catalogue shape; the alternative consideration was a vertical ledger which the brand register rejects"*). The alternatives SHOULD be reference-grounded when reference research is available (per `skills/stardust/reference/reference-research.md`): an alternative cites a real reference screen in the entry's `reference?` field using that file's evidence shape. Taste-only alternatives remain valid when research is unavailable. The audit lives in `_provenance.antiTemplatePass[]` with one entry per captured pattern: `{ pattern, defaultReflex, alternatives[], picked, rationale, reference? }`. **Discipline 3 — Surprise budget.** The brief declares a `surprise` field with one of: `low | medium | high`. Moves come from the bank of non-template moves — see `skills/stardust/reference/divergence-toolkit.md` § Non-template move bank, with worked examples in `reference/anti-template-bank.md` — or an evidence-shaped extension per the bank's § Extension rule. Tier semantics: - `low` — brand-faithful + improvements only. Variant A's role under reimagined; all of A1/A2/A3 under verbatim. - `medium` (default for B variants under reimagined) — one captured cliché replaced by one move from the bank. - `high` (default for C variants under reimagined) — two clichés replaced + one document-shape substitution. Under `ia-fidelity: verbatim` (per `skills/stardust/reference/intent-dimensions.md` § 9), the per-page surprise budget is **capped at `low` site-wide**. The validator refuses any verbatim-direction brief with `surprise: medium` or `high`. **`low` ≠ generic.** The budget bounds *added* divergence, not craft or fidelity. `low` means **brand-faithful + improvements + full signature preservation**, NOT "the most obvious faithful interpretation." The recurring failure mode (a fintech migration) is the agent reading `low` / `verbatim` as license to strip the page to a plain type-hero on a flat ground — the result is faithful but forgettable and under-sells the redesign. Hold the craft bar at `low`: keep the brand's distinctive elements, apply the improvements list, and reproduce the signature. **Signature preservation is mandatory and budget-exempt.** When the captured page has a signature hero medium (background video / canvas / WebGL / Lottie), signature motion (scroll / parallax / kinetic), or a signature visual motif (per `intent-dimensions.md` § 8b), the brief **must** reproduce it — with a static fallback, `prefers-reduced- motion` alternative, and (for overlaid text) a legibility scrim. This does **not** consume the `low` allowance: carrying the brand's own signature forward is fidelity, not divergence (§ 8b § Surprise-budget exemption). Record the kept signatures in `_provenance.signatureElements[]` as `{ kind, capturedSource, mechanism, fallback }`. **Render-refusal:** a brief that flattens a captured video/canvas/animation hero to a still, gradient, or type-only hero — or drops a site-wide motif — is rejected at the shape-brief audit; reproduce the signature instead. **Type-scale yield clause.** When a tier-`medium`-or-higher variant's captured-trait amplification structurally conflicts with a brand-level type-scale rule from `DESIGN.md` (e.g. a "Names-At-Headline-Scale" rule, or any other named type-scale floor / ceiling), the brand-level rule may yield per-page. The yield must be cited in `_provenance.surpriseTier_typeScaleYields[]` with: `{ rule, variantDominantDimension, capturedTraitAmplified, yieldedTo, rationale }`. The brand-level yield clause itself (the named exception in `DESIGN.md`) is project-side, not spec-side; the spec only requires the per-page citation when the yield fires. See § Friction carve-out #4 below. **Discipline 4 — Substrate transitions are deliberate, named, and rare.** Default: single substrate across the page. Each substrate exception requires a named purpose in the brief (*"highlights the featured-coffee promotional moment"*). **More than two substrate transitions per page fails the brief.** The transitions live in `_provenance.substrateTransitions` as `{ default, exceptions[] }`. **Exception — substrate-keyed document-shapes (friction carve-out #2).** When the variant's `surprise: high` move is a substrate-keyed document-shape (zine, catalog-card, poster-sequence), the per-section substrate IS the document-shape's structural rhythm. The ≤ 2-transition cap does not apply; each section's substrate must instead carry a **per-section captured-source citation** (typically a per-SKU label color, a per-page brand color, or a per-content-type ground convention from the captured site). The exception is recorded in `_provenance.substrateTransitions.note` with the document-shape named and the citation source. The validator accepts > 2 transitions when: 1. `surprise: high` is declared, AND 2. the picked move from the bank is `document-shape` with a substrate-keyed sub-kind (zine / catalog-card / poster-sequence), AND 3. every transition in `exceptions[]` carries a per-section captured-source citation. If any of the three conditions fails, the cap re-engages. **Discipline 5 — Heading hierarchy + voice classification tracked per section.** The brief requires: - H1 declared once per page; subsequent sections H2; H3 children. - Every literal value in copy classified as one of: `captured-verbatim`, `direction-authorized rewrite`, or `placeholder`. No section ships with copy without a classification. The classification list lives in `_provenance.voiceClassification[]` as `{ section, classification, copy?, source? }` and propagates to the rendered file. **Placeholder-ribbon labels (friction carve-out #3).** System- component honesty-signal labels (placeholder ribbons, "TBD" badges, "from the brand team at migrate" markers) are **direction-authorized