@hegemonart/get-design-done 1.0.7

package/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: get-design-done
+short_name: gdd
+description: "Master design pipeline for Claude Code. 5-stage workflow: Brief → Explore → Plan → Design → Verify. Run 'brief' first in any new project to capture the design problem, then 'explore' to inventory the codebase and interview for context. Invoke without arguments for status and auto-routing."
+argument-hint: "[brief|explore|plan|design|verify|handoff|map|next|help|status|style|darkmode|compare|figma-write|graphify|discuss|list-assumptions|progress|health|todo|stats|note|plant-seed|add-backlog|review-backlog|scan|discover|settings|update|reapply-patches|audit|pause|resume|new-cycle|debug|quick|new-project|complete-cycle|fast|do|ship|undo|pr-branch|sketch|sketch-wrap-up|spike|spike-wrap-up|reflect|apply-reflections|analyze-dependencies|extract-learnings|skill-manifest|warm-cache|optimize|cache-manager]"
+user-invocable: true
+---
+
+# Get Design Done — Pipeline Router
+
+Entry point for the get-design-done toolkit. Establishes the `/gdd:` command namespace.
+
+```
+Brief → Explore → Plan → Design → Verify  →  next
+```
+
+The 5-stage pipeline. `scan` and `discover` are now merged into `explore` — their old aliases still route through for backward compatibility.
+
+Each stage produces artifacts in `.design/` inside the current project.
+
+## Command Reference
+
+| Command | Skill | Purpose |
+|---|---|---|
+| `brief` | `get-design-done:gdd-brief` | Stage 1 of 5 — capture problem, audience, constraints, metrics, scope → BRIEF.md |
+| `explore` | `get-design-done:gdd-explore` | Stage 2 of 5 — inventory scan + design interview → DESIGN.md, DESIGN-DEBT.md, DESIGN-CONTEXT.md |
+| `plan` | `get-design-done:plan` | Stage 3 of 5 — decompose into tasks → DESIGN-PLAN.md |
+| `design` | `get-design-done:design` | Stage 4 of 5 — execute tasks → DESIGN-SUMMARY.md |
+| `verify` | `get-design-done:verify` | Stage 5 of 5 — score + audit → DESIGN-VERIFICATION.md |
+| `handoff <path>` | inline | Skip scan/discover/plan; initialize from Claude Design bundle; route to verify |
+| `map` | `get-design-done:gdd-map` | Parallel codebase mapping — spawns 5 mappers → `.design/map/*.md` + `.design/DESIGN-MAP.md` |
+| `next` | `get-design-done:gdd-next` | Route to the next pipeline stage based on STATE.md |
+| `help` | `get-design-done:gdd-help` | List all commands with one-line descriptions |
+| `style [ComponentName]` | `get-design-done:style` | Generate component handoff doc → .design/DESIGN-STYLE-[Name].md |
+| `darkmode` | `get-design-done:darkmode` | Audit dark mode architecture + contrast + anti-patterns → .design/DARKMODE-AUDIT.md |
+| `compare` | `get-design-done:compare` | Delta between DESIGN.md baseline and DESIGN-VERIFICATION.md → .design/COMPARE-REPORT.md |
+| `figma-write <mode>` | `get-design-done:figma-write` | Write design decisions to Figma (annotate/tokenize/mappings) |
+| `graphify <subcommand>` | `get-design-done:graphify` | Manage Graphify knowledge graph (build/query/status/diff) |
+| `discuss [topic] [--all] [--spec] [--cycle <name>]` | `get-design-done:gdd-discuss` | Adaptive design interview — spawns design-discussant; appends D-XX decisions to STATE.md |
+| `list-assumptions [--area]` | `get-design-done:gdd-list-assumptions` | Surface implicit design assumptions baked into the codebase |
+| **Audit & Session** | | |
+| `audit [--retroactive] [--quick] [--no-reflect]` | `get-design-done:gdd-audit` | Wraps design-verifier + design-auditor + design-reflector; `--retroactive` audits full cycle scope |
+| `reflect [--dry-run] [--cycle <slug>]` | `get-design-done:gdd-reflect` | On-demand reflection — reads cycle data, produces improvement proposals → `.design/reflections/<slug>.md` |
+| `apply-reflections [--filter <type>] [--dry-run]` | `get-design-done:gdd-apply-reflections` | Review + selectively apply reflection proposals (FRONTMATTER/REFERENCE/BUDGET/QUESTION/GLOBAL-SKILL) |
+| `pause [context]` | `get-design-done:gdd-pause` | Write session handoff to `.design/HANDOFF.md` |
+| `resume` | `get-design-done:gdd-resume` | Restore session context from `.design/HANDOFF.md` and route to next step |
+| **Lifecycle** | | |
+| `new-project [--name <n>]` | `get-design-done:gdd-new-project` | Initialize project — PROJECT.md + STATE.md + cycle-1 |
+| `new-cycle [<goal>]` | `get-design-done:gdd-new-cycle` | Start a new design cycle; writes `.design/CYCLES.md` entry |
+| `complete-cycle [<note>]` | `get-design-done:gdd-complete-cycle` | Archive cycle artifacts to `.design/archive/cycle-N/`; reset STATE.md |
+| **Execution speed** | | |
+| `quick [--skip <agent>] [stage]` | `get-design-done:gdd-quick` | Run pipeline skipping optional agents for speed |
+| `fast <task>` | `get-design-done:gdd-fast` | Trivial inline task — no subagents, no pipeline, no artifacts |
+| **Debug & Workflow** | | |
+| `debug [<symptom>]` | `get-design-done:gdd-debug` | Symptom-driven design investigation; persistent state in `.design/DEBUG.md` |
+| `do <natural language>` | `get-design-done:gdd-do` | Natural-language router — parses intent, confirms, dispatches |
+| **Ship & Safety** | | |
+| `ship [--title <t>] [--draft]` | `get-design-done:gdd-ship` | Post-verify PR flow — clean branch + `gh pr create` |
+| `pr-branch [<base>]` | `get-design-done:gdd-pr-branch` | Strip `.design/` and `.planning/` commits for clean code-review branch |
+| `undo [<sha>]` | `get-design-done:gdd-undo` | Safe revert with dependency check |
+| **Ops** | | |
+| `progress [--forensic]` | `get-design-done:gdd-progress` | Pipeline position + recommended next action; `--forensic` runs 6-check integrity audit |
+| `health` | `get-design-done:gdd-health` | Artifact health report for `.design/` |
+| `todo <add\|list\|pick> [text]` | `get-design-done:gdd-todo` | Design todo list → `.design/TODO.md` |
+| `stats` | `get-design-done:gdd-stats` | Cycle metrics — decisions, commits, todos |
+| **Idea capture** | | |
+| `note <add\|list\|promote> [text]` | `get-design-done:gdd-note` | Zero-friction notes → `.design/NOTES.md` |
+| `plant-seed [--trigger <cond>] [text]` | `get-design-done:gdd-plant-seed` | Forward-looking idea with trigger → `.design/SEEDS.md` |
+| `add-backlog [text]` | `get-design-done:gdd-add-backlog` | Park an idea → `.design/backlog/BACKLOG.md` |
+| `review-backlog` | `get-design-done:gdd-review-backlog` | Walk parked items; promote/archive |
+| **Exploration** | | |
+| `sketch [topic] [--variants N] [--quick]` | `get-design-done:gdd-sketch` | Multi-variant HTML exploration → `.design/sketches/<slug>/variant-*.html` |
+| `sketch-wrap-up [slug]` | `get-design-done:gdd-sketch-wrap-up` | Pick winner + rationale → writes `./.claude/skills/design-<area>-conventions.md` |
+| `spike [hypothesis] [--timebox N]` | `get-design-done:gdd-spike` | Timeboxed feasibility experiment → `.design/spikes/<slug>/` |
+| `spike-wrap-up [slug]` | `get-design-done:gdd-spike-wrap-up` | Capture findings + D-XX decision → `.design/spikes/<slug>/FINDINGS.md` |
+| `scan` *(deprecated)* | `get-design-done:scan` | Alias — use `explore` instead |
+| `discover` *(deprecated)* | `get-design-done:discover` | Alias — use `explore` instead |
+| **Configuration** | | |
+| `settings <profile\|parallelism\|cleanup\|show>` | `get-design-done:gdd-settings` | Manage `.design/config.json` — model profile, parallelism, cleanup |
+| **Maintenance** | | |
+| `update [--dry-run] [--version <tag>]` | `get-design-done:gdd-update` | Update plugin to latest release; preserves config + local skills |
+| `reapply-patches [--dry-run]` | `get-design-done:gdd-reapply-patches` | Reapply `reference/` customizations after an update |
+| `analyze-dependencies [--slice <name>]` | `get-design-done:analyze-dependencies` | Query the `.design/intel/` store — dependency slices, graph queries, phase-scoped reads |
+| `extract-learnings [--cycle <slug>]` | `get-design-done:extract-learnings` | Extract decisions, lessons, patterns, and surprises from a completed cycle → `.design/cycles/<slug>/LEARNINGS.md` |
+| `skill-manifest [--refresh]` | `get-design-done:skill-manifest` | List or refresh the local skill manifest used by the router for discovery |
+
+## Handoff Routing
+
+**Check FIRST** — before any other routing logic. If `$ARGUMENTS` starts with `handoff` OR contains `--from-handoff`:
+
+1. **Extract bundle path:**
+   - `handoff <path>` → bundle path is the second argument
+   - `--from-handoff <path>` → bundle path is the value after the flag
+   - Neither has a path → check STATE.md `handoff_path`; if absent, error: "Provide a bundle path: /gdd:handoff ./path/to/bundle.html"
+   - Verify the file exists; if not, error: "Bundle not found at <path>"
+
+2. **Initialize STATE.md:**
+   - If `.design/STATE.md` does not exist: copy `reference/STATE-TEMPLATE.md` to `.design/STATE.md`
+   - Set in `<position>`: `handoff_source: claude-design-html`, `handoff_path: <resolved path>`, `skipped_stages: scan, discover, plan`, `status: handoff-sourced`, `stage: verify`
+   - Set in `<connections>`: `claude_design: available`; all others remain `not_configured`
+
+3. **Spawn design-research-synthesizer** in handoff mode:
+   ```
+   Task("design-research-synthesizer", """
+   mode: handoff
+   handoff_path: <resolved bundle path>
+   state_path: .design/STATE.md
+   """)
+   ```
+   Wait for `## SYNTHESIZE COMPLETE`.
+
+4. **Spawn design-discussant** in `--from-handoff` mode:
+   ```
+   Task("design-discussant", """
+   <mode>--from-handoff</mode>
+   <required_reading>.design/STATE.md</required_reading>
+   """)
+   ```
+   Wait for `## DISCUSS COMPLETE`.
+
+5. **Route to verify** with `--post-handoff` flag:
+   ```
+   Skill("get-design-done:verify", "--post-handoff")
+   ```
+
+6. **Optional: Bidirectional write-back** (post-verify, offered to user)
+   After verify completes without FAIL-level gaps:
+   - Check STATE.md `<connections>` for `figma_writer`
+   - `figma_writer: not_configured` → skip (no offer)
+   - `figma_writer: available` → offer: "Write implementation status back to Figma? (annotates frames + Code Connect mappings)"
+     Options: [yes, write back] [dry-run, show proposal only] [skip]
+   - If yes or dry-run: spawn `agents/design-figma-writer.md` with `mode: implementation-status`, `dry_run: <true|false>`
+
+---
+
+## Routing Logic
+
+When invoked without arguments (or with `status`), show pipeline state and suggest next action:
+
+```
+1. No .design/ and no BRIEF.md → Suggest brief first: "New project — run /gdd:brief to capture the problem."
+2. BRIEF.md exists, no DESIGN.md → Route to explore
+3. DESIGN.md + DESIGN-CONTEXT.md exist, no DESIGN-PLAN.md → Route to plan
+4. DESIGN-PLAN.md exists, DESIGN-SUMMARY.md missing → Route to design
+5. DESIGN-SUMMARY.md exists, DESIGN-VERIFICATION.md missing → Route to verify
+6. DESIGN-VERIFICATION.md exists → Show summary + offer to start new cycle
+```
+
+## Status Display
+
+```
+━━━ Get Design Done Pipeline ━━━
+[✓] Brief      → .design/BRIEF.md
+[✓] Explore    → DESIGN.md + DESIGN-DEBT.md + DESIGN-CONTEXT.md   (stage 2-of-5; replaces scan+discover)
+[→] Plan       ← current stage (3-of-5)
+[ ] Design     (4-of-5)
+[ ] Verify     (5-of-5)
+```
+
+Use `[✓]` for complete, `[→]` for current, `[ ]` for pending, `[!]` for gaps/errors.
+
+## Jump Mode
+
+If `$ARGUMENTS` is a stage or command name — invoke it directly, no state check:
+
+```
+/gdd:brief     → Skill("get-design-done:gdd-brief")
+/gdd:explore   → Skill("get-design-done:gdd-explore")
+/gdd:plan      → Skill("get-design-done:plan")          # stage 3-of-5
+/gdd:design    → Skill("get-design-done:design")        # stage 4-of-5
+/gdd:verify    → Skill("get-design-done:verify")        # stage 5-of-5
+/gdd:handoff   → [Handoff Routing] (inline — see ## Handoff Routing above)
+/gdd:map       → Skill("get-design-done:gdd-map")       # parallel codebase mapping
+/gdd:next      → Skill("get-design-done:gdd-next")
+/gdd:help      → Skill("get-design-done:gdd-help")
+/gdd:style     → Skill("get-design-done:style")
+/gdd:darkmode     → Skill("get-design-done:darkmode")
+/gdd:compare      → Skill("get-design-done:compare")
+/gdd:figma-write  → Skill("get-design-done:figma-write")
+/gdd:graphify     → Skill("get-design-done:graphify")
+/gdd:discuss          → Skill("get-design-done:gdd-discuss")
+/gdd:list-assumptions → Skill("get-design-done:gdd-list-assumptions")
+/gdd:progress         → Skill("get-design-done:gdd-progress")
+/gdd:health           → Skill("get-design-done:gdd-health")
+/gdd:todo             → Skill("get-design-done:gdd-todo")
+/gdd:stats            → Skill("get-design-done:gdd-stats")
+# --- Idea capture ---
+/gdd:note           → Skill("get-design-done:gdd-note")
+/gdd:plant-seed     → Skill("get-design-done:gdd-plant-seed")
+/gdd:add-backlog    → Skill("get-design-done:gdd-add-backlog")
+/gdd:review-backlog → Skill("get-design-done:gdd-review-backlog")
+/gdd:scan      → Skill("get-design-done:gdd-explore")   # deprecated alias → explore
+/gdd:discover  → Skill("get-design-done:gdd-explore")   # deprecated alias → explore
+# --- Configuration ---
+/gdd:settings        → Skill("get-design-done:gdd-settings")
+# --- Maintenance ---
+/gdd:update          → Skill("get-design-done:gdd-update")
+/gdd:reapply-patches → Skill("get-design-done:gdd-reapply-patches")
+# --- Audit & Session ---
+/gdd:audit              → Skill("get-design-done:gdd-audit")
+/gdd:reflect            → Skill("get-design-done:gdd-reflect")
+/gdd:apply-reflections  → Skill("get-design-done:gdd-apply-reflections")
+/gdd:pause              → Skill("get-design-done:gdd-pause")
+/gdd:resume          → Skill("get-design-done:gdd-resume")
+# --- Lifecycle ---
+/gdd:new-project     → Skill("get-design-done:gdd-new-project")
+/gdd:new-cycle       → Skill("get-design-done:gdd-new-cycle")
+/gdd:complete-cycle  → Skill("get-design-done:gdd-complete-cycle")
+# --- Execution speed ---
+/gdd:quick           → Skill("get-design-done:gdd-quick")
+/gdd:fast            → Skill("get-design-done:gdd-fast")
+# --- Debug & Workflow ---
+/gdd:debug           → Skill("get-design-done:gdd-debug")
+/gdd:do              → Skill("get-design-done:gdd-do")
+# --- Ship & Safety ---
+/gdd:ship            → Skill("get-design-done:gdd-ship")
+/gdd:pr-branch       → Skill("get-design-done:gdd-pr-branch")
+/gdd:undo            → Skill("get-design-done:gdd-undo")
+# --- Exploration ---
+/gdd:sketch          → Skill("get-design-done:gdd-sketch")
+/gdd:sketch-wrap-up  → Skill("get-design-done:gdd-sketch-wrap-up")
+/gdd:spike           → Skill("get-design-done:gdd-spike")
+/gdd:spike-wrap-up   → Skill("get-design-done:gdd-spike-wrap-up")
+```
+
+Pass remaining arguments through: `/gdd:explore --skip-interview` → `Skill("get-design-done:gdd-explore", "--skip-interview")`.
+
+## Do Not
+
+- Do not perform any design work yourself — route to the stage skill.
+- Do not skip stages unless the user explicitly passes a stage argument.
+- Do not create or modify `.design/` files — the stage skills own their artifacts.

