@hegemonart/get-design-done 1.59.3 → 1.59.4

package/scripts/skill-templates/live/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: gdd-live
+description: "Live in-browser design mode. The user picks a DOM element on a running dev server (via the Claude Preview MCP), the agent generates N design variants in one batch, they hot-swap in place through HMR or preview_eval using a data-gdd-variant marker, the user accepts or discards, and the whole pick-generate-accept loop persists to .design/live-sessions so it survives a crash or resume. Use when the user wants to iterate on the look of a live component against a real running server, asks to try variants on a page, or runs the live command with a url; falls back to a screenshot-only degraded mode on harnesses without MCP support. Activates for requests involving in-browser design iteration, picking an element on a dev server, or generating variants with hot-swap."
+argument-hint: "[--variants N] [--resume <session-id>] [url]"
+tools: Read, Write, Edit, Bash, Glob, Grep, Task
+user-invocable: true
+---
+
+# gdd-live - Live In-Browser Design Mode
+
+Pick a DOM element on a running dev server, generate competing design variants, hot-swap them in place, and accept the winner as a real source edit. Every step persists to `.design/live-sessions/<id>.json` so the session survives a crash or a later resume.
+
+The browser-side runtime, the harness-mode gate, the session store, the events feed, the post-check, the scope guard, and the bandit feed are all separate modules under `scripts/lib/live/`. This skill describes the loop and names the module that owns each step; it does not import them.
+
+For the full surface (the Preview MCP tools, the six `live_*` events, the session file, the bandit feed, degraded mode, the scope guard), see `../../reference/live-mode-integration.md`. For the SKILL.md structural contract, see `../../reference/skill-authoring-contract.md`.
+
+---
+
+## Arguments
+
+- `[url]` - the page to drive. Optional. When omitted, detect the dev server and use its root.
+- `--variants N` - how many variants to generate per pick. Default 3.
+- `--resume <session-id>` - reattach to an in-progress session in `.design/live-sessions/`.
+
+---
+
+## BOOT
+
+1. Probe the Preview MCP per `../../connections/preview.md`: `ToolSearch({ query: "Claude_Preview" })`, then `mcp__Claude_Preview__preview_list`. Empty ToolSearch means the MCP is not loaded.
+2. Resolve the harness live mode. The capability signal is `capability_matrix.mcp_support` in `scripts/lib/manifest/harnesses.json`, projected by `scripts/lib/live/harness-mode.cjs` (`liveModeFor(harnessId)`). A `puppeteer` result means full live mode; a `degraded` result means screenshot-only.
+3. If `mcp_support` is false for this harness, or Preview is unavailable, enter DEGRADED mode and say so plainly: variants are generated and captured as static screenshots, with no in-page hot-swap. Skip the INJECT and PICK steps; generate against the file the user names instead.
+4. Detect the dev server. Look for Vite, Next, Bun, or a static server (check `package.json` scripts plus a `preview_list` entry). Record the server descriptor on the session.
+5. Open or create the session via `scripts/lib/live/session-store.cjs` (`.design/live-sessions/<id>.json`). On `--resume`, load the named session (see RESUME).
+
+---
+
+## INJECT
+
+Inject the browser runtime once. Read `RUNTIME_JS` from `scripts/lib/live/runtime.cjs` and evaluate it in the page with `mcp__Claude_Preview__preview_eval`. The runtime is an idempotent IIFE bound to `window.__gddLive`, so a re-inject after navigation rebinds the same singleton rather than stacking listeners. It installs the pick handler and the variant-swap helpers, and stamps the live variant on the element via the `data-gdd-variant` attribute.
+
+---
+
+## PICK
+
+1. Arm the picker (`window.__gddLive.pick()`), then guide the user to click the target element. Use `preview_click` and `preview_inspect` to confirm the element and read its computed styles and bounding box.
+2. Read the pick report back. Its fields are documented in `pickReportShape` (selector, tagName, classList, boundingRect, computedStyle subset, current variant). The selector strategy prefers id, then a data-testid, then a tag plus class plus nth-of-type path.
+3. Emit a `live_pick` event through `scripts/lib/live/events.cjs` and append a `pick` entry to the session.
+
+---
+
+## GENERATE (one batch)
+
+1. Load the relevant Phase 45 canonical reference index FIRST, so variants are grounded in real guidance: the domain index that matches the picked element (for example `../../reference/spatial.md` for layout, `../../reference/interaction.md` for components and a11y, `../../reference/color.md` for color, `../../reference/typography.md` for type, `../../reference/motion.md` for animation).
+2. Generate all N variants in ONE batch (default 3), each a distinct, hypothesis-tagged design direction for the picked element. Do not generate them one at a time.
+3. For each variant: write the change atomically to the implicated source file, then make it live. With HMR running, the file write is enough; otherwise apply the variant in place with `window.__gddLive.swapVariant({ n, style, html })`, which sets `data-gdd-variant="n"` and applies the variant's style or markup.
+
+---
+
+## POST-CHECK
+
+Run the post-check on each variant via `scripts/lib/live/postcheck.cjs`, which invokes `gdd-detect`. Show the findings inline next to each variant. A variant that trips a finding is flagged, NOT auto-rejected: the user still decides. Append a `live_postcheck` event per variant.
+
+---
+
+## ACCEPT / DISCARD
+
+- ACCEPT one variant: apply the chosen variant as the canonical source edit, and revert the others in the page (`window.__gddLive.revert()` on each non-chosen element). Emit a `live_accept` event and feed the outcome to the design-variants bandit via `scripts/lib/live/bandit-feed.cjs` (a dev-time signal). Append an `accept` entry.
+- DISCARD: revert every variant in the page back to its captured original and leave the source untouched. Emit a `live_discard` event and append a `discard` entry.
+
+Either way, persist the result through `scripts/lib/live/session-store.cjs` before continuing.
+
+---
+
+## PERSIST
+
+Every step (boot, pick, generate, post-check, accept, discard) is written to the session file through `scripts/lib/live/session-store.cjs` as it happens. The on-disk event log uses the `pick`, `generate`, `accept`, `discard` kinds; the telemetry stream uses the six `live_*` event types. Writes are atomic, so an interrupted step never leaves a half-written session.
+
+---
+
+## RESUME
+
+With `--resume <session-id>`, load the named session from `.design/live-sessions/`. Only an `in_progress` session is resumable. Offer the user two choices: continue from the last recorded event (report what that was, for example "last pick was the primary button"), or start fresh (open a new session and leave the old one intact). Never silently replay completed events.
+
+---
+
+## SCOPE GUARD
+
+Never write outside the source files implicated by the picked element. Run every proposed write through `scripts/lib/live/scope-guard.cjs`, which maps the picked selector to its owning source files and rejects edits that fall outside them. If a variant would need a change beyond that scope (a shared token, a parent layout, a new dependency), stop and surface it to the user rather than widening the blast radius.
+
+## Constraints
+
+- Do NOT edit files outside the picked element's implicated sources (enforced by the scope guard).
+- Do NOT generate variants one at a time; generate the full batch, then swap.
+- Do NOT auto-reject a variant on a post-check finding; flag it and let the user decide.
+- In DEGRADED mode, state up front that hot-swap is unavailable and fall back to screenshots.
+- Persist before every user-facing prompt so a crash never loses accepted work.
+
+## LIVE COMPLETE

