@hegemonart/get-design-done 1.45.0 → 1.46.0

package/scripts/lib/pin/cli.cjs

@@ -0,0 +1,145 @@
+'use strict';
+/**
+ * scripts/lib/pin/cli.cjs — Phase 46 (Skill UX Polish).
+ *
+ * Thin CLI over scripts/lib/pin/store.cjs. projectRoot is always process.cwd().
+ *
+ * Usage:
+ *   node cli.cjs pin <skill> [--user]
+ *   node cli.cjs unpin <skill>
+ *   node cli.cjs list
+ *
+ * Exit codes:
+ *   0  action succeeded (at least one file written/removed, or a non-empty list)
+ *   1  nothing done (no harness dirs / nothing to remove / empty list)
+ *   2  error (bad usage, unknown skill, unexpected failure)
+ *
+ * Dependency-free CommonJS. Ships in the npm package; runtime-safe.
+ */
+
+const path = require('path');
+
+const { pinSkill, unpinSkill, listPins } = require('./store.cjs');
+
+function out(msg) {
+  process.stdout.write(msg + '\n');
+}
+function err(msg) {
+  process.stderr.write(msg + '\n');
+}
+
+function usage() {
+  return [
+    'gdd pin - manage pinned skill aliases across installed harness dirs',
+    '',
+    'Usage:',
+    '  node cli.cjs pin <skill> [--user]',
+    '  node cli.cjs unpin <skill>',
+    '  node cli.cjs list',
+    '',
+    'Exit codes: 0 ok / 1 nothing done / 2 error.',
+  ].join('\n');
+}
+
+function runPin(skillId, opts) {
+  const projectRoot = process.cwd();
+  let res;
+  try {
+    res = pinSkill({ projectRoot, skillId, user: Boolean(opts.user) });
+  } catch (e) {
+    err(`pin: ${e.message}`);
+    return 2;
+  }
+  if (res.written.length === 0) {
+    err(`pin: no harness skills dirs found under ${projectRoot}${opts.user ? '' : ' (try --user to create them)'}.`);
+    for (const s of res.skipped) err(`  skipped ${s.config_dir}: ${s.reason}`);
+    return 1;
+  }
+  out(`Pinned "${skillId}" into ${res.written.length} harness dir(s):`);
+  for (const w of res.written) out(`  ${w.config_dir} -> ${path.relative(projectRoot, w.path)}`);
+  for (const s of res.skipped) err(`  skipped ${s.config_dir}: ${s.reason}`);
+  return 0;
+}
+
+function runUnpin(skillId) {
+  const projectRoot = process.cwd();
+  let res;
+  try {
+    res = unpinSkill({ projectRoot, skillId });
+  } catch (e) {
+    err(`unpin: ${e.message}`);
+    return 2;
+  }
+  for (const r of res.refused) err(`  refused ${r.config_dir}: ${r.reason}`);
+  if (res.removed.length === 0) {
+    err(`unpin: no pinned "${skillId}" stubs removed.`);
+    return 1;
+  }
+  out(`Unpinned "${skillId}" from ${res.removed.length} harness dir(s):`);
+  for (const r of res.removed) out(`  ${r.config_dir} -> ${path.relative(projectRoot, r.path)}`);
+  return 0;
+}
+
+function runList() {
+  const projectRoot = process.cwd();
+  let pins;
+  try {
+    pins = listPins(projectRoot);
+  } catch (e) {
+    err(`list: ${e.message}`);
+    return 2;
+  }
+  if (pins.length === 0) {
+    out('No pinned skills found.');
+    return 1;
+  }
+  out(`Pinned skills (${pins.length}):`);
+  for (const p of pins) {
+    out(`  [${p.config_dir}] ${p.alias} -> source=${p.source} (pinned ${p.pinnedAt})`);
+  }
+  return 0;
+}
+
+/**
+ * Pure entry point. argv is the slice AFTER node + script (process.argv.slice(2)).
+ * Returns an exit code; never calls process.exit (so tests can call it directly).
+ */
+function main(argv) {
+  const args = Array.isArray(argv) ? argv.slice() : [];
+  const cmd = args.shift();
+
+  if (!cmd || cmd === '--help' || cmd === '-h') {
+    out(usage());
+    return cmd ? 0 : 2;
+  }
+
+  if (cmd === 'list') {
+    if (args.length) { err(`list: unexpected argument "${args[0]}"`); return 2; }
+    return runList();
+  }
+
+  if (cmd === 'pin' || cmd === 'unpin') {
+    const opts = { user: false };
+    const positionals = [];
+    for (const a of args) {
+      if (a === '--user') opts.user = true;
+      else if (a.startsWith('--')) { err(`${cmd}: unknown flag ${a}`); return 2; }
+      else positionals.push(a);
+    }
+    const skillId = positionals[0];
+    if (!skillId) { err(`${cmd}: missing <skill> argument`); return 2; }
+    if (positionals.length > 1) { err(`${cmd}: unexpected argument "${positionals[1]}"`); return 2; }
+    if (cmd === 'unpin' && opts.user) { err('unpin: --user is not valid for unpin'); return 2; }
+    return cmd === 'pin' ? runPin(skillId, opts) : runUnpin(skillId);
+  }
+
+  err(`unknown command: ${cmd}`);
+  err(usage());
+  return 2;
+}
+
+if (require.main === module) {
+  process.exit(main(process.argv.slice(2)));
+}
+
+module.exports = { main };

