@hegemonart/get-design-done 1.57.3 → 1.58.1

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Get Design Done — 5-stage agent-orchestrated design pipeline (Brief → Explore → Plan → Design → Verify) for AI coding agents. 61 agents, 94 skills, 42 connection integrations, two MCP servers, opt-in SQLite state backbone, bidirectional Figma write-back, and a reflector-driven self-improvement loop. Cross-runtime install for Claude Code, Codex, Cursor, OpenCode, Gemini, and more.",
-    "version": "1.57.3"
+    "version": "1.58.1"
   },
   "plugins": [
     {
       "name": "get-design-done",
       "source": "./",
       "description": "Agent-orchestrated 5-stage design pipeline (Brief → Explore → Plan → Design → Verify) for AI coding agents. 61 specialized agents, 94 skills, 42 connection integrations (Figma, Refero, Preview, Storybook, Chromatic, Graphify, Linear, Jira, Notion, …), bidirectional Figma write-back, queryable intel store, opt-in SQLite state backbone, and a reflector-driven self-improvement loop. Two MCP servers (gdd-state for typed STATE mutators, gdd-mcp for 13 read-only project-priming tools), tier-aware routing with cost telemetry, and defense-in-depth hooks (protected paths, MCP circuit breaker, injection scanner, budget enforcer). Cross-runtime install for Claude Code, Codex, Cursor, OpenCode, Gemini, Copilot, and more.",
-      "version": "1.57.3",
+      "version": "1.58.1",
       "author": {
         "name": "hegemonart"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.57.3",
+  "version": "1.58.1",
   "description": "Agent-orchestrated 5-stage design pipeline (Brief → Explore → Plan → Design → Verify) for AI coding agents. 61 specialized agents, 94 skills, 42 connection integrations (Figma, Refero, Preview, Storybook, Chromatic, Graphify, Linear, Jira, Notion, …), bidirectional Figma write-back, queryable intel store for O(1) design-surface lookups, opt-in SQLite state backbone, and a reflector-driven self-improvement loop. Two MCP servers (`gdd-state` for typed STATE mutators, `gdd-mcp` for 13 read-only project-priming tools), tier-aware agent routing with cost telemetry, defense-in-depth hooks (protected paths, MCP circuit breaker, injection scanner, budget enforcer), and a cross-runtime install layer for Claude Code, Codex, Cursor, OpenCode, Gemini, Copilot, and more.",
   "author": {
     "name": "hegemonart",

package/CHANGELOG.md

@@ -4,6 +4,78 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.58.1] - 2026-06-04
+
+### Hotfix - restore committed skills/ for Claude Code marketplace install
+
+v1.58.0 gitignored `skills/` on the premise that it was a pure build artifact that the `prepare` lifecycle could regenerate on `npm install`. That assumption held for the npm install path (registry tarball already contains pre-built `skills/`) and for dev clones (`npm install` runs `prepare`), but **broke the Claude Code marketplace install path**: Claude Code installs plugins by git-cloning the source repo without running `npm install`, so post-clone `./skills/` was absent and the plugin failed to load any skill.
+
+v1.58.1 reverts the gitignore. `skills/` is committed again as a build artifact. The CI drift gate goes back to enforcing `committed skills/ == compile(skill-templates/)`. End users now get a working plugin via either install path (Claude Code marketplace OR `npm install`).
+
+### What stays from v1.58.0 (the architectural wins persist)
+
+- `skill-templates/` is the canonical editable source (no more `source/` wrapper).
+- `prepare` lifecycle runs `npm run build:skills` on `npm install` so contributor checkouts stay in sync after edits to `skill-templates/`.
+- `prepack` lifecycle chains `build:sdk && build:skills` so the npm tarball still ships a freshly-built `skills/`.
+
+### What changed back from v1.58.0
+
+- **`.gitignore`** no longer excludes `skills/`. 116 files re-tracked.
+- **`scripts/build-skills.cjs --check`** is back to the original Phase 42 drift-gate semantics ("committed === generated"), instead of the v1.58.0 determinism gate.
+- **`regression-baseline.test.cjs`** reads the skill-list from `skills/` again (was `skill-templates/` in v1.58.0).
+- **CI yml** label restored to "Skill build drift gate".
+
+### Migration
+
+No action needed. Contributors continue to edit `skill-templates/<slug>/SKILL.md` and run `npm run build:skills` (or just `npm install`) to regenerate the committed `skills/`. End users see no change.
+
+5,007/5,007 tests pass.
+
+### Breaking changes
+
+None.
+
+---
+
+## [1.58.0] - 2026-06-04
+
+### Architectural cleanup - kill the skills/ <-> source/skills/ duplication
+
+Previous layout (Phase 42) committed BOTH the editable templates (`source/skills/`) AND the rendered Claude Code surface (`skills/`) - 232 tracked files for 116 distinct skills, identical content modulo a single `{{command_prefix}}` placeholder substitution. Pure git churn.
+
+v1.58.0 makes `skill-templates/` (renamed from `source/skills/`; the gratuitous `source/` wrapper held only `skills/` and is gone) the single source of truth. `skills/` is gitignored and regenerated on demand. **End-user install experience is unchanged** - the npm tarball still ships `skills/` pre-built at the root; no build step runs on consumer machines.
+
+5,007/5,007 tests pass.
+
+### Breaking changes
+
+- **For contributors only:** the editable skill source path moved from `source/skills/<slug>/SKILL.md` to `skill-templates/<slug>/SKILL.md`. Forks with in-flight edits under `source/skills/` should `git mv` their changes to `skill-templates/`. No runtime contract changes; no API changes; end users installing from npm see no behavior difference.
+
+### Changed
+
+- **`source/skills/` -> `skill-templates/`** (renamed). The `source/` wrapper held only `skills/` inside and added nothing semantically. The new name is self-documenting.
+- **`skills/` is now gitignored.** Regenerated automatically by two npm lifecycle hooks:
+  - `prepare` (runs on `npm install` from a fresh git clone, and again on `npm publish`) -> dev clones work immediately, no extra steps.
+  - `prepack` (chains `build:sdk` -> `build:skills`) -> the published tarball always contains a freshly-built `skills/`.
+- **`build:skills:check` semantics flip** from "committed `skills/` matches source compile" to "compile is deterministic + on-disk `skills/` matches `skill-templates/`". Still catches manual edits to the build dir; no longer gates against a committed copy that doesn't need to exist.
+- **`scripts/build-skills.cjs` writes progress to stderr** (was stdout). Required for `npm pack --json` to produce parseable JSON when `prepack` runs first.
+
+### Migration for contributors
+
+Anyone editing skill content must now point at `skill-templates/<slug>/SKILL.md` instead of `source/skills/<slug>/SKILL.md`. After edits, `npm run build:skills` regenerates the local `skills/` (or just run `npm install`, which fires `prepare`). The CI `build:skills:check` gate catches any regression. End users running `npm install @hegemonart/get-design-done` see no change - the tarball contents are byte-identical to v1.57.3 for the same skill bodies.
+
+### Internal refactor scope
+
+- ~40 test + script + reference files updated: `source/skills/` -> `skill-templates/`.
+- `package.json#scripts` added `"prepare": "node scripts/build-skills.cjs"` + chained `prepack`.
+- `.gitignore` adds `skills/`.
+- `internal-refs.json` rebaselined (1749 -> 1682 hits; cleaner after removing duplicate path entries).
+- `STYLE.md` regenerated.
+- `reference/DEPRECATIONS.md` documents both the Phase 42 migration (`skills/` -> `source/skills/`) and the v1.58.0 follow-up (`source/skills/` -> `skill-templates/` + ungitignore).
+- `skill-templates/README.md` rewritten as the single canonical source-of-truth doc.
+
+---
+
 ## [1.57.3] - 2026-06-04
 
 ### Polish residuals - closes remaining POLISH-PLAN items + dist/ deduplication

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/**, source/skills/**), spawn a
+ * (skills/**, agents/**, reference/**, 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|source/skills)/.*\.(md|json)$
+ *        ^(skills|agents|reference|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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.57.3",
+  "version": "1.58.1",
   "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",
@@ -55,7 +55,8 @@
     "generate:skill-frontmatter": "node scripts/generate-skill-frontmatter.cjs",
     "generate:skill-frontmatter:check": "node scripts/generate-skill-frontmatter.cjs --check",
     "build:sdk": "node scripts/build-sdk-bins.cjs",
-    "prepack": "npm run build:sdk",
+    "prepare": "node scripts/build-skills.cjs",
+    "prepack": "npm run build:sdk && npm run build:skills",
     "postpack": "node scripts/build-sdk-bins.cjs --clean",
     "test": "node --test --experimental-strip-types \"test/suite/**/*.test.cjs\" \"test/suite/**/*.test.ts\"",
     "test:behavior": "node scripts/run-behavior-tests.cjs",

package/reference/DEPRECATIONS.md

@@ -30,17 +30,24 @@ the scanner pattern list in lockstep.
 
 ## 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.
+- **`skills/` as the authoring source** → **`source/skills/`** (Phase 42, deprecated)
+  → **`skill-templates/`** (v1.58.0, current). Two-step 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
+    rendered `skills/` was kept committed as a "generated-but-tracked artifact". A drift gate
+    (`npm run build:skills:check`) verified `committed === generated`.
+  - **v1.58.0** removed the committed render. `source/skills/` was renamed to `skill-templates/`
+    (the `source/` wrapper held only `skills/` and added nothing), and `skills/` is now
+    gitignored - regenerated by the `prepare` lifecycle on `npm install` and packed into the
+    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,
+  `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
+  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 (`source/skills/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 (`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 source/skills/, 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 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 `source/skills/<id>/SKILL.md`, the build step compiles
+generator projects it onto every `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
-`source/skills/<id>/` directory name); every other field is optional and omitted when it
+`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)
-  -> source/skills/<id>/SKILL.md
+  -> 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 `source/skills/` into the committed `skills/`
+`scripts/build-skills.cjs` then propagates `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 `source/skills/` with placeholders and compiled per-harness into
+> Phase 42. Skills are authored once in `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
-`source/skills/` is documented in this file, and that `source/skills/` mirrors the `skills/` skill count.
+`skill-templates/` is documented in this file, and that `skill-templates/` mirrors the `skills/` skill count.

package/scripts/lib/manifest/scaffolder.cjs

@@ -3,7 +3,7 @@
  * scripts/lib/manifest/scaffolder.cjs — Phase 50 (Authoring Contract v3).
  *
  * Pure, dependency-free generator behind the `/gdd:new-skill` scaffolder skill.
- * The SKILL.md (source/skills/new-skill/SKILL.md) drives the interactive
+ * The SKILL.md (skill-templates/new-skill/SKILL.md) drives the interactive
  * prompts; this module is the deterministic core it (and the test suite) call.
  *
  * Exports:

package/scripts/lib/manifest/schemas/skills.schema.json

@@ -25,7 +25,7 @@
           "name": {
             "type": "string",
             "minLength": 1,
-            "description": "Skill id = source/skills/<name>/ directory name."
+            "description": "Skill id = skill-templates/<name>/ directory name."
           },
           "frontmatter_name": {
             "type": "string",

package/scripts/lib/manifest/skills.json

@@ -312,7 +312,7 @@
     },
     {
       "name": "new-skill",
-      "description": "Scaffolds a new Phase-28.5 + Phase-50-compliant skill: gathers a name, a multi-paragraph v3 description, a lifecycle stage, an allowed-tools list, and optional composes_with neighbours, then writes source/skills/<name>/SKILL.md from the pure generator. Use when adding a brand-new gdd skill and you want the frontmatter, length cap, and v3 description form correct from the first commit. Activates for requests involving authoring a skill, scaffolding a command, creating a new SKILL.md, or adding a slash command.",
+      "description": "Scaffolds a new Phase-28.5 + Phase-50-compliant skill: gathers a name, a multi-paragraph v3 description, a lifecycle stage, an allowed-tools list, and optional composes_with neighbours, then writes skill-templates/<name>/SKILL.md from the pure generator. Use when adding a brand-new gdd skill and you want the frontmatter, length cap, and v3 description form correct from the first commit. Activates for requests involving authoring a skill, scaffolding a command, creating a new SKILL.md, or adding a slash command.",
       "argument_hint": "<skill-name>",
       "tools": "Read, Write, Bash, AskUserQuestion",
       "user_invocable": true,

package/scripts/lib/new-addendum.cjs

@@ -3,7 +3,7 @@
  * scripts/lib/new-addendum.cjs — Phase 54 (Composable Reference Addendums), REG-01.
  *
  * Pure, dependency-free generator behind the `/gdd:new-addendum <kind> <name>`
- * scaffolder skill (source/skills/new-addendum/SKILL.md). The SKILL.md drives
+ * scaffolder skill (skill-templates/new-addendum/SKILL.md). The SKILL.md drives
  * the prompts; this module is the deterministic core it (and the test suite)
  * call. Mirrors scripts/lib/manifest/scaffolder.cjs (the Phase 50 skill
  * scaffolder): same ReDoS-safe NAME_RE, same throw-on-invalid contract, same

package/sdk/cli/commands/build.ts

@@ -1,7 +1,7 @@
 // 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
+// from skill-templates/ 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.
 //
@@ -30,7 +30,7 @@ const BUILD_FLAGS: readonly FlagSpec[] = [
 
 export const BUILD_USAGE = `gdd-sdk build skills [flags]
 
-Compile per-harness skill bundles from source/skills/ into dist/<bundle>/ (and regenerate the
+Compile per-harness skill bundles from skill-templates/ into dist/<bundle>/ (and regenerate the
 committed Claude-Code surface skills/). One source, N provider bundles.
 
 Flags:

package/sdk/cli/index.js

@@ -9634,7 +9634,7 @@ var BUILD_FLAGS = [
 ];
 var BUILD_USAGE = `gdd-sdk build skills [flags]
 
-Compile per-harness skill bundles from source/skills/ into dist/<bundle>/ (and regenerate the
+Compile per-harness skill bundles from skill-templates/ into dist/<bundle>/ (and regenerate the
 committed Claude-Code surface skills/). One source, N provider bundles.
 
 Flags:
@@ -9954,7 +9954,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/.
+  build skills     Compile per-harness skill bundles from skill-templates/.
   dashboard        Open the GDD dashboard (TUI; --web for the browser graph).
 
 Use 'gdd-sdk <command> -h' for command-specific flags.

package/sdk/cli/index.ts

@@ -36,7 +36,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/.
+  build skills     Compile per-harness skill bundles from skill-templates/.
   dashboard        Open the GDD dashboard (TUI; --web for the browser graph).
 
 Use 'gdd-sdk <command> -h' for command-specific flags.

package/skills/README.md

@@ -1,41 +1,76 @@
-# `source/skills/` - Canonical Skill BODY Source
+# `skill-templates/` - Editable Skill Source (Single Source of Truth)
 
-This directory is the **canonical home for skill body content**. Every `SKILL.md` under
-`source/skills/<slug>/` is the editable truth: the per-skill prose, examples, procedure files,
-and any sibling docs (`*-procedure.md`, `*-rules.md`, emitters, etc.) live here.
+This directory is the **only** place to edit skill content. Every `SKILL.md` and sibling
+doc here is the editable truth - the per-skill prose, examples, procedure files
+(`*-procedure.md`, `*-rules.md`, emitters, etc.) all live here.
 
-`skills/` (the sibling at the repo root) is a **built artifact**, regenerated from this directory
-by `npm run build:skills`. Do not hand-edit `skills/<slug>/SKILL.md` - your edit will be wiped on
-the next build and the CI drift gate (`build:skills:check`) will fail.
+The user-facing `skills/` directory at the repo root is a **build artifact**, not source.
+It's gitignored and regenerated automatically:
+
+- on `npm install` (via the `prepare` lifecycle script) - so developer clones work immediately
+- on `npm pack` / `npm publish` (via `prepack`) - so the published tarball ships pre-built skills
+
+End users installing `@hegemonart/get-design-done` from the npm registry receive a tarball
+with `skills/` already built; no build step runs on their machine.
+
+## Why two directories, not one
+
+Claude Code reads `./skills/<slug>/SKILL.md` raw. If we kept `/gdd:` placeholders
+in the file Claude reads, the literal text `/gdd:` would show up in the prompt.
+So the editable templates need to live separately from the rendered output.
+
+The previous layout (Phase 42) put templates under `source/skills/` AND committed the
+rendered `skills/` alongside. That meant 232 tracked files for 116 distinct skills with
+identical content modulo a single placeholder substitution. Pure git churn.
+
+v1.58.0 fixes this: templates are tracked once at `skill-templates/`, the rendered output
+is generated on demand.
 
 ## Source-of-truth split (what lives where)
 
 | Concern | Source of truth | How it reaches `skills/` |
 |---|---|---|
-| **Body content** (everything below the frontmatter) | `source/skills/<slug>/SKILL.md` | `scripts/build-skills.cjs` walks `source/skills/`, applies per-harness placeholder substitution, writes to `skills/` |
-| **Universal frontmatter** (`name`, `description`, `argument-hint`, `tools`, `user-invocable`, `disable-model-invocation`) | `scripts/lib/manifest/skills.json` | `scripts/generate-skill-frontmatter.cjs` writes the managed block into `source/skills/<slug>/SKILL.md`, then `build:skills` copies it onward |
-| **Non-managed frontmatter** (e.g. `color`, `model`, custom keys) | `source/skills/<slug>/SKILL.md` itself (preserved verbatim) | carried through both generators unchanged |
+| **Body content** (everything below the frontmatter) | `skill-templates/<slug>/SKILL.md` | `scripts/build-skills.cjs` walks `skill-templates/`, applies per-harness placeholder substitution, writes to `skills/` |
+| **Universal frontmatter** (`name`, `description`, `argument-hint`, `tools`, `user-invocable`, `disable-model-invocation`) | `scripts/lib/manifest/skills.json` | `scripts/generate-skill-frontmatter.cjs` writes the managed block into `skill-templates/<slug>/SKILL.md`, then `build:skills` copies it onward |
+| **Non-managed frontmatter** (e.g. `color`, `model`, custom keys) | `skill-templates/<slug>/SKILL.md` itself (preserved verbatim) | carried through both generators unchanged |
 
-The forward direction is **`skills.json` -> `source/skills/` -> `skills/`**.
+The forward direction is **`skills.json` -> `skill-templates/` -> `skills/`**.
 Treat that direction as canonical; the `--extract` mode of `generate-skill-frontmatter.cjs` exists
 only to seed the manifest from current sources when reconciling drift.
 
 ## Editing protocol
 
-1. **Edit body** -> modify `source/skills/<slug>/SKILL.md` (anything below the frontmatter delimiter).
+1. **Edit body** -> modify `skill-templates/<slug>/SKILL.md` (anything below the frontmatter delimiter).
 2. **Edit universal frontmatter** -> modify `scripts/lib/manifest/skills.json`, then run
    `npm run generate:skill-frontmatter`.
-3. **Edit non-managed frontmatter** -> modify `source/skills/<slug>/SKILL.md` directly; the generator
+3. **Edit non-managed frontmatter** -> modify `skill-templates/<slug>/SKILL.md` directly; the generator
    preserves it.
-4. **Regenerate the built surface** -> `npm run build:skills`. This rewrites `skills/<slug>/SKILL.md`
-   byte-for-byte.
-5. **Verify no drift** -> `npm run build:skills:check` (CI gate) and `npm run generate:skill-frontmatter:check`.
+4. **Regenerate the built surface** -> `npm run build:skills`. This rewrites the gitignored
+   `skills/<slug>/SKILL.md` byte-for-byte from the templates.
+5. **Verify the build** -> `npm run build:skills:check` (CI gate) confirms compile determinism
+   and that the on-disk `skills/` matches what `skill-templates/` would generate.
+
+## Placeholders
+
+Four substitution slots are supported by `scripts/lib/build/factory.cjs`:
+
+- `/gdd:` - slash-command prefix (`/gdd:` for Claude, `/gdd-` for Codex, etc.)
+- `your configured Claude model` - human-readable model phrase ("your configured Claude model", etc.)
+- `.claude/settings.json` - per-harness config path (`.claude/settings.json`, `.codex/config.toml`, ...)
+- `ask Claude Code` - "ask Claude Code", "ask Codex", etc.
+
+Plus conditional blocks: `BODY` keeps
+`BODY` only when the active harness id is in the listed set.
+
+Escape with `{{ ... }}` to emit a literal `{{...}}` in the output (never substituted).
+
+Full grammar + the per-harness substitution table: `reference/skill-placeholders.md`.
 
 ## What npm ships
 
-`package.json` `files` lists `skills/` (the built surface); `source/skills/` is repo-only and is
-**not** distributed via npm. Users running `npm install @hegemonart/get-design-done` get the
-compiled skills; only contributors editing this repo touch `source/skills/`.
+`package.json` `files` lists `skills/` (the built surface); `skill-templates/` is repo-only and
+is **not** distributed via npm. The `prepack` lifecycle runs `npm run build:skills` so the tarball
+always contains a freshly-built `skills/`.
 
 ## Cross-references
 
@@ -44,3 +79,4 @@ compiled skills; only contributors editing this repo touch `source/skills/`.
 - `scripts/lib/manifest/README.md` - explains why `skills.json` is the universal-frontmatter SoT.
 - `scripts/generate-skill-frontmatter.cjs` - manifest -> source-frontmatter generator (with
   `--check` drift gate and `--extract` reverse mode).
+- `reference/skill-placeholders.md` - placeholder grammar + per-harness substitution table.

package/skills/new-skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-new-skill
-description: "Scaffolds a new Phase-28.5 + Phase-50-compliant skill: gathers a name, a multi-paragraph v3 description, a lifecycle stage, an allowed-tools list, and optional composes_with neighbours, then writes source/skills/<name>/SKILL.md from the pure generator. Use when adding a brand-new gdd skill and you want the frontmatter, length cap, and v3 description form correct from the first commit. Activates for requests involving authoring a skill, scaffolding a command, creating a new SKILL.md, or adding a slash command."
+description: "Scaffolds a new Phase-28.5 + Phase-50-compliant skill: gathers a name, a multi-paragraph v3 description, a lifecycle stage, an allowed-tools list, and optional composes_with neighbours, then writes skill-templates/<name>/SKILL.md from the pure generator. Use when adding a brand-new gdd skill and you want the frontmatter, length cap, and v3 description form correct from the first commit. Activates for requests involving authoring a skill, scaffolding a command, creating a new SKILL.md, or adding a slash command."
 argument-hint: "<skill-name>"
 tools: Read, Write, Bash, AskUserQuestion
 user-invocable: true
@@ -8,7 +8,7 @@ user-invocable: true
 
 # /gdd:new-skill
 
-**Role:** Interactively scaffold a contract-compliant skill. Gather the fields, then write `source/skills/<name>/SKILL.md` from the pure generator at `scripts/lib/manifest/scaffolder.cjs`. This skill writes ONE source file. It does NOT touch `scripts/lib/manifest/skills.json` and does NOT run the build; it prints the exact follow-up commands instead.
+**Role:** Interactively scaffold a contract-compliant skill. Gather the fields, then write `skill-templates/<name>/SKILL.md` from the pure generator at `scripts/lib/manifest/scaffolder.cjs`. This skill writes ONE source file. It does NOT touch `scripts/lib/manifest/skills.json` and does NOT run the build; it prints the exact follow-up commands instead.
 
 Read `reference/skill-authoring-contract.md` first for the length cap, the frontmatter required fields, and the v3 description form.
 
@@ -27,7 +27,7 @@ Either way the answers feed the same record builder. Never block waiting on a TT
 
 ## Step 1 - Gather the fields
 
-1. **name**: the slug from `$ARGUMENTS` if present, else ask. Must match `^[a-z0-9][a-z0-9-._]*$`. Reject `source/skills/<name>/` collisions.
+1. **name**: the slug from `$ARGUMENTS` if present, else ask. Must match `^[a-z0-9][a-z0-9-._]*$`. Reject `skill-templates/<name>/` collisions.
 2. **description**: a multi-paragraph v3 form. Sentence one is what the skill does. Sentence two is `Use when <triggers>`. Sentence three is `Activates for requests involving <kw1>, <kw2>, <kw3>.` Keep it 20 to 1024 chars.
 3. **lifecycle stage**: pick one of brief / explore / plan / verify / ship / figma / token / report (free text allowed). This seeds the composition suggestions.
 4. **tools**: a comma list (for example `Read, Write, Bash`). Empty means inherit-all.
@@ -45,7 +45,7 @@ Present the suggestions; let the user accept, edit, or clear them.
 
 ## Step 2 - Length pre-check
 
-Before writing, estimate the body length. If the planned body would exceed about 100 lines, warn the user (the authoring contract warns at 100 and blocks at 250) and suggest extracting domain content into a co-located `source/skills/<name>/<topic>.md` reference. The generated skeleton is small; the warning is for the prose the user will add next.
+Before writing, estimate the body length. If the planned body would exceed about 100 lines, warn the user (the authoring contract warns at 100 and blocks at 250) and suggest extracting domain content into a co-located `skill-templates/<name>/<topic>.md` reference. The generated skeleton is small; the warning is for the prose the user will add next.
 
 ## Step 3 - Write the file
 
@@ -66,7 +66,7 @@ process.stdout.write(s.renderSkillMd(rec));
 "
 ```
 
-`buildSkillRecord` throws on an invalid name, an out-of-budget description, or a malformed tools list. Surface the thrown message to the user and re-prompt the offending field. Capture stdout and write it verbatim to `source/skills/<name>/SKILL.md` via the Write tool.
+`buildSkillRecord` throws on an invalid name, an out-of-budget description, or a malformed tools list. Surface the thrown message to the user and re-prompt the offending field. Capture stdout and write it verbatim to `skill-templates/<name>/SKILL.md` via the Write tool.
 
 ## Step 4 - Tell the user the follow-up