@hegemonart/get-design-done 1.0.7

package/reference/motion.md

@@ -0,0 +1,285 @@
+# Motion & Animation Framework
+
+Based on Emil Kowalski's design engineering philosophy. Apply these rules in order — do not skip to "how should this animate" before answering "should this animate."
+
+---
+
+## Decision Framework (Run In Order)
+
+### Question 1: Should This Animate At All?
+
+| Action frequency | Decision |
+|---|---|
+| 100+/day — keyboard shortcuts, command palette, list navigation | **No animation. Ever.** |
+| Tens/day — hover states, toggles, tab switching | Remove or keep to <80ms. No delay. |
+| Occasional — modals opening, drawers, toasts | Standard animation (150–300ms) |
+| Rare — onboarding, celebrations, first-time flows | Can add personality and delight |
+| Once — loading splash, page transitions | Full animation budget |
+
+**Critical rule**: Never animate keyboard-initiated actions. They repeat hundreds of times daily. Every ms of animation is felt.
+
+### Question 2: What Is The Purpose?
+
+Valid animation purposes only. If it doesn't serve one of these, remove it.
+
+| Purpose | Example |
+|---|---|
+| **Spatial consistency** | Toast enters/exits same edge each time |
+| **State indication** | Button morphs to show loading → success |
+| **Cause-effect explanation** | Item deletion — item flies to trash |
+| **Feedback** | Button scales 0.97 on press |
+| **Prevent jarring changes** | Content appearing/disappearing needs transition |
+
+Invalid purposes: "It looks cool", "It feels modern", "Other apps do it."
+
+### Question 3: What Easing?
+
+| Element state | Easing | Rationale |
+|---|---|---|
+| **Entering** | `ease-out` (fast start, slow end) | Feels responsive — starts immediately |
+| **Exiting** | `ease-in` (slow start, fast end) | Gets out of the way — doesn't linger |
+| **State transition** (same element) | `ease-in-out` | Natural — neither abrupt start nor end |
+| **Interactive/draggable** | Spring physics | Follows finger/cursor naturally |
+| **Bounce/elastic** | **Never** | Feels toy-like and dated |
+
+CSS:
+```css
+/* Enter */
+transition: transform 200ms cubic-bezier(0, 0, 0.2, 1); /* ease-out */
+
+/* Exit */
+transition: transform 150ms cubic-bezier(0.4, 0, 1, 1); /* ease-in */
+
+/* Transition */
+transition: all 200ms cubic-bezier(0.4, 0, 0.2, 1); /* ease-in-out */
+```
+
+### Question 4: What Duration?
+
+| Animation type | Duration | Notes |
+|---|---|---|
+| Micro-interactions | 80–150ms | Hover, press, toggle |
+| Component enter/exit | 150–250ms | Modals, drawers, dropdowns |
+| Page transitions | 200–350ms | Route changes |
+| Complex/orchestrated | ≤400ms | Multi-step, staggered reveals |
+| **Never exceed** | 400ms | Anything longer feels broken |
+
+**Exit faster than enter**: Exit animations should run at **60–70%** of the enter duration. Exiting elements should get out of the way fast.
+
+```
+Enter: 250ms
+Exit: 150ms (60% of 250)
+```
+
+### Question 5: Only Animate `transform` and `opacity`
+
+**Only these properties animate on the GPU:**
+```css
+/* SAFE */
+transform: translateX(), translateY(), scale(), rotate()
+opacity: 0 → 1
+
+/* DANGEROUS — triggers layout/paint */
+width, height, top, left, margin, padding, font-size
+```
+
+Exception: `filter` (blur) is GPU-accelerated in modern browsers but battery-expensive on mobile.
+
+---
+
+## Stagger Rules
+
+When animating a list of items entering:
+- Stagger delay: **30–50ms** per item
+- Maximum stagger depth: **6–8 items** (items beyond that appear simultaneously)
+- Direction: top-to-bottom OR left-to-right — never random
+
+```css
+.item:nth-child(1) { animation-delay: 0ms; }
+.item:nth-child(2) { animation-delay: 40ms; }
+.item:nth-child(3) { animation-delay: 80ms; }
+/* etc. — cap at ~6 staggered items */
+```
+
+---
+
+## Press Feedback
+
+Every clickable element must give visual feedback within **100ms** of interaction.
+
+```css
+button:active {
+  transform: scale(0.97); /* NOT 0.90 — too dramatic */
+  transition: transform 80ms ease-out;
+}
+
+/* On release */
+button:not(:active) {
+  transform: scale(1);
+  transition: transform 150ms ease-out;
+}
+```
+
+Scale range: **0.95–0.98** for buttons. **0.97** is the safest default.
+Never scale below 0.90 — it looks broken.
+
+---
+
+## `prefers-reduced-motion`
+
+Always respect this. It's not optional.
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+```
+
+Or in JavaScript:
+```js
+const prefersReduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+if (!prefersReduced) {
+  // Run animation
+}
+```
+
+---
+
+## What Never To Animate
+
+- Keyboard shortcuts and commands (too frequent)
+- Tab switching within a page
+- Filter/sort toggles on data tables
+- Expanding/collapsing sidebar navigation items during heavy use
+- Any interaction the user will perform 50+ times in a session
+
+---
+
+## The Invisible Detail Rule
+
+The best animations are ones users cannot describe but notice when absent. Signs of this:
+- The interaction feels "snappy" or "responsive" without thinking about why
+- Removing the animation makes the UI feel broken
+- Users say "it feels premium" but can't point to any specific feature
+
+This is the goal. Not "look at this animation" — "why does this feel so good to use?"
+
+---
+
+## Quick Animation Audit Checklist
+
+- [ ] No animation on keyboard-triggered actions
+- [ ] All durations ≤ 400ms
+- [ ] Exit < enter duration
+- [ ] Only `transform` and `opacity` for performance
+- [ ] `prefers-reduced-motion` implemented
+- [ ] Stagger ≤ 50ms per item, capped at 6–8 items
+- [ ] Press feedback on all interactive elements
+- [ ] No bounce/elastic easing anywhere
+- [ ] All animations have a defined purpose
+
+---
+
+## Spring Physics
+
+Spring-based animation replaces duration-based tweening with physics parameters
+(stiffness, damping, mass). Output feels more organic and adapts to interruption.
+
+### React Spring
+
+```jsx
+import { useSpring, animated } from '@react-spring/web';
+
+const styles = useSpring({
+  from: { opacity: 0, transform: 'translateY(20px)' },
+  to:   { opacity: 1, transform: 'translateY(0px)' },
+  config: { tension: 170, friction: 26 }  // default preset
+});
+```
+
+React Spring presets:
+
+| Preset | tension | friction | Character |
+|--------|---------|----------|-----------|
+| default | 170 | 26 | balanced |
+| gentle | 120 | 14 | smooth, leisurely |
+| wobbly | 180 | 12 | playful bounce |
+| stiff | 210 | 20 | snappy |
+| slow | 280 | 60 | slow and deliberate |
+| molasses | 280 | 120 | very slow, no bounce |
+
+### Framer Motion
+
+```jsx
+<motion.div
+  animate={{ x: 100 }}
+  transition={{ type: "spring", stiffness: 100, damping: 15, mass: 1 }}
+/>
+```
+
+Parameter guidance:
+
+| Param | Range | Effect |
+|-------|-------|--------|
+| stiffness | 50–300 | higher = snappier arrival |
+| damping | 10–40 | higher = less oscillation |
+| mass | 0.5–2 | higher = more inertia, slower response |
+
+Rule of thumb: for UI micro-interactions use stiffness 150–250, damping 20–30, mass 1.
+
+---
+
+## Scroll-Triggered Animations
+
+Use IntersectionObserver for scroll-reveal effects — it replaces scroll-event
+listeners with a throttled browser-native API.
+
+### Basic pattern
+
+```js
+const observer = new IntersectionObserver((entries) => {
+  entries.forEach(entry => {
+    if (entry.isIntersecting) {
+      entry.target.classList.add('in-view');
+      // Optional: disconnect after first trigger
+      // observer.unobserve(entry.target);
+    }
+  });
+}, {
+  threshold: 0.1,
+  rootMargin: '0px 0px -100px 0px'  // trigger 100px before entering viewport bottom
+});
+
+document.querySelectorAll('.reveal').forEach(el => observer.observe(el));
+```
+
+### Threshold guidance
+
+| threshold | Meaning |
+|-----------|---------|
+| 0.0 | element enters viewport edge |
+| 0.1–0.25 | element partially visible (most common for reveals) |
+| 0.5 | element half-visible |
+| 1.0 | element fully visible |
+
+### Once vs repeat
+
+- **Once** — call `observer.unobserve(entry.target)` after first intersection.
+  Use for: hero reveals, one-shot entrance animations, stat counters.
+- **Repeat** — leave observer active. Use for: progress indicators, parallax effects,
+  sticky nav state changes.
+
+### Performance rules
+
+1. Animate only `transform` and `opacity` (GPU-accelerated). Avoid `top`, `left`, `width`, `height`.
+2. No debounce/throttle needed — IntersectionObserver is already throttled by the browser.
+3. For many elements, share a single observer instance and call `observe()` once per element.
+4. Prefer CSS transitions triggered by a class toggle over requestAnimationFrame loops.
+5. Use `will-change: transform, opacity` sparingly (only on elements that animate repeatedly).

package/reference/parallelism-rules.md

@@ -0,0 +1,108 @@
+# Parallelism Rules for get-design-done
+
+The decision engine reads these rules at every stage spawn point and writes its verdict to STATE.md `<parallelism_decision>`. Parallelism is computed, not hardcoded.
+
+---
+
+## Hard Rules — Always Serial (override everything)
+
+1. **Sequential dependency** — Agent B requires output from Agent A → serial.
+2. **Shared write conflict** — Two agents write to the same file path (intersecting `writes:` fields) → serial.
+3. **Interactive agent** — Agent requires `AskUserQuestion` during execution → serial. Interactive agents cannot be parallelized.
+4. **Single task** — Only 1 candidate in the wave → serial (nothing to parallelize).
+5. **Overlapping Touches** — Two tasks have overlapping `Touches:` fields (same file paths) → serial.
+6. **Schema migrations** — Any agent altering database schema (migrations, `ALTER TABLE`, index changes) → serial within its wave.
+7. **Rate-limited external API** — Agents calling an external API with shared rate limits (same auth token, same quota) → serial.
+
+## Soft Rules — Prefer Serial (yield to config overrides)
+
+8. **Below savings threshold** — `sum(typical-duration-seconds) - max(typical-duration-seconds) < config.min_estimated_savings_seconds` (default 30s) → prefer serial.
+9. **All candidates fast** — Every candidate has `typical-duration-seconds < 10` → parallel overhead may exceed savings → prefer serial.
+10. **Beyond max_parallel_agents cap** — N candidates > `config.max_parallel_agents` → split into sequential waves of `max_parallel_agents` each.
+11. **Worktree isolation unavailable** — `worktree_isolation: true` in config but git worktrees not available → fall back to serial.
+12. **Below min_tasks_to_parallelize** — Fewer than `config.min_tasks_to_parallelize` (default 2) eligible → serial.
+13. **Large context** — Any candidate's `<required_reading>` total is >100K tokens — risk of context bloat in concurrent dispatch → prefer serial.
+14. **Token-costly agents** — Agents tagged `model: opus` with `typical-duration-seconds > 120s` — prefer serial to avoid bursty spend unless explicitly opted in.
+
+---
+
+## Decision Algorithm
+
+```
+FOR each spawn point in a stage orchestrator:
+  candidates = tasks_in_current_wave
+
+  # Hard checks (short-circuit to serial)
+  IF len(candidates) < 2                                         → serial (rule 4)
+  IF any candidate is interactive                                → serial (rule 3)
+  FOR each pair (A, B) in candidates:
+    IF A.writes ∩ B.writes ≠ ∅                                  → serial (rule 2)
+    IF A.Touches ∩ B.Touches ≠ ∅ AND config.require_disjoint_touches
+                                                                 → serial (rule 5)
+    IF A.depends_on(B) OR B.depends_on(A)                       → serial (rule 1)
+  IF any candidate mutates schema                                → serial (rule 6)
+  IF rate_limit_sharing(candidates)                              → serial (rule 7)
+
+  # Soft checks (config-adjustable)
+  IF len(candidates) < config.min_tasks_to_parallelize           → serial (rule 12)
+  est_savings = sum(typical-duration-seconds) - max(typical-duration-seconds)
+  IF est_savings < config.min_estimated_savings_seconds          → serial (rule 8)
+  IF all(c.typical-duration-seconds < 10 for c in candidates)    → serial (rule 9)
+  IF worktree_required_but_unavailable()                          → serial (rule 11)
+  IF context_pressure(candidates) > 100K                         → serial (rule 13)
+
+  # Cap
+  IF len(candidates) > config.max_parallel_agents:
+    return split_into_waves(candidates, config.max_parallel_agents)
+
+  → verdict: parallel
+
+WRITE verdict to STATE.md <parallelism_decision>
+```
+
+---
+
+## State Output Format
+
+```xml
+<parallelism_decision>
+  stage: explore
+  verdict: parallel
+  reason: "5 mappers, all parallel-safe: auto, Touches disjoint, savings est. 165s"
+  agents: ["token-mapper", "component-taxonomy-mapper", "visual-hierarchy-mapper", "a11y-mapper", "motion-mapper"]
+  ruled_out: []
+  timestamp: 2026-04-18T05:00:00Z
+</parallelism_decision>
+```
+
+### Serial verdict example
+
+```xml
+<parallelism_decision>
+  stage: plan
+  verdict: serial
+  reason: "sequential dependency — design-planner consumes design-phase-researcher output (rule 1)"
+  agents: ["design-phase-researcher", "design-pattern-mapper", "design-planner", "design-plan-checker"]
+  ruled_out: ["parallel: rule 1"]
+  timestamp: 2026-04-18T05:10:00Z
+</parallelism_decision>
+```
+
+### Parallel verdict example
+
+```xml
+<parallelism_decision>
+  stage: verify
+  verdict: parallel
+  reason: "design-auditor + design-integration-checker — disjoint writes, both parallel-safe: auto, savings est 60s"
+  agents: ["design-auditor", "design-integration-checker"]
+  ruled_out: []
+  timestamp: 2026-04-18T05:20:00Z
+</parallelism_decision>
+```
+
+---
+
+## Why this is a first-class primitive
+
+"Why didn't it parallelize?" becomes a one-file STATE.md read — not a guess. Every stage orchestrator computes and writes a verdict before any multi-agent spawn. Operators can audit the decision without rerunning.

package/reference/priority-matrix.md

@@ -0,0 +1,31 @@
+# Priority Matrix — 10 Categories, CRITICAL → LOW
+
+Adapted from `ui-ux-pro-max`. Use this to rank findings when auditing, critiquing, or deciding fix order.
+
+| # | Category | Severity | Must-have checks | Anti-patterns (avoid) |
+|---|---|---|---|---|
+| 1 | **Accessibility** | CRITICAL | Contrast 4.5:1 body / 3:1 UI / 7:1 AAA; alt text; keyboard nav; aria-labels; visible focus rings; `prefers-reduced-motion`; no color-only meaning; sequential heading hierarchy | Removed focus rings; icon-only buttons without labels; placeholder as label; red/green only as meaning |
+| 2 | **Touch & Interaction** | CRITICAL | Min 44×44pt iOS / 48×48dp Android; 8px+ spacing between targets; loading feedback on async; error near field; visible press feedback | Hover-only interactions; instant (0ms) state changes; gesture-only critical actions; custom back overriding swipe |
+| 3 | **Performance** | HIGH | WebP/AVIF + `srcset`; lazy loading below fold; reserve space (CLS < 0.1); animate transform/opacity only; `touch-action: manipulation` | Layout thrashing; animating width/height; no reduced-motion respect; heavy blur > 20px in Safari |
+| 4 | **Style Selection** | HIGH | Committed aesthetic direction; consistency across surfaces; SVG icons only; max 2 font families; palette has dominant + accent (not rainbow) | Mixing flat + skeuomorphic; emoji as icons; 3+ font families; every element equally weighted |
+| 5 | **Layout & Responsive** | HIGH | Mobile-first min-width queries; viewport meta; safe-area insets; no horizontal scroll; container queries for components; 3 breakpoints usually enough | Fixed px widths; desktop-first max-width; disable-zoom viewport; ignoring notch / Dynamic Island |
+| 6 | **Typography & Color** | MEDIUM | Base 16px; line-height 1.5 (1.55 for light-on-dark); 65–75ch measure; OKLCH with tinted neutrals; semantic tokens, no raw hex; 5-step scale with 1.25+ ratio | Body < 12px; gray-on-gray; raw hex in components; Inter+purple+gradient default; pure gray neutrals; 8 sizes × 1.1 ratio |
+| 7 | **Animation** | MEDIUM | Duration 100–300ms UI, 300–500ms layout; ease-out for entry, ease-in for exit, exits ~75% of enter; purposeful; `prefers-reduced-motion` | Decorative-only animation; `transition: all`; `ease-in` on UI; `scale(0)` entry; bounce/elastic curves; animating keyboard-initiated actions |
+| 8 | **Forms & Feedback** | MEDIUM | Visible labels above fields; errors below with `aria-describedby`; helper text; validate on blur; progressive disclosure; single column | Placeholder-only label; errors only at top of form; overwhelming all fields upfront; validating every keystroke |
+| 9 | **Navigation Patterns** | HIGH | Predictable back; bottom nav ≤5 items; deep linking; breadcrumbs for deep IA; command palette ⌘K on web/desktop | Overloaded nav; broken back behavior; no deep links; hamburger as primary on desktop; FAB on iOS |
+| 10 | **Charts & Data** | LOW–MED | Legends; tooltips; accessible color palette; right-align numbers; tabular-nums; include axis labels | Color-only meaning; 3D effects; pie charts with > 5 slices; sparkline-as-decoration; missing units |
+
+## Severity definitions (P0–P3)
+
+- **P0 (block ship)**: Any CRITICAL failure, any legal/compliance issue, broken primary flow
+- **P1 (fix this sprint)**: HIGH severity, broken secondary flow, significant UX confusion
+- **P2 (backlog)**: MEDIUM, polish, non-blocking inconsistencies
+- **P3 (nice-to-have)**: LOW, micro-improvements, aesthetic refinements
+
+## How to use this table in audits
+
+1. Run the discover stage audit or a manual grep pass using `reference/anti-patterns.md` patterns.
+2. For each finding, assign a category (1–10) from above.
+3. Sort by severity descending.
+4. Fix P0s before shipping — never ship with one open.
+5. Map each P0/P1 to a task type in the Design stage: color findings → `color` task, typography → `typography` task, accessibility → `accessibility` task.

package/reference/project-skills-guide.md

@@ -0,0 +1,42 @@
+# Project-Local Skills Guide
+
+Project-local skills live at `./.claude/skills/` within the user's project (not the plugin install). They are auto-loaded by gdd pipeline stages (explore, plan, design) as additional design context.
+
+## Auto-loaded patterns
+
+Files matching `./.claude/skills/design-*-conventions.md` are read by:
+- `explore` — included in DESIGN-CONTEXT.md synthesis under a `<project_conventions>` section
+- `plan` — passed to design-planner as `<required_reading>`
+- `design` — passed to the executor as `<required_reading>`
+
+## File format
+
+```markdown
+# Design <Area> Conventions (Project-Local)
+
+Auto-loaded in gdd sessions.
+
+## Decision from sketch: <slug> (YYYY-MM-DD)
+**Winner**: variant-2
+**Rationale**: ...
+**Token implications**: ...
+```
+
+## Typical areas
+
+- `design-typography-conventions.md`
+- `design-color-conventions.md`
+- `design-layout-conventions.md`
+- `design-motion-conventions.md`
+- `design-component-conventions.md`
+- `design-interaction-conventions.md`
+
+## Writers
+
+- `/gdd:sketch-wrap-up` appends winner rationale to the appropriate file
+- User edits directly
+- `/gdd:spike-wrap-up` may append to the relevant file when adopted
+
+## Why this layer?
+
+Design decisions accumulate across cycles. Without a project-local layer, `explore` would re-discover the same conventions each cycle and `plan` would lack continuity. This directory persists decisions and feeds them back into the pipeline automatically.

package/reference/review-format.md

@@ -0,0 +1,107 @@
+# Review Format — The Before/After Table
+
+Adopted from `emil-design-eng` and enforced across `get-design-done`. **Every design review uses this format.** No exceptions.
+
+## The format
+
+```markdown
+| Before | After | Why |
+| --- | --- | --- |
+| `transition: all 300ms` | `transition: transform 200ms ease-out` | Specify exact properties; avoid `all` (repaint cost + unpredictable) |
+| `transform: scale(0)` | `transform: scale(0.95); opacity: 0` | Nothing in the real world appears from nothing |
+| `ease-in` on dropdown | `ease-out` with custom curve | `ease-in` feels sluggish; ease-out gives instant feedback |
+| No `:active` on button | `transform: scale(0.97)` on `:active` | Buttons must feel responsive to press |
+| `transform-origin: center` on popover | `transform-origin: var(--radix-popover-content-transform-origin)` | Popovers scale from their trigger (modals stay centered) |
+```
+
+**That's the whole format.** Three columns, one row per issue.
+
+## Why this format and not prose
+
+- **Scannable.** Reviewer can see the whole list at a glance.
+- **Actionable.** Each row is a specific, applyable change.
+- **Non-redundant.** No repeating "Before:" / "After:" labels every time.
+- **The "Why" column is required.** It forces reasoning instead of taste-asserting. Future you also forgets why; the column documents the decision.
+
+## Wrong format — never produce this
+
+```
+Before: transition: all 300ms
+After: transition: transform 200ms ease-out
+
+Before: scale(0)
+After: scale(0.95)
+```
+
+This form is verbose, hard to scan, and separates the reasoning from the change. Don't do it.
+
+Also wrong:
+- Bullet lists of "change X to Y" without the Why column
+- Narrative paragraphs explaining multiple changes at once
+- Code blocks with full file rewrites instead of focused diffs
+
+## When to use this format
+
+- **Any review of existing code or design.** `impeccable-audit`, `impeccable-critique`, `design:design-critique`, `design:accessibility-review` — all produce outputs that can be rendered as this table.
+- **Responding to "review this" / "what do you think of this."**
+- **After `Skill(impeccable-polish)` runs** — present the diff as a table.
+- **Documenting design-system migrations** (old token → new token, with why).
+
+## When NOT to use this format
+
+- **Greenfield design.** No "Before" exists — that's a design proposal, not a review.
+- **Strategic direction critiques.** ("Should we commit to dark mode?") — that's a decision, not a diff.
+- **Presentation to stakeholders.** Use `anthropic-skills:design-storytelling`'s narrative spine instead.
+
+## Variations by domain
+
+### Typography review
+```
+| Before | After | Why |
+| 3 font families (Inter + Playfair + JetBrains) | 2 (ABC Favorit + JetBrains) | More than 2 families dilutes hierarchy |
+| 8 font sizes at 1.1 ratio | 5 sizes at 1.25 ratio | Fewer sizes, more contrast = clearer hierarchy |
+```
+
+### Color review
+```
+| Before | After | Why |
+| `#888` secondary text on white | oklch(52% 0.01 [hue]) | #888 fails 4.5:1; oklch value passes |
+| Pure black dark-mode bg | oklch(14% 0.01 [brand-hue]) | Pure black is harsh; tinted darkens feels premium |
+```
+
+### Motion review
+```
+| Before | After | Why |
+| Same 300ms for open + close | 300ms open / 225ms close | Exits should be ~75% of enter duration |
+| Sheet animates height | Sheet animates transform: translateY | height animation is main-thread; transform is GPU |
+```
+
+### UX copy review
+```
+| Before | After | Why |
+| "OK" button | "Save changes" | Verbs describe the outcome; generic OK is lazy |
+| "Error: invalid email" | "Enter a valid email like name@example.com" | Tell user how to fix, not just what's wrong |
+| Empty state: "No items" | "No messages yet. Try [connecting your inbox]." | Empty state = onboarding opportunity |
+```
+
+## Scoring version (when comparing multiple artifacts)
+
+When comparing two variations (A vs B) instead of reviewing one, switch to a scored table:
+
+```
+| Dimension          | Variant A | Variant B | Winner | Why |
+| Visual hierarchy   | 6/10      | 8/10      | B      | B's size contrast more decisive |
+| Touch targets      | 7/10      | 5/10      | A      | B has 32px buttons fail 44pt |
+| Brand fit          | 9/10      | 5/10      | A      | A commits to editorial tone; B hedges |
+| Accessibility      | 7/10      | 7/10      | tie    | Both miss focus rings |
+```
+
+Use the 10 priority-matrix categories (see `priority-matrix.md`) as the dimensions by default.
+
+## Output header
+
+Always precede the table with one sentence stating the scope:
+
+> Reviewed: Settings page modal, `components/Settings.tsx`. 7 changes proposed — 2 P0 accessibility, 3 P1 motion, 2 P2 polish.
+
+Then the table. Then nothing. The reader decides whether to apply.

package/reference/schemas/config.schema.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://get-design-done.example/schemas/config.schema.json",
+  "title": ".design/config.json",
+  "description": "Shape of .design/config.json — model profile and parallelism settings per reference/config-schema.md.",
+  "type": "object",
+  "additionalProperties": true,
+  "properties": {
+    "model_profile": {
+      "type": "string",
+      "enum": ["quality", "balanced", "budget"]
+    },
+    "parallelism": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "max_parallel_agents": { "type": "integer", "minimum": 1 },
+        "min_tasks_to_parallelize": { "type": "integer", "minimum": 1 },
+        "min_estimated_savings_seconds": { "type": "integer", "minimum": 0 },
+        "require_disjoint_touches": { "type": "boolean" },
+        "worktree_isolation": { "type": "boolean" },
+        "per_stage_override": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": true,
+            "properties": {
+              "enabled": { "type": "boolean" },
+              "max_parallel_agents": { "type": "integer", "minimum": 1 },
+              "min_tasks_to_parallelize": { "type": "integer", "minimum": 1 },
+              "min_estimated_savings_seconds": { "type": "integer", "minimum": 0 },
+              "require_disjoint_touches": { "type": "boolean" },
+              "worktree_isolation": { "type": "boolean" }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/reference/schemas/hooks.schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://get-design-done.example/schemas/hooks.schema.json",
+  "title": "Claude hooks.json",
+  "description": "Shape of hooks/hooks.json — event-triggered commands registered by the plugin.",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["hooks"],
+  "properties": {
+    "hooks": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "SessionStart": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/hookGroup" }
+        },
+        "SessionEnd": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/hookGroup" }
+        },
+        "PreToolUse": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/hookGroup" }
+        },
+        "PostToolUse": {
+          "type": "array",
+          "items": { "$ref": "#/definitions/hookGroup" }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "hookGroup": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["hooks"],
+      "properties": {
+        "matcher": { "type": "string" },
+        "hooks": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["type", "command"],
+            "properties": {
+              "type": { "type": "string", "enum": ["command"] },
+              "command": { "type": "string", "minLength": 1 }
+            }
+          }
+        }
+      }
+    }
+  }
+}