@hegemonart/get-design-done 1.59.2 → 1.59.4

package/figma-plugin/src/payload-schema.ts

@@ -0,0 +1,250 @@
+// figma-plugin/src/payload-schema.ts — Plan 31-05 (Wave B.2)
+//
+// Single plugin-side definition of the GDD Sync payload: the TS mirror of
+// scripts/lib/figma-extract/payload-schema.json (31-06), the shared Path C
+// contract (D-04, D-13). code.ts + export-variables.ts import the payload type
+// from here; buildPayload below is the PURE, network-free core the offline test
+// drives against a figma.variables mock.
+//
+// Two consumers, one payload (the make-or-break interop requirement):
+//   1. Receiver (31-06) validates source + collections[] + variables[] against
+//      payload-schema.json before writing variables.json.
+//   2. The digest's normalizePluginPayload (31-02) reads a FLAT tokens[] array
+//      (preferred) or payload.meta.* — it does NOT read top-level variables[].
+//      So the payload ALSO carries tokens[] (colors->hex, aliases->{name}, modes
+//      keyed by mode NAME) so plugin variables surface in DESIGN.md.
+//      additionalProperties:true permits the extra tokens[]. One object, both ends.
+//
+// D-13: ALL local variables are emitted — no published-only filter here; the
+// digest filters.
+
+/** Figma colour: 0..1 floats. `a` optional (RGB vs RGBA). */
+export interface GddRgba {
+  r: number;
+  g: number;
+  b: number;
+  a?: number;
+}
+
+/** Alias marker — kept resolvable: target id always, target name when looked up. */
+export interface GddVariableAlias {
+  type: 'VARIABLE_ALIAS';
+  id: string;
+  name?: string;
+}
+
+/** A per-mode value in the receiver-facing variables[] (raw, unrendered). */
+export type GddVariableValue =
+  | number
+  | string
+  | boolean
+  | GddRgba
+  | GddVariableAlias;
+
+// ── Receiver-facing shapes (validated against payload-schema.json) ────────────
+
+export interface GddSyncMode {
+  modeId: string;
+  name: string;
+}
+
+export interface GddSyncCollection {
+  id: string;
+  name: string;
+  modes: GddSyncMode[];
+}
+
+export interface GddSyncVariable {
+  id: string;
+  name: string;
+  /** COLOR | FLOAT | STRING | BOOLEAN (schema enum). */
+  resolvedType: string;
+  collectionId: string;
+  /** Keyed by modeId. Raw value or alias marker (digest renders later). */
+  valuesByMode: Record<string, GddVariableValue>;
+}
+
+// ── Digest-interop shape: the FLAT tokens[] normalizePluginPayload reads ───────
+// Matches digest.cjs extractTokensFromVariables() output so DESIGN.md is
+// identical across paths: { name, type, collection, modes:{ <modeName>: rendered } }
+// where rendered = hex for colours, `{targetName}` for aliases, primitive otherwise.
+
+export interface GddSyncToken {
+  name: string;
+  type: string;
+  /** Collection NAME (not id) — matches digest Path A. */
+  collection?: string;
+  /** Keyed by mode NAME → rendered value. */
+  modes: Record<string, unknown>;
+}
+
+export interface GddSyncPayload {
+  /** Path C marker the digest/receiver key on. Literal — never anything else. */
+  source: 'gdd-plugin';
+  fileKey?: string;
+  exportedAt?: string;
+  collections: GddSyncCollection[];
+  /** ALL local variables, raw values (D-13). */
+  variables: GddSyncVariable[];
+  /** Flat rendered tokens the digest consumes (variables[] is ignored there). */
+  tokens: GddSyncToken[];
+}
+
+// ── Pure value rendering (shared by the flat tokens[] builder) ────────────────
+
+function isRgba(v: unknown): v is GddRgba {
+  return (
+    typeof v === 'object' &&
+    v !== null &&
+    typeof (v as GddRgba).r === 'number' &&
+    typeof (v as GddRgba).g === 'number' &&
+    typeof (v as GddRgba).b === 'number'
+  );
+}
+
+function isAlias(v: unknown): v is GddVariableAlias {
+  return (
+    typeof v === 'object' &&
+    v !== null &&
+    (v as GddVariableAlias).type === 'VARIABLE_ALIAS' &&
+    typeof (v as GddVariableAlias).id === 'string'
+  );
+}
+
+/** Render Figma {r,g,b,a?} (0..1) to hex — mirrors digest.cjs rgbToHex. */
+export function rgbToHex({ r, g, b, a }: GddRgba): string {
+  const to = (v: number): string =>
+    Math.round(v * 255)
+      .toString(16)
+      .padStart(2, '0');
+  const hex = `#${to(r)}${to(g)}${to(b)}`;
+  return a !== undefined && a < 1 ? `${hex}${to(a)}` : hex;
+}
+
+/** colour→hex, alias→`{targetName}` (or `{id}`), else primitive passthrough. */
+export function renderTokenValue(raw: GddVariableValue): unknown {
+  if (isRgba(raw)) return rgbToHex(raw);
+  if (isAlias(raw)) return `{${raw.name || raw.id}}`;
+  return raw;
+}
+
+// ── The single pure builder (network-free; the testable core) ─────────────────
+
+/** Minimal collection shape buildPayload needs (mirrors VariableCollection). */
+export interface RawCollectionLike {
+  id: string;
+  name: string;
+  modes: ReadonlyArray<{ modeId: string; name: string }>;
+}
+
+/** Minimal variable shape buildPayload needs (mirrors Variable). */
+export interface RawVariableLike {
+  id: string;
+  name: string;
+  resolvedType: string;
+  variableCollectionId: string;
+  valuesByMode: Record<string, GddVariableValue>;
+}
+
+/** Resolve a variable id → name (Figma's getVariableById(...)?.name). */
+export type VariableNameResolver = (id: string) => string | undefined;
+
+export interface BuildPayloadOptions {
+  fileKey?: string;
+  exportedAt?: string;
+  resolveName?: VariableNameResolver;
+}
+
+/**
+ * Build a GddSyncPayload from raw collections + variables. PURE: no Figma
+ * globals, no network. Emits ALL variables passed in (D-13). Produces BOTH the
+ * receiver-facing variables[] (raw values, alias markers retained with resolved
+ * name) AND the flat rendered tokens[] the digest consumes.
+ */
+export function buildPayload(
+  rawCollections: ReadonlyArray<RawCollectionLike>,
+  rawVariables: ReadonlyArray<RawVariableLike>,
+  opts: BuildPayloadOptions = {}
+): GddSyncPayload {
+  const resolveName: VariableNameResolver = opts.resolveName || (() => undefined);
+
+  const collections: GddSyncCollection[] = rawCollections.map((c) => ({
+    id: c.id,
+    name: c.name,
+    modes: c.modes.map((m) => ({ modeId: m.modeId, name: m.name })),
+  }));
+  const collectionById = new Map<string, GddSyncCollection>(
+    collections.map((c) => [c.id, c])
+  );
+
+  const variables: GddSyncVariable[] = [];
+  const tokens: GddSyncToken[] = [];
+
+  for (const v of rawVariables) {
+    // Receiver-facing valuesByMode: raw values, but resolve alias targets to a
+    // name (keep id + type) so it stays auditable. Keyed by modeId (schema).
+    const rawValuesByMode: Record<string, GddVariableValue> = {};
+    for (const modeId of Object.keys(v.valuesByMode)) {
+      const value = v.valuesByMode[modeId];
+      rawValuesByMode[modeId] = isAlias(value)
+        ? { type: 'VARIABLE_ALIAS', id: value.id, name: resolveName(value.id) }
+        : value;
+    }
+
+    variables.push({
+      id: v.id,
+      name: v.name,
+      resolvedType: v.resolvedType,
+      collectionId: v.variableCollectionId,
+      valuesByMode: rawValuesByMode,
+    });
+
+    // Flat token for the digest: rendered values keyed by mode NAME so a
+    // multi-mode (light/dark) variable round-trips.
+    const collection = collectionById.get(v.variableCollectionId);
+    const modesByName: Record<string, unknown> = {};
+    const modeList = collection ? collection.modes : [];
+    if (modeList.length > 0) {
+      for (const mode of modeList) {
+        const raw = rawValuesByMode[mode.modeId];
+        if (raw !== undefined) modesByName[mode.name] = renderTokenValue(raw);
+      }
+    } else {
+      // No collection metadata — fall back to modeId so nothing is dropped.
+      for (const modeId of Object.keys(rawValuesByMode)) {
+        modesByName[modeId] = renderTokenValue(rawValuesByMode[modeId]);
+      }
+    }
+
+    tokens.push({
+      name: v.name,
+      type: v.resolvedType,
+      collection: collection ? collection.name : undefined,
+      modes: modesByName,
+    });
+  }
+
+  const payload: GddSyncPayload = {
+    source: 'gdd-plugin',
+    collections,
+    variables,
+    tokens,
+  };
+  if (opts.fileKey) payload.fileKey = opts.fileKey;
+  if (opts.exportedAt) payload.exportedAt = opts.exportedAt;
+  return payload;
+}
+
+/**
+ * Narrow an unknown to GddSyncPayload: the literal source marker + the two
+ * required arrays. Cheap structural check (the receiver validates fully).
+ */
+export function isGddSyncPayload(x: unknown): x is GddSyncPayload {
+  if (typeof x !== 'object' || x === null) return false;
+  const p = x as Partial<GddSyncPayload>;
+  return (
+    p.source === 'gdd-plugin' &&
+    Array.isArray(p.collections) &&
+    Array.isArray(p.variables)
+  );
+}