package/scripts/lib/pin/harness-detect.cjs

@@ -0,0 +1,75 @@
+'use strict';
+/**
+ * scripts/lib/pin/harness-detect.cjs — Phase 46 (Skill UX Polish).
+ *
+ * Locates the per-harness `skills/` directories under a project root so the pin
+ * store knows where to write / scan pinned skill stubs. Each harness record in
+ * scripts/lib/manifest/harnesses.cjs carries a `config_dir` (e.g. ".claude",
+ * ".cursor", ".codex"); the candidate skills dir for a harness is
+ * `<projectRoot>/<config_dir>/skills`.
+ *
+ * Two surfaces:
+ *   detectHarnessSkillDirs(projectRoot)   -> only the candidates that EXIST on disk
+ *   harnessSkillDirCandidates(projectRoot)-> ALL candidates (existing or not), for
+ *                                            the --user / create flows that may need
+ *                                            to materialize a missing dir.
+ *
+ * Dependency-free CommonJS. Cross-platform: all path joins go through `path`,
+ * never a hardcoded separator. Ships inside the npm package, so it must stay
+ * runtime-safe (no dev-only requires).
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const harnesses = require('../manifest/harnesses.cjs');
+
+/**
+ * Build the full candidate list (one entry per harness record), regardless of
+ * whether the directory currently exists. The candidate skills dir for a harness
+ * is `<projectRoot>/<config_dir>/skills`.
+ *
+ * @param {string} projectRoot absolute or relative project root
+ * @returns {Array<{ id: string, config_dir: string, skillsDir: string }>}
+ */
+function harnessSkillDirCandidates(projectRoot) {
+  if (!projectRoot || typeof projectRoot !== 'string') {
+    throw new TypeError('harnessSkillDirCandidates: projectRoot must be a non-empty string');
+  }
+  const out = [];
+  const seen = new Set();
+  for (const h of harnesses) {
+    if (!h || !h.config_dir) continue;
+    // De-dupe on config_dir so two records pointing at the same dir don't double up.
+    if (seen.has(h.config_dir)) continue;
+    seen.add(h.config_dir);
+    out.push({
+      id: h.id,
+      config_dir: h.config_dir,
+      skillsDir: path.join(projectRoot, h.config_dir, 'skills'),
+    });
+  }
+  return out;
+}
+
+/**
+ * Filter the candidate list to the harness skills dirs that actually exist as
+ * directories under projectRoot.
+ *
+ * @param {string} projectRoot absolute or relative project root
+ * @returns {Array<{ id: string, config_dir: string, skillsDir: string }>}
+ */
+function detectHarnessSkillDirs(projectRoot) {
+  return harnessSkillDirCandidates(projectRoot).filter((c) => {
+    try {
+      return fs.statSync(c.skillsDir).isDirectory();
+    } catch {
+      return false;
+    }
+  });
+}
+
+module.exports = {
+  detectHarnessSkillDirs,
+  harnessSkillDirCandidates,
+};

package/scripts/lib/pin/store.cjs

