@hegemonart/get-design-done 1.49.0 → 1.50.0

package/skills/brief/SKILL.md

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

package/skills/compare/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-compare
-description: "Compute the delta between the `DESIGN.md` baseline (from scan) and the `DESIGN-VERIFICATION.md` result (from verify), reporting per-category score delta, anti-pattern delta (resolved vs new), must-have pass/fail change, and design drift (regressions without covering tasks in `DESIGN-PLAN.md`). Use after `verify` to measure whether a design pipeline cycle actually improved the design. Writes `.design/COMPARE-REPORT.md`."
+description: "Compute the delta between the `DESIGN.md` baseline (from scan) and the `DESIGN-VERIFICATION.md` result (from verify), reporting per-category score delta, anti-pattern delta (resolved vs new), must-have pass/fail change, and design drift (regressions without covering tasks in `DESIGN-PLAN.md`). Use after `verify` to measure whether a design pipeline cycle actually improved the design. Writes `.design/COMPARE-REPORT.md`. Activates for requests involving diffing a design baseline against verification output, or a before-after design delta."
 argument-hint: ""
 user-invocable: true
 ---

package/skills/connections/SKILL.md

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

package/skills/darkmode/SKILL.md

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

package/skills/design/SKILL.md

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

package/skills/discover/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: discover
-description: "Stage 1.5 of 4 orchestrator that probes Figma / Refero / Pinterest connections, spawns design-context-builder (auto-detect + interview) and (via lazy gate) design-context-checker (6-dimension validator), producing .design/DESIGN-CONTEXT.md. Use after /gdd:scan when a fast-path context build is wanted instead of the full /gdd:explore."
+description: "Stage 1.5 of 4 orchestrator that probes Figma / Refero / Pinterest connections, spawns design-context-builder (auto-detect + interview) and (via lazy gate) design-context-checker (6-dimension validator), producing .design/DESIGN-CONTEXT.md. Use after /gdd:scan when a fast-path context build is wanted instead of the full /gdd:explore. Activates for requests involving detecting an existing design system, inventorying tokens and components, or onboarding a brownfield repo."
 argument-hint: "[--auto]"
 user-invocable: true
 ---

package/skills/do/SKILL.md

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

package/skills/explore/SKILL.md

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

package/skills/fast/SKILL.md

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

package/skills/health/SKILL.md

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

package/skills/live/SKILL.md

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