package/scripts/skill-templates/locale/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: gdd-locale
+description: "Inspects or sets the GDD CLI locale for this project. With no argument, reports the resolved locale (config.locale > env LANG > en), the fallback chain, and per-locale coverage (which message tables are complete vs placeholder). With a <code> (en/ru/uk/de/fr/zh/ja), sets .design/config.json#locale after previewing the change. Localizes --help, common error messages, and skill prompt headers via scripts/lib/i18n/; missing keys fall back to English, so a partial locale never breaks the CLI. Use to switch GDD's own output language."
+argument-hint: "[<code>]"
+user-invocable: true
+tools: Read, Write, Bash, Grep, Glob
+---
+
+# {{command_prefix}}locale
+
+Closes the English-only CLI gap: GDD's README is multilingual, but `--help`, errors, and skill prompt
+headers spoke English until now. This skill inspects or sets the project's locale. Contract:
+`../../reference/cli-localization.md`.
+
+## Invocation
+
+| Command | Behavior |
+|---|---|
+| `{{command_prefix}}locale` | Report the resolved locale, the fallback chain, and per-locale coverage. |
+| `{{command_prefix}}locale <code>` | Set `.design/config.json#locale` to `<code>` (en/ru/uk/de/fr/zh/ja), after preview. |
+
+## Steps
+
+1. **Resolve current.** Read `.design/config.json#locale` (if any) and the environment, then call the
+   resolver to report the active locale + chain:
+
+   ```bash
+   node -e '
+     const i = require("./scripts/lib/i18n/index.cjs");
+     let cfg = {}; try { cfg = JSON.parse(require("fs").readFileSync(".design/config.json","utf8")); } catch {}
+     const loc = i.resolveLocale({ env: process.env, configLocale: cfg.locale });
+     const cov = i.KNOWN_LOCALES.map((l) => `${l}:${(i.loadTable(l)._meta||{}).coverage||"?"}`).join("  ");
+     console.log(JSON.stringify({ resolved: loc, chain: i.fallbackChain(loc), coverage: cov }));
+   '
+   ```
+
+2. **No argument** → print the resolved locale, the fallback chain, and the coverage line (which
+   tables are `complete` vs `placeholder`). Stop.
+3. **`<code>` argument** → validate it is in `KNOWN_LOCALES` (en/ru/uk/de/fr/zh/ja). Unknown → print the
+   `error.invalid_locale` message + the known list, change nothing.
+4. **Preview + set.** Show `locale: <old> -> <code>`, then write `locale` into `.design/config.json`
+   (create the file if absent, preserving any existing keys). Confirm, and note that missing keys in a
+   placeholder locale fall back to English.
+
+## Output
+
+End with:
+
+```
+## LOCALE COMPLETE
+```

