@hegemonart/get-design-done 1.0.7

package/reference/intel-schema.md

@@ -0,0 +1,266 @@
+# Intel Store Schema
+
+Version: 1.0.0
+Path: `.design/intel/` (gitignored — runtime data only)
+
+## Overview
+
+The intel store is a set of flat JSON files (slices) that index the design surface.
+Each slice is an independent file. Agents read slices they need; the updater rewrites only changed slices.
+
+Slices are rebuilt by `scripts/build-intel.cjs` (full initial build) and kept current by the
+`gdd-intel-updater` agent (incremental updates triggered by file changes).
+
+## Slice Definitions
+
+### files.json
+
+Index of all design-surface files tracked in the project.
+
+```json
+{
+  "generated": "<ISO-8601 timestamp>",
+  "git_hash": "<short SHA of HEAD at build time>",
+  "files": [
+    {
+      "path": "skills/scan/SKILL.md",
+      "type": "skill",
+      "mtime": "<ISO-8601>",
+      "size_bytes": 1240,
+      "git_hash": "<short SHA of last commit touching this file>"
+    }
+  ]
+}
+```
+
+`type` values: `skill`, `agent`, `reference`, `connection`, `script`, `hook`, `config`, `test`, `other`
+
+---
+
+### exports.json
+
+Named exports from each file (frontmatter `name:` fields, command names, agent names).
+
+```json
+{
+  "generated": "<ISO-8601>",
+  "exports": [
+    {
+      "file": "skills/scan/SKILL.md",
+      "kind": "skill",
+      "name": "gdd-scan",
+      "command": "/gdd:scan"
+    },
+    {
+      "file": "agents/design-verifier.md",
+      "kind": "agent",
+      "name": "design-verifier"
+    }
+  ]
+}
+```
+
+`kind` values: `skill`, `agent`, `reference`, `other`
+
+---
+
+### symbols.json
+
+Headings, section anchors, and named concepts extracted from markdown files.
+
+```json
+{
+  "generated": "<ISO-8601>",
+  "symbols": [
+    {
+      "file": "reference/accessibility.md",
+      "heading": "## WCAG Contrast Thresholds",
+      "level": 2,
+      "anchor": "wcag-contrast-thresholds",
+      "line": 42
+    }
+  ]
+}
+```
+
+---
+
+### tokens.json
+
+Design token references found across skill and agent files (color, spacing, typography, radius).
+
+```json
+{
+  "generated": "<ISO-8601>",
+  "tokens": [
+    {
+      "file": "skills/style/SKILL.md",
+      "token": "--color-primary",
+      "category": "color",
+      "line": 18,
+      "context": "Check `--color-primary` against WCAG AA"
+    }
+  ]
+}
+```
+
+`category` values: `color`, `spacing`, `typography`, `radius`, `shadow`, `motion`, `other`
+
+---
+
+### components.json
+
+Component names referenced or defined across design surface files.
+
+```json
+{
+  "generated": "<ISO-8601>",
+  "components": [
+    {
+      "file": "skills/design/SKILL.md",
+      "component": "Button",
+      "role": "reference",
+      "line": 31
+    }
+  ]
+}
+```
+
+`role` values: `definition`, `reference`, `example`
+
+---
+
+### patterns.json
+
+Design patterns classified by concern, extracted from design-pattern-mapper output and reference docs.
+
+```json
+{
+  "generated": "<ISO-8601>",
+  "patterns": [
+    {
+      "name": "color-system",
+      "category": "color-system",
+      "source_file": "reference/heuristics.md",
+      "description": "Semantic color token usage pattern"
+    }
+  ]
+}
+```
+
+`category` values: `color-system`, `spacing-system`, `typography-system`, `component-styling`, `layout`, `interaction`, `other`
+
+---
+
+### dependencies.json
+
+Intra-project @-references and explicit reads-from relationships between files.
+
+```json
+{
+  "generated": "<ISO-8601>",
+  "dependencies": [
+    {
+      "from": "skills/verify/SKILL.md",
+      "to": "reference/accessibility.md",
+      "kind": "at-reference",
+      "line": 7
+    },
+    {
+      "from": "agents/design-verifier.md",
+      "to": "reference/heuristics.md",
+      "kind": "reads-from",
+      "line": 3
+    }
+  ]
+}
+```
+
+`kind` values: `at-reference`, `reads-from`, `skill-calls-agent`, `agent-calls-agent`
+
+---
+
+### decisions.json
+
+Architectural decisions extracted from DESIGN-CONTEXT.md and `.design/DESIGN-DECISIONS.md` (if present).
+
+```json
+{
+  "generated": "<ISO-8601>",
+  "decisions": [
+    {
+      "id": "D-01",
+      "summary": "Use Figma MCP for token extraction — merge not replace grep results",
+      "source_file": ".design/DESIGN-CONTEXT.md",
+      "line": 12,
+      "date": "2026-04-18"
+    }
+  ]
+}
+```
+
+---
+
+### debt.json
+
+Design debt items extracted from `.design/DESIGN-DEBT.md`.
+
+```json
+{
+  "generated": "<ISO-8601>",
+  "debt": [
+    {
+      "id": "DEBT-01",
+      "summary": "Spacing token --space-4 used inconsistently across 3 components",
+      "severity": "medium",
+      "source_file": ".design/DESIGN-DEBT.md",
+      "line": 8
+    }
+  ]
+}
+```
+
+`severity` values: `high`, `medium`, `low`
+
+---
+
+### graph.json
+
+Cross-reference graph: nodes are files, edges are dependency relationships from dependencies.json.
+
+```json
+{
+  "generated": "<ISO-8601>",
+  "nodes": [
+    { "id": "skills/verify/SKILL.md", "type": "skill", "name": "gdd-verify" }
+  ],
+  "edges": [
+    {
+      "from": "skills/verify/SKILL.md",
+      "to": "reference/accessibility.md",
+      "kind": "at-reference"
+    }
+  ]
+}
+```
+
+## Incremental Update Rules
+
+1. On each run, compare current file `mtime` and `git_hash` against `files.json` entries.
+2. Only re-extract slices for files that changed.
+3. Always regenerate `graph.json` after any dependency slice update.
+4. `generated` timestamp in each slice reflects the last time that slice was written.
+
+## Usage by Agents
+
+Agents read slices conditionally using the `@.design/intel/<slice>.json (if present)` pattern.
+This allows graceful degradation when the intel store has not been built yet.
+
+Example conditional read block in an agent:
+
+```
+<required_reading>
+@.design/intel/tokens.json (if present)
+@.design/intel/components.json (if present)
+</required_reading>
+```

