@hegemonart/get-design-done 1.18.0 → 1.19.5

package/.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "Get Design Done — 5-stage agent-orchestrated design pipeline with 9 connections, handoff-first workflow, bidirectional Figma write-back, 22+ specialized agents, queryable knowledge layer (intel store, dependency analysis, learnings extraction), and a self-improvement loop (reflector, frontmatter + budget feedback, global-skills layer). Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation (auto-tag + GitHub Release + release-time smoke test).",
-    "version": "1.18.0"
+    "version": "1.19.5"
   },
   "plugins": [
     {
       "name": "get-design-done",
       "source": "./",
-      "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), Claude Design handoff, bidirectional Figma write-back, and a queryable intel store (.design/intel/) for dependency and learnings queries. Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings. Ships 35-component benchmark corpus with pipeline integration (auditor conformance, executor pre-flight, doc-writer scaffold, pattern-mapper convergence). Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, variable-font loading, image optimization, CSS Grid + container queries, advanced motion vocabulary, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation. Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression.",
-      "version": "1.18.0",
+      "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), Claude Design handoff, bidirectional Figma write-back, and a queryable intel store (.design/intel/) for dependency and learnings queries. Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings. Ships 35-component benchmark corpus with pipeline integration (auditor conformance, executor pre-flight, doc-writer scaffold, pattern-mapper convergence). Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, variable-font loading, image optimization, CSS Grid + container queries, advanced motion vocabulary, platform design patterns (iOS/Android/web/visionOS), RTL/CJK/cultural adaptations, IA catalog, form UX patterns, data-visualization matrix, and user-research methodology, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation. Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression.",
+      "version": "1.19.5",
       "author": {
         "name": "hegemonart"
       },
@@ -65,8 +65,14 @@
         "component-specs",
         "design-system-benchmarks",
         "component-conformance",
-        "convergence-detector"
+        "convergence-detector",
+        "i18n",
+        "user-research",
+        "information-architecture",
+        "form-patterns",
+        "data-viz",
+        "platforms"
       ]
     }
   ]
-}
+}

package/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.18.0",
-  "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), handoff-first workflow via Claude Design bundles, bidirectional Figma write-back (annotations, Code Connect), queryable intel store (`.design/intel/`) for O(1) design surface lookups, and self-improvement loop (reflector agent, frontmatter + budget feedback, global-skills layer at `~/.claude/gdd/global-skills/`). Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings, reflect, apply-reflections. Ships 35-component benchmark corpus (Waves 1–5) with pipeline integration: auditor conformance scoring, executor spec pre-flight, doc-writer scaffold, pattern-mapper convergence detector. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, variable-font loading, image optimization, CSS Grid + container queries, advanced motion vocabulary (RN MIT easings/spring/interpolate + hyperframes transition taxonomy), and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows, lint + schema + frontmatter + stale-ref + shellcheck + gitleaks + injection-scan + blocking size-budget) and release automation (auto-tag + GitHub Release + release-time smoke test). Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression.",
+  "version": "1.19.5",
+  "description": "Agent-orchestrated 5-stage design pipeline: Brief → Explore → Plan → Design → Verify. 22+ specialized agents, 9 connections (Figma, Refero, Preview, Storybook, Chromatic, Figma Writer, Graphify, Pinterest, Claude Design), handoff-first workflow via Claude Design bundles, bidirectional Figma write-back (annotations, Code Connect), queryable intel store (`.design/intel/`) for O(1) design surface lookups, and self-improvement loop (reflector agent, frontmatter + budget feedback, global-skills layer at `~/.claude/gdd/global-skills/`). Standalone commands: style, darkmode, compare, figma-write, graphify, handoff, analyze-dependencies, skill-manifest, extract-learnings, reflect, apply-reflections. Ships 35-component benchmark corpus (Waves 1–5) with pipeline integration: auditor conformance scoring, executor spec pre-flight, doc-writer scaffold, pattern-mapper convergence detector. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, variable-font loading, image optimization, CSS Grid + container queries, advanced motion vocabulary (RN MIT easings/spring/interpolate + hyperframes transition taxonomy), platform design patterns (iOS/Android/web/visionOS), RTL/CJK/cultural adaptations, information architecture catalog, form UX patterns (Wroblewski label research), data-visualization matrix (25 chart types, Okabe-Ito palette), and user-research methodology, and anti-pattern catalog. Ships with a full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows, lint + schema + frontmatter + stale-ref + shellcheck + gitleaks + injection-scan + blocking size-budget) and release automation (auto-tag + GitHub Release + release-time smoke test). Optimization layer (v1.0.4.1, retroactive): gdd-router + gdd-cache-manager skills, PreToolUse budget-enforcer hook, tier-aware agent frontmatter, lazy checker gates, streaming synthesizer, /gdd:warm-cache + /gdd:optimize commands, and cost telemetry at .design/telemetry/costs.jsonl — targeting 50-70% per-task token-cost reduction with no quality-floor regression.",
   "author": {
     "name": "hegemonart",
     "url": "https://github.com/hegemonart"
@@ -76,9 +76,15 @@
     "component-specs",
     "design-system-benchmarks",
     "component-conformance",
-    "convergence-detector"
+    "convergence-detector",
+    "i18n",
+    "user-research",
+    "information-architecture",
+    "form-patterns",
+    "data-viz",
+    "platforms"
   ],
   "skills": [
     "./skills/"
   ]