package/scripts/skill-templates/map/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: gdd-map
+description: "Dispatches 5 specialist codebase mappers in parallel. Produces .design/map/*.md files consumed by the explore stage."
+argument-hint: "[--only tokens|components|visual-hierarchy|a11y|motion]"
+tools: Read, Write, Bash, Task
+user-invocable: true
+---
+
+# Get Design Done - Map
+
+Parallel orchestrator. Spawns 5 specialist mappers, each writing one file under `.design/map/`. The explore stage consumes these when present. See `./reference/heuristics.md` §"Optimization rules" for parallel-spawn cost considerations.
+
+## Mapper → Output
+
+| Mapper | Output |
+|--------|--------|
+| `token-mapper` | `.design/map/tokens.md` |
+| `component-taxonomy-mapper` | `.design/map/components.md` |
+| `visual-hierarchy-mapper` | `.design/map/visual-hierarchy.md` |
+| `a11y-mapper` | `.design/map/a11y.md` |
+| `motion-mapper` | `.design/map/motion.md` |
+
+## Step 1 - Setup
+
+- Ensure `.design/map/` exists (create if missing).
+- Read `.design/config.json` → `parallelism` object. Use `reference/config-schema.md` defaults if absent.
+- Read `.design/STATE.md` - note `<connections>` (Figma availability for token-mapper).
+- Parse `$ARGUMENTS`. If `--only <name>`, restrict the dispatch set to one mapper.
+
+## Step 2 - Parallelism Decision
+
+Per `reference/parallelism-rules.md`: all 5 mappers have `parallel-safe: auto` with disjoint `writes:` (each writes a different `.design/map/*.md` file) - no hard-rule conflict. `typical-duration-seconds` sum (~210s) minus slowest (~45s) ≈ 165s savings → clears `min_estimated_savings_seconds`. Verdict: **parallel**.
+
+Write the verdict to STATE.md:
+
+```xml
+<parallelism_decision>
+  stage: map
+  verdict: parallel
+  reason: "5 mappers, parallel-safe: auto, writes disjoint, est savings ~165s"
+  agents: ["token-mapper", "component-taxonomy-mapper", "visual-hierarchy-mapper", "a11y-mapper", "motion-mapper"]
+  ruled_out: []
+  timestamp: [ISO 8601 now]
+</parallelism_decision>
+```
+
+`--only` → adjust `agents` and set `verdict: serial` with `reason: "single mapper requested"`.
+
+## Step 3 - Dispatch (concurrent)
+
+Spawn all selected mappers in a single response with multiple `Task()` calls:
+
+```
+Task("<mapper-name>", """
+<required_reading>
+@.design/STATE.md
+@reference/audit-scoring.md
+[@reference/accessibility.md — a11y-mapper only]
+[@reference/motion.md — motion-mapper only]
+</required_reading>
+
+You are <mapper-name>. Scan the codebase per your agent spec and write your
+output file under .design/map/. Emit your completion marker when done.
+""")
+```
+
+Wait for each completion marker: `## TOKEN MAP COMPLETE`, `## COMPONENT MAP COMPLETE`, `## VISUAL HIERARCHY MAP COMPLETE`, `## A11Y MAP COMPLETE`, `## MOTION MAP COMPLETE`.
+
+## Step 3.5 - Synthesize parallel mapper outputs (Plan 10.1-04, D-13/D-14/D-15)
+
+Each mapper has written its own `.design/map/*.md` (disjoint writes). Main-context doesn't need all 5 verbatim - invoke `synthesize` inline with `outputs:[<each file's text labelled "=== from <mapper> ==="]`, `directive: "Merge into cross-cutting DESIGN-PATTERNS.md preserving section headers; consolidate cross-mapper duplicates with source-agent names; target ~120 lines."`, `output_shape:"markdown"`.
+
+Wait for `## SYNTHESIS COMPLETE`. Write merged markdown to `.design/DESIGN-PATTERNS.md` (overwrite if present) - the primary explore-stage input; per-mapper files remain as drill-down evidence. `--only` (single mapper) → skip this step.
+
+## Step 4 - Collate
+
+Write `.design/DESIGN-MAP.md` - thin index linking to each `.design/map/*.md` with a one-paragraph summary from each file's header. If Step 3.5 ran, also cross-link to `.design/DESIGN-PATTERNS.md` and note at the top: "See DESIGN-PATTERNS.md for the merged cross-cutting summary - this index preserves per-mapper drill-down."
+
+## Step 5 - Report
+
+```
+━━━ Map complete ━━━
+Files: .design/map/tokens.md, components.md, visual-hierarchy.md, a11y.md, motion.md
+Index: .design/DESIGN-MAP.md
+Next: {{command_prefix}}explore (consumes .design/DESIGN-PATTERNS.md on happy path; .design/map/*.md available for drill-down)
+━━━━━━━━━━━━━━━━━━━━━
+```
+
+## MAP COMPLETE

