@hegemonart/get-design-done 1.59.3 → 1.59.5

package/scripts/skill-templates/bandit-reset/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: gdd-bandit-reset
+description: "Confirm-then-reset the per-(agent, bin, delegate) bandit posterior - backs up .design/telemetry/posterior.json to posterior.json.bak, then clears it to a fresh empty envelope. Mutation companion to read-only bandit-status. Use when the posterior is corrupted/unparseable, after a major agent/skill roster change invalidates accumulated arms, or when you deliberately want to rebootstrap adaptive routing from informed priors."
+argument-hint: "[--yes to skip the confirmation prompt]"
+tools: Read, Write, Bash, AskUserQuestion
+disable-model-invocation: true
+---
+
+# gdd-bandit-reset
+
+## Role
+
+You are a deterministic, destructive maintenance skill. You are the ONLY skill that clears the bandit posterior - the mutation companion to read-only `{{command_prefix}}bandit-status`. You read the posterior path declared by `scripts/lib/bandit-router.cjs`'s `DEFAULT_POSTERIOR_PATH` (`.design/telemetry/posterior.json`), REQUIRE explicit confirmation, back the file up to `posterior.json.bak`, then overwrite it with a fresh empty envelope so the next bandit pull rebootstraps from informed priors. See `./reference/bandit-integration.md` for setup, interpretation, and convergence guidance.
+
+## Invocation Contract
+
+- **Input**: optional `--yes` to skip the interactive confirmation (for non-interactive/automated runs).
+- **Output**: a Markdown reset receipt to stdout (backup path + arms cleared + envelope written).
+
+## Procedure
+
+### 1. Locate the posterior file
+
+Read `.design/telemetry/posterior.json` (path declared by `scripts/lib/bandit-router.cjs`'s `DEFAULT_POSTERIOR_PATH` - never hardcode a different path). Missing → nothing to reset; emit and skip to Section 5 (Record):
+
+```
+## Bandit Posterior Reset
+
+No posterior file found at `.design/telemetry/posterior.json` — nothing to reset.
+
+The next bandit pull with `adaptive_mode: full` will bootstrap a fresh posterior from informed priors. See `reference/bandit-integration.md`.
+```
+
+If present, count the arms (`arms.length`, treating a missing/non-array `arms` as `0`) so the confirmation and receipt can report what will be cleared. A corrupted/unparseable file is still resettable - report `arms: unknown (file unparseable)` and continue.
+
+### 2. Require explicit confirmation
+
+This is a DESTRUCTIVE operation. Do NOT proceed without confirmation.
+
+- If `--yes` was passed, skip straight to Section 3.
+- Otherwise, prompt via AskUserQuestion: "Reset the bandit posterior at `.design/telemetry/posterior.json`? This clears <N> learned arms. A backup will be written to `posterior.json.bak` first." with options **Reset** and **Cancel**.
+- On **Cancel** (or any non-affirmative answer), abort WITHOUT touching either the posterior or the backup, and emit:
+
+```
+## Bandit Posterior Reset — Cancelled
+
+No changes made. The posterior at `.design/telemetry/posterior.json` is untouched (<N> arms).
+```
+
+Then skip to Section 5 (Record) with `reset: false`.
+
+### 3. Back up the current posterior
+
+Copy the live posterior to `.design/telemetry/posterior.json.bak` (sibling backup) BEFORE clearing it, so the previous state is always recoverable. Overwrite any existing `.bak` from a prior reset. If the backup write fails, ABORT before clearing; never clear without a successful backup.
+
+### 4. Clear to a fresh empty envelope
+
+Overwrite `.design/telemetry/posterior.json` with a fresh empty envelope matching `scripts/lib/bandit-router.cjs`'s `loadPosterior()` shape (`SCHEMA_VERSION` = `1.0.0`, current ISO `generated_at`, empty `arms`):
+
+```json
+{
+  "schema_version": "1.0.0",
+  "generated_at": "<ISO>",
+  "arms": []
+}
+```
+
+Write atomically where possible (`.tmp` + rename, mirroring `savePosterior()`). Then emit the receipt:
+
+```
+## Bandit Posterior Reset
+
+Posterior cleared. The next bandit pull with `adaptive_mode: full` will rebootstrap from informed priors.
+
+- Backup: `.design/telemetry/posterior.json.bak`
+- Arms cleared: <N>
+- Fresh envelope: `.design/telemetry/posterior.json` (schema_version 1.0.0, 0 arms)
+
+Restore the previous state with: `cp .design/telemetry/posterior.json.bak .design/telemetry/posterior.json`
+Verify the cleared state with `{{command_prefix}}bandit-status`. See `reference/bandit-integration.md`.
+```
+
+### 5. Record
+
+Append one JSONL line to `.design/skill-records.jsonl`: `{"skill":"gdd-bandit-reset","ts":"<ISO>","reset":<bool>,"arms_cleared":<count>,"backup_written":<bool>}`. The skill mutates ONLY the posterior (+ its `.bak`) and appends to skill-records.jsonl (telemetry); it touches no other state.
+
+## Cross-references
+
+- `{{command_prefix}}bandit-status` - read-only companion; inspect the posterior before/after a reset.
+- `./reference/bandit-integration.md` - operator guide; interpretation patterns and when a reset is warranted.
+- `scripts/lib/bandit-router.cjs` - posterior shape, `DEFAULT_POSTERIOR_PATH`, `SCHEMA_VERSION`, `loadPosterior()`, `savePosterior()`, `reset()`.

package/scripts/skill-templates/bandit-status/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: gdd-bandit-status
+description: "Surface read-only per-(agent, bin, delegate) bandit posterior snapshot - alpha/beta/mean/stddev/count/last-used per arm. Phase 27.5 (v1.27.5) diagnostic. Use when investigating 'why did the bandit pick tier X for agent Y?' or when verifying posterior convergence after enabling adaptive_mode: full."
+argument-hint: ""
+tools: Read, Bash
+---
+
+# gdd-bandit-status
+
+## Role
+
+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 `{{command_prefix}}bandit-reset` (Phase 23.5). See `./reference/bandit-integration.md` for setup, interpretation, and convergence guidance.
+
+## Invocation Contract
+
+- **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`. Missing → emit 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`.
+
+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 `{{command_prefix}}bandit-reset`.
+
+See `reference/bandit-integration.md` for setup guidance.
+```
+
+Skip to Section 4 (Record). Parse failure (truncated/corrupted) → emit `Posterior file exists but is unparseable. Run {{command_prefix}}bandit-reset to start fresh, or restore from a backup.`
+
+### 2. Parse the posterior
+
+Schema:
+
+```json
+{
+  "schema_version": "1.0.0",
+  "generated_at": "<ISO>",
+  "arms": [{ "agent": "...", "bin": "...", "tier": "...", "delegate": "...", "alpha": N, "beta": N, "last_used": "...", "count": N }]
+}
+```
+
+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)` (3 decimals), `stddev = sqrt(alpha*beta / ((alpha+beta)^2 * (alpha+beta+1)))` (3 decimals).
+
+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 use `{{command_prefix}}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 |
+|-------|-----|----------|------|-------|------|------|--------|-------|-----------|
+| ...   | ... | ...      | ...  | ...   | ...  | ...  | ...    | ...   | ...       |
+
+> Mean = alpha / (alpha + beta). Stddev = sqrt(alpha*beta / ((alpha+beta)^2 * (alpha+beta+1))).
+> Delegate '-' = Phase 23.5 legacy slice (equivalent to 'none').
+> See `reference/bandit-integration.md` for interpretation.
+> Read-only — use `{{command_prefix}}bandit-reset` to clear posterior state.
+```
+
+Precision: alpha/beta 2 decimals; mean/stddev 3 decimals; count integer; `last_used` truncated to minute (`YYYY-MM-DDTHH:MM`); null `last_used` renders `-`.
+
+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
+
+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
+
+- `./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), `{{command_prefix}}bandit-reset` (Phase 23.5) - only surface that mutates the posterior.

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

@@ -0,0 +1,65 @@
+---
+name: gdd-benchmark
+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
+---
+
+# {{command_prefix}}benchmark
+
+Harvest per-component design knowledge from 18 design systems and synthesize canonical
+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
+
+| Invocation | Action |
+|------------|--------|
+| `{{command_prefix}}benchmark <component>` | Harvest + synthesize a single component |
+| `{{command_prefix}}benchmark --wave <N>` | Run a full wave (1 = Inputs, 2 = Containers, etc.) |
+| `{{command_prefix}}benchmark --list` | Show corpus coverage - which specs exist, which are pending |
+| `{{command_prefix}}benchmark --refresh <component>` | Re-harvest a spec (for design-system version bumps) |
+
+## Single-Component Flow (`{{command_prefix}}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 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 (`{{command_prefix}}benchmark --wave <N>`)
+
+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 |
+|------|-----------|
+| 1 | button, input, select-combobox, checkbox, radio, switch, link, label |
+| 2 | card, modal-dialog, drawer, popover, tooltip, accordion, tabs |
+
+Print progress per component: `[N/total] harvesting <component>…`
+
+## List Mode (`{{command_prefix}}benchmark --list`)
+
+Read `reference/components/README.md` and diff against `reference/components/*.md` files. Print a table with columns: Component, Status, Wave, Lines.
+
+## Refresh Mode (`{{command_prefix}}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.
+
+## Source List
+
+`../../connections/design-corpora.md` - 18 design systems with canonical URLs, licensing, and fallback chain (canonical → archive.org → Refero MCP → Pinterest MCP).
+
+## Output Artifacts
+
+| Artifact | Purpose |
+|----------|---------|
+| `.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/scripts/skill-templates/bootstrap-ds/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: gdd-bootstrap-ds
+description: "Bootstraps a design system for a GREENFIELD project that has none - no Figma, no tokens, no component library. Takes a brand input (primary color + optional secondary + tone tags + target framework) and emits a coherent OKLCH token system (color tints, modular type scale, 4pt/8pt spacing, radius + motion defaults) in 3 variants to pick from, then scaffolds proof components (button/input/card). Use at the start of a brand-new project, or when {{command_prefix}}explore finds no existing design system. Never invents a brand; never overwrites an existing DS."
+argument-hint: "[--primary <color>] [--secondary <color>] [--tone <tags>] [--framework web|native-ios|native-android|flutter]"
+user-invocable: true
+tools: Read, Write, Bash, Glob, Grep, AskUserQuestion, Task
+---
+
+# {{command_prefix}}bootstrap-ds
+
+Greenfield design-system bootstrap. Closes the gap that GDD's `design-context-builder` assumes a design system already exists (in code or Figma) - a brand-new project has none. This skill is the **front door**: it collects a brand input and hands it to `agents/ds-generator.md`, which emits the token system + proof components per `reference/ds-bootstrap-rubric.md` (deterministic math in `scripts/lib/ds/token-scale.cjs`).
+
+## When to use
+
+- At the start of a brand-new project (no `tailwind.config`, no token file, no DS).
+- When `{{command_prefix}}discover` / `design-context-builder` reports **no existing design system** and the user opts to bootstrap one.
+
+If a design system **already exists**, do NOT run this - defer to `design-context-builder` (it maps the existing one). State that and stop.
+
+## Steps
+
+1. **Collect the brand input.** From flags, or via `AskUserQuestion` for anything missing:
+   - **primary** (required) - the brand color (hex / rgb / `oklch()`).
+   - **secondary** (optional) - a second brand color (emitted only if supplied - the rubric's ≤2-brand-colors rule).
+   - **tone tags** (optional) - `calm` / `corporate` / `editorial` / `playful` / `bold` (maps to the type ratio + chroma treatment).
+   - **target framework** (optional) - `web` (default) / `native-ios` / `native-android` / `flutter`. Detect from the project if absent (Phase 34 routing).
+2. **Delegate to `ds-generator`** (via `Task`): it resolves the primary to OKLCH, runs `token-scale.cjs` for **3 variants** (conservative / balanced / bold), and presents them.
+3. **Pick a variant.** Surface the 3 variants (primary `500`, type ratio, spacing baseline, radius, feel); the user picks ONE.
+4. **Emit + scaffold (proposal → confirm).** `ds-generator` emits the chosen token set (role-named CSS custom properties + the framework mapping) and scaffolds **button / input / card** as a coherence proof. Nothing is written to `src/` without confirmation.
+
+## Do Not
+
+- Do not invent a brand (no logomark, no typeface choice, no third brand color) - emit a token *system*, not an identity.
+- Do not overwrite an existing design system - defer to `design-context-builder`.
+- Do not add a color-conversion dependency - `token-scale.cjs` emits native CSS `oklch()`.
+
+## Output
+
+End with:
+
+```
+## BOOTSTRAP-DS COMPLETE
+```

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`.