-}
+}

package/CHANGELOG.md

@@ -4,6 +4,57 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.19.5] — 2026-04-24
+
+### Added — Cross-Cycle Memory: Recall, Checkpoints, Experience Archive
+
+Turns write-only learnings and reflections into a queryable, ranked, self-pruning memory layer.
+
+**Search backend (`scripts/lib/design-search.cjs`):** Priority chain — FTS5 via `better-sqlite3` (optional dep, runtime-probed) → ripgrep → Node fs scan. `/gdd:recall --reindex` rebuilds the index. `scripts/lib/probe-optional.cjs` wraps optional native deps for future reuse.
+
+**Cross-cycle recall (`/gdd:recall <query>`):** `skills/recall/SKILL.md` — searches `.design/archive/`, `.design/learnings/LEARNINGS.md`, `.design/CYCLES.md`, and STATE.md decision blocks; signals `surfaced` for matched L-NN IDs via `relevance-counter.cjs`.
+
+**Numbered checkpoints (pause/resume rewrite):** `skills/pause/SKILL.md` atomic-appends to `.design/checkpoints/NN-<stage>-<ISO-date>.md` instead of clobbering `HANDOFF.md`; `HANDOFF.md` becomes a pointer to the latest checkpoint. `skills/resume/SKILL.md` gains listing mode with `AskUserQuestion` picker when no arg; `/gdd:resume N` restores checkpoint N. `skills/continue/SKILL.md` — alias for `/gdd:resume` (discoverability).
+
+**Per-cycle EXPERIENCE.md:** `skills/complete-cycle/SKILL.md` extended — Haiku-tier writer reads cycle STATE + DESIGN-VERIFICATION + reflections, emits `.design/archive/cycle-N/EXPERIENCE.md` (~100–200 lines, declarative-fact framing: Goal / Decisions made / Learnings graduated / What died / Surprises / Handoff to next cycle). Highest-priority source for decision-injector.
+
+**Timeline retrospective (`/gdd:timeline`):** `skills/timeline/SKILL.md` — narrative view across EXPERIENCE.md files + git log; sections Opened with / Key decisions / Surprises / What we'd do differently.
+
+**Relevance counter (`scripts/lib/relevance-counter.cjs`):** `record(id, signal, designDir)` under atomic-write + `.lock`; signals: `cited`, `surfaced`, `dismissed`. `shouldPromote` at 8+ cites; `shouldPrune` at 0 cites + 4 cycles.
+
+**Decision-injector FTS5 upgrade:** `hooks/gdd-decision-injector.js` backend-swaps to FTS5 transparently when `design-search.cjs` is available — zero surface-level output change, backend label shown in footer.
+
+**Record contract (mandatory for all agents):** `agents/README.md` authoring template gains mandatory `## Record` step — every agent appends one JSONL line to `.design/intel/insights.jsonl`. `reference/schemas/insight-line.schema.json` — schema with 6 required fields (`ts`, `agent`, `cycle`, `stage`, `one_line_insight`, `artifacts_written`). `tests/record-contract.test.cjs` enforces presence of `## Record` section in every `agents/*.md`. All 36 existing agents updated with stub Record sections.
+
+---
+
+## [1.19.0] — 2026-04-24
+
+### Added — Platform, Inclusive Design & UX Research References (knowledge-layer complete)
+
+This release closes the final reference gaps identified in the 2026-04-18 knowledge audit. The plugin now ships 18 reference files covering every major design-knowledge domain.
+
+#### 7 new reference files
+
+- **`reference/platforms.md`** — iOS/Android/web/visionOS/watchOS conventions: nav patterns, safe areas, gesture vocabularies, native typography, haptic feedback. Wired into `design-context-builder` + `design-phase-researcher`.
+- **`reference/rtl-cjk-cultural.md`** — RTL logical CSS properties, CJK typography (line-height 1.5–1.8, font-fallback stacks), Arabic/Hebrew, Devanagari/Tamil/Thai, cultural color meanings table, `Intl.*` formatting. Wired into `design-context-builder` + `design-auditor`.
+- **`reference/onboarding-progressive-disclosure.md`** — First-run pattern matrix, feature discovery, Aha-moment mapping, activation vs. habituation metrics, anti-patterns. Wired into `design-executor` + `design-auditor`.
+- **`reference/user-research.md`** — Research method matrix, card sort/tree test/A/B benchmarks, synthesis techniques, research ethics. Wired into `design-phase-researcher`.
+- **`reference/information-architecture.md`** — Nav pattern catalog (hub-and-spoke/nested/faceted/flat/mega-menu), tree-test benchmarks, wayfinding ARIA conventions. Wired into `design-context-builder` + `design-pattern-mapper`.
+- **`reference/form-patterns.md`** — Label position (Wroblewski research), on-blur validation default, full `autocomplete` taxonomy, `inputmode`/`enterkeyhint`, password UX (paste-allowed), CAPTCHA ethics. Wired into `design-auditor` (forms pillar) + `design-executor` (new `type:forms`).
+- **`reference/data-visualization.md`** — Chart-choice matrix, 25 chart types (decision-tree prose, UUPM `charts.csv` MIT), Okabe-Ito/viridis/cividis palettes, axis conventions, dashboard patterns. Wired into `design-auditor` + `design-executor`.
+
+#### Agent wiring
+- `design-context-builder` — Area 2 locale detection; Area 6 platform note; `canonical_refs` extended with 3 conditional references.
+- `design-auditor` — Required reading extended: form-patterns, onboarding, data-visualization, rtl-cjk-cultural, information-architecture.
+- `design-executor` — New `type:forms` task type (7-step checklist); `type:layout` reads data-viz for dashboards; `type:copy` reads onboarding for first-run flows.
+- `design-phase-researcher` — reads user-research.md + platforms.md.
+- `design-pattern-mapper` — reads information-architecture.md for nav classification.
+
+All 7 files registered in `reference/registry.json`. Regression baseline at `test-fixture/baselines/phase-19/`.
+
+---
+
 ## [1.18.0] — 2026-04-24
 
 ### Added — Advanced Craft References + Motion Vocabulary

