@hegemonart/get-design-done 1.41.0 → 1.42.0

package/dist/claude-code/.claude/skills/map/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: gdd-map
+description: "Dispatches 5 specialist codebase mappers in parallel. Produces .design/map/*.md files consumed by the explore stage."
+argument-hint: "[--only tokens|components|visual-hierarchy|a11y|motion]"
+tools: Read, Write, Bash, Task
+user-invocable: true
+---
+
+# Get Design Done — Map
+
+Parallel orchestrator. Spawns 5 specialist mappers, each writing one file under `.design/map/`. The explore stage consumes these when present. See `./reference/heuristics.md` §"Optimization rules" for parallel-spawn cost considerations.
+
+## Mapper → Output
+
+| Mapper | Output |
+|--------|--------|
+| `token-mapper` | `.design/map/tokens.md` |
+| `component-taxonomy-mapper` | `.design/map/components.md` |
+| `visual-hierarchy-mapper` | `.design/map/visual-hierarchy.md` |
+| `a11y-mapper` | `.design/map/a11y.md` |
+| `motion-mapper` | `.design/map/motion.md` |
+
+## Step 1 — Setup
+
+- Ensure `.design/map/` exists (create if missing).
+- Read `.design/config.json` → `parallelism` object. Use `reference/config-schema.md` defaults if absent.
+- Read `.design/STATE.md` — note `<connections>` (Figma availability for token-mapper).
+- Parse `$ARGUMENTS`. If `--only <name>`, restrict the dispatch set to one mapper.
+
+## Step 2 — Parallelism Decision
+
+Per `reference/parallelism-rules.md`: all 5 mappers have `parallel-safe: auto` with disjoint `writes:` (each writes a different `.design/map/*.md` file) — no hard-rule conflict. `typical-duration-seconds` sum (~210s) minus slowest (~45s) ≈ 165s savings → clears `min_estimated_savings_seconds`. Verdict: **parallel**.
+
+Write the verdict to STATE.md:
+
+```xml
+<parallelism_decision>
+  stage: map
+  verdict: parallel
+  reason: "5 mappers, parallel-safe: auto, writes disjoint, est savings ~165s"
+  agents: ["token-mapper", "component-taxonomy-mapper", "visual-hierarchy-mapper", "a11y-mapper", "motion-mapper"]
+  ruled_out: []
+  timestamp: [ISO 8601 now]
+</parallelism_decision>
+```
+
+`--only` → adjust `agents` and set `verdict: serial` with `reason: "single mapper requested"`.
+
+## Step 3 — Dispatch (concurrent)
+
+Spawn all selected mappers in a single response with multiple `Task()` calls:
+
+```
+Task("<mapper-name>", """
+<required_reading>
+@.design/STATE.md
+@reference/audit-scoring.md
+[@reference/accessibility.md — a11y-mapper only]
+[@reference/motion.md — motion-mapper only]
+</required_reading>
+
+You are <mapper-name>. Scan the codebase per your agent spec and write your
+output file under .design/map/. Emit your completion marker when done.
+""")
+```
+
+Wait for each completion marker: `## TOKEN MAP COMPLETE`, `## COMPONENT MAP COMPLETE`, `## VISUAL HIERARCHY MAP COMPLETE`, `## A11Y MAP COMPLETE`, `## MOTION MAP COMPLETE`.
+
+## Step 3.5 — Synthesize parallel mapper outputs (Plan 10.1-04, D-13/D-14/D-15)
+
+Each mapper has written its own `.design/map/*.md` (disjoint writes). Main-context doesn't need all 5 verbatim — invoke `synthesize` inline with `outputs:[<each file's text labelled "=== from <mapper> ==="]`, `directive: "Merge into cross-cutting DESIGN-PATTERNS.md preserving section headers; consolidate cross-mapper duplicates with source-agent names; target ~120 lines."`, `output_shape:"markdown"`.
+
+Wait for `## SYNTHESIS COMPLETE`. Write merged markdown to `.design/DESIGN-PATTERNS.md` (overwrite if present) — the primary explore-stage input; per-mapper files remain as drill-down evidence. `--only` (single mapper) → skip this step.
+
+## Step 4 — Collate
+
+Write `.design/DESIGN-MAP.md` — thin index linking to each `.design/map/*.md` with a one-paragraph summary from each file's header. If Step 3.5 ran, also cross-link to `.design/DESIGN-PATTERNS.md` and note at the top: "See DESIGN-PATTERNS.md for the merged cross-cutting summary — this index preserves per-mapper drill-down."
+
+## Step 5 — Report
+
+```
+━━━ Map complete ━━━
+Files: .design/map/tokens.md, components.md, visual-hierarchy.md, a11y.md, motion.md
+Index: .design/DESIGN-MAP.md
+Next: /gdd:explore (consumes .design/DESIGN-PATTERNS.md on happy path; .design/map/*.md available for drill-down)
+━━━━━━━━━━━━━━━━━━━━━
+```
+
+## MAP COMPLETE

