spec

---
name: spec
description: 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).
license: Apache-2.0
compatibility: 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.
---

# 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 and dynamics scripts to `stardust/scripts/spec/`, `stardust/scripts/diff/` and
`stardust/scripts/dynamics/` (S1, S2, S6 and S9 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`; 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 }` 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 stealth real-Chrome 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.

From adobe/skills at 940b879, shown as plain text under its license: Apache-2.0 (permissive). The license text is in plugins/stardust/skills/spec/SKILL.md.

• SKILL.md5.5 KB · 6ae548f2d244
• reference/
• config.md3.8 KB · e1c02a0c3855
• evaluation.md984 B · 26597e99973e
• implementation.md2.8 KB · 5afba1433e4b
• judgement.md3.6 KB · 8715a35ea6b2
• knowledge.md5.4 KB · ab695c8978c3
• scripts/
• lib.mjs24 KB · e150732770cf
• rules.mjs9.3 KB · b9f6c2de7beb
• spec-capture.mjs11 KB · 1fa82c4c2768
• spec-fetch.mjs11 KB · dbfba9870d49
• spec-inventory.mjs9.9 KB · 5a62238ac514
• spec-knowledge.mjs29 KB · b6632a9dc32d
• spec-links.mjs4.0 KB · 875498477650
• spec-map.mjs8.7 KB · 30b75cd327ec
• spec-martech.mjs9.2 KB · e9c6e9194f61
• spec-parse.mjs11 KB · 6cc36cd150b0
• spec-pick.mjs2.5 KB · 027b101d05bd
• spec-profile.mjs3.4 KB · ecdc0a5f4c3d
• spec-rum.mjs5.6 KB · 2edff36a0b2d
• spec-sheet.mjs3.4 KB · bf61856674c7
• spec-variants.mjs4.4 KB · a064b309fdea
• test/
• rules.test.mjs5.5 KB · 216e69323796
• spec-capture.test.mjs1.5 KB · 39132e6192a5
• spec-fetch.test.mjs2.9 KB · 58ddf2546582
• spec-inventory.test.mjs3.1 KB · ff75b55ad2a5
• spec-knowledge.test.mjs11 KB · c63679ac7a49
• spec-links.test.mjs1.7 KB · 6790c1ad73db
• spec-map.test.mjs4.1 KB · 6c977a7d161f
• spec-martech.test.mjs4.4 KB · 46a9366aaaff
• spec-parse.test.mjs7.3 KB · 45354326c247
• spec-pick.test.mjs1.7 KB · f4585187158f
• spec-profile.test.mjs1.9 KB · e4aace2aeff2
• spec-rum.test.mjs2.4 KB · 49ec9eb44c46
• spec-sheet.test.mjs1.6 KB · dabe82137f12
• spec-variants.test.mjs1.8 KB · 70ef8e0acfd6
• templates/
• catalog.json954 B · 87946a2624f8
• findings.json511 B · 94e0cf9c454f
• implementation.json704 B · c6481c3c71df
• mapping.aem-core.json1.6 KB · 8a281dea81c8
• open-questions.json12 KB · 05f691425613

40 files, 235 KB in total. Each file has a sha256 in the pin's manifest; the first 12 characters are shown.