@hegemonart/get-design-done 1.28.0 → 1.28.6

package/skills/bandit-status/SKILL.md

@@ -9,88 +9,69 @@ tools: Read, Bash
 
 ## Role
 
-You are a deterministic, read-only diagnostic skill. You do not spawn agents and do not modify the bandit posterior. You read `.design/telemetry/posterior.json` (the path declared by `scripts/lib/bandit-router.cjs`'s `DEFAULT_POSTERIOR_PATH` constant), aggregate per-`(agent, bin, delegate, tier)` arm state, and emit a single Markdown table summarizing the posterior. The user runs this when they want to inspect bandit decisions without touching the posterior.
-
-Strictly read-only per Phase 27.5 D-11. To reset the posterior, use `/gdd:bandit-reset` from Phase 23.5.
+You are a deterministic, read-only diagnostic skill. You do not spawn agents and do not modify the posterior. You read `.design/telemetry/posterior.json` (path declared by `scripts/lib/bandit-router.cjs`'s `DEFAULT_POSTERIOR_PATH`), aggregate per-`(agent, bin, delegate, tier)` arm state, and emit a single Markdown table. Read-only per Phase 27.5 D-11 — to reset, use `/gdd:bandit-reset` (Phase 23.5). See `./reference/bandit-integration.md` for setup, interpretation, and convergence guidance.
 
 ## Invocation Contract
 
-- **Input**: none. The skill takes no arguments.
-- **Output**: a Markdown bandit-status table to stdout. No JSON wrapper. The table is the entire output.
+- **Input**: none.
+- **Output**: a Markdown bandit-status table to stdout. The table is the entire output.
 
 ## Procedure
 
 ### 1. Locate the posterior file
 
-Read `.design/telemetry/posterior.json`. If the file does not exist:
-
-- Emit the empty-state message:
-
-  ```
-  ## Bandit Posterior Snapshot
-
-  No posterior data yet — run a few pipeline cycles with `adaptive_mode: full` first.
-
-  No posterior data found at `.design/telemetry/posterior.json`.
+Read `.design/telemetry/posterior.json`. Missing → emit empty-state message:
 
-  Possible reasons:
-  - `adaptive_mode` is `static` or `hedge` (bandit is silent — see `.design/budget.json` `adaptive_mode` setting).
-  - No spawns have fired since Phase 27.5 wiring landed.
-  - Posterior was cleared via `/gdd:bandit-reset`.
+```
+## Bandit Posterior Snapshot
 
-  See `reference/bandit-integration.md` for setup guidance.
-  ```
+No posterior data yet — run a few pipeline cycles with `adaptive_mode: full` first.
 
-- Skip to Section 4 (Record).
+No posterior data found at `.design/telemetry/posterior.json`.
 
-### 2. Parse the posterior
-
-Parse the file as JSON. If parsing fails (truncated/corrupted file), emit:
+Possible reasons:
+- `adaptive_mode` is `static` or `hedge` (bandit silent — see `.design/budget.json`).
+- No spawns have fired since Phase 27.5 wiring landed.
+- Posterior was cleared via `/gdd:bandit-reset`.
 
+See `reference/bandit-integration.md` for setup guidance.
 ```
-## Bandit Posterior Snapshot
 
-Posterior file at `.design/telemetry/posterior.json` exists but is unparseable (truncated or corrupted).
+Skip to Section 4 (Record). Parse failure (truncated/corrupted) → emit `Posterior file exists but is unparseable. Run /gdd:bandit-reset to start fresh, or restore from a backup.`
 
-Run `/gdd:bandit-reset` to start fresh, or restore from a backup.
-```
+### 2. Parse the posterior
 
-The posterior schema is:
+Schema:
 
 ```json
 {
   "schema_version": "1.0.0",
-  "generated_at": "<ISO timestamp>",
-  "arms": [
-    { "agent": "...", "bin": "...", "tier": "...", "delegate": "...", "alpha": N, "beta": N, "last_used": "...", "count": N }
-  ]
+  "generated_at": "<ISO>",
+  "arms": [{ "agent": "...", "bin": "...", "tier": "...", "delegate": "...", "alpha": N, "beta": N, "last_used": "...", "count": N }]
 }
 ```
 
-The `delegate` field is optional — when absent, the arm is the Phase 23.5 legacy slice (equivalent to `delegate: 'none'`). The status output renders `delegate: '-'` for legacy arms to distinguish them visually from explicit `'none'` arms.
+The `delegate` field is optional — absent = Phase 23.5 legacy slice (rendered as `-` in the table).
 
 ### 3. Render the table
 
-Compute per arm:
-
-- `mean = alpha / (alpha + beta)` (rounded to 3 decimals)
-- `stddev = sqrt(alpha * beta / ((alpha + beta)^2 * (alpha + beta + 1)))` (rounded to 3 decimals)
+Compute per arm: `mean = alpha / (alpha + beta)` (3 decimals), `stddev = sqrt(alpha*beta / ((alpha+beta)^2 * (alpha+beta+1)))` (3 decimals).
 
-Sort arms by `(agent ascending, bin ascending, delegate ascending where '-' sorts first, tier ascending where opus < sonnet < haiku is the canonical tier ordering, last_used descending tiebreaker)`. Group rows by agent for readability.
+Sort by `(agent ASC, bin ASC, delegate ASC where '-' first, tier ASC opus<sonnet<haiku, last_used DESC)`. Group by agent for readability.
 
 Emit:
 
 ```
 ## Bandit Posterior Snapshot
 
-Per-(agent, bin, delegate, tier) posterior state. Read-only — to reset the posterior, use `/gdd:bandit-reset` (Phase 23.5).
+Per-(agent, bin, delegate, tier) posterior state. Read-only — to reset use `/gdd:bandit-reset` (Phase 23.5).
 
 Posterior file: `.design/telemetry/posterior.json` (last updated: <generated_at>)
 Total arms: <count>
 
-| Agent           | Bin    | Delegate | Tier   | Alpha | Beta  | Mean  | Stddev | Count | Last Used            |
-|-----------------|--------|----------|--------|-------|-------|-------|--------|-------|----------------------|
-| <agent>         | <bin>  | <deleg>  | <tier> | <a>   | <b>   | <m>   | <s>    | <c>   | <last_used or '-'>   |
+| Agent | Bin | Delegate | Tier | Alpha | Beta | Mean | Stddev | Count | Last Used |
+|-------|-----|----------|------|-------|------|------|--------|-------|-----------|
+| ...   | ... | ...      | ...  | ...   | ...  | ...  | ...    | ...   | ...       |
 
 > Mean = alpha / (alpha + beta). Stddev = sqrt(alpha*beta / ((alpha+beta)^2 * (alpha+beta+1))).
 > Delegate '-' = Phase 23.5 legacy slice (equivalent to 'none').
@@ -98,32 +79,16 @@ Total arms: <count>
 > Read-only — use `/gdd:bandit-reset` to clear posterior state.
 ```
 
-Format numbers to fixed precision: alpha/beta to 2 decimals, mean/stddev to 3 decimals, count as integer, last_used truncated to the minute precision (`YYYY-MM-DDTHH:MM`).
+Precision: alpha/beta 2 decimals; mean/stddev 3 decimals; count integer; `last_used` truncated to minute (`YYYY-MM-DDTHH:MM`); null `last_used` renders `-`.
 
-When `last_used` is null (arm exists but never selected — possible if the arm was created by `ensureArm` without a subsequent `pull`), render `-` in the Last Used column.
-
-After the table, surface a brief best-arm summary per `(agent, bin)` slice — for each unique `(agent, bin)` pair, identify the arm with the highest `mean` (tie-broken by `count` descending) and display it as the "best-arm" recommendation. This helps the operator answer "why did the bandit pick tier X?" at a glance.
+After the table, surface a per-`(agent, bin)` best-arm summary: for each unique pair, identify highest-mean arm (tie-broken by `count` DESC) — answers "why did the bandit pick tier X?" at a glance.
 
 ### 4. Record
 
-After execution, append one JSONL line to `.design/skill-records.jsonl`:
-
-```json
-{"skill": "gdd-bandit-status", "ts": "<ISO timestamp>", "arms_seen": <count>, "posterior_present": <bool>}
-```
-
-The skill writes ONLY to `.design/skill-records.jsonl` for telemetry purposes. It never touches `.design/telemetry/posterior.json`.
+Append one JSONL line to `.design/skill-records.jsonl`: `{"skill":"gdd-bandit-status","ts":"<ISO>","arms_seen":<count>,"posterior_present":<bool>}`. Skill writes ONLY to skill-records.jsonl (telemetry); never touches the posterior.
 
 ## Cross-references
 
-- `scripts/lib/bandit-router.cjs` (Phase 23.5) — posterior shape, `DEFAULT_POSTERIOR_PATH` constant, `loadPosterior()` helper.
-- `scripts/lib/bandit-router/integration.cjs` (Phase 27.5-01) — production-integration shim.
-- `hooks/budget-enforcer.ts` (Phase 27.5-02) — bandit consultation site.
-- `scripts/lib/session-runner/index.ts` (Phase 27.5-03) — outcome recording site.
-- `scripts/lib/bandit-arbitrage.cjs` (Phase 27.5-04) — automated stale-frontmatter analysis.
-- `reference/bandit-integration.md` (Phase 27.5-06) — operator guide.
-- `/gdd:bandit-reset` (Phase 23.5) — the ONLY surface that mutates the posterior.
-
-## Record
-
-See Section 4 above.
+- `./reference/bandit-integration.md` — operator guide; interpretation patterns.
+- `scripts/lib/bandit-router.cjs` (Phase 23.5) — posterior shape, `DEFAULT_POSTERIOR_PATH`, `loadPosterior()`.
+- `scripts/lib/bandit-router/integration.cjs` (27.5-01), `hooks/budget-enforcer.ts` (27.5-02), `scripts/lib/session-runner/index.ts` (27.5-03), `scripts/lib/bandit-arbitrage.cjs` (27.5-04), `/gdd:bandit-reset` (Phase 23.5) — only surface that mutates the posterior.

package/skills/benchmark/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-benchmark
-description: Harvest and synthesize per-component design benchmarks from 18 design systems. Produces canonical specs at reference/components/<name>.md.
+description: "Harvest and synthesize per-component design benchmarks from 18 design systems and produce canonical component specs at `reference/components/<name>.md`. Use when adding a new component spec, running a benchmark wave, listing corpus coverage, or refreshing a spec after a design-system version bump."
 argument-hint: "<component> | --wave <N> | --list | --refresh <component>"
 tools: Read, Write, Bash, Grep, Glob, Task, WebFetch
 ---
@@ -8,7 +8,9 @@ tools: Read, Write, Bash, Grep, Glob, Task, WebFetch
 # /gdd:benchmark
 
 Harvest per-component design knowledge from 18 design systems and synthesize canonical
-specs at `reference/components/<name>.md`.
+specs at `reference/components/<name>.md`. The 18-source corpus + fallback chain lives in
+`../../connections/design-corpora.md`. Per-skill output discipline + completion-marker
+conventions are at `../../reference/shared-preamble.md#output-contract-reminders`.
 
 ## Invocation Modes
 
@@ -21,49 +23,17 @@ specs at `reference/components/<name>.md`.
 
 ## Single-Component Flow (`/gdd:benchmark <component>`)
 
-1. **Check if spec exists** — `Glob("reference/components/<component>.md")`.
-   If found and `--refresh` was not passed, confirm before overwriting.
-
-2. **Harvest** — spawn `component-benchmark-harvester` with:
-   ```
-   Task("component-benchmark-harvester", """
-   <required_reading>
-   @connections/design-corpora.md
-   </required_reading>
-
-   Harvest design-system excerpts for component: <component>
-   Emit raw harvest to: .planning/benchmarks/raw/<component>.md
-   Consume any relevant content from: .planning/research/impeccable-salvage/
-
-   Acceptance: .planning/benchmarks/raw/<component>.md exists with ≥4 source sections.
-   """)
-   ```
-
-3. **Synthesize** — spawn `component-benchmark-synthesizer` with:
-   ```
-   Task("component-benchmark-synthesizer", """
-   <required_reading>
-   @.planning/benchmarks/raw/<component>.md
-   @reference/components/TEMPLATE.md
-   @reference/anti-patterns.md
-   </required_reading>
-
-   Synthesize the raw harvest into a canonical spec.
-   Output: reference/components/<component>.md
-   Update: reference/components/README.md (add entry in correct category)
-
-   Acceptance: spec exists, ≤350 lines, cites ≥4 systems, has TEMPLATE.md sections,
-   WAI-ARIA keyboard contract present, failing-example block present.
-   """)
-   ```
+1. **Check if spec exists** — `Glob("reference/components/<component>.md")`. If found and `--refresh` was not passed, confirm before overwriting.
+
+2. **Harvest** — spawn `component-benchmark-harvester` with required-reading `@connections/design-corpora.md`, target component, raw-output path `.planning/benchmarks/raw/<component>.md`, and a salvage hint to `.planning/research/impeccable-salvage/`. Acceptance: raw harvest exists with ≥4 source sections.
+
+3. **Synthesize** — spawn `component-benchmark-synthesizer` with required-reading `@.planning/benchmarks/raw/<component>.md`, `@reference/components/TEMPLATE.md`, `@reference/anti-patterns.md`. Output: `reference/components/<component>.md`. Also update `reference/components/README.md` (add entry in correct category). Acceptance: spec ≤350 lines, cites ≥4 systems, follows `TEMPLATE.md` sections, has a WAI-ARIA keyboard contract + a failing-example block.
 
 4. **Report** — print spec path, line count, systems cited.
 
 ## Wave Mode (`/gdd:benchmark --wave <N>`)
 
-Read the wave definition from `reference/components/README.md` and run each component
-in the wave sequentially (not parallel — each harvest is network-bound and the raw files
-are large).
+Read the wave definition from `reference/components/README.md` and run each component sequentially (not parallel — each harvest is network-bound and the raw files are large).
 
 | Wave | Components |
 |------|-----------|
@@ -74,27 +44,15 @@ Print progress per component: `[N/total] harvesting <component>…`
 
 ## List Mode (`/gdd:benchmark --list`)
 
-Read `reference/components/README.md` and diff against `reference/components/*.md` files.
-Print a table:
-
-```
-Component        Status   Wave  Lines
-button           ✓        1     248
-input            ✓        1     312
-select-combobox  ✓        1     295
-...
-toast            pending  3     —
-```
+Read `reference/components/README.md` and diff against `reference/components/*.md` files. Print a table with columns: Component, Status, Wave, Lines.
 
 ## Refresh Mode (`/gdd:benchmark --refresh <component>`)
 
-Same as single-component flow but skips the "already exists" guard. Use when a design
-system ships a breaking update to a component's spec.
+Same as single-component flow but skips the "already exists" guard. Use when a design system ships a breaking update to a component's spec.
 
 ## Source List
 
-`connections/design-corpora.md` — 18 design systems with canonical URLs, licensing, and
-fallback chain (canonical → archive.org → Refero MCP → Pinterest MCP).
+`../../connections/design-corpora.md` — 18 design systems with canonical URLs, licensing, and fallback chain (canonical → archive.org → Refero MCP → Pinterest MCP).
 
 ## Output Artifacts
 
@@ -103,3 +61,5 @@ fallback chain (canonical → archive.org → Refero MCP → Pinterest MCP).
 | `.planning/benchmarks/raw/<component>.md` | Raw multi-source harvest (input only) |
 | `reference/components/<component>.md` | Canonical spec (distributed with plugin) |
 | `reference/components/README.md` | Corpus index (updated by synthesizer) |
+
+## BENCHMARK COMPLETE

package/skills/brief/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdd-brief
-description: "Design intake — captures problem statement, audience, constraints, success metrics, and scope into .design/BRIEF.md (Stage 1 of 5)"
+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."
 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
 ---
@@ -72,6 +72,17 @@ With `.design/STATE.md` seeded from the template:
 
 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
 
 ```

package/skills/cache-manager/SKILL.md

@@ -3,6 +3,7 @@ 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
+disable-model-invocation: true
 ---
 
 # gdd-cache-manager
@@ -37,60 +38,7 @@ You are the deterministic cache-key computer and cache-manifest writer for the o
 
 ## 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"
-  }
-}
-```
+The canonical reference implementation (single source of truth; `hooks/budget-enforcer.js` 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
 
@@ -115,6 +63,4 @@ Per D-09:
 
 ## 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.
+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/skills/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.js` 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:
+
+```
+$ /gdd: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:
+
+```
+$ /gdd: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.