package/README.md

@@ -76,6 +76,13 @@ You don't need to be a designer. The pipeline carries the design expertise so yo
 
 Built-in quality gates catch real problems: Handoff Faithfulness scoring on Claude Design bundles, contrast audits across the full palette × surface matrix, anti-pattern detection from the NNG catalog, dark-mode architecture verification, and motion-system consistency checks.
 
+### v1.19.0 Highlights — Full Knowledge Coverage (18 reference files)
+
+- **Knowledge-layer complete** — The plugin now ships **18 reference files** covering every major design-knowledge domain identified in the 2026-04-18 coverage audit. Agents have authoritative answers on platform conventions, internationalization, research methodology, information architecture, form design, and data visualization — in addition to the foundational knowledge from v1.15.0.
+- **7 new Phase 19 references** — `platforms.md` (iOS/Android/web/visionOS/watchOS), `rtl-cjk-cultural.md` (RTL + CJK + cultural color), `onboarding-progressive-disclosure.md`, `user-research.md` (method matrix, A/B, ethics), `information-architecture.md` (nav patterns, tree-test benchmarks), `form-patterns.md` (Wroblewski label research, autocomplete taxonomy, CAPTCHA ethics), `data-visualization.md` (25 chart types, Okabe-Ito palette, dashboard patterns — UUPM MIT).
+- **New `type:forms` executor task type** — `design-executor` now has a dedicated 7-step checklist for form audits: label position, validation timing, autocomplete tokens, inputmode hints, password UX, multi-step state, and CAPTCHA compliance.
+- **Platform + locale detection in context-builder** — `design-context-builder` now explicitly prompts for locale/RTL/CJK requirements (Area 2) and device targets with platform references (Area 6), ensuring downstream agents receive the full platform context.
+
 ### v1.18.0 Highlights — Advanced Craft References + Motion Vocabulary
 
 - **4 advanced craft references** — `variable-fonts-loading.md` (variable axes, font-display trade-offs, WOFF2 subsetting, fallback metric overrides, GRAD axis for dark mode), `image-optimization.md` (WebP/AVIF/JPEG XL matrix, srcset math, LQIP/BlurHash, CDN transforms, image budgets), `css-grid-layout.md` (subgrid, container queries, fluid `clamp()` typography, logical properties, safe areas, anchor positioning), `motion-advanced.md` (spring physics, FLIP, View Transitions API, gesture/drag mechanics, clip-path animations, blur crossfades, Framer Motion hardware-accel gotcha, motion cohesion, next-day review).