package/scripts/skill-templates/migrate/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: gdd-migrate
+description: "Migrates a project off GDD's own deprecated paths after an upgrade. Reads the machine-readable registry in reference/DEPRECATIONS.md (via scripts/lib/deprecation-registry.cjs), scans the project's .design/config.json + any local skill/agent references for paths that are now deprecated or removed at the installed version, and PREVIEWS a diff before changing anything. Interactive by default (confirm per change); --yes auto-applies; --dry-run previews only. Read-first, never silent. Use after {{command_prefix}}update flags a breaking change."
+argument-hint: "[--yes] [--dry-run]"
+user-invocable: true
+tools: Read, Write, Bash, Grep, Glob
+---
+
+# {{command_prefix}}migrate
+
+Closes the GDD-on-GDD gap: when GDD moves or removes its own paths (e.g. the Phase 31.5
+`scripts/lib/**` → `sdk/**` reorg), a project that referenced the old paths needs updating. This skill
+consults the deprecation registry, finds the stale references **in this project**, and rewrites them -
+**after showing you the diff**. It never edits silently. Contract: `../../reference/DEPRECATIONS.md`.
+
+## Invocation
+
+| Command | Behavior |
+|---|---|
+| `{{command_prefix}}migrate` | Scan + preview every applicable migration, then confirm each before applying. |
+| `{{command_prefix}}migrate --dry-run` | Preview only - print the diff, change nothing. |
+| `{{command_prefix}}migrate --yes` | Apply every applicable migration without the per-change prompt (still prints what changed). |
+
+## Steps
+
+1. **Resolve the installed version** from `.claude-plugin/plugin.json` (`version`).
+2. **Load the registry.** Parse `reference/DEPRECATIONS.md` with the pure helper:
+
+   ```bash
+   node -e '
+     const fs = require("fs");
+     const dr = require("./scripts/lib/deprecation-registry.cjs");
+     const entries = dr.parseDeprecations(fs.readFileSync("reference/DEPRECATIONS.md","utf8"));
+     const version = require("./.claude-plugin/plugin.json").version;
+     // Only entries that are deprecated/removed at the installed version are actionable.
+     const actionable = entries.filter(e => dr.classify(e, version) !== "pending");
+     console.log(JSON.stringify({ version, actionable }));
+   '
+   ```
+
+3. **Scan the project** for each actionable entry's `Old` path:
+   - `.design/config.json` (string values referencing an old path),
+   - project-local skill/agent references (`grep` the repo, excluding `.git/`, `node_modules/`, and
+     GDD's own `reference/DEPRECATIONS.md`),
+   - any `require(...)`/import of a removed SDK path.
+   For a code rewrite, scaffold the edit with `scripts/lib/migration/codemod-gen.cjs` (Phase 39.1) -
+   you emit the change as a reviewable patch, you do not run a codemod engine.
+4. **Preview.** Print a unified-diff-style preview per file: `Old → New`, the registry status
+   (`deprecated` vs `removed`), and the migration hint. If `--dry-run`, stop here.
+5. **Confirm + apply.** Without `--yes`, ask per change. With `--yes`, apply all. Use `Write` to make
+   the edits; never touch a file the user didn't consent to.
+6. **Report.** Summarize: files changed, references rewritten, and any `removed`-status reference that
+   still has no replacement wired (flag it loudly - that one breaks at the installed version).
+
+## Boundaries
+
+- **Preview-first.** Nothing changes before you've shown the diff (or `--yes` was passed).
+- Migrates **this project's references** to GDD paths - it does not rewrite GDD's own source, and it
+  never performs a downgrade (reverse migrations are out of scope).
+- Read the registry; never invent a migration that isn't in `reference/DEPRECATIONS.md`.
+
+## Record
+
+Print a `## Migration summary` (version, actionable entries, files changed, unresolved `removed`
+references) and append one JSONL line to `.design/intel/insights.jsonl` recording the migration run.
+Close with:
+
+```
+## MIGRATE COMPLETE
+```

package/scripts/skill-templates/migrate-context/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: gdd-migrate-context
+description: "Migrates a pre-Phase-52 project from the flat .design/map/*.md mapper notes to the typed DesignContext graph at .design/context-graph.json. Reads the old map notes, runs the deterministic extract-*.mjs passes to build mapper fragments, merges them with merge-fragments.mjs, validates the result with validate-design-context.cjs, and flags every low-confidence transform for human review before anything is trusted. Read-first and reversible; --dry-run previews the plan without writing. Use when upgrading a project to the DesignContext graph and .design/map/*.md still holds the only structured design notes. Activates for requests involving migrating design maps, building the context graph from old notes, or DesignContext graph migration."
+argument-hint: "[--dry-run]"
+tools: Read, Write, Bash
+user-invocable: true
+---
+
+# {{command_prefix}}migrate-context
+
+Closes the pre-graph gap: before Phase 52 a project recorded its structured design knowledge as flat
+`.design/map/*.md` mapper notes (token map, component taxonomy, motion map, a11y map, visual-hierarchy
+map). Phase 52 introduced the typed DesignContext graph at `.design/context-graph.json`. This skill
+carries a project across that boundary: it reads the old map notes, rebuilds the graph deterministically
+from source, validates it, and surfaces anything it could not transform with confidence so a human can
+confirm it. It never trusts a low-confidence guess silently.
+
+Contracts: `../../reference/design-context-schema.md` (the Node / Edge / Fragment / Graph shapes) and
+`../../reference/design-context-tag-vocab.md` (the controlled `tags[]` vocabulary).
+
+## Invocation
+
+| Command | Behavior |
+|---|---|
+| `{{command_prefix}}migrate-context` | Run the full migration: read old maps, extract fragments, merge, validate, then report the low-confidence items for review. |
+| `{{command_prefix}}migrate-context --dry-run` | Preview only. Print the migration plan and what each step would write, change nothing on disk. |
+
+## Step 1 - Detect the pre-52 state
+
+Read the project layout before touching anything.
+
+1. List `.design/map/*.md`. These are the pre-52 mapper notes (for example `token-map.md`,
+   `component-taxonomy.md`, `motion-map.md`, `a11y-map.md`, `visual-hierarchy.md`). If the directory is
+   absent or empty, there is nothing to migrate: print `No .design/map/*.md notes found; nothing to
+   migrate.` and stop.
+2. Check whether `.design/context-graph.json` already exists. If it does, this is a re-run: keep the
+   existing graph as a backup reference and report that the migration will rebuild it. Do not delete it.
+3. In `--dry-run`, print the file list and the planned outputs (`.design/fragments/<mapper>.json` per
+   mapper, then `.design/context-graph.json`) and stop before Step 2.
+
+## Step 2 - Rebuild fragments deterministically
+
+The graph topology comes from the source tree, not from prose. Run each deterministic extractor over the
+configured source roots (default `src/`; read `source_roots` from `.design/STATE.md` if present). Each
+extractor is pure, dependency-free, and prints a schema-valid Fragment to stdout.
+
+```bash
+mkdir -p .design/fragments
+for mapper in tokens components motion a11y visual-hierarchy; do
+  node "${CLAUDE_PLUGIN_ROOT:-.}/scripts/lib/design-context/extract-${mapper}.mjs" src/ \
+    > ".design/fragments/extract-${mapper}.json"
+done
+```
+
+The extractors fill `id / type / name / subtype / tags / complexity` and every edge they can prove; they
+leave each node `summary` empty for the summary pass. Use the old `.design/map/*.md` notes as the source
+of the human-authored `summary` text and any tags the extractor could not infer: for each node whose name
+matches a map entry, copy that note's one-line description into the node `summary` and add any vocabulary
+tags it implies. This is the only place prose feeds the graph.
+
+## Step 3 - Merge into the canonical graph
+
+Merge the fragments into the single graph. The merger dedupes nodes by `id`, unions tags, prefers a
+non-stub summary over the empty stub, and keeps an edge only when both endpoints resolve to a node in some
+fragment. Dropped dangling edges are reported on stderr as `could-not-fix:` lines.
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT:-.}/scripts/lib/design-context/merge-fragments.mjs" \
+  .design/fragments --out .design/context-graph.json
+```
+
+Capture the stderr `could-not-fix:` lines. Each one is a transform the merge could not complete (a map
+note referenced an entity the extractor never found in source). These are low-confidence items for Step 5,
+not silent drops.
+
+## Step 4 - Validate
+
+Validate the merged graph. The validator checks structure, referential integrity (no dangling edges),
+unique ids, non-stub summaries (soft warning), and the controlled tag vocabulary (soft warning).
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT:-.}/scripts/validate-design-context.cjs" .design/context-graph.json
+```
+
+Exit `0` is clean, `1` is warnings only (stub summaries or unknown tags to tidy later), `2` is a hard
+error (a dangling edge or duplicate id) that must be fixed before the graph is trusted. On exit `2`, do
+not present the graph as migrated: report the errors and stop so a human can resolve them.
+
+## Step 5 - Flag low-confidence transforms
+
+Collect everything that needs human eyes and present it as one review list rather than applying it:
+
+- every `could-not-fix:` line from the merge (an unresolved or dropped edge);
+- every node still carrying an empty `summary` after Step 2 (a map note had no matching entity, or no
+  note existed);
+- every validator `WARN` (stub summary, tag outside the controlled vocabulary).
+
+Print the list with a clear heading and ask the user to confirm or correct each item. Do not auto-resolve
+a low-confidence transform: a wrong edge or a mislabeled node poisons every later graph query.
+
+## Step 6 - Deprecate the old map notes
+
+The flat `.design/map/*.md` notes stay readable for one minor version so nothing breaks mid-upgrade. Add a
+one-line deprecation banner to the top of each migrated map note (do not delete the file):
+
+```text
+> Deprecated: superseded by the DesignContext graph (.design/context-graph.json) as of Phase 52.
+> Read-only for one minor version; regenerate the graph with {{command_prefix}}migrate-context.
+```
+
+In `--dry-run`, describe this banner instead of writing it. Announce that the next minor version may remove
+the `.design/map/*.md` notes, and that the graph is now the source of truth.
+
+## Do Not
+
+- Do not trust a low-confidence transform silently. Every `could-not-fix:` line and every stub goes on the
+  Step 5 review list.
+- Do not delete `.design/map/*.md`. Add the deprecation banner and keep the notes for one minor version.
+- Do not hand-edit `.design/context-graph.json` to force validation green. Fix the fragment or the source,
+  then re-merge.
+- Do not edit the extractors, the merger, or the validator. This skill only calls them.
+
+## MIGRATE-CONTEXT COMPLETE

