@hegemonart/get-design-done 1.41.5 → 1.42.0

package/dist/claude-code/.claude/skills/watch-authorities/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: gdd-watch-authorities
+description: "Fetches the design-authority feed whitelist, diffs against .design/authority-snapshot.json, and writes .design/authority-report.md (consumed by /gdd:reflect). Authority monitoring only — no trend-watching."
+argument-hint: "[--refresh] [--since <date>] [--feed <name>] [--schedule <weekly|daily|monthly>]"
+tools: Read, Write, Task, Bash
+---
+
+# /gdd:watch-authorities
+
+Runs `design-authority-watcher` on demand. Fetches the curated design-authority feed whitelist, diffs against the prior snapshot, classifies new entries into five buckets, and writes `.design/authority-report.md`. Phase 11's reflector picks up the report automatically when you next run `/gdd:reflect`.
+
+Authority-monitoring only. Not trend-watching. See `reference/authority-feeds.md` §"Rejected kinds" for what this skill will never fetch.
+
+## Steps
+
+1. **Parse args.** Extract optional flags: `--refresh`, `--since <date>`, `--feed <name>`, `--schedule <cadence>`. Anything that doesn't match one of these is an error — print `Unknown flag: <arg>. Valid flags: --refresh --since <date> --feed <name> --schedule <weekly|daily|monthly>.` and STOP.
+
+   Mutual exclusion rules:
+   - `--schedule` is handled entirely by this skill — it does not combine with the other three. If `--schedule` is present alongside any of `--refresh | --since | --feed`, print `--schedule cannot combine with other flags. Schedule registration runs this skill with no flags at the configured cadence.` and STOP.
+   - `--refresh` and `--since` are mutually exclusive — print `--refresh and --since are mutually exclusive. --refresh re-seeds the snapshot silently; --since surfaces a backlog from a boundary date. Pick one.` and STOP.
+
+2. **Handle `--schedule <cadence>` branch** (early-return).
+
+   If `--schedule` is set:
+   - Validate cadence ∈ {`weekly`, `daily`, `monthly`}; else print `Unknown cadence: <value>. Use one of: weekly, daily, monthly.` and STOP.
+   - Probe for the scheduled-tasks MCP via ToolSearch:
+
+     ```
+     ToolSearch({ query: "scheduled-tasks", max_results: 3 })
+     ```
+
+   - If the probe returns an empty result set: print `scheduled-tasks MCP not connected. Install it with: claude mcp add scheduled-tasks ... then retry with --schedule.` — this is a documented fallback (not an error). Terminate with `## WATCH COMPLETE` and exit 0.
+   - If the probe returns one or more `scheduled-tasks` tools: register the cron. Discover the MCP's registration tool name at runtime from the ToolSearch result and follow its schema. Target command: `/gdd:watch-authorities` with NO flags (the cron invokes the default diff-and-report behavior). Cadence → cron expression mapping:
+     - `weekly`  → `0 9 * * 1` (Mondays 09:00 local)
+     - `daily`   → `0 9 * * *` (every day 09:00 local)
+     - `monthly` → `0 9 1 * *` (1st of each month 09:00 local)
+   - After registration: print `Scheduled /gdd:watch-authorities to run <cadence>.` and terminate with `## WATCH COMPLETE`.
+
+3. **Validate `--since <date>`** (if present).
+
+   Accept ISO8601 (`YYYY-MM-DD` or `YYYY-MM-DDTHH:MM:SSZ`). Sanity-check via Bash `date -d "<value>" +%s` (GNU) or the POSIX equivalent `python3 -c "from datetime import datetime; datetime.fromisoformat('<value>'.replace('Z','+00:00'))"`. On parse failure: print `Invalid --since value: <value>. Use ISO8601 (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ).` and STOP.
+
+   If the parsed date is earlier than `2020-01-01`, ask: `Very old --since value: <value>. Did you mean something more recent? Proceed? [y/N]`. On anything other than `y`/`Y`, STOP.
+
+4. **Spawn the watcher.**
+
+   Build the `Task(subagent_type="design-authority-watcher", ...)` prompt. The prompt supplies the agent's required-reading block (watcher step 0), echoes the invocation flags verbatim (watcher Flags section), and instructs the agent to follow its own fetch/diff/classify/write loop:
+
+   ```
+   Task("design-authority-watcher", """
+   <required_reading>
+   @reference/authority-feeds.md
+   @.design/authority-snapshot.json
+   @.design/STATE.md
+   </required_reading>
+
+   Invocation flags: <joined flag list or "none">
+
+   Fetch the feeds listed in reference/authority-feeds.md, diff against .design/authority-snapshot.json,
+   classify new entries per the D-17 decision table, write .design/authority-snapshot.json and
+   .design/authority-report.md.
+
+   Terminate with ## WATCH COMPLETE.
+   """)
+   ```
+
+   `<joined flag list>` is the subset of `--refresh | --since <date> | --feed <name>` actually passed — e.g., `--refresh`, `--since 2026-03-01`, `--feed wai-aria-apg`, `--refresh --feed radix-ui-releases`, or literally `none` when no flags were supplied.
+
+5. **Print summary.**
+
+   After the agent returns:
+   - If STATE.md gained a `<blocker type="contract-violation">` on this run (snapshot version mismatch, hash-format violation, or over-200 entries per feed), surface the blocker verbatim and stop — do not print the default "review and reflect" line.
+   - Otherwise print the agent's one-line stdout summary (normal mode: `Surfaced N entries across M feeds. K skipped. See .design/authority-report.md.`; first-run / refresh mode: `Seeded snapshot for N feeds — next run will surface new entries.`) followed by: `Review and reflect: /gdd:reflect`.
+
+6. **Terminate with `## WATCH COMPLETE`.**
+
+## Do Not
+
+- Do not modify `agents/design-authority-watcher.md`.
+- Do not modify `agents/design-reflector.md` — Phase 13.2 does not touch the reflector agent (CONTEXT.md D-25).
+- Do not write to `.design/authority-snapshot.json` or `.design/authority-report.md` directly — those are the agent's writes.
+- Do not fetch URLs outside `reference/authority-feeds.md`. The whitelist is the allow-list.