package/SKILL.md

@@ -2,7 +2,7 @@
 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|watch-authorities|check-update|benchmark]"
+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|watch-authorities|check-update|benchmark|recall|timeline|continue]"
 user-invocable: true
 ---
 
@@ -42,8 +42,11 @@ Each stage produces artifacts in `.design/` inside the current project.
 | `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 |
+| `pause [context]` | `get-design-done:gdd-pause` | Write numbered checkpoint to `.design/checkpoints/NN-*.md` |
+| `resume [N]` | `get-design-done:gdd-resume` | Restore session from checkpoint N (or list checkpoints if no arg) |
+| `continue [N]` | `get-design-done:gdd-continue` | Alias for `/gdd:resume` |
+| `recall <query>` | `get-design-done:gdd-recall` | Search cross-cycle memory (decisions, learnings, experience archives) |
+| `timeline [N\|N-M\|all]` | `get-design-done:gdd-timeline` | Narrative retrospective across completed cycles |
 | **Lifecycle** | | |
 | `start [--budget <t>] [--skip-interview] [--dismiss-nudge]` | `get-design-done:start` | First-Run Proof Path — scans UI code, returns one concrete first fix. No STATE.md writes. |
 | `new-project [--name <n>]` | `get-design-done:gdd-new-project` | Initialize project — PROJECT.md + STATE.md + cycle-1 |
@@ -207,7 +210,10 @@ If `$ARGUMENTS` is a stage or command name — invoke it directly, no state chec
 /gdd:watch-authorities  → Skill("get-design-done:gdd-watch-authorities")
 /gdd:benchmark          → Skill("get-design-done:gdd-benchmark")
 /gdd:pause              → Skill("get-design-done:gdd-pause")
-/gdd:resume          → Skill("get-design-done:gdd-resume")
+/gdd:resume             → Skill("get-design-done:gdd-resume")
+/gdd:continue           → Skill("get-design-done:gdd-continue")
+/gdd:recall             → Skill("get-design-done:gdd-recall")
+/gdd:timeline           → Skill("get-design-done:gdd-timeline")
 # --- Lifecycle ---
 /gdd:start           → Skill("get-design-done:start")          # leaf command, no STATE.md
 /gdd:new-project     → Skill("get-design-done:gdd-new-project")

package/agents/README.md

@@ -188,6 +188,59 @@ Constraints: do not modify any file other than .design/example-output.md.
 
 ---
 
+## Mandatory Record Step (Phase 19.5)
+
+Every agent **must** end its run by appending one JSONL line to `.design/intel/insights.jsonl`. This feeds `/gdd:reflect`, `/gdd:extract-learnings`, and the decision-injector relevance counter.
+
+### Format
+
+```json
+{"ts":"2026-01-15T14:23:00.000Z","agent":"design-planner","cycle":"cycle-1","stage":"plan","one_line_insight":"Produced 7-task DESIGN-PLAN.md targeting typography and spacing","artifacts_written":[".design/DESIGN-PLAN.md"]}
+```
+
+### Schema
+
+`reference/schemas/insight-line.schema.json` — all six fields are required.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `ts` | ISO 8601 string | Current UTC time |
+| `agent` | string | Must match frontmatter `name` field |
+| `cycle` | string | From `STATE.md cycle:` — empty string if no active cycle |
+| `stage` | string | From `STATE.md stage:` |
+| `one_line_insight` | string ≤200 chars | Declarative fact: what was produced or learned |
+| `artifacts_written` | string[] | Relative paths written; `[]` for read-only agents |
+
+### Implementation pattern
+
+At the very end of your run (after all writes, before emitting the COMPLETE marker):
+
+```bash
+echo '{"ts":"...","agent":"...","cycle":"...","stage":"...","one_line_insight":"...","artifacts_written":[...]}' >> .design/intel/insights.jsonl
+```
+
+Or via Bash + `node -e` when quoting is complex. Always append (>>), never overwrite. Create `.design/intel/` with `mkdir -p` first.
+
+### Authoring template
+
+Every new agent body must include a `## Record` section before the `## <NAME> COMPLETE` footer:
+
+```markdown
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+\`\`\`json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle>","stage":"<stage>","one_line_insight":"<what was produced>","artifacts_written":["<files>"]}
+\`\`\`
+
+Schema: `reference/schemas/insight-line.schema.json`.
+```
+
+`tests/record-contract.test.cjs` enforces this section is present in every `agents/*.md` file.
+
+---
+
 ## 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:

