@hegemonart/get-design-done 1.59.2 → 1.59.4

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

@@ -0,0 +1,145 @@
+---
+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 {{command_prefix}}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
+---
+
+# 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>
+
+<prior-research>
+<!-- Phase 38: populated by agents/user-research-synthesizer.md from UserTesting/Maze/Hotjar
+     (pseudonymized) — ranked findings {finding · frequency · severity}. Empty on a fresh brief;
+     the verify stage cross-checks each finding (addressed or explicitly deferred). -->
+</prior-research>
+```
+
+Leave the `<prior-research>` block empty on a greenfield brief - it is filled by `{{command_prefix}}research-sync` (the `user-research-synthesizer`) when a research source is connected, and re-checked at verify. See `reference/design-variants.md` for the outcome loop.
+
+## Step 4 - Bootstrap STATE.md (if missing)
+
+<!-- BOOTSTRAP EXCEPTION: STATE.md does not exist yet — MCP tools require it to exist. Direct Write is intentional. All subsequent mutations use MCP. -->
+
+If `.design/STATE.md` does not exist, copy the template block from `reference/STATE-TEMPLATE.md` (between `==== BEGIN TEMPLATE ====` and `==== END TEMPLATE ====`) to `.design/STATE.md` via `Write`. Leave the `<ISO 8601 timestamp>` placeholders in-place - Step 5 stamps them via MCP. If STATE.md already exists, skip to Step 5.
+
+## Step 5 - Commit STATE.md initialization
+
+With `.design/STATE.md` seeded from the template:
+
+1. Stamp timestamps + cycle id: call `mcp__gdd_state__frontmatter_update` with `patch: { started_at: <ISO>, last_checkpoint: <ISO>, cycle: <cycle-id> }`.
+2. Mark brief progress: call `mcp__gdd_state__update_progress` with `task_progress: "5/5"`, `status: "brief_complete"`.
+3. Set handoff status: call `mcp__gdd_state__set_status` with `status: "brief_complete"`.
+
+Do NOT call `mcp__gdd_state__transition_stage` from brief - explore calls it on entry, keeping the transition atomic with the stage that owns the new state.
+
+## Step 6 - Inline glossary (CONTEXT.md) + ADR pointer
+
+When a fuzzy phrase is resolved or a new domain concept is named during the briefing
+interview: write to `./CONTEXT.md` IMMEDIATELY per `./../../reference/context-md-format.md`
+(H2 heading + body; lazy-create on first term; no batching). Glossary entries compound
+across cycles - token savings + naming consistency.
+
+Project-shaping decisions surfaced in briefing can be promoted to an ADR - see
+`./../../reference/adr-format.md` for the 3-criteria gate (hard-to-reverse AND
+surprising-without-context AND real-tradeoff). Routine choices stay in STATE.md.
+
+## After Writing
+
+```
+━━━ Brief complete ━━━
+Saved: .design/BRIEF.md
+Next: @get-design-done explore
+━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Spec self-review (before transition)
+
+Run this final spec-quality pass over `.design/BRIEF.md` before the brief→explore transition:
+- Placeholder scan: no TBD / TODO / `<placeholder>` / lorem left in the artifact.
+- Internal consistency: sections don't contradict each other.
+- Scope check: nothing in the artifact exceeds (or silently drops) the agreed scope.
+- Ambiguity check: every requirement/decision is specific enough to act on without a follow-up question.
+
+## Optional brief audit (non-blocking)
+
+Before the gate, you MAY spawn `agents/brief-auditor.md` via `Task` to grade the brief against the five
+brief anti-patterns (vague verbs, missing audience, immeasurable success criteria, scope creep, missing
+anti-goals). The auditor reads `.design/BRIEF.md` plus `reference/brief-quality-rubric.md` and writes
+advisory findings to `.design/BRIEF-AUDIT.md`. This step is advisory and MUST NOT block the brief to
+explore transition.
+
+If the auditor reports one or more fired anti-patterns, surface a single-line pointer to the user:
+
+```
+Brief audit flagged N issue(s) - run {{command_prefix}}discuss brief to refine, or proceed to explore.
+```
+
+The user decides. Proceeding to explore with a flagged brief is allowed; the pointer is a nudge, not a gate.
+If the auditor reports no fired anti-patterns, or you skip the audit, continue to the gate unchanged.
+
+<HARD-GATE>
+Do NOT transition to explore (or invoke `{{command_prefix}}explore`) until the brief artifact (default `.design/BRIEF.md`) is committed AND the user has approved it. If this project uses a custom `.design` location, read the artifact path from `.design/STATE.md` rather than assuming the default.
+</HARD-GATE>
+
+## Rationalizations - Thought to Reality
+
+The excuses an agent invents to skip or shortcut the brief, and what each one actually costs the cycle:
+
+| Thought | Reality |
+|---------|---------|
+| "This brief is too simple to need a problem statement." | Skip the brief = guess at requirements, then redesign mid-design when the real problem surfaces. |
+| "The user told me what to build, I can skip the interview." | Unasked constraints (a11y, brand, stack) become rework - the five questions exist because each one has blown a past cycle. |
+| "I'll capture success metrics later in verify." | Verify has nothing to check against; an un-metricked brief produces an un-verifiable cycle. |
+| "Scope is obvious, I don't need an in/out line." | Undeclared scope is scope creep waiting to happen - the explore scan widens to fill the vacuum. |
+| "I can answer all five questions for the user from context." | AskUserQuestion one-at-a-time exists because batched/assumed answers smuggle in wrong premises that compound downstream. |
+| "STATE.md bootstrap can wait." | Every later MCP mutation requires STATE.md to exist; skipping the bootstrap hard-blocks explore on entry. |
+
+## BRIEF COMPLETE

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

