@hegemonart/get-design-done 1.48.0 → 1.50.0

package/scripts/lib/manifest/scaffolder.cjs

@@ -0,0 +1,261 @@
+'use strict';
+/**
+ * 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
+ * prompts; this module is the deterministic core it (and the test suite) call.
+ *
+ * Exports:
+ *   buildSkillRecord({ name, description, argumentHint, tools, userInvocable,
+ *     composesWith }) -> a skills.json record object. Validates the name slug,
+ *     the v3 description budget (20..1024 chars), and the comma-separated tools
+ *     list. Throws on invalid input.
+ *   renderSkillMd(record) -> the SKILL.md template string (frontmatter in the
+ *     same canonical key order as generate-skill-frontmatter.cjs + a minimal
+ *     body skeleton with the standard sections).
+ *   suggestComposesWith(name, allSkills) -> heuristic composition suggestions
+ *     (skills sharing a lifecycle-stage keyword with the new skill name).
+ *
+ * Dependency-free of any third party. It DOES reuse the in-repo
+ * generate-skill-frontmatter.cjs `frontmatterFromRecord` emitter so the
+ * rendered frontmatter is a byte-for-byte fixed point with the forward
+ * generator (description quoted, canonical key order, name leads).
+ */
+
+const path = require('node:path');
+
+// Reuse the canonical frontmatter emitter so renderSkillMd stays compatible
+// with `npm run generate:skill-frontmatter` (same quoting + key order).
+const { frontmatterFromRecord } = require(
+  path.join(__dirname, '..', '..', 'generate-skill-frontmatter.cjs'),
+);
+
+// Slug rule mirrors reference/skill-authoring-contract.md `## Frontmatter`:
+// kebab-case identifier matching ^[a-z0-9][a-z0-9-._]*$.
+const NAME_RE = /^[a-z0-9][a-z0-9-._]*$/;
+
+// Description budget mirrors the Phase 28.5 contract (D-02) + skills.schema.json:
+// 20..1024 chars. The v3 "Activates for requests involving X, Y, Z." sentence
+// is recommended (LAX by default) but not regex-enforced here.
+const DESC_MIN = 20;
+const DESC_MAX = 1024;
+
+// Lifecycle-stage keyword groups used by suggestComposesWith. Skills whose
+// name shares a group with the new skill name are plausible composition
+// neighbours. Kept deliberately small and dependency-free; the SKILL.md treats
+// the result as a suggestion the user confirms, never an autowire.
+const STAGE_GROUPS = [
+  ['brief', 'intake', 'start', 'new-project', 'new-cycle'],
+  ['explore', 'discover', 'discuss', 'sketch', 'spike', 'map'],
+  ['plan', 'planning', 'design', 'do', 'build'],
+  ['verify', 'audit', 'review', 'quality-gate', 'check'],
+  ['ship', 'pr', 'complete', 'closeout', 'rollout'],
+  ['figma', 'extract', 'export', 'import', 'sync'],
+  ['token', 'tokens', 'darkmode', 'style', 'theme'],
+  ['health', 'progress', 'stats', 'report', 'timeline'],
+];
+
+function fail(msg) {
+  throw new Error(`scaffolder: ${msg}`);
+}
+
+/** Normalize a tools input (string or array) to a clean comma-list string. */
+function normalizeTools(tools) {
+  if (tools == null) return undefined;
+  let parts;
+  if (Array.isArray(tools)) {
+    parts = tools;
+  } else if (typeof tools === 'string') {
+    parts = tools.split(',');
+  } else {
+    fail('tools must be a comma-separated string or an array of tool names');
+  }
+  const cleaned = parts.map((t) => String(t).trim()).filter(Boolean);
+  if (cleaned.length === 0) fail('tools, when provided, must name at least one tool');
+  // Each token: a Tool name or an mcp__* identifier. No commas, no empty.
+  // `\w` already includes `_`, so a single `[\w-]*` class matches plain names
+  // (Read) AND mcp__* identifiers (mcp__gdd_state__get) in linear time. The old
+  // `(__[\w-]+)*` suffix overlapped `[\w-]*` and caused exponential backtracking
+  // (CodeQL js/redos) on inputs like `A__-__-__...`; it was redundant. Removed.
+  for (const t of cleaned) {
+    if (!/^[A-Za-z][\w-]*$/.test(t)) {
+      fail(`tools entry "${t}" is not a valid tool identifier`);
+    }
+  }
+  return cleaned.join(', ');
+}
+
+/** Normalize a composes_with input (string or array) to a slug array. */
+function normalizeComposesWith(composesWith) {
+  if (composesWith == null) return undefined;
+  let parts;
+  if (Array.isArray(composesWith)) parts = composesWith;
+  else if (typeof composesWith === 'string') parts = composesWith.split(',');
+  else fail('composesWith must be an array or comma-separated string of skill names');
+  const cleaned = parts.map((s) => String(s).trim()).filter(Boolean);
+  if (cleaned.length === 0) return undefined;
+  for (const s of cleaned) {
+    if (!NAME_RE.test(s)) fail(`composesWith entry "${s}" is not a valid skill slug`);
+  }
+  // De-dupe, preserve first-seen order.
+  return [...new Set(cleaned)];
+}
+
+/**
+ * Build a skills.json record object from scaffolder inputs.
+ * Keys are inserted in the canonical emit order so frontmatterFromRecord
+ * produces the same byte layout generate-skill-frontmatter.cjs would.
+ * @throws on an invalid name, out-of-budget description, or malformed tools.
+ */
+function buildSkillRecord(input) {
+  const opts = input || {};
+  const name = typeof opts.name === 'string' ? opts.name.trim() : opts.name;
+  if (!name || typeof name !== 'string') fail('name is required (a kebab-case slug)');
+  if (!NAME_RE.test(name)) {
+    fail(`name "${name}" must match ${NAME_RE} (lower-case, starts alnum, kebab/dot/underscore)`);
+  }
+
+  const description = typeof opts.description === 'string' ? opts.description.trim() : opts.description;
+  if (!description || typeof description !== 'string') fail('description is required');
+  if (description.length < DESC_MIN) {
+    fail(`description is ${description.length} chars; require >=${DESC_MIN}`);
+  }
+  if (description.length > DESC_MAX) {
+    fail(`description is ${description.length} chars; require <=${DESC_MAX}`);
+  }
+
+  // Insertion order == canonical managed-key emit order (name leads in the
+  // emitter; the rest follow record insertion order).
+  const rec = { name, description };
+
+  const argumentHint = opts.argumentHint != null ? String(opts.argumentHint) : undefined;
+  if (argumentHint !== undefined) rec.argument_hint = argumentHint;
+
+  const tools = normalizeTools(opts.tools);
+  if (tools !== undefined) rec.tools = tools;
+
+  if (opts.userInvocable !== undefined) rec.user_invocable = Boolean(opts.userInvocable);
+
+  const composesWith = normalizeComposesWith(opts.composesWith);
+  if (composesWith !== undefined) rec.composes_with = composesWith;
+
+  return rec;
+}
+
+/**
+ * Render the SKILL.md template string for a record.
+ * Frontmatter is emitted via the shared generate-skill-frontmatter emitter so
+ * it is a fixed point with the forward generator. composes_with (a Phase 50
+ * field not yet in the emitter's MANAGED set) is appended as an explicit
+ * frontmatter line; `--extract` carries it verbatim in extra_frontmatter.
+ */
+function renderSkillMd(record) {
+  if (!record || typeof record !== 'object') fail('renderSkillMd requires a record object');
+  // Validate/normalize defensively so renderSkillMd(buildSkillRecord(x)) and
+  // renderSkillMd(rawObject) both produce a contract-valid file.
+  const rec = buildSkillRecord({
+    name: record.name,
+    description: record.description,
+    argumentHint: record.argument_hint,
+    tools: record.tools,
+    userInvocable: record.user_invocable,
+    composesWith: record.composes_with,
+  });
+
+  // Separate composes_with: the shared emitter only knows the MANAGED keys, so
+  // composes_with rides as an extra_frontmatter line (the round-trip home the
+  // forward generator already uses for non-managed keys).
+  const composesWith = rec.composes_with;
+  const emitRec = { ...rec };
+  delete emitRec.composes_with;
+  if (composesWith && composesWith.length) {
+    emitRec.extra_frontmatter = [`composes_with: [${composesWith.join(', ')}]`];
+  }
+
+  const frontmatter = frontmatterFromRecord(emitRec);
+  const prefix = '{{command_prefix}}';
+  const upper = rec.name.toUpperCase();
+
+  const body = [
+    '',
+    `# ${prefix}${rec.name}`,
+    '',
+    `**Role:** ${rec.description.split('. ')[0]}.`,
+    '',
+    '## Steps',
+    '',
+    '1. State the preconditions this skill needs (read `.design/STATE.md` if relevant).',
+    '2. Do the work. Keep each step a single concrete action.',
+    '3. Report the result and recommend the next action.',
+    '',
+    '## Output',
+    '',
+    '```',
+    `${prefix}${rec.name} result summary goes here.`,
+    '```',
+    '',
+    '## Do Not',
+    '',
+    '- Do not exceed the authoring-contract length cap (warn at 100 lines).',
+    '- Do not invent state; read it from `.design/`.',
+    '',
+    `## ${upper} COMPLETE`,
+    '',
+  ].join('\n');
+
+  return `---\n${frontmatter}\n---\n${body}`;
+}
+
+/**
+ * Heuristic composition suggestions for a new skill.
+ * Returns skill names from `allSkills` that share a lifecycle-stage keyword
+ * with `name` (or whose name substring-matches a shared stage token). The
+ * new skill itself is never suggested. Order: stable by allSkills order.
+ * @param {string} name new skill slug
+ * @param {Array<string|{name:string}>} allSkills existing skills (names or records)
+ * @returns {string[]} suggested composition neighbours (possibly empty)
+ */
+function suggestComposesWith(name, allSkills) {
+  if (!name || typeof name !== 'string') return [];
+  const self = name.trim().toLowerCase();
+  const names = (Array.isArray(allSkills) ? allSkills : [])
+    .map((s) => (typeof s === 'string' ? s : s && s.name))
+    .filter((n) => typeof n === 'string' && n.trim() && n.trim().toLowerCase() !== self)
+    .map((n) => n.trim());
+
+  // Which stage groups does the new skill touch?
+  const tokensOf = (slug) => slug.toLowerCase().split(/[-._]/).filter(Boolean);
+  const selfTokens = new Set(tokensOf(self));
+  const selfGroups = new Set();
+  STAGE_GROUPS.forEach((group, idx) => {
+    if (group.some((kw) => selfTokens.has(kw) || self.includes(kw))) selfGroups.add(idx);
+  });
+
+  if (selfGroups.size === 0) return [];
+
+  const seen = new Set();
+  const out = [];
+  for (const candidate of names) {
+    if (seen.has(candidate)) continue;
+    const cTokens = new Set(tokensOf(candidate));
+    const inGroup = [...selfGroups].some((idx) =>
+      STAGE_GROUPS[idx].some((kw) => cTokens.has(kw) || candidate.toLowerCase().includes(kw)),
+    );
+    if (inGroup) {
+      out.push(candidate);
+      seen.add(candidate);
+    }
+  }
+  return out;
+}
+
+module.exports = {
+  buildSkillRecord,
+  renderSkillMd,
+  suggestComposesWith,
+  NAME_RE,
+  DESC_MIN,
+  DESC_MAX,
+  STAGE_GROUPS,
+};

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

