@hegemonart/get-design-done 1.28.0 → 1.28.6

package/scripts/validate-skill-length.cjs

@@ -0,0 +1,283 @@
+#!/usr/bin/env node
+'use strict';
+/**
+ * scripts/validate-skill-length.cjs — Phase 28.5 skill-authoring-contract validator.
+ *
+ * Walks skills/, validates per D-01/D-02/D-09/D-11:
+ *   - Frontmatter required: name, description
+ *   - description length: 20 <= len <= 1024 chars (always strict)
+ *   - description format (--strict-description / STRICT_DESCRIPTION=1):
+ *     regex `\. Use when .+\.$` (advisory by default per D-02)
+ *   - SKILL.md lines: >=250 block, >=100 warn (D-01)
+ *   - disable-model-invocation: only on D-09 whitelist
+ *
+ * Exit codes:
+ *   0  clean (no warnings, no blockers)
+ *   1  warnings only (>=100 lines but <250 on at least one skill, no other failures)
+ *   2  blockers present (>=250 lines, frontmatter missing/invalid, description out of range, etc.)
+ *
+ * CLI flags:
+ *   --quiet               Suppress per-skill output, print summary only.
+ *   --strict-description  Enforce `<what>. Use when <triggers>.` regex on description.
+ *   --json                Emit machine-readable JSON instead of human-readable text.
+ *   --help, -h            Print this usage message.
+ *
+ * Env:
+ *   STRICT_DESCRIPTION=1  Equivalent to --strict-description.
+ *   SKILLS_DIR=<path>     Override skills directory (default: ./skills relative to cwd).
+ *
+ * See reference/skill-authoring-contract.md for the full contract.
+ *
+ * Line counting: counts every line in the file via split on /\r?\n/ and drops a single
+ * trailing empty entry — matches `wc -l` semantics. We count ALL lines (including blanks
+ * and comments) because that is what consumes agent context. This mirrors the same
+ * counting convention used by tests/agent-size-budget.test.cjs.
+ *
+ * Validator does NOT enforce skill renames (D-05/D-07) — frontmatter.name is checked for
+ * presence only, never compared against a canonical-name list. Whitelist key for
+ * disable-model-invocation uses the skill folder name (skills/<dir>/SKILL.md), not the
+ * frontmatter.name field.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const WARN_LINES = 100;
+const BLOCK_LINES = 250;
+const DESC_MIN = 20;
+const DESC_MAX = 1024;
+// Strict-mode regex: trailing ". Use when <something>." sentence.
+// Multiline + non-greedy to tolerate descriptions split across YAML lines.
+const STRICT_RE = /\. Use when .+\.\s*$/m;
+
+// D-09 whitelist — skills permitted to set disable-model-invocation: true.
+// Keyed on skill folder name (skills/<folder>/SKILL.md), not frontmatter.name.
+const DISABLE_INVOCATION_WHITELIST = new Set([
+  'help', 'stats', 'note', 'add-backlog', 'todo', 'health', 'settings',
+  'next', 'pause', 'resume', 'fast', 'quick', 'pr-branch', 'ship',
+  'reapply-patches', 'list-assumptions', 'plant-seed', 'review-backlog',
+  'cache-manager', 'warm-cache', 'synthesize', 'timeline', 'start',
+  'recall', 'continue', 'update', 'undo', 'zoom-out',
+]);
+
+function parseArgs(argv) {
+  const flags = { quiet: false, strict: false, json: false };
+  for (const a of argv.slice(2)) {
+    if (a === '--quiet') flags.quiet = true;
+    else if (a === '--strict-description') flags.strict = true;
+    else if (a === '--json') flags.json = true;
+    else if (a === '--help' || a === '-h') { printHelp(); process.exit(0); }
+    else { process.stderr.write(`unknown flag: ${a}\n`); process.exit(2); }
+  }
+  if (process.env.STRICT_DESCRIPTION === '1') flags.strict = true;
+  return flags;
+}
+
+function printHelp() {
+  process.stdout.write([
+    'validate-skill-length.cjs — Phase 28.5 skill-authoring-contract validator',
+    '',
+    'Usage: node scripts/validate-skill-length.cjs [--quiet] [--strict-description] [--json]',
+    '',
+    'Flags:',
+    '  --quiet               Suppress per-skill output, print summary only.',
+    '  --strict-description  Enforce `<what>. Use when <triggers>.` regex on description.',
+    '  --json                Emit machine-readable JSON.',
+    '  --help, -h            Show this message.',
+    '',
+    'Env:',
+    '  STRICT_DESCRIPTION=1  Equivalent to --strict-description.',
+    '  SKILLS_DIR=<path>     Override skills directory (default: ./skills).',
+    '',
+    'Exit codes: 0=clean, 1=warnings only, 2=blockers present.',
+    '',
+    'See reference/skill-authoring-contract.md for the full contract.',
+    '',
+  ].join('\n'));
+}
+
+function parseFrontmatter(content) {
+  if (!content.startsWith('---\n') && !content.startsWith('---\r\n')) {
+    return { ok: false, error: 'missing-frontmatter' };
+  }
+  // Find the closing `\n---` after the opening one.
+  const end = content.indexOf('\n---', 4);
+  if (end < 0) return { ok: false, error: 'unterminated-frontmatter' };
+  const block = content.slice(4, end);
+  const fields = {};
+  const lines = block.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const m = line.match(/^([a-zA-Z][a-zA-Z0-9_-]*):\s*(.*)$/);
+    if (m) {
+      let value = m[2];
+      // Strip wrapping quotes (single or double).
+      if (value.length >= 2 &&
+          ((value.startsWith('"') && value.endsWith('"')) ||
+           (value.startsWith("'") && value.endsWith("'")))) {
+        value = value.slice(1, -1);
+      }
+      // Multi-line description folding: when description: is followed by empty value,
+      // gather continuation lines until the next `key:` line.
+      if (m[1] === 'description' && value === '') {
+        const parts = [];
+        for (let j = i + 1; j < lines.length; j++) {
+          if (/^[a-zA-Z][a-zA-Z0-9_-]*:/.test(lines[j])) break;
+          parts.push(lines[j].trim());
+        }
+        value = parts.join(' ').trim();
+      }
+      fields[m[1]] = value;
+    }
+  }
+  return { ok: true, fields, bodyStart: end + 4 };
+}
+
+function countLines(content) {
+  if (!content) return 0;
+  const lines = content.split(/\r?\n/);
+  // wc -l semantics: drop a single trailing empty entry (the newline-terminated final line).
+  if (lines[lines.length - 1] === '') lines.pop();
+  return lines.length;
+}
+
+function validateSkill(skillName, skillPath, flags) {
+  const result = {
+    name: skillName,
+    path: skillPath,
+    lines: 0,
+    descriptionLength: 0,
+    hasRequiredFields: false,
+    level: 'clean',
+    errors: [],
+    warnings: [],
+    reasons: [],
+  };
+  let content;
+  try {
+    content = fs.readFileSync(skillPath, 'utf8');
+  } catch (e) {
+    result.errors.push({ code: 'read-failed', message: e.message });
+    result.level = 'block';
+    result.reasons.push(`read-failed: ${e.message}`);
+    return result;
+  }
+  result.lines = countLines(content);
+
+  const fm = parseFrontmatter(content);
+  if (!fm.ok) {
+    result.errors.push({ code: 'frontmatter', message: fm.error });
+    result.reasons.push(`frontmatter: ${fm.error}`);
+    result.level = 'block';
+    return result;
+  }
+  const hasName = Boolean(fm.fields.name);
+  const hasDesc = Boolean(fm.fields.description);
+  result.hasRequiredFields = hasName && hasDesc;
+  if (!hasName) {
+    result.errors.push({ code: 'missing-name', message: 'frontmatter.name required' });
+    result.reasons.push('missing-name');
+  }
+  if (!hasDesc) {
+    result.errors.push({ code: 'missing-description', message: 'frontmatter.description required' });
+    result.reasons.push('missing-description');
+  } else {
+    const d = fm.fields.description;
+    result.descriptionLength = d.length;
+    if (d.length < DESC_MIN) {
+      result.errors.push({ code: 'description-too-short', message: `${d.length} chars; require >=${DESC_MIN}` });
+      result.reasons.push(`description-too-short: ${d.length}`);
+    }
+    if (d.length > DESC_MAX) {
+      result.errors.push({ code: 'description-too-long', message: `${d.length} chars; require <=${DESC_MAX}` });
+      result.reasons.push(`description-too-long: ${d.length}`);
+    }
+    if (flags.strict && !STRICT_RE.test(d)) {
+      result.errors.push({ code: 'description-format', message: 'strict mode: missing ". Use when <triggers>." suffix' });
+      result.reasons.push('description-format');
+    }
+  }
+  const dmi = fm.fields['disable-model-invocation'];
+  if (dmi !== undefined) {
+    if (dmi !== 'true' && dmi !== 'false') {
+      // Tolerate quoted "true"/"false" — parseFrontmatter strips quotes.
+      // Any other shape (e.g. raw "True", "yes") is a block.
+      result.errors.push({ code: 'disable-model-invocation-shape', message: `disable-model-invocation must be the boolean true|false, got "${dmi}"` });
+      result.reasons.push(`disable-model-invocation-shape: ${dmi}`);
+    } else if (dmi === 'true' && !DISABLE_INVOCATION_WHITELIST.has(skillName)) {
+      result.errors.push({ code: 'disable-model-invocation', message: `${skillName} not on D-09 whitelist` });
+      result.reasons.push('disable-model-invocation-not-whitelisted');
+    }
+  }
+  if (result.lines >= BLOCK_LINES) {
+    result.errors.push({ code: 'block-lines', message: `${result.lines} lines; block threshold ${BLOCK_LINES}` });
+    result.reasons.push(`block-lines: ${result.lines}`);
+  } else if (result.lines >= WARN_LINES) {
+    result.warnings.push({ code: 'warn-lines', message: `${result.lines} lines; warn threshold ${WARN_LINES}` });
+    result.reasons.push(`warn-lines: ${result.lines}`);
+  }
+  if (result.errors.length > 0) result.level = 'block';
+  else if (result.warnings.length > 0) result.level = 'warn';
+  else result.level = 'clean';
+  return result;
+}
+
+function walkSkills(skillsDir) {
+  if (!fs.existsSync(skillsDir)) return [];
+  const out = [];
+  for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const skillFile = path.join(skillsDir, entry.name, 'SKILL.md');
+    if (fs.existsSync(skillFile)) out.push({ name: entry.name, path: skillFile });
+  }
+  return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function main() {
+  const flags = parseArgs(process.argv);
+  const root = process.cwd();
+  const skillsDir = process.env.SKILLS_DIR || path.join(root, 'skills');
+  const skills = walkSkills(skillsDir);
+  const results = skills.map(s => validateSkill(s.name, s.path, flags));
+
+  const summary = {
+    total: results.length,
+    clean: results.filter(r => r.level === 'clean').length,
+    warnings: results.filter(r => r.level === 'warn').length,
+    blockers: results.filter(r => r.level === 'block').length,
+  };
+
+  if (flags.json) {
+    process.stdout.write(JSON.stringify({ summary, skills: results }, null, 2) + '\n');
+  } else {
+    if (!flags.quiet) {
+      for (const r of results) {
+        if (r.level === 'clean') continue;
+        process.stdout.write(`${r.name} (${r.lines} lines):\n`);
+        for (const e of r.errors) process.stdout.write(`  BLOCK ${e.code}: ${e.message}\n`);
+        for (const w of r.warnings) process.stdout.write(`  WARN  ${w.code}: ${w.message}\n`);
+      }
+    }
+    process.stdout.write(`\nSummary: ${summary.total} skills | ${summary.clean} clean | ${summary.warnings} warn | ${summary.blockers} block\n`);
+  }
+
+  if (summary.blockers > 0) process.exit(2);
+  if (summary.warnings > 0) process.exit(1);
+  process.exit(0);
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  parseFrontmatter,
+  countLines,
+  validateSkill,
+  walkSkills,
+  parseArgs,
+  DISABLE_INVOCATION_WHITELIST,
+  WARN_LINES,
+  BLOCK_LINES,
+  DESC_MIN,
+  DESC_MAX,
+  STRICT_RE,
+};

package/skills/add-backlog/SKILL.md

@@ -3,6 +3,7 @@ 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

package/skills/analyze-dependencies/SKILL.md

@@ -6,17 +6,17 @@ tools: Bash, Read, Glob, Grep
 
 # /gdd:analyze-dependencies
 
-**Role:** Surface dependency relationships, token usage spread, component graphs, and decision traceability using the `.design/intel/` store. No file greps — all queries are O(1) reads against pre-built JSON slices.
+**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 check
+## Pre-flight
 
-Before any analysis, verify the intel store exists:
+Verify the intel store exists:
 
 ```bash
 ls .design/intel/files.json 2>/dev/null && echo "ready" || echo "missing"
 ```
 
-If missing: print the following and stop:
+If missing, print:
 
 ```
 Intel store not found. Build it first:
@@ -26,145 +26,56 @@ 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
+- `/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
 
-**What:** Which design tokens are referenced in the most files? Which are orphaned (defined but never used)?
+Surfaces tokens referenced in many files + orphans (referenced exactly once).
 
-**Protocol:**
+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).
 
-1. Read `.design/intel/tokens.json`
-2. Group entries by `token` value
-3. Count distinct `file` values per token
-4. Sort descending by file count
-5. Print top-20 most-referenced tokens:
-
-```
-━━━ Token fan-out ━━━
-Token                        Files  Category
---color-primary              12     color
---space-4                    9      spacing
---font-size-body             7      typography
-...
-(top 20 shown)
-
-Orphaned tokens (referenced in exactly 1 file):
-  --shadow-card-hover (skills/design/SKILL.md:44)
-━━━━━━━━━━━━━━━━━━━━━
-```
+Header: `━━━ Token fan-out ━━━` … `(top 20 shown)` … `Orphaned tokens (referenced in exactly 1 file):` … footer rule.
 
 ## Analysis 2 — Component call-graph
 
-**What:** Which components are referenced most widely? Which files reference a given component?
-
-**Protocol:**
+Surfaces widely-referenced components and the files referencing each.
 
-1. Read `.design/intel/components.json`
-2. Group by `component` name
-3. Count distinct `file` values per component
-4. Sort descending by reference count
-5. Print top-20 most-referenced components with their source files:
+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).
 
-```
-━━━ Component call-graph ━━━
-Component      References  Files
-Button         14          skills/design/SKILL.md, agents/design-executor.md, ...
-Card           9           skills/verify/SKILL.md, reference/heuristics.md, ...
-...
-(top 20 shown)
-━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-If a specific component name is passed as a second argument (e.g., `/gdd:analyze-dependencies components Button`), show only that component's referencing files, one per line.
+Header: `━━━ Component call-graph ━━━` … footer rule.
 
 ## Analysis 3 — Decision traceability
 
-**What:** Which decisions from DESIGN-CONTEXT.md are referenced by which skill/agent files?
-
-**Protocol:**
+Maps decisions to skill/agent files that cite them.
 
-1. Read `.design/intel/decisions.json` to get known decision IDs (D-01, D-02, ...)
-2. Read `.design/intel/symbols.json` to find files that contain decision headings
-3. Read `.design/intel/dependencies.json` for @-reference chains
-4. For each decision in decisions.json, grep the intel store's files index:
-
-```bash
-grep -r "D-[0-9][0-9]*" .design/intel/decisions.json | head -20
-```
-
-5. Cross-reference with which skill/agent files cite that decision ID (look in symbols.json for heading anchors matching decision patterns)
-
-6. Print:
-
-```
-━━━ Decision traceability ━━━
-D-01  Use Figma MCP for token extraction
-      Referenced by: skills/scan/SKILL.md:12, agents/design-executor.md:7
+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`.
 
-D-02  Merge-not-replace pattern for Figma tokens
-      Referenced by: (no explicit references found)
-
-Total: 3 decisions tracked, 2 with file references
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-If `.design/intel/decisions.json` contains no entries (e.g., no DESIGN-CONTEXT.md exists yet), print:
-```
-No decisions indexed. Run node scripts/build-intel.cjs after creating .design/DESIGN-CONTEXT.md.
-```
+Empty-state: `No decisions indexed. Run node scripts/build-intel.cjs after creating .design/DESIGN-CONTEXT.md.`
 
 ## Analysis 4 — Circular dependency detection
 
-**What:** Detect cycles in the `@`-reference graph (File A -> File B -> File A).
-
-**Protocol:**
-
-1. Read `.design/intel/graph.json`
-2. Build an adjacency map from `edges` array: `{ from -> [to, to, ...] }`
-3. Run depth-first search with path tracking to detect back-edges (cycles)
-4. Algorithm:
-
-```
-visited = {}
-path = []
-cycles = []
-
-function dfs(node):
-  if node in path:
-    cycle_start = path.index(node)
-    cycles.append(path[cycle_start:] + [node])
-    return
-  if node in visited: return
-  visited.add(node)
-  path.append(node)
-  for neighbor in adjacency[node]:
-    dfs(neighbor)
-  path.pop()
-```
-
-5. Print detected cycles (or "No circular dependencies detected"):
-
-```
-━━━ Circular dependency detection ━━━
-Cycle 1:
-  skills/verify/SKILL.md
-  -> reference/accessibility.md
-  -> skills/verify/SKILL.md   <- CYCLE
-
-Total cycles: 1
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
+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".
 
-If no cycles: `All clear — no circular dependencies detected.`
+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 format
+## Combined report
 
-When run without a mode argument, print all four analyses in sequence separated by blank lines. Prefix the overall report with:
+When run without a mode argument, print all four analyses in sequence separated by blank lines, prefixed with:
 
 ```
 ━━━ Dependency Analysis ━━━

package/skills/apply-reflections/SKILL.md

@@ -52,46 +52,7 @@ Based on user choice:
 
 ### 4. Apply Logic by Proposal Type
 
-#### [FRONTMATTER]
-1. Extract agent name from Change field (e.g., `agents/design-verifier.md`)
-2. Read the agent file
-3. Find the frontmatter line matching the field being changed
-4. Use Edit tool to update the specific line
-5. Append `**Applied**: <date>` to the proposal in reflections file
-
-#### [REFERENCE]
-1. Extract target file path from Change field (e.g., `reference/heuristics.md`)
-2. If file exists: append the drafted text using Edit tool
-3. If file doesn't exist: create it with a minimal header + the drafted text using Write tool
-4. Append `**Applied**: <date>` to proposal in reflections file
-
-#### [BUDGET]
-1. Read `.design/budget.json`
-2. Locate the key path from the Change field (e.g., `design-verifier.per_run_cap_usd`)
-3. Update the value
-4. Write updated JSON back to `.design/budget.json`
-5. Append `**Applied**: <date>` to proposal in reflections file
-
-#### [QUESTION]
-1. Read `agents/design-discussant.md`
-2. Find the question text specified in the Change field
-3. If pruning: remove the question lines using Edit tool
-4. If rewording: replace the question text using Edit tool
-5. Append `**Applied**: <date>` to proposal in reflections file
-
-#### [GLOBAL-SKILL]
-1. Extract target filename from Change field (e.g., `design-color-conventions.md`)
-2. Ensure `~/.claude/gdd/global-skills/` directory exists (create with `mkdir -p` if not)
-3. If target file exists: append new content using Edit tool (add a `---` separator first)
-4. If target file doesn't exist: create with header + content using Write tool:
-   ```markdown
-   # <Topic> Conventions (Global)
-   *Promoted from project: <project-name>, cycle: <cycle-slug>*
-
-   <content>
-   ```
-5. Print: "Global skill written to ~/.claude/gdd/global-skills/<name>.md — auto-loads in all future gdd sessions"
-6. Append `**Applied**: <date>` to proposal in reflections file
+After the user chooses `a` (apply) or `e` (edit-then-apply), branch on the proposal's bracketed type tag and follow the per-type apply procedure in `./apply-reflections-procedure.md` — one numbered procedure each for `[FRONTMATTER]`, `[REFERENCE]`, `[BUDGET]`, `[QUESTION]`, `[GLOBAL-SKILL]`. All branches end with `**Applied**: <date>` appended to the proposal block in the reflections file.
 
 ### 5. Summary
 

package/skills/apply-reflections/apply-reflections-procedure.md

@@ -0,0 +1,68 @@
+---
+name: apply-reflections-procedure
+type: heuristic
+version: 1.0.0
+phase: 28.5
+tags: [apply-reflections, proposal, frontmatter, reference, budget, question, global-skill]
+last_updated: 2026-05-18
+---
+
+# Apply-Reflections — Per-Type Procedure
+
+Extracted from `skills/apply-reflections/SKILL.md` per Phase 28.5 D-10 (extract-then-link,
+never delete content). The orchestrator loop in `apply-reflections` (resolve file → parse →
+review loop → summary) stays in the SKILL. The per-proposal-type apply logic below moves
+here because it is content-class methodology, not workflow.
+
+## Apply Logic by Proposal Type
+
+After the user chooses `a` (apply) or `e` (edit-then-apply) in the review loop, branch by
+the proposal's bracketed type tag.
+
+### [FRONTMATTER]
+
+1. Extract agent name from Change field (e.g., `agents/design-verifier.md`)
+2. Read the agent file
+3. Find the frontmatter line matching the field being changed
+4. Use Edit tool to update the specific line
+5. Append `**Applied**: <date>` to the proposal in reflections file
+
+### [REFERENCE]
+
+1. Extract target file path from Change field (e.g., `reference/heuristics.md`)
+2. If file exists: append the drafted text using Edit tool
+3. If file doesn't exist: create it with a minimal header + the drafted text using Write tool
+4. Append `**Applied**: <date>` to proposal in reflections file
+
+### [BUDGET]
+
+1. Read `.design/budget.json`
+2. Locate the key path from the Change field (e.g., `design-verifier.per_run_cap_usd`)
+3. Update the value
+4. Write updated JSON back to `.design/budget.json`
+5. Append `**Applied**: <date>` to proposal in reflections file
+
+### [QUESTION]
+
+1. Read `agents/design-discussant.md`
+2. Find the question text specified in the Change field
+3. If pruning: remove the question lines using Edit tool
+4. If rewording: replace the question text using Edit tool
+5. Append `**Applied**: <date>` to proposal in reflections file
+
+### [GLOBAL-SKILL]
+
+1. Extract target filename from Change field (e.g., `design-color-conventions.md`)
+2. Ensure `~/.claude/gdd/global-skills/` directory exists (create with `mkdir -p` if not)
+3. If target file exists: append new content using Edit tool (add a `---` separator first)
+4. If target file doesn't exist: create with header + content using Write tool:
+
+   ```markdown
+   # <Topic> Conventions (Global)
+   *Promoted from project: <project-name>, cycle: <cycle-slug>*
+
+   <content>
+   ```
+
+5. Print: "Global skill written to ~/.claude/gdd/global-skills/<name>.md — auto-loads in all future gdd sessions"
+6. Append `**Applied**: <date>` to proposal in reflections file

package/skills/audit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-audit
-description: "Run design audit — wraps design-verifier + design-auditor + design-reflector. --retroactive audits the full cycle scope."
+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."
 argument-hint: "[--retroactive] [--quick] [--no-reflect]"
 tools: Read, Write, Task, Glob, Bash
 ---
@@ -9,6 +9,8 @@ tools: Read, Write, Task, Glob, Bash
 
 Wraps the existing `design-auditor`, `design-verifier`, and `design-integration-checker` agents — no new auditor logic here. Parses flags, spawns the right combination, prints summary.
 
+For the 6-pillar scoring rubric this skill aggregates, see `../../reference/audit-scoring.md`. For the shared design-quality pillar set that frames the score categories, see `../../reference/shared-preamble.md`.
+
 ## Modes
 
 ### Default