package/reference/model-prices.md

@@ -0,0 +1,37 @@
+# Model Prices — Static Price Table
+
+**Source of truth for `est_cost_usd` calculations** in the router (`skills/router/SKILL.md`) and budget-enforcer hook (`hooks/budget-enforcer.js`). Anthropic-only pricing. Update the table here when prices change — downstream calculators read this file.
+
+## Pricing (USD per 1M tokens)
+
+| Model | Tier | input_per_1m | output_per_1m | cached_input_per_1m |
+|-------|------|--------------|---------------|----------------------|
+| claude-haiku-4-5 | haiku | 1.00 | 5.00 | 0.10 |
+| claude-sonnet-4-7 | sonnet | 3.00 | 15.00 | 0.30 |
+| claude-opus-4-7 | opus | 15.00 | 75.00 | 1.50 |
+
+## size_budget → conservative token ranges
+
+Agent frontmatter carries `size_budget: S|M|L|XL`. The router uses these conservative token ranges to compute a pre-spawn `est_cost_usd` without a live model call:
+
+| size_budget | input_tokens (conservative max) | output_tokens (conservative max) |
+|-------------|----------------------------------|-----------------------------------|
+| S | 4000 | 1000 |
+| M | 10000 | 2500 |
+| L | 25000 | 6000 |
+| XL | 60000 | 15000 |
+
+## Estimator formula
+
+```
+est_cost_usd =
+  (input_tokens / 1_000_000) * input_per_1m
+  + (output_tokens / 1_000_000) * output_per_1m
+```
+
+When `cache_hit: true` (see D-08), the hook re-runs the formula with `cached_input_per_1m` in place of `input_per_1m` for the input portion.
+
+## Update protocol
+
+1. Pricing change: update the table above; commit as `chore(reference): update Anthropic pricing YYYY-MM-DD`.
+2. size_budget revision: requires a Phase 11 reflector proposal under `[FRONTMATTER]` scope; do not hand-edit agent ranges.

package/reference/model-tiers.md