package/dist/claude-code/.claude/skills/zoom-out/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: zoom-out
+description: "Asks the agent to go up a layer of abstraction and map the relevant modules and callers using the project's CONTEXT.md vocabulary. Use when the user is working in an unfamiliar area of code and needs orientation before deep work."
+disable-model-invocation: true
+argument-hint: "[scope]"
+---
+
+Source: mattpocock/skills (MIT) — adapted with permission. See `../NOTICE` for the full attribution block.
+
+# Zoom Out
+
+**Role:** Give the user a map, not a fix.
+
+I don't know this area of code well. Go up a layer of abstraction. Give me a map of all the relevant modules and callers, using the project's domain glossary (`CONTEXT.md`) vocabulary.
+
+When invoked, produce a one-screen map that names:
+
+1. **Modules in scope** — one-line description of each, using terms from `CONTEXT.md` (see `./../reference/context-md-format.md` for the schema). Do not invent terms.
+2. **Callers** — who calls these modules from elsewhere, with file paths.
+3. **Seams** — where data crosses module boundaries, named per `./../reference/architecture-vocabulary.md`.
+
+Do not propose fixes. Do not write code. The output is a map.
+
+If `CONTEXT.md` is absent, suggest `/gdd:discuss` to start one, but still produce the map using basenames and inferred terms.
+
+## ZOOM-OUT COMPLETE

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.41.5",
+  "version": "1.42.0",
   "description": "A design-quality pipeline for AI coding agents: brief, plan, implement, and verify UI work against your design system.",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",
@@ -23,6 +23,7 @@
     "sdk/",
     "recipes/",
     "docs/i18n/",
+    "dist/claude-code/",
     "scripts/lib/",
     "scripts/cli/",
     "scripts/install.cjs",