package/scripts/skill-templates/new-addendum/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: gdd-new-addendum
+description: "Scaffolds a new Phase-54 composable reference addendum for a design-system, framework, or motion library: validates the kind and the slug, defaults composes_into by kind, and writes a 4-section skeleton at reference/{systems|frameworks|motion}/<name>.md from the pure generator. Use when adding stack-specific guidance that an explore mapper should compose at spawn time and you want the frontmatter, the composes_into wiring, and the mandatory sections correct from the first commit. Activates for requests involving authoring a reference addendum, adding stack-specific mapper guidance, scaffolding a systems or frameworks or motion doc, or registering a new design-system."
+argument-hint: "<kind> <name>"
+tools: Read, Write, Bash, AskUserQuestion
+user-invocable: true
+---
+
+# {{command_prefix}}new-addendum
+
+**Role:** Scaffold a contract-compliant stack addendum. Validate the kind and the name, then write `reference/{systems|frameworks|motion}/<name>.md` from the pure generator at `scripts/lib/new-addendum.cjs`. This skill writes ONE reference file. It does NOT touch `reference/registry.json` and does NOT run any build; it prints the exact follow-up steps instead.
+
+An addendum is a registry entry, not a skill. Read `reference/registry.json` for the `type:"stack-addendum"` entry shape and `scripts/lib/mapper-spawn.cjs` for how `composes_into` selects an addendum at spawn time. Read one shipped example first, for instance `reference/systems/tailwind.md`, to match the house style.
+
+## Step 1 - Gather the fields
+
+1. **kind**: the first token of `$ARGUMENTS` if present, else ask. Must be one of `system`, `framework`, or `motion`. This picks the target subdir and the default `composes_into`.
+2. **name**: the second token of `$ARGUMENTS` if present, else ask. Must match `^[a-z0-9][a-z0-9-._]*$`. The basename is also the matcher key in `mapper-spawn.cjs`, so it must equal the value `detectStack` reports for this stack (for example `tailwind`, `nextjs`, `framer-motion`). Reject a `reference/{dir}/<name>.md` collision.
+3. **composes_into** (optional): accept the kind default, or override with a comma list of mapper names. Defaults: `system` to `token-mapper, component-taxonomy-mapper`; `framework` to `component-taxonomy-mapper, visual-hierarchy-mapper`; `motion` to `motion-mapper`.
+
+Resolve the target path and check for a collision:
+
+```bash
+node -e "
+const a = require('./scripts/lib/new-addendum.cjs');
+console.log(a.targetPathFor(process.argv[1], process.argv[2]));
+" "<kind>" "<name>"
+```
+
+If that path already exists, stop and tell the user to edit the existing file instead.
+
+## Step 2 - Write the file
+
+Build the record and render the skeleton with the pure generator, then write it with the Write tool (not shell redirection):
+
+```bash
+node -e "
+const a = require('./scripts/lib/new-addendum.cjs');
+const rec = a.buildAddendumRecord({
+  kind: process.env.AD_KIND,
+  name: process.env.AD_NAME,
+  composesInto: process.env.AD_COMPOSES || undefined,
+});
+process.stdout.write(a.renderAddendumMd(rec));
+"
+```
+
+`buildAddendumRecord` throws on an invalid kind, an invalid name, or a malformed composes_into list. Surface the thrown message to the user and re-prompt the offending field. Capture stdout and write it verbatim to the path from Step 1 via the Write tool.
+
+## Step 3 - Fill the four sections
+
+The skeleton ships four mandatory sections with TODO placeholders: Conventions, File patterns, Gotchas, Example output. Replace every TODO with terse vendor-checked bullets (keep the file at or under about 50 lines). Rules:
+
+- Lead with the real vendor docs URL in the attribution comment.
+- The Example output block uses ONLY the Phase 52 DesignContext schema (node types token / component / variant / state / motion-fragment / screen / layer; edge types uses-token / composes / extends / transitions-to / mirrors).
+- Tags must come from `reference/design-context-tag-vocab.md`; drop any tag not in that vocabulary.
+- For a motion addendum, reuse the `reference/motion-transition-taxonomy.md` duration classes (instant / quick / standard / slow / narrative) and call out the seconds-vs-ms-vs-no-duration unit trap.
+- No em dashes anywhere (the `lint:prose` gate scans `reference/`).
+
+## Step 4 - Tell the user the follow-up
+
+The skill stops here by contract. Print the next steps for the maintainer to run:
+
+```
+1. Add a registry entry for "<name>" to reference/registry.json
+   (name addendum-<kind>-<name>, path, type "stack-addendum", phase 54, kind, composes_into, description).
+2. node -e "require('./scripts/lib/reference-registry.cjs').validateRegistry({cwd:process.cwd()})"
+   must report ok:true (the round-trip scan picks up the new subdir file).
+3. npm test (the reference-registry + phase-54 suites must stay green).
+```
+
+The registry round-trip test stays red until the registry entry exists; that is expected and is the maintainer's step.
+
+## Do Not
+
+- Do not edit `reference/registry.json`, `package.json`, or `scripts/lib/manifest/skills.json`.
+- Do not run a build or the registry generator for the user; print the steps.
+- Do not write the file with shell redirection; use the Write tool so the content is exact.
+- Do not invent vendor facts; the addendum content must be vendor-checked.
+
+## NEW-ADDENDUM COMPLETE