@@ -0,0 +1,288 @@
+'use strict';
+/**
+ * scripts/lib/pin/store.cjs — Phase 46 (Skill UX Polish).
+ *
+ * Core for "pinning" a gdd skill: writing a small standalone shortcut alias
+ * (a SKILL.md stub) into every installed harness `skills/` dir so the skill is
+ * directly discoverable as its own command in each runtime, plus the inverse
+ * (unpin) and an inventory (listPins).
+ *
+ * The pin marker is exactly:
+ *   <!-- gdd-pinned-skill source=<skillId> -->
+ * and is the FIRST line of every pinned stub. unpin only ever deletes files
+ * carrying this marker, so a hand-written / unrelated SKILL.md is never removed.
+ *
+ * Metadata (name, description, argument-hint, tools) is pulled from the manifest
+ * SoT via readSkills() — NEVER scraped from live frontmatter — so a pinned stub
+ * always reflects the canonical record.
+ *
+ * Writes are atomic: contents go to `<dest>.tmp` then fs.renameSync to the final
+ * path (rename is atomic within a filesystem), so a crash mid-write never leaves
+ * a half-written SKILL.md.
+ *
+ * Dependency-free CommonJS. Cross-platform via `path`. Ships in the npm package,
+ * so it stays runtime-safe (no dev-only requires).
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { readSkills } = require('../manifest/index.cjs');
+const { detectHarnessSkillDirs, harnessSkillDirCandidates } = require('./harness-detect.cjs');
+
+const MARKER_PREFIX = '<!-- gdd-pinned-skill source=';
+const MARKER_SUFFIX = ' -->';
+
+/** Build the exact marker line for a skill id. */
+function markerFor(skillId) {
+  return `${MARKER_PREFIX}${skillId}${MARKER_SUFFIX}`;
+}
+
+/**
+ * Extract the `source=<id>` skill id from a marker line, or null if the line is
+ * not a gdd pin marker. Tolerates surrounding whitespace.
+ */
+function parseMarker(line) {
+  if (typeof line !== 'string') return null;
+  const trimmed = line.trim();
+  if (!trimmed.startsWith(MARKER_PREFIX) || !trimmed.endsWith(MARKER_SUFFIX)) return null;
+  const inner = trimmed.slice(MARKER_PREFIX.length, trimmed.length - MARKER_SUFFIX.length);
+  const id = inner.trim();
+  return id.length ? id : null;
+}
+
+/** First non-empty line of a text blob (trimmed), or '' if none. */
+function firstNonEmptyLine(text) {
+  const lines = String(text).replace(/\r\n/g, '\n').split('\n');
+  for (const l of lines) {
+    if (l.trim().length) return l;
+  }
+  return '';
+}
+
+/** Look up a skill record from the manifest SoT by id, or null. */
+function lookupSkill(skillId) {
+  const { skills } = readSkills();
+  for (const r of skills || []) {
+    if (r && r.name === skillId) return r;
+  }
+  return null;
+}
+
+/** Double-quote a YAML scalar, escaping backslashes and quotes. */
+function quote(s) {
+  return '"' + String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
+}
+
+/**
+ * Render the pinned stub contents for a skill record. Layout:
+ *   <marker line>
+ *   ---
+ *   name: gdd-<id>
+ *   description: "<desc>"
+ *   argument-hint: "<hint>"   (only when the record has one)
+ *   tools: <tools>            (only when the record has tools)
+ *   ---
+ *   <one-line body pointing at the source skill>
+ *
+ * `name` mirrors the generator: `gdd-<id>` unless the record overrides via
+ * `frontmatter_name`.
+ */
+function renderStub(skillId, rec) {
+  const fmName = rec.frontmatter_name || `gdd-${skillId}`;
+  const lines = [];
+  lines.push(markerFor(skillId));
+  lines.push('---');
+  lines.push(`name: ${fmName}`);
+  lines.push(`description: ${quote(rec.description || '')}`);
+  if (rec.argument_hint != null && String(rec.argument_hint).length) {
+    lines.push(`argument-hint: ${quote(rec.argument_hint)}`);
+  }
+  if (rec.tools != null && String(rec.tools).length) {
+    lines.push(`tools: ${rec.tools}`);
+  }
+  lines.push('---');
+  lines.push('');
+  lines.push(`Pinned alias for the gdd \`${skillId}\` skill. Run the canonical \`${fmName}\` skill; this stub only makes it directly discoverable in this harness.`);
+  lines.push('');
+  return lines.join('\n');
+}
+
+/** Atomic write: write to `<dest>.tmp` then rename into place. */
+function atomicWrite(dest, contents) {
+  const dir = path.dirname(dest);
+  fs.mkdirSync(dir, { recursive: true });
+  const tmp = `${dest}.tmp`;
+  fs.writeFileSync(tmp, contents, 'utf8');
+  try {
+    fs.renameSync(tmp, dest);
+  } catch (e) {
+    // Clean up the temp file on failure so we never leave a stray .tmp behind.
+    try { fs.unlinkSync(tmp); } catch { /* ignore */ }
+    throw e;
+  }
+}
+
+/**
+ * Pin a skill across harness skills dirs.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {string} args.skillId
+ * @param {Array<string>} [args.harnesses] optional allow-list of config_dir or harness id; when omitted, all detected dirs
+ * @param {boolean} [args.user] when true, materialize ALL candidate dirs (not just existing ones)
+ * @returns {{ skillId: string, written: Array<{ id, config_dir, path }>, skipped: Array<{ id, config_dir, reason }> }}
+ */
+function pinSkill(args) {
+  const { projectRoot, skillId } = args || {};
+  if (!projectRoot) throw new TypeError('pinSkill: projectRoot is required');
+  if (!skillId) throw new TypeError('pinSkill: skillId is required');
+
+  const rec = lookupSkill(skillId);
+  if (!rec) {
+    throw new Error(`pinSkill: "${skillId}" is not a known skill in scripts/lib/manifest/skills.json`);
+  }
+
+  const all = args.user
+    ? harnessSkillDirCandidates(projectRoot)
+    : detectHarnessSkillDirs(projectRoot);
+
+  const filter = Array.isArray(args.harnesses) && args.harnesses.length
+    ? new Set(args.harnesses)
+    : null;
+  const targets = filter
+    ? all.filter((c) => filter.has(c.config_dir) || filter.has(c.id))
+    : all;
+
+  const contents = renderStub(skillId, rec);
+  const written = [];
+  const skipped = [];
+  for (const t of targets) {
+    const dest = path.join(t.skillsDir, skillId, 'SKILL.md');
+    try {
+      atomicWrite(dest, contents);
+      written.push({ id: t.id, config_dir: t.config_dir, path: dest });
+    } catch (e) {
+      skipped.push({ id: t.id, config_dir: t.config_dir, reason: e.message });
+    }
+  }
+  return { skillId, written, skipped };
+}
+
+/**
+ * Unpin a skill: delete pinned stubs across harness dirs. REFUSES (skips with a
+ * warning) any SKILL.md whose first non-empty line is not the gdd pin marker, so
+ * a hand-authored skill is never deleted.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {string} args.skillId
+ * @returns {{ skillId: string, removed: Array<{ id, config_dir, path }>, refused: Array<{ id, config_dir, path, reason }>, missing: Array<{ id, config_dir, path }> }}
+ */
+function unpinSkill(args) {
+  const { projectRoot, skillId } = args || {};
+  if (!projectRoot) throw new TypeError('unpinSkill: projectRoot is required');
+  if (!skillId) throw new TypeError('unpinSkill: skillId is required');
+
+  // Look across every candidate harness dir (existing or not) so we can clean up
+  // stubs even if the surrounding harness dir was partially removed.
+  const candidates = harnessSkillDirCandidates(projectRoot);
+  const removed = [];
+  const refused = [];
+  const missing = [];
+
+  for (const c of candidates) {
+    const file = path.join(c.skillsDir, skillId, 'SKILL.md');
+    let content;
+    try {
+      content = fs.readFileSync(file, 'utf8');
+    } catch {
+      missing.push({ id: c.id, config_dir: c.config_dir, path: file });
+      continue;
+    }
+    const marker = parseMarker(firstNonEmptyLine(content));
+    if (marker == null) {
+      refused.push({
+        id: c.id,
+        config_dir: c.config_dir,
+        path: file,
+        reason: 'first non-empty line lacks the gdd-pinned-skill marker - refusing to delete',
+      });
+      continue;
+    }
+    try {
+      fs.unlinkSync(file);
+      // Remove the now-empty alias dir if nothing else lives there.
+      const aliasDir = path.dirname(file);
+      try {
+        if (fs.readdirSync(aliasDir).length === 0) fs.rmdirSync(aliasDir);
+      } catch { /* leave non-empty dir alone */ }
+      removed.push({ id: c.id, config_dir: c.config_dir, path: file });
+    } catch (e) {
+      refused.push({ id: c.id, config_dir: c.config_dir, path: file, reason: e.message });
+    }
+  }
+  return { skillId, removed, refused, missing };
+}
+
+/**
+ * List pinned skills across harness skills dirs.
+ *
+ * Scans each existing harness skills dir for `<alias>/SKILL.md` files whose first
+ * non-empty line carries the gdd pin marker.
+ *
+ * @param {string} projectRoot
+ * @returns {Array<{ id: string, config_dir: string, alias: string, source: string, pinnedAt: string }>}
+ *   `id` is the harness id, `alias` is the on-disk directory name, `source` is the
+ *   pinned source skill id from the marker, `pinnedAt` is the file mtime ISO string.
+ */
+function listPins(projectRoot) {
+  if (!projectRoot) throw new TypeError('listPins: projectRoot is required');
+  const out = [];
+  for (const dir of detectHarnessSkillDirs(projectRoot)) {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir.skillsDir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      const file = path.join(dir.skillsDir, e.name, 'SKILL.md');
+      let content;
+      let stat;
+      try {
+        content = fs.readFileSync(file, 'utf8');
+        stat = fs.statSync(file);
+      } catch {
+        continue;
+      }
+      const source = parseMarker(firstNonEmptyLine(content));
+      if (source == null) continue;
+      out.push({
+        id: dir.id,
+        config_dir: dir.config_dir,
+        alias: e.name,
+        source,
+        pinnedAt: stat.mtime.toISOString(),
+      });
+    }
+  }
+  // Stable order: by config_dir then alias for deterministic output.
+  out.sort((a, b) => (a.config_dir === b.config_dir
+    ? a.alias.localeCompare(b.alias)
+    : a.config_dir.localeCompare(b.config_dir)));
+  return out;
+}
+
+module.exports = {
+  pinSkill,
+  unpinSkill,
+  listPins,
+  // exported for the CLI + tests
+  markerFor,
+  parseMarker,
+  renderStub,
+  MARKER_PREFIX,
+  MARKER_SUFFIX,
+};