@@ -47,6 +48,8 @@
   },
   "scripts": {
     "build:bundles": "node scripts/build-distribution-bundles.cjs",
+    "build:skills": "node scripts/build-skills.cjs",
+    "build:skills:check": "node scripts/build-skills.cjs --check",
     "build:sdk": "node scripts/build-sdk-bins.cjs",
     "prepack": "npm run build:sdk",
     "postpack": "node scripts/build-sdk-bins.cjs --clean",

package/reference/DEPRECATIONS.md

@@ -28,6 +28,20 @@ the scanner pattern list in lockstep.
 - **`scan`** (stage name) → merged/renamed into `explore` in Phase 3. Migration: references to the `scan` stage in shipped skills and agents were replaced with `explore`.
 - **`discover`** (stage name) → merged/renamed into `explore` in Phase 3. Migration: references to the `discover` stage in shipped skills and agents were replaced with `explore`.
 
+## Authoring surfaces
+
+- **`skills/` as the authoring source** → **`source/skills/`** — deprecated in Phase 42 (multi-harness
+  source compilation). Skills are now authored once in `source/skills/` with placeholders
+  (`{{command_prefix}}` et al.; see `reference/skill-placeholders.md`) and compiled per-harness by
+  `scripts/build-skills.cjs`. The committed `skills/` tree is now a **generated artifact** (the Claude-Code
+  compile target) — CI's `npm run build:skills:check` drift-gates `committed === generated`.
+
+  Migration for contributors: **edit `source/skills/`, never `skills/` directly**, then run
+  `npm run build:skills` (or `gdd-sdk build skills`) and commit the regenerated `skills/` +
+  `dist/claude-code/`. `.claude-plugin/plugin.json`'s `"skills": ["./skills/"]` is unchanged — the plugin
+  still loads `skills/`, now produced from `source/skills/`. This is a path/authoring move only; no
+  stale-ref token is emitted (both paths are live), so the `detect-stale-refs.cjs` list is not extended.
+
 ## Scanner scope
 
 `scripts/detect-stale-refs.cjs` flags these tokens (line-granular match):

package/reference/registry.json

@@ -1042,6 +1042,13 @@
       "type": "meta-rules",
       "phase": 40.5,
       "description": "Phase 40.5 CLI-localization contract: locale resolution (config.locale > env LANG > en) + fallback chain locale->base->en + flat-JSON message tables via scripts/lib/i18n/index.cjs; tables at scripts/lib/i18n/messages/{en,ru,uk,de,fr,zh,ja}.json (en source-complete, ru full, 5 placeholders with en fallback); the opt-in description_i18n frontmatter (descriptionFor falls back to English); /gdd:locale skill; warn-only completeness; the add-a-locale contribution path (translate table + NOTICE credit + PR). Distinct from reference/i18n.md (which covers USER-design i18n)."
+    },
+    {
+      "name": "skill-placeholders",
+      "path": "reference/skill-placeholders.md",
+      "type": "meta-rules",
+      "phase": 42,
+      "description": "Phase 42 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 source/skills/, compiled per-harness by scripts/build-skills.cjs via scripts/lib/build/factory.cjs reading scripts/lib/manifest/harnesses.json."
     }
   ]
 }

package/reference/skill-placeholders.md