package/scripts/skill-templates/new-cycle/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: gdd-new-cycle
+description: "Start a new design cycle. Creates cycle scope in STATE.md, initializes .design/CYCLES.md entry. Each cycle has its own goal and tracks its own decisions/tasks/pipeline runs."
+argument-hint: "[<goal>]"
+tools: Read, Write, AskUserQuestion
+---
+
+# {{command_prefix}}new-cycle
+
+The cycle is the hierarchical unit above individual pipeline runs: **Cycle > Pipeline run > Wave > Task**. Each cycle has a goal, tracks its own decisions, and can span many pipeline runs. `{{command_prefix}}complete-cycle` closes the cycle once goals are met and a retrospective is captured.
+
+## Steps
+
+1. Read `.design/STATE.md`. If `cycle:` field is populated and no `complete` flag, ask: "Cycle <N> is active. End it first with `{{command_prefix}}complete-cycle`?" Abort if user declines.
+2. If no goal was passed as an argument, ask (AskUserQuestion): "What is the goal for this design cycle? (e.g., 'Redesign the checkout flow', 'Improve dashboard accessibility')"
+3. Generate cycle ID: read `.design/CYCLES.md` if present, find the max `cycle-N`, increment. If CYCLES.md is missing, start at `cycle-1`.
+4. Update `.design/STATE.md` frontmatter: set `cycle: cycle-N`.
+5. Create or append to `.design/CYCLES.md`:
+
+   ```markdown
+   ## cycle-N: <goal>
+   **Started**: <date>
+   **Status**: active
+   **Goal**: <goal>
+   **Pipeline runs**: 0
+   **Decisions made**: 0
+   ```
+
+6. Reset the `<decisions>` section in STATE.md for the new cycle. Preserve prior decisions by prepending a comment marker `<!-- prior cycle decisions archived in CYCLES.md -->`.
+7. Print: "Cycle cycle-N started. Run `@get-design-done brief` or `@get-design-done explore` to begin."
+
+## Do Not
+
+- Do not archive prior artifacts here - that's `{{command_prefix}}complete-cycle`.
+- Do not overwrite the existing CYCLES.md - append only.
+
+## NEW-CYCLE COMPLETE