@@ -0,0 +1,45 @@
+---
+name: gdd-budget
+description: "Forecasts GDD design-cycle spend before the bill arrives. Reads .design/telemetry/costs.jsonl (cost per cycle) + .design/budget.json (the project_cap), runs the pure cost-forecast model via agents/cost-forecaster.md, and projects the next N cycles - surfacing 'at the current rate you'll hit your $X project cap in Y cycles.' Supports --scenario best|typical|worst and --cycles N. Read-only - it forecasts and warns; it never spends, edits budget.json, or halts (the budget-enforcer hook halts). Use to sanity-check spend trajectory before a long run."
+argument-hint: "[--cycles N] [--scenario best|typical|worst]"
+user-invocable: true
+tools: Read, Bash, Grep, Glob, ToolSearch, Task
+---
+
+# {{command_prefix}}budget
+
+Closes the long-horizon cost gap: Phase 10.1 per-task caps + Phase 26 per-runtime telemetry track
+*cost*, but nothing **forecasts** it. This skill projects the next N cycles of spend and tells you how
+many cycles you have before you hit your `project_cap`. **Read-only** - it forecasts and warns; it
+never spends, never edits `budget.json`, and never halts (the Phase 25 budget-enforcer hook is the
+only thing that blocks a spawn). Contract: `../../reference/cost-governance.md`.
+
+## Invocation
+
+| Command | Behavior |
+|---|---|
+| `{{command_prefix}}budget` | Typical-scenario forecast over the next 5 cycles + cycles-to-cap. |
+| `{{command_prefix}}budget --cycles N` | Forecast over the next N cycles. |
+| `{{command_prefix}}budget --scenario best\|typical\|worst` | Pick the projection rate (best / steady / worst). |
+
+## Steps
+
+1. **Check telemetry exists.** No `.design/telemetry/costs.jsonl` (or zero rows) → print
+   `budget: no cost telemetry yet — run a cycle first.` and exit.
+2. **Delegate to `cost-forecaster`** (via `Task`): it groups `est_cost_usd` by `cycle`, runs the pure
+   `scripts/lib/budget/cost-forecast.cjs` model for the requested `--scenario`/`--cycles`, reads
+   `project_cap_usd` from `.design/budget.json`, and computes cycles-to-cap.
+3. **Render.** Show: the scenario + its per-cycle rate, the best↔worst band, the projected total over
+   N cycles, and - when `project_cap_usd > 0` - **"at the `<scenario>` rate (~$X/cycle) you'll reach
+   your $`<cap>` project cap in `<Y>` cycles"** (or "not at this rate" when the trend is flat/down).
+   When no cap is set, show the trajectory and note that `project_cap_usd` is unset (so the hook won't
+   halt).
+4. **Do not act.** Never raise/lower the cap, never spend - GDD forecasts; the human sets the budget.
+
+## Output
+
+End with:
+
+```
+## BUDGET COMPLETE
+```

