@hegemonart/get-design-done 1.57.2 → 1.57.3

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.57.3"
   },
   "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.57.3",
       "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.57.3",
+  "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,54 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.57.2",
+  "version": "1.57.3",
   "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",

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/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.",
@@ -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/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/skills/README.md

@@ -0,0 +1,46 @@
+# `source/skills/` - Canonical Skill BODY Source
+
+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.
+
+`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.
+
+## 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 |
+
+The forward direction is **`skills.json` -> `source/skills/` -> `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).
+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
+   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`.
+
+## 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/`.
+
+## Cross-references
+
+- `scripts/build-skills.cjs` - the multi-harness orchestrator that compiles this directory.
+- `scripts/lib/build/factory.cjs` - the pure transformer applied per-harness.
+- `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).

package/skills/bootstrap-ds/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-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 /gdd: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 /gdd: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

package/skills/compare/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-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
 ---

package/skills/new-cycle/SKILL.md

@@ -7,7 +7,7 @@ tools: Read, Write, AskUserQuestion
 
 # /gdd:new-cycle
 
-The cycle is the hierarchical unit above individual pipeline runs: **Cycle > Pipeline run > Wave > Task**. Each cycle has a goal, tracks its own decisions, and can span many pipeline runs. See `./milestone-completeness-rubric.md` §"Cycle level" for what counts as cycle completion (used by `/gdd:complete-cycle` to close the cycle).
+The cycle is the hierarchical unit above individual pipeline runs: **Cycle > Pipeline run > Wave > Task**. Each cycle has a goal, tracks its own decisions, and can span many pipeline runs. `/gdd:complete-cycle` closes the cycle once goals are met and a retrospective is captured.
 
 ## Steps
 

package/skills/peer-cli-customize/SKILL.md

@@ -79,7 +79,6 @@ See `./../peer-cli-add/peer-cli-protocol.md` §"Edge cases" for: rewire-to-unmat
 - `scripts/validate-frontmatter.ts` (Plan 27-06) - `delegate_to` validation.
 - `scripts/lib/peer-cli/registry.cjs` (Plan 27-05) - capability matrix.
 - `skills/peer-cli-add/SKILL.md` - for adding a NEW peer (this skill rewires among existing peers).
-- `.planning/phases/27-peer-cli-delegation/CONTEXT.md` D-06 - decision lineage.
 
 ## Record
 

package/skills/peers/SKILL.md

@@ -85,7 +85,7 @@ The table IS the output. No follow-up prose. Users act on it: `(opt-in disabled)
 
 - `./../peer-cli-add/peer-cli-protocol.md` - ACP/ASP handshake + adapter scaffold (procedure ref shared with peer-cli-add/customize).
 - `./reference/peer-cli-capabilities.md` (Plan 27-05) - full capability matrix doc.
-- `scripts/lib/peer-cli/registry.cjs` (Plan 27-05), `scripts/lib/install/runtimes.cjs` (Plan 27-11), `skills/peer-cli-customize/SKILL.md`, `skills/peer-cli-add/SKILL.md`, `.planning/phases/27-peer-cli-delegation/CONTEXT.md` D-10.
+- `scripts/lib/peer-cli/registry.cjs` (Plan 27-05), `scripts/lib/install/runtimes.cjs` (Plan 27-11), `skills/peer-cli-customize/SKILL.md`, `skills/peer-cli-add/SKILL.md`.
 
 ## Record
 

package/skills/reflect/procedures/capability-gap-scan.md