package/figma-plugin/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "module": "amd",
+    "moduleResolution": "node",
+    "lib": ["ES2017"],
+    "strict": true,
+    "outFile": "code.js",
+    "noEmitOnError": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "typeRoots": ["./node_modules/@types", "./node_modules/@figma"]
+  },
+  "include": ["code.ts", "src/**/*.ts"]
+}

package/figma-plugin/ui.html

@@ -0,0 +1,44 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <style>
+      body {
+        font-family: Inter, system-ui, sans-serif;
+        margin: 0;
+        padding: 16px;
+        font-size: 12px;
+        color: #1a1a1a;
+      }
+      button {
+        width: 100%;
+        padding: 10px;
+        font-size: 13px;
+        font-weight: 600;
+        color: #fff;
+        background: #18a0fb;
+        border: none;
+        border-radius: 6px;
+        cursor: pointer;
+      }
+      button:hover {
+        background: #0d8de0;
+      }
+      #status {
+        margin-top: 12px;
+        min-height: 16px;
+        color: #555;
+      }
+    </style>
+  </head>
+  <body>
+    <button id="export">Export to GDD</button>
+    <p id="status">Reads local Figma variables and POSTs them to the GDD receiver on localhost:5179.</p>
+    <script>
+      document.getElementById('export').onclick = function () {
+        document.getElementById('status').textContent = 'Exporting…';
+        parent.postMessage({ pluginMessage: { type: 'export' } }, '*');
+      };
+    </script>
+  </body>
+</html>

