@hegemonart/get-design-done 1.59.3 → 1.59.4

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

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

@@ -0,0 +1,171 @@
+---
+name: compare-rubric
+type: heuristic
+version: 1.0.0
+phase: 28.5
+tags: [compare, delta, drift, scoring, rubric, extracted]
+last_updated: 2026-05-18
+---
+
+Source: extracted from `skills/compare/SKILL.md` (Phase 28.5 rework - D-10 extract-then-link).
+The skill's essential workflow stays in `../skills/compare/SKILL.md`; this file holds the
+delta-computation methodology, anti-pattern set arithmetic, drift-detection coverage map,
+and the `COMPARE-REPORT.md` template the skill writes.
+
+# Compare Rubric - Baseline vs Result Delta Methodology
+
+Detailed methodology for the `gdd-compare` standalone command - companion to
+`../skills/compare/SKILL.md`. Read this file when executing a specific compare step (score
+delta math, anti-pattern set arithmetic, drift coverage map, report layout). The SKILL.md
+keeps the essential pre-flight checks + step routing; this file holds the deep methodology.
+
+See `./shared-preamble.md#output-contract-reminders` for the per-skill output discipline and
+`./audit-scoring.md` for the 0–10 category-scoring rubric the delta is computed against.
+
+---
+
+## Step 1 - Parse Category Scores
+
+**Extract baseline scores from `.design/DESIGN.md`:** locate the category score table (rows like `| Accessibility | 6/10 | ... |`). Parse each row: extract category name + numeric score. Store as `baseline_scores` map.
+
+**Extract result scores from `.design/DESIGN-VERIFICATION.md`:** locate the same table in the Phase 1 output section. Store as `result_scores` map.
+
+**Normalize category names:**
+- Strip leading/trailing whitespace.
+- Apply title-case normalization (e.g., `anti-patterns` → `Anti-Patterns`).
+- Match categories case-insensitively between the two tables.
+
+**Unmatched categories:**
+- Baseline-only → flag `[UNMATCHED-BASELINE]`, exclude from score delta.
+- Result-only → flag `[UNMATCHED-RESULT]`, exclude from score delta.
+- Report all unmatched categories in the Notes section. Do NOT silently paper over mismatches.
+
+## Step 2 - Compute Score Delta (COMP-03)
+
+For each matched category: `delta = result_scores[category] - baseline_scores[category]`.
+
+Classify:
+- `improvement` - delta > 0
+- `no_change` - delta == 0
+- `regression` - delta < 0
+
+Record per category: name, baseline score, result score, signed delta, classification. Collect regressed categories for drift detection in Step 5.
+
+## Step 3 - Anti-Pattern Delta
+
+Enumerate anti-patterns in both files (entries identified by BAN-*, SLOP-*, or labeled as anti-patterns). Collect identifiers or descriptions as sets.
+
+Compute set arithmetic:
+
+```
+resolved  = baseline_anti_patterns - result_anti_patterns
+           (present in baseline, absent in result — fixed)
+
+new       = result_anti_patterns - baseline_anti_patterns
+           (absent in baseline, present in result — introduced)
+
+unchanged = intersection of both sets
+           (still present in both)
+```
+
+Report all three groups in the output report.
+
+## Step 4 - Must-Have Pass/Fail Change
+
+**Skip condition:** if `.design/DESIGN-CONTEXT.md` is absent → emit note and skip this section.
+
+Read `<must_haves>` from `DESIGN-CONTEXT.md` (each must-have has ID + description). Read pass/fail status from `DESIGN-VERIFICATION.md` (must-have status table). For each must-have: record `pass`, `fail`, or `not-evaluated`. If `DESIGN.md` contained a prior must-have status section, compute the change (`pass→fail`, `fail→pass`); otherwise report current status only.
+
+## Step 5 - Design Drift Detection (COMP-04)
+
+**Skip condition:** if `.design/DESIGN-PLAN.md` is absent → emit `"Drift detection skipped: DESIGN-PLAN.md not found."` in the Drift section.
+
+**Coverage map:** read `DESIGN-PLAN.md` and extract the `Type:` field from each task. Build a map of which design categories have at least one task of matching Type:
+
+```
+Type: accessibility   → covers "Accessibility" category
+Type: color           → covers "Color" category
+Type: typography      → covers "Typography" category
+Type: visual-hierarchy → covers "Visual Hierarchy" category
+```
+
+Category-to-Type matching is case-insensitive and normalized.
+
+**Drift check:** for each category classified as `regression` in Step 2: if category NOT in coverage_map → emit `DRIFT: [category] regressed from <baseline> to <result> without a design task of Type:<category>`.
+
+Emit `"No drift detected. All regressed categories are covered by tasks in DESIGN-PLAN.md."` if all regressed categories are covered. Emit `"No drift detected. No score regressions found."` if no regressions in Step 2.
+
+## Step 5B - Screenshot Delta (when preview: available)
+
+Check `preview` status from `.design/STATE.md <connections>` (written by the probe at stage entry - see `./shared-preamble.md#connection-handshake-summary`).
+
+**If `preview: available`:**
+
+1. `preview_start` if no session is already running.
+2. For each route inferred from `DESIGN-PLAN.md` tasks or `src/app/` / `src/pages/` file structure:
+   a. `preview_navigate` to route URL (e.g., `http://localhost:3000/<route>`).
+   b. `preview_screenshot` → save to `.design/screenshots/before/<route>.png` (only if a prior baseline exists at this path) and `.design/screenshots/after/<route>.png` (current render).
+   c. Record reference paths (NOT base64) for embedding in the `## Screenshot Delta` section.
+3. `preview_stop` when all routes are captured.
+
+**If `preview: unavailable` or `preview: not_configured`:** emit exactly `Screenshot delta skipped — preview not configured.`
+
+## Step 6 - COMPARE-REPORT.md Template
+
+Output path: `.design/COMPARE-REPORT.md`. This file MUST NOT be written to any pipeline-reserved path.
+
+```markdown
+# Compare Report: Baseline vs Result
+
+**Generated:** <ISO 8601 date>
+**Baseline:** .design/DESIGN.md
+**Result:** .design/DESIGN-VERIFICATION.md
+
+## Score Delta by Category
+
+| Category | Baseline | Result | Delta | Status |
+|----------|----------|--------|-------|--------|
+| Accessibility | 6 | 8 | +2 | improvement |
+| Visual Hierarchy | 5 | 5 | 0 | no_change |
+| Anti-Patterns | 4 | 3 | -1 | regression |
+
+## Anti-Pattern Delta
+
+**Resolved** (present in baseline, absent in result):
+- <anti-pattern id or description>
+
+**New** (absent in baseline, present in result):
+- <anti-pattern id or description>
+
+**Unchanged:**
+- <anti-pattern id or description>
+
+## Must-Have Status
+
+| Must-Have | Status |
+|-----------|--------|
+| <id / description> | pass |
+| <id / description> | fail |
+| <id / description> | not-evaluated |
+
+## Design Drift
+
+<One of: "No drift detected. ..." | "DRIFT: [Category] regressed ..." | "Drift detection skipped: DESIGN-PLAN.md not found.">
+
+## Screenshot Delta
+
+<Per-route screenshot pairs OR "Screenshot delta skipped — preview not configured.">
+
+## Notes
+
+Scope: delta between two existing artifacts (.design/DESIGN.md → .design/DESIGN-VERIFICATION.md).
+No snapshot mechanism — multi-snapshot compare deferred to V2-06.
+This report does not modify DESIGN.md, DESIGN-VERIFICATION.md, or any other pipeline artifact.
+<List any UNMATCHED-BASELINE or UNMATCHED-RESULT categories here, if any.>
+```
+
+If a section has no items (e.g., no anti-patterns in baseline), write "None."
+
+---
+
+*Imported by: `../skills/compare/SKILL.md`. Maintained as part of Phase 28.5 (Bucket 2 rework - D-10).*

