
stardust
Redesign an existing website to make it better. Higher-level guided flow on top of impeccable.
- version
- 0.39.4
- GitHub stars
- 332
Install
/plugin install stardust@adobe-skillsRun it inside Claude Code after adding the marketplace with /plugin marketplace add adobe/skills.
Contents
Discovered from sourceSkills 16
stardust:audit
One URL in. One scored, evidence-bound audit out.
audit looks at an existing website from three perspectives — design
(brand tensions + concrete improvement opportunities), SEO/technical,
and LLM/AI-search visibility — measures Core Web Vitals, and
synthesizes everything into a seven-dimension scorecard plus a
prioritized findings ledger that tells the owner what to improve to
generate a better business outcome. The report is also the natural
seed for a redesign: its findings feed the stardust uplift skill's
improvements list and the stardust direct skill's Phase 2.5, and it closes
with uplift-shaped redesign directions so "run $stardust uplift" is
the obvious next step.
Opinionated defaults
- Multi-page by default —
$stardust extract <url> --cap 8(home + seven IA pillars) unless--singleor--pagesoverrides. - Non-interactive — the audit never asks questions. Every
assumption it makes instead is recorded in
audit.json#assumptionsand stated in the report's executive summary. - Evidence-bound — every claim cites a measurement, a
T-*tension id, a check result, or a screenshot observation. A claim with no citation does not ship. - No fabricated data — a measurement that could not be taken is
reported as
not measured (<reason>), never estimated silently. An estimate, where reasoned, is labeled as one with its basis. - Graceful degradation, not failure — optional capabilities (refero, marketing-skills, modern-web-guidance, PageSpeed Insights) are probed once and their absence is recorded, never fatal. See § Degradation ladder.
Inputs
<url>— required. The site to audit. A path narrows the crawl to that subtree (extract's semantics).--pages <n>— optional. Override the default 8-page extraction cap (passed through as--cap <n>).--single— optional. One-page audit of the given URL only. The cross-page checks (duplicate titles, sitemap coverage, CTA fragmentation across pages) then run on a single page and say so.--deploy— optional. After the report renders, publishreport.htmlas a single self-contained page via the DA transport (../deploy/da-deploy-protocol.md: source PUT → preview → live) and print the delivered URL. Transport only — the report never goes through deploy's section→block conversion, which would decompose the self-contained file.--benchmark— optional. Force Phase 5 reference benchmarking: probe the refero MCP even when the earlier capability probe was slow or ambiguous. Without this flag Phase 5 fires only when the probe succeeds quickly.
There are no other flags. Everything else is derived from the captured surface or governed by the underlying skills' contracts.
Phase 0 — Setup
- Run the master skill's setup (
../stardust/SKILL.md§ Setup) — with one audit-specific carve-out: impeccable absence is a degradation here, not the master setup's hard stop. When the dep check fails, recordimpeccable: unavailableinaudit.json#degradationsand continue — Phase 2 runs without the critique/audit arms (VISION pass + accessibility fold-in still fire) and Phase 6 skips the report render; the run ends at stop condition (b) afteraudit.jsonis written. - Extraction freshness check. If
stardust/current/holds an extraction of the same origin less than 7 days old — origin fromstardust/state.json(the site record extract stamped), recency from the newestpages/<slug>.json#_provenance.fetchedAt— reuse it and recordsite.extraction.reused: true. Otherwise invoke$stardust extract <url> --cap 8(or--single/--pages <n>per the inputs). Extract owns the crawl, the screenshots,_brand-extraction.json,pages/<slug>.json,PRODUCT.md/DESIGN.md, andbrand-review.htmlwith its Tensions section. - Probe optional capabilities once, recording each outcome in
the degradation record (
audit.json#degradations):marketing-skillsplugin (seo-audit,ai-seoskills present?)modern-web-guidance(npx -y modern-web-guidance@latest search "<query>"responds?)- refero MCP (attempt
mcp__refero__refero_search_styles; treat a tool-not-found or timeout as unavailable) - PageSpeed Insights API (network-reachable without a key?)
- rollout project (
stardust/rollout/rollout.jsonpresent?)
If extract fails entirely (site unreachable, bot-management block past the headed-Chrome fallback), stop and surface extract's error verbatim — there is nothing to audit. This is the only hard stop before synthesis; see § Stop conditions.
Procedure
Phase 1 — Brand surface & tension analysis
Read stardust/current/_brand-extraction.json and
stardust/current/brand-review.html § Tensions surfaced (rule
catalog in ../extract/reference/brand-review-template.md
§ Tensions). Every fired T-* tension is candidate evidence for a
finding — carry the ids forward, do not re-derive the detections.
Compute the four brand-expression measurements the report needs.
Each lands in audit.json#measurements with status + method per
reference/report-format.md:
brandColorShare— brand-color share of painted pixels on the captured home screenshot. Preferred method: Playwright pixel sampling (method: "pixel-sample") — load the screenshot, sample a grid (e.g. every 8th pixel), classify each sample to the nearest palette entry within a tolerance, and divide brand-hue samples by painted (non-white/near-white) samples. When sampling is infeasible in the session, a reasoned estimate from the captured surfaces is allowed but must ship asmethod: "surface-estimate"with its basis — never presented as measured.ctaFragmentation— distinct CTA labels per equivalence bucket, aggregated frompages/*.json#ctas[].label(the same buckets that driveT-cta-vocab).typeScale— distinct heading sizes and scale kind/ratio from_brand-extraction.json#type.scaleAudit.radiusSprawl— distinct border-radius values with occurrence counts from_brand-extraction.json#motifs.borderRadius.
Phase 2 — Design & experience critique
Three passes over the captured home page (screenshot + live URL), folded into one set of design findings:
- impeccable critique + audit. Invoke impeccable through the
harness's skill-invocation tool using the delegation mechanic in
../prototype/SKILL.md§ Invoking impeccable (Claude Code form:Skill { skill: "impeccable:impeccable", args: "critique <target>" }, then"audit <target>"for the accessibility / responsive / performance passes). Normalize its findings into the audit's finding shape. - VISION pass. Study the captured screenshots directly
(
stardust/current/assets/screenshots/<slug>.png) and name what a design director would: dated patterns the field has moved past, hierarchy failures, missed opportunities the captured surface doesn't capitalize on. The claim discipline is absolute — every observation cites a measurement, a tension id, or a screenshot region ("home.png, hero: three equal-weight CTAs compete"). Adjectives without evidence do not become findings. - Accessibility fold-in. Contrast computed (WCAG ratios for the
captured palette pairs in the roles they are actually used in),
alt coverage from
pages/*.json#media.images, landmark presence and heading order frompages/*.json#landmarks, content-free link labels (reuseT-link-content-freewhen fired).
Phase 3 — SEO & technical
When the marketing-skills plugin is installed, follow
marketing-skills:seo-audit's methodology and normalize its
issue/impact/evidence/fix items into findings. When absent, run the
checks directly — they are all curl/Playwright-derivable:
| area | checks | method |
|---|---|---|
| Crawlability | robots.txt present and sane; sitemap declared and valid XML | curl |
| Indexation | canonical present and self-referential; meta robots not accidentally noindex; http→https single-hop redirect; redirect chains | curl -I |
| Semantics | main/nav/footer landmarks; single <h1>; heading hierarchy without skips | pages/*.json + Playwright |
| Metadata | title/description presence + quality per page; duplicates across pages; Open Graph completeness | pages/*.json#metadata |
| Structured data | JSON-LD presence, parse validity, entity types vs page type | Playwright / curl |
Where a failure matches a rollout:baseline check id
(../rollout/reference/checks.md: single-h1, title-missing,
meta-description, canonical, sitemap, jsonld, img-alt,
landmark-main, duplicate-title), reuse that id as the
finding's evidence.ref (check:<id>) — findings recorded into a
rollout ledger under a known id get picked up by the AEM autofix
registry automatically.
Core Web Vitals. Measure LCP / CLS / TBT via Playwright
performance APIs (PerformanceObserver for
largest-contentful-paint and layout-shift, longtask entries for
TBT) on two viewports: mobile (375×667, CPU throttled where the
session supports it) and desktop (1440×900). When the PageSpeed
Insights API is network-reachable without a key, prefer it and record
method: "psi-api" (it adds field INP); otherwise record
method: "playwright-lab" and say in the measurement note that lab
TBT is a proxy for INP. Classify every metric against the Google
thresholds tabled in reference/scoring.md § performance.
Remediation guidance. When modern-web-guidance is installed,
run npx -y modern-web-guidance@latest search "<specific failure>"
for each distinct failure class and cite the returned guide ids in
the finding's guides[]. When absent, write the generic remediation
and leave guides: [].
Phase 4 — LLM visibility
When marketing-skills:ai-seo is installed, follow its methodology.
When absent, assess directly:
llms.txt— present at the origin root?- Answerability — does each audited page answer the question a user would ask of it ("what does this cost", "what is this") in extractable, well-structured prose — and how early on the page?
- schema.org coverage — do the JSON-LD entities cover the organization plus the page-type entities an answer engine needs for entity understanding?
- Heading-as-question coverage — what share of
h2/h3map to askable questions or scannable topics rather than slogans? - Content depth — extractable prose word counts on key pages; specific, citable claims vs thin marketing copy.
- Key facts in crawlable text — are pricing, what-it-is, and who-it's-for stated in crawlable text, or locked in images and JS-rendered widgets?
- Citation readability, measured — run
skills/deploy/scripts/ai-readability.mjs --origin <site> <sampled paths>and report the strict score per page with the top blocks adding rendered-only words; it is the exact formula of Adobe's AI Content Visibility Checker (deploy/reference/ai-readability.md).
Every Phase 4 finding names the concrete fix ("state the three price points in the pricing table as text; they currently render only inside the plan-card images"), not a category ("improve content").
Phase 5 — Reference benchmarking (optional)
Fires when the refero MCP tools are reachable — the Phase 0 probe
attempted mcp__refero__refero_search_styles; --benchmark forces a
re-probe. Skip gracefully when unavailable
(benchmarks: { status: "skipped", reason: … }).
When available: retrieve 2–3 same-vertical reference styles, compare
the audited site's brand expression (Phase 1 measurements) against
what best-in-class in the category does, and cite each reference —
title, URL, one line on what they do better — in the relevant design
findings and in audit.json#benchmarks.references.
Phase 6 — Synthesis & report
-
Scorecard. Score the seven dimensions per
reference/scoring.md— anchors first, evidence floor enforced, not-measured dimensions nulled and renormalized. Compute the weighted overall. -
Findings. Consolidate Phases 1–5 into the prioritized ledger: P1 (actively losing business or excluding users) / P2 (material drag) / P3 (polish). Per finding:
dimension,evidence(measurement / tension / screenshot / check / benchmark citation),businessImpactone-liner, concretefix,guides[]. -
Uplift directions. Close with 2–3 redesign directions framed exactly like uplift's variant role contract (
../uplift/SKILL.md§ The three-variant role contract): A faithful + fixes (names the findings it resolves), B one captured-but-underused trait amplified, C cinematic (motion as identity, register suggested per../prototype/reference/motion-registers.md§ Selection heuristic). Drop B when the captured surface can't support a differentiated middle — two strong directions beat three weak ones. -
Write
stardust/audit/<domain-slug>/audit.json— schema, slug convention, and measurement rules inreference/report-format.mdPart 1. Provenance_provenancefirst key. -
Render
stardust/audit/<domain-slug>/report.htmlby delegating to$impeccable craftwith the brief inreference/report-format.mdPart 2 — the same skill-invocation mechanic as prototype, and the same rule: never hand-template the report. Run the post-render validation checklist; on failure re-invoke craft with the specific violation. Open the result withopen stardust/audit/<domain-slug>/report.html. -
Ledger recording (rollout projects only). When
stardust/rollout/rollout.jsonexists, record each finding into the delivery ledger vianode skills/rollout/scripts/findings.mjs recordwith source namespaceaudit:—--source audit:<dimension>,--layerfrom the mapping below, severity carried through,--fixabilitynormalized per../rollout/reference/audit-sources.md§ Recording an external finding. Write each returned id into the finding'sledgerId.audit dimension ledger layer brand-expressionbrand-tensionsvisual-hierarchy-craftdesign-uxconversion-focuscontent-conversionaccessibilityaccessibilitytechnical-seoseo(site-wide:cross-page)content-llm-visibilityai-searchperformanceseo -
--deploy. When passed, publishreport.htmlvia the DA transport per../deploy/da-deploy-protocol.md— PUT the file as a single source, POST preview, POST live, verify the delivered URL returns 200 — and print the delivered URL. Transport only; never run deploy's section→block conversion on the report. -
Chat summary. Short — the work is on disk and openable:
audit complete — <url> Site health: <overall>/100 <dimension>: <score> × 7 (not-measured dimensions listed with reasons) Findings: <n> P1 · <n> P2 · <n> P3 Top lever: <the single highest-impact P1, one line> Report: stardust/audit/<domain-slug>/report.html Data: stardust/audit/<domain-slug>/audit.json Next: run `$stardust uplift <url>` — the report's closing directions are its variant briefs.
Degradation ladder
Probed once in Phase 0; every degradation is recorded in
audit.json#degradations and rendered in the report's methodology
appendix. None of these stops the audit.
| capability absent | behavior |
|---|---|
| refero MCP | skip Phase 5; benchmarks.status: "skipped" with reason |
| marketing-skills | run the Phase 3 / Phase 4 checks directly (tabled above) |
| modern-web-guidance | generic remediation text; guides: [] |
| PageSpeed Insights | Playwright-only lab metrics; measurement note says lab TBT proxies INP |
| Playwright pixel sampling infeasible | brandColorShare ships as method: "surface-estimate" with basis |
| rollout project | no ledger recording; ledgerId: null on every finding |
Hard constraints
- No fabricated data. A measurement that could not be taken is
not measured (<reason>)in both artifacts. Estimates are labeled with method + basis. This is the same discipline extract enforces against synthesis (../extract/SKILL.md§ Failure modes) — fabricated audit numbers are worse than missing ones because they are actionable-looking and wrong. - Evidence discipline. Every finding cites observable evidence:
a measurement key, a
T-*tension id, a screenshot region, a check id, or a benchmark URL. Uncited claims are cut in synthesis. - Report is craft-rendered.
report.htmlis authored by$impeccable craftagainst the brief inreference/report-format.md, validated afterward — never hand-templated, never hand-patched. - Provenance is mandatory on both artifacts, per
../stardust/reference/artifact-map.md§ Provenance shapes. - Non-interactive. No questions in normal flow; assumptions are stated in the report. The only stops are the two below.
- Audit does not fix. Fixes belong to
uplift(page redesign),directPhase 2.5 (improvements list), and rollout's optimize loop (platform autofix). Audit names the fix; it never edits the site.
Stop conditions
Stop and surface only if:
(a) Extract fails entirely — site unreachable, structure
unparseable, bot-management block past the headed-Chrome
fallback. Surface extract's error verbatim; nothing to audit.
(b) impeccable unavailable — Phase 2's critique/audit arms and
Phase 6's report render require it. Per the Phase 0 carve-out,
the run continues in degraded mode (VISION pass, SEO/technical,
LLM visibility, benchmarks all still fire) and writes
audit.json; then stop and tell the user the designed report
needs the impeccable plugin — deliver the data, not a
hand-templated substitute.
Everything else degrades per the ladder; the audit never stops for confirmation in normal flow.
Outputs
stardust/
├── current/ ← from extract (reused when <7 days old)
│ ├── _brand-extraction.json
│ ├── brand-review.html ← Tensions section = Phase 1 input
│ ├── pages/<slug>.json
│ └── assets/screenshots/<slug>.png ← VISION-pass + report evidence figures
└── audit/
└── <domain-slug>/ ← hostname, www-stripped, dots → dashes
├── audit.json ← scorecard, measurements, findings[], provenance
└── report.html ← craft-rendered, self-contained
stardust/rollout/optimize/findings.json ← appended via findings.mjs (rollout projects only)
Audit writes no state.json entries — extraction state belongs to
extract; audit's own artifacts are self-describing via provenance.
Re-running audit against a fresh extraction overwrites
stardust/audit/<domain-slug>/; ledger recordings dedupe by the
ledger's own id hash.
Scope
- Audits and prescribes; never modifies the site or its redesign artifacts.
- One origin per run. Auditing a competitor set is N runs.
- The natural continuations:
$stardust uplift <url>(the closing directions are its variant briefs), the stardustdirectskill (findings feed the Phase 2.5 improvements list), rollout's optimize loop (ledger findings with known check ids autofix on AEM).
References
reference/scoring.md— the seven dimensions, weights, observable anchors at 40/70/90, scoring procedure.reference/report-format.md—audit.jsonschema (Part 1) and thereport.htmlcraft brief + post-render validation (Part 2).../extract/SKILL.md— crawl, capture, brand-surface extraction; § Failure modes for the anti-synthesis discipline.../extract/reference/brand-review-template.md§ Tensions — theT-*detector catalog Phase 1 carries forward.../prototype/SKILL.md§ Invoking impeccable — the skill-invocation delegation mechanic reused for critique (Phase 2) and the report render (Phase 6).../rollout/reference/audit-sources.md— the findings-ledger normalization rules (severity, fixability) Phase 6 applies.../rollout/reference/checks.md— baseline check ids to reuse so AEM autofix picks the findings up.../rollout/scripts/findings.mjs— the ledger writer (record).../uplift/SKILL.md§ The three-variant role contract — the frame for the closing uplift directions.../prototype/reference/motion-registers.md§ Selection heuristic — register suggestion for direction C.../direct/SKILL.md§ Phase 2.5 — the improvements list audit findings feed on a subsequent redesign.../deploy/da-deploy-protocol.md— the DA transport behind--deploy(source PUT → preview → live; no block conversion).../stardust/SKILL.md§ Setup — master-skill setup run in Phase 0.../stardust/reference/artifact-map.md— provenance shapes.
stardust:deploy — prototypes → EDS/AEM
This file is the outline. The text of each section below is in skills/deploy/reference/, in the file the section names. Read that file in full when you reach the section; never work from a heading alone. A numbered rule that another file cites as #N is in one of those files: search skills/deploy/ for #N.
When to use
The user has:
- Per-page styled HTML prototypes — one file per page, each carrying its own CSS. Accept any of these shapes:
- Single-file with inline
<style>and:roottokens + semantic<section class="…">(e.g. stardust output, or claude-design "Stardust"/Mobirise/Relume-style pages). Easiest — convert directly. - External per-page
.css(the<style>lives in a sibling stylesheet). Read the linked CSS the same way you'd read an inline<style>. <x-dc>document-content with everything inline-styled (per-elementstyle="…"). Harder — you must lift inline styles into a scoped block stylesheet.- React/JSX prototypes (an HTML shell that mounts
.jsxcomponents at runtime). Pre-render to static HTML first (run it, or screenshot + read the JSX to reconstruct the DOM); you cannot decorate a shell that has no server-rendered<main>. The prototypes typically live understardust/prototypes/**or asamples/<Name>/folder — don't hard-code the path; discover them.
- Single-file with inline
- An EDS project at the repo root — vanilla
aem-boilerplate(github.com/adobe/aem-boilerplate):scripts/aem.js+scripts/scripts.js,blocks/withheader/footer/fragment,styles/styles.css+styles/fonts.css,head.html. This is the ONLY runtime this skill targets — no runtime files are ever ported, vendored, or edited. - A goal to convert: prototypes → authorable EDS blocks + EDS content pages under
content/**.
If the user has prototypes but no EDS scaffolding, stop and ask whether to scaffold from adobe/aem-boilerplate (use the template as-is; the conversion never modifies scripts/aem.js). If they have EDS but no prototypes, this skill doesn't apply.
Flow guard (stardust projects). When stardust/state.json exists but has no flow and the ask is a migration (a URL plus "migrate" / "to EDS" / "re-platform"), stop before Step 1: print the master skill's two-flow table (skills/stardust/SKILL.md § Two migration flows) and hand back to its routing, which stamps flow (skills/stardust/reference/state-machine.md § Flow keys). Hand-authored prototypes with no state.json are unaffected — that is this skill's standalone use.
Target runtime — vanilla aem-boilerplate (what the generated code can rely on)
Read skills/deploy/reference/target-runtime.md in full before you act on this section.
Playwright re-probe (run before anything that renders)
Read skills/deploy/reference/target-runtime.md in full before you act on this section.
Runtime-detection probe (run before Step 1 — write stardust/runtime-contract.json)
Read skills/deploy/reference/target-runtime.md in full before you act on this section.
Deploy (DA Source API, from a local agent)
Read skills/deploy/reference/da-source-api.md in full before you act on this section.
The one rule that drives everything else
One distinct visual PATTERN = one EDS block — and a section with NO pattern is NOT a block at all. The content structure that lands in DA must follow David's Model (davids-model.md, bundled with this skill — the 15 rules mapped to this skill's contracts; cited as D#N throughout). Its first rule shapes everything here:
- D1 — blocks aren't ideal for authoring. A block is a table an author must maintain. A section whose content is plain prose — heading, paragraphs, an image, CTAs, with no repeating units and no bespoke interactive structure — is authored as DEFAULT CONTENT in its own section, never wrapped in a block. Its skin rides a minimal section-metadata
stylevalue (see Step 3); the section's semantics stay native<h2>/<p>/<picture>/<a>. Never create atext/heading/imageblock around bare default content — that is the D1 anti-pattern verbatim. - Blocks are for structure default content can't express: repeating units (cards, FAQ, logos, team), genuinely bespoke compositions (a countdown, a stat band, a cinematic hero), and interactive components. For those, one distinct prototype pattern = one block. Don't abstract speculatively, and don't extract "patterns" across prototypes unless sections are genuinely the same pattern — each pattern's bespoke CSS can't be wrongly shared; violating this casually cost full resets (see ANTI-PATTERNS).
The one deliberate exception — collapse SAME-PATTERN sections into one block + VARIANT classes. When two or more sections are the same content pattern (card grids, prose/CTA bands, quotes, accordions) differing only in skin, emit ONE canonical block (cards, text, quote, accordion) and put each section's look behind a variant class (class="cards brands"), brand styling in the variant CSS. The block JS stays generic (classify cells by content); only the CSS differs per variant. This is the David's-Model library win (D9: small, reusable, variant-driven — not 20 bespoke names) and is proven to preserve fidelity. Keep genuinely-unique sections (a hero, a countdown) bespoke. Budget for it: variant CSS is careful work and some grids are count-specific.
The prototype is the visual spec. The block exists to AUTHOR its content — see The ENCODE contract below for what well-authored content looks like, and ANTI-PATTERNS for how a block must defensively PARSE it.
Output you will produce
For a typical 5–10 page site:
- One block per distinct prototype PATTERN (D1/D9). A 5-page site with 6 sections each → typically ~8–14 blocks: prose bands land as default content, same-pattern sections share one block + variants, and only genuinely bespoke sections get their own block.
- One EDS content page per prototype page. Same number of pages.
- Nav + footer documents at
content/nav.htmlandcontent/footer.html— authored content, deployed and published like any page, fetched by the stockheader/footerblocks (D12: chrome is the canonical fragment use case). - Per-site
blocks/header+blocks/footerCSS/JS reproducing the prototype's chrome (see Step 6). - Updated
styles/styles.csswith brand tokens lifted from the prototype's:root, a reset, the EDS section scaffold, a global button system (see "Lean on EDS button conventions" below), and the styles for the few section-metadatastylevalues default-content sections use. Nothing more. - No shared utility modules. No wave systems. No motion library. The prototype already encodes these per-section; keep them inside the owning block. Section-metadata
stylevalues stay a SMALL closed set (dark,tinted, …) used only by default-content sections — blocks keep painting their own sections.
The ENCODE contract — what well-authored content looks like
Read skills/deploy/reference/encode-contract.md in full before you act on this section. It covers: Section heads: default content the block reabsorbs; Images: editorial → authored content, decorative → CSS only.
Steps
1. Audit (light)
Read skills/deploy/reference/step-1-audit.md in full before you act on this section.
2. Decide names + reuse — LOCK BEFORE WRITING ANY CODE
Read skills/deploy/reference/step-2-names-and-schema.md in full before you act on this section.
2b. Section schema + decode tier — close the round-trip BEFORE writing code (#93, #95)
Read skills/deploy/reference/step-2-names-and-schema.md in full before you act on this section.
3. Foundation
Read skills/deploy/reference/step-3-foundation.md in full before you act on this section.
4. Self-host fonts and minimize CLS — never put font loads in head.html
Read skills/deploy/reference/step-4-fonts.md in full before you act on this section.
5. Lean on EDS button conventions — DO NOT manufacture button anchors in block JS
Read skills/deploy/reference/step-5-buttons.md in full before you act on this section.
6. Chrome — authored /nav + /footer documents, template-slotted header/footer blocks
Read skills/deploy/reference/step-6-chrome.md in full before you act on this section.
7. Blocks (parallel agents)
Read skills/deploy/reference/step-7-blocks.md in full before you act on this section.
8. Block JS scaffold
Read skills/deploy/reference/step-8-block-js.md in full before you act on this section. It covers: Experience Workspace editability contract.
9. Content page scaffold
Read skills/deploy/reference/step-9-content-page.md in full before you act on this section.
Local QA before deploy (no DA)
Read skills/deploy/reference/local-qa.md in full before you act on this section.
Step 10 — Reconcile on the DEPLOYED URL (content-diff ADVISORY + eyeball + CLS)
Read skills/deploy/reference/step-10-reconcile.md in full before you act on this section.
Anti-patterns (lessons paid for the hard way)
Read skills/deploy/reference/anti-patterns.md in full before you act on this section.
Checklist (per page)
Read skills/deploy/reference/checklist.md in full before you act on this section.
When you finish
First page of a site, or a new block or variant: publish the DA library (../rollout/SKILL.md § Phase D, #160). Update stardust/eds-conversion-log.md (or create one) with: final block inventory, decisions locked, anti-patterns avoided this run, anything site-specific the next person should know. The log is the running history of "why does this look the way it does."
References
davids-model.md— David's Model (aem.live) distilled: the 15 rules (D#N), each mapped to the contract or gate in this skill that enforces it, plus the component-model shape compatibility notes.da-deploy-protocol.md— the curl-based DA Source API deploy contract (auth, source PUT, preview/publish, asset-before-preview ordering).(#NN)citations in this document and in the deploy/diff scripts point to the deploy improvement ledger (findings #1–#80), removed from the tree; read it withgit show 940b8795:plugins/stardust/notes/deploy-improvements-archive.md. New findings go toskills/stardust/reference/learnings.md.scripts/ew-editability-probe.mjs— the Experience Workspace editability gate (Step 8 § contract): instrument → decorate → count survivors;--simulate-editoredit-mode drift; URL and--contentharness modes; reads@ew-exemptJSDoc tags.- Experience Workspace sources the contract was verified against (read them when the mechanism seems to have changed): da.live
blocks/canvas/editor-utils/editor-utils.js(getInstrumentedHTML— what is stamped),blocks/canvas/ew-editor-wysiwyg/ew-editor-wysiwyg.js,blocks/shared/prose2aem.js(cells keep their<p>); da-nxnx/public/plugins/quick-edit/quick-edit.js(setBody→loadPage→restoreBlockIndices),src/prose.js(createEditorswap shape),src/images.js,src/dom-index.js,src/selection.js(cursor math ontextContentlength).
stardust:diff — prototype ↔ build reconcile
Two probes that compare a source prototype against a built page. They catch disjoint failure classes — run BOTH; either alone gives a false "looks fine".
Both are framework-agnostic Playwright probes that compare two rendered URLs by
computed style + DOM (not pixels). All stack-specific language lives in a
profile (--profile eds|generic); the comparison logic is generic.
When to use
- After converting a prototype to EDS (the stardust
deployskill's Step 10) — use--profile eds. - Any "does the build match the design?" check between two rendered URLs (a Figma export vs a React build, a legacy page vs a rebuild) — use
--profile generic. - Inside a conversion/QA workflow as the validation gate (see Workflow use).
Not for: a single static file with no JS decoration (use the build/harness URL so components are decorated — a raw .plain.html has no roles to classify).
The two probes
| Probe | Script | Sees | Blind to |
|---|---|---|---|
| Pixel / layout | skills/diff/scripts/visual-diff.mjs | stretched images (vs the source), dropped max-width wraps, blank renders, surface/ground colour flips, heading size/face deltas, image-count gaps | "right text, wrong slot"; a dropped CTA (full pixels, plausible colours → no flag) |
| Structural content + type | skills/diff/scripts/content-diff.mjs | MISSING / ROLE-SWAPPED headings·eyebrows·CTAs, invented/dropped body copy, rendered-FACE font forks (width probe); dropped placeholder/aria-label/title values, missing/wrong/moved icons — on the main root AND the header/footer chrome roots by default | geometry / layout regressions |
content-diff extracts an ordered, role-classified inventory (heading / eyebrow /
cta+href / body) from each root — the --main root(s) plus, by default, the header
and footer chrome roots — classifying by computed style + tag so the prototype's DOM
and the built DOM compare symmetrically, then diffs them root by root; a second inventory per
root carries the placeholder / aria-label / title values and the icons.
Run it
# Prereq 0: playwright importable from the project root (node -e "import('playwright')"), else
# npm i -D playwright pixelmatch pngjs cheerio --legacy-peer-deps
# (never --no-save; extract SKILL.md § Setup). Run the copied scripts from the project
# root: ESM resolves from the script.
# Copy the WHOLE skills/diff/scripts/ dir: content-diff imports its local diff-profiles.mjs
# AND content-inventory.mjs (deploy keeps its own synced copies for #93/#94), plus the
# master's scripts/ (browser.mjs, the one entry to the browser) in stardust/scripts/stardust/.
# Prereq: a RENDERABLE source. Static → serve from its own dir (python3 -m http.server).
# The build URL must be the DECORATED page (live/preview or a local harness), not raw markup.
# ONE server, ONE port — probe before starting one (curl is always present, lsof is not):
curl -sI localhost:8791/ | head -1 # 200/404 = something serves the port; no line = free
curl -sI localhost:8791/<prototype>.html | head -1 # 200 = it serves YOUR dir: reuse it
command -v lsof >/dev/null && lsof -nP -iTCP:8791 -sTCP:LISTEN # optional: names the pid
# Nothing answered → start yours. A foreign server: never kill it; use a per-project port
# (the traps: ../deploy/SKILL.md § Step 10).
PROTO="http://localhost:8791/<prototype>.html"
BUILD="https://<branch>--<repo>--<owner>.aem.page/<path>" # or http://localhost:3000/<harness>
# 1. PIXEL/layout
node skills/diff/scripts/visual-diff.mjs "$PROTO" "$BUILD" --profile eds --sections ".hero"
# 2. STRUCTURAL content + type
node skills/diff/scripts/content-diff.mjs "$PROTO" "$BUILD" --profile eds # --json dumps both inventories
Flags (both tools): --profile eds|generic (default eds), --width <px> (default 1280),
--main <selector[,selector…]> (content root; content-diff defaults from the profile and takes a
comma-separated list — every root is inventoried and diffed on its own and each finding line
carries its root as [root]; visual-diff takes one selector, default main), content-diff only:
--chrome / --no-chrome (default on — the header and footer roots, resolved as the first
<header>/[role=banner] and <footer>/[role=contentinfo] outside the main root(s), are
compared beside it; a side lacking one is measured as empty there and the root line says so),
plus the live-target set (shared engine: skills/stardust/scripts/live-session.mjs — real Chrome presents its
user agent without the headless token and matching client hints; automation-signal handling stays on unless
STARDUST_STEALTH=0; every context sends standard Chrome request headers, and live navigations to one host are paced
STARDUST_LIVE_PACE_MS apart (default 1000), capped by STARDUST_LIVE_MAX_PARALLEL (default 2)
and STARDUST_LIVE_MAX_WAIT_MS (default 300000; 0 disables):
-
--ua <string>— user agent override (default: the browser's own withHeadlessChromereplaced byChrome). -
--wait-until <state>— goto wait override. Default rule (one shareddefaultWaitUntilinskills/stardust/scripts/live-session.mjs), decided per URL side, three tiers:- localhost/127.0.0.1 →
networkidle(local prototypes / harnesses, unchanged); - EDS build/preview origins — hostnames ending in
.aem.page,.aem.live,.hlx.page,.hlx.live→networkidle(they decorate asynchronously and reliably reach networkidle; measuring at domcontentloaded reads the pre-decoration DOM — flaky false reds / FONT FORK on deploy Step 10); - all other live http(s) →
domcontentloaded(live sites with analytics beacons never reach networkidle).
--wait-untiloverrides all three tiers. - localhost/127.0.0.1 →
-
--dismiss [sel,...]— dismiss overlays on both sides: cookie consent (clicked, not removed) AND timed marketing/newsletter modals, plus optional extra site-specific selectors; the mouse is parked afterwards. -
--headed— escalation for bot-managed sites: the same real Chrome plus the challenge-solve window and existing launch flags, window-free;STARDUST_STEALTH=0disables the flags and context spoof, whileSTARDUST_HEADED_WINDOW=1opens a window. -
--locale <tag>— pin Accept-Language + context locale (geo-redirecting sites capture a different locale per run otherwise).
visual-diff also: --out <dir>, --sections a,b (per-section screenshots).
A bot-management challenge/blocked interstitial on either navigation fails LOUD with
exit 3 — it is never measured as the source. Escalate with --headed; if that is still
blocked, the site needs crawl.mjs-class capture and the check cannot run unattended.
A plain (non-challenge) HTTP error on either side — e.g. a 404 build side, normal on aem.page before preview propagation — is NOT fatal: the probe logs a loud warning, measures the error page, and the flags (BLANK RENDER / content asymmetry) carry the signal with exit 0. That is the probes' advisory contract: 0 = ran (flags advisory), 1 = probe error, 3 = bot challenge.
The published-origin probes (#125)
content-diff reconciles a prototype with its build; against a LIVE commerce origin its per-node
findings were false, and the pixel gate passed a page whose every card was clipped
(../replica/reference/source-fidelity-gate.md § The all-pages published-origin gate). Three
probes ask the checkable questions; all load both sides in the same window-free real-Chrome tier
and settle them the same way (scripts/measure-live.mjs).
ORIGIN="https://www.example.com/<path>"; SERVED="https://main--repo--owner.aem.live/<path>"
node stardust/scripts/diff/clip-probe.mjs "$SERVED" [--json clip.json] # D1: exit 2 on cut / hidden text or controls
node stardust/scripts/diff/content-presence.mjs "$ORIGIN" "$SERVED" [--variable "<selO>=<selE>"] # D2: exit 2 on MISSING/HIDDEN link or heading
node stardust/scripts/diff/unit-geometry.mjs "$ORIGIN" "$SERVED" --unit "<selO>=<selE>" --n 2 # D3: exit 2 on an element off / hidden / missing
Reading: a 🔴 clip group names the clipper (a fixed-height box with overflow: hidden) — fix
that block's CSS, never the content. HIDDEN LINK = in the DOM but clipped (CSS); MISSING LINK =
not served (encoder); CONTROL STATE = same control, another value; COUNT … = session-variable
region, confirm by eye. The origin side fails loud on HTTP ≥ 400 (exit 4) and a bot challenge
(exit 3). Traps: an infinite-scroll origin keeps loading under the settle — mark the region
--variable; a live origin without <main> compares whole page against whole page (the scope
line says so), header / footer left to the chrome crop gate unless --chrome; the count-phrase
and "read more" heuristics are English word lists (--count-words, --more-words).
The header contract (#132)
Every probe above sees the header at rest (pointer parked, motion frozen), so it passes with every menu wrong; runs shipped boilerplate click dropdowns for hover mega menus, search and cart as plain links, a static list for a drill-down drawer. The header's behaviour is recorded from the source once and the build compared with it:
node stardust/scripts/diff/chrome-explore.mjs "$ORIGIN" stardust/chrome/header-contract.json # 1440 + 390
node stardust/scripts/diff/chrome-explore.mjs "$SERVED" stardust/chrome/header-build.json --max-requests 0 --pace-ms 0 --reload-pause-ms 0 # our host: source-edge protections do not apply
node stardust/scripts/diff/chrome-compare.mjs stardust/chrome/header-contract.json stardust/chrome/header-build.json \
--profile replica --json stardust/chrome/header-parity.json # functional under redesign and reskin
The explorer hovers (desktop), clicks and keys every header control and records each opened state (links,
headings, crop, aria-expanded, focus, scroll lock, motion, close paths), nested levels within --max-states 400 --max-depth 4, search typeahead and submit, and the header scrolled; its summary line sizes the work. The comparer
exits 2 on a missing control or state (hover rebuilt as click included), panel links, keyboard, close paths or
scroll lock; replica adds open-state crops (2 %), motion (max(80 ms, 25 %)) and scroll states. Only the site
owner clears a finding: stardust/chrome/header-decisions.json ({ decisions: [{ finding, decision, reason, by, at }] }), never signed by an agent. It runs at extract --prep (the contract), on the foundation shell and in
deploy Step 10, on the live host before handover (done-check header_parity), and in qa. Crops stay in
stardust/.work/chrome/.
Reading content-diff
- 🔴 MISSING CTA / HEADING / EYEBROW — real dropped content. FIX. A missing eyebrow is most often a segmentation drop where the eyebrow precedes its heading; a missing CTA means the component never rendered the link. These are exactly what the pixel probe cannot see.
- 🔴 ROLE SWAP — same text under a different role (body painted as eyebrow, eyebrow folded into a teaser). FIX the component's node segmentation. With the same look, body/eyebrow → heading is an accepted ROLE UPGRADE (root line and
--jsonaccepted, not a finding), heading → body/eyebrow 🟡 ROLE DOWNGRADE. Lost visually hidden (sr-only) text is 🟡 MISSING SR-ONLY TEXT; a lost sr-only link stays 🔴 MISSING CTA. - 🔴 MISSING PLACEHOLDER, MISSING ICON, ICON DIFF on an interactive element (an input, a button, a link or inside one) — a dropped localized search placeholder, a share link without its icon, a wrong flag in a locale link, an empty icon box. FIX. Outside interactive elements the same findings are 🟡. A lost aria-label is a nothing-lost 🟡 anywhere (fails the gate).
- Icons pair by identity or by the same pixels: a re-hosted file (SAME IMAGE) or an svg drawn as
<img>(SAME ICON) is accepted. A laid-out 0×0 icon is not one. - 🟡 MISSING TITLE — always 🟡: a title tooltip is not read by most assistive tech and is commonly dropped by design. 🟡 ICON MOVED — the same icon at another anchor, paired after the anchor passes (typically a text-less
<button>host that anchors asbutton#n): CONFIRM its placement. 🟡 ICON KIND (pixels not compared, e.g. a hidden icon) and every EXTRA. - Every finding line names its root —
🔴 MISSING PLACEHOLDER [header]: …— and the report prints one block per root (root "main",root "header", …; a root a side lacks is measured as empty there and the line says which side). - 🟡 MISSING BODY / EXTRA — body prose dropped, or build copy with no source. Usually a placeholder→real-copy rewrite. CONFIRM intended; don't blindly "fix".
- 🟠 FONT FORK — matched lines whose rendered FACE differs (width probe, never
document.fonts.check).source X→sysmeans the prototype named font X but never loaded it and fell back to system — the build self-hosting the intended fallback is then CORRECT, not a bug. All forked lines are grouped into one advisory. - Known limitation — node-granularity JOIN/SPLIT reads as 🔴 (#87). When the source renders one text run as N sibling nodes and the build renders the same text as ONE node (or vice versa — e.g. three fact chips vs one combined chip span), the diff currently reports MISSING + ROLE SWAP + EXTRA for what is a non-defect. Until concat-matching lands (a source node that is a substring of a same-region build node → 🟡 JOIN/SPLIT advisory), verify a 🔴 whose texts concatenate into an EXTRA finding's text before treating it as dropped content — confirmed-justified is a pass.
Pass bar: visual red flags none/justified AND content-diff 0 🔴 and 0 nothing-lost 🟡 (../replica/reference/source-fidelity-gate.md § Pass bar item 1). Re-run BOTH after each fix.
Profiles
skills/diff/scripts/diff-profiles.mjs holds them. A profile supplies the source/target labels,
per-flag remediation hints, the font-delta threshold, the default content-root
selector, and the eyebrow classifier thresholds. The engines carry no stack
strings.
eds(default) — Edge Delivery / DA remediation language + the stardustdeployskill's finding numbers.generic— neutral source/build language for any stack.
Add a profile by copying generic in diff-profiles.mjs and editing hints.
Shared engine + the in-loop sibling
The structural probe's classifier + differ live in skills/diff/scripts/content-inventory.mjs
(deploy imports its synced copy). They measure with the same instrument as two gates of the stardust deploy skill:
section-schema.mjs (the pre-code ENCODE/DECODE contract, deploy #93) and block-roundtrip.mjs
(the in-loop per-block gate, deploy #94 — the same inventory diff, run per block at authoring time
against a local decorate() harness, no DA needed, exit-code gated). Run the in-loop gate while
converting; run THIS skill's two probes as the final post-deploy proof. A defect first found here
that the in-loop gate passed = the delivery pipeline reshaped the content in transport — fix the
block's flattened-shape fallback, not the authoring.
Workflow use
Call both scripts in a validation phase and gate on the output, as deploy's Validate phase does on a served,
decorated build (local harness or branch preview): fix visual-diff's STRETCHED/FLUSH-LEFT/SURFACE-GROUND/GAP/
HEADING FACE flags (unless justified — a font substitution is one HEADING FACE ×N line) and every content-diff 🔴,
confirm 🟡/🟠, loop until both are clean.
stardust:direct
Resolve the user's freeform redesign intent into a complete target
specification: project-root PRODUCT.md and DESIGN.md (impeccable
format), a DESIGN.json sidecar with the divergence audit trail, and a
stardust/direction.md with the full reasoning trace.
direct produces the spec against which prototype and migrate
operate. It never writes prototypes or migrates pages — those are
downstream sub-commands.
Inputs
<phrase>— optional positional. The user's freeform intent ("make it better", "more Linear less Salesforce", "feel more premium on a small screen"). If omitted, ask the user for one.--re-direct— optional. Replace the current direction with a new one. Triggers stale-flagging on prototyped / approved / migrated pages perskills/stardust/reference/state-machine.md. Default behaviour without the flag is additive: if a direction already exists, the agent asks before replacing.--rebrand— optional. Force rebrand mode (full divergence-seed roll, no Mode A inheritance). Without it the default is brand-faithful whenever the captured signal issignal-strong(§ Mode-detection precedence).--prep— optional. Run in migrate-prep mode: confirm the type catalog, finalize the module catalog, capture color reservations and brand-level metadata defaults, re-evaluate direction against the wider crawl. See § Prep mode below. Typically invoked via theprepare-migrationorchestrator.--add-variant <name>— optional. Add a new variant against the existing direction without re-running intent reasoning or mode detection. WritesDESIGN-<name>.{md,json}at the project root and appends a per-variant section tostardust/direction.md; existing prototypes are not stale-flagged. See § Add-variant mode below.
Setup
- Run the master skill's setup
(
skills/stardust/SKILL.md§ Setup) — hard impeccable dep check, context loader, state read. - Verify
stardust/state.jsonexists and contains at least oneextractedpage. If not, stop and recommend$stardust extract <url>first. - Read
stardust/current/_brand-extraction.json. If absent, stop — extract did not complete brand-surface extraction; re-run extract. 3b. Cross-site brand inputs (when present).state.json.designSource(design-donor mode: Mode A pins bind to the donor's derived system) and_brand-extraction.json.origins[](sibling-property evidence: widens what can be amplified, not what is pinned). Readreference/cross-site-brand-inputs.mdfor the pin and evidence rules; surface the active mode in the plan. - Read
stardust/direction.mdif present. If a prior direction exists and--re-directwas not passed, ask whether the user wants to refine the existing direction or replace it. - Validate provenance (prep mode only). When
--prepis active, run the provenance validation perreference/prep-mode.mdbefore typing or module detection. - Classify the captured brand signal. Read
_brand-extraction.jsonand stamp one of:signal-strong— palette has ≥ 3 distinct colors (after near-duplicate clustering and excluding pure black/white if they are the only entries) AND at least one captured type family is named intype.headingFamily.nameortype.bodyFamily.name. This is the common case for any extracted commercial site.signal-thin— palette has 2 colors OR no captured type family ORtype.scaleAudit.kind === "ad-hoc"with fewer than 3 distinct heading sizes. The brand exists but cannot fully anchor a refresh.signal-absent— palette has 1 color or 0, or_brand-extraction.json._provenance.notesflags the extraction as failed / login-walled / iframe-dominated. The classification feeds the Mode-detection precedence in Phase 2. Surface the classification in the plan when it would change the default mode.
Procedure
Phase 1 — Reasoning
Run the full intent-reasoning procedure from
skills/stardust/reference/intent-reasoning.md. Steps 1-6: restate
the phrase in dimensional vocabulary, identify movement, identify
gaps, ask at most two clarifying questions, map to an impeccable
command sequence, show the plan to the user.
Worked examples in
skills/stardust/reference/intent-examples.md calibrate the style.
Hard ceiling on questions: two per turn, no exceptions.
Zero movement is not a direction — hand off to replica. Before
restating, check whether the phrase pins every axis unchanged: "exact
replica", "same design", "pixel-perfect", "faithful", "keep the current
design", "1:1", "re-platform only", "preserve verbatim", or
ia-fidelity: verbatim with palette, type and density all pinned. That
is a same-design migration and direct has nothing to decide: write a
one-paragraph note to stardust/direction.md ("zero-movement phrase —
same-design migration; the direction is the mechanical promotion in
replica Phase 2"), stamp state.json.flow: "replica" if unset
(../stardust/reference/state-machine.md § Flow keys), and stop with
"run $stardust replica <url>". Never continue into a redesign
direction, a --prep module catalog or a plan on such a phrase — under
hands-off included: "ask nothing" below never means "proceed on a
replica phrase". (Recorded: direct invoked with "exact replica —
preserve verbatim" kept going; 2,207 pages were published at 24–28 %
pixel diff, four to five times the replica pass bar.)
Hands-off mode (per skills/stardust/SKILL.md § Hands-off mode,
state.json.handsOff: true): ask nothing and wait for nothing — after
the zero-movement check above, which hands-off does not skip.
Derive every answer the questions would have collected from the
captured evidence — density and ia-fidelity from their documented
defaults and trigger conditions, audience and register from the
captured surface — and record each as a named assumption in
direction.md § Movements (e.g. density: balanced (hands-off default — multi-audience floor fired)). The plan is still written;
execution proceeds without the confirmation gate. Question budgets
and gates below that say "ask the user" resolve the same way: derive,
stamp the assumption, proceed.
Density tuning (one-shot, only when unmoved)
When the user's phrase does not move the density axis (per
reference/intent-dimensions.md § 4), and the resolved register is
brand, ask one short follow-up — count it within the two-question
ceiling:
Density tuning — (a) airy (NYT-Opinion-tier breathing, ~96px section padding), (b) balanced (calm but compact, ~64–72px), (c) packed (data-dense, ~40–48px). Default for brand-register sites with multi-audience IA is (b) balanced; pick (a) only when the page is editorial-led with deep per-section density.
If the user answers, stamp the chosen tier in direction.md §
Movements as density: <tier>. If unanswered, default to
balanced (not airy) for brand register and stamp
density: balanced (default).
Skip this question entirely when:
- The user's phrase already moved
density(any of "make it denser", "more breathing room", "compact", "tight", "spacious" count as movement). - The register is
product(defaultpackedper § 4). - The register is
ambiguousand resolving it earlier in the reasoning is the higher-value question — defer density to the next turn rather than burning a question slot.
Phase 4 reads the stamped tier to set spacing.sectionPadding;
it never re-asks.
IA-fidelity tuning (one-shot, only when unmoved)
When the user's phrase does not auto-pin ia-fidelity (per
reference/intent-dimensions.md § 9 — i.e. none of "verbatim",
"same IA", "keep the structure", "swap the surface",
"don't rethink the IA" and none of "reimagine", "rethink",
"deeper redesign", "what if" appear), ask one short follow-up
— count it within the two-question ceiling:
IA fidelity — (a) verbatim (same section sequence, same content beats; variants explore surface only: color, type, density, motion), or (b) reimagined (variants may demote / promote / drop sections, move IA priorities, take "what if" positions on the spine of the page). Default (b) for the typical refresh; pick (a) when the customer asked to keep their site structurally identical and only swap the surface.
If the user answers, stamp the chosen tier in direction.md §
Movements as ia-fidelity: <tier>. If unanswered, default to
reimagined and stamp ia-fidelity: reimagined (default).
Skip this question entirely when:
- The user's phrase already auto-pinned the axis (any trigger phrase in § 9 — "same IA, swap the surface" → verbatim; "what if we rethought the home page" → reimagined).
- An existing
direction.mdis being refined (the active tier holds unless the user explicitly re-pins).
Phase 4 stamps the tier into iaPriorities[].mutability;
downstream prototype reads it.
Pair this question with the density-tuning question when both are unmoved — "two things to pin before we resolve: (1) density …, (2) IA fidelity …" — to stay within the two-question ceiling. If resolving register (brand vs product) is also outstanding, prioritise register first; defer one of density / ia-fidelity to the next turn.
Wait for the user's confirmation ("go", or a correction to the
plan) before moving on.
Phase 2 — Resolve the divergence inputs
Once the plan is confirmed, resolve the divergence-toolkit inputs
from skills/stardust/reference/divergence-toolkit.md. Before
rolling the seed, run the mode-detection precedence below to decide
whether the seed needs rolling at all.
Mode-detection precedence (run first)
The default mode for direct is determined by whether an extracted
brand surface exists with usable signal — not by the user's
freeform phrase alone. Ambiguous refresh phrases ("make it modern",
"stunning new version", "design fatigue cure") are migration-shaped
asks, not rebrand triggers. The precedence is asymmetric on purpose:
the safer mode (Mode A — brand-faithful) catches ambiguous phrases;
the riskier rebrand mode requires the user to name it.
-
Site migration / refresh — DEFAULT. When the captured brand signal stamped in § Setup step 6 is
signal-strong, Mode A is active by default. The user's phrase moves expressive, distinctiveness, tone, and density axes inside Mode A — but palette and type are pinned to the captured surface, and the image-reuse contract (below) holds. Signature preservation also holds: a captured signature hero medium (background video / canvas / Lottie / scroll-motion, elevated as_brand-extraction.json#voice.heroMedium) or a site-wide motif is reproduced, not flattened — perskills/stardust/reference/ intent-dimensions.md§ 8b, and exempt from thesurprisebudget. Surface in the plan: "Brand-faithful mode active — palette and type pinned to the captured brand surface. Pass--rebrandto override." -
Rebrand — explicit opt-in. Mode A is overridden when any of the following triggers fire:
- The user's phrase contains an explicit rebrand signal: any of
rebrand,new brand,clean slate,start over,from scratch,replace the brand,not brand-faithful,editorial reimagination,completely new,redo the brand. - The
--rebrandflag is passed. - Captured signal is
signal-absent(no usable inheritance). Surface this case as an automatic switch with reason; the user can correct.
In rebrand mode, run the standard divergence-seed roll per "Default mode (no constraints)" below. Surface in the plan: "Rebrand mode active — full divergence-seed roll. Mode A bypassed because ."
- The user's phrase contains an explicit rebrand signal: any of
-
Brand-faithful + targeted exploration. When the user requests N variants (e.g. "3 variants", "4 directions") and Mode A is active, the variant role contract in
reference/multi-variant.mdapplies (trigger: § Phase 2.6). Variant A is locked to strict Mode A (palette and type pinned, IA preserved, every improvements-list item applied). Variants B+ may amplify one captured trait (a motif, a photo treatment, an IA priority the current site underplays) but cannot:- introduce a font outside the captured surface,
- introduce a color outside the captured palette,
- shift the register from PRODUCT.md.
-
Signal-thin fallback. When captured signal is
signal-thin, Mode A activates but warns: "Captured brand surface is thin — {reason}. Variants will inherit what is available; some dimensions will need to be filled by the divergence toolkit." The user may either re-run extract with a wider crawl (--cap 25) or proceed with reduced fidelity.
After mode-detection completes, run the existing mode definitions below (Mode A procedure, Mode B anchor-reference precedence, Mode C ground-family override) as applicable.
Mode A — Brand-faithful mode
Triggered automatically when the captured brand signal is
signal-strong and no rebrand-mode override fired (see
§ Mode-detection precedence above), OR when the user pinned both
type and palette (via explicit phrase: "keep typography and palette",
"preserve the existing brand", "brand-faithful redesign"; or via
constraints listing both as anchors).
In this mode, direct does not roll the type or palette dimensions of the seed — they are already locked.
The mode procedure:
-
Record
font_deck.name = "brand-inherited"andfont_deck.picked_by = "user-constraint". Do not invokereference/palette-picker.md. -
Record
palette.source = "inherited from _brand-extraction.json"andpalette.picked_by = "user-constraint". Apply role-renaming per toolkit § 4 if the inherited names violate the brand-native rule (this is still useful — role renaming is presentational, not a divergence choice). -
Still roll the seed for the non-locked dimensions (decade, register, ground-family-as-applicable per Mode C below). These dimensions still drive divergence — the visual register and the era can shift even when type and palette are pinned.
-
Auto-emit the
brand_faithful_inversions[]block inextensions.divergenceperreference/direction-format.md§ Brand-faithful inversions. The list is mostly mechanical (see § Brand-faithful inversions in direction-format.md for the canonical patterns). -
Surface in the user report which dimensions had teeth and which were inert:
Divergence (brand-faithful mode): decade ✓ rolled → 2025-now craft ✓ rolled → Riso print register ✓ rolled → Memoir-adjacent ground-family inherited → stark-white (brand-native) font deck inherited → existing site stack palette inherited → existing 5-color set -
Image-reuse contract. Captured images are reused via their public URLs (or the local copies in
stardust/current/assets/media/written by extract Phase 2) at the same semantic position as on the source site. Hero stays hero. Story-tile portrait stays story-tile portrait. Program-card image stays program-card image. Background-motif image stays background motif.This is part of brand-faithful inheritance: swapping a captured portrait for a placeholder, or demoting the hero photo to a thumbnail, erases the brand's most load-bearing trust signal.
The only legitimate ways to deviate from semantic position-preservation under Mode A:
- The captured image is broken (404, blocked by
referrer-policy, CORS-walled, or recorded withlocalPath: nulland adownloadError). - The brand-review surfaced the image as a tension (e.g.
T-stock-photographywhen added — flagging the captured image as obviously templated stock that the brand team would replace anyway). - The improvements list (Phase 2.5) explicitly notes a crop or positioning fix for that image — in which case the same image is reused at the corrected crop or position.
Synthesised placeholders are forbidden under Mode A. When a captured image cannot be reused, the prototype shape brief declares the gap explicitly and the rendered prototype shows a placeholder-with-signature element so reviewers see the gap rather than a fabricated photo.
- The captured image is broken (404, blocked by
The user can correct the mode at the plan-confirmation gate (e.g. "actually let me move the palette" or "actually rebrand it") before it locks.
Mode A+ — Brand-adjacent refinement (bounded, evidence-gated)
The middle tier between Mode A's hard pins and --rebrand: when
the improvements list (Phase 2.5) names a captured type or color
weakness with evidence, bounded same-classification upgrades are
permitted — each audited in extensions.divergence. brand_adjacent_refinements[], never active by default. Read
reference/mode-a-plus.md before applying any refinement.
Mode B — Anchor-reference precedence
When the user provides anchor references (Q1/Q2 answers like
"Pentagram nonprofits, This American Life, NYT Opinion longform"),
those references already imply seed dimensions (Pentagram →
decade 2025-now editorial; This American Life → register
Memoir-adjacent). Do not roll dimensions the references already
imply.
Agent-sourced anchors (default when the user provides none).
Mode B no longer waits for the user to name references: run the
reference-research procedure
(skills/stardust/reference/reference-research.md) to source 3–5
real-world anchors matched to the brand's category, register, and the
resolved direction movement. Researched anchors carry the same
implied-dimension weight as user-provided ones and are recorded as
picked_by: "reasoned: <anchor>" with the full citation in
extensions.divergence.references_used[]. User-provided references
always outrank researched ones on conflict. When research is
unavailable (ladder exhausted per reference-research.md § 1), Mode B
degrades to the deterministic roll for the un-implied dimensions.
Precedence rule:
- If anchor references are present, extract their implied
dimensions:
- Decade from era of the references (Pentagram → 2025-now; vintage Penguin → 1960s).
- Craft from medium of the references (TAL → audio editorial ≠ a craft per se, but Bandcamp → web-print hybrid; Riso-print anthology → Riso).
- Register from cultural reference set (Memoir, Tabloid, Catalogue, etc.).
- Ground-family from typical ground of those references (NYT Opinion → cream/parchment; Pentagram nonprofit → stark-white or monochrome-tint).
- Mark each implied dimension as
picked_by = "anchor-reference: <ref-name>". - Roll the seed only for un-implied dimensions.
- Record the anchor → dimension mapping in
extensions.divergence.seed.anchors[].
Mode B can compose with Mode A: anchor-references narrow the seed, brand-faithful constraints lock type/palette, the remaining roll is whatever the anchors didn't already imply.
Mode C — Brand-faithful ground-family override
When Mode A is active and the seed's ground_family roll
disagrees with the brand's existing ground (e.g. seed rolled
monochrome-tint but the brand's captured background is
#ffffff stark-white), the brand's ground wins. The seed roll is
not discarded — it informs the alt-section surface instead
(per divergence-toolkit.md § 4 Color roles). Record the override
in extensions.divergence.seed.ground_family.override with one
of three reasons:
brand-faithful— Mode A active and brand has a fixed ground.print-paper— manual override for print/paper categories (existing toolkit rule).direction-driven— seed wins (default; no override).
The three reasons are mutually exclusive; surface the chosen one in the user report.
Default mode (no constraints)
When neither Mode A nor Mode B applies (rebrand or thin-signal runs with no user anchors), the procedure is research-first, roll as fallback:
- Reference research first. Run
skills/stardust/reference/reference-research.mdto source anchors for the brand's category and the resolved direction, and derive the dimensions they imply (picked_by: "reasoned: <basis>"). This is Mode B's machinery applied to agent-sourced anchors — see § Mode B above. - Seed as fallback + tiebreaker. Roll the 4-dimension seed
(decade × craft × register × ground-family) per § 2 of the toolkit
only for dimensions research left un-implied, or entirely when
research is unavailable. The roll also remains available as a
deliberate convergence-breaker when the self-audit catches the
model reproducing its defaults despite research. Record
picked_byper dimension. - Font deck. Pick from the 10 named decks per § 3, letting the
researched anchors inform the pick the same way a seed implication
would (e.g. an editorial-serif anchor set →
serif-luxury). When neither research nor seed implies a deck, pick deterministically from the hash. - Palette. If the resolved direction moves the color-energy
axis or names the existing palette as part of the problem: derive
a full role-ramped palette (text, grounds, borders, accents,
states) from the primary researched anchor or a library candidate
— the library (
skills/direct/reference/palette-picker.md) is an anchor bank, not a closed menu; the model designs the ramp and validates every text-on-ground pair for WCAG AA before it lands in tokens (deterministic where it matters — math — not where it hurts — taste). Record the derivation basis inextensions.divergence.palette_source. Otherwise inherit the existing palette fromstardust/current/_brand-extraction.json, applying role-renaming per toolkit § 4 if the inherited names violate the brand-native rule.
Always run
- Anti-toolbox audit. Regardless of mode, run the self-audit (toolkit § 1 Enforcement + Self-audit) on the resolved direction. Each anti-toolbox hit needs a brand-specific justification or it is removed.
Record every resolution in DESIGN.json.extensions.divergence per
the v2 storage shape at the bottom of divergence-toolkit.md.
Phase 2.5 — Improvements list (Mode A only)
Before any variant is rendered downstream, write
stardust/prototypes/<slug>-improvements.md listing 3–5 specific
weaknesses observed in the captured site. It is the brief variant
A renders against: not prescriptive (no visual targets), but
descriptive of the gap between the existing site and a competent
2026 execution of the same brand. Variants B+ honor the list as a
floor (they may go further but not contradict it).
Skip this phase when the resolved mode is rebrand — the improvements list assumes brand-faithful inheritance, and a rebrand replaces the site rather than fixing it.
Audit reuse. When stardust/audit/<domain-slug>/audit.json
exists for this origin (written by the stardust audit skill), consume its
design findings as candidate improvements instead of re-deriving from
scratch — carry the finding IDs into each item's evidence citation.
The specificity bar below still applies to every carried item.
What goes in the list
The list draws from five categories. Items should be specific enough
that a downstream prototype shape brief can cite them by number.
- Dated patterns the design world has moved past — name the pattern and its era, not a feeling.
- Cluttered IA — unclear hierarchy, weak or redundant CTAs, fragmented conversion funnels.
- Contrast failures, accessibility gaps, density issues — pull
from
brand-review.htmlTensions when present (T-color-imbalance,T-img-alt-empty, etc.). - Cliché conventions the brand could move past while staying recognisably itself.
- Missed opportunities the existing site doesn't capitalise on.
Worked examples per category:
reference/improvements-list.md.
Specificity bar
A weakness is specific enough when it cites:
- a measurable observation (size, ratio, contrast value, count, or named tension ID) drawn from the per-page JSON, the brand-review, or the brand-extraction;
- the design pattern at fault (named, e.g. "centered hero + dual CTA");
- one concrete fix the variant A brief will apply.
"The hero needs work" fails all three. "Hero photo is cropped to 280×180 in a 1440-wide viewport when the captured source supports 16:9 full-bleed at 1440×810; variant A fix: render at full-bleed and move the headline to a left-anchored two-column overlay" passes all three.
Format
Markdown, with a _provenance frontmatter block per the artifact-map
convention. Each item is a numbered list entry with a category tag, a
weakness statement, and a one-line fix. Full worked example in
reference/improvements-list.md § Format example.
Stopping condition
If after reading the brand-review, the per-page JSON, and the brand-extraction the agent cannot name 3 specific weaknesses that meet the specificity bar, stop. Variant A has no brief; the "better" claim fails. See § Failure modes (d).
The agent should not rationalise — "the hero is dated" is not an item, "the typography could be more modern" is not an item. Genuine empty-list cases occur when the captured site is already at a high execution level on observable dimensions. In that case the honest answer is to surface the empty list and propose reduced scope (density-and-contrast adjustments only, or pivot to a single exploratory variant rather than three).
Phase 2.6 — Multi-variant fork (when N > 1)
When the user requests N variants (phrase contains "3 variants",
"4 directions", or equivalent), variant slots are
role-differentiated, not seed-differentiated. Branch on the
ia-fidelity tier stamped in Phase 1: surface-tuning forks
A1/A2/A3 under verbatim; role-differentiated A + B + C (faithful
- improvements / one captured trait amplified / a different
captured trait amplified) under
reimagined. Readreference/multi-variant.mdand follow its variant role contract, differentiation contract (each variant pair differs by ≥ 2 substantive changes), surface-fork rules, and render-refusal conditions before resolving any variant.
Phase 3 — Author target PRODUCT.md
Write PRODUCT.md at the project root using impeccable's
reference/init.md § Write PRODUCT.md as the format spec (not as
a runtime command to invoke; init, formerly teach, runs an
interview). Direct authoring is intentional: by the time direct
runs, every answer impeccable's interview would surface has already
been resolved through stardust's intent-reasoning + divergence
resolution above.
File order: stardust's <!-- stardust:provenance … --> block first
(per ../stardust/reference/artifact-map.md § Provenance, as for
every stardust-written artifact), then # Product, then the
<!-- impeccable:product-schema 1 --> comment verbatim so impeccable
reads the file as a current product record rather than a legacy one.
Omit a section rather than filling it with generic prose. Sections to
populate:
- Platform — the bare value
web. - Users — from the resolved audience tuple plus tone signals from the extracted brand surface.
- Product Purpose — from the user's phrase + extracted hero copy
- resolved tone, written as a one-line value statement followed by one-line scope.
- Positioning — the claim the site makes that a neighbour could not truthfully copy, from the extracted hero and proof copy. Mark inferred when the copy does not state it.
- Capabilities and Constraints — the resolved constraint set
(
a11y-first,RTL-required, platform or content constraints) and any product fact the user pinned. - Brand Commitments — the binding identity decisions: the resolved
registeraxis, the brand personality derived from the resolved expressive axis + tone + reference set (weight axes the user explicitly moved over inherited values), and the anti-references — the user's stated anti-refs plus any anti-toolbox guardrails relevant to the resolved direction (e.g. "modernise" triggers the Generic-2026-SaaS silhouette guardrail; list it explicitly so prototype and polish enforce it). - Evidence on Hand — the captured copy, imagery and proof under
stardust/current/with paths, and the absences future work must not fabricate (no testimonials captured, no pricing, …). - Product Principles — 3-5 durable strategic principles, each mapping to a specific axis movement. Format: one verb-led principle, one-line elaboration. No visual recipes; those belong in DESIGN.md.
- Accessibility & Inclusion — populated when the constraint set
includes
a11y-first,RTL-required, or similar. Otherwise omit and inherit impeccable's defaults.
Where a section cannot be populated with confidence from inputs,
mark it <!-- _provenance: inferred --> with a one-line basis
sentence. Never invent strategy.
Phase 4 — Author target DESIGN.md and DESIGN.json (site-level only)
Write DESIGN.md at the project root using impeccable's
reference/document.md as the format spec — Stitch YAML frontmatter
plus the 6 canonical sections in fixed order.
Site-level only. direct authors the design system, not
page-level deployments. Page-specific composition decisions live
in stardust/prototypes/<slug>-shape.md written by prototype
Phase 1 — see skills/prototype/reference/page-shape-brief.md.
The boundary is abstract role vs literal deployment:
| In DESIGN.md / DESIGN.json (site system) | In <slug>-shape.md (page deployment) |
|---|---|
| Token vocabulary (colors, typography, spacing, radii) | Per-page section list and order |
| Voice rules ("Mixed-Case-Headlines"), anti-refs | Literal copy per section (sourced from current/pages/.json) |
| Anti-toolbox audit, divergence trace | Page-specific layout decisions ("hero is 5/3 split on home") |
Abstract component vocabulary: button-primary, button-secondary, card, input, badge, link (default treatment, density, sizing — NO page-specific dimensions or content) | Section-level component dimensions (the211Panel at 320×260 with dock points per viewport) |
Named system-component roles (a header exists, a footer exists, a cta-band pattern exists) | System-component deployment (literal tile labels in fixed order, link targets, copy variants) |
| Default visual treatment for each abstract component | Per-page composition (statRow with literal "100 YEARS · 18,400 PEOPLE HOUSED · …") |
| Voice samples (do/don't, tone exemplars) | Per-page interaction model and key states |
Concrete examples of items that must not appear in DESIGN.md / DESIGN.json:
- Literal tile labels for any system-component pattern.
- Section-level pixel dimensions, dock points, breakpoint-specific widths.
- Stat numbers, addresses, quotes, named-person references.
- "On home, the hero is X" — that's a home-page deployment.
- Per-page copy variants ("on the donate page the CTA reads Y").
If a redesign demands a section-level dimension or a literal label
that feels site-wide ("every page has a 211 panel docked at the
bottom-right"), encode it as an abstract role in DESIGN.json
(e.g. extensions.systemComponentRoles.persistent-help with
purpose / position-class but no literal copy or dimensions) and let
each page's shape brief specify the deployment.
Token sources:
-
colors— from the picked palette (palette-picker.md output) or the inherited palette with role-renaming. Role names must satisfy toolkit § 4 (brand-native, noPrimary/Secondary/Alarmetc. as sole role names). -
typography— from the chosen font deck. Sizes scaled by the resolved expressive axis (drenched → ratio ≥ 1.333; committed → ratio 1.25; restrained → ratio 1.125-1.2). Heading vs body assignments inherit from the deck. -
rounded— derived from extracted brand-surfaceborderRadius.primarymode, unless the direction moves distinctiveness towardsingular(in which case re-derive from the font deck's tonal cousins). -
spacing— 4pt base scale;sectionPaddingpropagated from the density tier stamped in Phase 1 (reference/intent-dimensions.md§ 4):airy→sectionPadding.desktop: 96px,tablet: 72px,mobile: 48pxbalanced→sectionPadding.desktop: 64px,tablet: 48px,mobile: 32px← brand-register defaultpacked→sectionPadding.desktop: 48px,tablet: 36px,mobile: 24px← product-register default
The agent does not re-ask the density question here — the tier was resolved in Phase 1 (asked once when the phrase didn't move the axis, defaulted to balanced for brand register if unanswered). Pick the value deterministically from the stamp.
Hard floor enforcement. When the captured page inventory shows
5 sections OR >2 audience tracks (per
reference/intent-dimensions.md§ 4 → "Hard floor for brand-register multi-audience sites"), the resolvedsectionPadding.desktopis bounded at ≤ 64px and ≥ 40px on every variant including the highest-divergence one. If Phase 1 stampedairydespite the trigger conditions firing, surface the conflict before writing tokens — "density tierairywas selected but the captured inventory triggers the multi-audience hard floor; pick (a) override floor (density: airy (user-pinned)in direction.md) or (b) accept the floor (sectionPadding capped at 64px)." Default to (b) when the user does not respond. -
components— 4-6 canonical components (button-primary,button-secondary,card,input,badge,link) populated from extracted brand-surfacecomponentStyle, with values adjusted for direction movements.
Write DESIGN.json (schemaVersion 2) with:
-
extensions.colorMeta,typographyMeta,shadows,motion,breakpoints— filled from the same sources as DESIGN.md. Themotionblock carries the register selection (when cinematic motion may be applied at prototype time):"motion": { "register": "arrival | kinetic-display | live-systems | editorial | kinetic-grid", "registerRationale": "<one-line citation back to PRODUCT.md Brand Personality trait that selected this register>", "easings": { "entrance": "...", "transition": "...", "expo": "..." }, "durations": { "enter": <ms>, "stagger": <ms> }, "parallax": { "translate": <vh>, "fade": <0-1>, "rangeStart": <%>, "range": <%> } }Picked per the register selection heuristic in
skills/prototype/reference/motion-registers.md§ Selection heuristic, reading the resolvedPRODUCT.md§ Brand Personality:Personality traits (any match) Register civic-formal+ (institutionalORplace-led)arrivalsignage-ledORwayfinding-firstORdisplay-typography-signaturekinetic-displayoperationally-transparentORdata-ledORdashboard-registerlive-systemseditorialORslow-pacedORpublication-registereditorialproductORSaaSORtransactionalORmodular-cataloguekinetic-grid(ambiguous / no clear match) arrivalToken defaults per register are sourced from
skills/prototype/reference/motion-registers.md§ The five registers;directcopies them verbatim into themotionblock unless the user has provided overrides during intent reasoning. TheregisterRationalefield records the one-line justification so reviewers can audit the choice.directdoes not apply the motion — that happens at prototype time under--cinematic.directonly selects the register. Pages whose redesign does not need motion can leaveregisterabsent; cinematic prototype will then either ask or pick from the heuristic at render time.Per-variant placement (when N > 1 variants). The
motionblock goes into the variant-specificDESIGN-<id>.jsonfiles, not site-levelDESIGN.json— variants without aregisterrender static. Seereference/multi-variant.md§ Per-variant motion placement.When the user's intent phrase contains explicit motion direction ("make it cinematic", "feel alive", "move like signage"),
directpicks the register and notes the source inregisterRationaleas"user-phrase: <verbatim>". -
extensions.divergence— full audit trail per the v2 storage shape indivergence-toolkit.md. Includes the brand-faithful inversion log (perreference/direction-format.md§ Divergence inputs) capturing pure-color or hex-format retentions. -
extensions.componentStyle— the abstract v1 fields (buttons,cards,inputs,dualCTAPattern). Default treatment per component, no per-page dimensions or literal copy. -
extensions.systemComponentRoles— the abstract roles for named cross-page patterns (e.g.persistent-help,cta-band,header,footer). Each role carries purpose, position class, and any site-wide constraint — not literal copy, dimensions, or per-viewport dock points (those are page-deployment, in<slug>-shape.md). -
extensions.voice— sampled DOs and DON'Ts derived from_brand-extraction.jsonvoice samples + the resolved tone. -
narrative.northStar,overview,keyCharacteristics,rules,dos,donts— derived from the resolved direction. Toolkit § 7 Optional House Standards land here innarrative.rules[].
Every component HTML/CSS snippet in components[] must be
self-contained, use ds- class prefixes, and respect impeccable's
hard rules (OKLCH only, no pure black/white, no glassmorphism, no
side stripes, no gradient text, ≥ 1.25 type ratio for brand
register).
IA-priority preservation audit (Mode A)
After tokens are drafted but before they land in the variant DESIGN
files, run the IA-priority preservation audit per
reference/intent-dimensions.md § 8. For each captured signal that
fires a trigger condition (commercial conversion, search-led IA,
donation funnel, crisis affordance, audience routing), record an
extensions.iaPriorities[] entry in DESIGN.json:
[
{
"signal": "crisis-affordance",
"evidence": "pages/home.json#landmarks[hero] contains heading 'Looking for immediate shelter?' + phone 801-990-9999",
"preserveAs": "first-viewport",
"scope": "site-wide",
"mutability": "movable"
}
]
Each entry is a constraint that downstream prototype and migrate
must honor — a variant whose home shape brief omits the crisis
affordance from the first viewport fails the audit and is rejected.
The audit is the structural enforcement of § 8; without it, IA-
priority preservation is a guideline rather than a contract.
The mutability field reflects the ia-fidelity stamp from Phase 1
(per reference/intent-dimensions.md § 9): locked under verbatim
(variants may not move the priority at all — A1/A2/A3 are surface
forks), movable under reimagined (variants may demote / promote /
re-shape the priority's deployment, but the § 8 floor still fires).
The field is stamped once at Phase 4 and is the source of truth
prototype reads.
Multi-variant DESIGN files (when N > 1)
When Phase 2.6 is active, Phase 4 writes PRODUCT.md (shared)
plus per-variant DESIGN-{A,B,C,…}.{md,json} instead of a single
pair; every variant inherits the shared extensions.iaPriorities[]
audit. Under rebrand mode PRODUCT.md may also vary per variant.
See reference/multi-variant.md § Multi-variant DESIGN files.
Phase 5 — Write direction.md and update state
Write stardust/direction.md per
skills/direct/reference/direction-format.md. The full reasoning
trace: phrase, restatement, movements, gaps, questions and answers,
resolved axes, divergence inputs, command sequence proposed, user
confirmation, every assumption that defaulted in. Re-directs append
to the file as a new section; prior direction stays as history.
Update stardust/state.json:
direction.resolvedAt= nowdirection.phrase= the user's verbatim phrasedirection.directionFile="stardust/direction.md"- For each page in scope:
statusextracted→directed - On
--re-direct, for each page already inprototyped/approved/migrated: setstale: trueandstaleReason: "direction changed at <ts>". Do not change the status itself; the on-disk artifact is still valid, just out of step.
Print a one-screen summary report and recommend the next step:
direction resolved
==================
Phrase: "make it more expressive for a young audience"
Audience: Gen Z college / first-job (resolved via Q1)
Register: brand (inherited from current/PRODUCT.md)
Movements:
expressive axis restrained -> committed
distinctiveness familiar -> distinctive
tone serious -> playful
density (unchanged)
audience (resolved: Gen Z college / first-job)
Divergence:
seed 1970s x Riso print x zine x monochrome-tint
font deck zine-maximalist
palette "Brutalist Dawn" (picked from library)
Wrote:
PRODUCT.md, DESIGN.md, DESIGN.json
stardust/direction.md
State:
25 pages: extracted -> directed
0 stale prototypes (none exist yet)
Next: $stardust prototype (defaults to home page)
Outputs
| Path | Purpose |
|---|---|
PRODUCT.md | Target strategy (impeccable format). Shared across variants when N > 1 under Mode A. |
DESIGN.md | Target visual system (Stitch frontmatter + 6 sections). Single-variant runs only. |
DESIGN.json | Sidecar with extensions (divergence, componentStyle, voice, iaPriorities) and narrative. Single-variant runs only. |
DESIGN-{A,B,C,…}.md | Per-variant DESIGN files when the user requested N > 1 variants (Phase 2.6 active). |
DESIGN-{A,B,C,…}.json | Per-variant DESIGN sidecars matching the .md files. |
stardust/prototypes/<slug>-improvements.md | Improvements list (Mode A only, written in Phase 2.5). The load-bearing artifact for variant A. |
stardust/direction.md | Resolved direction + full reasoning trace + per-variant resolutions when N > 1. |
stardust/state.json | Updated with direction + per-page status changes + direction.variantMode + direction.variants[] when N > 1. |
Failure modes
- No extracted state. Abort and recommend
$stardust extract. - Phrase too vague even after two questions. Persist the partial
reasoning to
stardust/direction.mdunder a# Pendingsection, ask the user to refine further, do not writePRODUCT.md/DESIGN.md/DESIGN.jsonfrom incomplete reasoning. - Re-direct with prior approved or migrated pages. Always confirm before stale-flagging. The flag is visible to the user and reversible (clearing happens automatically on successful re-run of prototype or migrate), but a re-direct invalidates work the user may have signed off on.
- Anti-toolbox audit removes too many moves. If the resolved direction collapses to defaults after the audit strips unjustifiable hits, surface this to the user and re-prompt for reference anchors before writing tokens.
- (b) Insufficient brand signal for N variants. Fewer than 3
distinct amplifiable traits in the captured surface (or
signal-thin) → refuse N ≥ 3 under Mode A and propose 1–2 variants instead; full contract inreference/multi-variant.md§ Failure mode. - (c) Hard rule conflict. When Mode A is active and the
user's phrase requires violating a Mode A pin (e.g., the user
asks for "a completely different palette" while migration mode
is active and
--rebrandwas not passed), stop. Name the conflict explicitly: "You asked to keep the brand and to change the palette — those are not compatible. Did you mean (a) keep the current palette and only refresh execution, (b) rebrand (--rebrand) and roll a new palette, or (c) Mode A with a targeted palette move (single role recolored, rest pinned)?" Wait for explicit answer. - (d) Empty improvements list. When Phase 2.5 produces fewer
than 3 weaknesses meeting the specificity bar, stop before
rendering any variant. Variant A's brief depends on the list;
without it, the "better" claim fails. Surface honestly:
"the captured site is already at a competent execution level on
observable dimensions — variant A would reduce to spacing and
contrast adjustments only." Ask the user whether to (a) proceed
with reduced scope (density + contrast only), (b) extract
additional pages (
extract --cap 25or higher) to surface more weaknesses, or (c) pivot to rebrand mode (--rebrand) where the brand-fidelity floor doesn't apply.
Prep mode (--prep)
When invoked with --prep, direct runs an extended pass that
finalizes the inventory data structures migrate consumes: type
catalog confirmation, module catalog finalization, color
reservations, a wider direction re-evaluation, and site-level
metadata defaults. Read reference/prep-mode.md and follow it on
top of the standard procedure. Discovery-mode runs are unchanged.
Add-variant mode (--add-variant)
When the user has already approved (or rendered) variant A and
asks for B / C / etc. as alternatives, --re-direct is too heavy
— the user is extending the existing direction, not changing it.
--add-variant <name> skips Phases 1–2 (mode, seed, palette, and
ground family are inherited from the active direction), resolves
the new variant's role per the variant role contract, and writes
DESIGN-<name>.{md,json} plus a ## Variant <name> section in
direction.md, without stale-flagging any page. Read
reference/add-variant.md and follow its procedure, parentage
and per-field inheritance rules, and failure modes before
writing anything.
References
skills/stardust/reference/intent-dimensions.md— the 8 axes (the 7 axes plus § 8 IA-priority preservation, the Mode A constraint that fires on captured commercial-conversion / crisis / audience-routing signals).skills/stardust/reference/intent-reasoning.md— the procedure.skills/stardust/reference/intent-examples.md— worked examples.skills/stardust/reference/impeccable-command-map.md— when to reach for each impeccable command (used when building the plan).skills/stardust/reference/reference-research.md— the research-first anchor procedure (refero MCP → WebSearch → seed fallback) consumed by Mode B and Default mode; evidence shape and budgets.skills/stardust/reference/divergence-toolkit.md— anti-mediocrity inputs and the v2 storage shape for the audit trail. Contains the anti-toolbox additions for multi-variant moves (C-cliff overshoot,Anonymous middle variant,Variant homogeneity) and universal hardening (Fabricated content,Hero text on photographic background without contrast scrim,Editorial-register vocabulary applied to non-editorial brands).skills/stardust/reference/artifact-map.md— provenance shape.reference/direction-format.md— schema forstardust/direction.md.reference/palette-picker.md— palette resolution procedure.reference/prep-mode.md— the--prepextended pass (provenance validation, type/module catalogs, color reservations, metadata).reference/add-variant.md— the--add-variantflow (procedure, variant parentage, per-field inheritance, failure modes).reference/multi-variant.md— the N > 1 fork: variant role contract, differentiation contract, surface forks, C-cliff.reference/improvements-list.md— worked examples for the Phase 2.5 improvements list (categories + format).reference/mode-a-plus.md— bounded brand-adjacent refinements.reference/cross-site-brand-inputs.md— design-donor and sibling-origin evidence rules.
stardust:dynamics — the dynamic surface of a migration
Static migration treats a page as content and layout. This skill treats it as behaviour: everything the source renders from JavaScript, a service or a data source, and everything the target host cannot serve the same way. Three real migrations found the same thing: the dynamic surface is invisible to a block-scoped, pixel-verified pipeline — and invisible in a way every gate certifies as correct. Modals rendered as links, video pills as CTAs without targets, a search box as a 404, forms that rendered and could not submit. This skill makes that surface visible and forces a decision per row before import, then proves the behaviour after delivery. It never blocks the static path; every page must still work as a static page.
When it runs — migration-bound, default-on there, never elsewhere
| entry point | what runs here |
|---|---|
prepare-migration Phase 4.5 · replica Phase 2 | Phases 1–3 (detect on archetypes, classify, triage) — the pre-import gate |
migrate Phase 1 | safety net: no inventory → run Phases 1–3 now (hand-run extract → direct → prototype → migrate never passed a gate) |
deploy | reads the inventory as brief input (fallback rows, #modal markers, endpoint config; never flatten client-only / modal-bearing sections) |
rollout B2 · D2 | B2 verifies the inventory against fresh evidence; D2 = Phase 4 for the self set + one owner batch |
qa dynamics check · rollout report | Phase 5 replay of parity.json |
standalone $stardust dynamics <origin> | all phases on a site that was already migrated without them |
uplift, audit and a bare extract never trigger it: dynamics is a migration concern (EDS today,
other platforms later), not a redesign one.
Phase 1 — Detect
node skills/dynamics/scripts/dynamics-detect.mjs --from-state stardust/state.json --out stardust/current [--reach stardust/current]
(or --urls one per archetype + the home page). Depth on archetypes, reach from the crawl's
extract --dynamics per-page signals. Output stardust/current/_dynamics.json +
dynamic-features.generated.md. Evidence only. reference/classes-and-signals.md. For every
search form found, run one probe term on the SOURCE and record what it shows — the visible result
count, the top titles (≤ 3), one known hit — as expectCount / expectTitles / expectIncludes
on the feature's search-query check (Phase 5; a spec's knowledge/search-probes.json already
holds them); without them the rebuilt search can only be checked for presence.
Phase 2 — Classify
Every finding gets a class from L S F M V T A R X I18N CR D; known vendors resolve to a role
through scripts/vendors.json; unknown third-party hosts stay visible as "inspect". When a target
host exists, dynamics-plan.mjs --target-origin <host> probes every recorded first-party API path
there and marks dead ones host-bound — the signal a pixel gate reports as "band shorter".
Phase 3 — Triage (the gate output)
node skills/dynamics/scripts/dynamics-plan.mjs [--target-origin …] [--migrated stardust/migrated] [--knowledge] [--chrome] --out stardust/dynamics
drafts one row per finding with the four axes pre-filled — class · disposition ·
reproducibility · status — plus pattern, phase, the owner decision and target, the delivery form
(widget where no authored rows remain — reference/triage.md § Target); --knowledge adds a spec's
curated features, decisions from its open questions; --chrome a row per header-contract family (cart and
account decide their backend, the UI ships). Curate it into stardust/dynamic-features.md (§ Listings
contract + § Features + § Decision batch + § Register) and stardust/dynamic-features-plan.md.
reference/triage.md is the contract. Rules that decide the shape of the phase:
- Reconcile against the migrated output before scheduling anything.
- Only reproducibility
selfships autonomously; everything else is one decision batch. - Never fabricate copy for a blank client-rendered capture; never auto-wire a
regulated-piiform; a search box implies a results page; decided-out is explicit and owner-stated — a hands-off assumption never writes it. - Gate: a row without a disposition fails prepare-migration 4.5 / replica Phase 2 / rollout B2. The static migration continues regardless.
- Martech only on request: when the owner asks to keep tags or consent, add
--martech(reference/martech.md); everything is scaffolded off.
Phase 4 — Implement (per plan phase)
From reference/patterns.md (catalogue + contracts + embedded example mechanisms),
reference/listings.md, reference/off-origin-data.md, reference/forms.md,
reference/locale-trees.md. Principles that held on three sites: static first, then wire ·
authoring contract before code · no owner input, no waiting (ship the interim tier, name the
decision) · existing library first (feed it, do not fork it) · decided-out is explicit. Each phase
ends with the flow verified on the published origin at 1440 and 360, a parity row, a journal entry
and a commit. Tooling: snapshot-api.mjs, snapshot-forms.mjs, sync-sheets.mjs. A flow script you write
follows the recipe in ../stardust/SKILL.md § Setup, step 7. The query index
comes from helix-query.yaml in the code branch — commit, push, publish live, poll — never from a
configuration-service write; the sheet-backed interim index only when the branch is not writable
(reference/listings.md § Getting an index at all). Search follows reference/patterns.md
§ search-index-backed. Listings and data-fed bands are document-first: the document carries the item text as authored rows, the block reads the index or snapshot only for non-text fields and top-up (reference/listings.md § Block contract; why: deploy/reference/ai-readability.md).
Phase 5 — Verify: dynamic parity
Write stardust/dynamics/parity.json (reference/parity-report.md) with replayable checks from the
closed set; node skills/dynamics/scripts/dynamics-check.mjs --origin <published origin> [--auth-header … | --token-env SITE_TOKEN]
writes stardust/qa/dynamics-report.md. Flows, not presence. A search-query check compares the
result COUNT and the top titles with the source's recorded values — a count mismatch fails. The site
secret rides an origin-scoped route filter only; third-party request statuses are recorded next to
every assertion.
Hands-off resolutions
| gate | resolution |
|---|---|
| owner decision (backend, tags on the new host, datasource ownership, locale scope) | ship the interim tier, record the decision by name in the plan and parity report, continue — never as decided-out, which takes an owner's statement or a hard blocker |
| unknown third-party host | classify from the XHR body; else T "inspect" — never drop silently |
| blank client-rendered capture | hard content gap → human-capture batch; never migrate blank |
| regulated-pii form | UI rebuilt, submission blocked, mandatory decision |
| hand-off target unreachable from the test network | environment-limit row with the egress region; not a defect |
| content source cannot receive submissions | local capture with an explicit "no backend connected" message; decision named |
Hard blockers (event: "blocked")
Source unreachable from the probe network; target config not writable when endpoint indirection is required; an interim tier that would capture regulated data (record as decided-out instead).
Artifacts
stardust/current/_dynamics.json, dynamic-features.generated.md · stardust/dynamics/dynamic-features.generated-plan.{md,json} ·
stardust/dynamic-features.md, stardust/dynamic-features-plan.md (curated) · helix-query.yaml (listings + search, committed in the code branch) ·
data/<feature>/*.json + _provenance.json (snapshots, code bus) · scripts/site-config.js (owner-facing integrations, disabled) ·
stardust/martech-contract.json, martech-handoff.md, scripts/martech.js (opt-in) ·
stardust/dynamics/parity.json · stardust/qa/dynamics-report.{md,json} · register rows · journal + status lines.
References
reference/classes-and-signals.md— the class axis, detector procedure, vendor table policy, origin-bound probe.reference/triage.md— the four axes, rules, the inventory file format.reference/patterns.md— catalogue: contracts + verification per pattern, example mechanisms.reference/listings.md— metadata contract + query-index mechanics (formerly rollout's dynamic-listings).reference/off-origin-data.md— feeding an existing library off-origin; sheet-backed data; chrome URL space.reference/forms.md— controls not form tags; intake by content source; regulated data.reference/parity-report.md— schema, check types, rules.reference/locale-trees.md— I18N as a tree.reference/martech.md— opt-in martech contract, owner enablement, runtime, verification.scripts/—dynamics-detect.mjs,dynamics-plan.mjs,dynamics-check.mjs,snapshot-api.mjs,snapshot-forms.mjs,sync-sheets.mjs,vendors.json,lib.mjs,martech.mjs.
stardust:extract
Crawl an existing website, parse each page, extract the brand surface,
and produce a stardust-formatted snapshot of the current state under
stardust/current/. The output describes what the site is; later
sub-commands consume it to decide what it should be.
This skill is descriptive: it does not invent direction, it does not
critique, and it does not modify the live site. It writes only under
stardust/current/ and updates stardust/state.json.
Inputs
<url>— required. The origin to crawl. Examples:https://example.com,https://example.com/shop. A path narrows the same-origin crawl to that subtree.--cap <N>— optional. Override the default 5-page cap. The cap is intentionally small — a 5-page sample (home + four IA pillars/templates) is enough for cross-page brand aggregation, system-component detection, and the brand-review HTML; lift it (e.g.--cap 25) when a deeper crawl is genuinely needed.--all— optional. Lift the cap entirely; extract every discovered page after junk filtering. Equivalent to--cap 0. Use when the user spontaneously asks for a full crawl.--pages <slug,slug,...>— optional. Restrict the crawl to specific paths (slugs derived perreference/ia-extraction.md). Bypasses the cap.--refresh <slug>— optional. Re-extract one page that already exists instate.json.--single— optional. Equivalent to--cap 1. Useful for testing.--wait <fast|medium|spec|auto>— optional. Wait strategy per page. Defaultmedium. Seereference/playwright-recipe.md§ Wait modes.--no-junk-filter— optional. Disable the default junk-page filter in discovery (seereference/ia-extraction.md§ Filtering).--no-consent-dismiss— optional. Skip the pre-flight consent / cookie banner dismissal (seereference/playwright-recipe.md§ Pre-flight: consent dismissal). Use when the redesign scope includes the consent surface or the dismissal's side-effects (script activation that wouldn't otherwise run) must be avoided. Default is to dismiss, keeping screenshots, voice aggregation, and per-section style unpolluted by the banner.--dynamics— optional, migration-bound. Record per-page reach signals of the dynamic surface (data endpoints, forms, modal triggers, player ids) in each page JSONdynamicsection and roll them up in_crawl-log.json#dynamicSurface. Set byprepare-migration,replicaandmigrate's safety net; never by a bare extract,upliftoraudit— dynamics is a migration concern. Depth and classification belong to the stardustdynamicsskill.--concurrency <n>— optional. Parallel browser contexts for the per-page capture loop. Default 4; sane range 4–8. See § Concurrency.--brand-source <url>— optional, repeatable. An additional same-brand origin whose brand surface enriches the primary extraction (shallow capture: home + up to 2 nav-linked pages). See § Cross-site brand sources.--design-source <url>— optional. Design-donor origin: its design system is captured tostardust/canon-source/and becomes the fixed redesign target while the primary origin supplies content. See § Cross-site brand sources.--prep— optional. Run in migrate-prep mode: lift the cap, type each page, detect module candidates, capture typed content slots, emit the prep summary. See § Prep mode below. Typically invoked via theprepare-migrationorchestrator skill rather than directly.
Setup
Run the master skill's setup procedure first
(skills/stardust/SKILL.md § Setup): impeccable dep check, context
loader, state read.
Additional checks for this sub-command:
-
Playwright availability. The extraction step needs a real browser. Detect Playwright in this order: a Playwright MCP server, then a project-importable
playwrightmodule. Thenpx playwrightprobe is NOT sufficient — it confirms the CLI (which resolves a global install) but the recipe andscripts/crawl.mjsloadplaywrightthroughbrowser.mjs, and ESM module resolution does not honour a global install orNODE_PATH— the import throwsERR_MODULE_NOT_FOUNDeven wherenpx playwright --versionsucceeds. Verify the module is import-resolvable from the project root (probe:node -e "import('playwright').then(()=>process.exit(0))"); if it isn't, runnpm i -D playwright pixelmatch pngjs cheerio --legacy-peer-deps(devDependencies, never--no-save— #125) or use the Playwright MCP server, before crawling. The--legacy-peer-depsflag is required onaem-boilerplatetargets (their pinnedeslint@8makes a plainnpm iexitERESOLVEbefore playwright is even considered). Don't trust the CLI probe alone.--no-saveinstalls are ephemeral. Any later realnpm i(e.g. a setup step adding a devDependency) prunes non-manifest packages, silently removing playwright mid-pipeline. Every downstream skill that renders (prototype, migrate, deploy, diff) must re-run the import-resolvability probe — and re-install on failure — at the start of its own run, not assume extract's install survived.Script location matters. ESM resolves
import 'playwright'from the script's directory and the plugin tree ships nonode_modules: copy every script byte-identical into the project (stardust/scripts/…), the master skill's too (../stardust/SKILL.md§ Setup, step 7), and run the copy.Bundled crawler.
skills/extract/scripts/crawl.mjsis a runnable reference implementation of this whole sub-command — browser config + bot-management fallback, consent dismissal, wait- scroll, the capture list, per-page full-page screenshots
(
assets/screenshots/<slug>.png, consumed by the Phase 2.5 vision gate), response validation, and the § Capture-hygiene hardening (visibility filter, interstitial drop, SPA-shell flag, modaltextContentcapture, tracking-pixel discounting, cross-page duplicate detection). Prefer invoking it over hand-rolling a Playwright script per run; extend its in-pagecapture()to cover any recipe field it doesn't yet emit.
- scroll, the capture list, per-page full-page screenshots
(
-
Origin collision. If
stardust/state.jsonalready recordssite.originUrland the new<url>is a different origin, stop and ask before clobbering. Stardust does not silently mix two sites in one project. Flow guard (migration asks only). If the ask carries migration intent ("migrate", "to EDS", "re-platform", "1:1", "replica") andstardust/state.jsonexists — or is about to be created — withoutflow, hand back to the master skill § Two migration flows before crawling: the flow is chosen and stamped there, and a keep-design ask enters throughreplica(which invokes this skill with--prepitself). A bareextract <url>for a redesign, audit or uplift is unaffected. (Recorded:extracton a raw URL as the entry of a same-design migration; the agent then built its own importer besidereplica.) -
Browser contexts. Open a fresh
BrowserContextper capture worker (§ Concurrency; default 4). Run the consent dismissal pre-flight perreference/playwright-recipe.md§ Pre-flight: consent dismissal unless--no-consent-dismissis set. Cookies persist within a context but not across contexts — re-establish consent state per context (re-run the dismissal on the worker's first page, or clone the probe context'sstorageState). Record the resolved method in_crawl-log.json#consent.method. -
Bot-management probe. When the first navigation in the run returns
ERR_HTTP2_PROTOCOL_ERRORorERR_QUIC_PROTOCOL_ERROR, or hangs through the entire hard-cap on what should be a fast origin, do not retry headless — switch to headed Chrome per § Failure modes → Bot-management block and record the switch in_crawl-log.json#discovery.fetchTechniqueso re-runs start in headed mode without rediscovering the issue.
Procedure
Phase 1 — Discovery
Discover the page inventory before crawling. Procedure in
reference/ia-extraction.md. In summary:
-
Fetch
<origin>/sitemap.xml, then<origin>/sitemap_index.xml, then checkrobots.txtforSitemap:directives. -
If no sitemap is reachable, run a same-origin BFS crawl from
<url>, depth-limited to 3, link-extracting from rendered HTML. -
Filter the discovered URL list: same origin only, exclude
mailto:,tel:, anchor-only links, query-only variations, common asset paths (.css,.js,.pdf, image extensions). -
De-duplicate trailing-slash variations.
-
Apply the junk-page filter (
reference/ia-extraction.md§ Junk-page filter) unless--no-junk-filteris set. Surface the filtered list to the user as overridable. -
Apply the cap (default 5, or
--cap, or--allfor no cap) and proceed silently. Print an informational summary of what was kept and what was cut — but do not gate on user confirmation. Users who want different scope set it spontaneously at command time:$stardust extract https://example.com # default 5 pages $stardust extract https://example.com --cap 25 # bump to 25 $stardust extract https://example.com --all # lift the cap $stardust extract https://example.com --pages home,about,pricing $stardust extract https://example.com --single # just the entry URLThe agent reads spontaneous scope intent from the user's prompt (e.g. "extract all pages", "look at just the home and pricing", "do a full crawl") and applies the equivalent flag. No re-confirmation needed once intent is clear.
Informational output (not a prompt — proceed immediately):
Discovered 38 pages on https://example.com (sitemap.xml). Filtered as likely junk (5): /test/, /sample-page/, /holiday1/, ... Selecting 5 highest-priority pages: - / (home) - /about - /pricing - /products - /contact Cut (28 pages, --all to lift): /blog/post-1, /blog/post-2, ... Extracting...Selection heuristic: when the user names N, link-first order (the entered page, then its links). Otherwise page-type checklist first, then score-based ranking. See
reference/ia-extraction.md§ Page selection and § Priority for the cap. -
Write the discovered list to
stardust/current/_crawl-log.json(created if absent) with_provenanceand the full discovery reasoning, includingfilteredAsJunk[]anduserChoice. This is an audit trail, not a state file.
Phase 2 — Per-page extraction
For each page in the cap-respecting list, render with Playwright
following reference/playwright-recipe.md. Captures run
concurrently per § Concurrency. The recipe is
mandatory per page — in particular, do not skip the wait, scroll, or
capture-list steps:
- Viewport 1440 × 900 @ 2× DPR
- Wait per the configured wait mode (default
medium; see § Wait modes inreference/playwright-recipe.md) - Disable animations via
prefers-reduced-motion: reduce - After the wait resolves, scroll to bottom in 4 viewport-height steps with 300 ms pauses, then return to top — this is required to trigger lazy-load and IntersectionObserver-driven content
- Record
waitMsandwaitModein the per-page_provenance
Capture per page (full schema in reference/current-state-schema.md):
-
Page metadata (title, meta description, OG tags, theme-color)
-
Semantic structure: heading outline, landmark roles, sections
-
Hero headline + lede (resolved) —
heroHeadline/heroLedepicked by font-size × hero-region with a junk/hidden-state filter and a clean meta-description fallback (perreference/playwright-recipe.md§ Capture list 5-bis). Required for JS-rendered sites whose document-order headings surface modal / promo / count junk instead of the real tagline. -
Content: visible text per section (full innerText, no truncation per
reference/playwright-recipe.md§ Capture list 7), structured paragraphs (body[]), lists, FAQ Q/A pairs, and review/testimonial quotes per § Capture list 7-bis. Without these structured fields, every body region under a heading falls back to placeholder signature at migrate time. -
CTA labels and href targets, link inventory (internal vs external)
-
Per-section computed style summary: dominant colors, font families in use, spacing rhythm, border-radius, shadows
-
Media inventory: img with
currentSrc/srcsetcaptured with query strings intact plus aresolvesflag (HEAD/GET with browser UA + Referer), intrinsic dimensions, inline SVG count, video/iframe presence,cssBackgrounds[](including pseudo-element::before/::afterwalks per § Capture list 11) sobackground-imageheroes and motifs do not silently disappear and 404ing CDN images are flagged before migrate shipsabout:error. -
Font files captured via network-intercept (per § Capture list 16): every
woff2/woff/ttf/otfresponse saved underassets/fonts/and recorded in_brand-extraction.json#type.files[]with licensing flag. -
Icon-font detection (per § Capture list 17): when the page uses
[class^="icon-"]with non-default::beforefont-family + codepoint, capture the family, save the file, and record theiconClass → codepointtable in_brand-extraction.json#iconFont. -
Interactive elements: forms (with field types), buttons, modals detected by ARIA roles
-
Full-page screenshot to
assets/screenshots/<slug>.png— script-captured by the bundled crawler after the wait/scroll settle (viewport-only fallback on extremely tall pages; mode in_signals.screenshotMode, relative path in the page JSONscreenshotfield) -
Dynamic surface (only with
--dynamics) — per-page reach signals: endpoints, third-party script hosts, forms, modal triggers, player ids, hydration hints, in the page JSONdynamicsection and_crawl-log.json#dynamicSurface(schema inreference/current-state-schema.md § Dynamic). Evidence only; the stardustdynamicssub-skill probes archetypes in depth and decides.
Save to stardust/current/pages/<slug>.json with _provenance as the
first key. The bundled crawler also saves the settled rendered DOM
verbatim as stardust/current/pages/<slug>.html (page.content()
after the wait/scroll settle; path in the record's renderedHtml
field). Capture once, parse offline: every downstream importer or
sibling generator iterates its extraction against this artifact —
free, reproducible, and provenance — instead of re-running live
probes per selector guess (recorded: 4+ live round-trips per page
family before the switch). Live probes stay for what the static DOM
cannot answer: geometry and computed styles. Save referenced media to stardust/current/assets/media/
preserving basename plus a short content hash.
Live-render evidence (synthesis is forbidden). Refuse to mark
a page extracted in state.json unless its _provenance
contains renderedBy: "playwright", an ISO-8601 fetchedAt, a
positive integer waitMs, a waitMode from the recipe, and a
final httpStatus in the 2xx/3xx range. These five fields are
the contract enforced by reference/current-state-schema.md
§ Live-render evidence and read back by every downstream phase
via validateProvenance() per
skills/stardust/reference/state-machine.md § Provenance
validation. Synthesizing a page record from
_brand-extraction.json plus URL patterns plus captured photos
— the 2026-04-30 e-commerce shortcut — is the failure mode this
guard exists to prevent. When the agent (or a delegated sub-
agent) cannot satisfy the contract for a page, treat the page
as a Phase 2 failure: record under _crawl-log.json#crawl.failures[]
with errorClass: "ProvenanceMissing" and continue.
Mark the page extracted in state.json immediately after each
successful page write. If a page fails, record the error in
_crawl-log.json and continue — extraction is best-effort per page.
Phase 2.5 — Vision verification
Before anything downstream is authored, look at each captured
page's screenshot (assets/screenshots/<slug>.png) — the multimodal
model reads the image — and verify it against the extracted record:
- Does the recorded hero (headline + asset) match what the pixels show?
- Is the extracted palette plausible against the pixels?
- Does a
cssBackgrounds: []record look believable, or is imagery visibly present — a silent capture failure? - Is the logo captured?
- Is the page actually rendered — not a consent wall, bot-block page, or blank SPA shell?
Read the whole page through its thumbnail —
node stardust/scripts/thumb.mjs stardust/current/assets/screenshots/<slug>.png --width 480
(skills/extract/scripts/thumb.mjs, copied beside crawl.mjs; a
box-filter downscale, so 1-px rules and hairline borders survive; its
--max-bytes cap, 150 KB by default, re-encodes a heavy page narrower
first and crops only as a last resort, never below 60 % of the page) —
never the full-resolution screenshot, and read any detail as a crop of
the full capture. The check is of the WHOLE page: read the script's
stdout line before the image, and when it prints a share below 100
(cropped at <n>px of <H> = <share>%) run the same command with
--offset <n> and read <slug>-thumb-<n>.png too, repeating while its
rows <n>-<end>px line ends short of <H>. A recorded hands-off run's
thumbnails kept a median 28 % of each page and the check read them as
the page. A thumbnail enters the context only after thumb.mjs has
written it (≤ 150 KB, or the floor thumbnail it named on stderr, exit 1)
— or the vision check runs in a subagent that reads the thumbnails and
returns one line per page
(<slug>: ok | recaptured | suspect — <note>); a recorded hands-off run
read eight *-thumb.png files of 268–608 KB each into one context —
3.2 MB of pixels for eight verdicts.
On mismatch, re-run that page's capture with the escalation ladder
before proceeding: bump the wait mode one step
(reference/playwright-recipe.md § Wait modes), then headed Chrome
(§ Bot-management fallback), then a fresh browser context. Record
the outcome per page in _crawl-log.json#visionCheck[]:
{ "slug": "pricing", "verdict": "recaptured", "notes": "record said zero CSS backgrounds; screenshot shows a full-bleed photo hero" }
verdict is "ok" | "recaptured" | "suspect" — suspect means the
mismatch survived the ladder; downstream phases treat that record as
unreliable. Vision is the authoritative capture check; the
heuristic defenses (low-media flag, spaShellSuspect, duplicate
hash) remain as cheap early signals but no longer gate alone.
Phase 3 — Brand-surface extraction
Run after the capture phases (2–2.5). Aggregation may proceed
incrementally as concurrent page captures complete (§ Concurrency),
but the written file must reflect every extracted page — including
brand-source pages per § Cross-site brand sources.
Produces stardust/current/_brand-extraction.json
per reference/brand-surface.md. Some fields are home-only (logo,
voice samples, register heuristic); the visual tokens that drive
DESIGN.md (palette, radius, shadow, type) are aggregated across all
extracted pages to avoid the home-page bias documented in
brand-surface.md § Aggregation scope.
Computed-style census — run the shipped instrument; author no
probe. node <plugin>/skills/extract/scripts/style-census.mjs
(copied into the project like crawl.mjs, § Setup) measures every
captured page at 1440 and writes
stardust/current/_computed-styles.json; add --width 360 when the
breakpoints include it. One more live pass over every page — run it
ONCE, after the crawl, in the background; it opens the live side
through the shared browser.mjs like every other live instrument. Read the
palette, type, motif and hover values from the file's aggregate and
cite each from its sources[] (url, selector, prop); the
per-page detail sits under pages[url][width].
Content-cap model — run the shipped probe; author no lift (#124).
node stardust/scripts/replica/cap-probe.mjs <archetype-url>… --write-design stardust/current/DESIGN.json (replica's script; it needs the master skill's scripts copied too)
renders each archetype at 1440 and at a DERIVED wide width —
max(2560, largest cap × 1.25); a probe AT a cap's width cannot see it — and
records every box that stops growing (kind shell / content / module,
px, authored via, tier) into extensions.breakpoints: containerMaxWidth
(the --max-width source; null when fluid), probeWidth, caps[],
modules[]. One navigation per archetype after the census (never beside
it), once DESIGN.json is authored (it merges). A cap on the shell or
on every archetype is design intent whatever its value; capRegister lists
single-module or archetype-divergent caps for the inconsistency register.
The cap model never records layout breakpoints: a redesign target keeps its own two;
replica keeps the source's, or maps them to --target-breakpoints.
Captures:
- Logo by the v1 priority chain: inline SVG →
<img>with logo-ish class/id →apple-touch-icon→og:image→ favicon → synthesized placeholder. Save tostardust/current/assets/logo.<ext>. - Favicon — ALWAYS captured as its own asset (independent of the
logo chain) to
stardust/current/assets/favicon.<ext>, perreference/playwright-recipe.md§ Favicon capture. Downstream,prototypeembeds it in the proposed page head anddeployships it to the Edge Delivery site. - Palette — aggregate computed colors across all extracted pages (background, text, accents, borders, hovers). Frequency-sort, cluster near-duplicates, emit a role-named list (background, surface, text, primary, secondary, accent).
- Type — font families in use with their weights, sizes, and
computed line-heights. Identify the heading family vs body family.
Run the modular-scale audit (
brand-surface.md§ Modular-scale audit) and emitscaleAudit.kind = "modular" | "ad-hoc". - Motifs — signature border-radius (cross-page mode of non-zero
values, weighted by element count), shadow stack (top 3 distinct,
cross-page), gradient inventory, common patterns (chip, badge,
card, hero-with-image). When the home-only mode disagrees with the
cross-page mode, surface the divergence in
_provenance.notes. - Voice samples — first paragraph of body copy, the hero headline,
3 representative CTA labels, a representative link list. Used by
directlater but extracted now so the network round-trip is over. - Hero image — elevate the home page's primary visual
asset to
voice.heroImage(perreference/brand-surface.md§ heroImage resolution), so downstream prototype picks the live hero rather than theog:imagefrom the raw media list. - Hero medium (signature) — when the hero/first viewport carries a
moving asset (background
<video>/ HLS / canvas / WebGL / Lottie / animated SVG / scroll-driven motion), elevate it tovoice.heroMedium(perreference/brand-surface.md§ heroMedium resolution). This is the page's signature; without elevation downstream prototype flattens it to a static hero. A non-nullheroMediumtriggers signature preservation (skills/stardust/reference/intent-dimensions.md§ 8b) at prototype time. - Icon font — when detected per
reference/playwright-recipe.md§ Capture list 17, populate_brand-extraction.json#iconFontwith family, file path, and theiconClass → codepointtable so prototypes can render the brand's actual icons. - System components — cross-page repeated DOM blocks (site
header, site footer, cross-promo strips, persistent CTAs,
breadcrumbs). Detected by heading-sequence + CTA-label fingerprint
per
reference/brand-surface.md§ System components. Required — these are usually the most load-bearing surfaces and must not silently disappear from the redesign target. - Origins — one entry per contributing origin in
_brand-extraction.json#origins[]perreference/brand-surface.md§ Origins. Single-origin runs emit a one-entry array; brand-source runs attribute widened evidence per origin.
Do not invent values. Every captured value cites a source selector or
URL in _brand-extraction.json for traceability.
Phase 4 — Seed stardust/current/PRODUCT.md and DESIGN.md
The current-state PRODUCT.md and DESIGN.md are descriptive, not
authored — there is no interview to run because the user is not
defining intent here, the agent is describing the existing site. Write
them directly using impeccable's format specs (impeccable's skill
directory is what node <plugin>/skills/stardust/scripts/impeccable-version-check.mjs --where
prints; read each spec by section, not whole):
- For PRODUCT.md, follow the section structure in impeccable's
reference/init.md§ Write PRODUCT.md. File order: stardust's<!-- stardust:provenance … -->block first (per../stardust/reference/artifact-map.md§ Provenance, as for every file this skill writes), then# Product, then the<!-- impeccable:product-schema 1 -->comment verbatim, thenPlatform(web),Users,Product Purpose,Positioning,Capabilities and Constraints,Brand Commitments,Evidence on Hand,Product Principles,Accessibility & Inclusion; omit a section rather than pad it. UnderBrand Commitmentsrecord the register guess from the brand surface (sites that read as marketing/landing →brand; tools/dashboards →product; ambiguous →brandwith a note), the observed brand personality and the observed anti-references.Evidence on Handlists what was captured understardust/current/with paths. PopulateUsers,Product Purpose,PositioningandProduct Principlesfrom the captured copy and the brand surface. Where the agent must infer, mark the section with_provenance: inferredand a one-line basis sentence. - For DESIGN.md and DESIGN.json, follow the format spec in
impeccable's
reference/document.md. Populate frontmatter (colors,typography,rounded,spacing,components) from the captured tokens. Theextensionsblock of DESIGN.json carries v1'scomponentStyle,motifs, andvoicearrays so nothing is lost, andbreakpoints— the cap-probe sizing model — verbatim.
Stardust does not invoke $impeccable init (formerly teach) or
$impeccable document for the current-state files: those commands write to project
root (the target) and run an interview. Stardust authors the
descriptive snapshot directly. The format spec from impeccable is the
contract; the runtime command is not.
The target-state PRODUCT.md and DESIGN.md at the project root are
written by $stardust direct in Phase 2 of the pipeline, not here.
Phase 5 — Render stardust/current/brand-review.html
After Phase 4 writes the descriptive PRODUCT.md and DESIGN.md, emit
the current-state brand review per
reference/brand-review-template.md.
The brand-review HTML is the first surface a human can eyeball to verify the extraction before committing to a redesign direction — misreads that are invisible in JSON (a wrong dominant radius, a missing system component, a single-page palette bias) are obvious to the eye while they are still cheap to fix (re-extract is fast; re-direct + re-prototype is not).
The template is mandatory. In particular:
- Run the Tensions detectors listed in
reference/brand-review-template.md§ Detectors. Each rule is mechanical; emit a tension card whenever the trigger condition matches. The review may ship with zero tensions if the data is too thin to evaluate, but the detectors must always be run. - Render in the brand's own captured colors and fonts, not a stardust shell.
- Embed all CSS; do not load external JavaScript or fonts unless the live site already does.
- Cite the source artifact for every section (e.g.
_brand-extraction.json § typeunder Typography).
If the data for a section is missing, omit the section — do not fabricate placeholders. The coverage callout at the top reflects what is missing.
Phase 6 — Update state and report
After all Phase 2-5 writes succeed:
-
Update
stardust/state.json(schema inskills/stardust/reference/state-machine.md):site.originUrl,site.extractedAt,site.pageCap,site.totalDiscovered,site.crawledpages[]— one entry per crawled page withstatus: "extracted", filledcurrentStatePath, emptyprototypePathandmigratedPathdesignSource— only when--design-sourcewas used:{ url, capturedAt, path }per § Cross-site brand sources
-
Print a one-screen summary:
Extracted https://example.com (5/38 pages, sitemap.xml) stardust/current/ PRODUCT.md, DESIGN.md, DESIGN.json, brand-review.html, pages/ (5), assets/logo.svg, _brand-extraction.json, _crawl-log.json Per-page evidence: slug live waitMode waitMs status media(img/bg) / yes medium 2380 200 38/6 /pricing yes medium 1940 200 9/0 ⚠ low-media /contact yes domcontentloaded(fb) 8000 200 3/0 ... Wait summary: 4 resolved at medium (avg 2.4s), 1 fallback (timed out at 8s) → /contact may be under-captured; consider --refresh Media summary: 1 page flagged low-media (/pricing) — see media-coverage check Vision check: 4 ok, 1 recaptured (/pricing) — _crawl-log.json#visionCheck Open stardust/current/brand-review.html to verify the extraction before running $stardust direct. Coverage note: extracted 5 of 38 discovered pages; 5 pages covering distinct templates is usually sufficient for the cross-page brand surface. Widen with --cap <N> or --pages. Next: $stardust direct (resolve a redesign direction)The per-page evidence table is mandatory. The
livecolumn isyeswhen_provenance.renderedBy === "playwright"ANDwaitMs > 0, elseno. Anorow means the page record was not produced by a live Playwright render — the visible column is the defense-in-depth signal for the failure mode the write-time guard exists to prevent (2026-04-30 e-commerce run). A maintainer scanning the summary should seeyeson every row.Compute the wait summary by grouping each page's
_provenance.waitModeand averagingwaitMs. List slugs whosewaitModeends in(fallback)(rendered as(fb)in the table for width) as candidates for--refresh.The
media(img/bg)column is the analogous defense-in-depth signal for imagery. It prints<count of media.imgs> / <count of media.cssBackgrounds>. Flag a row⚠ low-mediawhen the page reads as brand/marketing (registerbrand, or a landing/solution/ product template) yet hascssBackgrounds: []and few large rasters (nomedia.imgsentry with intrinsic width ≥ 600). That combination is the signature of a silently-failed background / lazy-media walk — a capture pass that specs the full background walk (playwright-recipe.md§ Capture list 11) yet silently produces nothing still ships an image-less capture (2026-06-26 a SaaS site:cssBackgrounds: []on every page, all product imagery lost). A flagged row is the cue to re-run that page with--refresh(and, if it persists, to fall back to headed Chrome per § Bot-management fallback). A maintainer scanning the summary should treat abrand-register site with all-zerobgcounts as suspect, not as "this site uses no background images."
Cross-site brand sources
Two flags widen extraction beyond the primary origin — read
reference/cross-site-sources.md in full whenever either flag is
present. Both are opt-in; without them this section is inert.
Core contract (merge rules and capture shapes in the reference):
--brand-source <url>(repeatable) — a same-brand sibling gets a shallow capture (home + ≤2 nav-linked pages, full recipe + provenance) understardust/current/brand-sources/<host>/. Evidence, not inventory: never entersstate.json.pages[]. Its palette/type/motif/voice evidence aggregates into_brand-extraction.jsonwith per-origin attribution (origins[]); conflicts resolve toward the primary; widened traits are attributed, never invented. Excluded from system components,voiceTable, and cross-promo detection.--design-source <url>— a design donor is captured tostardust/canon-source/(same shapes ascurrent/, default cap), its descriptive DESIGN.md/json derived per Phase 4 rules, andstate.json.designSource = { url, capturedAt, path: "stardust/canon-source/" }stamped.directpins the donor system as the target (its § Mode A); donor evidence never aggregates into the primary_brand-extraction.json.
Sibling-site discovery
After the primary crawl (Phases 2–2.5), harvest candidate same-brand origins from evidence already captured — no extra navigation:
- footer / nav links out to other properties
- "our brands" / "our companies" pages
hreflangalternates on other domains- subdomain families (
shop.,careers., country subdomains) og:site_namematches across captured pages
List candidates with confidence + the evidence line in the crawl
report and in _crawl-log.json#siblingCandidates[]:
{ "origin": "https://example.co.uk", "confidence": "high", "evidence": "hreflang alternate on 4/5 pages", "decision": "included" }
- Interactive: propose — "found 3 candidate sibling properties —
include as
--brand-source?" — and proceed on the answer. - Hands-off (
state.json.handsOffis true): auto-include up to 2 high-confidence candidates as brand-sources; record the decision insiblingCandidates[].decision.
Discovery is capped and cheap: harvesting reads captured evidence only, and each included sibling gets the shallow brand-source capture (≤ 3 pages). It must never balloon the crawl.
Outputs
| Path | Purpose |
|---|---|
stardust/current/PRODUCT.md | Descriptive strategy of the existing site (impeccable format) |
stardust/current/DESIGN.md | Descriptive visual system (Stitch format) |
stardust/current/DESIGN.json | Sidecar with extensions for motifs, voice, components |
stardust/current/brand-review.html | Self-contained visual review of the extraction (first eyeball-able artifact) |
stardust/current/pages/<slug>.json | Per-page parsed structure + content |
stardust/current/pages/<slug>.html | Settled rendered DOM (crawler sidecar; parse offline, never re-scrape) |
stardust/current/assets/logo.<ext> | Extracted logo |
stardust/current/assets/favicon.<ext> | Site favicon (first-class asset; prototype head + deploy consume it) |
stardust/current/assets/media/ | Extracted media referenced by pages |
stardust/current/assets/screenshots/ | Per-page full-page screenshots, script-captured by crawl.mjs (Phase 2.5 vision gate + brand-review) |
stardust/current/_brand-extraction.json | Consolidated brand surface (palette, type, motifs, voice, system components) |
stardust/current/_crawl-log.json | Discovery + crawl audit trail (incl. visionCheck[], siblingCandidates[]; dynamicSurface reach roll-up only with --dynamics) |
stardust/current/brand-sources/<host>/ | Shallow same-brand captures (only with --brand-source) |
stardust/canon-source/ | Design-donor capture + descriptive DESIGN.md/json (only with --design-source) |
stardust/state.json | Updated with site + per-page status (+ designSource stamp) |
Concurrency
Page captures run concurrently: the Phase 2 queue is drained by
4–8 parallel browser contexts (--concurrency, default 4). Each
worker owns its BrowserContext; consent state is re-established per
context (Setup step 3). Media resolves / HEAD checks are batched
with Promise.all. Brand-surface aggregation (Phase 3) may proceed
incrementally as pages complete, so long as the written
_brand-extraction.json reflects every extracted page. The bundled
crawler implements the pool (crawl.mjs --concurrency <n>).
Across processes, per state-machine.md: stardust does not lock. Two
concurrent extracts on the same project are last-write-wins. Document
this in the user report; do not engineer around it.
Failure modes
- Network failure mid-crawl. Continue, record in
_crawl-log.json, end with a partial state. State.json reflects only successfully extracted pages. User can re-run; already-extracted pages are skipped unless--refresh <slug>. - HTTP 4xx/5xx, non-HTML content, soft-404s. Validated explicitly
per
reference/playwright-recipe.md§ Response validation. Each produces a distinct error class (HTTPError,ContentTypeError,EmptyPageError) recorded in_crawl-log.json#crawl.failures[]. Failed pages do not appear instate.jsonasextracted— they appear only in the failure log. Without this validation a 5xx page silently lands as an empty success and propagates wrong data todirectandprototype. - Login wall. Do not attempt to authenticate. If the home page redirects to a login screen, capture that one page, mark the rest as unreachable, and ask the user how to proceed (provide cookies via Playwright config, change the entry URL, or scope to public pages).
- Bot-management block (Akamai / Cloudflare / F5 / Imperva / CloudFront).
When the first navigation returns
ERR_HTTP2_PROTOCOL_ERROR,ERR_QUIC_PROTOCOL_ERROR, or hangs through the hard-cap on a TLS/H2 fingerprint check, the issue is JA3/H2 fingerprinting on bundled-chromium-default headless mode — not auth, not network.crawl.mjsruns the fallback itself, window-free: real Chrome headless (channel: 'chrome', its own identity, no launch flags) first, bundled Chromium only when Chrome is missing, one real-Chrome relaunch with the challenge-solve window on an entry-page block, and a wall — an edge 403 or a 200 verification interstitial — is named within seconds in_crawl-log.json(discovery.botBlock, per-pageBotChallengefailures), never captured as content (node crawl.mjs --help; a hand-rolled recipe followsreference/playwright-recipe.md§ Bot-management fallback). Note for asset harvest: a page-level bot wall usually does NOT gate assets — media/CSS/font URLs commonly return 200 to a plain browser-UA curl even while every page navigation is challenged (Cloudflare challenge, field-confirmed). Probe one asset with curl BEFORE reaching for in-page-fetch machinery; the in-page harvest is the fallback, not the default. - JavaScript-only content. Playwright already handles this. If
the configured wait condition never fires within the mode's hard
cap (
reference/playwright-recipe.md§ Wait modes), fall back todomcontentloadedand capture what is rendered. Record the fallback in the per-page_provenance.waitModeand surface in the wait-summary line of the final report. - Synthesis attempt (forbidden). When the agent (or a delegated
sub-agent) cannot run a real Playwright render for a page —
whether due to time pressure, token budget, or a tool/network
failure — the only correct outcome is to record the page as a
Phase 2 failure (
errorClass: "ProvenanceMissing"in_crawl-log.json#crawl.failures[]) and continue. Synthesizing a page record from_brand-extraction.jsonplus URL patterns plus captured photos at "semantically matching" template positions is forbidden. The shortcut produces output indistinguishable from a successful run and propagates fabricated content through every downstream phase (2026-04-30 e-commerce run: 20 of 25 pages synthesized, caught four phases later).
Prep mode (--prep)
When invoked with --prep, extract runs an extended pass that
prepares the inventory for migration — read
reference/prep-mode.md in full before running any --prep
extraction. Discovery-mode runs (without --prep) are unchanged:
small cap, no typing, no module detection. The flag is intended for
the prepare-migration orchestrator, though direct invocation is
supported.
Core contract (procedure, formats, and detection rules in the reference):
--prepimplies--allunless the user named N (then--cap N,reference/prep-mode.md§ 1) — migration coverage requires the full junk-filtered inventory, not the discovery cap.- Page types (
landing | article | listing | program | form | static | unique) are LLM-inferred intostate.json.pages[].type(discovery-mode runs leavetypenull); the user confirms indirect --prep. - Module candidates (cross-page structural repeats, detected by the
signal-source priority in the reference) are drafted under
DESIGN.json.extensions.modules[]withstatus: "candidate"; per-page JSON gains a typedslotssection per page-type. - Locale-root capture gaps are settled before Phase 2 of any flow.
After the crawl,
crawl.mjstakes every captured locale root (a one- or two-segment path of locale codes —/en,/fr-ca,/ca/en), lists the same-origin targets linked from that page under its own path, and marks the ones missing from the capture:_crawl-log.json#captureGaps(roots[]withroot,slug,linked,uncaptured[], plusdetail, a ready ledger string) and one[crawl] capture gaps:stderr line. Copyroots[]tostate.json.site.captureGaps(thesiteblock is extract's; an uncaptured target never becomes apages[]row) and carrydetailverbatim in the ledgerendline that closes the extraction —ledger.mjs extract prep end --detail "… uncaptured first-level targets: ca/en 15, fr/fr 0"(replica'sextract endrepeats it) — so the owner decides on the gap now (widen with--pages, or record it as scope debt), not in the rollout link audit: two recorded hands-off runs captured/ca/enas a locale root while 15/ca/en/*pages existed on the source, and found out six hours later, when 15 links answered 404 and the gap exceeded the 12-page deliver threshold. - The header contract is recorded here (
../diff/SKILL.md§ The header contract); its summary line in the prep summary sizes the header. - The prep summary replaces the Phase 6 report; its
Provenance: <live>/<total> liveline is mandatory, and any ratio short of<total>/<total>means the run failed the synthesis guard and is incomplete. - When delegating extraction to a sub-agent, the sub-agent prompt
must forbid synthesis by name and require the per-page
evidence table and wait-summary line in its return
(
reference/prep-mode.md§ Sub-agent prompt requirements); missing any of the three is a recipe violation.
References
reference/playwright-recipe.md— viewport, capture list, logo locator chain.reference/ia-extraction.md— sitemap + BFS crawl + cap procedure.reference/current-state-schema.md— per-page JSON schema.reference/brand-surface.md— consolidated brand-surface schema.reference/brand-review-template.md— current-state brand-review HTML contract + Tensions detectors.reference/prep-mode.md— full--prepprocedure (typing, module candidates, typed slots, prep summary, sub-agent requirements).reference/cross-site-sources.md— full--brand-source/--design-sourceprocedure (shallow capture, merge rules, canon-source donor).skills/stardust/reference/state-machine.md— state.json contract.skills/stardust/reference/artifact-map.md— provenance shape.
stardust:migrate
Apply the target spec authored by direct, the visual canon
written by prototype --prep, and the brand-module catalog
extracted during prepare-migration to every page in the
inventory. Produces a self-contained, deployable static HTML site
under stardust/migrated/. Per-page, incremental, idempotent.
migrate is the final stardust phase. Output is platform-
agnostic HTML — downstream conversion (AEM EDS, a CMS, a
framework) is the job of a separate plugin that consumes
migrated/ plus DESIGN.json plus the per-page _meta.json
sidecars.
The procedure below is an outline. The text of each phase is in skills/migrate/reference/, in the file the phase names. Read that file in full when you reach the phase; never work from a heading alone.
Inputs
<slug>— optional positional. Migrate just this page. Without it, migrate every page whose status isdirected,prototyped, orapproved(and notstale).--all— migrate every page including stale ones.--force— re-migrate every page even when the idempotent skip would skip them.--require-approved— refuse to migrate any non-approvedpage. Default behaviour migratesdirectedpages too (using Path A′ or Path B perreference/template-and-module-rendering.md); this flag flips approval-gating on.--strict-canon— refuse approvals that conflict with canon. Default logs the deviation and continues. Useful for projects where canon discipline matters more than per-template flexibility.--clean— delete assets previously bundled but no longer referenced fromstardust/migrated/assets/. Off by default (migrate is additive). Implies--force: every page is re-rendered so the run'sbundledAssetsSet is the complete union of currently-referenced assets — otherwise--cleanwould risk deleting assets still referenced by idempotent-skipped pages. Seereference/asset-bundling.md§ Stale asset cleanup.--pin-timestamp <ISO8601>— pin the migrate-provenance timestamp so re-runs without source changes produce byte- identical HTML. Default re-uses the current wall clock, which is fine for normal use; CI deployment fingerprinting may want the pin.
The mobile-adapt audit, content-sourcing scan, and placeholder
refusal are all mandatory gates — there is no --skip-* or
--allow-* flag to bypass them. If a gate refuses a page, the
remediation is to fix the proposed file (re-prototype, edit
inline, or run an impeccable command) and re-invoke migrate.
Setup
-
Playwright re-probe (mandatory first step).
--no-saveplaywright installs from earlier phases are pruned by any later realnpm i(extract SKILL.md § Setup →--no-saveinstalls are ephemeral). Before any rendering step, probenode -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. -
Run the master skill's setup (
skills/stardust/SKILL.md§ Setup). Flow guard. Ifstardust/state.jsonexists withoutflowand the ask is a migration (a URL plus "migrate" / "to EDS" / "re-platform"), do not run: print the two-flow table from the master skill § Two migration flows and hand back to its routing — the flow is chosen and stamped there before any sub-skill runs (skills/stardust/reference/state-machine.md§ Flow keys):replicaunless the ask names a redesign. (Recorded:migrate <url>as the first command of two same-design migrations led to a hand-built compiler tuned by eye instead of the replica gate.) -
Verify
stardust/state.jsonexists with at least onedirectedpage. -
Verify project-root
DESIGN.mdandDESIGN.jsonexist withDESIGN.json.extensions.canonpopulated. -
Verify
stardust/canon/exists with at leastheader.html,footer.html,canon.css.Canon auto-bootstrap (when steps 3–4 find no canon). The documented
prototype → migrate → deployhappy path does not runprepare-migration, so a first migrate legitimately arrives with no canon (observed on 4 of 6 e2e sites, where every run had to derive canon by hand to proceed — this is the fix). When canon is absent and at least oneapprovedprototype exists, do not stop: run the canon write-back inline from the first approved prototype (the canon-author, defaulthome) per../prototype/reference/canon-extraction.md§ Five-step procedure — extractheader.html/footer.html/canon.csstostardust/canon/, pin tokens + compositional moves toDESIGN.json.extensions.canon, and recordcanon.source: "auto-bootstrap: <slug>". This is exactly whatprototype --prepdoes on first approval; migrate performs it on demand so the core pipeline never dead-ends. Only stop and recommend$stardust prepare-migrationwhen canon is absent and no approved prototype exists (there is nothing to derive canon from). Understate.json.handsOffthe bootstrap is automatic and logged; interactively, surface it as a one-line notice before proceeding. -
Verify
stardust/direction.mdhas an active (not pending) direction. -
Read
state.json.pages[]and partition into:- inScope: status
directed,prototyped, orapproved,stale: false(or--all/ explicit<slug>). - skipped: everything else, with reason captured.
- inScope: status
-
Validate provenance on every in-scope page. Call
validateProvenance(page)perskills/stardust/reference/state-machine.md§ Provenance validation for every page ininScope. Abort with the helper's error when any page lacks live-render evidence — migrating a synthesized page record produces deployable HTML that misrepresents the source site, the exact failure mode that motivated the validator. SurfaceProvenance OK on N pagesin the migrate-plan output before Phase 1. -
Mobile-adapt audit on every Path A / Path A′ source. For every page whose render branch consumes a proposed or archetype HTML file (Path A, Path A′ per
reference/template-and-module-rendering.md§ Render path selection), run the audit perskills/prototype/SKILL.md§ Mobile-adapt audit (viewport meta, mobile-first queries, the 360px render checks).Refuse pages that fail — the audit is mandatory; there is no skip flag. The user fixes the proposed file (re-prototype or chat-driven impeccable command) and re-invokes migrate. Record the audit result per page in the migrate report and in the post-render
_meta.json#audit.adaptsidecar. Path B (unique-renders) skips the audit because adapt hasn't run on those pages — a Path B page that needs mobile coverage gets it via$impeccable adaptinvoked separately by the user. Surface this distinction in the report so it's not read as a silent skip.
Procedure
Phase 1 — Plan
Read skills/migrate/reference/phase-1-plan.md in full before you act on this section.
Phase 2 — Per-page render
Read skills/migrate/reference/phase-2-per-page-render.md in full before you act on this section.
Phase 3 — Sitewide assets and bundle finalisation
Read skills/migrate/reference/phase-3-sitewide-assets.md in full before you act on this section.
Phase 4 — State and report
Read skills/migrate/reference/phase-4-state-and-report.md in full before you act on this section.
Outputs
| Path | Purpose |
|---|---|
stardust/migrated/<source-url-path> | Migrated page. Output path mirrors the source URL literally (see reference/migration-procedure.md § Output path mapping). The bundle is zip-and-deploy: drop on any static host at any path, or open index.html directly via file://. Every internal reference is relative to the page that emits it; nav targets carry an explicit index.html (or the source URL's literal filename) so file:// resolves without a server. |
| _meta.json sidecar | Lives next to each migrated page. For <dir>/index.html the sidecar is <dir>/_meta.json; for <dir>/<name>.html the sidecar is <dir>/<name>._meta.json so multiple .html siblings don't collide. Per reference/migration-procedure.md § _meta.json sidecar. |
stardust/migrated/index.html | The home page (special case). |
stardust/migrated/_meta.json | Home sidecar. |
stardust/migrated/assets/logo.<ext> | Brand logo (sitewide). |
stardust/migrated/assets/<subpath> | Every asset referenced by any migrated page, bundled. Source subdir structure preserved verbatim. |
stardust/migrated/assets/favicon.<ext> + variants | Favicon and apple-touch-icon, manifest icons. |
stardust/migrated/assets/fonts/... | Downloaded font files (from canon @font-face URLs). |
stardust/migrated/robots.txt | Minimal robots.txt. |
stardust/migrated/sitemap.xml | Sitemap derived from migrated inventory + page types. |
stardust/state.json | Updated with migrated status, history, and the migrate block (selfContained: true, asset counts). |
The driver (node stardust/scripts/migrate/migrate.mjs render …) writes
the per-page rows above (index.html / <name>.html, _meta.json,
bundled assets/**) and the migrate block of state.json (pageMap[],
bundledAssets[], pages[], missingAssets[], lastRun); status
changes, robots.txt and sitemap.xml stay with Phases 3–4.
Idempotent and incremental
The whole pipeline is built around two properties:
- Idempotent. Re-running
$stardust migratewith no changes produces zero file writes. Every page is sha-compared across designMd, designJson, sourceCurrent, sourceProposed (Path A), canonShas, archetypeSource (Path A′) — and skipped if all match. - Incremental. Migrate 5 pages today, 20 pages tomorrow, fix one page's content next week — the migrated tree is always the union of every successful migration to date.
These properties hold even when DESIGN.md, canon, or modules are edited mid-run: the edit changes the relevant sha, so the next migrate run re-renders every affected page (canon and DESIGN.md edits typically affect every page).
Stale handling
When direction.md, canon, or the module catalog changes after
some pages have been migrated:
- Affected pages are flagged
stale: trueperskills/stardust/reference/state-machine.md§ Stale flagging. Stale-flagging is content-aware in all three trigger cases. $stardust migrate(no flags) skips stale pages and reports the count.$stardust migrate --allre-migrates each stale page, clearing the flag on success.$stardust migrate <slug>always operates on the named page, stale or not.
The user decides whether stale pages should be refreshed — direction/canon/module changes don't invalidate prior migrated work, they just mark it as out-of-step.
Failure modes
- No directed pages. Recommend
$stardust direct(or$stardust extractif no extracted state). - No DESIGN.md or DESIGN.json. Recommend
$stardust direct. - No canon, but an approved prototype exists. Do NOT stop — auto-bootstrap canon from the canon-author inline (Setup step 4).
- No canon and no approved prototype. Recommend
$stardust prepare-migration(or approve a prototype first). - Pending direction. Refuse; user must resolve direction first.
- Validation failure on a single page. Skip that page,
continue, log the failure under
state.json.lastRun.failures[]. Do not abort the whole run. - Asset copy failure. Continue the run; record the missing
asset in the page's
migrationDecisions[]withkind: "asset-missing". The migrated<img src>keeps the original absolute URL as a fallback. - Output path collision. Two slugs mapping to the same output path. Refuse to write the second one and surface to the user — manual slug rename needed.
- Placeholder content in proposed/archetype file. Refuse (Phase 2 placeholder gate); surface the unsourced list and recommend sourcing real content (re-prototype, or edit the proposed file directly).
- Color reservation violated. Refuse the page; surface to user with the offending color and the reserved-for context.
- Brand-faithful inversion conflict. A hard rule declared
inverted in
extensions.divergence.brand_faithful_inversions[]is lifted from validation per T&M § Brand-faithful inversion handling. Emit a one-line note in the run summary acknowledging the lift.
What migrate does NOT do
- Critique or audit the migrated output. Run
$impeccable critique stardust/migrated/after migration if you want a quality assessment. - Deploy. Stardust does not push, upload, or modify origin.
- Generate AEM EDS, a CMS payload, or framework components. The output is platform-agnostic static HTML; downstream conversion is a separate plugin's job.
- Re-fetch the live site. Offline after extract Phase 1.
- Run any iteration loop. Iteration belongs to
prototype; migrate consumes the result.
References
reference/migration-procedure.md— per-page render procedure, output path mapping, validation, provenance shape, idempotent skip, sidecar schema.reference/template-and-module-rendering.md— three render branches in detail, slot injection, deviation policy, validation contracts.reference/metadata-and-jsonld.md— head composition, JSON-LD per page-type, canonical strategy.reference/content-preservation.md— what's kept, transformed, dropped; internal-link rewriting; asset path rewriting; form handling.reference/asset-bundling.md— detection / copy / rewrite contract for the per-page asset-bundling phase.skills/stardust/reference/migrate-output-format.md— the self-contained-bundle contract downstream consumers can rely on (asset reference shape, directory layout,state.json.migrateblock).skills/stardust/reference/token-contract.md—:rootblock refreshed from DESIGN.md on every render.skills/stardust/reference/data-attributes.md— structural attributes includingdata-template,data-module,data-slot,data-canon,data-deviation,data-bespoke,data-broken-link.skills/stardust/reference/state-machine.md— page lifecycle, page typing, stale-flagging cascade.skills/stardust/reference/artifact-map.md— provenance shape for migrated artifacts; canon files; sidecar shape.skills/prototype/reference/canon-extraction.md— how canon is built (input to migrate).skills/prepare-migration/SKILL.md— the cascade that produces every input migrate consumes.
stardust:prepare-migration
Orchestrate the migrate-prep cascade. When the user commits to
migrating an existing site, this skill runs the upstream phases
(extract, direct, prototype) in their --prep modes,
sequenced with confirmation gates so the user can confirm or refine
the inferred catalog at each step.
prepare-migration is a thin orchestrator — it does not
duplicate logic from the underlying skills; it invokes them and
brokers the per-phase summaries. The substantive work lives in:
skills/extract/SKILL.md§ Prep modeskills/direct/SKILL.md§ Prep modeskills/prototype/SKILL.md§ Prep mode +reference/canon-extraction.md
When prep is complete, the user runs $stardust migrate
separately. The two-step boundary (prepare-migration then
migrate) is intentional: it makes "I'm committing to migrate
this site" a conscious gesture and keeps idempotency obvious.
Inputs
--from <phase>— optional. Resume the cascade from a specific phase. Values:extract | direct | prototype | assets | dynamics. Default starts from the earliest incomplete phase.--skip-confirm— optional. Skip the per-phase confirmation gates. Useful for re-runs where the catalog is already settled. Default is to gate at every phase boundary. Hands-off mode (skills/stardust/SKILL.md§ Hands-off mode, i.e.state.json.handsOff: true) implies--skip-confirm.--canon-from <slug>— optional. Forward toprototype --prep --canon-from <slug>when that phase runs. Override the default canon-author (which ishome).--refine-module <module-id>— optional. Re-enter Phase 2's module-catalog step for one module — the target ofmigrate's "bespoke slot crossing promotion threshold" hint. Promotes the recurring bespoke slot into that module's slot schema (DESIGN.json.extensions.modules[]), surfaces the change for confirmation, then stops; it does not re-run the full cascade. Affected pages are stale-flagged content-aware perskills/stardust/reference/state-machine.md.
Setup
-
Run the master skill's setup (
skills/stardust/SKILL.md§ Setup) — impeccable dep check, context loader, state read. Flow guard. This is the redesign flow's orchestrator. Ifstate.json.flowisreplica, refuse: print "never runprepare-migrationbefore or afterreplica" and the switch command ($stardust prepare-migration --switch-flow, which marks the replica artefacts stale — master skill § Two migration flows). Ifflowis absent, resolve it first: only an explicit redesign phrase ("redesign", "modernise", "refresh", "new look") selects this skill — stampflow: "redesign"(skills/stardust/reference/state-machine.md§ Flow keys). Any other migration ask, keep-design phrase or plain "migrate", means this skill does not apply — say so and hand toreplica. -
Verify
stardust/state.jsonexists with at least one extracted page. If not, recommend$stardust extract <url>and stop. -
Verify
stardust/direction.mdexists with an active direction. If not, recommend$stardust directand stop. -
Determine which phases are already complete by inspecting project state:
- extract: every page has a non-null
typeinstate.jsonandcurrent/pages/<slug>.jsoncarries aslotsblock. - direct:
DESIGN.json.extensions.modules[]entries all havestatus: confirmed;colorReservationsandmetadatablocks present. - prototype: every page-type has at least one approved
archetype;
stardust/canon/populated;DESIGN.json.extensions.canonpopulated. - assets: favicon variants in
stardust/migrated/assets/; fonts downloaded. - dynamics:
stardust/dynamic-features.mdpresent with every row carrying a disposition;helix-query.yamlpresent when any listing is index-backed (Phase 4.5 records "none" otherwise).
Resume from the earliest incomplete phase unless
--fromoverrides. - extract: every page has a non-null
Procedure
The cascade runs five phases sequentially. Each phase invokes its
underlying skill via the harness's skill-invocation tool (see the master
skill § Routing for how sub-skills are addressed), surfaces the phase's prep
summary, then waits for user confirmation (unless --skip-confirm
or hands-off mode) before advancing.
Phase 1 — extract --prep
Invoke the stardust extract skill with the argument --prep.
Claude Code form: Skill { skill: "stardust:extract", args: "--prep" }.
The underlying skill runs the standard extract procedure with the
five --prep overlays (lift cap, page typing, module candidates,
typed slots, prep summary).
On completion, surface the summary verbatim, name the flow, and gate — the first interactive gate of the cascade carries the keep-vs-redesign choice (one recorded migration ran this cascade for 3.5 hours before the user asked for the keep-design flow, and the work was discarded):
Flow: redesign — the design changes while migrating. Say `switch to replica` now if it is to be kept.
Confirm and continue? (yes / refine "<phrase>" / switch to replica)
User options:
yes— advance to Phase 2.switch to replica— the design is to be kept: stop this cascade and run$stardust replica <url> --switch-flow(master skill § Two migration flows). The extract just produced is reused by replica Phase 1; nothing else from this flow is.refine "<phrase>"— re-invokeextract --prepwith the refinement (e.g., "type news/* slugs as listing not article", "exclude /search and /404 from inventory"). Re-surface summary; loop.
Provenance guard (between Phase 1 and Phase 2)
Before invoking direct --prep, validate every page in the
inventory via validateProvenance(page) per
skills/stardust/reference/state-machine.md § Provenance
validation. Abort the cascade with the helper's error if any
page lacks live-render evidence. This is the cascade-level
defense against the failure mode where extract --prep (or its
delegated sub-agent) silently synthesized one or more page
records — extract's own write-time refusal is the primary guard,
but the cascade adds a second check between phases so the
synthesis bug recurring under a different rationale cannot
quietly contaminate the rest of the run.
The same guard runs implicitly inside Phase 2, 3, and 4 (each
underlying skill's setup calls validateProvenance() per its
own SKILL.md) — but surfacing it here as an explicit cascade
step makes the abort happen before the user sees the Phase 2
prep summary, which would otherwise look like a successful run.
Surface in the cascade output:
Provenance OK on 127 pages.
When the check fails:
Provenance check failed on 20 of 127 pages — see error above.
Cascade aborted between Phase 1 and Phase 2.
→ Re-run extract for the affected slugs:
$stardust extract --refresh <slug-1>
$stardust extract --refresh <slug-2>
...
Phase 2 — direct --prep
Invoke the stardust direct skill with the argument --prep.
Claude Code form: Skill { skill: "stardust:direct", args: "--prep" }.
The underlying skill runs five --prep overlays (type catalog
confirmation, module catalog finalization, color reservations,
direction re-evaluation, brand metadata defaults).
Surface the summary and gate. User options match Phase 1
(yes / refine "<phrase>").
Phase 3 — prototype --prep
Invoke the stardust prototype skill with the argument --prep, plus
--canon-from <slug> when a canon slug is already known.
Claude Code form: Skill { skill: "stardust:prototype", args: "--prep --canon-from <slug>" }.
The underlying skill fills page-type gaps (one approved archetype
per type) and writes canon back per
skills/prototype/reference/canon-extraction.md. First approval
establishes canon; subsequent approvals extend it (with conflicts
logged as deviations by default).
This phase typically takes the longest — each archetype goes through the full prototype loop (shape brief, craft, open in browser, iterate, approve). Stream progress to the user as each archetype lands.
Surface the summary and gate.
Phase 4 — assets prep
Generate or download asset variants needed for the migrated site. This phase has no underlying SKILL — it runs as a small image- processing + download routine.
-
Favicon variants. From the canonical favicon at
stardust/current/assets/favicon.<ext>, generate:stardust/migrated/assets/favicon-512.pngstardust/migrated/assets/apple-touch-icon.png(180×180)stardust/migrated/assets/icon-192.png,icon-512.png(manifest sizes)
-
Font downloads. Scan
stardust/canon/canon.css(andstardust/canon/header.html/footer.html) for@font-facerules with external URLs. For each:- Download the file to
stardust/migrated/assets/fonts/<basename-with-hash>.<ext>. - Rewrite the
@font-faceurl(...)reference in canon files to the local path. - Skip if already downloaded (sha-compared).
- Log a warning if download fails (font keeps external URL;
migrate logs a
metadata-overridewarning per page).
- Download the file to
-
Brand-asset audit. Verify the logo, favicon, and any media files referenced by canon module renderings are present in
stardust/current/assets/. Surface missing assets to the user.
Surface summary and gate:
assets prep complete
====================
Favicon variants: favicon-512.png, apple-touch-icon.png, icon-192.png, icon-512.png
Font downloads: 4 files (HarmoniaSans 4 weights)
Brand assets: all present
Phase 4.5 — Dynamic surface (pre-import gate: dynamics Phases 1–3)
Runs after assets prep and before any bulk import. Migration-bound:
this is the step that keeps a dynamic site from being imported as a
static one. Delegate to skills/dynamics/SKILL.md:
- Detect — re-run
extract --dynamicsif Phase 1 ran without it (reach), thendynamics-detect.mjs --from-state stardust/state.json --reach stardust/current(depth on archetypes). - Classify + triage —
dynamics-plan.mjs [--target-origin <host>]drafts the four axes per row; curate intostardust/dynamic-features.md(§ Listings contract withhelix-query.yaml, § Features, § Decision batch, § Register) andstardust/dynamic-features-plan.md. - Gate — passes when every row has a disposition. "none" in both sections is a valid pass. The gate never blocks the static path; it blocks silent regressions.
Summary line: dynamic surface: N findings · self K · owner batch M · host-bound H · listings L dynamic / S static. Contract:
skills/dynamics/reference/triage.md.
Final report
prepare-migration complete
==========================
Phase 1 (extract --prep): 127 pages, 7 types, 8 module candidates
Phase 2 (direct --prep): types & modules confirmed; metadata set
Phase 3 (prototype --prep): 6 archetypes approved; canon written
Phase 4 (assets prep): favicon variants + fonts + brand assets ready
Phase 4.5 (dynamic surface): 14 findings · self 6 · owner batch 7 · host-bound 1 · listings 3 index-backed / 1 static
Next: $stardust migrate
Outputs
prepare-migration writes nothing directly — every artifact is
written by the underlying skill or by the Phase 4 / 4.5 routines.
After the cascade runs, the project state has:
| Artifact | Phase that wrote it |
|---|---|
state.json.pages[].type | extract --prep |
current/pages/<slug>.json § slots | extract --prep |
DESIGN.json.extensions.modules[] (status: confirmed) | extract --prep + direct --prep |
DESIGN.json.extensions.colorReservations[] | direct --prep |
DESIGN.json.extensions.metadata | direct --prep |
stardust/canon/ (header, footer, css, modules/) | prototype --prep |
DESIGN.json.extensions.canon | prototype --prep |
stardust/migrated/assets/favicon-* | assets prep |
stardust/migrated/assets/fonts/ | assets prep |
stardust/dynamic-features.md + -plan.md (inventory, four axes, decision batch) | dynamics gate (Phase 4.5) |
helix-query.yaml (scoped indexes, EDS project root) | dynamics gate (Phase 4.5) |
stardust/state.json (per-page status updates) | each underlying phase |
Failure modes
- No state.json or no extracted pages. Recommend
$stardust extract <url>and stop. - No active direction. Recommend
$stardust directand stop. - User refuses a phase. Stop the cascade cleanly. State is
left in a consistent intermediate (the underlying skill's writes
have landed); the user can resume with
$stardust prepare-migration --from <phase>. - Underlying skill fails. Surface the failure verbatim; do not advance. User fixes and re-runs.
- Phase 3 canon conflict during a non-canon-author approval.
Conflicts log as deviations by default per
reference/canon-extraction.md. If the user wants to override per-conflict (promote to canon / reject and re-iterate / log as deviation), surface during the phase's confirmation gate rather than at runtime. A future--strict-canonflag could refuse approvals that conflict; not in v0.2. - Phase 4 asset download failure. Continue the run; log the failure in the assets-prep summary. Migrate later surfaces a warning per affected page.
Concurrency
Per skills/stardust/reference/state-machine.md § Concurrency:
state.json writes merge by slug, so the cascade's per-page writes
coexist with other parallel lanes. But two concurrent
prepare-migration runs on the same project race on the same
top-level artifacts (canon, module catalog) — that remains
last-write-wins with a warning, and is likely to corrupt canon.
Don't run two cascades at once; do not engineer a lock around it.
Idempotency
Re-running prepare-migration after partial completion resumes
from the earliest incomplete phase (or the explicit --from
phase). Each underlying skill is itself idempotent — already-
typed pages are not re-typed, already-confirmed modules are not
re-proposed, already-approved archetypes are not re-prototyped,
already-generated favicon variants are not re-generated, and an
existing dynamic-features.md is refined rather than rewritten.
Re-running after full completion is a no-op unless inputs changed (extract found new pages, direction was edited, the canon-author prototype was re-iterated, etc.).
References
skills/extract/SKILL.md§ Prep modeskills/direct/SKILL.md§ Prep modeskills/prototype/SKILL.md§ Prep modeskills/prototype/reference/canon-extraction.md— the five-step extraction procedure prototype --prep performs on approvalskills/dynamics/SKILL.md+reference/triage.md,reference/listings.md— Phase 4.5 is its Phases 1–3skills/migrate/SKILL.md— the consumer of every data structure this cascade preparesskills/stardust/reference/state-machine.md— page typing, stale-flagging cascadeskills/stardust/reference/artifact-map.md— file structure, DESIGN.json.extensions shape
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).
This file is the outline of the procedure. The text of each phase is in skills/prototype/reference/, in the file the phase names. Read that file in full when you reach the phase; never work from a heading alone.
Inputs
<slug>— optional positional. Prototype just this page. Without it, prototype everydirectedpage that is notstale.--all— prototype everydirectedpage 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 tostardust/canon/andDESIGN.json.extensions.canon. See § Prep mode below andreference/canon-extraction.md. Typically invoked via theprepare-migrationorchestrator.--canon-from <slug>— optional. Override the default canon- author (which is the first approved prototype, typicallyhome). 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 inreference/publish-sample.md: eligibility checks, file staging, PR creation against the upstream stardust repo. Requiresghinstalled 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,:roottoken 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 fromDESIGN.json.extensions.motion.register(written bydirect); if absent, the prototype phase picks one using the same heuristic perreference/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--cinematicbut 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
- Playwright re-probe (mandatory first step).
--no-saveplaywright installs from earlier phases are pruned by any later realnpm i(extract SKILL.md § Setup →--no-saveinstalls are ephemeral). Before any rendering step, probenode -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. - Run the master skill's setup
(
skills/stardust/SKILL.md§ Setup). - Verify
stardust/state.jsonexists and contains at least onedirectedpage. If not, recommend$stardust directand stop. - Verify the project-root
DESIGN.mdandDESIGN.jsonexist. If not, the direction was not fully authored — recommend$stardust directand stop. - Verify
stardust/direction.mdhas an active (not pending) direction. Pending directions block prototype. - Validate provenance on every page in scope. Call
validateProvenance(page)perskills/stardust/reference/state-machine.md§ Provenance validation for every page that this run will render (the single<slug>argument when present, otherwise every non-staledirected/prototyped/approvedpage). Abort with the helper's error when any page lacks live-render evidence — re-runningprototypeagainst a synthesized page record silently propagates the synthesis into the rendered prototype. SurfaceProvenance OK on N pagesonce the check passes. - 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
Read skills/prototype/reference/delegation-mechanic.md in full before you act on this section. It covers: Invoking impeccable.
Procedure
Phase 1 — Plan the prototype (page-shape brief)
Read skills/prototype/reference/phase-1-plan.md in full before you act on this section. It covers: Brief-time disciplines.
Phase 2 — Render the proposed page
Read skills/prototype/reference/phase-2-render.md in full before you act on this section. It covers: Craft-time disciplines.
Phase 2.4 — Motion application (when --cinematic)
Read skills/prototype/reference/phase-2-4-motion-application.md in full before you act on this section. It covers: Output paths; When to use the static-only path.
Phases 2.5 – 2.8 — Quality gates: Critique → Audit → Adapt → Motion (Discipline 9)
Read skills/prototype/reference/phase-2-5-to-2-8-quality-gates.md in full before you act on this section.
Phase 2.5 — Critique
Read skills/prototype/reference/phase-2-5-to-2-8-quality-gates.md in full before you act on this section.
Phase 2.6 — Audit (detector specifics)
Read skills/prototype/reference/phase-2-5-to-2-8-quality-gates.md in full before you act on this section.
Phase 2.7 — Adapt (mandatory pre-approval)
Read skills/prototype/reference/phase-2-5-to-2-8-quality-gates.md in full before you act on this section. It covers: Adapt procedure; Mobile-adapt audit; Mobile nav collapse.
Phase 2.8 — Motion validation (mandatory when motion declared)
Read skills/prototype/reference/phase-2-5-to-2-8-quality-gates.md in full before you act on this section. It covers: Variant-convergence detector.
Phase 4 — Open and iterate
Read skills/prototype/reference/phase-4-and-5-iterate-and-approve.md in full before you act on this section. It covers: Iteration paths.
Phase 5 — Approval (+ fold-back, Part III)
Read skills/prototype/reference/phase-4-and-5-iterate-and-approve.md in full before you act on this section.
Phase 5.5 — Adapt for mobile (retired; see Phase 2.7)
Adapt and the mobile-adapt audit moved to Phase 2.7 as part of
the Discipline 9 critique → audit → adapt cycle, gating
prototyped instead of approval. A 2026-05-03 e-commerce
showcase failure mode (stakeholders eyeballing variants on a phone
getting the unadjusted desktop layout) is unchanged — the gate just
fires earlier in the lifecycle, so a non-adapted prototype never
lands as prototyped in the first place.
The implementation (impeccable adapt invocation, mobile-adapt audit, mobile-nav-collapse stock pattern) lives in § Phase 2.7 above. This section is retained as an anchor for any external cross-reference that still names Phase 5.5.
Stale handling
When direction.md changes, the prototype's againstDirection
provenance becomes outdated and state.json flags the page
stale: true. Default behaviour:
$stardust prototype(no slug) skips stale pages and reports the count:2 stale pages (home, about) — re-run with --all.$stardust prototype homeoperates onhomeeven if stale.$stardust prototype --allre-prototypes every directed page including stale ones.
When a stale page is successfully re-prototyped, clear its stale
flag and update againstDirection to the new active direction.
Outputs
| Path | Purpose |
|---|---|
stardust/prototypes/<slug>-shape.md | Per-page compositional brief (Phase 1 output, craft input). |
stardust/prototypes/<slug>-proposed.html | Proposed redesign (chat-driven iteration target, migration source, user-facing review surface). |
stardust/state.json | Updated with page status and approval history. |
DESIGN.json | Updated with extensions.divergence.anti_toolbox_hits and any audit amendments from this prototype's render. |
Failure modes
- No directed pages. Recommend
$stardust directand stop. - Pending direction. Refuse to run; the user must resolve the direction first.
- Validation failure (:root block missing, data attributes missing, unjustified anti-toolbox hit, impeccable rule violation). Do not write the file. Surface the specific failure and a suggested fix.
- Impeccable not available. Refuse to run — impeccable is a hard requirement (Delegation mechanic). Recommend the user install the impeccable plugin and re-invoke.
Concurrency
Per state-machine.md: stardust does not lock. Two concurrent
prototype runs on different slugs are safe. Two on the same slug
are last-write-wins; warn the user if they explicitly try.
Prep mode (--prep)
Read skills/prototype/reference/prep-mode.md in full before you act on this section. It covers: 1. Fill page-type gaps; 2. Canon write-back on first approval; 3. Canon write-back on subsequent approvals; Prep summary.
References
reference/page-shape-brief.md— per-page compositional brief format (Phase 1 output, craft input). Page-level deployment decisions live here; site-level system decisions live in DESIGN.md.reference/canon-extraction.md— the five-step canon-extraction procedure performed on prototype approval in--prepmode.reference/proposed-file-shell.md— proposed-file schema and required structure (:roottoken block, data attributes, provenance, content sourcing hierarchy, mobile-adapt audit).reference/publish-sample.md—--publish-samplesub-flow: eligibility checks, file staging, PR creation against the upstream stardust showcase. Lands the prototype as a public sample athttps://{owner}.github.io/stardust-2/.reference/mobile-nav-collapse.md— stock CSS-only hamburger pattern Phase 2.7 auto-applies when the Mobile-adapt audit refuses onhorizontal-overflow-at-360pxornav-readability-floor. Carries the copy-pasteable HTML+CSS+JS, the audit smoke-test command, and the alternative-pattern vocabulary.reference/motion-validation.md— Phase 2.8 procedure: scroll-position probe, finding classification, motion-bug checks (clipped-container reveal timing, animation-range vs reading position, anim-enter trigger reachability, reduced-motion override completeness, no-JS state, multi- viewport scroll-driven check). Reusable Playwright probe patterns documented inline.reference/motion-registers.md— five brand-faithful motion registers (arrival,kinetic-display,live-systems,editorial,kinetic-grid), the selection heuristic that maps PRODUCT.md Brand Personality traits to a register, and the § Extension rule for bespoke registers derived from the site's own captured motion. Consumed by Phase 2.4 (motion application).reference/motion-stack.md— technology choice for cinematic prototypes: Lenis + CSS keyframes + rAF + IntersectionObserver. Why not GSAP. Bundle policy + Lenis pinning procedure.reference/motion-attributes.md—data-*vocabulary the cinematic runtime consumes ([data-anim],[data-tile-anim],[data-countup],[data-flip],[data-fill],[data-split],[data-parallax]). Annotated per the active register.reference/motion-runtime.md— the canonical inline runtime script that powers every cinematic prototype. Single source of truth; embedded verbatim during Phase 2.4.reference/fidelity-refined-pass.md— concrete CSS recipes for the--fidelity=refinedcraft micro-pass (Discipline 8).reference/anti-template-bank.md— worked examples of the non-template moves Discipline 3 draws from (typographic substitution / substrate-promotion / inversion / document-shape / scale-displacement), plus the § Extension rule for evidence-shaped new moves.skills/stardust/reference/reference-research.md— sourcing real-world design references (refero MCP with WebSearch fallback, graceful skip when unavailable); consumed by Discipline 2's reference-grounded alternatives.reference/approval-fold-back.md— Phase 5 fold-back procedure (Part III of the merged spec): diff algorithm, surfacing UX, write logic, stale flagging,--auto-fold/--no-foldflags, verbatim no-op gating.fixtures/composition-delta-good.md— example shape brief with a strong structuralcompositionDelta(passes Discipline 10).fixtures/composition-delta-trivial.md— example shape brief with token-only deltas (fails Discipline 10).../stardust/reference/token-contract.md—:roottoken block (cross-cutting, used by prototype + migrate).../stardust/reference/data-attributes.md— structural data attribute vocabulary (cross-cutting, used by prototype + migrate).../stardust/reference/divergence-toolkit.md— anti-mediocrity rules consumed during render and iteration.../stardust/reference/intent-dimensions.md— the 7-axis vocabulary used to read a chat-driven refinement phrase (iteration path 2).../stardust/reference/impeccable-command-map.md— when to reach for each impeccable command. Consulted during chat-driven iteration (path 2) to pick the command for a refinement phrase.../stardust/reference/state-machine.md— page lifecycle and stale rules.../stardust/reference/artifact-map.md— provenance shape.- impeccable's
reference/craft.mdandreference/live.md— the underlying impeccable commands stardust delegates to.
stardust:qa — read-only site QA sweep
One live URL in. One evidence-bound findings report out. This skill never
edits anything — not site content, not DA documents, not repo code. Its only
writes are report artifacts under stardust/qa/. If the user wants findings
fixed, that is a separate, explicit follow-up outside this skill.
qa is the post-deploy counterpart of rollout's delivery verification: where
rollout asks "did every page ship?", qa asks "is everything that shipped
actually correct?" — at all three layers a deploy can silently break:
- delivery — what the pipeline serves (
.plain.html, full HTML, sheets, sitemap) - rendered — what a browser shows after block decoration (and what it does: an autoplay video that only shows its poster is a rendered defect)
- regression — what changed since the last approved state (visual baselines)
A green upper layer never implies the lower one: a publish 200 ≠ delivered, delivered HTML ≠ rendered correctly.
Setup
- Run the master skill's setup (
skills/stardust/SKILL.md§ Setup) if not already done this session.qaworks standalone too — it only needs a live base URL. - Resolve the base URL (the
*.aem.livehost or production domain). If the user didn't give one, look instardust/rollout/rollout.json(site.liveHost) or ask. - Resolve the inventory source — what pages the sweep covers, merged from
any of:
stardust/template-map.json(also supplies template assignments for conformance;scripts/from-knowledge.mjswrites it from a spec, plus allowlist entries for 404s the source already had), a paths file, and the livesitemap.xml(always fetched; parity mismatches become findings, so a wrong sitemap can't silently shrink coverage). - Optional inputs that unlock deeper checks:
--scrape stardust/scrape— verbatim fidelity vs the extraction capture--expected-blocks <json>— explicit per-template block expectations--parity <json>— dynamic parity file to replay (defaultstardust/dynamics/parity.json; thedynamicscheck reportsparity-missingwhen absent)--auth-header "token …"/--token-env SITE_TOKEN— protected origins; the secret is sent to the base origin only (otherwise derived by fleet consensus)--blocks-dir <dir>— the site'sblocks/checkout, so theeditabilitycheck can honour@ew-exemptJSDoc tags (otherwise pass--ew-exempt a,bfor index-driven blocks)
- Browser checks need playwright resolvable from the project (
node_modules/playwright). If missing, run the delivery-layer checks only (--checks routing,content,templates,metadata,links) and tell the user what was skipped. - Append a phase-transition line to
stardust/status.jsonlperreference/run-status.md(master skill) at sweep start/end.
Procedure
Phase 1 — deterministic sweep
node <plugin>/skills/qa/scripts/qa.mjs \
--base https://main--<site>--<org>.aem.live \
--template-map stardust/template-map.json \
--scrape stardust/scrape
Writes stardust/qa/inventory.json, report.json, report.html, screenshots
under stardust/qa/shots/, and (first run) visual baselines under
stardust/qa/baselines/. Exit 0 = no active errors, 1 = active errors,
2 = infra failure. reference/checks.md documents every check, its finding
ids, and severity rationale. Useful variants: --checks <subset>,
--max-pages <n> (smoke run), --fail-on warn (strict gate). The ai-readability check
reproduces Adobe's AI Content Visibility Checker per page (served words ÷ rendered words) and
attributes the gap per block (deploy/reference/ai-readability.md).
The editability check is the post-deploy Experience Workspace
editability gate (deploy SKILL.md § 8, EW1–EW10): per page it re-creates
the da.live canvas's instrumentation on the served document, lets the live
page decorate, and counts which authored texts still carry their editor
index. editability/dead-text (error) = a block rebuilt authored text and
the author cannot click it in the canvas; editability/duplicated-index
(warn) = a presentational clone kept the index. Dead texts inside blocks
declared @ew-exempt (or listed in --ew-exempt) are info, not errors.
First run on a site: expect a wave of visual/baseline-created info findings —
that is the baseline being established, not a defect. Baselines are
screenshots and therefore local (stardust/.gitignore excludes
qa/baselines/ and qa/shots/, master skill § Artifacts): later runs on the
same machine diff against them; a fresh clone re-establishes them on its
first sweep. qa/allowlist.json is the tracked record of judgement.
Phase 2 — triage the ambiguous flags (LLM judgment, still read-only)
The deterministic sweep marks two finding classes as needs triage; read
report.json and judge only those:
content/verbatim-below-threshold— inspectevidence.missingNodesagainst the live page and the scrape capture: is copy actually lost/corrupted (defect) or acceptably transformed (candidate for the allowlist)?visual/visual-diff— openevidence.baselineandevidence.currentside by side (they are PNGs; view them): real layout/style regression, or benign dynamism (carousel frame, loaded font, live embed)? Use thebandsevidence to locate the changed region.
Record each verdict by annotating the finding in your summary to the user
(defect vs non-defect + why). Do not edit report.json scores and do not fix
anything.
Phase 3 — report to the user
Summarize: totals by severity, the confirmed defects first (with page paths
and one-line evidence), then triaged-away flags with their rationale, then
notable warns. Point at stardust/qa/report.html. Recommend — but do not
apply — fixes.
Allowlist workflow (documented non-defects)
stardust/qa/allowlist.json (schema in schemas/qa-allowlist.schema.json)
keeps known non-defects from drowning every future run — e.g. a source page
that itself ships placeholder copy, or a form endpoint deliberately awaiting a
client credential. Entries match on check/id/path/messagePattern and must
carry a reason. Allowlisted findings stay in the report, greyed out, so the
evidence is never deleted.
Only add an entry when the user confirms the flag is a non-defect (or it is already documented as one in the project's records). Never allowlist to make a run green.
Read-only contract
- Writes only under
stardust/qa/(plus thestatus.jsonlledger line). - Never invokes deploy/publish APIs, never PUTs to DA, never edits blocks, styles, or content — even for "trivial" fixes the sweep itself surfaced.
- Reports failure honestly: a crashed check appears in the report as
<check>/check-crashed(error), never silently dropped.
Scheduling / CI
The runner is plain node with no plugin-runtime dependency, so the same
command works from a GitHub Action or cron for drift monitoring; --fail-on
sets the gate. In CI without playwright, pin --checks to the delivery-layer
subset.
stardust:replica — same-design migration
Same pages, same content, same design — new platform. The target spec IS the captured current state, the only permitted deltas are the entries of an explicit inconsistency register, and every archetype passes a measured source-fidelity gate against the live site before anything ships.
- No creative decisions. The direction step is mechanical promotion of
the captured spec: the stardust
directskill is never invoked and impeccable craft is never delegated to (its redesign gates do not apply — a "tastefully improved" section is a failing section). - Recreation, not copying. Archetypes are clean semantic HTML/CSS authored from captured content and from values MEASURED on the source — never DOM copies, never ported page-level stylesheets. Fidelity is proven by instruments, not asserted.
Inputs
<URL>— required. The site to migrate.--breakpoints <list>— optional. Gate widths, default1440,360; each gets its own gate pass (mobile is not free — gate doc § Per-breakpoint).--target-breakpoints <list>— optional. Mobile-firstmin-widthsteps (e.g.600,900,1200) the delivered site switches layout at instead of the source's. Absent = source breakpoints kept, every target step below skipped. Persisted inDESIGN.jsonextensions.breakpoints.target.--register <file>— optional. Inconsistency items to seed the register (Phase 2). Without it and without an audit the register is empty.--first-page <url|home>— optional; hands-offhome. The page a full-site run delivers first (reference/first-page-first.md).
Setup
- Run the master skill's setup (
../stardust/SKILL.md§ Setup). Flow guard: ifstate.json.flowisredesign, refuse — print the never-mix line and the switch command ($stardust replica --switch-flow; master skill § Two migration flows). Ifflowis absent, stampflow: "replica",flowSource: "user-phrase". - Probe the gate's deps from the project root —
node -e "import('pixelmatch').then(()=>process.exit(0))"(and playwright, pngjs, cheerio) — and only on failure install them AS devDependencies, never--no-save(npm i -D playwright pixelmatch pngjs cheerio --legacy-peer-deps): ESM resolves from the project root, and the delivered repo carries what is installed. - Copy scripts into the project and run them from there: this skill's
scripts/tostardust/scripts/replica/,../stardust/scripts/tostardust/scripts/stardust/,../migrate/scripts/tostardust/scripts/migrate/and../diff/scripts/tostardust/scripts/diff/(siblings — the gates import across them). Never into the project-rootscripts/: that is the EDS boilerplate's.
The context is the budget — read reference/reading-discipline.md once
at Setup. Reference docs by section (section.mjs <doc> --list, then one
heading per call); captures through css-rules.mjs, json-query.mjs and
html-slice.mjs; instrument output through run-bg.mjs wait and
log --grep, never cat; script flags from
../stardust/reference/scripts-index.md, then --help, never the source.
Procedure
Five phases. 1 and 5 delegate to existing skills unchanged; 2–4 are
replica's. A full-site run opens first page first
(reference/first-page-first.md). Every phase opens with
node stardust/scripts/stardust/ledger.mjs replica <phase> start as its
FIRST command and closes with the end line plus its section in
stardust/journal.md (../stardust/reference/run-status.md).
Phase 1 — EXTRACT (delegate to $stardust extract --prep --dynamics)
Invoke $stardust extract <URL> --prep --dynamics, unchanged. Replica
consumes the full migration inventory: stardust/current/pages/<slug>.json
(the verbatim source of every string), the per-page screenshots, the
captured fonts and media, the descriptive PRODUCT.md / DESIGN.md /
DESIGN.json, state.json.pages[].type (each type becomes one archetype)
and DESIGN.json.extensions.modules[] (block candidates).
Surface extract's summary with the flow line first — "Flow: replica — the
design is kept. Say switch to redesign now if it is to change."
(switch to redesign runs $stardust prepare-migration --switch-flow; the
extract is reused, nothing else is.)
Bounded entry (one page, or a pilot): $stardust extract <URL> --single --dynamics (or --pages <slug,...> --dynamics) is a first-class way in. It
provides what recreation needs per page; it skips page typing and module
detection, needed only when Phase 5 fans out, and the descriptive synthesis
(Phase 2 takes the bounded promotion branch).
If extract fell back to headed Chrome, the gate captures need --headed too.
Phase 2 — PRESERVE DIRECTION (mechanical — never invoke the stardust direct skill)
Full contract: reference/preserve-direction.md.
- Promote
stardust/current/PRODUCT.md,DESIGN.md,DESIGN.jsonverbatim to the project root as the target spec — no divergence roll, no re-direction. Bounded entry: those files do not exist; take the bounded promotion branch (§ 1a, provenancebounded-single). Never mix the two. - Write
stardust/direction.md: what was promoted, from where, the provenance and the register pointer — what tells downstream skills the direction step happened. - Build the inconsistency register at
stardust/replica/inconsistency-register.md— the ONLY permitted design deltas. Sources:auditdesign findings (only when the user wants improvement candidates) and--registeritems; every entry carries captured evidence, the minimal change and a status. An empty register is a pure replica, a valid and common outcome. - Target breakpoints (only with
--target-breakpoints), before any CSS exists (§ 4): persist the list, map each source breakpoint to a step instardust/replica/breakpoint-map.md, seed the ONE register entry. - Dynamic surface (the stardust
dynamicsskill, Phases 1–3): run the detector on the archetypes, draft the triage, curatestardust/dynamic-features.mdand its plan — every row gets a disposition (skills/dynamics/reference/triage.md). This is what surfaces the modals, forms, search and host-bound APIs a pixel gate certifies as correct.
Anything not in the register is out of scope for change: a recreation choice that "improves" something unregistered is a fidelity bug.
Phase 3 — RECREATE (one archetype per page type)
Full method: reference/recreation-procedure.md (§ Authoring order). For
each page type (archetype: the type's rep_url in a spec's
archetypes.json) author stardust/prototypes/<slug>-proposed.html (+ its
CSS):
- Measure the source first, at every gate width, before any CSS:
node stardust/scripts/replica/source-spec.mjs capture <live-url> --slug <slug> --widths 1440,360writes a spec per width and the header and footer inventory. Author from them. - Content verbatim from
current/pages/<slug>.json— headings, body, CTAs and hrefs, alt text, metadata (../migrate/reference/content-preservation.md): no rewording. - The source's CSS for what the spec cannot name (states, media-query
structure, tokens), read through
css-rules.mjs. The container model is measured (DESIGN.jsonextensions.breakpoints; a bounded entry runscap-probe.mjs <live-url> --write-design stardust/current/DESIGN.jsonfirst). Any other live-vs-prototype box check goes throughmeasure.mjs --against, never an authored probe. source-spec.mjs compare <spec> <prototype-url>exits 0 at every width BEFORE the first gate round.
Fonts (§ Fonts policy): the captured faces are self-hosted as-is,
proprietary ones with deploy's licensing alert and one register entry; a
substitute renders only a face with no captured file, declared in
stardust/replica/font-subst.txt.
With a target set, every @media rule and JS width threshold is
authored on the target steps from the first line per breakpoint-map.md;
breakpoint-lint.mjs exits 0 on a prototype before its gate.
Every archetype gets its own standalone prototype — cumulative, never skipped. Never go straight to platform authoring for a new archetype: direct-authored pages plateaued at 8–16 % in the field, prototyped ones at 3.5–5.6 %. Each new prototype imports the shared layers already gated and iterates only on its new modules (§ Cumulative archetype prototypes).
CSS-portation is the per-section fallback only (§ CSS-portation fallback): paint effects not recoverable from computed styles, JS-hydrated widgets, video or animated heroes — the minimal source rules, scoped, never page-level.
Phase 4 — SOURCE-FIDELITY GATE (measured, per breakpoint)
Full contract: reference/source-fidelity-gate.md ("gate doc"). Per
archetype, per breakpoint, live URL against the served prototype:
PROTO="http://localhost:8791/<slug>-proposed.html" # ONE server, ONE port; one that answers but is not yours is never killed — take another port
LIVE="https://<site>/<path>"
G=stardust/replica/gates/<slug>-1440
# A round = gate.sh through run-bg, never a hand-written wrapper. The FIRST round of a
# breakpoint and the CONFIRMATION round after the last fix run --full; the others are pixel rounds.
node stardust/scripts/replica/run-bg.mjs start --name <slug>-1440-iter1 -- \
stardust/scripts/replica/gate.sh <slug> "$LIVE" "$PROTO" 1440 iter1 --full --main "<content-root>"
node stardust/scripts/replica/run-bg.mjs start --name <slug>-360-iter1 -- \
stardust/scripts/replica/gate.sh <slug> "$LIVE" "$PROTO" 360 iter1 --full --main "<content-root>"
node stardust/scripts/replica/run-bg.mjs wait # verdict lines; exit 75 = still going → wait again as the NEXT step
# header and footer: style parity BEFORE any pixel round on them (exit 0 = quiet)
node stardust/scripts/replica/chrome-parity.mjs "$LIVE" "$PROTO" --width 1440 --live-cache $G/chrome-live.json
# content-cap row: once per archetype after the 1440 pass, at DESIGN.json's derived probeWidth
node stardust/scripts/replica/cap-probe.mjs "$LIVE" --against "$PROTO" --design DESIGN.json --slug <slug> --main "<content-root>"
# when the archetypes pass: the prototype table, one run per width — a prototype without a row is ungated
node stardust/scripts/replica/gate-all.mjs --stage prototype --proto-base "$PROTO_BASE" --width 1440
gate.sh --help lists the flags and exit codes. Its verdict lines are the
pass bar (gate doc § Pass bar): content-diff 0 🔴 and 0 nothing-lost 🟡;
visual-diff flags none or justified; pixel aligned ≤ 10 % with the offsets
within their bound; |Δh| ≤ 8 px; Clipped: 0; declared repeated units
within 4 px; no horizontal overflow; cap-probe: PASS. Exit 124 (deadline),
5 (unstable reference) and 3 (blocked — escalate --headed) are never a
verdict: fix the capture and re-run.
- Reading a failing round (gate doc § Reading the band breakdown): the offset steps are the fix list — fix every one in ONE round; bands are read after alignment. Every fix comes off an instrument line, never the eye.
- Round cap (gate doc § Iteration discipline): three counted rounds per
page, width and stage.
gate.shexits 6 at the cap untilrounds.mjs deciderecords the decision; residuals are logged, never iterated past it. - No step waits longer than the context cache lives: a long instrument
goes through
run-bg.mjs(start, thenwaitin ≤ 100-second slices) — never in the foreground, never two as parallel tool calls, never behind asleep. - Capture traps are the scripts' flags, the same on both sides
(
--consent,--dismiss,--headed,--locale,--main—--main bodyis never valid); a project copy with hand-edits is a defect. The list: gate doc § Hardening rules. - With a target set (#131) the gate widths add each target step; inside a shifted band a pixel failure is tier-shift (logged against the register entry) or a defect — gate doc § Target breakpoints.
Interaction parity is a REQUIRED gate output per archetype, after the
static gate passes (reference/recreation-procedure.md § Interaction
parity): motion is OBSERVED with motion-observe.mjs, never inferred from
classes or CSS; only what fired is implemented; the prototype is observed
the same way and compared with motion-compare.mjs. Record
motion: {observed, implemented, dead[]} in progress.json, then re-run
the pixel round — the number returns to the gated value.
When all breakpoints pass, present the archetype and its gate metrics for
approval (hands-off records approvedBy: "hands-off"). Bookkeeping is one
command each, never a hand-built JSON line: node stardust/scripts/stardust/state.mjs advance <slug> --to approved --by hands-off --prototype stardust/prototypes/<slug>-proposed.html and node stardust/scripts/stardust/ledger.mjs replica source-fidelity-gate end --detail "<per-breakpoint numbers>". Resuming a run starts with
ledger.mjs tail and state.mjs summary --slugs, not cat.
Phase 5 — HANDOFF (delegate — migrate → deploy → rollout, unchanged)
Read the contract card first: reference/handoff-contract.md — the
migrate, deploy and rollout rules this phase needs, the rollout ledger phase
strings, one usage line per script. Read it by section (section.mjs <doc> --list, then the section a step needs), never whole, and never the
sibling SKILL.md files whole.
- Pages beyond the archetypes go through
migrateat sibling tier (../migrate/reference/fidelity-tiers.md), only AFTER their archetype is live and gated at the published origin (contract § 3 row C). Siblings inherit the archetype's encoder, never a new one; template constancy is measured first (sibling-variance.mjs), content fidelity per page at import. - Delivery via
deployper page: template-slotted for fixed compositions, reconstructive for repeat groups; blocks obey the editability contract and passblock-roundtrip --ew. - Site-wide rollout via
rollout, unchanged. C-deliver runs in recorded units (contract § 3 row C, Fan-out discipline): the foundation first, gated on the published origin with the header contract, then frozen (no frozen file is edited mid-wave); each archetype deployed and gated on its preview URL BEFORE its siblings render; one subagent per template cluster; C-final. - Target breakpoints: C0 authors on the target steps and wires
breakpoint-lint.mjsintonpm run lint. - The final gate runs against the PUBLISHED origin, not the harness
(gate doc § The published-origin gate):
gate.sh <slug> "$LIVE" "<preview-url>" <width> pub1 --full --marker "<brand or domain string>"throughrun-bg.mjs, in the page's ordinary gate dir. Nothing pixel-shaped runs on the local harness. - The delivery gate is the ALL-PAGES run (gate doc § The all-pages
published-origin gate):
node stardust/scripts/replica/gate-all.mjs [--only <slug,…>] [--skip-existing] [--eds-host <host>]— pixel, height, clipped text and missing or hidden content; a page without a row is ungated. C-final ends withupdate-coverage.mjs --gate.
What replica never does
- No redesign. No new palette, type, spacing, composition, motion.
- No content rewriting. Captured strings are verbatim; placeholders and hydration states are replicated as captured, not "fixed".
- No invented improvements. A change without a register entry is a defect, however tasteful.
- No DOM copying. Never paste the live DOM or port page-level CSS as the prototype: clean re-authoring is the point.
Outputs
stardust/
├── state.json, direction.md, journal.md ← core state, the preserve-mode record, the run journal
├── current/ ← from extract
├── prototypes/<slug>-proposed.html ← gated archetypes, one per page type
├── replica/
│ ├── inconsistency-register.md ← the ONLY permitted design deltas
│ ├── breakpoint-map.md ← only with --target-breakpoints
│ ├── spec/<slug>-<width>.json ← the measured source (Phase 3)
│ ├── progress.json ← per page type: rounds, gate results, residuals, motion
│ ├── motion/<slug>.json ← motion-observe evidence
│ └── gates/ ← <slug>-<width>/ per round; prototypes-<width>/ and all-<width>/ tables
├── migrated/ ← from migrate (Phase 5)
└── rollout/ ← from rollout: progress.json (C-deliver units), foundation-freeze.json, foundation-requests.md
PRODUCT.md / DESIGN.md / DESIGN.json ← promoted from current/ (Phase 2)
References
reference/preserve-direction.md— promotion contract, register schema.reference/recreation-procedure.md— authoring order, CSS lifting, fonts policy, fixed and sticky chrome, interaction parity, the fallback.reference/source-fidelity-gate.md— the gate: procedure, pass bar, reading a round, iteration discipline, hardening, the published-origin and all-pages gates, residual logging.reference/handoff-contract.md— Phase 5 contract card.reference/reading-discipline.md,reference/first-page-first.md.../diff/SKILL.md— the probes replica reuses, the header contract.../migrate/reference/fidelity-tiers.md— the archetype / sibling model.
stardust:reskin — same content, donor design
The user has a site (the content source) and a design that already exists somewhere else (the donor: another live site, or a directory of static HTML prototypes; Figma is future scope). Reskin rebuilds the content site's pages so that every visible byte of content survives — text, ordered images, CTAs, SEO metadata — while the surface comes entirely from the donor's tokens and module vocabulary.
The two halves have different contracts:
- Content is non-negotiable. The gate is byte equality of whitespace-normalized visible text, the ordered visible-image set, and full metadata carry-over. Not "close" — equal, after an explicitly declared, executable normalization ledger.
- Design is flexible. Content is re-laid-out onto donor modules; a carousel may become a static card grid, a sidebar may become a band. Structure (element counts, tag sequences) is informational, never gating — a reskin re-structures markup by design.
The decisive rule, validated in the UC2-E1 experiment (a healthcare site × a fintech donor: 2281/2281 text bytes, 7/7 images, 47/47 slots, 13/13 metadata, 17/17 donor-token probe): the page is generated programmatically from the captured content model — content strings are never retyped. Byte fidelity then holds by construction and the content gate becomes a regression check instead of a debugging tool.
Inputs
<content-url>— required. The site whose content is preserved.- Donor, exactly one of:
--donor <url>— a live site whose design system is adopted.--donor-dir <path>— a directory of local static HTML prototypes (claude-design / Mobirise / Relume / Lovable / v0 / hand-coded). Served on localhost and captured through the same path — recipe inreference/donor-sources.md§ Local prototypes.--donor-figma <url>— not yet implemented. The contract is defined (reference/donor-sources.md§ Figma) but the adapter is future scope. Tell the user exactly this: "Figma donors are not implemented yet. Export the frames as static HTML prototypes (or point me at a live staging URL of the design) and re-run with--donor-dir/--donor. The Figma adapter — variables→palette, text styles→type, frame screenshots→vision references, provenance classfigma-mcp— is specced inskills/reskin/reference/donor-sources.mdand will land in a later release." Do not improvise a partial Figma capture.
--pages <slug,slug,...>— optional. Restrict the content capture to specific pages. Default: the archetype set (one page per page family; a spec'sarchetypes.jsonnames them; scale to siblings happens in Phase 6 viamigrate).--scope <selectors>— optional. Pre-declare the content-root scope for a single-page run (comma-separated,!suffix keeps a scope whole; seereference/content-model.md§ Scope declaration). Without it, run the scope-discovery procedure per page.
Setup
- Run the master skill's setup (
../stardust/SKILL.md§ Setup): impeccable dep check, context loader, state read. Flow. Stampstate.json.flow: "reskin"if unset (../stardust/reference/state-machine.md§ Flow keys); if another flow is set, print it and the switch command ($stardust reskin --switch-flow) instead of running. - Playwright import-resolvability probe — same contract as
../extract/SKILL.md§ Setup:node -e "import('playwright').then(()=>process.exit(0))"from the project root; on failurenpm i -D playwright --no-save --legacy-peer-deps. Re-run the probe at the start of every phase that renders — a--no-saveinstall is pruned by any later realnpm i. - Copy the scripts into the project. ESM resolves
import('playwright')from the script's directory and the plugin tree ships nonode_modules. Copyskills/reskin/scripts/*(all five files —capture-content.mjsanddom-equality.mjsimportsource-normalize.mjsas a sibling) byte-identical tostardust/scripts/reskin/, and the master skill's scripts (../stardust/SKILL.md§ Setup, step 7): every reskin gate script resolvesbrowser.mjsthere at startup and exits 2 without it, even for--help. Run the copies. - Origin collision — if
stardust/state.jsonrecords a differentsite.originUrl, stop and ask before mixing sites, per../extract/SKILL.md§ Setup.
Procedure
Phase 1 — INGEST DONOR
The donor's design system is captured separately from the content
site, into stardust/canon-source/. Full recipes per donor type in
reference/donor-sources.md; summary:
- Live URL (
--donor <url>): invoke$stardust extract <content-url> --design-source <donor-url>— the existing skill, unchanged. It lands instardust/canon-source/: the donor'spages/,assets/(screenshots included),_brand-extraction.json,_crawl-log.json, and a descriptiveDESIGN.md+DESIGN.json, and stampsstate.json.designSource = { url, capturedAt, path }— see../extract/SKILL.md§ Cross-site brand sources. - Local prototype dir (
--donor-dir <path>): serve the directory on localhost (python3 -m http.server <port> --directory <path>) and run the same--design-sourcecapture path against the localhost origin. Record the real provenance (localhost serve of<path>) incanon-source/_crawl-log.json. Recipe details — page listing, index-less directories, port hygiene — inreference/donor-sources.md§ Local prototypes. - Figma (
--donor-figma): FUTURE. Surface the exact message from § Inputs and stop.
Then author two reskin-owned donor artifacts (contracts in
reference/donor-sources.md):
stardust/reskin/donor-tokens.json— the curated, probe-able token sheet: palette roles, type ramp, layout metrics, button specs, radii, shadows, motifs — every value a computed-style string the Phase 5 probe can assert verbatim. Curated fromcanon-source/DESIGN.json+_brand-extraction.json+ the raw computed styles; cites the donor page each value came from. On a bounded donor capture (a single donor page, no full--design-sourcerun) there is noDESIGN.json,_brand-extraction.json, ordesignSourcestamp to curate from — the token sheet is authored entirely from raw computed-style sampling of the donor page, a first-class parallel path (reference/donor-sources.md§ Two first-class token-sourcing paths).stardust/reskin/donor-modules.md— the enumerated module vocabulary (M1..Mn): one row per donor module with where-seen screenshot evidence and an anatomy description. This is the closed set the Phase 3 mapping brief maps onto.
The pin-one-reference-page rule (hard). Real donors run multiple
design systems concurrently — the experiment's donor served radius-4px
/ 1266px on its homepage and pill-radius / 1080px on older product
pages. Consolidating across them produces a chimera no live page ever
shipped, and the token probe then asserts against nothing. When donor
pages disagree on a token, pin ONE donor reference page per module
family, record it in donor-tokens.json (curatedFrom + a note
naming the reference page), and demote the other pages to
corroboration.
Phase 2 — CONTENT-MODEL CAPTURE
The new capability: a byte-oriented capture of each content page — distinct from extract's design-oriented capture. Run the ported capture script per page:
node stardust/scripts/reskin/capture-content.mjs \
--url <page-url> \
--scope '<sel1,sel2!,...>' \
--normalize stardust/reskin/normalize/<slug>.mjs \
--out stardust/reskin/content-model/<slug>/
It writes stardust/reskin/content-model/<slug>/content-model.json
(full contract in reference/content-model.md): per section-slot —
headings with levels, eyebrows and other leftovers, body paragraphs,
list items, CTAs with absolute hrefs, ordered visible images
(currentSrc + alt), plus the ordered stream (ordered) — the
same content as kind-tagged nodes in document order with nesting and
separator flags, the render surface Phase 4 consumes; page-level —
full SEO metadata (title,
description, canonical, OG, Twitter, JSON-LD, lang, favicon), the
whitespace-normalized visible text of the scope (the content-gate
reference string), and a full-page screenshot.
Two declarations are mandatory per page, because they are the experiment's top two failure modes:
- CONTENT-ROOT SCOPE declaration. Naive scoping silently dropped
30% of the experiment page's content — the hero and a banner
carousel lived inside
<header>, outside the obvious#contentroot, and byte equality would have "passed" against the incomplete reference. Never trustmainor#contentblind. Run the scope-discovery procedure (reference/content-model.md§ Scope discovery): compare the captured scope text against the whole-body text and the page screenshot, verify the h1 is inside the scope, widen with comma-separated multi-scope selectors until everything visible in the screenshot that isn't declared chrome is in the model. Chrome exclusions (nav, footer) are declared deltas (D1-style), not silent omissions. The capture script prints a coverage line (bodyTextLen / scopeTextLen / h1InScope) to make the check mechanical. - EXECUTABLE NORMALIZATION LEDGER. Cookie-consent chrome removal,
carousel de-duplication (hidden slides are absent from
innerText; clone slides duplicate it — rotating carousels break byte determinism), and any page-specific cleanup live in a per-page ledger modulestardust/reskin/normalize/<slug>.mjsthat extends the shared default (scripts/source-normalize.mjs). The same ledger file is passed verbatim to the capture and to every gate (--normalize), so the gate measures exactly the normalization the capture declared. The ledger is code, not prose. Format inreference/content-model.md§ Normalization ledger.
Phase 3 — MAPPING BRIEF
Author stardust/reskin/mapping.md — the cross-origin mapping brief.
Full contract and entry schema in reference/mapping-brief.md. Per
every content slot in the content model:
- assigned donor module id (from
donor-modules.md's closed vocabulary) + a one-line rationale grounded in slot anatomy vs module anatomy; - status ∈
{mapped, new-module, chrome, carried-invisible}— the last for sr-only/visually-hidden content inside the byte scope (carried verbatim into an equivalent hidden element, no donor module;reference/mapping-brief.md§ Status semantics).
Gates before any rendering:
- ≥ 80% of content slots
mappedonto named donor modules. Below that, the donor vocabulary doesn't cover this content — stop and surface (see § Stop conditions). - Every
new-moduleentry is explicitly composed from donor tokens (name the tokens it borrows: input spec + primary button spec, etc.) and listed in the brief's stats block. New modules are never silently improvised mid-render. - Chrome swaps documented — nav/footer replaced by donor chrome carrying the source's links is a declared delta, excluded from the content-gate scope.
- Casing / text-transform policy declared. The donor may render
eyebrows uppercase (or the source may — Chrome's
innerTextreflectstext-transform, so captured text is rendered-case). The underlying text stays byte-faithful; casing is applied via CSStext-transformonly, never by editing the string. Policy details inreference/mapping-brief.md§ Casing policy.
Composite source sections (one wrapper div holding two logical regions) are split into atomic slots in the brief — section ≠ slot.
Phase 4 — PROGRAMMATIC RENDER
The decisive validated rule: the page is GENERATED from
content-model.json — never retyped by hand. Write a renderer
script per archetype (stardust/reskin/renderers/<archetype>.mjs,
modeled on the experiment's render-reskin.mjs) that:
- reads the page's
content-model.jsonand interpolates every visible string, href, and image URL from the model (HTML-escaped) — if a string appears in the output HTML but not in the model, the renderer is wrong; - takes each slot's structure from the ordered stream
(
sections[].ordered,reference/content-model.md§ The ordered stream): kind-tagged nodes in document order, nesting preserved (a CTA wrapping its heading and vice versa),sepflags marking zero-separator inline joins. The stream is innerText-consistent by construction (its text nodes are sliced from the parent's renderedinnerText— the byte-gate basis), so emitting it verbatim is safe. Emit nodes in stream order; emitsep: ""neighbours with no whitespace between them (inline); never reorder, and never reconstruct order or separators fromvisibleText— the first field run did exactly that (per-type arrays matched greedily againstvisibleTextas an oracle) and burned three debug rounds on duplicate identical strings, both directions of CTA/container nesting, and zero-separator inlineliruns, all of which the stream now captures structurally; - renders
formControlnodes as equivalent controls, not text: a<select>carrying the captured option texts verbatim, in order; inputs/textareas carrying value/placeholder — restyled with donor tokens (the new-module composition rules apply), never flattened to prose and never dropped. A select's option text is part of the source'sinnerText, so dropping the control fails the byte gate with nothing structured to render from (reference/content-model.md§ Slot taxonomy, formControls); - carries the metadata block verbatim into
<head>(title, description, canonical, OG, Twitter, JSON-LD — including source garbage like broken JSON-LD URLs: fidelity over repair; flag such items for the human in the run report, never silently fix or silently keep); - takes its surface exclusively from
donor-tokens.json(emitted as CSS custom properties) + the donor module patterns assigned inmapping.md. Use the rendered-page conventions the Phase 5 probe asserts against: content in<main>,.containerfor the measure,.btnfor the donor primary button (reference/gates.md§ Rendered-page conventions); - writes
stardust/reskin/pages/<slug>.html, self-contained.
Renderers may parse a single node's text apart (split a list-item row
into kicker/date/title) but must fail loudly (throw) when a parse
doesn't reproduce the node's text — a silent partial parse is a silent
content drop. A slot whose orderedVerified is false is inspected
before rendering, never trusted blind; when inspection shows stream
text genuinely absent from the slot's visibleText, the
sanctioned fallback is to drop that text before rendering and
record the drop in the model's provenance — filtering ghosts against
visibleText is the documented resolution, distinct from the
forbidden order-reconstruction move
(reference/content-model.md § When orderedVerified is false).
Phase 5 — GATES
Three gate families per page; commands, pass bars, tolerances, and
failure modes in reference/gates.md. Serve or file://-address the
rendered page and run:
(a) CONTENT GATE — all three must pass:
node stardust/scripts/reskin/dom-equality.mjs \
--source <page-url> --source-scope '<declared scope>' \
--normalize stardust/reskin/normalize/<slug>.mjs \
--rendered stardust/reskin/pages/<slug>.html --rendered-scope main \
--report stardust/reskin/reports/<slug>-content-gate.md
node stardust/scripts/reskin/slot-coverage.mjs \
--model stardust/reskin/content-model/<slug>/content-model.json \
--rendered stardust/reskin/pages/<slug>.html \
--report stardust/reskin/reports/<slug>-slot-coverage.md
dom-equality.mjs (vendored + adapted from github.com/aemcoder/skills,
Apache-2.0) gates on whitespace-normalized visible-text byte
equality and the ordered, URL-normalized visible-image set;
element count and tag sequence are reported but informational.
slot-coverage.mjs additionally proves every model slot present
(slot text substring, every CTA as a (text, absolute-href) pair,
every image) and asserts metadata carry-over field by field.
(b) DESIGN-ADOPTION GATE:
node stardust/scripts/reskin/donor-probe.mjs \
--tokens stardust/reskin/donor-tokens.json \
--rendered stardust/reskin/pages/<slug>.html \
--report stardust/reskin/reports/<slug>-donor-probe.md
Computed-style assertions of donor token values on the rendered page —
bg/fg, font-family token string, display weight, button spec,
container width, band palette, section rhythm. Tolerances (exact for
colors/radius/family; ±2px button padding; ±20px container; ±16px
section rhythm) documented in reference/gates.md § Tolerances.
Then the side-by-side judgment: open the rendered page next to the
donor reference-page screenshots (canon-source/assets/screenshots/)
and judge adoption with your eyes — the probe proves tokens, the
eyeball proves the page reads as the donor. Record the verdict.
(c) Sanity — no horizontal overflow at 1440 and 360 (donor-probe
runs this automatically; --widths to override).
One fix iteration per gate family — one for the content gate,
one for design-adoption/sanity. On a failure in a family, fix once,
re-run all gates (a fix for one gate can break another). Residual
failures after a family's iteration is spent are logged in
stardust/reskin/ledger.json under the page's residuals[] — never
silently absorbed, never looped on indefinitely. (Both field runs
support the budget: the validation experiment spent one iteration on
360px chrome; the smoke run spent exactly one per family — a
content-side separator emission fix and a sanity-side 360px chrome
fix. A single shared iteration would have forced a false residual;
per-family keeps the loop bounded without absorbing real failures.)
Phase 6 — HANDOFF
Reskin owns the archetype pages; scale and shipping are the existing pipeline, unchanged:
- Scale via the stardust
migrateskill (../migrate/SKILL.md) with the donor-pinned target (thestate.json.designSourcestamp Phase 1 wrote is exactly whatdirect/migrateread for donor pinning; a bounded donor capture wrote no stamp — record the donor origin in the handoff instead,reference/donor-sources.md§ Two first-class token-sourcing paths). Same-type sibling pages render at the sibling tier against the gated archetype. Content rules are the ones reskin already enforces —../migrate/reference/content-preservation.mdis inherited wholesale. - Ship via the stardust
deployandrolloutskills, unchanged. Blocks written for donor modules obey the Experience Workspace editability contract (deploy SKILL.md § 8, EW1–EW10) and pass the EW gate (block-roundtrip --ew) before they are done.
Reskin writes its own state under stardust/reskin/ — ledger.json
holds per-page status (captured → mapped → rendered → gated), gate
results, and residuals. It makes no changes to the core state
machine (../stardust/reference/state-machine.md); the only
state.json touch is the designSource stamp that extract itself
writes in Phase 1.
What reskin never does
- No content rewriting or summarizing. Not headlines, not body, not CTA labels, not casing-by-editing. Faithful ≠ clean: source garbage is carried verbatim and flagged, not fixed.
- No invented sections. Every rendered slot traces to a
content-model slot; every module traces to
donor-modules.mdor an explicit new-module entry inmapping.md. - No donor-token drift. No colors, fonts, radii, or spacing
outside
donor-tokens.json. Licensed donor fonts are adopted as the family token string with local fallback, never rebundled. - No silent slot drops. Anything excluded from the gate scope is a
declared chrome delta or a ledger normalization — declared in
mapping.md, executable in the normalize module.
Stop conditions
- Donor capture fails (bot-block past the headed fallback, prototypes dir unservable) — surface extract's error verbatim.
- Mapping ratio < 80% — the donor vocabulary can't carry this content. Ask: widen the donor capture (more donor pages → more modules) or accept a larger explicit new-module list.
- Scope undecidable — the content page's visible content cannot be covered by any selector set (heavy shadow-DOM, iframe-embedded content). Surface with the screenshot evidence.
- Figma donor requested — future scope; exact message in § Inputs.
Outputs
| Path | Purpose |
|---|---|
stardust/canon-source/ | Donor capture + descriptive DESIGN.md/json (extract --design-source, unchanged) |
stardust/reskin/donor-tokens.json | Curated probe-able token sheet, pinned to one reference page |
stardust/reskin/donor-modules.md | Enumerated donor module vocabulary (M1..Mn) with screenshot evidence |
stardust/reskin/content-model/<slug>/content-model.json | Byte-oriented per-page content model (+ source screenshot) |
stardust/reskin/normalize/<slug>.mjs | Per-page executable normalization ledger (shared capture ↔ gates) |
stardust/reskin/mapping.md | The mapping brief: every slot → donor module, status, rationale |
stardust/reskin/renderers/<archetype>.mjs | Programmatic renderers (model in, HTML out) |
stardust/reskin/pages/<slug>.html | Rendered reskin pages |
stardust/reskin/reports/ | Per-page gate reports + screenshots |
stardust/reskin/ledger.json | Per-page status, gate results, residuals |
stardust/scripts/reskin/ | Project-local copies of the five skill scripts |
References
reference/donor-sources.md— the three donor types and their capture recipes; pin-one-reference-page;donor-tokens.jsonanddonor-modules.mdcontracts; the Figma future contract.reference/content-model.md— the capture contract: slot taxonomy, the ordered stream (the render surface), scope-discovery procedure, normalization ledger format, provenance.reference/mapping-brief.md— entry schema, the ≥80% gate, new-module composition rules, casing policy.reference/gates.md— both gates' commands, pass bars, tolerances, failure modes, residual logging.../extract/SKILL.md§ Cross-site brand sources — the--design-sourcedonor-capture path Phase 1 delegates to.../migrate/reference/content-preservation.md— the content rules reskin inherits (and tightens to byte level).../diff/SKILL.md— the pixel + structural probes; reuse them as a supplementary build-side check after Phase 6 deploy,--profile eds.
stardust:rollout — whole site → AEM (Edge Delivery Services)
deploy converts one page to AEM. rollout delivers the whole site: it
inventories the agnostic output of migrate, then drives deploy across every
page, tracking delivery coverage so you always know what's done and what's left.
rollout is delivery-only — it does not redesign. The page-by-page redesign
(extract → direct → prototype → migrate) and deploy itself are unchanged;
rollout is the across-pages layer on top. Design rationale, coverage model, and
phasing are in notes/rollout/PLAN.md. The flow
runs A→I below.
When to use
Full mode — the user has a fully migrated site at stardust/migrated/
(per-page HTML + _meta.json from stardust migrate), an EDS/AEM project + DA
destination (the same target deploy needs), and wants the entire site
delivered, incrementally and resumably.
Archetypes-only mode — the user has one migrated archetype per template plus a
full page inventory in stardust/state.json (with type per page), and wants to
ship all block code immediately without waiting for every page to be migrated.
Sibling pages register as content-pending and get their content later via a
separate track.
If there is no stardust/migrated/ tree at all, recommend stardust migrate on at
least the archetype pages first. For a single page, use stardust deploy directly.
Setup
- Run the master skill's setup (
skills/stardust/SKILL.md§ Setup). Flow guard:stardust/state.jsonwithoutflowon a migration ask → do not roll out; print the master's two-flow table and hand back to its routing (skills/stardust/reference/state-machine.md§ Flow keys). - Verify
stardust/migrated/exists with at least one*.htmlpage (full mode: all pages; archetypes-only: the archetypes + astate.jsonwithtypepopulated). If not, recommendstardust migrateon the archetypes and stop. Gated-archetype precondition (flow: replica). Readstardust/replica/progress.json: a page type may ship only when its archetype has a gate result at every configured breakpoint that ispass: true, or over the bar with every residual carrying acause(skills/replica/reference/source-fidelity-gate.md§ Residual logging format — a documented residual is a pass with an asterisk). A page type whose archetype was never gated, or is over the bar with no residual entries, is blocked: list it with its archetype slug and the command to gate it ($stardust replica <archetype>), and neither fan out its siblings norPOST /live/any of them. Accepting logged residuals under hands-off is not a bypass for an ungated archetype. Thresholds are the gate's, unchanged. (Recorded: 2,207 pages published at 24–28 % diff from an archetype that never passed; a 3,366-page re-import after a random review found what a gate would have.) - Verify the EDS/AEM target is ready exactly as
deployrequires (project scaffolding,DA_TOKEN, code branch pushable).rolloutadds no new transport. - If
state.json.handsOffis true (skills/stardust/SKILL.md§ Hands-off mode), run full-auto: no per-phase pauses. Every gate and verify step below runs unchanged — hands-off removes waiting, not validation.
Procedure
Phase A — Inventory (build the coverage)
node skills/rollout/scripts/inventory.mjs --site-url <source-url>
# defaults: --migrated stardust/migrated --out stardust/rollout
# archetypes-only mode: add the full page roster from state.json
node skills/rollout/scripts/inventory.mjs --site-url <source-url> --state stardust/state.json
Writes coverage/pages.json (one row per page: slug, delivered path,
templateId, blocks, sourceHash, delivery status), coverage/templates.json
(pages grouped by template), and rollout.json (target + DA config + lastRun).
Archetypes-only mode (--state): pages with a _meta.json are seeded as in
full mode; pages present only in state.json are seeded with templateId from
type, blocks from the archetype sidecar, and delivery.status: content-pending.
Inventory is idempotent and incremental: delivery status is preserved; a page
whose migrated HTML changed after delivery is re-flagged stale (never a
pinned row: replica's first page first). Fill in the DA
coordinates in rollout.json (site.da.org, site.site, site.da.ref,
site.liveHost) if not inferred.
Phase B — Block dedup plan (FIRST-CLASS, before any conversion)
node skills/rollout/scripts/blocks.mjs # → coverage/blocks.json (the dedup unit)
node skills/rollout/scripts/plan.mjs # → plan.json + a readable conversion plan
blocks.mjscollapses every block instance (per-pagemodules,widgets+ chrome) into the distinct set, assigns each a canonicaledsBlockName(kebab, reserved-class guarded) and recordsusedByPages/instanceCount. Chrome (header/nav/footer) iskind: chrome→ site-wide authored documents (/nav,/footer). A widget (kind: widget, from the sidecar'swidgets[] {id, href}) needs no document rows: its code ships atwidgets/<path>/<name>.htmland the page carries one/widgets/…htmllink (#133). In archetypes-only mode the archetype sidecars determine the block set;content-pendingpages add none. A module that maps to EDS default content (title, text, image, button, separator) needs no block: record itupdate-coverage.mjs --block <id> --status converted --eds-name default-content; such a row is never counted pending, whatever its status.plan.mjsorders pages representative-first per template and gives each distinct block a single conversion point: the first page that uses it CONVERTS it, every later page REUSES it by name. The per-pageconvert/reuselists aredeploy's Step-7 brief input.content-pendingpages are alwaysconvert: [].
Extending a delivered site: audit
blocks/andwidgets/first — a "new template" is usually a new composition of them (reference/operational-learnings.md).
Phase B2 — Dynamic surface (PRE-IMPORT GATE — verify the inventory)
Before Phase C. stardust/dynamic-features.md (from prepare-migration 4.5 or replica
Phase 2) must exist with a disposition on every row; verify it against fresh evidence here —
dynamics-detect.mjs --from-state … --reach stardust/current and dynamics-plan.mjs --target-origin <live host> --migrated stardust/migrated (host-bound APIs, rows the capture
already delivered). New evidence → new rows. The listings contract (per-type <meta> fields +
helix-query.yaml) is emitted by Phase C's deploy brief per page: retrofitting metadata across
published pages is a second migration. Missing inventory → run the stardust dynamics skill Phases 1–3 now.
Contract: skills/dynamics/reference/triage.md, reference/listings.md.
Phase C — Deliver the site (drive deploy per page, per the plan)
Blocked on Phase B2 — author each page's metadata contract into its metadata block during delivery, so the indexes are rich at import time.
Walk plan.json.steps in order (representative pages first). For each page:
-
Convert + push the migrated HTML (
source.migratedHtml) to AEM via thedeploymethodology. Pass the plan step into deploy's brief: create only the blocks inconvert; for each block inreuse, REUSE the existing block by itsedsBlockName(do not recreate). The brief MUST carry the Experience Workspace editability contract (deploy SKILL.md § 8, EW1–EW10): every converted block moves authored elements into wrappers (never rebuilds from text) and passes the EW gate (block-roundtrip --ew) before it counts as delivered — a brief without it skipped the contract on 27/27 blocks of a real site. The brief also carries the archetype'scaptureState[].restoreAtDeliverylist (replicaprogress.json): a freeze the gate needed (video at frame 0, carousel on slide 1) is a behaviour to deliver, never the spec (../replica/reference/recreation-procedure.md § Carousels).Deploy first, judge on the preview origin. The local harness (
build-harness.mjs→qa-gate.mjs,block-roundtrip.mjs --ew) serves the structural asserts only; every pixel or visual judgment — replica's source-fidelity gate, the header/footercrop-comparebands, the deployed eyeball — runs against the page's preview URL afterPUT → preview, never against the harness before the first PUT (deploy SKILL.md § Local QA before deploy, § Step 10). A recorded delivery session iterated CSS against a local harness pixel diff for its whole budget and delivered no page.Chrome and fragment documents carry
Robots | noindex.content/nav.html,content/footer.html, every per-localenav-*/footer-*document and any locale shell that is not a page get one more metadata block row at write time —<div><div>Robots</div><div>noindex</div></div>(renders<meta name="robots" content="noindex">). Without it the platform's index of published documents, and the/sitemap.xmlit serves, list them as pages: a recorded hands-off run served 58 sitemap urls for a 36-page site (every page plus 22 chrome documents). Phase D verifies the served sitemap.content-pendingpages (archetypes-only): no migrated HTML — skip the document push entirely (no shell/placeholder), recordcontent-pending, surface as "awaiting content track." Their block code is already deployed via the archetype. -
Static contract lint (pre-PUT, deterministic). Before the push, run the delivery-contract linter — it catches the cheap, deterministic failures (wrapper, one-CTA-per-
<p>, trailing-slash, path-safety,/img/src,about:error) offline so a broken page never reaches preview. Mechanics inreference/delivery-lint.md. A P0/P1 blocks the PUT.node skills/rollout/scripts/delivery-lint.mjs --file <html> --path </da/path> node skills/rollout/scripts/media-reconcile.mjs --file <html> --deploy-host <branch>--<repo>--<owner>.aem.live [--media-ledger <file>] [--apply]media-reconcileresolves every non-hosted image on the network and decides optimize/keep/rewrite/omit (skills/migrate/reference/media-reconciliation.md) — the authoritative form of the image-fidelity gate below. A content-host URL (content.da.live) is thehosteddecision instead: checked offline against the media ledger (--media-ledger <file>, auto-detected), never fetched anonymously (401by design); missing from the ledger fails the gate. -
Run the delivery gates before flipping a page to
deployed. Each is a one-line rule here; mechanics + helpers inreference/delivery-gates.md:- Source-fidelity — don't add sections the source lacks; never fabricate
facts.
node skills/rollout/scripts/section-fidelity.mjs --file <html> --source <url>(a static outline check on the authored file — not replica's pixel source-fidelity gate, which runs on the published origin afterdeployed) - Image-fidelity — every authored
<img>src must return 200 or be omitted; never ship<img src="about:error">. Runmedia-reconcile.mjs(step 2). - Path-safety —
reference/delivery-gates.md§ Gate 3; record original→normalized instardust/redirects.tsv. (delivery-lint flags violations.) - Source-content hygiene — skip dead source URLs; author bodyless/PDF-only
sources thin and faithful (tier
thin,skills/migrate/reference/fidelity-tiers.md), don't pad with invented prose. - Fidelity tier declared — record each page's
fidelityTier(archetype/sibling/thin) so coverage shows what was craft-gated vs cloned (skills/migrate/reference/fidelity-tiers.md).
- Source-fidelity — don't add sections the source lacks; never fabricate
facts.
-
Record outcomes with the state-writer (never hand-edit the ledger):
node skills/rollout/scripts/update-coverage.mjs <slug> --status converting node skills/rollout/scripts/update-coverage.mjs --block <id> --status converted --eds-name <name> node skills/rollout/scripts/update-coverage.mjs --block <id> --status converted --eds-name default-content # maps to default content, no block node skills/rollout/scripts/update-coverage.mjs <slug> --status deployed --url <branch-preview-url> node skills/rollout/scripts/update-coverage.mjs <slug> --status content-pending # no document pushPublish in the loop (
PUT → preview → live), don't stop at preview — any query-index (Phase D2) builds from the live tree, so a preview-only delivery leaves indexes empty. On failure:--status failed --error "<reason>"and continue (one page's failure never aborts the rollout).
Foundation-first gate (hard block, once per rollout). When the FIRST
archetype page flips to deployed, stop and prove the foundation before
authoring any second page: run the stardust diff skill (both probes) against its
prototype, plus computed-style invariants in a headless render — grid
containers compute display: grid (not stacked single-column), sections are
full-bleed where the design says so, and the CTA/button classes are actually
styled (per stardust/runtime-contract.json, skills/deploy/SKILL.md
§ Runtime-detection probe). deployed means after PUT + preview: the gate's
probes run against the page's preview URL, never a local harness — a
pre-deploy harness pixel diff is NOT this gate. A wrong runtime assumption (block wrapper class,
button classes) is silent and sitewide — typography still looks fine while
every grid stacks. This one gate is the difference between fixing one page
and rebuilding every template. The same gate runs qa.mjs --checks metadata
against the origin: favicon-default means the site's icon never shipped
(deploy Step 3 § Favicon) — recorded first passes served the boilerplate
icon while /favicon.ico answered 200. Archetype first, per template (#126): the
template's archetype is deployed and passes its full gate row on the preview URL
(gate-all.mjs --only, cap 3 fix rounds) before any of its siblings is rendered
or converted — the recorded unit C-archetype (handoff contract § 3, row C).
Execution model: waves. Deliver in waves of parallel author-only agents
— each agent curls its source pages and writes files only, never deploys or
edits blocks — template clusters concurrently (non-overlapping pages),
representative-first so blocks exist to be reused; then a central deploy
per page; then background batches with a per-page OK/FAIL ledger, re-driving
FAILs only. For clusters of 6–20+ siblings, the full flow is
reference/delivery-gates.md § Batched delivery (it also names the one
variant where cluster agents deploy themselves — replica's Phase 5 fan-out,
per-cluster deploy ledgers, lock-safe shared ledgers). The central deploy step
should run the bundled, resumable driver rather than a serial loop:
node skills/deploy/scripts/deploy-batch.mjs --org <org> --repo <repo> --branch <branch> --content <dir> (concurrency pool, persistent ledger that skips
already-live pages, retry/backoff, append-only log, delivered-.plain.html check).
The driver and every batch run in the background; its log and ledger are the
progress file. Check them at most every 4 minutes and never with a fixed sleep
of 5 minutes or more (the prompt-cache window) — the master skill's wait
discipline; recorded batch waits of 9–10 minutes re-wrote a ~650k prefix each time.
After a transient blip, re-run the same command — it re-drives only the FAILs.
Then reconcile the ledger into coverage with update-coverage.mjs.
Foundation first: lint AND commit styles.css, header/footer CSS and the
contract file BEFORE the first agent spawns; no token or custom-property rename
after fan-out (a recorded rename under three running agents cost seven
coordination messages). Disjoint clusters spawn concurrently — a wave waits
only on a real dependency (a recorded second wave idled 14 min behind an
unrelated first). Every tool call stays under 4 minutes, the main agent's
included (the prompt cache holds 5; calls of 5.2 and 6.6 min re-wrote the whole
context, and so did one 338 s foreground turn on the main agent that ran a pixel
loop beside a deploy-batch start + wait): a long instrument (gate rounds, pixel
loops, Playwright captures, deploy batches) goes through run-bg.mjs start, and
wait is the NEXT tool call — it returns within its --max (100 s by default); never two long instruments
as parallel tool calls in one turn, never two waits in one command.
Phase D — Site assembly (whole-site artifacts)
node skills/rollout/scripts/assemble.mjs # → rollout/site/{sitemap.xml,robots.txt,manifest.json} — the EXPECTED set
node skills/rollout/scripts/assemble.mjs --verify-origin https://<branch>--<repo>--<owner>.aem.live # vs the SERVED /sitemap.xml; exit 1 on a mismatch
Generates site-wide artifacts: sitemap.xml + robots.txt from delivered paths,
and a fragments manifest mapping chrome blocks to the authored chrome documents
(content/nav.html, content/footer.html) with their canon/*.html source
(deploy authors + deploys the documents through the normal content chain —
they MUST be published or the chrome 404s sitewide).
The assembled sitemap is never the served one. stardust/rollout/ is in
.hlxignore, so site/sitemap.xml is a local artifact — the EXPECTED url set.
The platform serves its own /sitemap.xml, built from its index of every
published document, chrome documents included unless each carries Robots | noindex (Phase C). A recorded hands-off run read the local file, reported
"sitemap 36 urls" and shipped a served sitemap of 58 (36 pages + 22 nav /
footer documents). Two remedies, the first required:
- Authoring: every chrome/fragment document —
/nav,/footer, per-localenav-*/footer-*, locale shells that are not pages — carries the metadata rowRobots | noindex; a document already published without it is re-authored and re-published (preview → live) before the check below. - Configuration (alternative, additive): when the code branch is writable, a
helix-sitemap.yamlat the project root (sitemaps.default.include: ['/**'],exclude: ['/nav', '/footer', '/**/nav*', '/**/footer*', '/fragments/**'],properties.lastmod: lastModified) keeps chrome out of the served sitemap even when a document lacks the row; the sameexcludeglobs go intohelix-query.yaml(Phase D2) so the index never carries them either.
Verify the SERVED sitemap, never the local file. assemble.mjs --verify-origin <live-origin> compares the served <loc> paths with the coverage rows and
exits 1 on any difference. An extra
path is a chrome document without noindex or a page built outside the migrated
tree with no coverage row (update-coverage.mjs --new, Phase D2); a missing path
is a page not published live. Re-run after the fix until it exits 0. The D-site
ledger end line names the SERVED count, never the assembled one — e.g.
--detail "sitemap served 36 = assembled 36; redirects wired; / 200".
DA library (#160). Without a library tab in its site config, a migrated
site shows authors an inherited or empty block library, never the blocks it
shipped. Run node skills/rollout/scripts/da-library.mjs (one document per block
variant and per template, the sheets, and only the Blocks / Templates config rows)
whenever a block, variant or template ships — in archetypes-only mode once the
archetypes are delivered.
D-site checklist (all before the D-site end line): assemble.mjs --verify-origin exits 0 · every chrome document carries Robots | noindex and is
published · the redirects sheet is published (below) · da-library.mjs exits 0 ·
curl -sIL <origin>/ ends in 200.
Redirects: if Phase C's path-safety gate emitted stardust/redirects.tsv, wire
it into the EDS redirects mechanism here so original inbound URLs don't 404 — the
redirects sheet at the content root (on a DA-backed site /redirects.json, columns
Source / Destination; PUT through the admin API, then preview + publish it like a
page). The root MUST answer: when the source root serves a page, deliver it as
the root index document (the pipeline serves / from it — /index ≡ /;
never also a / Source row, which would shadow it); only when the source root
itself redirects (curl -sI <source-url>, follow the Location chain) does the
sheet carry / and /index.html → the landing page. Then verify
curl -sIL https://<branch>--<repo>--<owner>.aem.page/ ends in 200: a 404 on
/ fails the whole delivery after every phase has passed (recorded — a sheet
with a row for every .html path and
none for /).
Phase D2 — Dynamic features (dynamics Phases 4–5)
Implement the plan's reproducibility-self rows from the pattern catalogue
(skills/dynamics/reference/patterns.md — index-backed listings and search, modal loader,
media as URL, client-compute blocks, owner-facing tag config disabled, off-origin data tiers,
sheet sync); emit every other row as one owner decision batch and ship its interim tier.
Query indexes build from the published tree — publish per page in Phase C, then poll total.
Each feature ends with a parity row in stardust/dynamics/parity.json carrying a replayable check;
dynamics-check.mjs --origin <live host> runs before Phase H and the report carries its table.
Failed replays are dynamic-gap / api-dependency learnings, never silent passes.
Index-backed listings ship document-first (authored rows, index for non-text and top-up —
dynamics/reference/listings.md); the deploy AI-readability gate runs on every listing page.
A missing query index is a code-branch gap, not a configuration-service problem.
/query-index.json answering 404 means the project ships no helix-query.yaml. Author it
at the code branch root (a spec's knowledge/helix-query.yaml is the draft), publish the
pages LIVE and poll: skills/dynamics/reference/listings.md § Getting an index at all. A
403 from the configuration service is expected; only an unwritable code branch ships the
sheet-backed interim index (recorded interim, decision named).
Search parity is count + titles, not presence. The results block ranks title
matches first and consults description, then body text, only while fewer than N title
hits exist (N = the source's visible count for the probe term), dedupes by title +
description and caps the typeahead at N — N, the top titles and one known hit are read
from the SOURCE during detect and recorded on the search-query check (expectCount,
expectTitles, expectIncludes); dynamics-check.mjs fails the check on a count
mismatch (skills/dynamics/reference/patterns.md § search-index-backed).
Pages built here enter coverage. A results page (or any page without a capture)
has no inventory row, so it stays outside verify.mjs --all, optimize.mjs and the
assembled sitemap unless registered:
node skills/rollout/scripts/update-coverage.mjs --new search --path /search --template search --origin dynamics --title "Search"
then record its status like any page. inventory.mjs keeps such rows on a re-run (the
origin marker in source.migratedHtml identifies them; status untouched), so the line
runs once.
Phase D3 — Multilingual (per-language trees) — optional
When the source has language trees (/fr/…, /en/…), add them as parallel content
trees that REUSE the same block library — only authored content and a little wiring
change (language-routed chrome documents, per-language indexes, per-language path-safety).
See reference/multilingual.md.
Phase E — Full-site verify
node skills/rollout/scripts/verify.mjs # uses rollout.json site.liveHost
# or: --base <url> (explicit host) | --root <dir> (offline, against a local export)
For every delivered page, verify confirms HTTP 200, no about:error (deploy
#75), and that every internal href="/…" resolves to a known delivered path — then
flips each page to verified or failed. Exits non-zero if any page failed.
Headless render check (per template). A 200 .plain.html can still render
blank — decoration failures (missing script, wrong block wrapper class, 404
chrome) are invisible to a text check. On the FIRST delivered page of each
template (home included), load the live URL in a headless browser and assert
decoration ran: the runtime's body.appear class is set (per
stardust/runtime-contract.json), main .section count > 0,
zero pageerror events, zero broken images, and every restoreAtDelivery
entry of the template's archetype holds: an autoplay <video> at least a
quarter visible is playing (!paused, currentTime advancing — not merely
present), a rotating carousel advances without interaction.
Published-origin gate over the roster (#125). verify proves the pages render; the
DELIVERY verdict is replica's gate-all.mjs (pixel + height + clip + content per deployed page,
../replica/reference/source-fidelity-gate.md § The all-pages published-origin gate).
update-coverage.mjs --gate stardust/replica/gates/all-<w>/summary.json writes each row into
delivery.gate and flips a failing page to failed; verify never marks it verified while the
gate fails — completion derives from one place, never from the pixel number alone. In C-deliver
the roster run is the recorded unit gate-all (handoff contract § 3, row C).
Phase E2 — Link-audit completeness
verify.mjs checks the links on delivered pages; this phase closes the set of
link targets a roster-driven batch misses
(reference/operational-learnings.md § Two verify checks):
- Nav/footer/landing targets are NOT archetype siblings. Enumerate every
hrefin the/nav+/footerdocuments plus each section's index/landing page and confirm each is deployed + published + verified — and that the chrome documents THEMSELVES are published — otherwise they get committed but never published, their links 404, and the dashboard still reads 100%. - Localize source-site bounce links with the deploy stage, not by hand:
node skills/deploy/scripts/localize-links.mjs --source-host <live-host> --content content --redirects stardust/redirects.tsvrewrites every source-host href whose path exists in the content tree (header/footer/home included) to the canonical root-relative form and lists the ones it kept absolute (no local page — a bounce beats a 404). Re-run over the WHOLE tree after every wave: earlier waves' pages gain newly valid targets only when a later wave ships them.--checkis the gate (exit 2 = localizable links remain). - Link every internal page at its served URL (
deploy/scripts/eds-path.mjs): no.html, a slash only on a folder index (/x/)..htmland a leaf's slash 404 while.plain.htmlpasses. Repoint.htmllinks with no local page at the working source URL. - The audit GETs each href against the LIVE tree: the ledger alone misses slash and case defects.
- Targets missing from the capture. Two cases, both recorded in
direction.mdas a named decision with the list: a target the direction's caps meant to include is a CAPTURE GAP — crawl it first (capture → migrate → gate, never authored from a live read) and deliver when the gap is ≤ 12 pages, else repoint to the source site and list it as scope debt; a target outside the declared caps is SCOPE EXTENSION — repoint regardless of count. External targets: repoint to the source site; other-locale targets: repoint ONLY when that locale root was never captured. Any captured page — astardust/state.jsonrow, includingduplicateOfshells and locale roots — is in scope and is delivered, never repointed (the ≤ 12 rule is for UNcaptured pages; a recorded run dropped ten captured locale roots by citing it). Never leave a 404 (a recorded audit found 10 uncaptured in-scope pages — delivering them was the right call).
Phase F — Optimize: multi-source audit + gate (delivery quality)
The in-flow quality gate. optimize aggregates findings from existing audit
skills into one ledger (optimize/findings.json + optimize/scorecard.json),
tags each by fixability, and gates the rollout. Sources (full mapping in
reference/audit-sources.md):
rollout:baseline— built-in deterministic detectors:node skills/rollout/scripts/optimize.mjs # uses rollout.json site.liveHost # or: --base <url> | --root <dir> | --slug <s> | --allimpeccable:critique+impeccable:audit— design quality + a11y/perf.- The marketing SEO skills —
seo-audit,schema,ai-seo,site-architecture. stardust:tensions— mechanical design tensions fromstardust/current/brand-review.html.
Source parity. When the extract capture exists (stardust/current/pages/<slug>.json
and its rendered sidecar; --current <dir> to point elsewhere), baseline findings the
SOURCE shares — the same <title>, no description on the source either, no JSON-LD on
the source either, the same title shared by the same pages — are tagged fixability: out-of-scope with the evidence prefix source parity: and listed in their own report
section: informational, excluded from the health score and the open P1/P2/P3 counts,
never gated, never auto-fixed. A recorded hands-off run accepted 63 such findings by
hand. Everything else routes as before (reference/checks.md § Source parity).
Normalize each source's findings into the ledger with the writer:
node skills/rollout/scripts/findings.mjs record \
--source marketing:seo-audit --layer seo --check thin-content \
--severity P2 --fixability platform-migration \
--scope-ids blog/post --evidence "…" --recommend "…"
node skills/rollout/scripts/findings.mjs resolve <id> --status accepted --note "…"
All sources share one id space, dedup, scorecard, and the detect → fix → verify
loop: re-running a source resolves its own gone findings; a regressed fixed
finding re-opens; human accepted/wontfix are preserved. Fixability routing:
platform-migration → autofix / re-deploy; design-pass → upstream (surface
only); out-of-scope → informational. The gate exits non-zero if any open P1 is
in scope — a page is delivery-clean only when verify passes and the ledger has
no open P1.
At ~1k-page scale: a
head.html-level fix needs a site-wide republish to land and flip its per-page findings; the optimize gate only audits pages incoverage/pages.json; and faithfully migrated parallel source trees produce legitimate duplicate-title findings (a canonical decision, not a bug). Seereference/operational-learnings.md.
The judgment layers (brand-tensions, design-ux, content-conversion) are scored
null until populated by the impeccable/tensions sources — the scorecard shows
not-assessed rather than faking a score.
Phase G — AEM autofix (close the loop)
node skills/rollout/scripts/autofix-aem.mjs --project <eds-root> # [--dry-run] [--slug s] [--check c]
The platform autofix engine (AEM-EDS, v1 — aggressive). For every open finding
whose check has a registered EDS fixer, it edits the EDS project files, logs
the change on finding.autofix, and stages the finding in-progress:
- deterministic —
eds-fix-h1(exactly one<h1>), sitemap (re-assemble). - content-draft (logged for review) —
eds-metadata-title/eds-metadata-description,eds-alt-draft,eds-disambiguate-title. - manual (prepares guidance/payload) —
eds-jsonld(usemarketing:schema),eds-canonical,eds-landmark-main.
Use --dry-run first. After applying, re-deploy the edited pages, then re-run
verify + optimize — staged findings flip to fixed. design-pass findings
are surfaced, not auto-fixed.
Phase H — Report
Include the dynamic parity table (stardust/qa/dynamics-report.md, from Phase D2) next to
the delivery ledger: per feature its class, reach, status, owner decision and the replayed
check — so the report is honest about what the site does, not only what it shows.
Read rollout.json.lastRun + optimize/scorecard.json (or re-run inventory.mjs):
rollout — <site> → aem-eds
==================================================
Pages <N> total · <v> verified · <d> deployed · <p> pending · <cp> content-pending · <s> stale
Templates <T> (per-template delivered/total)
Blocks <B> total · <c> converted · <p> pending
Quality health <H>/100 · open P1 <n> / P2 <n> / P3 <n>
Pixel table prototypes <p>/<P> PASS · deployed <d>/<D> PASS (pixel-only <x>/<D>) — gates/{prototypes,all}-1440/summary.md
To deliver <list of remaining slugs>
Content <cp> pages awaiting content track (block code deployed, document not yet pushed)
Surface pending/stale/failed as the explicit "what's missing" list. The pixel-table
line comes from the two summary.json totals (pass, pixelOnlyPass, pages); a deployed
page missing from all-1440/summary.json is ungated and belongs in that list (#125).
content-pending pages are listed separately — not failures; their block code is
live and they advance to pending automatically when migrate emits their HTML
and inventory is re-run.
Also write/refresh stardust/learnings.md per
skills/stardust/reference/learnings.md: one entry per failure class this run
surfaced (evidence, proposed skill + section to change, status: pending).
plugin maintainers harvest pending entries into skill
diffs — this is how a run's hard-won fixes stop being re-learned.
Phase I — Dashboard
node skills/rollout/scripts/dashboard.mjs # → dashboard/index.html + data.json
A self-contained, no-external-JS dashboard rendered in the project's design
identity (brand tokens read from a migrated page's :root). Centerpiece: a
page tree of every identified page, nested by URL path, each node colour-coded
by the most-advanced lifecycle stage it reached:
identified → prototyped → deployed → optimised
The stage spans state.json (rostered/extracted/directed → identified,
prototyped/approved/migrated → prototyped), rollout coverage
(deployed/verified → deployed), and optimize (optimised = verified and no
open findings). A content-pending sibling stays at identified (it's in the
ledger so delivery can be tracked, but has no designed document yet). Legend counts
are cumulative. Template archetypes are badged T; a page with open
findings shows a red count. Also a templates table + the quality scorecard.
dashboard/data.json is the inspectable snapshot — regenerate at every iteration
boundary. (state.json is read-only and optional.)
Done is one verdict: the rollout is complete when node skills/rollout/scripts/done-check.mjs
exits 0; otherwise it prints one gap per line.
Inputs
| Input | Source | Used for |
|---|---|---|
stardust/migrated/*.html | migrate | the pages to deliver (read-only) |
stardust/migrated/**/_meta.json | migrate | templateId (template; an archetype with template: null groups under its own slug; else type), blocks (modules — the inventory report counts sidecars with an empty list: fill them before Phase B), widgets (widgets[] {id, href}), title |
stardust/state.json | stardust core | (archetypes-only mode) full page roster + type for pages not yet migrated |
stardust/rollout/rollout.json | rollout / user | DA target coordinates |
Outputs
| Path | Purpose |
|---|---|
stardust/rollout/coverage/pages.json | per-page delivery ledger (schema: schemas/rollout-pages.schema.json) |
stardust/rollout/coverage/templates.json | template grouping + roll-ups (schema: schemas/rollout-templates.schema.json) |
stardust/rollout/coverage/blocks.json | the block dedup ledger + EDS mapping (schema: schemas/rollout-blocks.schema.json) |
stardust/rollout/plan.json | dedup-driven delivery order + per-page convert/reuse briefs |
stardust/rollout/optimize/findings.json | multi-source quality findings ledger (schema: schemas/rollout-findings.schema.json) |
stardust/rollout/optimize/scorecard.json | quality scorecard + history (schema: schemas/rollout-scorecard.schema.json) |
stardust/rollout/rollout.json | config + lastRun summary (schema: schemas/rollout-config.schema.json) |
stardust/rollout/site/{sitemap.xml,robots.txt,manifest.json} | site-level assembly artifacts |
stardust/rollout/dashboard/{index.html,data.json} | self-contained progress dashboard + snapshot |
edits to the EDS project (content/**, styles/) | applied by autofix-aem (the only files rollout writes outside stardust/rollout/) |
| the delivered EDS site | produced by deploy per page (blocks/, widgets/, content/, fragments — owned by deploy) |
rollout writes under stardust/rollout/ and — only via autofix-aem — to the
EDS project it delivers to. It never modifies the agnostic core, state.json,
or migrated/ — those are read-only inputs.
Dependencies (audit sources — referenced, not vendored)
optimize orchestrates existing audit skills by invocation; they must be installed:
- impeccable (
critique,audit) — already a stardust dependency. - marketing skills —
seo-audit,schema,ai-seo,site-architecture. Optional; surface a note if absent. - stardust tensions — emitted in-repo by
extract(brand-review.html).
Normalize each one's output into the ledger via findings.mjs record. See
reference/audit-sources.md.
What rollout does NOT do
- No upstream redesign.
design-passfindings are surfaced, not fixed here. autofix only touches platform-fixable findings in the EDS project. - No new transport. Delivery is
deploy's DA Source API path, unchanged. - No redesign of the agnostic core.
extract/direct/prototype/migrateanddeployare untouched. - No full pre-migration requirement. Archetypes-only mode is first-class: block
code is deployed from the archetypes; remaining pages advance from
content-pendingtodeployedasmigrateemits their HTML — no rollout restart.
Scripts
scripts/inventory.mjs— migrated tree → page + template coverage (idempotent, stale-aware).--state <path>enables archetypes-only mode.scripts/blocks.mjs— distinct-block dedup ledger (blocks.json).scripts/plan.mjs— dedup-driven delivery order + per-page convert/reuse briefs.scripts/update-coverage.mjs— deterministic delivery state-writer for pages and blocks; re-derives all roll-ups.--new <slug> --path --template --originregisters a page built outside the migrated tree (D2) so it enters coverage.scripts/section-fidelity.mjs— source-fidelity gate scaffold (authored sections vs source heading outline; informs the gate, never auto-decides).scripts/assemble.mjs— site-level sitemap / robots / fragments manifest (the EXPECTED set);--verify-origin <live-origin>compares the SERVED/sitemap.xmlwith it and exits 1 on a mismatch.scripts/verify.mjs— full-site structural verification (HTTP or offline--root).scripts/optimize.mjs—rollout:baselinedetectors + the multi-source gate; exits non-zero on open P1. Findings mirroring the source capture are taggedsource parity:— informational, not scored, not gated.scripts/findings.mjs— record/resolve findings from the external audit sources.scripts/autofix-aem.mjs— the AEM autofix engine (edits the EDS project).scripts/dashboard.mjs— design-identity dashboard +data.jsonsnapshot.scripts/done-check.mjs— the completion verdict (Phase I); exit 0 = complete.scripts/lib.mjs— shared IO + roll-up + page-loading + autofix-registry helpers.
References
notes/rollout/PLAN.md— design, coverage model, phasing, open questions.reference/delivery-gates.md— Phase C gates + batched-delivery-at-scale flow.skills/dynamics/SKILL.md+ itsreference/— the dynamic surface: classes, triage axes, listings contract + query-index mechanics, pattern catalogue, parity report (B2/D2).reference/multilingual.md— per-language trees (D3).reference/operational-learnings.md— scaled-rollout gotchas (extend, republish, verify).reference/audit-sources.md— the audit-source → layer → fixability → autofix map.reference/checks.md— therollout:baselinecheck catalog.skills/stardust/reference/learnings.md— the per-run learnings ledger the report phase writes.skills/migrate/reference/fidelity-tiers.md— the archetype/sibling/thin tier contract Phase C records.skills/migrate/reference/media-reconciliation.md— the image-fidelity resolver's decision table.skills/deploy/SKILL.md— the single-page conversion methodology rollout drives.skills/deploy/da-deploy-protocol.md— the DA Source API transport.skills/migrate/SKILL.md— produces themigrated/+_meta.jsoninputs.schemas/*.schema.json— the coverage + config contracts.
stardust:spec — the migration spec, before the migration
The spec answers the people planning a migration (what to build, reuse, fix or decide) and the agent that runs it (archetypes, block backlog, contracts, redirects, a default for every decision). The agent builds it stage by stage.
Principles
- Evidence, then judgement. Stages S1–S6 and S8 measure the live site; S7 and S9 are judgement (mapping, reuse,
features, questions) recorded in
judgement/with a rationale per decision. - Blind judgement. Judge from the source site only (reference/judgement.md); state the provenance in
implementation.json#provenance. - Variants, not templates. CMS templates are loose; plan, capture and QA by layout variant (S8).
- Every open question ships a default. A hands-off migration applies it; a recorded answer replaces it.
- Computed, never typed. Every figure in findings, feature reach and question impact is a rule (reference/knowledge.md § Rules) the knowledge stage evaluates.
Setup
stardust/spec/spec.config.json (reference/config.md): origin, scopePath, template rule, parser profile
(aem-classic, aem-core, or generic for any other site) + main selector, optional maxPages, rum,
referenceBlocks. Copy the stardust, spec, diff, dynamics and deploy scripts to stardust/scripts/<skill>/ (the stages import them).
Stages
| # | Stage | Command (from the project root) | Output |
|---|---|---|---|
| S1 | Inventory | spec-inventory.mjs | <work>/inventory/ |
| S2 | Fetch | spec-fetch.mjs | <work>/fetch/ |
| S3 | Parse | spec-parse.mjs | <work>/parse/ |
| S4 | Links | spec-links.mjs, then spec-fetch.mjs --urls <work>/links/pages.txt --out <work>/links/pages.jsonl and spec-parse.mjs --fetch <work>/links/pages.jsonl --out <work>/links | <work>/links/ |
| S5 | Real-user data (optional) | spec-rum.mjs (key from $RUM_DOMAIN_KEY) | <work>/rum/rum.json |
| S6 | First capture | spec-pick.mjs --components-only, spec-capture.mjs | <work>/media/ |
| S7 | Judgement: mapping | spec-profile.mjs, spec-sheet.mjs <component>, write judgement/mapping.json, spec-map.mjs | <work>/map/page-blocks.jsonl |
| S8 | Variants + visuals | spec-variants.mjs, spec-pick.mjs, spec-capture.mjs | <work>/map/variants.json, <work>/media/ |
| S9 | Implementation | dynamics-detect.mjs --urls <reps> --out <work>/dynamics, spec-martech.mjs, chrome-explore.mjs <home> <work>/chrome/header.json; write judgement/catalog.json, implementation.json, findings.json, search-probes.json | <work>/, judgement/ |
| S10 | Knowledge | spec-knowledge.mjs | knowledge/ |
Each stage logs start and end to stardust/status.jsonl (ledger.mjs spec s1-inventory start). <work> is stardust/.work/spec/, never committed. Large sites: S2 runs at 4 parallel requests and is resumable —
start it, then write config and judgement scaffolding while it runs. One browser job at a time (S6/S8/S9), two tabs.
Judgement (S7, S9)
Start from templates/. mapping.json and catalog.json: reference/judgement.md. implementation.json:
reference/implementation.md. findings.json: 6–10 plain-text { title, text, chapter, rank } headlines. Recorded answers go in
judgement/answers.json.
Outputs
judgement/ and knowledge/ in stardust/spec/, committed; reference/knowledge.md is the contract. Raw material,
captures and crops stay in <work>.
Gates
- S7 passes when
spec-map.mjsreports no unmapped component and every block in the page blocks is incatalog.json(spec-knowledge.mjswarns otherwise). - S10 passes when
spec-knowledge.mjsexits 0 (every rule computed) and every open question has a default. - A blocked origin (S1 or S2 exit 3: bot challenges or refusals on 10% or more) stops the build: ask the user to
allow-list the crawler, or to choose
--headed(the plugin's real-Chrome challenge-solve tier ofbrowser.mjs, as replica uses) or--archive <date>(Internet Archive captures, which the provenance and a finding must disclose). Never choose for them, and never work around a block another way. - Before sharing: no customer secret, internal evaluation or other migration's name in the project or the output.
References
- reference/config.md —
spec.config.json, template rules, parser profiles. - reference/judgement.md — the blind rule, mapping rules, contact sheets, block families, reuse verdicts.
- reference/implementation.md — features, martech, data layer, metadata, indexes, locales, open questions.
- reference/knowledge.md — the output contract: files, fields, the rule format.
- reference/evaluation.md — scoring a spec against a delivered migration; blind re-judgement.
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)
-
Verify impeccable is installed. Stardust has a hard dependency on impeccable and ships no fallbacks. Look for the
impeccableskill 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. The same script with--whereprints impeccable's skill directory (the one holding itsSKILL.mdandreference/); note it once — the phases that read impeccable's format specs (reference/init.md,reference/document.md) read them from there by section, never after a filesystem search. -
Check the target-state files.
PRODUCT.mdandDESIGN.mdat 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. -
Read stardust's state. Read
stardust/state.jsonif present (reference/state-machine.mddefines the schema). Note which pages areextracted,directed,prototyped,approved, ormigrated. -
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. -
Status ledger. Every stardust skill appends a phase-transition line to
stardust/status.jsonlat each phase start/end, perreference/run-status.md— written withskills/stardust/scripts/ledger.mjs <skill> <phase> <start|end|blocked> [--detail …](--strictrefuses unknown phases), never with hand-builtprintf. Page status moves withskills/stardust/scripts/state.mjs advance <slug…> --to <status>; a resuming agent readsledger.mjs tailandstate.mjs summary. For progress, recommendnode stardust/scripts/stardust/ledger.mjs tail [-n 10]orlast [<skill>]; ledger has nosummarycommand. Report recorded status, not process liveness. -
Project hygiene (idempotent). Write
stardust/.gitignorefromreference/stardust.gitignoreif absent; never edit a project's copy. In a git repo: root.gitignorecovers.env/.env.*(managed# >>> stardustblock),.hlxignoreif present listsstardust/, andgit check-ignore -q stardust/state.jsonmust fail — if it passes, stop and name the rule. Offer, never write, LFS above 50 MB of tracked binaries understardust/. Details inreference/artifact-map.md§ Versioning. -
Copy this skill's whole
scripts/dir tostardust/scripts/stardust/before any other skill's script runs. Itsbrowser.mjsis the one entry to the browser for every script. A script you write opens every page this way (#159):newLiveContextandgotoLive, neverchromium.launch()orpage.goto:import { pathToFileURL } from 'node:url'; const { openBrowser, newLiveContext, gotoLive } = await import(pathToFileURL('stardust/scripts/stardust/browser.mjs').href); const browser = await openBrowser({ mode: 'chrome' }); const context = await newLiveContext(browser, { viewport: { width: 1440, height: 900 }, stateUrl: url }); const page = await context.newPage(); await gotoLive(page, url); // paced on a live site. A bot wall throws.
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 hasstardust/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 throughgrep, 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'sSKILL.mdand follow it inline. Never confuse the stardustextractandauditskills with impeccable'sextractandauditcommands, which are always written$impeccable <command>. The master skill routes all sibling sub-skills:keyword owns extractcrawl + capture the current site directresolve the visual direction prototypeper-page redesign prototypes migratefull-site platform-agnostic static HTML prepare-migrationthe migrate-prep cascade (prep phases, assets, dynamics gate) — redesign flow only replicasame-design migration (re-platform, keep the current design) — runs its own preserve-mode prep, then hands off to migrate/deploy/rollout reskinbyte-faithful content re-laid onto a separately defined donor design system deployone page → EDS blocks + DA delivery rolloutwhole migrated site → EDS, with coverage + delivery gates dynamicsthe 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 diffprototype ↔ build fidelity probes (pixel + structural) auditthree-perspective site audit — design tensions, SEO/technical, LLM visibility — scored report + findings ledger qaread-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 upliftone-shot presales orchestrator (3 variants) specpre-migration spec of a site — pages, blocks with reuse verdicts, dynamic features, martech, open decisions — as committed knowledge files prototypeaccepts--cinematic(or--cinematic=<register>) to layer a brand-faithful motion register on top of the static prototype (perskills/prototype/reference/motion-registers.md).upliftis 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 (perskills/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.mdand 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 instardust/direction.mdinstead 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 ask decides whether the design is kept or changed: a migration keeps its design unless the ask says to redesign it. That selects the flow; the downstream chain is shared.
- Scoping, before either flow: "scope / estimate / plan / spec the
migration of X", "which pages use block X", a redirect or 404 inventory →
spec. Flow-neutral: it never stampsflow. - Redesign while migrating:
extract→direct→prototype, or in one orchestrated stepprepare-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.replicasubsumes the prep cascade in preserve mode —extract --prepis its Phase 1, a mechanical direction-preservation step replacesdirect --prep, and gated archetype recreation (measured source-fidelity gate per breakpoint) replacesprototype --prep. Never runprepare-migrationbefore or afterreplica; 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-migration4.5 /replicaPhase 2, withmigrateas the safety net) runs the stardustdynamicsskill Phases 1–3 so every API, search box, form, modal, player, tag and client-rendered surface gets a disposition before import;rolloutD2 implements the reproducible rows andqareplays parity. Never for redesign-only work (uplift, a bareextract): dynamics is a migration concern.
Choosing, and recording the choice. Read the ask before any sub-skill loads:
- Keep-design phrases select
replicawithout 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: verbatimwith 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. Only an explicit phrase does; nothing is inferred.
- Anything else ("migrate X to EDS") is a faithful migration:
replica,flowSource: "default", no question, interactive and hands-off alike. The first response carries replica's flow line ("Flow: replica — the design is kept. Sayswitch to redesignnow if it is to change."), so the one decision stays visible. With 1,000+ sitemap URLs and no spec, it adds "Large site: sayspec firstto scope it." Offered only, never in hands-off mode.
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; a named assumption never sets decided-out |
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, said out loud. Default 100
pages overall, 20 per template; "all pages" (or
--all-pages) in the invocation lifts them; a user-named N replaces both and orders link-first (../extract/reference/ia-extraction.md§ Priority for the cap). Otherwise 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. The setup status line names the roster against the site (roster 94 of 2,532 discovered — cap 100/20); a capped roster is never called the full site. Record the caps indirection.md. - First page first. A full-site replica run delivers one page (home,
or the one named) first:
../replica/reference/first-page-first.md. - Captured pages stay in the roster. Locale is never a reason to
drop a captured page: every
state.jsonrow is delivered — duplicate-content locale shells ride the sibling tier of their twin;D3-multilingualis for language trees that were never captured. - 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 (replica shipsskills/replica/scripts/section.mjsfor exactly this:--listfor a document's outline, then one heading; it works on any Markdown file — a whole reference doc is 30–40k characters, the section a step needs is 2–4k, and one recorded session paid for three whole docs twice when theircatoutput overflowed and was re-read in full). Instruments that can stall run under their shipped deadline (replicagate.sh,pixel-compare --timeout) — never under an agent-authoredsleep N; killloop — 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 fixedsleepof 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: trueon 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.) The harness-neutral form of the same rule is replica'srun-bg.mjs:startdetaches the instrument,waitreturns within--max(default 100 s, ceiling 110 s — inside the shell tool's ~2-minute default timeout, which applies only to a call that declares none) with verdict lines only, exit 75 = still going,waitagain as the NEXT call — never in a shell loop, never after asleep. The rule binds the main agent as it binds subagents: one long instrument in the foreground, or two long instruments as parallel tool calls in one turn, is the same blocked step (recorded: a 338 s main-agent turn cost one full cache re-write). - One shell, one working directory. The harness's shell keeps its
working directory from one tool call to the next: a
cdinside a command moves every later command with it, and a path written from the project root then fails from wherever the previous call ended. Write paths from the project root (or absolute), and confine anycdto a subshell —(cd stardust/current && …). (Field evidence, 2026-09: onecdinto the capture directory failed the next three reads and cost a re-run turn.) - Author large files in parts. Write the skeleton, then append in edits of roughly 150 lines or less, so no single turn generates for longer than the prompt cache lives (about five minutes); a turn that outruns it leaves the next request with a cold cache and re-writes the whole context. (Field evidence, 2026-09: in one recorded run two such turns — the brand documents written in one go at the end of extract, and a first prototype's whole HTML and CSS in one write — each cost a full re-write of a ~200k-token context; an earlier run re-wrote 513k and 694k the same way. No compaction was involved; the sessions simply outran the cache lifetime inside one generation.)
- 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
.envpoisons 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:
- Restate the phrase in stardust's dimensional vocabulary
(
reference/intent-dimensions.md). - Identify which axes the phrase moves and in which direction.
- Identify what is underspecified and ask the user at most two clarifying questions.
- Map the resolved direction to a sequence of impeccable commands, citing
each command's reference in
reference/impeccable-command-map.md. - Show the proposed plan to the user before executing.
- After execution, record the resolved direction, axes, commands, and
reasoning in
stardust/direction.mdwith 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, gate images, two heavy
folders (migrated/assets/, rollout/qa/), .work/, run residue, session
state. Per-directory table and what a clone can and cannot do:
reference/artifact-map.md § Versioning.
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.
Named deviations. Any agent-authored crawler, compiler, importer,
wave driver or gate that replaces a skill phase is recorded in
stardust/direction.md as a named deviation — what it replaces, why
the shipped instrument did not serve, where the replacement lives — and
noted in the journal entry. An unrecorded parallel pipeline is a defect,
not initiative: three recorded migrations rebuilt the import pipeline by
hand (one a 60 KB importer) beside skills that shipped it, and their
fidelity numbers were never comparable to the gate's.
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):
- Render in Playwright (file:// for static, or local dev server), through
browser.mjs(§ Setup, step 7). - 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.
- 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.
- Save the final clean-pass screenshots to
stardust/validation/<artifact>/<viewport>.pngso 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.mdinstead 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
--pageslist 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.migrateemits platform-agnostic static HTML; the EDS conversion and delivery are owned by the stardustdeploy(one page) androllout(whole site) skills 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 24 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, provenance shape and (§ Versioning) what is tracked.reference/stardust.gitignore— installed asstardust/.gitignoreby Setup step 6.reference/divergence-toolkit.md— anti-mediocrity device. Default-moves list, deterministic seed, font decks, role-naming rule. Consumed bydirect(when authoring target tokens) andprototype(when generating variants).reference/token-contract.md—:rootCSS custom-property contract every prototype and migrated page must expose. The token interface between stardust and any downstream consumer.reference/data-attributes.md— structuraldata-*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.mdentry format. Append-only chronological log; the shared narrative layer over the state machine.reference/run-status.md— thestardust/status.jsonlphase-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-shapedderivedcandidates.
stardust:uplift
One entry point. One URL. Three presales-quality redesign variants.
uplift collapses the extract → direct → prototype × 3 chain into a
single opinionated command that picks every variability axis from the
captured brand surface rather than asking the user. The output is the
same as the long-form chain (state.json, brand-review.html, three
proposed files, motion validation) — the user just doesn't have to
coordinate it.
Opinionated defaults
- Single-page extract — the homepage by default (the brand
owner's first surface) unless
--page <slug>overrides. - Brand-faithful Mode A — palette + typography pinned. No invented colors, no fonts outside the captured surface.
- Three variants, fixed role contract — A is the green-light, B is the design-team motivator, C is the visionary cinematic pitch.
- Cinematic register auto-picked — C's motion register is
selected from the captured PRODUCT.md Brand Personality per
../prototype/reference/motion-registers.md§ Selection heuristic. - "What if..." candidates are evidence-shaped — B and C each
pick one captured-but-underused trait, from the eight worked
candidates in
reference/what-if-candidates.mdor a derived candidate per its § Extension rule. Different traits per variant. - Validation cascade runs — every gate in
prototype/SKILL.mdPhases 2.5–2.8 fires, including cinematic Pass 6 for variant C.
Inputs
<URL>— required. The page to redesign. Defaults to homepage when the URL has no path (https://example.com/→ home).--page <slug>— optional. Override the slug if the URL points elsewhere or the user wants a different surface.--cinematic-register <name>— optional. Override the auto-picked register for variant C. One ofarrival,kinetic-display,live-systems,editorial,kinetic-grid. Recorded asregisterSource: "user-override"in C's provenance.--two-variants— optional. Render only A and C (skip B). Useful when the brand surface is thin and a forced three-way differentiation would produce a weak middle (per the stop condition below).--re-extract— optional. Force a fresh crawl even when a prior extraction of the same URL is < 7 days old (see § Setup, reuse-if-fresh).
There are no other flags. Everything else is derived from the captured brand surface or governed by the underlying skills' contracts.
Setup
- Run the master skill's setup
(
../stardust/SKILL.md§ Setup): impeccable dep check, context loader, state read. - Verify Playwright is available (
extractwill fail without it — surface the same install message extract would). - Read
stardust/state.jsonif present. Reuse-if-fresh: when a prior extraction of the same URL is < 7 days old, skip Phase 1 and render against the existing capture, with a one-line notice ("reusing extraction from — pass--re-extractfor a fresh crawl").--re-extractforces a fresh crawl regardless of age; extractions ≥ 7 days old re-extract without asking.
Procedure
Six phases plus a reference-grounding interphase. Phases 1, 4, 5
delegate to existing skills; phases 2, 2.5, 3, 6 are owned by
uplift.
Phase 1 — Extract (delegate to the stardust extract skill)
Invoke $stardust extract <URL> --single (single-page mode).
Extract owns:
- Live Playwright render with the standard wait recipe.
stardust/current/_brand-extraction.json(palette + type + motifs- voice + system components + photography).
stardust/current/pages/home.json(full per-page capture).stardust/current/brand-review.htmlwith the tensions detectors applied — this is the load-bearing input for Phase 2.stardust/current/PRODUCT.mdandDESIGN.md(descriptive — the current state, not the target).
uplift does not crawl beyond one page. The brand surface from a
single homepage is sufficient for three variants; multi-page extract
is what the stardust extract skill (without --single) is for.
Phase 2 — Tension and trait identification (owned by uplift)
Read stardust/current/brand-review.html § Tensions surfaced and
_brand-extraction.json. Produce two artifacts:
2a — stardust/uplift-improvements.md
At least 3 specific weaknesses observed in the captured site — as many as the evidence supports, no fixed count. Same load-bearing contract as the existing presales workflow: without specifics, "make it better" has no claim. Category tags (MAY repeat across items when the evidence supports it):
[dated-pattern]— patterns the design world has moved past (be specific: "centered hero with stock photo + double CTA in primary blue reads as the SaaS template circa 2019")[ia-clutter]— cluttered IA / unclear hierarchy / weak CTAs / redundant sections[contrast-or-density]— contrast failures, accessibility gaps, density issues[cliché]— conventions the brand could move past while staying recognisably itself[missed-opportunity]— the captured surface doesn't capitalise on its own strengths ("captured photography is excellent but the layout crops it to thumbnail-size")
Specificity bar — every item. Each item cites a measurement, tension ID, or screenshot observation from the capture, names the pattern at fault, and proposes one concrete fix. An item that fails the bar is cut, not padded.
Audit consumption. When stardust/audit/<domain-slug>/audit.json
exists for this origin (written by the stardust audit skill),
consume its design findings as candidate improvements instead of
re-deriving them from scratch — cite the finding IDs in the item's
evidence and add the audit file to readArtifacts.
Refuse to proceed if fewer than 3 specific weaknesses can be named (see § Stop conditions).
Format (mirrors the provenance shape used by the rest of stardust):
---
_provenance:
writtenBy: stardust:uplift
writtenAt: <ISO-8601>
againstInput: <URL>
readArtifacts:
- stardust/current/_brand-extraction.json
- stardust/current/pages/<slug>.json
- stardust/current/brand-review.html
---
# Improvements — <URL>
1. **[<category-tag>]** <one-line headline> — <measurement /
tension ID / screenshot observation> · <pattern at fault> ·
fix: <one concrete fix>.
2. **[<category-tag>]** … (≥ 3 items; tags may repeat)
The bracketed tag preceding each weakness is a category from the list above. The headline is the one-sentence summary the agent will restate when variant A's shape brief applies the fix.
2b — stardust/uplift-questions.md
Six to eight "what if we leaned into…" candidates derived from the
captured brand surface. Each candidate cites the captured evidence
that makes it concrete. Candidates are drawn from the catalog in
reference/what-if-candidates.md — eight worked examples that are
the floor, not a ceiling:
- Display-typography amplification
- Photography re-foregrounding
- Live-data promotion
- Signature-gesture extension
- Voice-register pivot
- Color-ladder re-weighting
- Audience-routing reframe
- Motif vocabulary swap
An out-of-catalog derived candidate is admissible when it
carries the same evidence shape as the catalog entries: ≥ 2
captured citations + an explicit disqualification test + the
variant role it serves (per reference/what-if-candidates.md
§ Extension rule). Record each candidate's source —
catalog | derived — in the candidate list.
For each candidate the agent generates: a one-line "what if…" phrasing, the captured evidence that makes the candidate concrete, the variant role it best serves (B's composition bet vs C's cinematic bet), and whether the candidate is disqualified for this brand (e.g. "Photography re-foregrounding disqualified — the captured photography is generic stock; amplifying it would expose the weakness").
The disqualification step is what keeps the agent from reflexively picking the same candidate for every brand.
Phase 2.5 — Reference grounding (owned by uplift)
When reference research is available (per
skills/stardust/reference/reference-research.md — when to fire,
the 3–5 reference budget, the evidence shape, and provenance
recording are all defined there), ground the Phase 2 claims in
real-world references before Phase 3 picks directions:
(a) Ground each [dated-pattern] claim in
uplift-improvements.md with a named contemporary
counter-example — a real site / screen citation showing what
the pattern's world moved to.
(b) Anchor variant B's composition bet with a named real-world
compositional anchor — a real screen whose composition the bet
resembles.
(c) Verify C's register pick against how motion is actually
used in the vertical — does the register match observed
contemporary practice for this kind of brand?
Record the references per reference-research.md's provenance
contract (_provenance.referencesUsed[] on the artifact each
grounding serves). When reference research is unavailable, skip
with a one-line note in that provenance and proceed — the phase
degrades gracefully.
This phase never replaces captured-evidence discipline: references justify the MOVE, captured evidence justifies the TRAIT. A candidate without captured citations is inadmissible no matter how well-referenced its move is.
Phase 3 — Pick three variant directions (owned by uplift)
Default: three variants (A + B + C). When --two-variants is
active, skip § 3c (B's candidate selection) and the direction.md
authored in § 3d declares only A + C. Phase 4 then writes only
DESIGN-A and DESIGN-C files at the project root, and Phase 5
renders accordingly. All downstream contracts (variant
differentiation, motion validation on C, summary in Phase 6)
operate over the reduced variant set without modification.
3a — Pick the cinematic register for variant C
Read PRODUCT.md Brand Personality (from stardust/current/PRODUCT.md)
and apply the heuristic in ../prototype/reference/motion-registers.md
§ Selection heuristic. Record the picked register + the one-line
rationale.
3b — Pick C's "what if" candidate
The candidate must be the one the picked register naturally
amplifies through motion. The per-candidate Natural register
for C fields in reference/what-if-candidates.md are the single
source of truth for the register→candidate mapping — read the
mapping there (a derived candidate admitted per its § Extension
rule must declare the same field). This file does not duplicate
the table.
Fallback when C's natural candidates are all disqualified:
re-pick the second-choice register — the next-best match from
../prototype/reference/motion-registers.md § Selection heuristic
— and take its natural candidate. If the second-choice register's
natural candidates are also all disqualified, fall through to
--two-variants via stop condition (d): drop B and let C take the
strongest remaining non-disqualified candidate.
3c — Pick B's "what if" candidate
Pick from the remaining (non-disqualified, non-C) candidates in
uplift-questions.md. Prefer:
- A candidate that addresses a tension surfaced in
brand-review.html§ Tensions. - A candidate whose visual move is composition / IA / voice rather than motion (so B and C are differentiated by axis, not just intensity).
3d — Author stardust/direction.md
Write the resolved direction with three variant declarations:
## Variant A — Faithful + improvements
Role: risk-averse green-light. "Yes, that's us, with the obvious
fixes."
Composition: same as captured.
Motion: static (no cinematic layer).
Improvements applied: <list from uplift-improvements.md>.
## Variant B — What if we amplified <captured trait>?
Role: design-team motivator. The brand's underused capability
foregrounded.
What if: "<one-line "what if…" framing>"
Captured trait amplified: <trait from uplift-questions.md>
Evidence: <captured citation>
Composition: <specific layout strategy that amplifies the trait>
Motion: static (no cinematic layer).
## Variant C — What if motion was part of the identity?
Role: visionary pitch. The brand's third dimension — kinetic.
What if: "<one-line "what if…" framing tied to the register>"
Cinematic register: <register> (auto-picked from PRODUCT.md
Brand Personality)
Captured trait amplified: <trait — the one register naturally
amplifies>
Evidence: <captured citation>
Composition: identical IA to A; the bet is motion, not layout.
Motion: cinematic, register <register>.
Phase 4 — Direct (delegate to the stardust direct skill)
Invoke the stardust direct skill with the resolved direction. Pass the
three-variant declaration as the input phrase ("uplift presales
redesign — three variants per stardust/direction.md"). Direct owns:
- Mode A authoring of PRODUCT.md, DESIGN.md, DESIGN.json (root).
- Per-variant DESIGN-A / DESIGN-B / DESIGN-C files.
- The motion register block in DESIGN-C.json (read from the direction.md declaration).
- IA-priority preservation audit.
- Density floor enforcement.
- Anti-toolbox audit.
- Variant differentiation contract.
uplift does not duplicate any of those checks; it relies on
direct's existing validators to refuse if the variants violate
the brand-faithful contract.
Phase 5 — Prototype × 3 (delegate to the stardust prototype skill)
Render A first, then B and C:
- Render A — invoke
$stardust prototype <slug>scoped to variant A. A establishes and freezes the canon (tokens, chrome, module renderings) that B and C inherit; rendering it first removes the ordering race. - Render B, then C (default: sequential; parallel only where the
harness offers a subagent primitive, such as Claude Code's Agent
tool or Copilot CLI's
tasktool). B and C prototype the same slug, and same-slug concurrent runs are last-write- wins onstate.jsonper../stardust/reference/state-machine.md§ Concurrency — so in-place parallel rendering is unsafe. Parallel is permitted only via isolated workspace copies: each subagent gets a copy of the project (git worktree or directory copy) containing only its ownDESIGN-<id>.jsonat the root (siblings stashed), so prototype's file-presence detection renders exactly that variant. The subagent returns its<slug>-<id>-shape.md,<slug>-<id>-proposed.html(and C's-cinematic.html) plus provenance; the parent copies the artifacts back and performs the singlestate.jsonupdate for both variants. - Open each prototype as it completes (via the
openmechanics in Phase 6 step 1) rather than waiting for all three.
Prototype detects the variant set from the per-variant DESIGN-A,
DESIGN-B, DESIGN-C files that direct wrote in Phase 4 —
authoring <slug>-A-shape.md / -B-shape.md / -C-shape.md and
emitting <slug>-A-proposed.html / <slug>-B-proposed.html /
<slug>-C-proposed.html per the variant-convergence detector
contract (../prototype/SKILL.md § Phase 2.5 / Discipline 10).
Cinematic motion fires per-variant from the per-variant DESIGN
file, not from a CLI flag. Never pass --cinematic to
prototype from uplift. Because Phase 4 wrote
extensions.motion.register into DESIGN-C.json only (A and B
omit it), prototype's Phase 2.4 (motion application) fires only
for variant C. Variant C emits both <slug>-C-proposed.html
(the static reference) and <slug>-C-cinematic.html (the
register-applied surface). Variants A and B render static, never
acquiring the motion runtime.
Prototype owns:
- Page-shape brief authoring per Phase 1 of prototype.
- Render via
$impeccable craftdelegation, per variant. - Phase 2.4 motion application for variants whose
DESIGN-<id>.jsondeclares anextensions.motion.register. - Phases 2.5–2.8 quality gates (critique, audit, adapt, motion) per variant.
- Variant C's cinematic-mode gates (Pass 6) per
../prototype/reference/motion-validation.md. - Variant-convergence detector (≥ 2 structural changes per pair) per Discipline 10.
Multi-variant rendering is driven by the presence of multiple
DESIGN-<id>.json files at the project root, not by a CLI selector
— prototype has no --variant <id> input. That is exactly why the
parallel path in step 2 requires isolated workspace copies with a
single pinned DESIGN-<id>.json each: file presence is the only
variant selector prototype has. The A-first ordering above is what
keeps canon consistent across the B and C runs in either path.
Phase 6 — Open and summarize (owned by uplift)
After all three prototypes mark prototyped in state.json:
-
Confirm all three are open in the browser — each variant was opened as it completed (Phase 5 step 3); open any that weren't, using the
openshell command (notplaywright-cli open) so VFS paths are served via the preview service worker:open stardust/prototypes/<slug>-A-proposed.html open stardust/prototypes/<slug>-B-proposed.html open stardust/prototypes/<slug>-C-cinematic.htmlplaywright-cli openbypasses the preview service worker and produces a FILE NOT FOUND error for VFS paths. Always useopen <vfs-path>for local prototype files. -
Print the three-pitch summary in the chat:
uplift complete — three variants for <URL> A · Tomorrow's version of the site you have today. Improvements applied: <count>. File: stardust/prototypes/<slug>-A-proposed.html Pitch: "yes, that's us, fixed." B · What if we amplified <captured trait>? Trait: <name>. Composition bet: <one-line summary>. File: stardust/prototypes/<slug>-B-proposed.html Pitch: "the brand's underused capability, foregrounded." C · What if motion was part of the identity? Cinematic register: <register>. Motion bet: <one-line summary>. File: stardust/prototypes/<slug>-C-cinematic.html Pitch: "the brand's third dimension." Differentiation: A vs B ≥ 2 changes (✓), A vs C ≥ 2 changes (✓), B vs C ≥ 2 changes (✓). Validation: all three pass critique + audit + adapt; C additionally passes motion validation Pass 6. Next: iterate any variant via chat ("make B's hero quieter") or approve via the standard prototype approval flow (records the approval in state.json).
The summary is the user's only direct touchpoint with the three variants. Keep it short — the work is on disk and openable.
The three-variant role contract (hard)
| Variant | Pitch | Composition | Motion | Stakeholder |
|---|---|---|---|---|
| A | "Tomorrow's version." | Same IA + improvements applied | Static | Risk-averse green-light buyer |
| B | "What if we amplified <captured trait>?" | One captured-but-underused trait foregrounded in IA / composition / voice | Static | Design team that wants brand exploration |
| C | "What if motion was part of the identity?" | Same IA as A | Fully cinematic, register from brand surface | Visionary buyer + design lead |
This contract is non-negotiable. The "C is cinematic" rule is
how uplift reliably ships a third proposition that's defensibly
different from A and B (rather than the C-cliff failure mode of
"everything from B but bigger").
If the captured brand surface can't support three differentiated
variants (e.g. the palette has only one color, the captured page
has only two sections, the brand register doesn't map cleanly to
any motion register), reduce to two variants (A + C) via
--two-variants rather than ship three weak ones.
Hard constraints
Inherited from the underlying skills — uplift does not re-state
them but relies on them being enforced:
- Mode A pinning — palette + typography from captured brand
surface. Enforced by
direct/SKILL.md§ Mode A. - IA priority preservation — configurator stays above the
fold, crisis affordances stay first-viewport, etc. Enforced
by
direct/SKILL.md§ IA-priority preservation audit. - Density floor — brand-register pages with > 5 sections cap
sectionPadding.desktopat ≤ 64px. Enforced bydirect/SKILL.md§ Hard floor enforcement. - Variant differentiation — each variant differs from the
others by ≥ 2 changes. Enforced by
direct/SKILL.md§ Variant differentiation contract. - Captured images reused in semantic positions — hero stays
hero, story image stays story image. Enforced by
prototype/reference/proposed-file-shell.md§ Content sourcing hierarchy. - No fabricated content — stats, addresses, quotes, named
persons rendered as
[data-placeholder]not invented. Enforced byprototype/SKILL.mdPhase 2 § Content sourcing scan. - Site favicon in every variant's head — when
stardust/current/assets/favicon.<ext>exists, each variant page inlines it as a data: URI<link rel="icon">. Enforced byprototype/reference/proposed-file-shell.md§ Hard requirements #8. - C-cliff refusal for variant C — variant C bets on motion,
not on "everything from B but more." Enforced by
prototype/reference/motion-validation.md§ Pass 6f motion C-cliff detector. - Reduced-motion fallback for variant C — every motion
element is neutralized under
prefers-reduced-motion: reduce. Enforced byprototype/reference/motion-validation.md§ Pass 6b.
When any of these gates refuses, uplift surfaces the refusal
verbatim from the underlying skill — the user sees the specific
violation, not a generic "uplift failed" message.
Stop conditions
Stop and ask only if:
(a) Extract fails — site unreachable, structure unparseable,
bot-management blocks past the headed-Chrome fallback.
(b) Brand surface insufficient — palette has fewer than 2
distinct colors after clustering; OR the captured page has
fewer than 3 sections; OR the captured PRODUCT.md Brand
Personality maps to none of the five motion registers.
Surface honestly: "the captured brand surface is too thin
for three differentiated variants — render one strong variant
instead?"
(c) Improvements list empty — Phase 2a cannot name 3 specific
weaknesses. Without specifics, variant A has no brief and
"uplift" has no claim. Surface honestly.
(d) Two candidates equally weak — if B's "what if…" candidate
and C's cinematic candidate would amplify the same captured
trait, the variants would not differentiate. Switch to
--two-variants (A + C only).
(e) Hard rule conflict — captured palette has a single color,
captured typography has no display register, captured site
has no system components. Brand-faithful constraint
impossible without invention. Surface and ask.
The skill does not stop for confirmation in normal flow. The "PROCEED. Run all phases without stopping" property of the original presales prompt is preserved.
Outputs
stardust/
├── state.json ← extracted + 3× prototyped
├── direction.md ← resolved direction + 3 variant declarations
├── uplift-improvements.md ← load-bearing weakness list (≥ 3 items)
├── uplift-questions.md ← 6–8 "what if…" candidate list with disqualifications
├── current/ ← from extract
│ ├── PRODUCT.md
│ ├── DESIGN.md
│ ├── DESIGN.json
│ ├── brand-review.html
│ ├── _brand-extraction.json
│ ├── _crawl-log.json
│ ├── pages/<slug>.json
│ └── assets/
└── prototypes/
├── <slug>-A-shape.md
├── <slug>-A-proposed.html ← faithful + improvements
├── <slug>-B-shape.md
├── <slug>-B-proposed.html ← "what if amplifying <trait>"
├── <slug>-C-shape.md
├── <slug>-C-proposed.html ← static fallback for C
├── <slug>-C-cinematic.html ← cinematic variant C
├── lenis.min.js ← copied from skill assets
└── lenis.min.css
PRODUCT.md ← shared (Mode A)
DESIGN.md / DESIGN.json ← shared
DESIGN-A.md / DESIGN-A.json
DESIGN-B.md / DESIGN-B.json
DESIGN-C.md / DESIGN-C.json ← carries motion.register
Scope
- One page per run. Multi-page redesigns use the standard
extract→direct→prototypechain. - Three review surfaces, not a deployable bundle. After the brand
owner picks a variant, iterate via chat-driven impeccable
commands and approve via the standard
prototypeapproval flow. Migration is the stardustmigrateskill.
References
reference/what-if-candidates.md— the eight worked captured-trait amplification candidates that B and C pick from, plus the § Extension rule for evidence-shaped derived candidates.skills/stardust/reference/reference-research.md— procedure for sourcing real-world design references (Phase 2.5): when to fire, the 3–5 reference budget, the evidence shape, provenance recording.../prototype/reference/motion-registers.md— register catalog and selection heuristic used in Phase 3a.../prototype/reference/motion-validation.md§ Pass 6 — cinematic-mode validation gates that fire for variant C.../prototype/SKILL.md— multi-variant rendering and motion driven by the per-variantDESIGN-<id>.jsonfilesdirectwrote in Phase 4, not by a CLI selector or flag (uplift never passes--cinematic).../direct/SKILL.md§ Phase 2.6 — multi-variant fork; uplift passes the three-variant declaration through.../stardust/reference/data-attributes.md— structural section attributes applied by prototype to all three variants.../prototype/reference/proposed-file-shell.md— content sourcing hierarchy and placeholder convention.
Sponsors
Details
- Marketplace
- adobe/skills
- Source
- plugins/stardust
- Author
- Adobe
- Category
- Design
- License
- Apache-2.0
- Keywords
- design, redesign, frontend, skills, impeccable
More from adobe/skills
All 19- webv1.0.0
- workfrontv2.0.0
- adobe-analyticsv1.0.0
- adobe-cjav1.0.1
- adobe-for-developersv1.0.0
- aem-6-5-ltsv1.0.0
- aem-cloud-servicev1.4.4
- aem-edge-delivery-servicesv1.3.2
- aem-eds-content-opsv1.3.1
- aem-eds-personalizationv1.0.0
- aem-forms-edge-delivery-servicesv1.0.1
- aem-project-managementv1.0.1
- app-builderv1.0.0
- commerce-app-management
- commerce-app-migration
- commerce-app-reviewv1.0.0
- run-workflowv1.0.0
- semrushv1.0.0