@@ -0,0 +1,71 @@
+# Skill Placeholders — Multi-Harness Source Compilation
+
+> Phase 42. Skills are authored once in `source/skills/` 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
+> compile target is the committed `skills/` tree; CI asserts `committed === generated` (the drift gate).
+
+## The four placeholders
+
+| Placeholder           | Meaning                                              | Claude value (round-trip anchor) |
+|-----------------------|------------------------------------------------------|----------------------------------|
+| `{{command_prefix}}`  | The slash-command invocation prefix before a verb.   | `/gdd:` (so `{{command_prefix}}audit` -> `/gdd:audit`) |
+| `{{model}}`           | How the skill refers to the active model.            | `your configured Claude model`   |
+| `{{config_file}}`     | The harness's settings/config file path.             | `.claude/settings.json`          |
+| `{{ask_instruction}}` | How the skill tells the user to query the agent.     | `ask Claude Code`                |
+
+Only `{{command_prefix}}` is currently woven through the migrated source (every literal `/gdd:` became
+`{{command_prefix}}`); the other three are documented + factory-supported for authors who need them.
+Because Claude's `command_prefix` is exactly `/gdd:`, `compile(source, claude)` reproduces `skills/`
+byte-for-byte — that pure-inverse property is what makes the drift gate safe.
+
+## Per-harness substitution table
+
+| Harness id    | `{{command_prefix}}` | `{{config_file}}`           |
+|---------------|----------------------|-----------------------------|
+| `claude`      | `/gdd:`              | `.claude/settings.json`     |
+| `codex`       | `/gdd-`             | `.codex/config.toml`        |
+| `gemini`      | `/gdd:`              | `.gemini/settings.json`     |
+| `qwen`        | `/gdd:`              | `.qwen/settings.json`       |
+| `kilo`        | `/gdd:`              | `.kilo/config.json`         |
+| `copilot`     | `/gdd:`              | `.copilot/config.json`      |
+| `cursor`      | `/gdd:`              | `.cursor/settings.json`     |
+| `windsurf`    | `/gdd:`              | `.windsurf/settings.json`   |
+| `antigravity` | `/gdd:`              | `.antigravity/config.json`  |
+| `augment`     | `/gdd:`              | `.augment/config.json`      |
+| `trae`        | `/gdd:`              | `.trae/config.json`         |
+| `codebuddy`   | `/gdd:`              | `.codebuddy/config.json`    |
+| `cline`       | `/gdd:`              | `.cline/config.json`        |
+| `opencode`    | `/gdd:`              | `.opencode/config.json`     |
+
+`codex` is the deliberate outlier: its custom-prompt grammar is flat (`/gdd-audit`), not the namespaced
+`/gdd:audit`. `{{model}}` and `{{ask_instruction}}` follow the pattern `your configured <Name> model` and
+`ask <Name>` respectively (see `harness-configs.cjs` for exact strings). Adding a 15th harness is one new
+entry in `scripts/lib/manifest/harnesses.json` plus an optional row in `harness-configs.cjs`.
+
+## Escaping a literal placeholder
+
+To emit a literal `{{command_prefix}}` (or any `{{...}}`) without substitution, backslash-escape the
+opening braces: write `\{{command_prefix}}`. The factory strips the backslash and leaves the braces
+untouched. Use this only when documenting the placeholder syntax itself.
+
+## Harness-only blocks
+
+To include a span of content for specific harnesses only, wrap it in an HTML-comment fence (it survives
+Markdown and is easy to grep):
+
+```
+<!-- harness-only: cursor,codex -->
+This sentence ships only in the Cursor and Codex bundles.
+<!-- /harness-only -->
+```
+
+The block body is kept iff the compiling harness's `id` appears in the comma list; otherwise it is removed
+entirely. Full per-harness content forking beyond placeholders and these blocks is intentionally out of
+scope (a maintenance trap) — see the Phase 42 CONTEXT.
+
+## Validation
+
+`test/suite/phase-42-placeholders.test.cjs` asserts that every placeholder actually used across
+`source/skills/` is documented in this file, and that `source/skills/` mirrors the `skills/` skill count.

package/scripts/lib/build/factory.cjs

@@ -0,0 +1,62 @@
+'use strict';
+// Phase 42 — pure transformer factory (impeccable-style). compile(text, config) => string.
+// Pure: no filesystem, no I/O, no module imports. The orchestrator (scripts/build-skills.cjs)
+// does all reading/writing; this layer only transforms a single skill body for one harness config.
+//
+// Transform order (deterministic):
+//   1. harness-only blocks   <!-- harness-only: a,b -->BODY<!-- /harness-only --> kept iff config.id in {a,b}
+//   2. protect escapes       \{{ x }}  -> sentinel  (emit literal {{ x }}, never substituted)
+//   3. substitute            {{command_prefix}} {{model}} {{config_file}} {{ask_instruction}}
+//   4. restore escapes       sentinel -> {{ x }}
+//
+// D-01: for the Claude config (command_prefix === '/gdd:') this is the exact inverse of the migration
+// (/gdd: -> {{command_prefix}}), so compile(source, claude) reproduces skills/ byte-for-byte.
+
+const PLACEHOLDERS = ['command_prefix', 'model', 'config_file', 'ask_instruction'];
+const ESCAPE_OPEN = '@@GDD_ESC_';
+const ESCAPE_CLOSE = '@@';
+
+function stripHarnessOnly(text, id) {
+  const re = /<!--\s*harness-only:\s*([^>]*?)\s*-->([\s\S]*?)<!--\s*\/harness-only\s*-->/g;
+  return text.replace(re, (_m, list, body) => {
+    const ids = String(list).split(',').map((s) => s.trim()).filter(Boolean);
+    return ids.includes(id) ? body : '';
+  });
+}
+
+function compile(text, config) {
+  if (typeof text !== 'string') throw new TypeError('compile: text must be a string');
+  if (!config || typeof config !== 'object') throw new TypeError('compile: config object is required');
+
+  let out = stripHarnessOnly(text, config.id);
+
+  // 2. protect \{{ ... }} escapes
+  const escapes = [];
+  out = out.replace(/\\\{\{([\s\S]*?)\}\}/g, (_m, inner) => {
+    escapes.push('{{' + inner + '}}');
+    return ESCAPE_OPEN + (escapes.length - 1) + ESCAPE_CLOSE;
+  });
+
+  // 3. substitute placeholders
+  for (const key of PLACEHOLDERS) {
+    if (config[key] == null) continue;
+    out = out.split('{{' + key + '}}').join(String(config[key]));
+  }
+
+  // 4. restore escapes as literal {{ ... }}
+  out = out.replace(/@@GDD_ESC_(\d+)@@/g, (_m, i) => escapes[Number(i)]);
+  return out;
+}
+
+/** Placeholders genuinely substituted (escaped \{{...}} excluded) — used by the catalogue test. */
+function placeholdersUsed(text) {
+  if (typeof text !== 'string') return new Set();
+  const scrubbed = String(text).replace(/\\\{\{[\s\S]*?\}\}/g, '');
+  const used = new Set();
+  const re = /\{\{([a-z_]+)\}\}/g;
+  let m;
+  while ((m = re.exec(scrubbed)) !== null) used.add(m[1]);
+  return used;
+}
+
+module.exports = { compile, placeholdersUsed, stripHarnessOnly, PLACEHOLDERS };