package/scripts/skill-templates/cache-manager/SKILL.md

@@ -0,0 +1,66 @@
+---
+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.ts before every Agent spawn."
+user-invocable: false
+tools: Read, Bash, Write
+disable-model-invocation: true
+---
+
+# 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 (single source of truth; `hooks/budget-enforcer.ts` imports the same primitive via a shared helper) lives in `./cache-policy.md#deterministic-input-hash-algorithm-layer-b` - it documents the JS implementation, the maintainer notes (sorted-unique paths, MISSING-file sentinel, agent-path bust behavior), the manifest shape, and TTL semantics in one place. Conform to the algorithm exactly so the hook and any orchestrator agree byte-for-byte.
+
+## Integration Points
+
+- **`hooks/budget-enforcer.ts`** (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 `{{command_prefix}}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. Stale entries are lazily cleaned on read (no eager reaper in v1). Full TTL discussion: `./cache-policy.md#ttl-semantics-layer-b`.

package/scripts/skill-templates/cache-manager/cache-policy.md

@@ -0,0 +1,126 @@
+---
+name: cache-policy
+type: heuristic
+version: 1.0.0
+phase: 28.5
+tags: [cache, layer-a, layer-b, sha-256, ttl, warm-cache, cache-manager, anthropic-prompt-cache]
+last_updated: 2026-05-18
+---
+
+# Cache Policy (Layer A + Layer B)
+
+Extracted from `skills/cache-manager/SKILL.md` and `skills/warm-cache/SKILL.md` per Phase 28.5
+D-10 (extract-then-link, never delete content). The two skills keep their orchestration
+contracts and step-by-step flows; the deeper algorithmic and operational detail moves here
+so the SKILLs stay under the 100-line cap.
+
+The two layers (D-08):
+
+- **Layer A** - Anthropic's 5-min prompt cache (owned by `warm-cache`). Keyed on shared-preamble-first prompt prefix. No project-local state.
+- **Layer B** - explicit `.design/cache-manifest.json` (owned by `gdd-cache-manager`). Keyed on deterministic SHA-256 of `(agent-path, sorted-input-file-paths, input-content-hashes)`. Per-repo state.
+
+## Deterministic Input-Hash Algorithm (Layer B)
+
+The canonical reference implementation (the single source of truth; `hooks/budget-enforcer.ts` imports the same primitive via a shared helper):
+
+```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 (Layer B)
+
+See `./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"
+  }
+}
+```
+
+## TTL Semantics (Layer B)
+
+- 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.
+
+## Concrete Warm-Cache Command Examples (Layer A)
+
+Full invocation:
+
+```
+$ {{command_prefix}}warm-cache
+
+Warming Anthropic prompt cache for 14 agents (5 min TTL)...
+[1/14] design-verifier ... ok (0.3s)
+[2/14] design-planner ... ok (0.3s)
+[3/14] design-integration-checker ... ok (0.3s)
+...
+[14/14] design-reflector ... ok (0.3s)
+
+## Warm-cache complete
+- Agents warmed: 14
+- Skipped (no shared preamble import): 3  (agents/README.md not an agent; 2 agents not yet migrated to shared preamble)
+- Duration: 4.2s
+- Next 5 min: repeated spawns of these agents pay cached_input_per_1m rate
+```
+
+Filtered invocation:
+
+```
+$ {{command_prefix}}warm-cache --agents design-verifier,design-planner
+
+Warming Anthropic prompt cache for 2 agents (filtered from 14)...
+[1/2] design-verifier ... ok (0.3s)
+[2/2] design-planner ... ok (0.3s)
+
+## Warm-cache complete
+- Agents warmed: 2
+- Filtered out by --agents: 12
+- Duration: 0.7s
+```
+
+## Cost Model (Layer A)
+
+- Each no-op Haiku ping: ~50 input tokens (shared preamble + "No-op warm: acknowledge..." system+user) + ~5 output tokens ("ok").
+- At Haiku rates (`./model-prices.md`): `(50 / 1e6) * 1.00 + (5 / 1e6) * 5.00 = $0.00005 + $0.000025 = $0.000075` per agent.
+- 14 agents × $0.000075 = **$0.00105** total for a full warm-cache invocation.
+- Payback: a single subsequent Opus spawn with 40k cached input tokens saves `(40000/1e6) * (15.00 - 1.50) = $0.54`. Warm-cache pays for itself ~500× over on the first repeated planner spawn.

package/scripts/skill-templates/check-update/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: gdd-check-update
+description: "Manual plugin-update check. Shows cached state by default; --refresh bypasses the 24h TTL; --dismiss hides the nudge until a newer release ships; --prompt spawns design-update-checker for a richer summary."
+argument-hint: "[--refresh] [--dismiss] [--prompt]"
+tools: Read, Write, Bash, Task
+---
+
+# {{command_prefix}}check-update
+
+**Role:** Manual entry point for the plugin-update checker. The SessionStart hook (`hooks/update-check.sh`) already runs on its own 24h cadence and writes `.design/update-cache.json` + `.design/update-available.md`. This command lets the user inspect / force / dismiss / enrich that state on demand. See `./reference/heuristics.md` §"Version-cadence" for the off-cadence / preview-suffix handling background.
+
+## Flags
+
+| Flag | Effect |
+|------|--------|
+| *(none)* | Print cached state. If cache is older than 24h, trigger `--refresh` implicitly. |
+| `--refresh` | Invoke `hooks/update-check.sh --refresh` - bypasses the 24h TTL and re-fetches immediately. |
+| `--dismiss` | Write `update_dismissed: "<latest_tag>"` to `.design/config.json` atomically and delete `.design/update-available.md`. Sticky until a newer release ships. |
+| `--prompt` | Spawn `design-update-checker` agent (Haiku) to produce a 3–5-line "what this release changes for you" summary. Does not alter the banner or cache. |
+
+Flags combine: `--refresh --prompt` is valid (re-fetch, then enrich). `--dismiss` is the only flag that mutates `.design/config.json`.
+
+## Steps
+
+1. **Parse flags.** Detect `--refresh`, `--dismiss`, `--prompt` in `$ARGUMENTS`. Unknown flag → `Unknown flag: <flag>` and exit.
+
+2. **`--refresh` path** (if set):
+
+    ```bash
+    bash "${CLAUDE_PLUGIN_ROOT:-$(pwd)}/hooks/update-check.sh" --refresh
+    ```
+
+    This re-fetches `/releases/latest`, rewrites `.design/update-cache.json`, and re-renders `.design/update-available.md` subject to state/dismissal gates.
+
+3. **Read cache.** After any optional refresh, read `.design/update-cache.json`. If missing: print `No cache. Network may be unreachable or the hook has not run yet. Try {{command_prefix}}check-update --refresh.` and exit.
+
+4. **`--dismiss` path** (if set): Compute new config contents and write atomically via the env-prefix Python heredoc pattern below. The pattern is essential - passing variables as trailing `KEY=VALUE` argv treats them as `sys.argv`, not `os.environ`. Use env-prefix form only.
+
+    ```bash
+    CONFIG_PATH=".design/config.json"
+    LATEST_TAG="$(grep -E '"latest_tag"' .design/update-cache.json | head -n1 | sed -E 's/.*"latest_tag"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/')"
+    [ -n "$LATEST_TAG" ] || { echo 'No latest_tag in cache — nothing to dismiss.'; exit 0; }
+    mkdir -p .design
+    CONFIG_PATH="$CONFIG_PATH" LATEST_TAG="$LATEST_TAG" python3 <<'PY'
+    import json, os, sys, tempfile
+    config_path = os.environ['CONFIG_PATH']
+    latest_tag = os.environ['LATEST_TAG']
+    try:
+        with open(config_path, 'r', encoding='utf-8') as f:
+            data = json.load(f)
+        if not isinstance(data, dict): data = {}
+    except (FileNotFoundError, json.JSONDecodeError): data = {}
+    data['update_dismissed'] = latest_tag
+    target_dir = os.path.dirname(config_path) or '.'
+    fd, tmp_path = tempfile.mkstemp(prefix='config.', suffix='.tmp', dir=target_dir)
+    try:
+        with os.fdopen(fd, 'w', encoding='utf-8') as f:
+            json.dump(data, f, indent=2); f.write('\n')
+        os.replace(tmp_path, config_path)
+    except Exception:
+        try: os.unlink(tmp_path)
+        except OSError: pass
+        sys.exit(1)
+    PY
+    rm -f .design/update-available.md
+    echo "Dismissed $LATEST_TAG. The nudge will return when a newer release ships."
+    ```
+
+    D-14 atomic-write invariant: `os.replace()` (POSIX `rename(2)`) is atomic on the same filesystem. The `json.load → set single key → json.dump` round-trip preserves every unknown top-level key (e.g. `model_profile`, `parallelism`) verbatim.
+
+5. **Print default state** (always, unless exited early):
+
+    ```
+    ━━━ {{command_prefix}}check-update ━━━
+    Current:   v<X.Y.Z>
+    Latest:    v<A.B.C>   (delta: <major|minor|patch|off-cadence|none>)
+    Newer:     <true|false>
+    Checked:   <ISO time of checked_at>
+    Dismissed: <tag or "no">
+    ━━━━━━━━━━━━━━━━━━━━━━━━━━
+    ```
+
+    Parse fields from `.design/update-cache.json` via `grep + sed` (no jq dep). Read dismissal from `.design/config.json` via the same pattern as `hooks/update-check.sh`.
+
+6. **`--prompt` path** (if set): Spawn `design-update-checker` via Task tool with context `{current_tag, latest_tag, delta, release_body}`. Display response verbatim below the banner. Agent ends with `## UPDATE-CHECKER COMPLETE`.
+
+## Do Not
+
+- Do not fetch from GitHub directly - always go through `hooks/update-check.sh --refresh` so caching + state-guard + dismissal logic stays in one place.
+- Do not modify `.design/update-available.md` except to delete on `--dismiss`.
+- Do not rewrite `.design/config.json` wholesale - the atomic Python rewrite preserves every unknown key (D-14).
+- Do not pass variables to the Python heredoc via trailing `KEY=VALUE` argv - env-prefix form only.
+
+## Completion marker
+
+```
+## CHECK-UPDATE COMPLETE
+```

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