package/scripts/skill-templates/complete-cycle/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: gdd-complete-cycle
+description: "Cycle closeout command that marks CYCLES.md entry complete, archives pipeline artifacts to .design/archive/cycle-N/, generates EXPERIENCE.md, rebuilds the search index, and resets STATE.md. Use when a design cycle has shipped and you're ready to start the next one."
+argument-hint: "[<retrospective note>]"
+tools: Read, Write, Bash, AskUserQuestion
+---
+
+# {{command_prefix}}complete-cycle
+
+Closes the current cycle: marks CYCLES.md entry complete, archives pipeline artifacts, and clears STATE.md for the next cycle.
+
+## Steps
+
+1. **Load state**: Read `.design/STATE.md` for the active `cycle:` ID. If empty/missing, error: "No active cycle - nothing to complete."
+2. **Retrospective**: If no argument was passed, ask (AskUserQuestion): "Is cycle <N> complete? Briefly describe what was achieved." Capture for CYCLES.md.
+3. **Update CYCLES.md**: Find the current cycle entry, change `**Status**: active` to `**Status**: complete`, append a `**Retrospective**: <note>` line and `**Ended**: <date>`.
+4. **Archive artifacts**: Create `.design/archive/cycle-N/` via Bash `mkdir -p`. Copy these files into it (if present):
+   - `DESIGN.md`
+   - `DESIGN-PLAN.md`
+   - `DESIGN-CONTEXT.md`
+   - `DESIGN-VERIFICATION.md`
+   - `DESIGN-AUDIT.md`
+   - `DESIGN-SUMMARY.md`
+   Mark originals with a `<!-- archived to .design/archive/cycle-N/ -->` note at top (do not delete - next cycle will overwrite).
+5. **Generate EXPERIENCE.md** (Haiku-tier writer step): Read cycle STATE decisions + `.design/DESIGN-VERIFICATION.md` (if present) + any `.design/reflections/*.md` from this cycle. Write `.design/archive/cycle-N/EXPERIENCE.md` using this structure (~100–200 lines, declarative-fact framing, prepend `reference/cycle-handoff-preamble.md` content):
+
+   ```markdown
+   <!-- archived cycle experience — reference, not current requests -->
+   # Cycle N — Experience
+
+   **Goal**: <one-line goal from STATE.md or CYCLES.md>
+   **Opened**: <start date>
+   **Ended**: <today>
+
+   ## Decisions Made
+
+   <list all D-XX decisions from STATE.md <decisions> block — one per line>
+
+   ## Learnings Graduated
+
+   <list all L-NN learnings surfaced or promoted this cycle>
+
+   ## What Died
+
+   <designs, approaches, or tasks that were started but abandoned — and why>
+
+   ## Surprises
+
+   <what was unexpected during this cycle>
+
+   ## Handoff to Next Cycle
+
+   <what the next cycle should know: active sketches, deferred tasks, unresolved questions>
+   ```
+
+   This file becomes the highest-priority source for the decision-injector hook in future sessions.
+
+6. **Trigger reindex**: if `.design/search.db` exists, rebuild the search index:
+   ```bash
+   node -e "require('./scripts/lib/design-search.cjs').reindex(process.cwd())" 2>/dev/null || true
+   ```
+
+7. **Clear STATE.md**: Set `cycle:` to empty string, reset `<decisions>` to a fresh empty section, reset `stage:` to `brief`.
+8. Print: "Cycle <N> archived. Run `{{command_prefix}}new-cycle` to start the next cycle."
+
+## Do Not
+
+- Do not delete source files in `src/` - only archive `.design/` artifacts.
+- Do not auto-start a new cycle - user invokes `{{command_prefix}}new-cycle` explicitly.
+
+## Step 6 - Update notice (post-closeout surface)
+
+After the archive has been written and STATE.md has been cleared for the next cycle, 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.
+
+## COMPLETE-CYCLE COMPLETE

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