package/skills/new-skill/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: gdd-new-skill
+description: "Scaffolds a new Phase-28.5 + Phase-50-compliant skill: gathers a name, a multi-paragraph v3 description, a lifecycle stage, an allowed-tools list, and optional composes_with neighbours, then writes source/skills/<name>/SKILL.md from the pure generator. Use when adding a brand-new gdd skill and you want the frontmatter, length cap, and v3 description form correct from the first commit. Activates for requests involving authoring a skill, scaffolding a command, creating a new SKILL.md, or adding a slash command."
+argument-hint: "<skill-name>"
+tools: Read, Write, Bash, AskUserQuestion
+user-invocable: true
+---
+
+# /gdd:new-skill
+
+**Role:** Interactively scaffold a contract-compliant skill. Gather the fields, then write `source/skills/<name>/SKILL.md` from the pure generator at `scripts/lib/manifest/scaffolder.cjs`. This skill writes ONE source file. It does NOT touch `scripts/lib/manifest/skills.json` and does NOT run the build; it prints the exact follow-up commands instead.
+
+Read `reference/skill-authoring-contract.md` first for the length cap, the frontmatter required fields, and the v3 description form.
+
+## Prompt strategy (clack with a fallback)
+
+Mirror the installer pattern in `scripts/install.cjs`: try `@clack/prompts` lazily, and degrade to `AskUserQuestion` (or plain text) when it is absent. Use this probe at the start:
+
+```bash
+node -e "try { require.resolve('@clack/prompts'); console.log('clack'); } catch { console.log('fallback'); }"
+```
+
+- `clack`: drive `clack.text`, `clack.select`, and `clack.confirm` from a short Node script.
+- `fallback`: ask the same questions with `AskUserQuestion` (one prompt per field), or read plain answers.
+
+Either way the answers feed the same record builder. Never block waiting on a TTY in a non-interactive run; fall back to `AskUserQuestion`.
+
+## Step 1 - Gather the fields
+
+1. **name**: the slug from `$ARGUMENTS` if present, else ask. Must match `^[a-z0-9][a-z0-9-._]*$`. Reject `source/skills/<name>/` collisions.
+2. **description**: a multi-paragraph v3 form. Sentence one is what the skill does. Sentence two is `Use when <triggers>`. Sentence three is `Activates for requests involving <kw1>, <kw2>, <kw3>.` Keep it 20 to 1024 chars.
+3. **lifecycle stage**: pick one of brief / explore / plan / verify / ship / figma / token / report (free text allowed). This seeds the composition suggestions.
+4. **tools**: a comma list (for example `Read, Write, Bash`). Empty means inherit-all.
+5. **composes_with**: auto-suggest neighbours, then confirm. Compute the suggestion list:
+
+```bash
+node -e "
+const s = require('./scripts/lib/manifest/scaffolder.cjs');
+const m = require('./scripts/lib/manifest/skills.json');
+console.log(JSON.stringify(s.suggestComposesWith(process.argv[1], m.skills)));
+" "<name>"
+```
+
+Present the suggestions; let the user accept, edit, or clear them.
+
+## Step 2 - Length pre-check
+
+Before writing, estimate the body length. If the planned body would exceed about 100 lines, warn the user (the authoring contract warns at 100 and blocks at 250) and suggest extracting domain content into a co-located `source/skills/<name>/<topic>.md` reference. The generated skeleton is small; the warning is for the prose the user will add next.
+
+## Step 3 - Write the file
+
+Build the record and render the file with the pure generator, then write it with the Write tool (not shell redirection):
+
+```bash
+node -e "
+const s = require('./scripts/lib/manifest/scaffolder.cjs');
+const rec = s.buildSkillRecord({
+  name: process.env.SK_NAME,
+  description: process.env.SK_DESC,
+  argumentHint: process.env.SK_HINT || undefined,
+  tools: process.env.SK_TOOLS || undefined,
+  userInvocable: process.env.SK_UI === 'true',
+  composesWith: (process.env.SK_COMPOSES || '').split(',').map(x => x.trim()).filter(Boolean),
+});
+process.stdout.write(s.renderSkillMd(rec));
+"
+```
+
+`buildSkillRecord` throws on an invalid name, an out-of-budget description, or a malformed tools list. Surface the thrown message to the user and re-prompt the offending field. Capture stdout and write it verbatim to `source/skills/<name>/SKILL.md` via the Write tool.
+
+## Step 4 - Tell the user the follow-up
+
+The skill stops here by contract. Print the next two commands for the user to run after they add the manifest record:
+
+```
+1. Add a record for "<name>" to scripts/lib/manifest/skills.json
+   (description, argument_hint, tools, user_invocable; put composes_with in extra_frontmatter).
+2. npm run generate:skill-frontmatter && npm run build:skills
+```
+
+Note that `npm run generate:skill-frontmatter:check` and the skills-coverage test stay red until the manifest record exists; that is expected and is the maintainer's step.
+
+## Do Not
+
+- Do not edit `scripts/lib/manifest/skills.json`, `package.json`, or any reference doc.
+- Do not run `build:skills` or `generate:skill-frontmatter` for the user; print the commands.
+- Do not write the SKILL.md with shell redirection; use the Write tool so the content is exact.
+- Do not invent a description; require the v3 three-sentence form from the user.
+
+## NEW-SKILL COMPLETE

package/skills/plan/SKILL.md

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

package/skills/progress/SKILL.md

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

package/skills/quick/SKILL.md

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

package/skills/scan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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 /gdd: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 /gdd: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
 ---

package/skills/ship/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-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

package/skills/verify/SKILL.md

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