package/hooks/gdd-intel-trigger.js

@@ -4,7 +4,7 @@
  * hooks/gdd-intel-trigger.js — D5 (PostToolUse on Edit|Write)
  *
  * On every Edit/Write that touches a design-authoritative surface
- * (skills/**, agents/**, reference/**, skill-templates/**), spawn a
+ * (skills/**, agents/**, reference/**, scripts/skill-templates/**), spawn a
  * background, detached refresh of the .design/intel/ store so downstream
  * consumers (router, planner, audits) see the latest extracts without the
  * user paying for a full rebuild on the next /gdd run.
@@ -14,7 +14,7 @@
  *      camelCase field names (tool_name/toolName, tool_input/toolInput,
  *      file_path/filePath/path).
  *   2. If the edited path matches
- *        ^(skills|agents|reference|skill-templates)/.*\.(md|json)$
+ *        ^(skills|agents|reference|scripts/skill-templates)/.*\.(md|json)$
  *      (path-separator-agnostic), schedule a background refresh.
  *   3. Otherwise no-op — write {continue:true} and exit 0.
  *   4. Always exit 0. Never block. Never surface errors. Errors only ever
@@ -55,7 +55,7 @@ const path = require('node:path');
 const { spawn } = require('node:child_process');
 
 const LOCK_TTL_MS = 5 * 60 * 1000; // 5 minutes
-const TARGET_RE = /^(?:skills|agents|reference|source\/skills)\/.*\.(?:md|json)$/;
+const TARGET_RE = /^(?:skills|agents|reference|scripts\/skill-templates)\/.*\.(?:md|json)$/;
 
 /**
  * Extract the edited file path + tool name from a PostToolUse payload.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.59.2",
+  "version": "1.59.4",
   "description": "A design-quality pipeline for AI coding agents: brief, explore, plan, design, and verify UI work against your design system.",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",
@@ -25,9 +25,13 @@
     "docs/i18n/",
     "scripts/lib/",
     "scripts/cli/",
+    "scripts/skill-templates/",
     "scripts/install.cjs",
     "scripts/injection-patterns.cjs",
     "scripts/bootstrap.cjs",
+    "scripts/build-skills.cjs",
+    "scripts/generate-skill-frontmatter.cjs",
+    "figma-plugin/",
     "SKILL.md",
     "README.md",
     "CHANGELOG.md",
@@ -62,6 +66,7 @@
     "test:behavior": "node scripts/run-behavior-tests.cjs",
     "typecheck": "tsc --noEmit",
     "codegen:schemas": "node --experimental-strip-types scripts/codegen-schema-types.ts",
+    "codegen:schemas:check": "node --experimental-strip-types scripts/codegen-schema-types.ts --check",
     "lint:md": "npx --yes markdownlint-cli2 \"**/*.md\" \"#**/node_modules\" \"#.planning\" \"#.claude\" \"#test/fixtures/baselines\"",
     "lint:links": "npx --yes lychee --no-progress --accept 200,206,403,429 \"**/*.md\" || true",
     "lint:agentskills": "node scripts/lint-agentskills-spec.cjs",

package/reference/DEPRECATIONS.md

@@ -31,7 +31,7 @@ the scanner pattern list in lockstep.
 ## Authoring surfaces
 
 - **`skills/` as the authoring source** → **`source/skills/`** (Phase 42, deprecated)
-  → **`skill-templates/`** (v1.58.0, current). Two-step migration:
+  → **`skill-templates/`** (v1.58.0) → **`scripts/skill-templates/`** (v1.59, current). Migration:
 
   - **Phase 42** introduced multi-harness compilation. Skills moved to `source/skills/` with
     placeholders (`{{command_prefix}}` et al.; see `reference/skill-placeholders.md`) and the
@@ -43,10 +43,10 @@ the scanner pattern list in lockstep.
     tarball via `prepack`. Net: 232 tracked files dropped to 116, with no change to end-user
     install experience (the tarball still ships `skills/` pre-built).
 
-  Migration for contributors: **edit `skill-templates/`, never `skills/` directly**. After edits,
+  Migration for contributors: **edit `scripts/skill-templates/`, never `skills/` directly**. After edits,
   `npm run build:skills` regenerates `skills/` locally (or `npm install` does it automatically).
   `.claude-plugin/plugin.json`'s `"skills": ["./skills/"]` is unchanged - the plugin still loads
-  `skills/`, now produced from `skill-templates/`. The `detect-stale-refs.cjs` list is extended to
+  `skills/`, now produced from `scripts/skill-templates/`. The `detect-stale-refs.cjs` list is extended to
   emit warnings on lingering `source/skills/` path references.
 
 ## Scanner scope

package/reference/live-mode-integration.md

@@ -9,7 +9,7 @@ last_updated: 2026-06-03
 
 # Live Mode Integration
 
-This file is the meta-rules companion to the `gdd-live` skill (`skill-templates/live/SKILL.md`). It describes how `/gdd:live` turns a running dev server into a live design surface: the user picks a DOM element, the agent generates N variants in one batch, the variants hot-swap in place, the user accepts or discards, and the whole session persists. For the SKILL.md structural contract (line cap, description budget, frontmatter), see `./skill-authoring-contract.md`. The variants themselves are grounded in the Phase 45 domain indexes (`./spatial.md`, `./interaction.md`, `./color.md`, `./typography.md`, `./motion.md`).
+This file is the meta-rules companion to the `gdd-live` skill (`scripts/skill-templates/live/SKILL.md`). It describes how `/gdd:live` turns a running dev server into a live design surface: the user picks a DOM element, the agent generates N variants in one batch, the variants hot-swap in place, the user accepts or discards, and the whole session persists. For the SKILL.md structural contract (line cap, description budget, frontmatter), see `./skill-authoring-contract.md`. The variants themselves are grounded in the Phase 45 domain indexes (`./spatial.md`, `./interaction.md`, `./color.md`, `./typography.md`, `./motion.md`).
 
 There is NO bundled browser automation. The skill drives the Claude Preview MCP at runtime; the modules under `scripts/lib/live/` are pure and dependency-free.
 

package/reference/registry.json

@@ -1071,7 +1071,7 @@
       "path": "reference/skill-placeholders.md",
       "type": "meta-rules",
       "phase": 42,
-      "description": "Multi-harness skill-placeholder catalogue: the four placeholders ({{command_prefix}}/{{model}}/{{config_file}}/{{ask_instruction}}) + per-harness substitution table + the \\{{...}} escape + the <!-- harness-only: a,b --> block rule. Skills authored once in skill-templates/, compiled per-harness by scripts/build-skills.cjs via scripts/lib/build/factory.cjs reading scripts/lib/manifest/harnesses.json."
+      "description": "Multi-harness skill-placeholder catalogue: the four placeholders ({{command_prefix}}/{{model}}/{{config_file}}/{{ask_instruction}}) + per-harness substitution table + the \\{{...}} escape + the <!-- harness-only: a,b --> block rule. Skills authored once in scripts/skill-templates/, compiled per-harness by scripts/build-skills.cjs via scripts/lib/build/factory.cjs reading scripts/lib/manifest/harnesses.json."
     },
     {
       "name": "color",

package/reference/skill-metadata.md

@@ -10,7 +10,7 @@ last_updated: 2026-06-02
 # Skill Metadata Single Source of Truth
 
 `scripts/lib/manifest/skills.json` is the one place skill frontmatter is authored. A
-generator projects it onto every `skill-templates/<id>/SKILL.md`, the build step compiles
+generator projects it onto every `scripts/skill-templates/<id>/SKILL.md`, the build step compiles
 those into the shipped trees, and CI gates keep the three copies identical. This doc
 explains the file, the generator, and the description budget. For the structural rules a
 SKILL.md body must follow (line cap, progressive disclosure, frontmatter required fields),
@@ -20,7 +20,7 @@ see `./skill-authoring-contract.md`.
 
 The file is a JSON object: a `schema_version` integer and a `skills` array. Each array
 element is one skill record. Only `name` is required (it must equal the
-`skill-templates/<id>/` directory name); every other field is optional and omitted when it
+`scripts/skill-templates/<id>/` directory name); every other field is optional and omitted when it
 has no value.
 
 ```json
@@ -50,7 +50,7 @@ Metadata flows in one direction, and a `*:check` gate guards each hop:
 ```text
 skills.json
   -> generate-skill-frontmatter      (npm run generate:skill-frontmatter)