package/skills/figma-extract/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-figma-extract
-description: Off-context Figma design-system extraction into a compact local digest (DESIGN.md + tokens.json + components.json). Pulls the file via the Figma REST API and digests it without the raw JSON ever entering the model context.
+description: "Off-context Figma design-system extraction into a compact local digest (DESIGN.md + tokens.json + components.json). Pulls the file via the Figma REST API and digests it without the raw JSON ever entering the model context."
 ---
 
 # gdd-figma-extract

package/skills/graphify/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-graphify
-description: Manage the Graphify knowledge graph for the current project. Build, query, status, diff. When available, design-planner and design-integration-checker use the graph for pre-search consultation.
+description: "Manage the Graphify knowledge graph for the current project. Build, query, status, diff. When available, design-planner and design-integration-checker use the graph for pre-search consultation."
 ---
 
 # gdd-graphify

package/skills/list-pins/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: gdd-list-pins
+description: "Lists pinned skill aliases per harness with their source skill and pin timestamp. Use when you want to see which gdd skills have been pinned as standalone shortcuts and where."
+tools: Read, Bash
+---
+
+# /gdd:list-pins
+
+**Role:** Show every pinned skill alias across the installed harness `skills/` directories. For each one, report the harness it lives in, the on-disk alias directory name, the source skill it points at (from the `<!-- gdd-pinned-skill source=<skill> -->` marker), and when it was pinned (the file modification time).
+
+## Steps
+
+1. **Run the list CLI.** Invoke the shipped script (it takes no arguments). The plugin root resolves via `CLAUDE_PLUGIN_ROOT` (falling back to the current directory when that variable is absent):
+
+    ```bash
+    node "${CLAUDE_PLUGIN_ROOT:-$(pwd)}/scripts/lib/pin/cli.cjs" list
+    ```
+
+    The CLI scans each harness `skills/` directory under the current project, finds the stubs carrying the gdd pin marker, and prints one line per pinned alias in the form `[<config-dir>] <alias> -> source=<skill> (pinned <timestamp>)`.
+
+2. **Report the result.** Relay the CLI output verbatim. Exit codes: 0 means one or more pinned aliases were found, 1 means none were found (nothing has been pinned yet), 2 means an error.
+
+## Do Not
+
+- Do not scan the harness directories by hand. The CLI already enforces the marker check, so only genuine gdd pins are listed.
+
+## LIST-PINS COMPLETE

