@hegemonart/get-design-done 1.0.7

package/skills/analyze-dependencies/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: gdd-analyze-dependencies
+description: "Queries the intel store to surface token fan-out, component call-graphs, decision traceability, and circular dependency detection. Requires .design/intel/ to exist (run build-intel.cjs first)."
+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.
+
+## Pre-flight check
+
+Before any analysis, 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:
+
+```
+Intel store not found. Build it first:
+  node scripts/build-intel.cjs --force
+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
+
+## Analysis 1 — Token fan-out
+
+**What:** Which design tokens are referenced in the most files? Which are orphaned (defined but never used)?
+
+**Protocol:**
+
+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)
+━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Analysis 2 — Component call-graph
+
+**What:** Which components are referenced most widely? Which files reference a given component?
+
+**Protocol:**
+
+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:
+
+```
+━━━ 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.
+
+## Analysis 3 — Decision traceability
+
+**What:** Which decisions from DESIGN-CONTEXT.md are referenced by which skill/agent files?
+
+**Protocol:**
+
+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
+
+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.
+```
+
+## 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
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+If no cycles: `All clear — no circular dependencies detected.`
+
+## Combined report format
+
+When run without a mode argument, print all four analyses in sequence separated by blank lines. Prefix the overall report with:
+
+```
+━━━ Dependency Analysis ━━━
+Intel store: .design/intel/
+Generated:   <timestamp from files.json>
+Files indexed: <count>
+```
+
+## Required reading (conditional)
+
+@.design/intel/tokens.json (if present)
+@.design/intel/components.json (if present)
+@.design/intel/dependencies.json (if present)
+@.design/intel/decisions.json (if present)
+@.design/intel/graph.json (if present)
+
+## ANALYZE-DEPENDENCIES COMPLETE

package/skills/apply-reflections/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: gdd-apply-reflections
+description: "Review and selectively apply proposals from .design/reflections/<cycle-slug>.md. Diffs each proposal, prompts user to accept/skip/edit, then writes changes."
+argument-hint: "[--cycle <slug>] [--filter <FRONTMATTER|REFERENCE|BUDGET|QUESTION|GLOBAL-SKILL>] [--dry-run]"
+tools: Read, Write, Edit, Bash, Glob
+---
+
+# /gdd:apply-reflections
+
+Interactive proposal review loop. Reads `.design/reflections/<cycle-slug>.md`, walks each numbered proposal, and applies accepted ones to the appropriate target file. Nothing is applied without explicit user confirmation.
+
+## Steps
+
+### 1. Resolve reflections file
+
+- If `--cycle <slug>` given: load `.design/reflections/<slug>.md`
+- Else: glob `.design/reflections/*.md`, sort by modified time descending, load the most recent
+- If no file found: error "No reflections found. Run `/gdd:reflect` first."
+- Print: "Reviewing reflections: <filename>"
+
+### 2. Parse proposals
+
+Scan file for lines matching `### Proposal N — [TYPE] ...`. Extract each proposal block (Why / Change / Risk).
+
+If `--filter <TYPE>` given: skip proposals whose type tag doesn't match.
+
+Print: "Found N proposals (N after filter)."
+
+### 3. Review loop
+
+For each proposal (in order):
+
+Print the full proposal block:
+```
+─────────────────────────────────────────
+Proposal N/TOTAL — [TYPE] Title
+Risk: low|medium
+
+Why: ...
+Change: ...
+─────────────────────────────────────────
+(a) apply   (s) skip   (e) edit   (q) quit
+```
+
+If `--dry-run`: print `[dry-run — would prompt here]` and continue to next proposal without prompting.
+
+Based on user choice:
+- **a** — apply (see Apply Logic below)
+- **s** — mark proposal as `**Reviewed: skipped**` in the reflections file; continue
+- **e** — show the Change text, ask user to provide edited version, then apply the edited version
+- **q** — stop processing; print "Stopped at proposal N. Resume with `/gdd:apply-reflections --cycle <slug>`."
+
+### 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
+
+### 5. Summary
+
+After all proposals processed (or `q`):
+```
+─────────────────────────────────────────
+Apply-reflections complete
+  Applied:  N
+  Skipped:  N
+  Remaining: N (run again to continue)
+─────────────────────────────────────────
+```
+
+## Do Not
+
+- Do not apply any proposal without the user explicitly choosing `a` or `e`.
+- Do not modify source code files (`.ts`, `.tsx`, `.css`, `.js`) — only agent files, reference files, budget.json, discussant questions, and global skills.
+- Do not re-run the reflector — this skill only applies existing proposals.

package/skills/audit/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: gdd-audit
+description: "Run design audit — wraps design-verifier + design-auditor + design-reflector. --retroactive audits the full cycle scope."
+argument-hint: "[--retroactive] [--quick] [--no-reflect]"
+tools: Read, Write, Task, Glob
+---
+
+# /gdd:audit
+
+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.
+
+## Modes
+
+### Default
+Spawn `design-auditor` (6-pillar scoring 1–4) in parallel with `design-integration-checker`. After both finish, read `.design/DESIGN-AUDIT.md` and `.design/DESIGN-INTEGRATION.md` and print a consolidated summary (scores + top 3 findings each).
+
+After the auditor and integration checker complete, check if `.design/learnings/` exists and contains at least one `.md` file. If so — and unless `--no-reflect` is passed — spawn `design-reflector` for the current cycle. Append the reflection proposal count to the audit summary: "Reflection: N proposals → review with `/gdd:apply-reflections`".
+
+### `--retroactive`
+Spawn `design-verifier` with cycle-span scope. Verifier reads all tasks completed in the current cycle (from STATE.md `<completed_tasks>` list for the active `cycle:` ID) and uses `DESIGN-PLAN.md` goals as the reference baseline for what "should have been done." Output: `.design/DESIGN-VERIFICATION.md` with per-task pass/fail.
+
+### `--quick`
+Run only `design-auditor` (skip `design-integration-checker`). Faster health check when integration isn't the concern.
+
+## Steps
+
+1. Parse args for `--retroactive`, `--quick`, and `--no-reflect`.
+2. Verify `.design/STATE.md` exists; abort if not (suggest `/gdd:new-project`).
+3. Spawn the appropriate agents (Task tool). Default and `--retroactive` spawn two agents; `--quick` spawns one.
+4. Wait for completion, then read each output file and print a summary:
+   - Auditor scores per pillar
+   - Integration check pass/fail
+   - Verifier pass/fail per task (retroactive mode)
+5. **Reflection step** (default + retroactive modes only, skipped with `--no-reflect` or `--quick`):
+   - Check if `.design/learnings/` exists and has ≥1 `.md` file
+   - If yes: spawn `design-reflector` for the current cycle slug (read from STATE.md)
+   - After completion: count proposal types and append to summary
+6. Recommend next action based on findings (e.g., "Score 2/4 on typography — run `/gdd:discuss typography` to gather decisions").
+
+## Registered Audit Agents
+
+| Agent | Trigger | Output |
+|---|---|---|
+| `design-auditor` | Default, retroactive | `.design/DESIGN-AUDIT.md` |
+| `design-integration-checker` | Default, retroactive | `.design/DESIGN-INTEGRATION.md` |
+| `design-verifier` | `--retroactive` only | `.design/DESIGN-VERIFICATION.md` |
+| `design-reflector` | Default + retroactive when learnings exist | `.design/reflections/<slug>.md` |
+
+## Do Not
+
+- Do not modify source files.
+- Do not rerun stages; this is a read-only audit.
+
+## AUDIT COMPLETE

package/skills/brief/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: gdd-brief
+description: "Design intake — captures problem statement, audience, constraints, success metrics, and scope into .design/BRIEF.md (Stage 1 of 5)"
+argument-hint: "[--re-brief to redo intake on existing project]"
+tools: Read, Write, AskUserQuestion
+---
+
+# Get Design Done — Brief
+
+**Role:** You are the Brief stage. Stage 1 of 5 in the get-design-done pipeline.
+
+**Purpose:** Capture the design problem before any scanning or exploration. Produces `.design/BRIEF.md`.
+
+---
+
+## Step 1 — Check for existing BRIEF.md
+
+1. Read `.design/BRIEF.md` if it exists.
+2. Parse it into sections: Problem, Audience, Constraints, Success Metrics, Scope.
+3. Note which sections are already answered (non-empty).
+4. If `--re-brief` flag is passed, ignore existing answers and ask all five questions.
+5. Otherwise, only ask questions for unanswered sections.
+
+## Step 2 — Interview
+
+Ask the following one at a time using `AskUserQuestion`, only for unanswered sections:
+
+1. **Problem** — "What design problem are we solving? (user-facing outcome)"
+2. **Audience** — "Who is the primary audience? (role, device, context)"
+3. **Constraints** — "What constraints apply? (tech stack, brand, time, a11y requirements)"
+4. **Success Metrics** — "How will we measure success? (specific metrics or outcomes)"
+5. **Scope** — "What is in/out of scope for this cycle?"
+
+Do not proceed to the next question until the current one is answered.
+
+## Step 3 — Write .design/BRIEF.md
+
+Write the brief with these sections, preserving any pre-existing answers:
+
+```markdown
+# Design Brief — <project name>
+
+## Problem
+<answer>
+
+## Audience
+<answer>
+
+## Constraints
+<answer>
+
+## Success Metrics
+<answer>
+
+## Scope
+<answer>
+```
+
+## Step 4 — Update STATE.md
+
+- If `.design/STATE.md` does not exist, create it from `reference/STATE-TEMPLATE.md`.
+- Set frontmatter `stage: explore` (next stage).
+- Update `last_checkpoint` to now.
+- Write STATE.md.
+
+## After Writing
+
+```
+━━━ Brief complete ━━━
+Saved: .design/BRIEF.md
+Next: @get-design-done explore
+━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## BRIEF COMPLETE

package/skills/cache-manager/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: gdd-cache-manager
+description: "Maintains .design/cache-manifest.json for Layer B explicit cache per D-08. Computes deterministic SHA-256 input-hash from (agent-path + sorted-input-file-paths + input-content-hashes). On spawn: lookup key → return cached blob if within TTL, else miss. On completion: write result + TTL. Consulted by hooks/budget-enforcer.js before every Agent spawn."
+user-invocable: false
+tools: Read, Bash, Write
+---
+
+# gdd-cache-manager
+
+## Role
+
+You are the deterministic cache-key computer and cache-manifest writer for the optimization layer. You do not spawn agents, and you do not make model calls. You read agent paths, input file paths, and input file contents; you compute a stable SHA-256 key; you look that key up in `.design/cache-manifest.json`; you return a hit (cached result + `cache_hit: true`) or a miss. On spawn completion, the orchestrator calls you again to persist the result. You are Layer B of the two-layer cache (D-08). Layer A — Anthropic's 5-min prompt cache — is not owned by you; it's owned by the shared-preamble ordering convention in `agents/README.md`.
+
+## Invocation Contract
+
+### Phase 1: compute-key
+
+- **Input**: `{agent_path: string, input_file_paths: string[]}` — `agent_path` is the absolute or repo-relative path to the `agents/<name>.md` file; `input_file_paths` is the sorted-unique list of files the agent will read.
+- **Output**: `{input_hash: string}` — 64-character lowercase SHA-256 hex.
+- **Algorithm**: canonicalize inputs, concat with newline separators, SHA-256 (see Deterministic Input-Hash Algorithm below).
+
+### Phase 2: lookup
+
+- **Input**: `{input_hash: string}`
+- **Output**: `{hit: true, result: string, expires_at: string} | {hit: false}`
+- Reads `.design/cache-manifest.json`. If key absent → miss. If present and `Date.now() >= entry.expires_at` → miss (lazy cleanup: caller may evict but is not required to). Else → hit with `entry.result`.
+
+### Phase 3: short-circuit-or-miss
+
+- On hit: orchestrator short-circuits the spawn. Budget-enforcer hook (Plan 10.1-01) emits `SkippedCached` telemetry with `tokens_in: 0, tokens_out: 0, cache_hit: true, est_cost_usd: 0` (writer lands in Plan 10.1-05). Returns cached `result` as the tool output.
+- On miss: orchestrator proceeds with real spawn. Cache-manager is not involved until Phase 4.
+
+### Phase 4: write-result-on-completion
+
+- **Input**: `{input_hash: string, agent: string, result: string, ttl_seconds: number}` — `ttl_seconds` defaults to `.design/budget.json.cache_ttl_seconds` (3600 if budget.json absent).
+- **Behavior**: open `.design/cache-manifest.json` (create if missing), set key `input_hash` → `{agent, result, written_at, ttl_seconds, expires_at}`, write file. `written_at` is `new Date().toISOString()`. `expires_at` is `written_at + ttl_seconds` as ISO.
+
+## Deterministic Input-Hash Algorithm
+
+The canonical reference implementation (the single source of truth; `hooks/budget-enforcer.js` will import the same primitive via a shared helper in Plan 10.1-05 when telemetry lands):
+
+```js
+// Deterministic cache-key primitive (reference implementation)
+// hash = SHA-256(
+//   agent_path + "\n" +
+//   sorted(input_file_paths).join("\n") + "\n" +
+//   sorted(input_file_paths)
+//     .map(p => sha256(readFileSync(p, "utf8")))
+//     .join("\n")
+// )
+const crypto = require('crypto');
+const fs = require('fs');
+
+function sha256Hex(s) {
+  return crypto.createHash('sha256').update(s, 'utf8').digest('hex');
+}
+
+function computeInputHash(agentPath, inputFilePaths) {
+  const sortedPaths = [...inputFilePaths].sort();
+  const contentHashes = sortedPaths.map(p => {
+    try { return sha256Hex(fs.readFileSync(p, 'utf8')); }
+    catch { return 'MISSING'; }
+  });
+  const canonical = [
+    agentPath,
+    sortedPaths.join('\n'),
+    contentHashes.join('\n')
+  ].join('\n');
+  return sha256Hex(canonical);
+}
+```
+
+Notes for maintainers:
+
+- **Sorted-unique paths** — ordering must be stable; caller is expected to de-duplicate. If the same path appears twice the hash still matches as long as caller pre-dedupes before invoking.
+- **Missing file** — the string `MISSING` is used in place of the content hash so a missing dependency doesn't silently collide with an empty file (empty file's SHA-256 is `e3b0c44...`). Missing-file hashes naturally miss on the next read because the real file has a different content hash.
+- **Agent-path** — agents changing their own body (role, tools, output contract) invalidate all their cache entries automatically because the agent file's content is not hashed; but the `agent_path` string is concatenated. Upgrading agents between versions naturally busts the cache only when the path changes. Plan 10.1-04 (shared preamble extraction) is expected to slightly adjust agent bodies — consumers should treat the first post-10.1 run as a full cache miss, which is the intended behavior.
+
+## Manifest Shape
+
+See `reference/config-schema.md` §.design/cache-manifest.json Schema (Phase 10.1) for the authoritative schema. Keyed object, flat SHA-256 hex keys. Example:
+
+```json
+{
+  "a3f1e...": {
+    "agent": "design-verifier",
+    "result": "<base64-or-path>",
+    "written_at": "2026-04-18T12:00:00Z",
+    "ttl_seconds": 3600,
+    "expires_at": "2026-04-18T13:00:00Z"
+  }
+}
+```
+
+## Integration Points
+
+- **`hooks/budget-enforcer.js`** (Plan 10.1-01) reads the manifest on every Agent spawn. The hook already calls `cacheLookup(agent, inputHash)` against `.design/cache-manifest.json`. This skill is the authority on how `inputHash` is computed so the hook and any orchestrator agree byte-for-byte.
+- **Orchestrators** (e.g., `skills/map/`, `skills/discover/`, `skills/plan/`) invoke Phase 1 (compute-key) + Phase 4 (write-result-on-completion) around each Agent spawn they launch. Phase 2 + Phase 3 are executed by the hook.
+- **Warm-cache command** (`skills/warm-cache/SKILL.md`, Task 02) does not touch Layer B — it only primes Anthropic's 5-min prompt cache (Layer A). Do not confuse the two.
+
+## Failure Modes
+
+- `.design/cache-manifest.json` missing or malformed → treat every lookup as miss; orchestrator proceeds with full spawn. Do not throw.
+- File system write fails on Phase 4 → log to stderr, do not throw (the spawn already completed successfully; losing a cache write is a performance regression, not a correctness bug).
+- `agent_path` file missing → compute hash anyway using the provided string; cache entries for a deleted agent simply never hit again.
+
+## Non-Goals
+
+Per D-09:
+
+- No semantic / graph-based lookup. Manifest is a dumb KV store keyed by content hash.
+- No cross-project cache sharing. Manifest lives at `.design/cache-manifest.json`, scoped per repo.
+- No eviction beyond lazy expiry on read. A `/gdd:cache-prune` command is a Phase 11 reflector candidate, not 10.1 scope.
+- No hash-algorithm tuning. SHA-256 is fixed; if a future phase wants BLAKE3, bump the manifest schema version (not relevant in v1).
+
+## TTL Semantics
+
+- Default `ttl_seconds` = `.design/budget.json.cache_ttl_seconds` = 3600s (1 hour) per D-10.
+- `expires_at` is computed at write time and stored; readers do not recompute.
+- Lazy cleanup: stale entries are not actively deleted on read (overhead for no benefit in normal operation). A separate reaper is optional and out of v1 scope.