@@ -60,6 +60,20 @@
             },
             "description": "Reserved for pin shortcuts; honored by the pin metadata catalogue."
           },
+          "composes_with": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Phase 50 (v3) optional: skill names this skill calls as sub-orchestration. Each becomes a directed composition edge validated by scripts/validate-composition-graph.cjs (must be a DAG, no dangling refs)."
+          },
+          "next_skills": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Phase 50 (v3) optional: pipeline hint listing skill names that naturally run after this one. Each becomes a directed edge in the composition graph (DAG, no dangling refs)."
+          },
           "extra_frontmatter": {
             "type": "array",
             "items": {

package/scripts/lib/manifest/skills.json

@@ -22,7 +22,7 @@
     },
     {
       "name": "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"
     },
@@ -47,7 +47,7 @@
     },
     {
       "name": "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 {{command_prefix}}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 {{command_prefix}}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"
     },
@@ -73,7 +73,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`.",
+      "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
     },
@@ -85,7 +85,7 @@
     },
     {
       "name": "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 `{{command_prefix}}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 `{{command_prefix}}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"
@@ -99,7 +99,7 @@
     },
     {
       "name": "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
     },
@@ -112,7 +112,7 @@
     {
       "name": "design",
       "frontmatter_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"
@@ -120,7 +120,7 @@
     {
       "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.",
+      "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]",
       "user_invocable": true
     },
@@ -132,13 +132,13 @@
     },
     {
       "name": "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"
     },
     {
       "name": "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 {{command_prefix}}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 {{command_prefix}}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"
     },
@@ -156,7 +156,7 @@
     },
     {
       "name": "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
@@ -175,7 +175,7 @@
     },
     {
       "name": "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
     },
@@ -200,7 +200,7 @@
     },
     {
       "name": "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,
@@ -239,6 +239,14 @@
       "argument_hint": "[--name <project-name>]",
       "tools": "Read, Write, AskUserQuestion, Bash, Glob"
     },
+    {
+      "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.",
+      "argument_hint": "<skill-name>",
+      "tools": "Read, Write, Bash, AskUserQuestion",
+      "user_invocable": true,
+      "registered_in_phase": "50"
+    },
     {
       "name": "next",
       "description": "Routes to the next pipeline stage based on current STATE.md position",
@@ -304,7 +312,7 @@
     {
       "name": "plan",
       "frontmatter_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"
@@ -325,7 +333,7 @@
     },
     {
       "name": "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"
     },
@@ -349,7 +357,7 @@
     },
     {
       "name": "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
@@ -424,7 +432,7 @@
     {
       "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.",
+      "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
     },
@@ -437,7 +445,7 @@
     },
     {
       "name": "ship",
-      "description": "Post-verify PR flow - creates a clean PR branch, invokes code review check, and prepares the PR for merge.",
+      "description": "Post-verify PR flow - creates a clean PR branch, invokes code review check, and prepares the PR for merge. Activates for requests involving finishing a cycle, packaging design output, or moving work to a pull request.",
       "argument_hint": "[--title <PR title>] [--draft]",
       "tools": "Read, Write, Bash, AskUserQuestion, Task",
       "disable_model_invocation": true
@@ -556,7 +564,7 @@
     {
       "name": "verify",
       "frontmatter_name": "verify",
-      "description": "Stage 5 of 5 orchestrator that spawns design-auditor, design-verifier, and design-integration-checker in sequence, interprets pass/gap result, and drives the gap-response loop (inline fix, save-and-exit, or accept-as-is). Use when implementation is complete and ready for final pre-ship verification.",
+      "description": "Stage 5 of 5 orchestrator that spawns design-auditor, design-verifier, and design-integration-checker in sequence, interprets pass/gap result, and drives the gap-response loop (inline fix, save-and-exit, or accept-as-is). Use when implementation is complete and ready for final pre-ship verification. Activates for requests involving checking finished UI against the design system, running a pre-ship review, or final verification.",
       "argument_hint": "[--auto] [--post-handoff]",
       "user_invocable": true,
       "tools": "mcp__gdd_state__get, mcp__gdd_state__transition_stage, mcp__gdd_state__add_must_have, mcp__gdd_state__add_blocker, mcp__gdd_state__resolve_blocker, mcp__gdd_state__update_progress, mcp__gdd_state__set_status, mcp__gdd_state__checkpoint, mcp__gdd_state__probe_connections"