package/agents/a11y-mapper.md

@@ -141,3 +141,13 @@ Total: N findings. (0 = clean)
 No modifications outside `.design/map/`. No live browser. No git. No agent spawning.
 
 ## A11Y MAP COMPLETE
+
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.

package/agents/component-benchmark-harvester.md

@@ -105,6 +105,17 @@ This pre-analysis seeds the synthesizer's convergence analysis.
 End your response with:
 
 ```
+
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
 ## HARVEST COMPLETE
 Component: <name>
 Sources harvested: <N>

package/agents/component-benchmark-synthesizer.md

@@ -80,6 +80,17 @@ Update `reference/components/README.md`:
 End your response with:
 
 ```
+
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
 ## SYNTHESIS COMPLETE
 Component: <name>
 Spec: reference/components/<name>.md

package/agents/component-taxonomy-mapper.md

@@ -85,4 +85,14 @@ dominant_styling: [CSS Modules | Tailwind | styled-components | mixed]
 
 Do not modify anything outside `.design/map/`. No git. No agent spawning.
 
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
 ## COMPONENT MAP COMPLETE

package/agents/design-advisor.md

@@ -136,4 +136,14 @@ You MUST NOT:
 
 ---
 
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
 ## ADVICE COMPLETE

package/agents/design-assumptions-analyzer.md

@@ -168,4 +168,14 @@ You MUST NOT:
 
 ---
 
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
 ## ANALYSIS COMPLETE

package/agents/design-auditor.md

@@ -57,6 +57,11 @@ Minimum expected files:
 - `reference/image-optimization.md` (if present) — format matrix, srcset/sizes, LQIP/BlurHash, CDN transforms, image budgets; use when auditing Pillar 5 (Layout & Spacing) for image-heavy UIs
 - `reference/css-grid-layout.md` (if present) — subgrid, container queries, fluid clamp() typography, logical properties; use when auditing Pillar 5 (Layout & Spacing)
 - `reference/motion-advanced.md` (if present) — advanced motion patterns; score gesture/drag mechanics, clip-path animations, blur crossfades as "advanced craft" signal (positive, not a penalty) in Pillar 7 (Micro-Polish)