package/agents/README.md

@@ -0,0 +1,226 @@
+# Agents — Authoring Contract
+
+This directory contains the specialized agents that pipeline stages spawn to do focused work. Read this file before writing a new agent — it is the complete authoring contract. You do not need to read GSD source code.
+
+## Overview
+
+Pipeline stages are **thin orchestrators**. They read `.design/STATE.md`, decide which work to delegate, spawn one or more agents via the `Task` tool, collect results, and write updated state. The agents do the actual work: extracting design tokens, mapping patterns, writing plans, verifying artifacts.
+
+This separation provides three concrete benefits:
+
+- **Context isolation** — each agent starts fresh with only what it needs, keeping token budgets tight and results deterministic.
+- **Reusability** — the same `design-verifier` agent can be called from the `design` stage and the `verify` stage without modification.
+- **Testability** — agents can be invoked directly against fixture inputs without running the full pipeline.
+
+Agents live in `agents/` as individual markdown files. Each file contains YAML frontmatter (metadata consumed by the Claude Code `Task` tool) and a prose body (instructions the agent follows when invoked).
+
+---
+
+## Naming Convention
+
+Filenames use kebab-case with the `design-` prefix to scope them within this plugin:
+
+```
+agents/design-planner.md
+agents/design-verifier.md
+agents/design-token-extractor.md
+agents/design-pattern-mapper.md
+```
+
+The `design-` prefix prevents name collisions with agents from other Claude Code plugins. The remainder of the name describes the agent's role. Use nouns or noun phrases, not verbs: `design-planner`, not `design-plan`.
+
+---
+
+## Frontmatter Schema
+
+Every agent file begins with a YAML frontmatter block. All fields except `model` are required. The `default-tier` and `tier-rationale` fields were added in Phase 10.1 — see `reference/model-tiers.md` for the per-agent assignment rationale.
+
+| Field | Type | Accepted values | Purpose |
+|-------|------|-----------------|---------|
+| `name` | kebab-case string | unique within plugin | Identifier passed to the `Task` tool — must match the filename without `.md` |
+| `description` | string | free-form | One sentence: what the agent does + when it is spawned |
+| `tools` | comma-separated list | `Read`, `Write`, `Edit`, `Bash`, `Grep`, `Glob`, `Task`, `WebFetch`, `TodoWrite`, `mcp__*` | Claude tools the agent may use — list only what is needed |
+| `color` | enum | `yellow`, `green`, `blue`, `red` | Terminal display color for the agent's output |
+| `model` | enum (optional) | `inherit`, `sonnet`, `haiku` | Omit to use the project's configured profile default. Use `inherit` to bypass the profile and use the highest available model (quality-tier work) |
+| `default-tier` | enum | `haiku`, `sonnet`, `opus` | **Phase 10.1.** The model tier the router + budget-enforcer hook select when `.design/budget.json.tier_overrides` has no entry for this agent. Paired with `reference/model-tiers.md` — the per-agent map in that file is the source of truth; this field is the per-agent replica the hook reads. Required on all agents. |
+| `tier-rationale` | string | free-form, one line, quoted | **Phase 10.1.** One-sentence justification for the `default-tier` choice. Surfaces in `/gdd:optimize` output when the advisor suggests a tier move. Required on all agents. |
+| `parallel-safe` | enum | `always`, `never`, `conditional-on-touches`, `auto` | Whether stages may dispatch this agent in parallel with siblings. `conditional-on-touches` means safe only when `Touches:` do not overlap |
+| `typical-duration-seconds` | int | e.g. `30`, `60`, `120` | Expected wall-clock duration. Used by parallelism planner to decide whether savings clear `min_estimated_savings_seconds`. **Extensible** — Phase 10.1 adds `default-tier` override; Phase 11's `design-reflector` adds `measured-duration-seconds` from telemetry without replacing this field. |
+| `reads-only` | bool | `true`/`false` | True when the agent never writes any file |
+| `writes` | list | e.g. `[".design/DESIGN-PLAN.md"]` | Files / globs the agent may write. `[]` for read-only agents |
+
+> **Frontmatter is extensible.** New fields can be added by downstream phases without removing existing ones. The `design-reflector` agent (Phase 11) may propose updates to `typical-duration-seconds` and `default-tier` based on measured telemetry — those proposals go through `/gdd:apply-reflections`, never auto-applied.
+
+Example frontmatter block:
+
+```yaml
+---
+name: design-token-extractor
+description: Extracts design tokens (colors, typography, spacing) from scanned source files. Spawned by the scan stage.
+tools: Read, Grep, Glob
+color: blue
+---
+```
+
+---
+
+## Required Reading Pattern
+
+When an agent must read specific files before acting, the orchestrating stage embeds a `<required_reading>` block in the prompt it passes to `Task`. The block is part of the **prompt string**, not the agent file.
+
+```markdown
+<required_reading>
+@.design/STATE.md
+@reference/typography.md
+</required_reading>
+```
+
+**Invariant:** when a `<required_reading>` block is present in the prompt, the agent MUST `Read` every listed file before taking any other action. Paths starting with `@` are repo-relative (or absolute) file paths — pass them directly to the `Read` tool.
+
+Agents do not hard-code their required reading. Required reading is supplied by the stage at call time, so the same agent can be given different context for different invocations.
+
+---
+
+## Completion Markers
+
+Every agent terminates its response with a completion marker — a specific `##` heading that the orchestrating stage checks to confirm the agent finished successfully.
+
+**GSD-style markers (used by research/planning/execution/verification agents):**
+
+| Agent type | Completion marker |
+|-----------|-------------------|
+| Research agent | `## RESEARCH COMPLETE` |
+| Planning agent | `## PLANNING COMPLETE` |
+| Execution agent | `## EXECUTION COMPLETE` |
+| Verification agent | `## VERIFICATION COMPLETE` |
+
+**Design-pipeline-specific markers (proposed — confirm in Phase 2 when the first stage agent is written):**
+
+| Stage | Proposed marker |
+|-------|-----------------|
+| scan | `## SCAN COMPLETE` |
+| discover | `## DISCOVER COMPLETE` |
+| plan | `## PLAN COMPLETE` |
+| design | `## DESIGN COMPLETE` |
+| verify | `## VERIFY COMPLETE` |
+
+If the agent encounters an error or cannot complete, it still emits the completion marker but appends a failure note and writes a `<blocker>` entry to `.design/STATE.md`. The orchestrator detects failure by inspecting STATE.md, not by the absence of a marker.
+
+---
+
+## How stages invoke agents
+
+Stages spawn agents using the Claude Code `Task` tool:
+
+```
+Task("design-planner", prompt_string)
+```
+
+The first argument is the agent's `name` field (must match exactly). The second argument is a **fully self-contained prompt string** — no session state, no previous tool call results, nothing from the orchestrator's context passes through automatically. Everything the agent needs must be in the prompt.
+
+This means: if the agent needs to know the current pipeline stage, the target component, or the path to an artifact, the stage must embed that information in the prompt.
+
+---
+
+## What to include in an agent prompt
+
+Use this checklist when writing the prompt string a stage passes to `Task`:
+
+- **Task specification** — what the agent must do, stated as a concrete imperative ("Extract all color tokens from the files listed in STATE.md `<source_roots>` and write them to `.design/DESIGN-TOKENS.md`.")
+- **Context block** — paths to relevant artifacts, the current pipeline position, prior stage outputs the agent should be aware of
+- **Required reading block** — `<required_reading>` listing files the agent must read before acting
+- **Acceptance criteria** — how the orchestrator (and the agent itself) will know the task succeeded; specific, checkable conditions
+- **Output format** — structured output required: which file to write, what sections to include, what the completion marker is
+- **Constraints** — what the agent must NOT do ("do not modify files outside `.design/`", "do not run shell commands")
+
+---
+
+## Worked Example
+
+### Example agent file — `agents/design-example.md`
+
+```markdown
+---
+name: design-example
+description: Reference agent showing the required structure. Never actually invoked in production.
+tools: Read, Write, Grep
+color: blue
+---
+
+# design-example
+
+This agent demonstrates the authoring contract. Replace the role description and behavior below with real work when building a production agent.
+
+## Task
+
+Read the input artifact specified in the prompt, validate it against the acceptance criteria, produce the output artifact, and emit a completion marker.
+
+## Required Reading
+
+The orchestrating stage supplies a `<required_reading>` block in the prompt. Read every listed file before acting — this is mandatory.
+
+## Output Format
+
+Write results to the path specified in the prompt. Terminate the response with the completion marker the prompt specifies (e.g., `## VERIFY COMPLETE`). If an error occurs, still emit the marker but prepend a brief failure description and write a `<blocker>` entry to `.design/STATE.md`.
+```
+
+### Example prompt a stage would pass to this agent
+
+```
+Task("design-example", """
+<required_reading>
+@.design/STATE.md
+@reference/STATE-TEMPLATE.md
+</required_reading>
+
+Read STATE.md and confirm the <position> section contains valid fields (stage, wave, task_progress).
+Write the validation result to .design/example-output.md as a markdown table: field | value | valid.
+
+Acceptance criteria:
+- .design/example-output.md exists after this call
+- The file contains a table with the three position fields
+- Each field has a "valid" or "invalid" status
+
+Output format: markdown table, then a one-line summary, then `## VERIFY COMPLETE`.
+Constraints: do not modify any file other than .design/example-output.md.
+""")
+```
+
+---
+
+## Size Budgets
+
+Agents should be kept small — long instruction bodies burn context at every spawn and drift from their single-responsibility role. Per-tier soft limits:
+
+| Tier | Examples | Limit |
+|---|---|---|
+| Orchestrator | `design-planner`, `design-executor`, `design-verifier`, `design-reflector` | ≤ 300 lines |
+| Worker | `design-auditor`, `design-fixer`, `design-doc-writer`, `design-pattern-mapper`, `design-context-builder` | ≤ 200 lines |
+| Checker | `design-integration-checker`, `design-plan-checker`, `design-context-checker`, `design-advisor`, `design-assumptions-analyzer`, `design-phase-researcher` | ≤ 150 lines |
+
+Global ceiling: **no single agent file exceeds 600 lines** under any circumstances. When an agent approaches its tier limit, extract repeated prose into `reference/*.md` and `@`-include it from the prompt rather than inlining.
+
+---
+
+## Cache-Aligned Ordering Convention (Phase 10.1)
+
+Every agent body under `agents/*.md` is structured in this exact order so that Anthropic's 5-minute prompt cache (and the plugin's `/gdd:warm-cache` pre-warmer) can key on the longest possible identical prefix across spawns. The rule (from Phase 10.1 decision D-17):
+
+1. **Shared-preamble import** — the first non-blank line of the body MUST be `@reference/shared-preamble.md`. This pulls the framework identity, required-reading discipline, writes protocol, deviation handling, and hook awareness into the prompt. Identical bytes across all 26 agents → one cache entry warms them all.
+2. **Agent-specific role + tools contract + output format** — unique to the agent but stable across every invocation of that same agent. Cache hits on the per-agent tail after the first call of the session.
+3. **Dynamic content** — the orchestrator's `<required_reading>` block, per-invocation parameters, concrete task description. Different every call; never caches, but also never invalidates the earlier layers.
+
+**Do not reorder these layers.** Splicing dynamic content (e.g., a `<context>` block) before the stable role description breaks the cache for everything after that splice. Inlining the preamble into the agent body (instead of importing) costs every spawn full-input rates on the preamble bytes.
+
+See `reference/shared-preamble.md` (the imported file) and `reference/model-tiers.md` (tier assignment + override precedence) for the two paired references.
+
+**Cross-references.**
+- `reference/shared-preamble.md` — the preamble file itself (Plan 10.1-03).
+- `reference/model-tiers.md` — tier-selection guide + per-agent map (Plan 10.1-03).
+- `skills/warm-cache/SKILL.md` — the command that primes Layer A cache across the roster (Plan 10.1-02).
+- `skills/cache-manager/SKILL.md` — Layer B (explicit manifest) cache; independent of this ordering rule (Plan 10.1-02).
+- `.planning/phases/10.1-optimization-layer-cost-governance/10.1-CONTEXT.md` §D-08, §D-16, §D-17 — decision lineage.
+
+---
+
+*Cross-reference: [Claude Code Task tool documentation](https://docs.anthropic.com/en/docs/claude-code/sub-agents) for deeper detail on agent invocation, tool permissions, and model selection. This README is the authoring contract — the documentation covers the runtime.*

package/agents/a11y-mapper.md

@@ -0,0 +1,118 @@
+---
+name: a11y-mapper
+description: "Maps static accessibility signals — ARIA usage, keyboard nav, focus states, skip links, semantic markup — to .design/map/a11y.md. Static-only; no live browser audit."
+tools: Read, Write, Bash, Grep, Glob
+color: cyan
+model: inherit
+default-tier: sonnet
+tier-rationale: "Open-ended a11y pattern recognition across many files; Sonnet's breadth matters"
+parallel-safe: auto
+typical-duration-seconds: 45
+reads-only: false
+writes:
+  - ".design/map/a11y.md"
+---
+
+@reference/shared-preamble.md
+
+# a11y-mapper
+
+## Role
+
+You produce a static accessibility inventory. You do NOT run a browser audit — that is Phase 8 work. You never modify source code and do not spawn agents.
+
+## Required Reading
+
+- `.design/STATE.md`
+- `reference/accessibility.md` (if present)
+- Any files supplied by the orchestrator
+
+## Scan Strategy
+
+### ARIA usage
+
+```bash
+grep -rEn "aria-[a-z]+=" src/ --include="*.tsx" --include="*.jsx" --include="*.vue" --include="*.svelte" --include="*.html" | head -200
+grep -rEn "role=\"[a-z]+\"" src/ | head -100
+```
+
+### Keyboard navigation
+
+```bash
+grep -rEn "(tabIndex|onKeyDown|onKeyPress|onKeyUp)" src/ --include="*.tsx" --include="*.jsx" | head -100
+```
+
+### Focus states
+
+```bash
+grep -rEn "(:focus-visible|:focus|outline\s*:|ring-)" src/ --include="*.css" --include="*.tsx" | head -100
+```
+
+Flag `outline: none` / `outline: 0` without a visible replacement.
+
+### Semantic markup
+
+```bash
+grep -rEn "<(header|nav|main|section|article|aside|footer)\b" src/ --include="*.tsx" --include="*.jsx" | head -100
+```
+
+### Skip links
+
+```bash
+grep -rEn "(skip-nav|skip-to-content|#main-content)" src/ | head -20
+```
+
+### Image alt coverage
+
+```bash
+grep -rEn "<img\b[^>]*>" src/ | head -100
+```
+
+Count how many include `alt=`.
+
+## Output Format — `.design/map/a11y.md`
+
+```markdown
+---
+generated: [ISO 8601]
+scope: static-only
+---
+
+# Accessibility Map (Static)
+
+## ARIA usage
+| Attribute | Occurrences | Notes |
+|-----------|-------------|-------|
+
+## Keyboard support
+- tabIndex uses: [N]
+- onKey* handlers: [N]
+- Missing handlers on interactive non-buttons: [list]
+
+## Focus states
+| File | Issue |
+|------|-------|
+
+## Semantic landmarks
+| Tag | Count |
+|-----|-------|
+
+## Skip links: [present | missing]
+## Image alt coverage: [N/M = PCT%]
+
+## WCAG criterion mapping
+- 1.1.1 Non-text Content — [status]
+- 2.1.1 Keyboard — [status]
+- 2.4.1 Bypass Blocks — [status]
+- 2.4.7 Focus Visible — [status]
+- 4.1.2 Name, Role, Value — [status]
+
+## Scope note
+Static scan only. Runtime contrast, focus-trap, and screen-reader behavior require a live audit (Phase 8).
+```
+
+## Constraints
+
+No modifications outside `.design/map/`. No live browser. No git. No agent spawning.
+
+## A11Y MAP COMPLETE

package/agents/component-taxonomy-mapper.md

@@ -0,0 +1,88 @@
+---
+name: component-taxonomy-mapper
+description: "Maps the component inventory — React/Vue/Svelte components, design patterns, reuse opportunities — to .design/map/components.md."
+tools: Read, Write, Bash, Grep, Glob
+color: cyan
+model: inherit
+default-tier: sonnet
+tier-rationale: "Classifies components by role; requires nuance Haiku lacks, not enough to warrant Opus"
+parallel-safe: auto
+typical-duration-seconds: 45
+reads-only: false
+writes:
+  - ".design/map/components.md"
+---
+
+@reference/shared-preamble.md
+
+# component-taxonomy-mapper
+
+## Role
+
+You inventory the component taxonomy of the codebase. Zero session memory. You do not modify source code or spawn other agents.
+
+## Required Reading
+
+- `.design/STATE.md`
+- Any files supplied by the orchestrator
+
+## Scan Strategy
+
+### Find components
+
+```bash
+Glob: **/*.{tsx,jsx,vue,svelte}
+```
+
+Exclude `node_modules`, `dist`, `.next`, `build`.
+
+### Classify each component
+
+For each file:
+- Count props (via `interface Props`, `type Props`, `defineProps`, `export let`)
+- Count imports (complexity proxy)
+- Count exports (default + named)
+- Detect styling approach (CSS Modules, Tailwind, styled-components, inline)
+
+### Pattern classification (atomic design)
+
+- **Atom** — 0 child components, single responsibility (Button, Input, Icon)
+- **Molecule** — 2-5 child components (FormField, Card, SearchBar)
+- **Organism** — 6+ children or routable (Header, Sidebar, ProductList)
+
+### Reuse opportunities
+
+Grep for near-duplicate component names and file-size clusters. Flag components with 3+ near-identical siblings.
+
+## Output Format — `.design/map/components.md`
+
+```markdown
+---
+generated: [ISO 8601]
+total_components: [N]
+dominant_styling: [CSS Modules | Tailwind | styled-components | mixed]
+---
+
+# Component Map
+
+## Inventory
+| Component | Path | Type (atom/molecule/organism) | Props | Styling |
+|-----------|------|-------------------------------|-------|---------|
+
+## Dominant patterns
+- [e.g., "Card + Card.Header + Card.Body compound pattern used in 12 places"]
+
+## Reuse opportunities
+- [Near-duplicate components that could be unified]
+- [Missing abstractions — repeated inline patterns without a component]
+
+## Complexity outliers
+| Component | Reason |
+|-----------|--------|
+```
+
+## Constraints
+
+Do not modify anything outside `.design/map/`. No git. No agent spawning.
+
+## COMPONENT MAP COMPLETE