package/dist/claude-code/.claude/skills/migrate/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: gdd-migrate
+description: "Migrates a project off GDD's own deprecated paths after an upgrade. Reads the machine-readable registry in reference/DEPRECATIONS.md (via scripts/lib/deprecation-registry.cjs), scans the project's .design/config.json + any local skill/agent references for paths that are now deprecated or removed at the installed version, and PREVIEWS a diff before changing anything. Interactive by default (confirm per change); --yes auto-applies; --dry-run previews only. Read-first, never silent. Use after /gdd:update flags a breaking change."
+argument-hint: "[--yes] [--dry-run]"
+user-invocable: true
+tools: Read, Write, Bash, Grep, Glob
+---
+
+# /gdd:migrate
+
+Closes the GDD-on-GDD gap: when GDD moves or removes its own paths (e.g. the Phase 31.5
+`scripts/lib/**` → `sdk/**` reorg), a project that referenced the old paths needs updating. This skill
+consults the deprecation registry, finds the stale references **in this project**, and rewrites them —
+**after showing you the diff**. It never edits silently. Contract: `../../reference/DEPRECATIONS.md`.
+
+## Invocation
+
+| Command | Behavior |
+|---|---|
+| `/gdd:migrate` | Scan + preview every applicable migration, then confirm each before applying. |
+| `/gdd:migrate --dry-run` | Preview only — print the diff, change nothing. |
+| `/gdd:migrate --yes` | Apply every applicable migration without the per-change prompt (still prints what changed). |
+
+## Steps
+
+1. **Resolve the installed version** from `.claude-plugin/plugin.json` (`version`).
+2. **Load the registry.** Parse `reference/DEPRECATIONS.md` with the pure helper:
+
+   ```bash
+   node -e '
+     const fs = require("fs");
+     const dr = require("./scripts/lib/deprecation-registry.cjs");
+     const entries = dr.parseDeprecations(fs.readFileSync("reference/DEPRECATIONS.md","utf8"));
+     const version = require("./.claude-plugin/plugin.json").version;
+     // Only entries that are deprecated/removed at the installed version are actionable.
+     const actionable = entries.filter(e => dr.classify(e, version) !== "pending");
+     console.log(JSON.stringify({ version, actionable }));
+   '
+   ```
+
+3. **Scan the project** for each actionable entry's `Old` path:
+   - `.design/config.json` (string values referencing an old path),
+   - project-local skill/agent references (`grep` the repo, excluding `.git/`, `node_modules/`, and
+     GDD's own `reference/DEPRECATIONS.md`),
+   - any `require(...)`/import of a removed SDK path.
+   For a code rewrite, scaffold the edit with `scripts/lib/migration/codemod-gen.cjs` (Phase 39.1) —
+   you emit the change as a reviewable patch, you do not run a codemod engine.
+4. **Preview.** Print a unified-diff-style preview per file: `Old → New`, the registry status
+   (`deprecated` vs `removed`), and the migration hint. If `--dry-run`, stop here.
+5. **Confirm + apply.** Without `--yes`, ask per change. With `--yes`, apply all. Use `Write` to make
+   the edits; never touch a file the user didn't consent to.
+6. **Report.** Summarize: files changed, references rewritten, and any `removed`-status reference that
+   still has no replacement wired (flag it loudly — that one breaks at the installed version).
+
+## Boundaries
+
+- **Preview-first.** Nothing changes before you've shown the diff (or `--yes` was passed).
+- Migrates **this project's references** to GDD paths — it does not rewrite GDD's own source, and it
+  never performs a downgrade (reverse migrations are out of scope).
+- Read the registry; never invent a migration that isn't in `reference/DEPRECATIONS.md`.
+
+## Record
+
+Print a `## Migration summary` (version, actionable entries, files changed, unresolved `removed`
+references) and append one JSONL line to `.design/intel/insights.jsonl` recording the migration run.
+Close with:
+
+```
+## MIGRATE COMPLETE
+```

package/dist/claude-code/.claude/skills/new-cycle/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: gdd-new-cycle
+description: "Start a new design cycle. Creates cycle scope in STATE.md, initializes .design/CYCLES.md entry. Each cycle has its own goal and tracks its own decisions/tasks/pipeline runs."
+argument-hint: "[<goal>]"
+tools: Read, Write, AskUserQuestion
+---
+
+# /gdd:new-cycle
+
+The cycle is the hierarchical unit above individual pipeline runs: **Cycle > Pipeline run > Wave > Task**. Each cycle has a goal, tracks its own decisions, and can span many pipeline runs. See `./milestone-completeness-rubric.md` §"Cycle level" for what counts as cycle completion (used by `/gdd:complete-cycle` to close the cycle).
+
+## Steps
+
+1. Read `.design/STATE.md`. If `cycle:` field is populated and no `complete` flag, ask: "Cycle <N> is active. End it first with `/gdd:complete-cycle`?" Abort if user declines.
+2. If no goal was passed as an argument, ask (AskUserQuestion): "What is the goal for this design cycle? (e.g., 'Redesign the checkout flow', 'Improve dashboard accessibility')"
+3. Generate cycle ID: read `.design/CYCLES.md` if present, find the max `cycle-N`, increment. If CYCLES.md is missing, start at `cycle-1`.
+4. Update `.design/STATE.md` frontmatter: set `cycle: cycle-N`.
+5. Create or append to `.design/CYCLES.md`:
+
+   ```markdown
+   ## cycle-N: <goal>
+   **Started**: <date>
+   **Status**: active
+   **Goal**: <goal>
+   **Pipeline runs**: 0
+   **Decisions made**: 0
+   ```
+
+6. Reset the `<decisions>` section in STATE.md for the new cycle. Preserve prior decisions by prepending a comment marker `<!-- prior cycle decisions archived in CYCLES.md -->`.
+7. Print: "Cycle cycle-N started. Run `@get-design-done brief` or `@get-design-done explore` to begin."
+
+## Do Not
+
+- Do not archive prior artifacts here — that's `/gdd:complete-cycle`.
+- Do not overwrite the existing CYCLES.md — append only.
+
+## NEW-CYCLE COMPLETE

package/dist/claude-code/.claude/skills/new-cycle/milestone-completeness-rubric.md

@@ -0,0 +1,87 @@
+---
+name: milestone-completeness-rubric
+type: heuristic
+version: 1.0.0
+phase: 28.5
+tags: [milestone, closeout, rubric, completion, turn-closeout, new-cycle, complete-cycle]
+last_updated: 2026-05-18
+---
+
+# Milestone Completeness Rubric
+
+What "complete" means at each layer of the gdd lifecycle. Used by `skills/turn-closeout/`,
+`skills/new-cycle/`, `skills/complete-cycle/`, the phase closeout discipline (Plan -12 of
+every phase), and the cycle wrap-up flow. Centralized here so the rubric stays consistent
+across consumers and updates land in one place rather than fanning out across N skills.
+
+## Layers
+
+The lifecycle has four nested layers. A layer is complete only when EVERY criterion at
+that layer is satisfied. Layers above can only flip complete when every layer below has
+flipped complete first — closeout walks bottom-up.
+
+### Task level
+
+The smallest unit of work — one row in a PLAN.md `<tasks>` list.
+
+- Verify command runs with exit 0 (the `<verify>` block's command).
+- The `<done>` criterion is observable (the file exists, the test passes, the output
+  matches the contract).
+- If the task is `tdd="true"`: tests pass after the GREEN step; tests fail before it.
+- File diff is scoped to the declared `files_modified` only — no collateral damage.
+- A single commit per task in conventional form `{type}({phase}-{plan}): {description}`.
+- Deviations (Rules 1, 2, 3) tracked for the SUMMARY.md "Deviations" section.
+
+### Plan level
+
+A self-contained chunk of work — one `XX-YY-PLAN.md`.
+
+- All tasks complete (per task level above).
+- Plan-level validator passes (e.g. `validate-skill-length.cjs` for Phase 28.5 buckets;
+  `validate-frontmatter.ts` for agent-frontmatter plans).
+- SUMMARY.md written at `.planning/phases/XX-name/XX-YY-SUMMARY.md` with the canonical
+  shape: deviations, files-modified table, commits, verification result, decisions.
+- No collateral damage outside the plan's declared `files_modified` list — out-of-scope
+  edits are forbidden (executor Rule 5 boundary).
+- A final docs commit aggregates `SUMMARY.md`, `STATE.md`, `ROADMAP.md`, and
+  `REQUIREMENTS.md` updates.
+
+### Phase level
+
+A coherent batch of plans — one `XX-name/` directory under `.planning/phases/`.
+
+- All plans complete (per plan level above).
+- Phase-level verification ALL pass (`<verification>` block in each PLAN.md).
+- ROADMAP.md flipped `[ ]` → `[x]` for all plans in this phase (rule #14: scoped flip
+  only — never flip plans outside this phase).
+- Phase SUMMARY ladder coherent — each `XX-YY-SUMMARY.md` exists and reads top-to-bottom
+  as a single story.
+- All decisions surfaced through the SUMMARY frontmatter and rolled up into STATE.md's
+  `<decisions>` block.
+
+### Cycle level
+
+A shipping milestone — typically one minor version bump in the gdd project.
+
+- All phases for the cycle's target version complete (per phase level above).
+- 4 manifests version-aligned: `plugin.json`, `marketplace.json`, `package.json`, and
+  the phase-20 manifests-version baseline (`test-fixture/baselines/phase-XX/manifests-version.txt`).
+- CHANGELOG.md entry written for the new version with one block per phase.
+- Off-cadence registration if applicable — `tests/semver-compare.test.cjs` adds
+  `OFF_CADENCE_VERSIONS.add('<version>')` for `.5`/`.6`/`.7` insertion-style versions.
+- Regression baseline at `test-fixture/baselines/phase-XX/` exists and the
+  `tests/phase-XX-baseline.test.cjs` suite passes (version-agnostic — reads
+  `package.json#version`).
+- NOTICE attribution updated if any third-party content was adopted in this cycle.
+- Closeout plan's scoped ROADMAP flip touches only this cycle's checkboxes (precedent:
+  Phase 28 closeout flipped exactly 7 inline + 1 overview entry).
+
+## Cross-references
+
+- `./STATE-TEMPLATE.md` — STATE.md schema; closeout updates the `<position>` block's
+  `last_checkpoint` field.
+- `../skills/turn-closeout/SKILL.md` — consumer at the turn boundary (within a stage).
+- `../skills/new-cycle/SKILL.md` — consumer at cycle ingress.
+- `../skills/complete-cycle/SKILL.md` — consumer at cycle egress.
+- `../skills/quality-gate/SKILL.md` — Stage 4.5 gate that gates the plan-level "verify
+  command runs with exit 0" criterion when project tooling exists.

package/dist/claude-code/.claude/skills/new-project/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: gdd-new-project
+description: "Initialize a new get-design-done project. Gathers project context, creates PROJECT.md and STATE.md, initializes first cycle. Run once per project before any pipeline stage."
+argument-hint: "[--name <project-name>]"
+tools: Read, Write, AskUserQuestion, Bash, Glob
+---
+
+# /gdd:new-project
+
+One-time project initialization. Replaces "run scan cold" by gathering context up front and producing PROJECT.md + STATE.md + cycle-1.
+
+## Steps
+
+1. **Existing check**: If `.design/STATE.md` exists, ask (AskUserQuestion): "Project already initialized. Re-initialize? (This does not delete existing work.)" Abort if declined.
+2. **Create directory**: `mkdir -p .design` via Bash.
+3. **Auto-detect from codebase** (do this before asking):
+   - Read `package.json` for framework (React/Next.js/Vue/SvelteKit/etc.).
+   - Glob for `tailwind.config.*`, `components/`, `src/`, `shadcn.json` to guess the design system.
+   - Use directory name as default project name.
+4. **Gather context** (AskUserQuestion, one at a time, pre-filled with detected values):
+   - Project name
+   - Project type (framework)
+   - Main design goal
+   - Primary user
+   - Design system / component library
+5. **Write `.design/PROJECT.md`**:
+   ```markdown
+   # Project: <name>
+   **Type**: <framework>
+   **Design system**: <system>
+   **Main goal**: <goal>
+   **Primary user**: <user>
+   **Initialized**: <date>
+   ```
+6. **Initialize STATE.md**: Copy from `reference/STATE-TEMPLATE.md`, fill in project name, set stage to `brief`, cycle to `cycle-1`.
+7. **Create `.design/config.json`** with defaults from `reference/config-schema.md`.
+8. **Initialize first cycle**: Write `.design/CYCLES.md` with a `cycle-1` entry (goal copied from PROJECT.md main goal, status `active`).
+9. **Seed project-local skills directory**: Create `./.claude/skills/` and write `./.claude/skills/README.md`:
+   ```markdown
+   # Project-Local Skills
+
+   Auto-loaded by gdd pipeline stages. See `reference/project-skills-guide.md` in the plugin.
+   Files named `design-*-conventions.md` are read by explore/plan/design.
+   Populated by `/gdd:sketch-wrap-up` and manual edits.
+   ```
+10. Print: "Project initialized. Run `/gdd:brief` to capture your design problem, or `/gdd:explore` to scan directly. Run `/gdd:connections` to wire up optional integrations (Figma, Storybook, Chromatic, etc.)."
+
+## Do Not
+
+- Do not delete or overwrite existing `.design/` artifacts if re-initializing.
+- Do not run any pipeline stage automatically — this is init only.
+
+## NEW-PROJECT COMPLETE

package/dist/claude-code/.claude/skills/next/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: gdd-next
+description: "Routes to the next pipeline stage based on current STATE.md position"
+tools: Read, Write, mcp__gdd_status, mcp__gdd_phase_current, mcp__gdd_plans_list
+disable-model-invocation: true
+---
+
+# Get Design Done — Next
+
+**Role:** Lightweight router. Read `.design/STATE.md` and recommend the next command.
+
+---
+
+## Logic
+
+Two paths — MCP preferred when available, file-read fallback otherwise.
+
+### MCP path (preferred)
+
+When `mcp__gdd_phase_current` is exposed (Phase 27.7+, registered via `npx @hegemonart/get-design-done --register-mcp`):
+
+1. Call `mcp__gdd_status` (no args) → `{phase, branch, last_decisions, last_completed_plans, blocker_count}`. Gives cycle + branch context for the output block in one call.
+2. Call `mcp__gdd_phase_current` (no args) → `{phase, stage, task_progress, status}`. Use `stage` to drive the routing table below.
+3. (Optional) Call `mcp__gdd_plans_list` (no args) → current phase plans + status, to identify the next incomplete plan and refine the recommendation.
+4. If `mcp__gdd_status` returns a "STATE.md missing" error, print: "No STATE.md found. Run `/gdd:new-project` to initialize, or `@get-design-done brief` to start the pipeline." and stop. Otherwise, skip to the routing table.
+
+Two to three MCP calls = full routing decision (~3s, ~32k tokens — Storybloq benchmark).
+
+### File-read path (fallback)
+
+When MCP tools are not available, fall back to the legacy flow:
+
+1. Check if `.design/STATE.md` exists.
+   - **No STATE.md** → Print: "No STATE.md found. Run `/gdd:new-project` to initialize, or `@get-design-done brief` to start the pipeline."
+2. If STATE.md exists, parse frontmatter `stage:` field. Proceed to the routing table.
+
+This path loads the same context in 1–2 file reads (~20s, ~46.5k tokens — file-reading baseline).
+
+## Routing table
+
+Map the `stage` (from either path above) to the next recommended command:
+
+| Current `stage:` | Recommendation |
+|---|---|
+| `brief` | Run `@get-design-done explore` to scan and interview |
+| `explore` | Run `@get-design-done plan` to create design plan |
+| `plan` | Run `@get-design-done design` to execute design tasks |
+| `design` | Run `@get-design-done verify` to audit and verify |
+| `verify` | Pipeline complete. Run `/gdd:new-cycle` for next cycle or `/gdd:ship` to create PR |
+
+## Output
+
+Print the recommendation as a single formatted block:
+
+```
+━━━ Next step ━━━
+Current stage: <stage>
+Status: <status>
+→ <recommendation>
+━━━━━━━━━━━━━━━━━━
+```
+
+## Do Not
+
+- Do not modify STATE.md.
+- Do not invoke the next stage automatically — only recommend.
+
+## NEXT COMPLETE

package/dist/claude-code/.claude/skills/note/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: gdd-note
+description: "Zero-friction idea capture during any stage. Appends to .design/NOTES.md. Subcommands: add, list, promote."
+argument-hint: "<add|list|promote> [text|line-number]"
+tools: Read, Write
+disable-model-invocation: true
+---
+
+# /gdd:note
+
+**Role:** Ephemeral design notes. Zero ceremony — no priority, no due date. Backing store: `.design/NOTES.md`.
+
+## File format
+
+```markdown
+# Design Notes
+
+- [2026-04-18 04:55] Consider revisiting the card border-radius after Phase 7 ships
+- [2026-04-18 05:10] [promoted → todo] Try a glassmorphism treatment for the sidebar
+```
+
+## Subcommands
+
+### add [text]
+Create `.design/NOTES.md` with header if missing. Append one line:
+```
+- [YYYY-MM-DD HH:MM] <text>
+```
+If text omitted, append a blank timestamped entry for the user to fill later:
+```
+- [YYYY-MM-DD HH:MM] 
+```
+
+### list
+Read `.design/NOTES.md`. Print each note line with its line number for use with `promote`.
+
+### promote [line-number]
+Read the note at that line. Delegate to `/gdd:todo add` by writing a new P2 entry into `.design/TODO.md` directly (format: `- [ ] [YYYY-MM-DD] <text>` under `## P2 — Normal`). Rewrite the original note line in NOTES.md with `[promoted → todo]` prefix before the text:
+```
+- [2026-04-18 05:10] [promoted → todo] <original text>
+```
+
+## Constraints
+
+- Never overwrite prior notes on `add`.
+- Preserve exact line order on `promote`.
+
+## NOTE COMPLETE

package/dist/claude-code/.claude/skills/openrouter-status/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: gdd-openrouter-status
+description: "Read-only OpenRouter catalog + tier-mapping diagnostic — surfaces catalog freshness (fetched_at vs the 24h TTL), the last-fetch timestamp, the resolved opus/sonnet/haiku → model mappings (via the Phase-33.6 adapter), and a per-tier preview. Use when investigating which OpenRouter model a tier resolves to, or whether the catalog cache is fresh/stale. Phase 33.6 (v1.33.6) diagnostic — /gdd:openrouter-status."
+argument-hint: "[--refresh]"
+tools: Read, Bash
+disable-model-invocation: true
+---
+
+# gdd-openrouter-status
+
+## Role
+
+You are a deterministic, read-only diagnostic skill. You do **not** spawn agents and you do **not** modify the catalog cache. You read `.design/cache/openrouter-models.json` (the Phase-33.6-01 catalog cache) via `scripts/lib/openrouter/catalog-fetcher.cjs#readCatalog`, resolve the `opus`/`sonnet`/`haiku` tiers via `scripts/lib/tier-resolver-openrouter.cjs#resolve`, and emit a single Markdown status block. Read-only — to refresh the catalog you pass `--refresh` (a single opt-in fetch gated on `OPENROUTER_API_KEY`); there is no other mutation. See `connections/openrouter.md` for setup and `reference/openrouter-tier-mapping.md` for the resolution heuristic.
+
+This is `disable-model-invocation: true` (mirroring `skills/cache-manager/SKILL.md`): the skill is user-invoked only — the model must not auto-spawn it. It never makes a model call.
+
+## Invocation Contract
+
+- **Input**: optional `--refresh`. When absent, the skill is purely read-only (cache + resolve). When `--refresh` is set AND `OPENROUTER_API_KEY` is present, it calls the Phase-33.6-01 fetcher once to refresh the cache before reading; when `--refresh` is set but no key is present, it prints the empty-state/no-key message and does NOT fetch.
+- **Output**: a Markdown OpenRouter-status block to stdout. The block is the entire output.
+
+## Procedure
+
+### 1. (Optional) refresh
+
+If `--refresh` is set and `OPENROUTER_API_KEY` is present, run a single fetch to refresh the cache:
+
+```bash
+node -e "require('./scripts/lib/openrouter/catalog-fetcher.cjs').fetchCatalog().then(()=>{}).catch(()=>{})"
+```
+
+This is the ONLY mutation the skill performs, and only on explicit `--refresh`. The fetch never throws (D-08); a failure degrades to the existing cache.
+
+### 2. Read the catalog cache
+
+Read `.design/cache/openrouter-models.json` via `readCatalog`. Missing or empty → emit the empty-state message and stop:
+
+```
+## OpenRouter Status
+
+No OpenRouter catalog yet — set OPENROUTER_API_KEY and run a cycle, or `/gdd:openrouter-status --refresh`.
+
+Tier resolution is currently falling back to the native provider (graceful degrade — D-08).
+```
+
+### 3. Compute freshness
+
+Read `fetched_at` from the cache object and compare against the 24h TTL (D-02): `age = now - fetched_at`. `age < 24h` → **fresh**; otherwise → **stale** (a stale catalog still resolves — the adapter uses the last good cache).
+
+### 4. Resolve the tiers
+
+For each of `opus`, `sonnet`, `haiku`, resolve via the adapter (it reads `.design/config.json#openrouter_tier_overrides` and applies the heuristic over the cached catalog):
+
+```bash
+node -e "const r=require('./scripts/lib/tier-resolver-openrouter.cjs');for(const t of ['opus','sonnet','haiku'])console.log(t, '->', r.resolve(t) || '(null → native fallback)')"
+```
+
+A `null` for a tier means OpenRouter has no pick → the native provider resolves that tier (D-08). Note any tier that resolved from an explicit `openrouter_tier_overrides` pin vs the heuristic.
+
+### 5. Print the status block
+
+```
+## OpenRouter Status
+
+Catalog source: <source URL from cache>
+Last fetched:   <fetched_at>  (<fresh | stale> — TTL 24h)
+Models in catalog: <count>
+
+| Tier   | Resolved model id                | Source             |
+|--------|----------------------------------|--------------------|
+| opus   | <id or (null → native fallback)> | <override | heuristic> |
+| sonnet | <id or (null → native fallback)> | <override | heuristic> |
+| haiku  | <id or (null → native fallback)> | <override | heuristic> |
+
+> Resolution: override (`.design/config.json#openrouter_tier_overrides`) wins, else the closed-vs-open + pricing heuristic over the catalog.
+> A null resolution means tier resolution falls back to the native provider (D-08).
+> Read-only — this skill never modifies the cache; use `--refresh` to re-fetch (needs OPENROUTER_API_KEY).
+```
+
+## Completion marker
+
+End the output with:
+
+```
+## OPENROUTER-STATUS COMPLETE
+```

package/dist/claude-code/.claude/skills/optimize/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: optimize
+description: "Reads .design/telemetry/costs.jsonl + .design/agent-metrics.json, runs rule-based analysis, writes .design/OPTIMIZE-RECOMMENDATIONS.md. Pure advisory — no auto-apply. User reviews + decides."
+argument-hint: "[--refresh] [--min-spawns=N]"
+user-invocable: true
+tools: Read, Bash, Grep, Write
+---
+
+# /gdd:optimize — Optimization Advisor
+
+## Role
+
+Read the telemetry ledger (`.design/telemetry/costs.jsonl`) and per-agent aggregate (`.design/agent-metrics.json`), apply a fixed set of rule-based heuristics, and emit recommendations to `.design/OPTIMIZE-RECOMMENDATIONS.md`. Never modify agent files, budget config, or cache state. Output is a markdown table of proposals the user reviews manually, mirroring Phase 11 `/gdd:apply-reflections`. **Advisory only**: never edits `agents/*.md`, `.design/budget.json`, `.design/cache-manifest.json`. Never makes model calls — every rule is deterministic. See `./reference/heuristics.md` §"Optimization rules" for the full rule catalog.
+
+## Refresh Step
+
+Before analysis, invoke the aggregator:
+
+```bash
+node --experimental-strip-types scripts/aggregate-agent-metrics.ts
+```
+
+Idempotent. If `--refresh` absent and `.design/agent-metrics.json` generated within 60s, skip.
+
+## Inputs
+
+- `.design/telemetry/costs.jsonl` — append-only; tolerant of malformed lines.
+- `.design/agent-metrics.json` — per-agent aggregate; source of truth for `cache_hit_rate`, `lazy_skip_rate`, `total_cost_usd`, `total_spawns`.
+- `agents/*.md` — frontmatter cross-reference for tier override churn + typical-duration drift.
+- `.design/budget.json` — `tier_overrides` table (optional).
+
+## Optional Arguments
+
+- `--refresh` — force aggregator refresh even if metrics file is fresh.
+- `--min-spawns=N` — only emit recommendations for agents with ≥ N spawns (default 5).
+
+## Rules
+
+Rule-based analysis. Full thresholds + emission templates in `./reference/heuristics.md` §"Optimization rules"; here, the short rule catalog:
+
+- **R1 — Low cache hit rate.** IF `total_spawns >= --min-spawns` AND `cache_hit_rate < 0.20` → propose batching + investigate shared-preamble ordering.
+- **R2 — Expensive + rarely lazy-skipped.** IF `total_cost_usd > 0.50` AND `lazy_skip_rate < 0.10` → propose adding a lazy gate at `agents/{agent}-gate.md` (Plan 10.1-04 pattern).
+- **R3 — Tier override churn.** IF measured `tier` differs from frontmatter `default-tier` for multiple rows → propose updating frontmatter or removing budget.json override.
+- **R4 — Typical duration drift.** IF measured `typical_duration_seconds` differs from frontmatter by > 50% → propose frontmatter update. (v1 only computes wall-clock duration if both spawn + complete rows have matching correlation IDs; otherwise flag "insufficient data".)
+
+## Output Format
+
+Write `.design/OPTIMIZE-RECOMMENDATIONS.md`:
+
+```markdown
+# Optimization Recommendations
+
+**Generated:** {ISO-8601 timestamp}
+**Telemetry rows analyzed:** {N}
+**Agents analyzed:** {M}
+**Min spawns threshold:** {--min-spawns value}
+
+> Advisory only. No changes have been applied. Review each proposal and apply manually via the suggested action.
+
+## Proposals
+
+| Rule | Agent | Current | Proposed | Rationale |
+|------|-------|---------|----------|-----------|
+| R1 | ... | ... | ... | ... |
+
+## Summary
+
+- R1 matches: {count}
+- R2 matches: {count}
+- R3 matches: {count}
+- R4 matches: {count}
+
+## OPTIMIZE COMPLETE
+```
+
+The `## OPTIMIZE COMPLETE` marker is the completion sentinel.
+
+## No Auto-Apply
+
+This skill **never modifies** `agents/*.md`, `.design/budget.json`, `.design/cache-manifest.json`, or any other configuration. **Never auto-applies** proposals. If the user wants to act, they do so manually. Discipline mirrors `/gdd:apply-reflections` from Phase 11.
+
+## Integration with Phase 11 Reflector
+
+The Phase 11 reflector (`agents/design-reflector.md`) reads both `costs.jsonl` and `agent-metrics.json` on its own cadence. `/gdd:optimize` is user-facing; the reflector is automation-facing. Outputs land in different files (`.design/OPTIMIZE-RECOMMENDATIONS.md` vs `.design/reflections/*.md`) and never collide.
+
+## Non-Goals
+
+- Does not make model calls (rule-based, deterministic).
+- Does not modify config.
+- Does not propose changes outside the four rules — future rules added by future phases.
+- Does not learn from history — Phase 11 reflector territory.
+
+## Failure Modes
+
+- Missing `.design/telemetry/costs.jsonl` → emit `No telemetry data yet — run /gdd:* commands to accumulate data, then retry.` + `## OPTIMIZE COMPLETE`.
+- Missing `.design/agent-metrics.json` after refresh → emit `Aggregator failed — check node --experimental-strip-types scripts/aggregate-agent-metrics.ts output manually.`
+- Zero rules matched → write `No recommendations — all agents within healthy thresholds.` + `## OPTIMIZE COMPLETE`.