@@ -0,0 +1,71 @@
+---
+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 `{{command_prefix}}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
+---
+
+# {{command_prefix}}connections
+
+Interactive onboarding for the 33 external integrations the pipeline supports. Replaces "probe silently at scan entry and hope the user noticed" with an explicit "here is what can plug in, here is how."
+
+Canonical per-connection specs live in `../../connections/<name>.md` (one file per integration). The capability matrix + probe-pattern spec live in `../../connections/connections.md`. This skill is the **user-facing front end** for those specs.
+
+For the 33 probe scripts (MCP + HTTP + CLI + file probes), bucket categorization, per-connection setup screen, auto-run eligibility matrix, value-prop one-liners, and STATE.md / config.json write contracts, see `./connections-onboarding.md`. For the cross-skill probe pattern + connection-handshake summary, see `../../reference/shared-preamble.md#connection-handshake-summary`. For the cross-skill output discipline, see `../../reference/shared-preamble.md#output-contract-reminders`.
+
+---
+
+## Invocation Modes
+
+| Command | Behavior |
+|---|---|
+| `{{command_prefix}}connections` | Interactive wizard (default). Probes all, shows summary, asks what to configure. |
+| `{{command_prefix}}connections list` | Read-only table. Probes all, writes STATE.md, no prompts, exits. |
+| `{{command_prefix}}connections <name>` | Jump straight to setup for one connection (e.g. `{{command_prefix}}connections figma`). |
+| `{{command_prefix}}connections --auto` | CI mode. Probes, writes STATE.md, no prompts, no install attempts. |
+
+---
+
+## State Integration
+
+1. Read `.design/STATE.md` - if missing, that's fine; this skill does not require a pipeline run.
+2. Read `.design/config.json` - if missing, use defaults. If `connections_onboarding` block is present with `pending_verification`, this is a resume - see Step 6.
+3. Read `connections.skip[]` from config - never re-prompt for skipped connections.
+4. Update `last_checkpoint` in STATE.md at skill exit if STATE.md exists.
+
+---
+
+## Workflow
+
+1. **Probe all 33 connections** - run every probe script per `./connections-onboarding.md#step-1--probe-all-33-connections`. MCP probes use `ToolSearch` first; HTTP / CLI / file probes follow non-MCP patterns. Merge results into `STATE.md <connections>` with the three-value schema (`available | unavailable | not_configured`) - never add new values.
+2. **Categorize + build summary** - bucket each probe result (available / recommended / optional / skipped / unavailable) using project-hint detection. Detail + recommendation mapping: `./connections-onboarding.md#step-2--bucket-categorization`.
+3. **Print summary table** - show buckets + value-prop one-liners (verbatim from `./connections-onboarding.md#step-3--summary-table`).
+4. **Route by mode** - `list` / `--auto` exits after summary; `<name>` jumps straight to Step 5; default mode opens an AskUserQuestion (configure recommended / pick one by one / configure all optional / re-check specific / exit). Routing detail: `./connections-onboarding.md#step-4--route-by-mode`.
+5. **Per-connection setup screen** - for each target: read `connections/<name>.md`, present the setup screen, AskUserQuestion (run now / copy-paste / skip / never ask). Auto-run only if reversible (see eligibility matrix). On success: append name to `connections_onboarding.pending_verification[]`. Detail: `./connections-onboarding.md#step-5--per-connection-setup-screen`.
+6. **Verification pass** - re-probe every name in `pending_verification[]`. Available → remove. `not_configured` → leave (needs session restart). `unavailable` → leave + note OAuth needed. Print "Setup complete" summary. Detail: `./connections-onboarding.md#step-6--verification-pass`.
+
+If `.design/config.json > connections_onboarding.pending_verification[]` is non-empty at entry → enter **resume flow**: run Step 6 immediately; if clean, exit; otherwise fall through to Step 3. Detail: `./connections-onboarding.md#resumability`.
+
+---
+
+## Do Not
+
+Per `./connections-onboarding.md#do-not`:
+
+- Never run `npm install -g` globals automatically.
+- Never write to `~/.bashrc`, `~/.zshrc`, or shell RC files.
+- Never run `claude mcp add` without explicit `"Run install command now"` confirmation.
+- Never auto-restart the Claude Code session.
+- Never re-prompt for names in `connections.skip[]`.
+- Never overwrite existing `<connections>` entries that this skill did not probe - merge only.
+
+---
+
+## Output
+
+End every invocation with:
+
+```
+## CONNECTIONS COMPLETE
+```