package/skills/pin/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: gdd-pin
+description: "Writes standalone shortcut aliases for a gdd skill across installed harness skill dirs. Use when you want a skill directly discoverable as its own command in every installed runtime."
+argument-hint: "<skill-name>"
+tools: Read, Bash
+---
+
+# /gdd:pin
+
+**Role:** Write a standalone shortcut alias (a small SKILL.md stub) for one gdd skill into every installed harness `skills/` directory, so that skill is directly discoverable as its own command in each runtime (Claude Code, Codex, Cursor, Gemini, and the rest).
+
+Each pinned stub starts with the marker line `<!-- gdd-pinned-skill source=<skill> -->`, then carries frontmatter (name, description, argument-hint, tools) pulled from the manifest source of truth, then a one-line body pointing back at the canonical skill. Stubs are written atomically (temp file plus rename), so a failed write never leaves a half-written file.
+
+## Steps
+
+1. **Read the argument.** The skill name to pin comes from `$ARGUMENTS` (for example `darkmode`). If it is empty, ask the user which skill to pin and stop.
+
+2. **Run the pin CLI.** Invoke the shipped script, passing the skill name. The plugin root resolves via `CLAUDE_PLUGIN_ROOT` (falling back to the current directory when that variable is absent):
+
+    ```bash
+    node "${CLAUDE_PLUGIN_ROOT:-$(pwd)}/scripts/lib/pin/cli.cjs" pin "<skill-name>"
+    ```
+
+    The CLI detects every harness `skills/` directory that exists under the current project (`.claude/skills`, `.cursor/skills`, and so on) and writes the stub into each. Pass `--user` to also create the harness directories that do not exist yet:
+
+    ```bash
+    node "${CLAUDE_PLUGIN_ROOT:-$(pwd)}/scripts/lib/pin/cli.cjs" pin "<skill-name>" --user
+    ```
+
+3. **Report the result.** The CLI prints one line per harness it wrote to, plus any skips. Relay that summary verbatim. Exit codes: 0 means at least one stub was written, 1 means nothing was written (no harness dirs found, suggest `--user`), 2 means an error (for example an unknown skill name).
+
+## Do Not
+
+- Do not hand-write the stub files. Always go through the CLI so the marker, the manifest-sourced frontmatter, and the atomic write stay consistent.
+- Do not pin a skill that is not in the manifest. The CLI rejects unknown skill names with exit code 2; surface that error rather than inventing a stub.
+
+## PIN COMPLETE