@@ -0,0 +1,118 @@
+# Model Tiers — Selection Guide + Per-Agent Map
+
+**Purpose:** Source of truth for the `default-tier: haiku|sonnet|opus` frontmatter field carried by every agent at `agents/*.md`. Tiers are one of three Anthropic model classes — priced in `reference/model-prices.md`.
+
+Phase 10.1 (OPT-06) locked the initial per-agent tier assignment. Phase 11's `design-reflector` (`agents/design-reflector.md`) proposes refinements from measured `.design/agent-metrics.json` data; no auto-apply — proposals flow through `/gdd:apply-reflections` and `/gdd:optimize`.
+
+---
+
+## Tier Assignment Rules
+
+### haiku — Verifiers and checkers with deterministic rubrics
+
+Pick `haiku` when the agent is:
+- Applying a fixed scoring rubric (`design-verifier` runs five deterministic passes with numeric category scores).
+- Producing a boolean + rationale answer (`design-plan-checker`, `design-context-checker`, `design-integration-checker` all return "gaps found" + structured list).
+- Performing a read-only state sync (`gdd-graphify-sync` mirrors graph state — no reasoning density beyond schema matching).
+- Running at high frequency where cost compounds (checkers run on every `/gdd:verify` pass — cost multiplies with iterations).
+
+Haiku's ~20x price advantage over Opus per 1M tokens (see `reference/model-prices.md`) makes it correct for deterministic-rubric work where the marginal quality gain of larger models is negligible.
+
+### sonnet — Researchers, mappers, doc-writers, executors, fixers
+
+Pick `sonnet` when the agent is:
+- Doing open-ended pattern recognition on codebase data (`a11y-mapper`, `component-taxonomy-mapper`, `design-pattern-mapper`, `motion-mapper`, `token-mapper`, `visual-hierarchy-mapper`).
+- Synthesizing prose from structured input (`design-doc-writer`, `design-research-synthesizer`, `design-context-builder`).
+- Executing a concrete plan under supervision (`design-executor`, `design-fixer`, `design-figma-writer`).
+- Conducting targeted research under a time budget (`design-phase-researcher` — 2-minute web-search budget).
+- Updating / extracting / maintaining project state (`gdd-intel-updater`, `gdd-learnings-extractor`, `design-auditor`).
+
+Sonnet balances reasoning density against cost. This is the default — if you're uncertain about an agent's role, it's probably sonnet.
+
+### opus — Planners, critics, advisors, strategic reflectors
+
+Pick `opus` when the agent is:
+- Proposing a plan that downstream executors will follow (`design-planner` — the plan becomes the contract for the whole design stage).
+- Critiquing or advising on ambiguity (`design-advisor`, `design-assumptions-analyzer` — these agents question the prompt itself).
+- Facilitating interactive decision-gathering (`design-discussant`).
+- Cross-phase strategic reasoning (`design-reflector` — Phase 11 — proposes changes to the plugin itself from measured data).
+
+Opus cost (~5x Sonnet, ~25x Haiku) is justified only when a single wrong decision cascades into many downstream agent spawns. Planners fit. Mappers don't.
+
+---
+
+## Per-Agent Tier Map
+
+| Agent | Role class | default-tier | Rationale |
+|-------|------------|--------------|-----------|
+| design-verifier | Verifier | haiku | Runs a deterministic 5-pass scoring rubric; Haiku handles structured grading without quality loss. |
+| design-plan-checker | Checker | haiku | Checks the plan against a fixed schema — boolean + gap-list output. |
+| design-context-checker | Checker | haiku | Checks context completeness against a schema — boolean + gap-list output. |
+| design-integration-checker | Checker | haiku | Checks cross-artifact references — deterministic link-integrity work. |
+| gdd-graphify-sync | Sync agent | haiku | Mirrors graph state to the graph store — no reasoning density required. |
+| a11y-mapper | Mapper | sonnet | Open-ended a11y pattern recognition across many files; Sonnet's breadth matters. |
+| component-taxonomy-mapper | Mapper | sonnet | Classifies components by role — requires nuance Haiku lacks, not enough to warrant Opus. |
+| design-auditor | Worker | sonnet | Emits structured findings from code inspection; Sonnet balances depth with cost. |
+| design-context-builder | Builder | sonnet | Assembles DESIGN-CONTEXT.md from discover outputs — prose synthesis. |
+| design-doc-writer | Writer | sonnet | Produces polished prose documentation; Sonnet's style quality is sufficient. |
+| design-executor | Executor | sonnet | Follows an Opus-authored plan — executes rather than plans. |
+| design-figma-writer | Writer | sonnet | Emits Figma-formatted output from existing spec. |
+| design-fixer | Fixer | sonnet | Applies targeted fixes to a localized artifact; structured input, structured diff output. |
+| design-pattern-mapper | Mapper | sonnet | Catalogs design patterns present in codebase. |
+| design-phase-researcher | Researcher | sonnet | Time-budgeted research on project-type conventions. |
+| design-research-synthesizer | Synthesizer | sonnet | Collapses multiple research outputs into one; synthesis is Sonnet territory. |
+| gdd-intel-updater | Updater | sonnet | Refreshes .planning/intel/ files from current codebase. |
+| gdd-learnings-extractor | Extractor | sonnet | Pulls decisions + lessons + patterns from phase artifacts. |
+| motion-mapper | Mapper | sonnet | Inventories motion patterns — open-ended visual reasoning. |
+| token-mapper | Mapper | sonnet | Extracts design tokens from source — pattern recognition across files. |
+| visual-hierarchy-mapper | Mapper | sonnet | Maps visual hierarchy signals — breadth across many files. |
+| design-advisor | Advisor | opus | Questions prompts to surface ambiguity — wrong advice cascades. |
+| design-assumptions-analyzer | Critic | opus | Surfaces load-bearing assumptions before planning — one wrong assumption derails the phase. |
+| design-discussant | Facilitator | opus | Interactive decision gathering — user-facing, quality-critical. |
+| design-planner | Planner | opus | Authors DESIGN-PLAN.md — the contract every downstream agent follows. |
+| design-reflector | Strategic reflector | opus | Phase 11 — reads telemetry + proposes changes to the plugin itself. |
+
+**Row count:** 26 — matches the agent suite ls. Every row has a rationale; no blank rationales.
+
+---
+
+## Override Precedence
+
+When the budget-enforcer hook resolves which tier to spawn an agent at, it walks this precedence (D-04):
+
+1. **`.design/budget.json.tier_overrides[{agent_name}]`** — per-project configuration. Wins over frontmatter. Use this knob when the project has budget constraints that differ from the plugin defaults.
+2. **Agent frontmatter `default-tier`** (this file's per-agent map) — plugin default. Set at authoring time.
+3. **Hardcoded fallback `"sonnet"`** — belt-and-suspenders in `hooks/budget-enforcer.js` for agents that somehow lack the frontmatter field. Should never fire in practice after Phase 10.1.
+
+Plus two modifiers that can override the above at spawn time:
+
+- **`auto_downgrade_on_cap: true`** (D-03): at 80% of `per_task_cap_usd`, the hook force-downgrades the tier to `haiku` for the remainder of the task, regardless of the precedence chain. Logged as `tier_downgraded: true` in `.design/telemetry/costs.jsonl`.
+- **Hard-cap block** (D-02): at 100% of `per_task_cap_usd` or `per_phase_cap_usd`, the hook blocks the spawn outright. Tier is irrelevant — nothing runs.
+
+---
+
+## When to Upgrade or Downgrade
+
+The plugin ships with the Per-Agent Tier Map above as a well-reasoned baseline. **Do not hand-edit agent frontmatter `default-tier` fields without evidence.** Two legitimate paths to change a tier assignment:
+
+1. **Phase 11 reflector proposal.** `agents/design-reflector.md` reads `.design/agent-metrics.json` and surfaces cases where measured `gap_rate` or `deviation_rate` suggests a tier is too low (verifier missed gaps a Sonnet would catch) or too high (planner over-reasoned simple plans a Sonnet would handle). Proposals flow through `/gdd:apply-reflections` — user-reviewed, never auto-applied.
+2. **Budget constraint.** Project-level override via `.design/budget.json.tier_overrides` — does not require touching the frontmatter.
+
+Signals that a tier move might be warranted (Phase 11 reflector's heuristics):
+- **Downgrade signal** (Sonnet → Haiku, or Opus → Sonnet): agent's `gap_rate < 10%` over ≥ 10 runs AND measured output length < 25% of `size_budget` ceiling → agent is over-provisioned.
+- **Upgrade signal** (Haiku → Sonnet, or Sonnet → Opus): agent's `deviation_rate > 15%` over ≥ 5 runs (agent frequently misinterprets prompt) → reasoning density may be the bottleneck.
+
+Phase 11's reflector encodes these heuristics. This section documents the philosophy so contributors understand why an edit to this file shows up in a reflector proposal.
+
+---
+
+## Integration Points
+
+- **`hooks/budget-enforcer.js`** (Plan 10.1-01 Task 04) — implements the precedence chain above. `resolveTier(agent, agentDefaultTier, overrides)` is the concrete function.
+- **`skills/router/SKILL.md`** (Plan 10.1-01 Task 03) — consults this file's tier map + `reference/model-prices.md` to produce `estimated_cost_usd` pre-spawn.
+- **`skills/optimize/SKILL.md`** (Plan 10.1-04) — advisory command; may suggest tier moves based on telemetry + this doc's heuristics.
+- **`agents/design-reflector.md`** (Phase 11, already merged) — may propose edits to this file + paired frontmatter updates. Proposals land in `.design/reflections/` for user review.
+
+---
+
+*Maintained as part of Phase 10.1 (OPT-06). Edits to the Per-Agent Tier Map MUST be paired with matching frontmatter edits in `agents/*.md` — the two are the same fact stored twice (router cross-checks). A mismatch indicates drift; Phase 11 reflector detects and reports it.*