package/scripts/skill-templates/new-project/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: gdd-new-project
+description: "Initialize a new get-design-done project. Gathers project context, creates PROJECT.md and STATE.md, initializes first cycle. Run once per project before any pipeline stage."
+argument-hint: "[--name <project-name>]"
+tools: Read, Write, AskUserQuestion, Bash, Glob
+---
+
+# {{command_prefix}}new-project
+
+One-time project initialization. Replaces "run scan cold" by gathering context up front and producing PROJECT.md + STATE.md + cycle-1.
+
+## Steps
+
+1. **Existing check**: If `.design/STATE.md` exists, ask (AskUserQuestion): "Project already initialized. Re-initialize? (This does not delete existing work.)" Abort if declined.
+2. **Create directory**: `mkdir -p .design` via Bash.
+3. **Auto-detect from codebase** (do this before asking):
+   - Read `package.json` for framework (React/Next.js/Vue/SvelteKit/etc.).
+   - Glob for `tailwind.config.*`, `components/`, `src/`, `shadcn.json` to guess the design system.
+   - Use directory name as default project name.
+4. **Gather context** (AskUserQuestion, one at a time, pre-filled with detected values):
+   - Project name
+   - Project type (framework)
+   - Main design goal
+   - Primary user
+   - Design system / component library
+5. **Write `.design/PROJECT.md`**:
+   ```markdown
+   # Project: <name>
+   **Type**: <framework>
+   **Design system**: <system>
+   **Main goal**: <goal>
+   **Primary user**: <user>
+   **Initialized**: <date>
+   ```
+6. **Initialize STATE.md**: Copy from `reference/STATE-TEMPLATE.md`, fill in project name, set stage to `brief`, cycle to `cycle-1`.
+7. **Create `.design/config.json`** with defaults from `reference/config-schema.md`.
+8. **Initialize first cycle**: Write `.design/CYCLES.md` with a `cycle-1` entry (goal copied from PROJECT.md main goal, status `active`).
+9. **Seed project-local skills directory**: Create `./.claude/skills/` and write `./.claude/skills/README.md`:
+   ```markdown
+   # Project-Local Skills
+
+   Auto-loaded by gdd pipeline stages. See `reference/project-skills-guide.md` in the plugin.
+   Files named `design-*-conventions.md` are read by explore/plan/design.
+   Populated by `{{command_prefix}}sketch-wrap-up` and manual edits.
+   ```
+10. Print: "Project initialized. Run `{{command_prefix}}brief` to capture your design problem, or `{{command_prefix}}explore` to scan directly. Run `{{command_prefix}}connections` to wire up optional integrations (Figma, Storybook, Chromatic, etc.)."
+
+## Do Not
+
+- Do not delete or overwrite existing `.design/` artifacts if re-initializing.
+- Do not run any pipeline stage automatically - this is init only.
+
+## NEW-PROJECT COMPLETE