@hegemonart/get-design-done 1.59.2 → 1.59.4

package/scripts/skill-templates/figma-extract/SKILL.md

@@ -0,0 +1,64 @@
+---
+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."
+---
+
+# gdd-figma-extract
+
+Pull a whole Figma design system into a compact, queryable local digest - **without** the raw JSON ever entering Claude context. The heavy lifting runs in tested `.cjs` tools; the model reads only the digest outputs.
+
+## Usage
+
+```
+{{command_prefix}}figma-extract <file-key-or-url>                  # full design-system digest
+{{command_prefix}}figma-extract <file-key-or-url> --component Button  # ~500-token single-component slice
+```
+
+`<file-key-or-url>` is a Figma file URL (`https://www.figma.com/file/<key>/…` or `/design/<key>/…`) or a bare file key.
+
+## Behavior
+
+1. **Preflight (D-10).** Confirm `FIGMA_TOKEN` is set in the environment:
+   ```
+   node -e "process.exit(process.env.FIGMA_TOKEN||process.env.FIGMA_PERSONAL_ACCESS_TOKEN?0:1)"
+   ```
+   If unset, tell the user to `export FIGMA_TOKEN=figd_…` (from https://www.figma.com/developers/api#access-tokens). The token comes from the environment **only** - never ask the user to paste it into a file or the chat, and never echo it back.
+
+2. **Stage 1 - pull.** Pull the file's REST endpoints into the gitignored raw cache (D-09):
+   ```
+   node scripts/lib/figma-extract/pull.cjs "<file-key-or-url>"
+   ```
+   This caches to `.figma-extract-cache/raw/<file-key>/` and skips re-pulling when Figma's `version` is unchanged (D-11). Add `--force` to bypass the cache, `--out <dir>` to relocate the cache. The tool prints a JSON summary (endpoints, bytes, cached) on stdout - the raw bodies stay on disk.
+
+3. **Stage 2 - plugin sync (OPTIONAL, Path C).** Only when the design tokens live in Figma Variables that the REST API cannot return (non-Enterprise plans → the pull summary shows `variables` skipped) and the user wants token coverage:
+   ```
+   node scripts/lib/figma-extract/receiver.cjs --out .figma-extract-cache/raw/<file-key>
+   ```
+   This binds `127.0.0.1:5179` (D-06). Tell the user to run the dev-installed **"GDD Sync"** plugin in Figma and click **"Export to GDD"** - see `figma-plugin/README.md` for the one-time dev-install. The receiver writes `variables.json` into the cache and exits on receipt or timeout. Skip this stage entirely for design systems whose tokens already come through the REST pull.
+
+4. **Stage 3 - digest.** Transform the cache into the compact digest:
+   ```
+   node scripts/lib/figma-extract/digest.cjs --raw .figma-extract-cache/raw/<file-key> --out .figma-extract-cache/digest
+   ```
+   This writes `DESIGN.md`, `tokens.json`, and `components.json`. Add `--prefer-styles` to invert the token priority to styles-first (D-04). Add `--component <name>` (D-08) to emit a single-component slice instead of the full digest.
+
+5. **Read the digest.** Open **only** `.figma-extract-cache/digest/DESIGN.md` (plus `tokens.json` / `components.json` when you need structured data). For a single component, pass `--component <name>` in Stage 3 and read the ~500-token slice instead of the full ~16K-token spec.
+
+## Required Reading
+
+- `.figma-extract-cache/digest/DESIGN.md` - the compact human/LLM-readable spec
+- `.figma-extract-cache/digest/tokens.json` - resolved design tokens (when structured token data is needed)
+- `.figma-extract-cache/digest/components.json` - components with variants/props/defaults (when structured component data is needed)
+
+## Notes
+
+- Two-stage pipeline (D-01): re-run Stage 3 against an existing cache without re-pulling. The digest does zero network calls.
+- The spike proved **0 Claude tokens** during extraction (898× compression, 223 MB → 254 KB). That property holds only because this skill never surfaces the raw cache.
+- Figma MCP remains the right tool for spot questions on a single live component; this skill is the cheaper path for whole-design-system workflows.
+
+## Do Not
+
+- **Do NOT read or `cat` the `raw/*.json` cache** (e.g. `.figma-extract-cache/raw/<file-key>/file.json`). It is tool-internal and often 100+ MB; loading it into context defeats the off-context guarantee (D-12). Read only the digest outputs above.
+- **Do not persist, log, echo, or print `FIGMA_TOKEN`** (D-10). It belongs in the environment only - never write it to a file, a commit, or chat output.
+
+## FIGMA-EXTRACT COMPLETE

package/scripts/skill-templates/figma-write/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: gdd-figma-write
+description: "Write design decisions from `.design/DESIGN-CONTEXT.md` back into the active Figma file by dispatching the `design-figma-writer` agent in one of three modes (annotate / tokenize / mappings). Use when the user has completed a design pipeline cycle and wants the decisions (layer comments, variable bindings, or Code Connect mappings) reflected in Figma. Operates proposal→confirm with `--dry-run` and `--confirm-shared` flags."
+---
+
+# gdd-figma-write
+
+Dispatches the `design-figma-writer` agent to write design decisions back to the open Figma file. The shared probe pattern (ToolSearch → live call → STATE.md write) and connection handshake are documented at `../../reference/shared-preamble.md#connection-handshake-summary` and `../../connections/figma.md`.
+
+## Usage
+
+```
+/get-design-done figma-write <mode> [--dry-run] [--confirm-shared]
+```
+
+Modes:
+- `annotate` - add design decision comments to Figma layers
+- `tokenize` - bind hard-coded color/spacing/type values to Figma variables
+- `mappings` - write Code Connect component↔code file mappings
+
+Flags:
+- `--dry-run` - emit the proposal without executing any Figma writes
+- `--confirm-shared` - authorize writes to shared team library components
+
+## Prerequisites
+
+1. Remote Figma MCP registered (writes are remote-only). Preferred: `claude plugin install figma@claude-plugins-official`. Manual: `claude mcp add --transport http figma https://mcp.figma.com/mcp`.
+2. `.design/DESIGN-CONTEXT.md` exists (run `discover` first)
+3. `.design/STATE.md` `<connections>` shows `figma: available (…, writes=true)`. If `writes=false` (desktop-only variant), writes are not supported - the agent will STOP with an instruction to install the remote MCP.
+
+## Required Reading
+
+Read `.design/STATE.md` and `.design/DESIGN-CONTEXT.md` before dispatching the agent.
+
+## Dispatch
+
+```
+Task("design-figma-writer", """
+mode: <annotate|tokenize|mappings>
+dry_run: <true|false>
+confirm_shared: <true|false>
+required_reading:
+  - .design/STATE.md
+  - .design/DESIGN-CONTEXT.md
+""")
+```
+
+Pass `mode` from the first positional argument; `dry_run` from `--dry-run`;
+`confirm_shared` from `--confirm-shared`. Wait for the agent's completion
+marker before returning.

package/scripts/skill-templates/graphify/SKILL.md

@@ -0,0 +1,49 @@
+---
+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."
+---
+
+# gdd-graphify
+
+Thin command wrapper around the GSD graphify tools integration.
+
+## Usage
+
+```
+/get-design-done graphify build          # Build or rebuild the knowledge graph
+/get-design-done graphify query <term>   # Query graph for a node and neighbors
+/get-design-done graphify status         # Check graph age, enabled, node count
+/get-design-done graphify diff           # Show topology changes since last build
+```
+
+## Behavior
+
+1. Read `.design/STATE.md` to check `graphify` status in `<connections>`.
+2. Check `graphify.enabled` in `.design/config.json` via a direct file read (per D-09 - no `config-get` CLI subcommand):
+   ```
+   node -e "try{const c=JSON.parse(require('fs').readFileSync('.design/config.json','utf8'));process.stdout.write(String(c.graphify?.enabled===true))}catch{process.stdout.write('false')}"
+   ```
+3. If not enabled, print:
+   ```
+   "Graphify is not enabled. Edit `.design/config.json` to set `graphify.enabled: true`."
+   "Then run {{command_prefix}}graphify build to generate the knowledge graph."
+   ```
+   STOP.
+4. Execute the requested subcommand via the native CLI:
+   - build:  `node bin/gdd-graph build`
+   - query:  `node bin/gdd-graph query "<term>" --budget 2000`
+   - status: `node bin/gdd-graph status`
+   - diff:   `node bin/gdd-graph diff`
+5. After `build` completes, update `.design/STATE.md` `<connections>`: `graphify: available`
+
+## Required Reading
+
+- `.design/STATE.md` - for graphify status in `<connections>`
+- `.design/config.json` - for `graphify.enabled` flag
+
+## Notes
+
+- Graphify is optional. The native CLI ships in this repo at `bin/gdd-graph` (no external install - Node only).
+- Graph is stored at `.design/graph/graph.json` (Ajv-validated against `scripts/lib/graph/schema.json`).
+- Graph covers source code (`src/`, `components/`). It does NOT index `.design/` artifacts by default.
+- Use `query` with node IDs from the graph schema: `component:<name>`, `token:color/<name>`, `decision:D-<nn>`, etc.

package/scripts/skill-templates/health/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: gdd-health
+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
+---
+
+# {{command_prefix}}health
+
+**Role:** Report the health of the `.design/` directory. Print a score and list the checks that failed.
+
+## Checks
+
+1. **Artifact inventory** - `ls -la .design/*.md` with size and mtime. Print a table.
+2. **Missing expected artifacts** - by `stage` field from the `mcp__gdd_state__get` snapshot:
+   - `brief` expects BRIEF.md
+   - `explore` expects DESIGN.md, DESIGN-DEBT.md, DESIGN-CONTEXT.md
+   - `plan` expects DESIGN-PLAN.md
+   - `design` expects DESIGN-SUMMARY.md
+   - `verify` expects DESIGN-VERIFICATION.md
+   FAIL per missing.
+3. **Token drift** - `wc -c .design/DESIGN.md .design/DESIGN-CONTEXT.md`; approx tokens = bytes/4. WARN if combined >40000.
+4. **Aged DESIGN-DEBT** - items in `.design/DESIGN-DEBT.md` not touched in >14 days (file mtime). WARN.
+5. **Broken state transitions** - `stage` field from the snapshot inconsistent with artifacts present (e.g. stage=`verify` but DESIGN-SUMMARY.md missing). FAIL.
+6. **Pending sketch/spike wrap-ups** - any `.design/sketches/*` or `.design/spikes/*` directory lacking a SUMMARY.md. WARN.
+7. **Seed germination** - scan `.design/SEEDS.md` (if present) for seeds whose trigger keywords match the snapshot or CYCLES.md content. List as "Seed ready: <text>".
+
+## State snapshot
+
+Call `mcp__gdd_state__get` once at the start to pull the snapshot used by checks 2, 5, and 7. Aggregate health math stays prose-level:
+- Count available connections from `<connections>`.
+- Count open blockers from `<blockers>` where `resolved` is absent.
+- Count pending must-haves from `<must_haves>` where `status: "pending"`.
+
+## Output
+
+```
+━━━ Design health ━━━
+Artifacts:
+  BRIEF.md           2.1 KB   2026-04-14
+  DESIGN.md          18.4 KB  2026-04-17
+  DESIGN-CONTEXT.md  7.2 KB   2026-04-17
+
+Checks:
+  [PASS] Missing artifacts
+  [WARN] Token drift (42,100)
+  [PASS] Aged DESIGN-DEBT
+  [PASS] State transitions
+  [PASS] Sketch/spike wrap-ups
+  [PASS] Seed germination
+
+Health: 5 / 6 checks passing.
+━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Figma-extract readiness (figma_extract)
+
+After the health table, the `gdd_health` MCP surface (`scripts/lib/health-mirror/index.cjs`) reports a `figma_extract` check so a user knows whether figma-extract is usable. The detail is one of three exact strings:
+
+- `figma extract: ready (token set)` - `FIGMA_TOKEN` (or `FIGMA_PERSONAL_ACCESS_TOKEN`) is present (status `ok`).
+- `figma extract: token missing` - no token env is set (status `warn`).
+- `figma extract: plugin sync needed for variables (Free tier detected)` - token present but a prior pull recorded a 403/skip on the Variables REST path, so run the plugin-sync step (status `warn`).
+
+Token PRESENCE only is detected (D-10) - the token value is never read, logged, or shown. The Free-tier signal is read from the local raw-pull cache only; no network call is made.
+
+## Skill-discipline bootstrap (skill_discipline)
+
+The `gdd_health` MCP surface also reports a `skill_discipline` check (Phase 32) confirming the using-gdd SessionStart bootstrap is live - detail is one of three exact strings:
+- `skill-discipline: ready` - `skills/using-gdd/SKILL.md` exists AND `hooks/hooks.json` SessionStart wires `inject-using-gdd.sh` (status `ok`).
+- `skill-discipline: missing using-gdd` (skill absent) or `skill-discipline: hook not wired` (skill present, no SessionStart inject) - both `warn`. The MCP surface also reports a `harness_freshness` check (Phase 44): per-harness `last_verified` age, status-aware (only `tested` harnesses warn at 60d / fail at 180d; others `n/a`). Full taxonomy in `HARNESSES.md`; refresh with `npm run verify:harness <id>`.
+
+## Check MCP registration (gdd-mcp)
+
+After the health table, inspect whether `gdd-mcp` (Phase 27.7+) is registered with any installed harness and render a one-line status row. Dismissable via `.design/config.json#mcp_nudge=false`. Non-blocking: failure paths render `MCP server: unknown` rather than crash. Full detection procedure (dismissal check, detection via `scripts/lib/install/mcp-register.cjs`, row rendering for claude/codex/both/neither, fallback) lives in `./health-mcp-detection.md`.
+
+## Update notice (safe-window surface)
+
+After the health table, emit the plugin-update banner if one is present:
+
+```bash
+[ -f .design/update-available.md ] && cat .design/update-available.md
+```
+
+Written by `hooks/update-check.sh`; suppressed mid-pipeline and when the latest release is dismissed.
+
+## Skill-length report
+
+After the health table, surface the Phase 28.5 skill-authoring contract drift signal by running `node scripts/validate-skill-length.cjs --quiet --json` and reading `summary` from stdout. Print two prose lines:
+
+- `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). 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
+
+- Do not mutate STATE.md - this skill is read-only. Only `mcp__gdd_state__get` is permitted.
+
+## HEALTH COMPLETE

package/scripts/skill-templates/health/health-mcp-detection.md

@@ -0,0 +1,44 @@
+---
+name: health-mcp-detection
+type: heuristic
+version: 1.0.0
+phase: 28.5
+tags: [health, mcp, detection, gdd-mcp, registration-nudge]
+last_updated: 2026-05-18
+---
+
+# Health MCP-Registration Detection Procedure
+
+Extracted from `skills/health/SKILL.md` per Phase 28.5 D-10 (extract-then-link, never delete content).
+This file documents the canonical procedure for inspecting whether `gdd-mcp` (Phase 27.7+) is
+registered with any installed harness and rendering a one-line status row after the health
+table. The procedure is non-blocking by design: any failure path renders `unknown` rather
+than crashing the skill.
+
+## Dismissal check
+
+1. Read `.design/config.json` (if present). Parse JSON inside a try/catch.
+2. If `config.mcp_nudge === false`, SKIP this step entirely (render nothing).
+3. On parse failure: default to `mcp_nudge=true` (show the row) - fail-safe per threat T-27.7-04-05.
+
+## Detection
+
+1. Read `.claude/settings.local.json` (or equivalent harness settings file) and inspect its `mcpServers` object - alternatively run `claude mcp list` / `codex mcp list` if a CLI is available (see fallback below).
+2. Preferred invocation via the install-lib: call `detectMcpRegistration()` from `scripts/lib/install/mcp-register.cjs`. Returns `{harnesses: [{harness, present, registered}], summary}`.
+
+## Row rendering
+
+Based on the detection result, render exactly ONE of these row strings:
+
+- When `claude` and `codex` both present + both registered:
+  `MCP server: registered with claude+codex`
+- When only one harness is present and registered:
+  `MCP server: registered with claude` (or `MCP server: registered with codex`)
+- When at least one harness is present but `gdd-mcp` is NOT in its registered list:
+  `MCP server: not registered  (run: npx @hegemonart/get-design-done --register-mcp; dismiss: .design/config.json#mcp_nudge=false)`
+- When neither harness CLI is found on PATH:
+  `MCP server: unknown (claude/codex CLI not found)`
+
+## Fallback (if `mcp-register.cjs` not yet shipped)
+
+Skip this step silently with status `MCP server: unknown`. This step is non-blocking - failures here MUST NOT crash the SKILL.

package/scripts/skill-templates/health/health-skill-length-report.md

@@ -0,0 +1,69 @@
+# Health skill - skill-length report subsection
+
+Phase 28.5-11 / D-11 reference. Read by `skills/health/SKILL.md` to render the
+"Skill-length report" subsection after the standard health checks.
+
+## JSON shape (from `validate-skill-length.cjs --quiet --json`)
+
+```jsonc
+{
+  "summary": {
+    "total":    70,   // number of SKILL.md files under skills/
+    "clean":    70,   // skills with 0 errors and 0 warnings
+    "warnings": 0,    // skills with >=100 lines but <250 (D-01 warn band)
+    "blockers": 0     // skills with any block-level error (>=250 lines,
+                      //   missing frontmatter field, description out of
+                      //   range, disable-model-invocation non-whitelisted)
+  },
+  "skills": [
+    {
+      "name": "...",           // skill folder name (matches skills/<name>/SKILL.md)
+      "path": "...",           // absolute path to the file on disk
+      "lines": 0,              // wc -l semantics
+      "descriptionLength": 0,  // length of frontmatter.description string
+      "hasRequiredFields": true,
+      "level": "clean",        // "clean" | "warn" | "block"
+      "errors": [{ "code": "...", "message": "..." }],
+      "warnings": [{ "code": "...", "message": "..." }],
+      "reasons": ["..."]       // human-readable summary lines
+    }
+  ]
+}
+```
+
+## Render contract
+
+The health skill prints two lines after the existing checks table:
+
+```
+Skill-length: <total> total | <clean> clean | <warnings> warn (>=100) | <blockers> block (>=250)
+  All skills within contract.
+```
+
+If `summary.blockers > 0`, replace the second line with one indented row per
+blocker entry (skills where `level === "block"`):
+
+```
+Skill-length: 70 total | 67 clean | 2 warn (>=100) | 1 block (>=250)
+  - <name> (<lines> lines)
+```
+
+## Thresholds (D-01)
+
+- `warn >=100` - skill flagged as advisory; CI emits `::warning::` annotation
+  but does not fail the build.
+- `block >=250` - skill flagged as blocker; CI emits `::error::` and fails
+  the build via exit code 2.
+
+## Strict description-format (D-02)
+
+`STRICT_DESCRIPTION=1` / `--strict-description` is OFF by default. Phase 33
+will graduate the strict `<what>. Use when <triggers>.` regex from advisory
+to hard-block based on A/B evidence at
+`.design/research/description-format-ab.md`.
+
+## Cross-link from health
+
+- `skills/health/SKILL.md` - emits the report after the main checks table.
+- `scripts/validate-skill-length.cjs` - provides the JSON.
+- `tests/phase-28.5-baseline.test.cjs` - locks the post-rework distribution.

package/scripts/skill-templates/help/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: gdd-help
+description: "Lists all available get-design-done commands with one-line descriptions"
+tools: Read
+disable-model-invocation: true
+---
+
+# Get Design Done - Help
+
+**Role:** Print a complete, formatted reference of every `{{command_prefix}}` command with a one-line description. The list is built from the skill manifest at runtime so it can never drift from the installed skills.
+
+---
+
+## Procedure
+
+1. **Read the manifest.** Open `scripts/lib/manifest/skills.json`. Its `skills` array is the source of truth: one object per skill, each with a `name` (the command, used as `{{command_prefix}}<name>`) and a `description`. Some records also carry `user_invocable`, `disable_model_invocation`, `composes_with`, `next_skills`, and `registered_in_phase` - use those only to refine grouping, never to drop a skill.
+
+2. **Cover every skill.** The output must include every object in `skills` exactly once. Do not hardcode a command list and do not print a fixed count - the only authority is the manifest you just read. If a skill is in the manifest, it appears in the help; if it is removed from the manifest, it disappears from the help automatically.
+
+3. **One-line each.** For every skill, emit `{{command_prefix}}<name>` followed by a single condensed line drawn from its `description`. Trim each description to its first sentence (cut at the first sentence-ending period) so the table stays scannable. Strip any leading "Stage N of 5" boilerplate into a short `Stage N` tag where it helps. Never invent a description - if a record has only a terse `description`, use it verbatim (condensed).
+
+4. **Group sensibly.** The manifest has no explicit category field, so derive groups from what each skill does and lead with the ones users reach for first. A good order:
+   - **Pipeline stages (run in order):** `brief`, `explore`, `plan`, `design`, `verify` - the five-stage spine, in that sequence.
+   - **Standalone analysis:** one-shot audits and deltas (for example `style`, `darkmode`, `compare`, `audit`, `start`).
+   - **Navigation and status:** `next`, `help`, `progress`, `health`, `stats`, `quick`, `fast`.
+   - **Exploration and ideation:** `discuss`, `list-assumptions`, `sketch`, `sketch-wrap-up`, `spike`, `spike-wrap-up`, `map`, `bootstrap-ds`.
+   - **Lifecycle and session:** `new-project`, `new-cycle`, `complete-cycle`, `pause`, `resume`, `continue`, `do`, `ship`, `pr-branch`, `undo`.
+   - **Everything else:** every remaining skill not yet listed, alphabetically. This catch-all is what guarantees completeness - sweep the manifest for any `name` you have not already printed and place it here.
+
+   Grouping is a presentation aid, not a filter. If you are ever unsure where a skill belongs, fall back to a single alphabetical list of all manifest skills - completeness beats tidy buckets.
+
+5. **Render.** Use this header and shape (a fenced reference block):
+
+```
+=== Get Design Done - Command Reference ===
+
+Pipeline stages (run in order):
+  brief              <first sentence of brief.description>
+  explore            <first sentence of explore.description>
+  ...
+
+Standalone analysis:
+  ...
+
+(continue for every group, ending with the alphabetical catch-all)
+```
+
+   Pad command names to a consistent column so descriptions align. Keep the `{{command_prefix}}` convention: show the bare name in the table (it is already understood to be a `{{command_prefix}}` command), and use the full `{{command_prefix}}<name>` form in any surrounding prose.
+
+## Update notice (safe-window surface)
+
+After the command reference, emit the plugin-update banner if one is present:
+
+```bash
+[ -f .design/update-available.md ] && cat .design/update-available.md
+```
+
+Written by `hooks/update-check.sh`; suppressed mid-pipeline and when the latest release is dismissed.
+
+## HELP COMPLETE

package/scripts/skill-templates/instinct/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: gdd-instinct
+description: "Inspects and manages atomic instinct learning units - small, scoped, confidence-weighted patterns the pipeline accumulates across cycles. Lists the project and global instinct stores, searches them by keyword, and promotes a vetted project instinct to the global store once it has cleared the cross-project gate. Use when the user wants to see what instincts exist, find an instinct by topic, or promote one to global scope. Activates for requests involving instincts, learned patterns, instinct promotion, instinct search, or the instinct store."
+argument-hint: "[list | query <keyword> | promote <id>] [--scope project|global] [--domain <d>]"
+tools: Read, Bash
+user-invocable: true
+---
+
+# {{command_prefix}}instinct
+
+**Role:** Front end for the atomic instinct store. An instinct is a single learned pattern with a trigger, a confidence between 0.3 and 0.9, a domain, and a scope. This skill lists, searches, and promotes instincts. It never edits stored units by hand and never invents new ones - the reflector and `{{command_prefix}}extract-learnings` author them.
+
+The store engine ships at `scripts/lib/instinct-store.cjs` (authored elsewhere - this skill only calls it). Unit shape (YAML frontmatter plus a short body) is specified in `reference/instinct-format.md`. The project store lives at `.design/instincts/instincts.json`; the global store at `~/.claude/gdd/global-instincts.json`.
+
+Invoke the engine with `node`, the same way other skills call a `scripts/lib` helper:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/lib/instinct-store.cjs" <subcommand> [args]
+```
+
+If the engine exposes only a module API rather than a CLI, drive it from a short `node -e` script:
+
+```bash
+node -e "const s=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/instinct-store.cjs'); console.log(JSON.stringify(s.list({scope:process.env.SCOPE})))"
+```
+
+## Invocation Modes
+
+| Command | Behavior |
+|---|---|
+| `{{command_prefix}}instinct list` | Compact table of stored instincts (default mode). |
+| `{{command_prefix}}instinct query "<keyword>"` | Search instincts by keyword; show the top matches. |
+| `{{command_prefix}}instinct promote <id>` | Promote one project instinct to the global store (gated). |
+
+Flags apply across modes:
+
+- `--scope project|global` selects which store to read. Default is `project`.
+- `--domain <d>` filters to one domain (the domain enum is defined in `reference/instinct-format.md`).
+
+## list
+
+Read the requested store and print a compact table. Call `instinct-store.list({ scope, domain, baseDir })`:
+
+```bash
+node -e "const s=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/instinct-store.cjs'); \
+  const rows=s.list({ scope: process.env.SCOPE || 'project', domain: process.env.DOMAIN || undefined }); \
+  console.log(JSON.stringify(rows));"
+```
+
+Render one row per instinct. Keep it scannable:
+
+```
+ID        DOMAIN     CONF   CYCLES  TRIGGER
+in-7f3a   tokens     0.72   3       palette has no neutral ramp
+in-91bc   layout     0.55   2       cards overflow on the 320px breakpoint
+```
+
+- `CONF` is the stored confidence (0.3 to 0.9).
+- `CYCLES` is `cycles_seen`.
+- Truncate `TRIGGER` to keep each line on one row.
+
+If the store is empty, print: `No instincts in the <scope> store yet. Run {{command_prefix}}reflect or {{command_prefix}}extract-learnings to accumulate some.`
+
+## query
+
+Search by keyword and show the closest matches. Call `instinct-store.query(keyword, { scope, baseDir, limit })`. The engine uses an FTS5 index when one is present and falls back to a plain scan otherwise; either path returns the same row shape.
+
+```bash
+node -e "const s=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/instinct-store.cjs'); \
+  const hits=s.query(process.env.KW, { scope: process.env.SCOPE || 'project', limit: 10 }); \
+  console.log(JSON.stringify(hits));"
+```
+
+Print the top matches in the same table shape as `list`, ordered by the engine's relevance ranking. If there are no matches, say so plainly and suggest a broader keyword. Quote multi-word keywords so the shell passes one argument.
+
+## promote
+
+Promote a single project instinct into the global store so it applies across every project. Promotion is **gated**: `instinct-store.promote(id, { baseDir })` only succeeds when the instinct has been seen across at least K cycles (K=2) spanning at least M distinct project ids (M=2). The engine enforces the gate; this skill surfaces the outcome and asks the user to confirm before the write.
+
+Confirm first. Prefer `@clack/prompts`, and fall back to `AskUserQuestion` when it is absent (mirror the probe in `{{command_prefix}}new-skill`):
+
+```bash
+node -e "try { require.resolve('@clack/prompts'); console.log('clack'); } catch { console.log('fallback'); }"
+```
+
+- `clack`: drive `clack.confirm({ message: 'Promote <id> to the global store?' })` from a short Node script.
+- `fallback`: ask the same yes or no question with `AskUserQuestion`.
+
+On a confirmed yes, run the promotion:
+
+```bash
+node -e "const s=require('${CLAUDE_PLUGIN_ROOT}/scripts/lib/instinct-store.cjs'); \
+  console.log(JSON.stringify(s.promote(process.env.ID, {})));"
+```
+
+Branch on the engine result:
+
+- Promotion succeeded: print `Promoted <id> to the global store.` and show the new global row.
+- Gate not met: the engine reports how far the instinct is from the K=2 / M=2 bar. Print that plainly, for example `<id> needs 2 cycles across 2 projects; seen 1 cycle in 1 project so far. Not promoted.` Do not retry and do not force the write.
+- Unknown id: print `No instinct <id> in the project store.` and suggest `{{command_prefix}}instinct list`.
+
+If the user answers no at the confirm step, print `Promotion cancelled.` and exit without writing.
+
+## Do Not
+
+- Do not edit `.design/instincts/instincts.json` or the global store by hand. All writes go through `scripts/lib/instinct-store.cjs`.
+- Do not author new instincts here. The reflector and `{{command_prefix}}extract-learnings` emit units; this skill reads and promotes them.
+- Do not bypass the promotion gate. If the K=2 / M=2 bar is not met, report it and stop.
+- Do not modify `reference/instinct-format.md` or the store engine.
+
+## INSTINCT COMPLETE

package/scripts/skill-templates/list-assumptions/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: gdd-list-assumptions
+description: "Surfaces hidden design assumptions baked into the codebase before planning - pattern-based detection plus user-surfaced items."
+argument-hint: "[--area typography|color|layout|motion|a11y]"
+tools: Read, Grep, Glob
+disable-model-invocation: true
+---
+
+# {{command_prefix}}list-assumptions
+
+**Role:** Surface implicit design assumptions that were never explicitly decided. Output a numbered list tagging each as `[EXPLICIT]` (found in STATE.md/DESIGN-CONTEXT.md decisions) or `[IMPLICIT]` (inferred from code patterns).
+
+## Step 1 - Read explicit decisions
+
+Read `.design/STATE.md` `<decisions>` and `.design/DESIGN-CONTEXT.md` (if present). Collect every D-XX as `[EXPLICIT]` entries keyed by category.
+
+## Step 2 - Scan codebase for implicit patterns
+
+If `--area <name>` is given, restrict to that area. Otherwise scan all.
+
+**Layout**
+- Grep for `@media` queries → "Is mobile-first or desktop-first assumed?"
+- Grep for `grid-template`, `flex-direction` → "Is F-pattern or Z-pattern layout assumed?"
+
+**Typography**
+- Grep for `font-family` declarations → "Does the chosen font stack assume brand acceptance?"
+- Grep for `font-size: [0-9]+px` with varying values → "Is a modular scale assumed or ad-hoc sizing?"
+
+**Color**
+- Grep for hex literals `#[0-9a-fA-F]{3,8}` → "Is the palette assumed to be fixed without a token layer?"
+
+**Motion**
+- Grep for `@keyframes`, `transition`, `animate` → "Does the brand tolerate animation?"
+- Grep for `prefers-reduced-motion` → "Is reduced-motion honored or assumed ignored?"
+
+**A11y**
+- Grep for `aria-`, `role=`, `alt=` coverage → "Is WCAG AA the target, or AAA?"
+- Grep for `outline: none`, `outline: 0` → "Are focus rings intentionally removed?"
+
+For each hit, emit `Detected assumption: [pattern] at [file:line]` and flag as `[IMPLICIT]`.
+
+## Step 3 - Output
+
+```
+━━━ Design assumptions ━━━
+
+Typography
+  01 [EXPLICIT] D-03: Font family Inter
+  02 [IMPLICIT] 18 px font-size values found — scale not explicit (src/Card.css:12, ...)
+
+Color
+  03 [IMPLICIT] 47 hex literals — no token layer (see {{command_prefix}}discuss color)
+
+...
+
+N assumptions total — M implicit.
+Next: {{command_prefix}}discuss --all to resolve implicit ones.
+━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## LIST-ASSUMPTIONS COMPLETE

package/scripts/skill-templates/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
+---
+
+# {{command_prefix}}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