@@ -117,4 +117,3 @@ npm test
 - `reference/schemas/events.schema.json` - the `capability_gap` event class shipped by Plan 29-01 (the 7-field shape + `TrajectoryRef` definition).
 - `scripts/lib/event-chain.cjs` - `appendChainEvent` (the real emitter API; 29-01 did NOT ship a separate helper file).
 - `scripts/lib/bandit-router.cjs` - Phase 23.5 posterior file producer (the source for scan #2).
-- `.planning/phases/29-capability-gap-self-authoring/CONTEXT.md` - phase decisions (D-02 7-field shape, D-07 hash-pinning, D-08 MCP carve-out, D-11 tmpdir tests).

package/skills/report-issue/report-issue-procedure.md

@@ -117,4 +117,3 @@ Body is written to a tmp file to avoid arg-length and shell-escaping. URL parsed
 - [SKILL.md](./SKILL.md) - entry contract.
 - `reference/pseudonymization-rules.md` - full R1..R8 rule catalog (Plan 30-01).
 - `reference/known-failure-modes.md` - triage catalogue (Plan 30-03).
-- `.planning/phases/30-issue-reporter/CONTEXT.md` - phase decisions D-01..D-15.

package/skills/synthesize/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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/skills/turn-closeout/SKILL.md

@@ -9,7 +9,7 @@ tools: Read, Bash
 
 ## Role
 
-You are a deterministic **closeout** skill. You close the per-turn telemetry gap on runtimes that don't expose a Stop event (codex, gemini, and 11 others). You are a code-level mirror of `hooks/gdd-turn-closeout.js` (D-10): same conditions, same idempotence, same emitted event shape. The only difference: the JS hook emits the nudge as `additionalContext` via the harness; this skill prints the nudge directly to the user. See `./../new-cycle/milestone-completeness-rubric.md` §"Task level" for the broader closeout discipline (what "turn complete" means within a stage).
+You are a deterministic **closeout** skill. You close the per-turn telemetry gap on runtimes that don't expose a Stop event (codex, gemini, and 11 others). You are a code-level mirror of `hooks/gdd-turn-closeout.js` (D-10): same conditions, same idempotence, same emitted event shape. The only difference: the JS hook emits the nudge as `additionalContext` via the harness; this skill prints the nudge directly to the user. A turn is "complete" when the verify command exits 0, the `<done>` criterion is observable, and the diff stays within the declared scope - any deviation is logged for the run summary.
 
 **When to invoke:** orchestrator skills (`/gdd:next`, `/gdd:design`, `/gdd:verify`) tail-call this skill as their final step before returning. Adoption is incremental - each orchestrator can wire the tail-call independently; the skill exists as a stable, callable surface today.
 

package/dist/claude-code/.claude/skills/add-backlog/SKILL.md

@@ -1,48 +0,0 @@
----
-name: gdd-add-backlog
-description: "Park a design idea for a future cycle. Writes to .design/backlog/BACKLOG.md."
-argument-hint: "[text]"
-tools: Read, Write, AskUserQuestion
-disable-model-invocation: true
----
-
-# /gdd:add-backlog
-
-**Role:** Long-term parking lot for design ideas. Backing store: `.design/backlog/BACKLOG.md`.
-
-## Step 1 - Get text
-
-If `$ARGUMENTS` is empty, ask the user: "What should be added to the backlog?"
-
-## Step 2 - Append
-
-Create `.design/backlog/` directory and `BACKLOG.md` with `# Design Backlog` header if missing.
-
-Derive `<title>` = first 60 characters of the text (strip newlines). Append:
-
-```markdown
-## <title>
-**Added**: YYYY-MM-DD
-**Status**: parked
-
-<full text>
-
----
-```
-
-## Output
-
-```
-━━━ Backlog entry parked ━━━
-Title: <title>
-Status: parked
-Promote later via: /gdd:review-backlog
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-## Constraints
-
-- Do not modify files outside `.design/backlog/`.
-- Do not set status to anything other than `parked` here - `/gdd:review-backlog` owns status transitions.
-
-## ADD-BACKLOG COMPLETE

package/dist/claude-code/.claude/skills/analyze-dependencies/SKILL.md

@@ -1,95 +0,0 @@
----
-name: gdd-analyze-dependencies
-description: "Queries the intel store to surface token fan-out, component call-graphs, decision traceability, and circular dependency detection. Requires .design/intel/ to exist (run build-intel.cjs first)."
-tools: Bash, Read, Glob, Grep
----
-
-# /gdd:analyze-dependencies
-
-**Role:** Surface dependency relationships, token usage spread, component graphs, and decision traceability using `.design/intel/`. All queries are O(1) reads against pre-built JSON slices - no file greps. See `./reference/heuristics.md` for the underlying dependency-analysis heuristics (fan-out thresholds, orphan-token criteria, cycle-detection bias).
-
-## Pre-flight
-
-Verify the intel store exists:
-
-```bash
-ls .design/intel/files.json 2>/dev/null && echo "ready" || echo "missing"
-```
-
-If missing, print:
-
-```
-Intel store not found. Build it first:
-  node scripts/build-intel.cjs --force
-Then re-run /gdd:analyze-dependencies.
-```
-
-## Usage modes
-
-- `/gdd:analyze-dependencies` - run all four analyses and print a combined report
-- `/gdd:analyze-dependencies tokens` - token fan-out only
-- `/gdd:analyze-dependencies components` - component call-graph only
-- `/gdd:analyze-dependencies decisions` - decision traceability only
-- `/gdd:analyze-dependencies circular` - circular dependency detection only
-
-## Analysis 1 - Token fan-out
-
-Surfaces tokens referenced in many files + orphans (referenced exactly once).
-
-1. Read `.design/intel/tokens.json`; group by `token` value; count distinct `file` values.
-2. Sort descending; print top-20 with token / file count / category columns.
-3. Append orphans list (token + file:line of the single reference).
-
-Header: `━━━ Token fan-out ━━━` … `(top 20 shown)` … `Orphaned tokens (referenced in exactly 1 file):` … footer rule.
-
-## Analysis 2 - Component call-graph
-
-Surfaces widely-referenced components and the files referencing each.
-
-1. Read `.design/intel/components.json`; group by `component` name; count distinct `file` values.
-2. Sort descending; print top-20 with component / references / files columns.
-3. If `components <Name>` is passed, print only that component's referencing files (one per line).
-
-Header: `━━━ Component call-graph ━━━` … footer rule.
-
-## Analysis 3 - Decision traceability
-
-Maps decisions to skill/agent files that cite them.
-
-1. Read `.design/intel/decisions.json` (decision IDs D-01, D-02, …).
-2. Read `.design/intel/symbols.json` for heading anchors; `.design/intel/dependencies.json` for @-reference chains.
-3. For each decision, cross-reference which files cite the ID.
-4. Print per-decision block: `D-NN  <description>` then a 6-space-indented `Referenced by: <file:line>, …` line (or `(no explicit references found)`).
-5. Footer: `Total: N decisions tracked, M with file references`.
-
-Empty-state: `No decisions indexed. Run node scripts/build-intel.cjs after creating .design/DESIGN-CONTEXT.md.`
-
-## Analysis 4 - Circular dependency detection
-
-Detects cycles in the `@`-reference graph (File A → File B → File A). DFS with path-tracking detects back-edges; algorithm + adjacency-map shape detailed in `./reference/heuristics.md` §"Dependency-cycle detection".
-
-1. Read `.design/intel/graph.json`; build adjacency map from `edges`.
-2. Run DFS with path-tracking; collect back-edges as cycles.
-3. Print each cycle with the node sequence + `<- CYCLE` marker on the closing node.
-4. Footer: `Total cycles: N` (or `All clear — no circular dependencies detected.`).
-
-## Combined report
-
-When run without a mode argument, print all four analyses in sequence separated by blank lines, prefixed with:
-
-```
-━━━ Dependency Analysis ━━━
-Intel store: .design/intel/
-Generated:   <timestamp from files.json>
-Files indexed: <count>
-```
-
-## Required reading (conditional)
-
-@.design/intel/tokens.json (if present)
-@.design/intel/components.json (if present)
-@.design/intel/dependencies.json (if present)
-@.design/intel/decisions.json (if present)
-@.design/intel/graph.json (if present)
-
-## ANALYZE-DEPENDENCIES COMPLETE