@@ -0,0 +1,82 @@
+---
+name: gdd-compare
+description: "Compute the delta between the `DESIGN.md` baseline (from explore) 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
+---
+
+# gdd-compare - Baseline vs Result Delta
+
+Standalone delta command. Computes the difference between the scan baseline (`DESIGN.md`) and the verification result (`DESIGN-VERIFICATION.md`), and flags design drift for any regression not covered by an explicit task in `DESIGN-PLAN.md`. Writes one artifact: `.design/COMPARE-REPORT.md`.
+
+For the full step-by-step methodology (score parsing, set arithmetic for anti-patterns, drift-coverage map, screenshot-delta probe, and `COMPARE-REPORT.md` template), see `./compare-rubric.md`. For the cross-skill output discipline (artifact prefix, completion marker, MUST-NOT-write list, connection-probe pattern), see `../../reference/shared-preamble.md#output-contract-reminders` and `../../reference/shared-preamble.md#connection-handshake-summary`. For the underlying 0–10 category-scoring rubric the delta is computed against, see `../../reference/audit-scoring.md`.
+
+---
+
+## Scope
+
+This command is **standalone** - not a pipeline stage:
+
+- Scoped strictly to delta between two existing files (COMP-02): `DESIGN.md` (baseline, from scan) and `DESIGN-VERIFICATION.md` (result, from verify).
+- Does NOT require or implement a snapshot mechanism - multi-run history is deferred to V2-06.
+- Does NOT mutate any pipeline artifact (`DESIGN.md`, `DESIGN-VERIFICATION.md`, `DESIGN-SUMMARY.md`, `DESIGN-CONTEXT.md`, `DESIGN-PLAN.md`, `.design/STATE.md`).
+- Writes exactly ONE file: `.design/COMPARE-REPORT.md`.
+- Output artifact prefix `COMPARE-REPORT` is distinct from the pipeline namespace (`DESIGN-*.md`). No naming conflict.
+
+---
+
+## Pre-Flight Checks (Pitfall 3)
+
+Required files - abort if either is missing:
+
+- `.design/DESIGN.md` missing → `"No baseline found. Run /get-design-done scan first."`
+- `.design/DESIGN-VERIFICATION.md` missing → `"No verification result found. Run /get-design-done verify first to produce DESIGN-VERIFICATION.md."`
+
+**Optional files (graceful degradation if absent):**
+
+- `.design/DESIGN-CONTEXT.md` - used for must-have delta. If missing, skip the Must-Have Status section and emit note: `"Must-have delta skipped: DESIGN-CONTEXT.md not found."`
+- `.design/DESIGN-PLAN.md` - used for drift detection. If missing, skip DRIFT flagging and emit note: `"Drift detection skipped: no DESIGN-PLAN.md."`
+
+Confirm `.design/` directory exists. If absent: `mkdir -p .design/`.
+
+Probe `preview` connection per `../../reference/shared-preamble.md#connection-handshake-summary` (ToolSearch → live call → STATE.md write). Result drives Step 5B (screenshot delta).
+
+---
+
+## Workflow
+
+1. **Parse Category Scores** - extract baseline + result score tables, normalize names, flag unmatched. Detail: `./compare-rubric.md#step-1--parse-category-scores`.
+2. **Compute Score Delta** - `delta = result - baseline`, classify (`improvement`/`no_change`/`regression`). Detail: `./compare-rubric.md#step-2--compute-score-delta-comp-03`.
+3. **Anti-Pattern Delta** - set arithmetic on baseline vs result anti-pattern sets (resolved / new / unchanged). Detail: `./compare-rubric.md#step-3--anti-pattern-delta`.
+4. **Must-Have Pass/Fail Change** - read `<must_haves>` from `DESIGN-CONTEXT.md`, status from `DESIGN-VERIFICATION.md`. Detail: `./compare-rubric.md#step-4--must-have-passfail-change`.
+5. **Design Drift Detection (COMP-04)** - build coverage map from `DESIGN-PLAN.md` `Type:` fields; for each `regression` not in coverage_map → emit `DRIFT: [category] ...`. Detail: `./compare-rubric.md#step-5--design-drift-detection-comp-04`.
+6. **Screenshot Delta (preview: available only)** - capture per-route screenshots to `.design/screenshots/{before,after}/<route>.png`. Detail: `./compare-rubric.md#step-5b--screenshot-delta-when-preview-available`.
+7. **Write `.design/COMPARE-REPORT.md`** - full template at `./compare-rubric.md#step-6--compare-reportmd-template`.
+
+---
+
+## Constraints
+
+This command MUST NOT (per `../../reference/shared-preamble.md#output-contract-reminders`):
+
+- Write to `DESIGN.md`, `DESIGN-VERIFICATION.md`, `DESIGN-SUMMARY.md`, `DESIGN-CONTEXT.md`, `DESIGN-PLAN.md`, or `.design/STATE.md`.
+- Require or implement a snapshot system (V2-06 deferred).
+- Reinterpret or silently normalize category names that do not match between files - report mismatches in the Notes section.
+- Invoke `design-auditor` or any other pipeline agent.
+- Produce more than one output file: `.design/COMPARE-REPORT.md`.
+
+Must abort with a clear actionable error message if either input file (`DESIGN.md` baseline, `DESIGN-VERIFICATION.md` result) is missing.
+
+---
+
+## Completion
+
+After writing `.design/COMPARE-REPORT.md`, print a summary:
+
+```
+Compare complete. Improvements: N. Regressions: M. Drift flags: K. See .design/COMPARE-REPORT.md.
+```
+
+Where `N` = improvement count, `M` = regression count, `K` = DRIFT-flag count (0 if drift detection was skipped or no regressions). Do not summarize individual issues - the file contains the full detail.
+
+## COMPARE COMPLETE