package/scripts/lib/build/harness-configs.cjs

@@ -0,0 +1,64 @@
+'use strict';
+// Phase 42 — per-harness build/compile config. The base record (id / name / configDir) comes from the
+// Phase 41.5 manifest SoT (scripts/lib/manifest/harnesses.json); this layer adds the four placeholder
+// substitutions + frontmatter-strip rules + the dist bundle slug. Adding a 15th harness = one manifest
+// entry (+ an optional OVERRIDES row); everything else falls back to DEFAULTS.
+//
+// command_prefix is the ONLY field that affects the byte-identical Claude round-trip: it MUST be '/gdd:'
+// for claude (the migration replaced literal '/gdd:' with {{command_prefix}}; the Claude compile reverses it).
+
+const { readHarnesses } = require('../manifest/index.cjs');
+
+const DEFAULTS = {
+  command_prefix: '/gdd:',
+  config_file: 'config.json',
+  model: 'your configured model',
+  ask_instruction: 'ask your agent',
+  stripFrontmatter: [],
+};
+
+// Per-harness overrides. Only `codex` diverges on command_prefix (its custom-prompt grammar is flat,
+// `/gdd-audit`, not the namespaced `/gdd:audit`); the rest share Claude's slash-command namespace.
+const OVERRIDES = {
+  claude:      { bundleSlug: 'claude-code', command_prefix: '/gdd:', config_file: '.claude/settings.json',     model: 'your configured Claude model',      ask_instruction: 'ask Claude Code' },
+  codex:       { command_prefix: '/gdd-',  config_file: '.codex/config.toml',        model: 'your configured Codex model',       ask_instruction: 'ask Codex' },
+  gemini:      { command_prefix: '/gdd:',  config_file: '.gemini/settings.json',     model: 'your configured Gemini model',      ask_instruction: 'ask Gemini' },
+  qwen:        { command_prefix: '/gdd:',  config_file: '.qwen/settings.json',       model: 'your configured Qwen model',        ask_instruction: 'ask Qwen Code' },
+  kilo:        { command_prefix: '/gdd:',  config_file: '.kilo/config.json',         model: 'your configured Kilo model',        ask_instruction: 'ask Kilo Code' },
+  copilot:     { command_prefix: '/gdd:',  config_file: '.copilot/config.json',      model: 'your configured Copilot model',     ask_instruction: 'ask Copilot' },
+  cursor:      { command_prefix: '/gdd:',  config_file: '.cursor/settings.json',     model: 'your configured Cursor model',      ask_instruction: 'ask Cursor' },
+  windsurf:    { command_prefix: '/gdd:',  config_file: '.windsurf/settings.json',   model: 'your configured Windsurf model',    ask_instruction: 'ask Cascade' },
+  antigravity: { command_prefix: '/gdd:',  config_file: '.antigravity/config.json',  model: 'your configured Antigravity model', ask_instruction: 'ask Antigravity' },
+  augment:     { command_prefix: '/gdd:',  config_file: '.augment/config.json',      model: 'your configured Augment model',     ask_instruction: 'ask Augment' },
+  trae:        { command_prefix: '/gdd:',  config_file: '.trae/config.json',         model: 'your configured Trae model',        ask_instruction: 'ask Trae' },
+  codebuddy:   { command_prefix: '/gdd:',  config_file: '.codebuddy/config.json',    model: 'your configured CodeBuddy model',   ask_instruction: 'ask CodeBuddy' },
+  cline:       { command_prefix: '/gdd:',  config_file: '.cline/config.json',        model: 'your configured Cline model',       ask_instruction: 'ask Cline' },
+  opencode:    { command_prefix: '/gdd:',  config_file: '.opencode/config.json',     model: 'your configured OpenCode model',    ask_instruction: 'ask OpenCode' },
+};
+
+function buildConfigs(opts) {
+  const { harnesses } = readHarnesses(opts);
+  return harnesses.map((h) => {
+    const ov = OVERRIDES[h.id] || {};
+    return {
+      id: h.id,
+      name: h.name,
+      configDir: h.config_dir,
+      bundleSlug: ov.bundleSlug || h.id,
+      ...DEFAULTS,
+      ...ov,
+    };
+  });
+}
+
+const CONFIGS = buildConfigs();
+
+function byId(id) {
+  return CONFIGS.find((c) => c.id === id) || null;
+}
+
+function claude() {
+  return byId('claude');
+}
+
+module.exports = { CONFIGS, byId, claude, buildConfigs, DEFAULTS };