package/skills/unpin/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: gdd-unpin
+description: "Removes pinned skill aliases across harness dirs, deleting only stubs that carry the gdd pin marker. Use when you no longer want a pinned shortcut and want hand-written skills left untouched."
+argument-hint: "<skill-name>"
+tools: Read, Bash
+---
+
+# /gdd:unpin
+
+**Role:** Remove the pinned shortcut aliases for one gdd skill from every installed harness `skills/` directory. Only stubs that carry the marker line `<!-- gdd-pinned-skill source=<skill> -->` as their first non-empty line are deleted, so a hand-authored or unrelated SKILL.md is never touched.
+
+## Steps
+
+1. **Read the argument.** The skill name to unpin comes from `$ARGUMENTS` (for example `darkmode`). If it is empty, ask the user which skill to unpin and stop.
+
+2. **Run the unpin CLI.** Invoke the shipped script, passing the skill name. The plugin root resolves via `CLAUDE_PLUGIN_ROOT` (falling back to the current directory when that variable is absent):
+
+    ```bash
+    node "${CLAUDE_PLUGIN_ROOT:-$(pwd)}/scripts/lib/pin/cli.cjs" unpin "<skill-name>"
+    ```
+
+    The CLI scans every harness `skills/` directory under the current project, checks each candidate stub for the gdd pin marker, deletes the ones that carry it, and refuses (skips with a warning) any file that does not.
+
+3. **Report the result.** The CLI prints one line per harness it removed a stub from, plus a warning for any file it refused to delete. Relay that summary verbatim. Exit codes: 0 means at least one stub was removed, 1 means nothing was removed (no matching pinned stubs found), 2 means an error.
+
+## Do Not
+
+- Do not delete skill files by hand. Always go through the CLI so the marker check protects hand-written skills.
+- Do not force-remove a file the CLI refused. A refusal means the file lacks the gdd pin marker and is not a pinned alias; leave it in place.
+
+## UNPIN COMPLETE