@hegemonart/get-design-done 1.48.0 → 1.50.0

package/scripts/lib/worktree-resolve.cjs

@@ -0,0 +1,221 @@
+'use strict';
+/**
+ * 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
+ * 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.
+ *
+ * Detection: `git rev-parse --git-dir` and `--git-common-dir` DIFFER inside a
+ * linked worktree (git-dir is `<main>/.git/worktrees/<name>`, common-dir is
+ * `<main>/.git`); in the main checkout they are EQUAL. The main repo root is the
+ * PARENT of the common git dir.
+ *
+ * Pure + dependency-free except for spawning `git`, and the `git` call is fully
+ * injectable via an `exec` parameter so tests run without a real worktree. NEVER
+ * throws: when git is unavailable (no repo, git not on PATH) every resolver
+ * degrades gracefully to the caller's `cwd`, so non-git consumers are unaffected.
+ *
+ * No top-level `Date.now()` / `Math.random()` — the only module-level mutable
+ * state is the one-shot `noticeOnce` flag, intentionally per-process.
+ *
+ * CommonJS so it ships in the npm package and loads from `.cjs` callers and the
+ * dual-mode `.ts`/`.js` MCP servers alike.
+ */
+
+const { spawnSync } = require('node:child_process');
+const path = require('node:path');
+
+/**
+ * Default `exec`: synchronously run `git <args...>` in `cwd` and return its
+ * trimmed stdout. Returns null on ANY failure (git missing, non-zero exit,
+ * not a repo) so callers can treat "no git" as "not a worktree".
+ *
+ * @param {string[]} args git arguments, e.g. ['rev-parse', '--git-dir']
+ * @param {string} cwd working directory to run git in
+ * @returns {string | null} trimmed stdout, or null on failure
+ */
+function defaultExec(args, cwd) {
+  try {
+    const res = spawnSync('git', args, {
+      cwd,
+      encoding: 'utf8',
+      windowsHide: true,
+    });
+    if (!res || res.status !== 0 || typeof res.stdout !== 'string') return null;
+    const out = res.stdout.trim();
+    return out.length ? out : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Normalize an injectable `exec` into a uniform `(args, cwd) => string|null`.
+ *
+ * The injectable form callers/tests pass is `(cmd, args) => string` where `cmd`
+ * is the literal `'git'` and `args` is the argv array (matching the prompt
+ * contract). We adapt it here and swallow throws into null so a test exec that
+ * throws models "git unavailable" exactly like the real one returning null.
+ *
+ * @param {undefined | ((cmd: string, args: string[]) => string)} exec
+ * @param {string} cwd
+ * @returns {(args: string[]) => string | null}
+ */
+function makeRunner(exec, cwd) {
+  if (typeof exec === 'function') {
+    return (args) => {
+      try {
+        const out = exec('git', args);
+        if (typeof out !== 'string') return null;
+        const trimmed = out.trim();
+        return trimmed.length ? trimmed : null;
+      } catch {
+        return null;
+      }
+    };
+  }
+  return (args) => defaultExec(args, cwd);
+}
+
+/**
+ * Resolve the absolute git-dir and git-common-dir for `cwd`.
+ *
+ * `git rev-parse` prints these relative to `cwd` in some setups and absolute in
+ * others; we resolve both against `cwd` so comparison and parent-of logic is
+ * always done on absolute, normalized paths.
+ *
+ * @returns {{ gitDir: string, commonDir: string } | null} null when not a repo
+ */
+function gitDirs(run, cwd) {
+  const gitDirRaw = run(['rev-parse', '--git-dir']);
+  if (gitDirRaw == null) return null;
+  const commonDirRaw = run(['rev-parse', '--git-common-dir']);
+  if (commonDirRaw == null) return null;
+  const gitDir = path.resolve(cwd, gitDirRaw);
+  const commonDir = path.resolve(cwd, commonDirRaw);
+  return { gitDir, commonDir };
+}
+
+/**
+ * True when `cwd` sits inside a linked git WORKTREE (git-dir !== git-common-dir).
+ * False in the main checkout, and false (degrade gracefully) when git is
+ * unavailable or `cwd` is not inside any repo.
+ *
+ * @param {string} [cwd=process.cwd()]
+ * @param {(cmd: string, args: string[]) => string} [exec] injectable git runner
+ * @returns {boolean}
+ */
+function isWorktree(cwd = process.cwd(), exec) {
+  const run = makeRunner(exec, cwd);
+  const dirs = gitDirs(run, cwd);
+  if (dirs == null) return false;
+  return dirs.gitDir !== dirs.commonDir;
+}
+
+/**
+ * Resolve the MAIN repo root for `cwd`.
+ *
+ *   - In a worktree: the parent of the git-common-dir (`<main>/.git` -> `<main>`).
+ *   - In the main checkout: the toplevel (`git rev-parse --show-toplevel`).
+ *   - git unavailable / not a repo: falls back to `path.resolve(cwd)`.
+ *
+ * Never throws.
+ *
+ * @param {string} [cwd=process.cwd()]
+ * @param {(cmd: string, args: string[]) => string} [exec] injectable git runner
+ * @returns {string} absolute main repo root
+ */
+function resolveRepoRoot(cwd = process.cwd(), exec) {
+  const run = makeRunner(exec, cwd);
+  const dirs = gitDirs(run, cwd);
+  if (dirs == null) {
+    // Not a repo / git unavailable — degrade to cwd.
+    return path.resolve(cwd);
+  }
+  if (dirs.gitDir !== dirs.commonDir) {
+    // Worktree: the main repo root is the parent of the common `.git` dir.
+    // common-dir is typically `<main>/.git`; its dirname is `<main>`. Guard the
+    // (unusual) bare-repo case where common-dir has no `.git` basename by only
+    // climbing when the basename looks like a git dir.
+    const base = path.basename(dirs.commonDir);
+    if (base === '.git' || base.endsWith('.git')) {
+      return path.dirname(dirs.commonDir);
+    }
+    // Bare/relocated git dir: best effort — fall through to toplevel below.
+  }
+  // Main checkout (or odd common-dir shape): prefer the toplevel.
+  const top = run(['rev-parse', '--show-toplevel']);
+  if (top != null) return path.resolve(cwd, top);
+  // Last resort: parent of the git dir, else cwd.
+  const base = path.basename(dirs.commonDir);
+  if (base === '.git' || base.endsWith('.git')) return path.dirname(dirs.commonDir);
+  return path.resolve(cwd);
+}
+
+/**
+ * Absolute `.design` root in the MAIN repo (worktree-safe).
+ *
+ * @param {string} [cwd=process.cwd()]
+ * @param {(cmd: string, args: string[]) => string} [exec]
+ * @returns {string}
+ */
+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;
+
+/**
+ * Emit a single one-line stderr notice — exactly once per process — announcing
+ * that worktree redirection is in effect. Subsequent calls are no-ops, so a
+ * caller can invoke this freely on every redirect without spamming stderr.
+ *
+ * @param {string} targetRoot the resolved MAIN repo root writes are redirected to
+ * @param {(line: string) => void} [write] injectable sink (default process.stderr)
+ * @returns {boolean} true if THIS call emitted the notice, false if already emitted
+ */
+function noticeOnce(targetRoot, write) {
+  if (NOTICE_EMITTED) return false;
+  NOTICE_EMITTED = true;
+  const line = `worktree detected -> .design/.planning redirected to ${targetRoot}\n`;
+  try {
+    if (typeof write === 'function') {
+      write(line);
+    } else {
+      process.stderr.write(line);
+    }
+  } catch {
+    /* never let a logging failure break a write path */
+  }
+  return true;
+}
+
+/** Test-only: reset the one-shot notice flag. Not part of the public contract. */
+function _resetNoticeForTests() {
+  NOTICE_EMITTED = false;
+}
+
+module.exports = {
+  isWorktree,
+  resolveRepoRoot,
+  resolveDesignRoot,
+  resolvePlanningRoot,
+  noticeOnce,
+  _resetNoticeForTests,
+};

package/sdk/mcp/gdd-state/server.js

@@ -35,7 +35,7 @@ __export(server_exports, {
   runStdio: () => runStdio
 });
 module.exports = __toCommonJS(server_exports);
-var import_node_fs4 = require("node:fs");
+var import_node_fs5 = require("node:fs");
 var import_node_path3 = require("node:path");
 var import_server = require("@modelcontextprotocol/sdk/server/index.js");
 var import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
@@ -1799,6 +1799,8 @@ async function transition(path2, toStage) {
 
 // sdk/mcp/gdd-state/tools/shared.ts
 var import_node_path2 = __toESM(require("node:path"));
+var import_node_fs4 = require("node:fs");
+var import_node_module2 = require("node:module");
 
 // sdk/event-stream/index.ts
 var import_node_os2 = require("node:os");
@@ -2012,9 +2014,40 @@ function getSessionId() {
   if (CACHED_SESSION_ID === null) CACHED_SESSION_ID = makeSessionId();
   return CACHED_SESSION_ID;
 }
+function _findRepoRoot2() {
+  let dir = process.cwd();
+  for (let i = 0; i < 8; i++) {
+    if ((0, import_node_fs4.existsSync)(import_node_path2.default.join(dir, "package.json"))) return dir;
+    const parent = import_node_path2.default.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return process.cwd();
+}
+var _worktree = (() => {
+  try {
+    const root = _findRepoRoot2();
+    const candidate = import_node_path2.default.resolve(root, "scripts/lib/worktree-resolve.cjs");
+    if (!(0, import_node_fs4.existsSync)(candidate)) return null;
+    const req = (0, import_node_module2.createRequire)(import_node_path2.default.join(root, "package.json"));
+    return req(candidate);
+  } catch {
+    return null;
+  }
+})();
 function resolveStatePath() {
   const override = process.env["GDD_STATE_PATH"];
   if (typeof override !== "string" || override.length === 0) {
+    if (_worktree !== null) {
+      try {
+        const designRoot = _worktree.resolveDesignRoot();
+        if (_worktree.isWorktree()) {
+          _worktree.noticeOnce(import_node_path2.default.dirname(designRoot));
+        }
+        return import_node_path2.default.join(designRoot, "STATE.md");
+      } catch {
+      }
+    }
     return ".design/STATE.md";
   }
   if (import_node_path2.default.isAbsolute(override)) {
@@ -2734,12 +2767,12 @@ function here() {
   const entry = process.argv[1];
   if (typeof entry === "string" && entry.length > 0) {
     const entryDir = (0, import_node_path3.dirname)((0, import_node_path3.resolve)(entry));
-    if ((0, import_node_fs4.existsSync)((0, import_node_path3.join)(entryDir, "tools", "index.ts"))) {
+    if ((0, import_node_fs5.existsSync)((0, import_node_path3.join)(entryDir, "tools", "index.ts"))) {
       return entryDir;
     }
   }
   const candidate = (0, import_node_path3.resolve)(process.cwd(), expectedRel);
-  if ((0, import_node_fs4.existsSync)((0, import_node_path3.join)(candidate, "tools", "index.ts"))) {
+  if ((0, import_node_fs5.existsSync)((0, import_node_path3.join)(candidate, "tools", "index.ts"))) {
     return candidate;
   }
   return candidate;
@@ -2748,7 +2781,7 @@ function loadTools() {
   const baseDir = here();
   return TOOL_MODULES.map((m) => {
     const absPath = (0, import_node_path3.join)(baseDir, "tools", m.schemaPath);
-    const raw = (0, import_node_fs4.readFileSync)(absPath, "utf8");
+    const raw = (0, import_node_fs5.readFileSync)(absPath, "utf8");
     const parsed = JSON.parse(raw);
     const rawInput = parsed.properties?.input;
     const inputSchema = rawInput !== void 0 && typeof rawInput === "object" ? rawInput : { type: "object" };

package/sdk/mcp/gdd-state/tools/shared.ts

@@ -12,6 +12,8 @@
 // {success:false, error} — handlers never propagate exceptions."
 
 import path from 'node:path';
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
 import {
   ValidationError,
   OperationFailedError,
@@ -50,6 +52,49 @@ export function getSessionId(): string {
   return CACHED_SESSION_ID;
 }
 
+/**
+ * Worktree redirect (Phase 49). When GDD runs inside a git WORKTREE, a naive
+ * `process.cwd()`-relative `.design/STATE.md` write lands in the ephemeral
+ * worktree and is lost when it is removed. `scripts/lib/worktree-resolve.cjs`
+ * resolves the MAIN repo root and points STATE writes there.
+ *
+ * Soft-loaded via createRequire (mirrors sdk/event-stream/writer.ts): tsc's
+ * Node16 module mode classifies this .ts as CJS output, so `import.meta` is
+ * unavailable — we anchor createRequire on the repo-root package.json found by
+ * walking up from cwd. If the helper is unreachable (a test subprocess running
+ * far above the plugin tree), every resolver degrades to a null shim and the
+ * default falls back to the legacy relative path. Production callers always run
+ * inside the plugin tree.
+ */
+interface WorktreeResolver {
+  resolveDesignRoot: (cwd?: string) => string;
+  isWorktree: (cwd?: string) => boolean;
+  noticeOnce: (targetRoot: string) => boolean;
+}
+
+function _findRepoRoot(): string {
+  let dir = process.cwd();
+  for (let i = 0; i < 8; i++) {
+    if (existsSync(path.join(dir, 'package.json'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return process.cwd();
+}
+
+const _worktree: WorktreeResolver | null = (() => {
+  try {
+    const root = _findRepoRoot();
+    const candidate = path.resolve(root, 'scripts/lib/worktree-resolve.cjs');
+    if (!existsSync(candidate)) return null;
+    const req = createRequire(path.join(root, 'package.json'));
+    return req(candidate) as WorktreeResolver;
+  } catch {
+    return null;
+  }
+})();
+
 /**
  * Resolve the target STATE.md path from the environment, with a
  * PATH-TRAVERSAL guard (Plan 33.5-03, D-08).
@@ -69,6 +114,22 @@ export function getSessionId(): string {
 export function resolveStatePath(): string {
   const override = process.env['GDD_STATE_PATH'];
   if (typeof override !== 'string' || override.length === 0) {
+    // No override: resolve STATE.md under the worktree-aware `.design` root
+    // (Phase 49). Outside a worktree this equals the legacy `<cwd>/.design`
+    // (when cwd is the repo root) so behavior is unchanged; inside a worktree
+    // the design root points at the MAIN repo so state is not lost. The notice
+    // fires at most once per process, only on an actual worktree redirect.
+    if (_worktree !== null) {
+      try {
+        const designRoot = _worktree.resolveDesignRoot();
+        if (_worktree.isWorktree()) {
+          _worktree.noticeOnce(path.dirname(designRoot));
+        }
+        return path.join(designRoot, 'STATE.md');
+      } catch {
+        // Fall through to the legacy relative default on any resolver fault.
+      }
+    }
     return '.design/STATE.md';
   }
 

package/skills/audit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-audit
-description: "Run a design audit by spawning design-auditor, design-integration-checker, and (optionally) design-verifier + design-reflector agents, then printing a consolidated 6-pillar score summary. Use when the user wants to score the current design, retroactively verify a completed cycle, or quickly re-check after a fix."
+description: "Run a design audit by spawning design-auditor, design-integration-checker, and (optionally) design-verifier + design-reflector agents, then printing a consolidated 6-pillar score summary. Use when the user wants to score the current design, retroactively verify a completed cycle, or quickly re-check after a fix. Activates for requests involving scoring an existing design, retroactively reviewing quality, or re-checking after a fix."
 argument-hint: "[--retroactive] [--quick] [--no-reflect]"
 tools: Read, Write, Task, Glob, Bash
 ---

package/skills/brief/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-brief
-description: "Stage 1 of 5 design intake that captures problem statement, audience, constraints, success metrics, and scope into .design/BRIEF.md, and bootstraps .design/STATE.md if missing. Use when starting a new design cycle and before /gdd:explore."
+description: "Stage 1 of 5 design intake that captures problem statement, audience, constraints, success metrics, and scope into .design/BRIEF.md, and bootstraps .design/STATE.md if missing. Use when starting a new design cycle and before /gdd:explore. Activates for requests involving capturing a problem statement, defining audience and constraints, or starting a new design brief."
 argument-hint: "[--re-brief to redo intake on existing project]"
 tools: Read, Write, AskUserQuestion, mcp__gdd_state__frontmatter_update, mcp__gdd_state__set_status, mcp__gdd_state__update_progress, mcp__gdd_state__get
 ---

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`."
+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."
 argument-hint: ""
 user-invocable: true
 ---

package/skills/connections/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-connections
-description: "Interactive onboarding wizard for the 33 external integrations the pipeline supports - probes all (`figma`, `refero`, `preview`, `storybook`, `chromatic`, `graphify`, `pinterest`, `claude-design`, `paper-design`, `pencil-dev`, `21st-dev`, `magic-patterns`, `lazyweb`, `mobbin`, `slack`, `discord`, `linear`, `jira`, `notion`, `lottie`, `rive`, `framer`, `penpot`, `webflow`, `v0-dev`, `plasmic`, `builder-io`, `launchdarkly`, `statsig`, `growthbook`, `usertesting`, `maze`, `hotjar`), recommends based on project type, walks the user through setup (auto-run MCP install or copy-command fallback), writes results to `STATE.md <connections>`. Use after `/gdd:new-project` or whenever the user wants to add, inspect, or skip a connection. Re-runnable anytime."
+description: "Interactive onboarding wizard for the 33 external integrations the pipeline supports - probes all (`figma`, `refero`, `preview`, `storybook`, `chromatic`, `graphify`, `pinterest`, `claude-design`, `paper-design`, `pencil-dev`, `21st-dev`, `magic-patterns`, `lazyweb`, `mobbin`, `slack`, `discord`, `linear`, `jira`, `notion`, `lottie`, `rive`, `framer`, `penpot`, `webflow`, `v0-dev`, `plasmic`, `builder-io`, `launchdarkly`, `statsig`, `growthbook`, `usertesting`, `maze`, `hotjar`), recommends based on project type, walks the user through setup (auto-run MCP install or copy-command fallback), writes results to `STATE.md <connections>`. Use after `/gdd:new-project` or whenever the user wants to add, inspect, or skip a connection. Re-runnable anytime. Activates for requests involving setting up external integrations, probing Figma or preview or storybook, or onboarding tools."
 argument-hint: "[list | <connection-name> | --auto]"
 user-invocable: true
 tools: Read, Write, Bash, Glob, Grep, AskUserQuestion, ToolSearch

package/skills/darkmode/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-darkmode
-description: "Audit a project's dark mode implementation - detects architecture (CSS custom props, Tailwind `dark:` prefix, or JS class toggle), runs architecture-specific contrast / token-override / anti-pattern / meta-property checks, and writes a prioritized fix list to `.design/DARKMODE-AUDIT.md`. Use when the user wants to verify dark mode quality without re-running the full design pipeline. Read-only - no score writeback to `DESIGN.md`."
+description: "Audit a project's dark mode implementation - detects architecture (CSS custom props, Tailwind `dark:` prefix, or JS class toggle), runs architecture-specific contrast / token-override / anti-pattern / meta-property checks, and writes a prioritized fix list to `.design/DARKMODE-AUDIT.md`. Use when the user wants to verify dark mode quality without re-running the full design pipeline. Read-only - no score writeback to `DESIGN.md`. Activates for requests involving auditing dark mode, checking dark-theme contrast, or dark-mode anti-patterns."
 argument-hint: ""
 user-invocable: true
 ---

package/skills/design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: design
-description: "Stage 4 of 5 orchestrator that reads DESIGN-PLAN.md, partitions tasks by wave + parallel-safe flag, and spawns design-executor agents with the appropriate isolation (worktree for parallel batches, in-place for sequential tail). Use when DESIGN-PLAN.md is approved and ready for implementation."
+description: "Stage 4 of 5 orchestrator that reads DESIGN-PLAN.md, partitions tasks by wave + parallel-safe flag, and spawns design-executor agents with the appropriate isolation (worktree for parallel batches, in-place for sequential tail). Use when DESIGN-PLAN.md is approved and ready for implementation. Activates for requests involving implementing UI, building components, or turning a plan into working interface code."
 argument-hint: "[--auto] [--parallel] [--variants N]"
 user-invocable: true
 tools: Read, Write, Bash, Grep, Glob, Task, AskUserQuestion, mcp__gdd_state__get, mcp__gdd_state__transition_stage, mcp__gdd_state__update_progress, mcp__gdd_state__set_status, mcp__gdd_state__add_blocker, mcp__gdd_state__resolve_blocker, mcp__gdd_state__checkpoint

package/skills/discover/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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 /gdd:scan when a fast-path context build is wanted instead of the full /gdd:explore."
+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 /gdd:scan when a fast-path context build is wanted instead of the full /gdd:explore. Activates for requests involving detecting an existing design system, inventorying tokens and components, or onboarding a brownfield repo."
 argument-hint: "[--auto]"
 user-invocable: true
 ---

package/skills/do/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-do
-description: "Natural-language design task router. Parses your intent, maps to the right gdd command(s), confirms before executing."
+description: "Natural-language design task router. Parses your intent, maps to the right gdd command(s), confirms before executing. Activates for requests involving a natural-language design request, routing intent to the right command, or not knowing which skill to use."
 argument-hint: "<natural language description>"
 tools: Read, Write, AskUserQuestion
 ---

package/skills/explore/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-explore
-description: "Stage 2 of 5 - unified exploration merging inventory grep + design interview. Probes 6 connections, scans the codebase, conducts the AskUserQuestion interview, and writes .design/DESIGN.md + DESIGN-DEBT.md + DESIGN-CONTEXT.md. Use after /gdd:brief to map the existing system and lock decisions before planning."
+description: "Stage 2 of 5 - unified exploration merging inventory grep + design interview. Probes 6 connections, scans the codebase, conducts the AskUserQuestion interview, and writes .design/DESIGN.md + DESIGN-DEBT.md + DESIGN-CONTEXT.md. Use after /gdd:brief to map the existing system and lock decisions before planning. Activates for requests involving researching design direction, gathering references, or exploring visual options."
 argument-hint: "[--skip-interview] [--skip-scan]"
 tools: Read, Write, Bash, Grep, Glob, Task, AskUserQuestion, mcp__gdd_state__get, mcp__gdd_state__transition_stage, mcp__gdd_state__probe_connections, mcp__gdd_state__update_progress, mcp__gdd_state__set_status, mcp__gdd_state__add_blocker, mcp__gdd_state__checkpoint, mcp__gdd_state__add_decision
 ---

package/skills/fast/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-fast
-description: "Trivial inline design task. No subagents, no planning documents, no pipeline stages. Just do the thing described."
+description: "Trivial inline design task. No subagents, no planning documents, no pipeline stages. Just do the thing described. Activates for requests involving a single quick design fix, a one-shot change, or a fast targeted edit."
 argument-hint: "<task description>"
 tools: Read, Write, Edit, Bash, Grep, Glob
 disable-model-invocation: true

package/skills/health/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-health
-description: "Reports .design/ artifact health - staleness, missing files, token drift, broken state transitions."
+description: "Reports .design/ artifact health - staleness, missing files, token drift, broken state transitions. Activates for requests involving checking .design artifact health, staleness, token drift, or broken state transitions."
 tools: Read, Bash, Glob, Grep, mcp__gdd_state__get
 disable-model-invocation: true
 ---
@@ -90,7 +90,7 @@ After the health table, surface the Phase 28.5 skill-authoring contract drift si
 - `Skill-length: <total> total | <clean> clean | <warnings> warn (>=100) | <blockers> block (>=250)`
 - If blockers > 0: list each blocker as a row `- <name> (<lines> lines)`. Else: print `All skills within contract.`
 
-Thresholds: warn >=100, block >=250 (D-01). Strict description-format off by default (D-02). See `./health-skill-length-report.md` for the JSON shape and threshold rationale.
+Thresholds: warn >=100, block >=250 (D-01). Strict description-format off by default (D-02). Then add two compact Phase 50 lines from `scripts/lib/manifest/skills.json`: `Skills: <n>/<total> in v3 description form` (descriptions matching `/Activates for requests involving/i`) and `Composition: <edges> edges | <cycles> cycles` (`composes_with`/`next_skills` fan-out; cycles via `scripts/validate-composition-graph.cjs` when present, else `0`). See `./health-skill-length-report.md` for the JSON shape and threshold rationale.
 
 ## Do Not
 

package/skills/live/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-live
-description: "Live in-browser design mode. The user picks a DOM element on a running dev server (via the Claude Preview MCP), the agent generates N design variants in one batch, they hot-swap in place through HMR or preview_eval using a data-gdd-variant marker, the user accepts or discards, and the whole pick-generate-accept loop persists to .design/live-sessions so it survives a crash or resume. Use when the user wants to iterate on the look of a live component against a real running server, asks to try variants on a page, or runs the live command with a url; falls back to a screenshot-only degraded mode on harnesses without MCP support."
+description: "Live in-browser design mode. The user picks a DOM element on a running dev server (via the Claude Preview MCP), the agent generates N design variants in one batch, they hot-swap in place through HMR or preview_eval using a data-gdd-variant marker, the user accepts or discards, and the whole pick-generate-accept loop persists to .design/live-sessions so it survives a crash or resume. Use when the user wants to iterate on the look of a live component against a real running server, asks to try variants on a page, or runs the live command with a url; falls back to a screenshot-only degraded mode on harnesses without MCP support. Activates for requests involving in-browser design iteration, picking an element on a dev server, or generating variants with hot-swap."
 argument-hint: "[--variants N] [--resume <session-id>] [url]"
 tools: Read, Write, Edit, Bash, Glob, Grep, Task
 user-invocable: true

package/skills/new-skill/SKILL.md

@@ -0,0 +1,90 @@
+---
+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."
+argument-hint: "<skill-name>"
+tools: Read, Write, Bash, AskUserQuestion
+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.
+
+Read `reference/skill-authoring-contract.md` first for the length cap, the frontmatter required fields, and the v3 description form.
+
+## Prompt strategy (clack with a fallback)
+
+Mirror the installer pattern in `scripts/install.cjs`: try `@clack/prompts` lazily, and degrade to `AskUserQuestion` (or plain text) when it is absent. Use this probe at the start:
+
+```bash
+node -e "try { require.resolve('@clack/prompts'); console.log('clack'); } catch { console.log('fallback'); }"
+```
+
+- `clack`: drive `clack.text`, `clack.select`, and `clack.confirm` from a short Node script.
+- `fallback`: ask the same questions with `AskUserQuestion` (one prompt per field), or read plain answers.
+
+Either way the answers feed the same record builder. Never block waiting on a TTY in a non-interactive run; fall back to `AskUserQuestion`.
+
+## 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.
+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.
+5. **composes_with**: auto-suggest neighbours, then confirm. Compute the suggestion list:
+
+```bash
+node -e "
+const s = require('./scripts/lib/manifest/scaffolder.cjs');
+const m = require('./scripts/lib/manifest/skills.json');
+console.log(JSON.stringify(s.suggestComposesWith(process.argv[1], m.skills)));
+" "<name>"
+```
+
+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.
+
+## Step 3 - Write the file
+
+Build the record and render the file with the pure generator, then write it with the Write tool (not shell redirection):
+
+```bash
+node -e "
+const s = require('./scripts/lib/manifest/scaffolder.cjs');
+const rec = s.buildSkillRecord({
+  name: process.env.SK_NAME,
+  description: process.env.SK_DESC,
+  argumentHint: process.env.SK_HINT || undefined,
+  tools: process.env.SK_TOOLS || undefined,
+  userInvocable: process.env.SK_UI === 'true',
+  composesWith: (process.env.SK_COMPOSES || '').split(',').map(x => x.trim()).filter(Boolean),
+});
+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.
+
+## Step 4 - Tell the user the follow-up
+
+The skill stops here by contract. Print the next two commands for the user to run after they add the manifest record:
+
+```
+1. Add a record for "<name>" to scripts/lib/manifest/skills.json
+   (description, argument_hint, tools, user_invocable; put composes_with in extra_frontmatter).
+2. npm run generate:skill-frontmatter && npm run build:skills
+```
+
+Note that `npm run generate:skill-frontmatter:check` and the skills-coverage test stay red until the manifest record exists; that is expected and is the maintainer's step.
+
+## Do Not
+
+- Do not edit `scripts/lib/manifest/skills.json`, `package.json`, or any reference doc.
+- Do not run `build:skills` or `generate:skill-frontmatter` for the user; print the commands.
+- Do not write the SKILL.md with shell redirection; use the Write tool so the content is exact.
+- Do not invent a description; require the v3 three-sentence form from the user.
+
+## NEW-SKILL COMPLETE

package/skills/plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: plan
-description: "Stage 3 of 5 orchestrator that reads DESIGN-CONTEXT.md, runs optional research (phase-researcher / pattern-mapper / assumptions-analyzer / synthesizer), spawns design-planner + design-plan-checker, and writes DESIGN-PLAN.md. Use when DESIGN-CONTEXT.md is locked and you need a wave-ordered execution plan."
+description: "Stage 3 of 5 orchestrator that reads DESIGN-CONTEXT.md, runs optional research (phase-researcher / pattern-mapper / assumptions-analyzer / synthesizer), spawns design-planner + design-plan-checker, and writes DESIGN-PLAN.md. Use when DESIGN-CONTEXT.md is locked and you need a wave-ordered execution plan. Activates for requests involving breaking design work into steps, sequencing implementation, or planning a build."
 argument-hint: "[--auto] [--parallel]"
 user-invocable: true
 tools: Read, Write, Bash, Glob, Task, AskUserQuestion, ToolSearch, mcp__gdd_state__get, mcp__gdd_state__transition_stage, mcp__gdd_state__add_decision, mcp__gdd_state__add_must_have, mcp__gdd_state__update_progress, mcp__gdd_state__set_status, mcp__gdd_state__add_blocker, mcp__gdd_state__checkpoint, mcp__gdd_state__probe_connections

package/skills/progress/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-progress
-description: "Shows current pipeline position and routes to next action. --forensic runs 6-check integrity audit."
+description: "Shows current pipeline position and routes to next action. --forensic runs 6-check integrity audit. Activates for requests involving showing current project state, routing to the next action, or a status check."
 argument-hint: "[--forensic]"
 tools: Read, Bash, Grep, Glob, mcp__gdd_state__get, mcp__gdd_status, mcp__gdd_phase_current
 ---
@@ -78,6 +78,14 @@ Seeds ready: 0
 ━━━━━━━━━━━━━━━━━━━━━━
 ```
 
+## Step 3.5 - Composition-graph readiness
+
+After the pipeline state (and forensic audit if run), surface a one-line composition-graph hint from `scripts/lib/manifest/skills.json`. Count skill records declaring `composes_with` or `next_skills`, then probe for structural problems (cycles in the directed graph, or edges pointing at a skill name that has no record). Print one line:
+
+- `Composition graph: <edges> edges, <skills-with-edges> skills wired | cycles: <n> | dangling: <n>`
+
+Run `scripts/validate-composition-graph.cjs` for the authoritative cycle and dangling-edge counts when that validator is present; until then report `0` and note the graph is not yet wired. This is a readiness hint, not a gate.
+
 ## Step 4 - Update notice (safe-window surface)
 
 After printing the pipeline state, emit the plugin-update banner if one is present. This file is written by `hooks/update-check.sh` subject to the state-machine guard (mid-pipeline stages suppress it) and per-version dismissal.

package/skills/quick/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-quick
-description: "Run the pipeline with optional agents skipped for speed. Skips: phase-researcher, design-assumptions-analyzer, design-integration-checker. Keeps: planner, executor, verifier, auditor."
+description: "Run the pipeline with optional agents skipped for speed. Skips: phase-researcher, design-assumptions-analyzer, design-integration-checker. Keeps: planner, executor, verifier, auditor. Activates for requests involving a lightweight design pass, a fast iteration, or a quick low-ceremony change."
 argument-hint: "[--skip <agent-name>] [stage]"
 tools: Read, Task
 disable-model-invocation: true