-  -> skill-templates/<id>/SKILL.md
+  -> scripts/skill-templates/<id>/SKILL.md
   -> build:skills                     (npm run build:skills)
   -> skills/  +  dist/claude-code/
 ```
@@ -64,7 +64,7 @@ skills.json
 - `--check`: the CI drift gate. It writes nothing and exits non-zero when any committed
   frontmatter differs from what the manifest would generate.
 
-`scripts/build-skills.cjs` then propagates `skill-templates/` into the committed `skills/`
+`scripts/build-skills.cjs` then propagates `scripts/skill-templates/` into the committed `skills/`
 tree and `dist/claude-code/`; its own check mode asserts that the built output equals the
 committed output. So the contract is: edit `skills.json`, regenerate, build. Never
 hand-edit a managed frontmatter line in `SKILL.md`, because the drift gate will fail.

package/reference/skill-placeholders.md

@@ -1,6 +1,6 @@
 # Skill Placeholders - Multi-Harness Source Compilation
 
-> Phase 42. Skills are authored once in `skill-templates/` with placeholders and compiled per-harness into
+> Phase 42. Skills are authored once in `scripts/skill-templates/` with placeholders and compiled per-harness into
 > `dist/<bundle>/<config-dir>/skills/...` by `scripts/build-skills.cjs` (the pure transform lives in
 > `scripts/lib/build/factory.cjs`; the per-harness values in `scripts/lib/build/harness-configs.cjs`,
 > which reads the Phase 41.5 manifest root `scripts/lib/manifest/harnesses.json`). The Claude-Code
@@ -68,4 +68,4 @@ scope (a maintenance trap) - see the Phase 42 CONTEXT.
 ## Validation
 
 `test/suite/phase-42-placeholders.test.cjs` asserts that every placeholder actually used across
-`skill-templates/` is documented in this file, and that `skill-templates/` mirrors the `skills/` skill count.
+`scripts/skill-templates/` is documented in this file, and that `scripts/skill-templates/` mirrors the `skills/` skill count.

package/scripts/build-skills.cjs

@@ -0,0 +1,146 @@
+'use strict';
+// Phase 42 — multi-harness skill build orchestrator.
+// v1.58.0 renamed source/skills/ → skill-templates/ (the source/ wrapper held only skills/
+// and added nothing). v1.58.0 ALSO gitignored skills/ as a pure build artifact — that broke
+// the Claude Code marketplace install path (Claude Code git-clones the plugin without running
+// `npm install`, so `./skills/` was absent post-clone). v1.58.1 reverts the gitignore:
+// skills/ is committed again so git-clone-based installs work; scripts/skill-templates/ remains the
+// canonical editable source; `prepare` still regenerates skills/ on contributor checkouts.
+//
+//   node scripts/build-skills.cjs [--harness <id>] [--check] [--zip]
+//
+// Reads scripts/skill-templates/**/*.md, applies the pure factory per harness config, and writes:
+//   - skills/**                            (the committed Claude-Code surface, regenerated in place)
+//   - dist/<bundleSlug>/<configDir>/skills/**  (per-harness bundles; build-only artifacts, gitignored)
+//
+// --check : no writes; verify the committed skills/ equals compile(scripts/skill-templates/),
+//           exit 1 on any byte drift. This is the CI drift gate.
+// --harness <id> : restrict to one harness (skips the skills/ in-place regen unless id === claude).
+// --zip   : after building, tar -czf dist/<bundleSlug>.tgz each bundle (graceful skip if tar absent).
+//
+// Idempotent + byte-stable: file walk is sorted; bytes are written verbatim (line endings preserved).
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { compile } = require('./lib/build/factory.cjs');
+const { CONFIGS, byId, claude } = require('./lib/build/harness-configs.cjs');
+
+const ROOT = path.resolve(__dirname, '..');
+const SRC = path.join(ROOT, 'scripts', 'skill-templates');
+const SKILLS = path.join(ROOT, 'skills');
+const DIST = path.join(ROOT, 'dist');
+
+function parseArgs(argv) {
+  const out = { check: false, zip: false, harness: null };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--check') out.check = true;
+    else if (a === '--zip') out.zip = true;
+    else if (a === '--harness') out.harness = argv[++i];
+    else if (a.startsWith('--harness=')) out.harness = a.slice('--harness='.length);
+  }
+  return out;
+}
+
+function walkMd(dir) {
+  const out = [];
+  for (const e of fs.readdirSync(dir, { withFileTypes: true }).sort((x, y) => x.name.localeCompare(y.name))) {
+    const p = path.join(dir, e.name);
+    if (e.isDirectory()) out.push(...walkMd(p));
+    else if (e.isFile() && e.name.endsWith('.md')) out.push(p);
+  }
+  return out;
+}
+
+/** Compile every source file for one config -> Map<relPath, string>. */
+function compileAll(config) {
+  const result = new Map();
+  for (const abs of walkMd(SRC)) {
+    const rel = path.relative(SRC, abs).split(path.sep).join('/');
+    result.set(rel, compile(fs.readFileSync(abs, 'utf8'), config));
+  }
+  return result;
+}
+
+function writeMap(map, destRoot) {
+  let written = 0;
+  for (const [rel, text] of map) {
+    const dst = path.join(destRoot, rel.split('/').join(path.sep));
+    fs.mkdirSync(path.dirname(dst), { recursive: true });
+    fs.writeFileSync(dst, text);
+    written++;
+  }
+  return written;
+}
+
+function bundleDir(config) {
+  return path.join(DIST, config.bundleSlug, config.configDir, 'skills');
+}
+
+/** Compare a compiled map against on-disk files under destRoot. Returns array of drifting rel paths. */
+function diffMap(map, destRoot) {
+  const drift = [];
+  for (const [rel, text] of map) {
+    const dst = path.join(destRoot, rel.split('/').join(path.sep));
+    let cur = null;
+    try { cur = fs.readFileSync(dst, 'utf8'); } catch { /* missing */ }
+    if (cur !== text) drift.push(rel);
+  }
+  return drift;
+}
+
+function runCheck() {
+  // v1.58.1: skills/ is committed (reverts v1.58.0 gitignore — Claude Code marketplace
+  // git-clones the plugin without running npm install, so `./skills/` MUST exist post-clone).
+  // --check is back to its original Phase 42 semantics: gate that committed skills/ matches
+  // compile(scripts/skill-templates/). If contributors edit scripts/skill-templates/ without re-running
+  // `npm run build:skills`, this catches the drift.
+  const cfg = claude();
+  const map = compileAll(cfg);
+  const driftSkills = diffMap(map, SKILLS);
+  if (driftSkills.length) {
+    process.stderr.write('build-skills --check: DRIFT detected (run `npm run build:skills` and commit).\n');
+    for (const r of driftSkills.slice(0, 10)) process.stderr.write(`  skills/${r}\n`);
+    if (driftSkills.length > 10) process.stderr.write('  ...\n');
+    return 1;
+  }
+  process.stderr.write(`build-skills --check: OK - skills/ matches scripts/skill-templates/ (${map.size} files).\n`);
+  return 0;
+}
+
+function tarBundle(config) {
+  const tgz = path.join(DIST, `${config.bundleSlug}.tgz`);
+  const r = spawnSync('tar', ['-czf', tgz, '-C', DIST, config.bundleSlug], { stdio: 'ignore' });
+  if (r.error || r.status !== 0) {
+    process.stderr.write(`  (zip skipped for ${config.bundleSlug}: tar unavailable)\n`);
+    return false;
+  }
+  return true;
+}
+
+function runBuild(opts) {
+  const targets = opts.harness ? [byId(opts.harness)].filter(Boolean) : CONFIGS;
+  if (opts.harness && targets.length === 0) {
+    process.stderr.write(`build-skills: unknown harness '${opts.harness}'\n`);
+    return 1;
+  }
+  let total = 0;
+  for (const cfg of targets) {
+    const map = compileAll(cfg);
+    total += writeMap(map, bundleDir(cfg));
+    if (cfg.id === 'claude') writeMap(map, SKILLS); // regenerate the committed Claude surface in place
+    if (opts.zip) tarBundle(cfg);
+    process.stderr.write(`  built ${cfg.bundleSlug} (${map.size} files)${cfg.id === 'claude' ? ' + skills/' : ''}\n`);
+  }
+  process.stderr.write(`build-skills: wrote ${total} files across ${targets.length} harness bundle(s).\n`);
+  return 0;
+}
+
+function main(argv) {
+  const opts = parseArgs(argv);
+  return opts.check ? runCheck() : runBuild(opts);
+}
+
+if (require.main === module) process.exit(main(process.argv.slice(2)));
+module.exports = { main, parseArgs, compileAll, bundleDir };