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 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.mjs reports no unmapped component and every block in the page blocks is in catalog.json
(spec-knowledge.mjs warns otherwise).
- S10 passes when
spec-knowledge.mjs exits 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 from the diff skill's
live-session.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.
1---2name: spec3description: Build the pre-migration spec of a website — pages, redirects, 404s, layout variants, the EDS blocks each page needs with reuse verdicts, dynamic features, martech and open decisions — as documented knowledge files for people and a migration agent. Use when someone asks to scope, estimate or plan a migration, wants "which pages use block X / which blocks does page Y need", a redirect or 404 inventory, or the facts behind a migration brief. Not the migration itself (replica, migrate, rollout).4license: Apache-2.05compatibility: Requires Node 20+, and Playwright with Chromium resolvable from the project for the capture stages. Real-user data needs an AEM Operational Telemetry domain key.6metadata:7 source: https://skillmd.com/skills/adobe/spec8---910# stardust:spec — the migration spec, before the migration1112The spec answers the people planning a migration (what to build, reuse, fix or decide) and the agent that runs it13(archetypes, block backlog, contracts, redirects, a default for every decision). The agent builds it stage by stage.1415## Principles1617- **Evidence, then judgement.** Stages S1–S6 and S8 measure the live site; S7 and S9 are judgement (mapping, reuse,18 features, questions) recorded in `judgement/` with a rationale per decision.19- **Blind judgement.** Judge from the source site only (reference/judgement.md); state the provenance in20 `implementation.json#provenance`.21- **Variants, not templates.** CMS templates are loose; plan, capture and QA by layout variant (S8).22- **Every open question ships a default.** A hands-off migration applies it; a recorded answer replaces it.23- **Computed, never typed.** Every figure in findings, feature reach and question impact is a rule24 (reference/knowledge.md § Rules) the knowledge stage evaluates.2526## Setup2728`stardust/spec/spec.config.json` (reference/config.md): `origin`, `scopePath`, `template` rule, `parser` profile29(`aem-classic`, `aem-core`, or `generic` for any other site) + main selector, optional `maxPages`, `rum`,30`referenceBlocks`. Copy the spec, diff, dynamics and deploy scripts to `stardust/scripts/<skill>/` (the stages import them).3132## Stages3334| # | Stage | Command (from the project root) | Output |35|---|---|---|---|36| S1 | Inventory | `spec-inventory.mjs` | `<work>/inventory/` |37| S2 | Fetch | `spec-fetch.mjs` | `<work>/fetch/` |38| S3 | Parse | `spec-parse.mjs` | `<work>/parse/` |39| 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/` |40| S5 | Real-user data (optional) | `spec-rum.mjs` (key from `$RUM_DOMAIN_KEY`) | `<work>/rum/rum.json` |41| S6 | First capture | `spec-pick.mjs --components-only`, `spec-capture.mjs` | `<work>/media/` |42| S7 | Judgement: mapping | `spec-profile.mjs`, `spec-sheet.mjs <component>`, write `judgement/mapping.json`, `spec-map.mjs` | `<work>/map/page-blocks.jsonl` |43| S8 | Variants + visuals | `spec-variants.mjs`, `spec-pick.mjs`, `spec-capture.mjs` | `<work>/map/variants.json`, `<work>/media/` |44| 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/` |45| S10 | Knowledge | `spec-knowledge.mjs` | `knowledge/` |4647Each 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 —48start it, then write config and judgement scaffolding while it runs. One browser job at a time (S6/S8/S9), two tabs.4950## Judgement (S7, S9)5152Start from `templates/`. `mapping.json` and `catalog.json`: reference/judgement.md. `implementation.json`:53reference/implementation.md. `findings.json`: 6–10 plain-text `{ title, text, chapter, rank }` headlines. Recorded answers go in54`judgement/answers.json`.5556## Outputs5758`judgement/` and `knowledge/` in `stardust/spec/`, committed; reference/knowledge.md is the contract. Raw material,59captures and crops stay in `<work>`.6061## Gates6263- S7 passes when `spec-map.mjs` reports no unmapped component and every block in the page blocks is in `catalog.json`64 (`spec-knowledge.mjs` warns otherwise).65- S10 passes when `spec-knowledge.mjs` exits 0 (every rule computed) and every open question has a default.66- A blocked origin (S1 or S2 exit 3: bot challenges or refusals on 10% or more) stops the build: ask the user to67 allow-list the crawler, or to choose `--headed` (the plugin's real-Chrome challenge-solve tier from the diff skill's68 `live-session.mjs`, as replica uses) or `--archive <date>` (Internet Archive captures, which the provenance and a69 finding must disclose). Never choose for them, and never work around a block another way.70- Before sharing: no customer secret, internal evaluation or other migration's name in the project or the output.7172## References7374- reference/config.md — `spec.config.json`, template rules, parser profiles.75- reference/judgement.md — the blind rule, mapping rules, contact sheets, block families, reuse verdicts.76- reference/implementation.md — features, martech, data layer, metadata, indexes, locales, open questions.77- reference/knowledge.md — the output contract: files, fields, the rule format.78- reference/evaluation.md — scoring a spec against a delivered migration; blind re-judgement.