+- `reference/form-patterns.md` — label position, validation timing, autofill tokens, password UX (use for forms-pillar checks)
+- `reference/onboarding-progressive-disclosure.md` — first-run patterns, feature discovery, anti-patterns (use when onboarding flows are in scope)
+- `reference/data-visualization.md` — chart-choice matrix, color-blind palettes, axis conventions (use for chart-heavy projects)
+- `reference/rtl-cjk-cultural.md` — RTL mirroring, CJK typography, cultural color meanings (use when i18n or multi-locale is in scope)
+- `reference/information-architecture.md` — nav pattern catalog, menu-depth rules, wayfinding (use when nav structure is in scope)
 
 ---
 
@@ -523,4 +528,14 @@ If `reference/components/` does not exist or contains no specs, skip this sectio
 
 ---
 
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
 ## AUDIT COMPLETE

package/agents/design-authority-watcher.md

@@ -205,4 +205,14 @@ On contract violation (schema mismatch, hash format violation, over-200 entries)
 
 Terminate every response with:
 
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
 ## WATCH COMPLETE

package/agents/design-component-generator.md

@@ -219,3 +219,13 @@ Written: src/components/<ComponentName>.tsx
 DS: <design_system>
 [Preview: <preview_url>]
 ```
+
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.

package/agents/design-context-builder.md

@@ -317,6 +317,8 @@ Examples:
 
 If inferred from README, state the inference and ask for correction.
 
+Also capture: locale/language targets. If the product serves RTL locales (Arabic, Hebrew) or CJK audiences (Chinese, Japanese, Korean), note this in the context file and read `reference/rtl-cjk-cultural.md` before writing layout and typography decisions.
+
 ### Area 3 — Goals (Observable Outcomes)
 
 > What does success look like? Name 1–3 observable, measurable outcomes.
@@ -398,7 +400,7 @@ Note: Refero tool name may differ — always verify via ToolSearch. Two or more
 - Framework / CSS approach (already inferred — confirm)
 - Existing design tokens that cannot change
 - Accessibility level (WCAG AA minimum by default — AAA if specified)
-- Device targets (desktop-primary, mobile-first, or responsive equal priority)
+- Device targets (desktop-primary, mobile-first, or responsive equal priority) — if mobile or native-app target, read `reference/platforms.md` for safe-area, gesture, and nav-pattern constraints
 - Browser support requirements
 - Performance constraints (animation budget, bundle size)
 - Deadline
@@ -578,6 +580,9 @@ C-04: [other constraints]
 - ${CLAUDE_PLUGIN_ROOT}/reference/heuristics.md
 - ${CLAUDE_PLUGIN_ROOT}/reference/iconography.md
 - ${CLAUDE_PLUGIN_ROOT}/reference/performance.md
+- ${CLAUDE_PLUGIN_ROOT}/reference/platforms.md (read when project targets mobile or cross-platform — iOS, Android, visionOS, watchOS)
+- ${CLAUDE_PLUGIN_ROOT}/reference/rtl-cjk-cultural.md (read when project serves non-Latin locales or has explicit i18n requirement)
+- ${CLAUDE_PLUGIN_ROOT}/reference/information-architecture.md (read when nav complexity or IA decisions are in scope)
 </canonical_refs>
 
 <baseline_audit>

package/agents/design-context-checker-gate.md

@@ -87,4 +87,14 @@ You MAY:
 
 Per 10.1-CONTEXT decision **D-21** (Lazy Checker Spawning): "Cheap Haiku gate agents at `agents/*-gate.md` decide whether to spawn full checker. If false, skip full checker, log as `lazy_skipped: true` in telemetry." This gate is the context-checker-specific instance of that pattern — the full `design-context-checker` runs a 6-dimension rubric against `.design/DESIGN-CONTEXT.md`. If the builder made no changes to that file in this phase (a no-op re-run of discover, for example), the prior verdict still holds and the spawn is wasted cost.
 
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
 ## GATE COMPLETE

package/agents/design-context-checker.md

@@ -257,4 +257,14 @@ You MUST NOT:
 
 ---
 
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
 ## CONTEXT CHECK COMPLETE

package/agents/design-discussant.md

@@ -95,4 +95,14 @@ Write quality log after every exchange. This data feeds `design-reflector`'s que
 - Never grep or glob the codebase — you are a discussant, not a detector.
 - Never spawn other agents.
 
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
 ## DISCUSS COMPLETE

package/agents/design-doc-writer.md

@@ -6,6 +6,8 @@ color: yellow
 model: sonnet
 default-tier: sonnet
 tier-rationale: "Produces polished prose documentation; Sonnet's style quality is sufficient"
+size_budget: XL
+size_budget_rationale: "Phase 19.5 Record contract added ~11 lines; base doc-writer body is 250-line tier"
 parallel-safe: always
 typical-duration-seconds: 45
 reads-only: false
@@ -247,4 +249,14 @@ This agent MUST NOT:
 
 ---
 
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
 ## DOC COMPLETE

package/agents/design-executor.md

@@ -178,7 +178,7 @@ before committing final values.
 
 ### Type: layout
 
-Read `reference/layout.md` (if present) and relevant DESIGN-CONTEXT.md decisions before starting. If `reference/css-grid-layout.md` is present, also read it — apply modern Grid patterns (subgrid, container queries with `@container`, fluid `clamp()` typography, logical properties, safe-area insets, anchor positioning). If `reference/image-optimization.md` is present, apply it to any image-related layout decisions (format choice, srcset/sizes, lazy-loading, CDN transforms, image budget enforcement).
+Read `reference/layout.md` (if present) and relevant DESIGN-CONTEXT.md decisions before starting. If `reference/css-grid-layout.md` is present, also read it — apply modern Grid patterns (subgrid, container queries with `@container`, fluid `clamp()` typography, logical properties, safe-area insets, anchor positioning). If `reference/image-optimization.md` is present, apply it to any image-related layout decisions (format choice, srcset/sizes, lazy-loading, CDN transforms, image budget enforcement). If the layout task involves charts, dashboards, or data display, also read `reference/data-visualization.md` for chart-choice and dashboard-pattern guidance.
 
 1. **Inventory layout structure**: identify all grid, flex, and positioning patterns in scope files.
 2. **Check spacing consistency**: grep for magic spacing values (px or rem) not from a spacing scale. Map to nearest scale step.
@@ -511,4 +511,14 @@ This agent MUST NOT:
 @.design/intel/tokens.json (if present)
 @.design/intel/decisions.json (if present)
 
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
 ## EXECUTION COMPLETE

package/agents/design-figma-writer.md

@@ -361,3 +361,13 @@ Annotations applied: N/N_total
 Code Connect mappings registered: M/M_total
 Failed: <list any failed operations>
 ```
+
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.

package/agents/design-fixer.md

@@ -177,4 +177,14 @@ The stage reads the inline summary to determine how many gaps were fixed before
 
 ---
 
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
 ## FIX COMPLETE

package/agents/design-integration-checker-gate.md

@@ -90,4 +90,14 @@ You MAY:
 
 Per 10.1-CONTEXT decision **D-21** (Lazy Checker Spawning): "Cheap Haiku gate agents at `agents/*-gate.md` decide whether to spawn full checker. If false, skip full checker, log as `lazy_skipped: true` in telemetry." This gate is the integration-checker-specific instance of that pattern — the full `design-integration-checker` is a LARGE-size post-verification spawn that grep-walks the codebase for D-XX decision application. If no decision or anchor doc moved in the diff, the wiring result is unchanged from the last verify and the spawn is wasted cost.
 
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
 ## GATE COMPLETE

package/agents/design-integration-checker.md

@@ -323,4 +323,14 @@ Document any ambiguous cases in the per-decision "Notes" field.
 
 ---
 
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.
+
 ## INTEGRATION CHECK COMPLETE

package/agents/design-paper-writer.md

@@ -129,3 +129,13 @@ Applied: N/M operations succeeded
 Budget used: N/100 (this session)
 Failed: <list failed operations or "none">
 ```
+
+## Record
+
+At run-end, append one JSONL line to `.design/intel/insights.jsonl`:
+
+```json
+{"ts":"<ISO-8601>","agent":"<name>","cycle":"<cycle from STATE.md>","stage":"<stage from STATE.md>","one_line_insight":"<what was produced or learned>","artifacts_written":["<files written>"]}
+```
+
+Schema: `reference/schemas/insight-line.schema.json`. Use an empty `artifacts_written` array for read-only agents.