@hegemonart/get-design-done 1.57.2 → 1.58.0

package/.claude-plugin/marketplace.json

@@ -4,15 +4,15 @@
     "name": "hegemonart"
   },
   "metadata": {
-    "description": "Get Design Done — 5-stage agent-orchestrated design pipeline (Brief → Explore → Plan → Design → Verify) for AI coding agents. 61 agents, 96 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.2"
+    "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.58.0"
   },
   "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, 96 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.2",
+      "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.58.0",
       "author": {
         "name": "hegemonart"
       },

package/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.57.2",
-  "description": "Agent-orchestrated 5-stage design pipeline (Brief → Explore → Plan → Design → Verify) for AI coding agents. 61 specialized agents, 96 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.",
+  "version": "1.58.0",
+  "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",
     "url": "https://github.com/hegemonart"

package/CHANGELOG.md

@@ -4,6 +4,93 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [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
+
+Continuation of the v1.57.2 grooming wave. Closes the open POLISH-PLAN items that v1.57.2 deferred, plus a structural cleanup the user noticed during PR review. Additive only; no breaking changes. 5,007/5,007 tests pass.
+
+### Removed
+
+- **`agents/prototype-gate.md`** - orphan agent (no skill dispatched it, no hook fired it). Functionality is absorbed by `sketch-wrap-up` and `spike-wrap-up`.
+- **`skills/scan/` + `skills/discover/`** + their `source/skills/` mirrors. Deprecated aliases of `/gdd:explore` for several releases; the root SKILL.md command table no longer carries them. Counts drop 96 -> 94 skills.
+- **`hooks/run-hook.cmd`** - obsolete after the v1.57.2 `.sh` -> `.cjs` SessionStart hook port (all 4 SessionStart hooks now run via `node`, no Windows-bash wrapper needed).
+- **`scripts/lib/worktree-resolve.cjs#resolvePlanningRoot`** - unused export per the audit. Zero production callers across `scripts/ sdk/ hooks/ agents/ skills/`.
+- **`skills/new-cycle/milestone-completeness-rubric.md`** - plugin-internal release-process rubric that was shipping to users via `skills/`. Moved to `docs/MAINTAINER-NOTES.md` so it stops landing in user `~/.claude/skills/` installs.
+- **6 stale `docs/i18n/README.*.md` translations** (de / fr / it / ja / ko / zh-CN). Frozen at v1.24.0 per the v1.57.2 audit. The English README will be rewritten separately. Removed the multilingual nav line from the main README.
+- **`dist/claude-code/` from `package.json#files` + git tracking** - the directory was a byte-identical duplicate of `skills/` (120 files; Claude Code reads `./skills/` directly via `package.json#skills`). `dist/` now fully gitignored; the on-disk dir is a deterministic build artifact rebuilt by `npm run build:skills` on demand. Saves ~120 duplicate-file entries from every npm tarball (tarball-manifest baseline shrank 1001 -> 879 lines).
+- **`.DS_Store` macOS cruft** swept from `skills/`, `test/`, `dist/` + added `**/.DS_Store` to `.gitignore`.
+
+### Added
+
+- **`scripts/check-codex-plugin-drift.cjs`** + `npm run validate:codex-plugin` + `test/suite/codex-plugin-drift.test.cjs` - new CI gate that asserts the committed `.codex-plugin/plugin.json` and `.cursor-plugin/plugin.json` byte-match the generator output from `scripts/build-distribution-bundles.cjs`. Mirrors the baseline-ratchet pattern of `check-feature-counts.cjs`; supports `--rebaseline` for legitimate generator changes. Closes the "committed vs generated SoT" open question from POLISH-PLAN.md by making the generator authoritative and the committed snapshot a verified mirror.
+- **`source/skills/README.md`** + **`skills/README.md`** - documents `source/skills/` as the canonical home for skill BODY content. `scripts/lib/manifest/skills.json` remains the SoT for universal frontmatter fields (`name`, `description`, `argument-hint`, `tools`, `user-invocable`, `disable-model-invocation`). `skills/` is a byte-stable build artifact (npm distribution path); `dist/<harness>/` is a build-time output for non-Claude harness channels.
+- **`docs/MAINTAINER-NOTES.md`** - relocated home for `milestone-completeness-rubric.md` (moved from `skills/new-cycle/`).
+- **Phase 58 entry in `.planning/ROADMAP.md`** - Composition-Graph Mandatory Rollout. Goal: backfill `composes_with` on the remaining 74 of 96 skills (this release added 13 more, bringing the total from 9 to 22 wired skills). Scope: 6 plans across 3 waves (audit + allowlist; backfill + contract bump + scaffolder; closeout). Target v1.58.0.
+- **`composes_with` edges on 13 additional high-traffic skills** (`scripts/lib/manifest/skills.json`): apply-reflections, brief, compare, complete-cycle, darkmode, debug, discuss, explore, figma-extract, figma-write, live, map, new-cycle, new-project, progress. `reference/skill-graph.md` regenerated (96 -> 94 nodes after scan/discover removal, 34 edges, 0 cycles).
+- **`connections/cursor.md`** got a documented sibling-drop fix (followup from v1.57.2's H6 documentation).
+
+### Changed
+
+- **`source/skills/style/SKILL.md`** - removed user-facing `.planning/STATE.md` reference (was "a pre-roadmap decision recorded in `.planning/STATE.md`" -> now neutral "deliberate namespace decision"). Built artifacts in `skills/` and `dist/claude-code/` propagated.
+- **`reference/model-tiers.md`** - softened the agent-name prefix convention (`gdd-*` = housekeeping; `design-*` = pipeline) into a soft naming hint rather than enforced rule. Added explicit "prefix is not a tier signal" clarifier above the Per-Agent Tier Map. Fixed gdd-intel-updater rationale that mentioned `.planning/intel/` (the agent actually writes `.design/intel/`).
+- **`agents/README.md` Naming Convention** - replaced the implicit "all agents use `design-` prefix" claim with neutral language acknowledging the mix of `design-*` / `gdd-*` / bare prefixes. No enforcement; no expected pattern.
+- **`reference/runtime-models.md`** - the 10 unverified entries (kilo, copilot, cursor, windsurf, antigravity, augment, trae, codebuddy, cline, opencode) reformatted: dropped the `<TODO: confirm at ...>` URL wrapper, kept the plain URL, added explicit `"verified": false` field on provenance. The 4 verified entries (claude, codex, gemini, qwen) get `"verified": true`. Schema (`reference/schemas/runtime-models.schema.json`) gained the optional `verified` boolean field.
+- **`scripts/lib/manifest/skills.json` + `reference/skill-graph.md`** - graph regenerated (now 94 skills, 34 composition edges, 0 cycles).
+- **`.github/workflows/release.yml`** - added `cursor-marketplace` channel to the distribution-bundles build step (was missing from the release CI; the converter existed but wasn't wired into the release run).
+- **Skill count claims** synchronized to filesystem truth across all 5 surfaces (plugin.json + marketplace.json + README.md): 96 -> 94 skills.
+- **`scripts/build-skills.cjs` `--check` mode** - dropped the `dist/claude-code/` drift assertion (the dir is no longer committed; only `skills/` is the canonical built artifact under git).
+- **`test/suite/phase-42-build.test.cjs` 42-build-06** - repurposed from "dist/claude-code/ mirrors skills/" to "dist/claude-code/ is NOT committed" (preserves the gate against accidental re-introduction).
+
+### Test infrastructure
+
+- Forward-propagated `manifests-version.txt` baselines from `1.57.2` -> `1.57.3` across 37 phase fixture dirs.
+- `semver-compare.test.cjs` registers `OFF_CADENCE_VERSIONS.add('1.57.3')` with multi-line rationale comment matching the v1.57.2 pattern.
+- Tarball manifest baseline regenerated via `npm pack --dry-run --json` (1001 -> 879 lines after dist/claude-code/ removal + scan/discover/prototype-gate/milestone-rubric deletes).
+- Skill frontmatter regenerated via `npm run generate:skill-frontmatter` (3 drifted entries on bootstrap-ds, compare, synthesize).
+- 23 test failures from the deletes (count drift, baseline drift, em-dash lint, codex-plugin-drift) all resolved.
+
+---
+
 ## [1.57.2] - 2026-06-04
 
 ### Polish wave - 24 commits closing the v1.57 audit + 5 new CI gates

package/README.md

@@ -307,7 +307,7 @@ Targets 50–70% per-task token-cost reduction with no quality-floor regression.
 
 ## Commands
 
-GDD ships 96 skills. The most common ones are below; for the full reference see [SKILL.md](SKILL.md).
+GDD ships 94 skills. The most common ones are below; for the full reference see [SKILL.md](SKILL.md).
 
 ### Core Pipeline
 

package/SKILL.md

@@ -2,7 +2,7 @@
 name: get-design-done
 short_name: gdd
 description: "Master design pipeline for Claude Code. 5-stage workflow: Brief → Explore → Plan → Design → Verify. Run 'brief' first in any new project to capture the design problem, then 'explore' to inventory the codebase and interview for context. Invoke without arguments for status and auto-routing."
-argument-hint: "[brief|explore|plan|design|verify|handoff|map|next|help|status|style|darkmode|live|compare|figma-write|graphify|discuss|list-assumptions|progress|health|todo|stats|note|plant-seed|add-backlog|review-backlog|scan|discover|settings|update|reapply-patches|audit|pause|resume|new-cycle|debug|quick|new-project|complete-cycle|fast|do|ship|undo|pr-branch|sketch|sketch-wrap-up|spike|spike-wrap-up|reflect|apply-reflections|analyze-dependencies|extract-learnings|skill-manifest|pin|unpin|list-pins|new-skill|new-addendum|instinct|warm-cache|optimize|cache-manager|watch-authorities|check-update|benchmark|recall|timeline|continue|zoom-out]"
+argument-hint: "[brief|explore|plan|design|verify|handoff|map|next|help|status|style|darkmode|live|compare|figma-write|graphify|discuss|list-assumptions|progress|health|todo|stats|note|plant-seed|add-backlog|review-backlog|settings|update|reapply-patches|audit|pause|resume|new-cycle|debug|quick|new-project|complete-cycle|fast|do|ship|undo|pr-branch|sketch|sketch-wrap-up|spike|spike-wrap-up|reflect|apply-reflections|analyze-dependencies|extract-learnings|skill-manifest|pin|unpin|list-pins|new-skill|new-addendum|instinct|warm-cache|optimize|cache-manager|watch-authorities|check-update|benchmark|recall|timeline|continue|zoom-out]"
 user-invocable: true
 ---
 
@@ -14,7 +14,7 @@ Entry point for the get-design-done toolkit. Establishes the `/gdd:` command nam
 Brief → Explore → Plan → Design → Verify  →  next
 ```
 
-The 5-stage pipeline. `scan` and `discover` are now merged into `explore` - their old aliases still route through for backward compatibility.
+The 5-stage pipeline. `scan` and `discover` (previously deprecated aliases of `explore`) have been removed - use `explore` directly.
 
 Each stage produces artifacts in `.design/` inside the current project.
 
@@ -82,8 +82,6 @@ Each stage produces artifacts in `.design/` inside the current project.
 | `sketch-wrap-up [slug]` | `get-design-done:gdd-sketch-wrap-up` | Pick winner + rationale → writes `./.claude/skills/design-<area>-conventions.md` |
 | `spike [hypothesis] [--timebox N]` | `get-design-done:gdd-spike` | Timeboxed feasibility experiment → `.design/spikes/<slug>/` |
 | `spike-wrap-up [slug]` | `get-design-done:gdd-spike-wrap-up` | Capture findings + D-XX decision → `.design/spikes/<slug>/FINDINGS.md` |
-| `scan` *(deprecated)* | `get-design-done:scan` | Alias - use `explore` instead |
-| `discover` *(deprecated)* | `get-design-done:discover` | Alias - use `explore` instead |
 | **Configuration** | | |
 | `settings <profile\|parallelism\|cleanup\|show>` | `get-design-done:gdd-settings` | Manage `.design/config.json` - model profile, parallelism, cleanup |
 | **Maintenance** | | |
@@ -226,8 +224,6 @@ If `$ARGUMENTS` is a stage or command name - invoke it directly, no state check:
 /gdd:plant-seed     → Skill("get-design-done:gdd-plant-seed")
 /gdd:add-backlog    → Skill("get-design-done:gdd-add-backlog")
 /gdd:review-backlog → Skill("get-design-done:gdd-review-backlog")
-/gdd:scan      → Skill("get-design-done:gdd-explore")   # deprecated alias → explore
-/gdd:discover  → Skill("get-design-done:gdd-explore")   # deprecated alias → explore
 # --- Configuration ---
 /gdd:settings        → Skill("get-design-done:gdd-settings")
 # --- Maintenance ---

package/connections/cursor.md

@@ -49,7 +49,6 @@ This is a systemic limitation of the current `multi-artifact` install pipeline (
 - `explore/explore-procedure.md`
 - `health/health-mcp-detection.md`
 - `health/health-skill-length-report.md`
-- `new-cycle/milestone-completeness-rubric.md`
 - `peer-cli-add/peer-cli-protocol.md`
 - `plan/plan-procedure.md`
 - `quality-gate/threat-modeling.md`

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.2",
+  "version": "1.58.0",
   "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",
@@ -23,7 +23,6 @@
     "sdk/",
     "recipes/",
     "docs/i18n/",
-    "dist/claude-code/",
     "scripts/lib/",
     "scripts/cli/",
     "scripts/install.cjs",
@@ -56,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-graph.md

@@ -9,13 +9,12 @@ is a `composes_with` edge (the source calls the target as sub-orchestration); a
 a `next_skills` edge (a pipeline hint for what runs next). Stage grouping is best-effort and
 inferred from the skill name; skills with no stage keyword fall under Utility.
 
-Skills: 96. Composition edges: 21 composes_with, 6 next_skills.
+Skills: 94. Composition edges: 19 composes_with, 6 next_skills.
 
 ```mermaid
 flowchart TD
   subgraph intake["Intake"]
     n_brief["brief"]
-    n_discover["discover"]
     n_new_cycle["new-cycle"]
     n_new_project["new-project"]
     n_start["start"]
@@ -52,7 +51,6 @@ flowchart TD
     n_complete_cycle["complete-cycle"]
     n_quality_gate["quality-gate"]
     n_review_backlog["review-backlog"]
-    n_scan["scan"]
     n_turn_closeout["turn-closeout"]
     n_verify["verify"]
   end
@@ -134,7 +132,6 @@ flowchart TD
   n_design --> n_paper_write
   n_design --> n_pencil_write
   n_design -.-> n_verify
-  n_discover --> n_explore
   n_discuss --> n_list_assumptions
   n_explore --> n_discuss
   n_explore --> n_list_assumptions
@@ -144,7 +141,6 @@ flowchart TD
   n_new_project --> n_brief
   n_new_project -.-> n_brief
   n_plan -.-> n_design
-  n_scan --> n_explore
   n_ship --> n_pr_branch
   n_sketch --> n_sketch_wrap_up
   n_spike --> n_spike_wrap_up

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

@@ -43,7 +43,7 @@
     },
     {
       "name": "bootstrap-ds",
-      "description": "Bootstraps a design system for a GREENFIELD project that has none - no Figma, no tokens, no component library. Takes a brand input (primary color + optional secondary + tone tags + target framework) and emits a coherent OKLCH token system (color tints, modular type scale, 4pt/8pt spacing, radius + motion defaults) in 3 variants to pick from, then scaffolds proof components (button/input/card). Use at the start of a brand-new project, or when {{command_prefix}}discover finds no existing design system. Never invents a brand; never overwrites an existing DS.",
+      "description": "Bootstraps a design system for a GREENFIELD project that has none - no Figma, no tokens, no component library. Takes a brand input (primary color + optional secondary + tone tags + target framework) and emits a coherent OKLCH token system (color tints, modular type scale, 4pt/8pt spacing, radius + motion defaults) in 3 variants to pick from, then scaffolds proof components (button/input/card). Use at the start of a brand-new project, or when {{command_prefix}}explore finds no existing design system. Never invents a brand; never overwrites an existing DS.",
       "argument_hint": "[--primary <color>] [--secondary <color>] [--tone <tags>] [--framework web|native-ios|native-android|flutter]",
       "user_invocable": true,
       "tools": "Read, Write, Bash, Glob, Grep, AskUserQuestion, Task"
@@ -82,7 +82,7 @@
     },
     {
       "name": "compare",
-      "description": "Compute the delta between the `DESIGN.md` baseline (from scan) and the `DESIGN-VERIFICATION.md` result (from verify), reporting per-category score delta, anti-pattern delta (resolved vs new), must-have pass/fail change, and design drift (regressions without covering tasks in `DESIGN-PLAN.md`). Use after `verify` to measure whether a design pipeline cycle actually improved the design. Writes `.design/COMPARE-REPORT.md`. Activates for requests involving diffing a design baseline against verification output, or a before-after design delta.",
+      "description": "Compute the delta between the `DESIGN.md` baseline (from explore) and the `DESIGN-VERIFICATION.md` result (from verify), reporting per-category score delta, anti-pattern delta (resolved vs new), must-have pass/fail change, and design drift (regressions without covering tasks in `DESIGN-PLAN.md`). Use after `verify` to measure whether a design pipeline cycle actually improved the design. Writes `.design/COMPARE-REPORT.md`. Activates for requests involving diffing a design baseline against verification output, or a before-after design delta.",
       "argument_hint": "",
       "user_invocable": true,
       "composes_with": [
@@ -151,16 +151,6 @@
         "verify"
       ]
     },
-    {
-      "name": "discover",
-      "frontmatter_name": "discover",
-      "description": "Stage 1.5 of 4 orchestrator that probes Figma / Refero / Pinterest connections, spawns design-context-builder (auto-detect + interview) and (via lazy gate) design-context-checker (6-dimension validator), producing .design/DESIGN-CONTEXT.md. Use after {{command_prefix}}scan when a fast-path context build is wanted instead of the full {{command_prefix}}explore. Activates for requests involving detecting an existing design system, inventorying tokens and components, or onboarding a brownfield repo.",
-      "argument_hint": "[--auto] [--incremental] [--full]",
-      "user_invocable": true,
-      "composes_with": [
-        "explore"
-      ]
-    },
     {
       "name": "discuss",
       "description": "Adaptive design interview command that spawns design-discussant in normal / --all / --spec mode to gather decisions via one-question-at-a-time AskUserQuestion, writing D-XX entries to STATE.md <decisions>. Use when locking design decisions outside the main pipeline or backfilling missing context.",
@@ -322,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,
@@ -535,16 +525,6 @@
       "argument_hint": "<intent-string> [<target-artifacts-csv>]",
       "tools": "Read, Bash, Grep"
     },
-    {
-      "name": "scan",
-      "frontmatter_name": "scan",
-      "description": "Pre-pipeline initializer that maps an existing repo's design system (colors, typography, spacing, components, tokens), runs the anti-pattern audit, scores the 7 weighted categories, and writes DESIGN.md + .design/DESIGN-DEBT.md. Use when starting work in any new or existing repo before {{command_prefix}}discover. Activates for requests involving a fast read-only anti-pattern sweep, a quick design lint, or spotting slop without a full audit.",
-      "argument_hint": "[--quick] [--full]",
-      "user_invocable": true,
-      "composes_with": [
-        "explore"
-      ]
-    },
     {
       "name": "settings",
       "description": "Manage .design/config.json settings. Subcommands: profile, parallelism, cleanup, show.",
@@ -628,7 +608,7 @@
     {
       "name": "synthesize",
       "frontmatter_name": "synthesize",
-      "description": "Streaming synthesizer - collapses N parallel-agent markdown outputs into one compact merged summary via a single Haiku 4.5 call. Invoked inline by orchestrators (skills/map/, skills/discover/, skills/plan/) after parallel spawns return. Not user-invocable.",
+      "description": "Streaming synthesizer - collapses N parallel-agent markdown outputs into one compact merged summary via a single Haiku 4.5 call. Invoked inline by orchestrators (skills/map/, skills/explore/, skills/plan/) after parallel spawns return. Not user-invocable.",
       "tools": "Read, Task",
       "user_invocable": false,
       "disable_model_invocation": 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/scripts/lib/worktree-resolve.cjs

@@ -2,9 +2,9 @@
 /**
  * scripts/lib/worktree-resolve.cjs — Phase 49 (Quick Anti-Slop Floor).
  *
- * Redirect `.design/` and `.planning/` writes to the MAIN repo root when GDD
- * runs inside a git WORKTREE. A worktree has its own ephemeral checkout dir; a
- * naive `process.cwd()`-relative `.design/STATE.md` write would land inside the
+ * Redirect `.design/` writes to the MAIN repo root when GDD runs inside a git
+ * WORKTREE. A worktree has its own ephemeral checkout dir; a naive
+ * `process.cwd()`-relative `.design/STATE.md` write would land inside the
  * throwaway worktree and get lost (or leak) when the worktree is removed. We
  * detect the worktree, resolve the main repo root, and point artifact writes
  * there so state survives across worktree lifecycles.
@@ -167,17 +167,6 @@ function resolveDesignRoot(cwd = process.cwd(), exec) {
   return path.join(resolveRepoRoot(cwd, exec), '.design');
 }
 
-/**
- * Absolute `.planning` root in the MAIN repo (worktree-safe).
- *
- * @param {string} [cwd=process.cwd()]
- * @param {(cmd: string, args: string[]) => string} [exec]
- * @returns {string}
- */
-function resolvePlanningRoot(cwd = process.cwd(), exec) {
-  return path.join(resolveRepoRoot(cwd, exec), '.planning');
-}
-
 /** One-shot guard so the redirect notice prints at most once per process. */
 let NOTICE_EMITTED = false;
 
@@ -193,7 +182,7 @@ let NOTICE_EMITTED = false;
 function noticeOnce(targetRoot, write) {
   if (NOTICE_EMITTED) return false;
   NOTICE_EMITTED = true;
-  const line = `worktree detected -> .design/.planning redirected to ${targetRoot}\n`;
+  const line = `worktree detected -> .design redirected to ${targetRoot}\n`;
   try {
     if (typeof write === 'function') {
       write(line);
@@ -215,7 +204,6 @@ module.exports = {
   isWorktree,
   resolveRepoRoot,
   resolveDesignRoot,
-  resolvePlanningRoot,
   noticeOnce,
   _resetNoticeForTests,
 };

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.