package/sdk/cli/commands/build.ts

@@ -0,0 +1,106 @@
+// sdk/cli/commands/build.ts — Phase 42 (COMPILE-06).
+//
+// `gdd-sdk build skills [--harness <id>] [--zip] [--check]` — compile the per-harness skill bundles
+// from source/skills/ via the orchestrator scripts/build-skills.cjs. The orchestrator is a separate
+// dep-free CJS process (no bundling entanglement with the SDK); we resolve it relative to the package
+// root and spawn it, forwarding stdout/stderr.
+//
+// Exit codes:
+//   * 0 — build (or --check) succeeded.
+//   * 1 — --check found drift (committed != generated).
+//   * 3 — arg / config error (missing/unknown target).
+
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+import {
+  coerceFlags,
+  COMMON_FLAGS,
+  type FlagSpec,
+  type ParsedArgs,
+} from '../parse-args.ts';
+
+const BUILD_FLAGS: readonly FlagSpec[] = [
+  ...COMMON_FLAGS,
+  { name: 'harness', type: 'string' },
+  { name: 'zip', type: 'boolean' },
+  { name: 'check', type: 'boolean' },
+];
+
+export const BUILD_USAGE = `gdd-sdk build skills [flags]
+
+Compile per-harness skill bundles from source/skills/ into dist/<bundle>/ (and regenerate the
+committed Claude-Code surface skills/). One source, N provider bundles.
+
+Flags:
+  --harness <id>   Build only one harness (e.g. claude, codex, gemini). Default: all 14.
+  --zip            Also package each bundle as dist/<bundle>.tgz (needs tar).
+  --check          Verify committed skills/ + dist/claude-code/ match source/ (the drift gate); no writes.
+  -h, --help       Show this help.
+
+Exit codes: 0 ok · 1 drift (--check) · 3 arg error
+`;
+
+interface CommandCtx {
+  readonly stdout: NodeJS.WritableStream;
+  readonly stderr: NodeJS.WritableStream;
+}
+
+/** Walk up from the CLI entry (argv[1]) to the package root that holds scripts/build-skills.cjs. */
+function findOrchestrator(): string | null {
+  let dir = dirname(process.argv[1] ?? process.cwd());
+  for (let i = 0; i < 8; i++) {
+    const candidate = join(dir, 'scripts', 'build-skills.cjs');
+    if (existsSync(candidate)) return candidate;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  const cwdCandidate = join(process.cwd(), 'scripts', 'build-skills.cjs');
+  return existsSync(cwdCandidate) ? cwdCandidate : null;
+}
+
+export async function buildCommand(parsed: ParsedArgs, ctx: CommandCtx): Promise<number> {
+  if (parsed.flags['help'] === true || parsed.flags['h'] === true) {
+    ctx.stdout.write(BUILD_USAGE);
+    return 0;
+  }
+
+  const target = parsed.positionals[0];
+  if (target !== 'skills') {
+    ctx.stderr.write(`gdd-sdk build: expected target "skills" (got ${target ? `"${target}"` : 'nothing'})\n${BUILD_USAGE}`);
+    return 3;
+  }
+
+  let flags: Record<string, unknown>;
+  try {
+    flags = coerceFlags(parsed, BUILD_FLAGS);
+  } catch {
+    ctx.stderr.write(`gdd-sdk build: invalid flags\n${BUILD_USAGE}`);
+    return 3;
+  }
+
+  const script = findOrchestrator();
+  if (!script) {
+    ctx.stderr.write('gdd-sdk build: could not locate scripts/build-skills.cjs\n');
+    return 3;
+  }
+
+  const orchestratorArgs: string[] = [];
+  if (flags['check'] === true) orchestratorArgs.push('--check');
+  if (flags['zip'] === true) orchestratorArgs.push('--zip');
+  const harness = flags['harness'];
+  if (typeof harness === 'string' && harness.length > 0) {
+    orchestratorArgs.push('--harness', harness);
+  }
+
+  const res = spawnSync(process.execPath, [script, ...orchestratorArgs], { encoding: 'utf8' });
+  if (res.stdout) ctx.stdout.write(res.stdout);
+  if (res.stderr) ctx.stderr.write(res.stderr);
+  if (res.error) {
+    ctx.stderr.write(`gdd-sdk build: failed to run orchestrator: ${res.error.message}\n`);
+    return 3;
+  }
+  return typeof res.status === 'number' ? res.status : 3;
+}

package/sdk/cli/index.js

@@ -8004,6 +8004,83 @@ function errMessage5(err) {
   return String(err);
 }
 
+// sdk/cli/commands/build.ts
+var import_node_child_process = require("node:child_process");
+var import_node_fs22 = require("node:fs");
+var import_node_path20 = require("node:path");
+var BUILD_FLAGS = [
+  ...COMMON_FLAGS,
+  { name: "harness", type: "string" },
+  { name: "zip", type: "boolean" },
+  { name: "check", type: "boolean" }
+];
+var BUILD_USAGE = `gdd-sdk build skills [flags]
+
+Compile per-harness skill bundles from source/skills/ into dist/<bundle>/ (and regenerate the
+committed Claude-Code surface skills/). One source, N provider bundles.
+
+Flags:
+  --harness <id>   Build only one harness (e.g. claude, codex, gemini). Default: all 14.
+  --zip            Also package each bundle as dist/<bundle>.tgz (needs tar).
+  --check          Verify committed skills/ + dist/claude-code/ match source/ (the drift gate); no writes.
+  -h, --help       Show this help.
+
+Exit codes: 0 ok \xB7 1 drift (--check) \xB7 3 arg error
+`;
+function findOrchestrator() {
+  let dir = (0, import_node_path20.dirname)(process.argv[1] ?? process.cwd());
+  for (let i = 0; i < 8; i++) {
+    const candidate = (0, import_node_path20.join)(dir, "scripts", "build-skills.cjs");
+    if ((0, import_node_fs22.existsSync)(candidate)) return candidate;
+    const parent = (0, import_node_path20.dirname)(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  const cwdCandidate = (0, import_node_path20.join)(process.cwd(), "scripts", "build-skills.cjs");
+  return (0, import_node_fs22.existsSync)(cwdCandidate) ? cwdCandidate : null;
+}
+async function buildCommand(parsed, ctx) {
+  if (parsed.flags["help"] === true || parsed.flags["h"] === true) {
+    ctx.stdout.write(BUILD_USAGE);
+    return 0;
+  }
+  const target = parsed.positionals[0];
+  if (target !== "skills") {
+    ctx.stderr.write(`gdd-sdk build: expected target "skills" (got ${target ? `"${target}"` : "nothing"})
+${BUILD_USAGE}`);
+    return 3;
+  }
+  let flags;
+  try {
+    flags = coerceFlags(parsed, BUILD_FLAGS);
+  } catch {
+    ctx.stderr.write(`gdd-sdk build: invalid flags
+${BUILD_USAGE}`);
+    return 3;
+  }
+  const script = findOrchestrator();
+  if (!script) {
+    ctx.stderr.write("gdd-sdk build: could not locate scripts/build-skills.cjs\n");
+    return 3;
+  }
+  const orchestratorArgs = [];
+  if (flags["check"] === true) orchestratorArgs.push("--check");
+  if (flags["zip"] === true) orchestratorArgs.push("--zip");
+  const harness = flags["harness"];
+  if (typeof harness === "string" && harness.length > 0) {
+    orchestratorArgs.push("--harness", harness);
+  }
+  const res = (0, import_node_child_process.spawnSync)(process.execPath, [script, ...orchestratorArgs], { encoding: "utf8" });
+  if (res.stdout) ctx.stdout.write(res.stdout);
+  if (res.stderr) ctx.stderr.write(res.stderr);
+  if (res.error) {
+    ctx.stderr.write(`gdd-sdk build: failed to run orchestrator: ${res.error.message}
+`);
+    return 3;
+  }
+  return typeof res.status === "number" ? res.status : 3;
+}
+
 // sdk/cli/index.ts
 var USAGE6 = `gdd-sdk <command> [flags]
 
@@ -8013,6 +8090,7 @@ Commands:
   query <op>       Typed STATE.md read operations.
   audit            Probe connections + dry-run verify.
   init             Bootstrap a new project.
+  build skills     Compile per-harness skill bundles from source/skills/.
 
 Use 'gdd-sdk <command> -h' for command-specific flags.
 
@@ -8030,7 +8108,8 @@ async function dispatch(parsed, deps = {}) {
     stage: deps.commands?.stage ?? stageCommand,
     query: deps.commands?.query ?? queryCommand,
     audit: deps.commands?.audit ?? auditCommand,
-    init: deps.commands?.init ?? initCommand
+    init: deps.commands?.init ?? initCommand,
+    build: deps.commands?.build ?? buildCommand
   };
   if (parsed.subcommand === null) {
     stdout.write(USAGE6);
@@ -8054,6 +8133,8 @@ async function dispatch(parsed, deps = {}) {
       return await commands.audit(parsed, { stdout, stderr });
     case "init":
       return await commands.init(parsed, { stdout, stderr });
+    case "build":
+      return await commands.build(parsed, { stdout, stderr });
     default:
       stderr.write(
         `gdd-sdk: unknown subcommand "${parsed.subcommand}"
@@ -8067,7 +8148,8 @@ var KNOWN_SUBCOMMANDS = /* @__PURE__ */ new Set([
   "stage",
   "query",
   "audit",
-  "init"
+  "init",
+  "build"
 ]);
 async function main(argv = process.argv.slice(2), deps = {}) {
   const parsed = parseArgs(argv);

package/sdk/cli/index.ts

@@ -21,6 +21,7 @@ import { stageCommand } from './commands/stage.ts';
 import { queryCommand } from './commands/query.ts';
 import { auditCommand } from './commands/audit.ts';
 import { initCommand } from './commands/init.ts';
+import { buildCommand } from './commands/build.ts';
 
 // ---------------------------------------------------------------------------
 // Top-level USAGE.
@@ -34,6 +35,7 @@ Commands:
   query <op>       Typed STATE.md read operations.
   audit            Probe connections + dry-run verify.
   init             Bootstrap a new project.
+  build skills     Compile per-harness skill bundles from source/skills/.
 
 Use 'gdd-sdk <command> -h' for command-specific flags.
 
@@ -57,6 +59,7 @@ export interface DispatcherDeps {
     readonly query?: typeof queryCommand;
     readonly audit?: typeof auditCommand;
     readonly init?: typeof initCommand;
+    readonly build?: typeof buildCommand;
   };
 }
 
@@ -81,6 +84,7 @@ export async function dispatch(
     query: deps.commands?.query ?? queryCommand,
     audit: deps.commands?.audit ?? auditCommand,
     init: deps.commands?.init ?? initCommand,
+    build: deps.commands?.build ?? buildCommand,
   };
 
   // Bare invocation or top-level help → USAGE.
@@ -111,6 +115,8 @@ export async function dispatch(
       return await commands.audit(parsed, { stdout, stderr });
     case 'init':
       return await commands.init(parsed, { stdout, stderr });
+    case 'build':
+      return await commands.build(parsed, { stdout, stderr });
     default:
       stderr.write(
         `gdd-sdk: unknown subcommand "${parsed.subcommand}"\n${USAGE}`,
@@ -125,6 +131,7 @@ const KNOWN_SUBCOMMANDS: ReadonlySet<string> = new Set([
   'query',
   'audit',
   'init',
+  'build',
 ]);
 
 // ---------------------------------------------------------------------------