@hegemonart/get-design-done 1.19.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.19.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, 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.0",
+      "version": "1.19.5",
       "author": {
         "name": "hegemonart"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.19.0",
+  "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",

package/CHANGELOG.md

@@ -4,6 +4,30 @@ 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)

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

@@ -528,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-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

@@ -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.

package/agents/design-pattern-mapper.md

@@ -267,4 +267,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.
+
 ## MAPPING COMPLETE

package/agents/design-pencil-writer.md

@@ -97,3 +97,13 @@ Mode: <mode>
 Applied: N/M operations (N committed, M failed)
 Failed: <list 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.

package/agents/design-phase-researcher.md

@@ -226,4 +226,14 @@ flowchart TD
 @.design/intel/dependencies.json (if present)
 @.design/intel/graph.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.
+
 ## RESEARCH COMPLETE

package/agents/design-plan-checker.md

@@ -161,4 +161,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.
+
 ## PLAN CHECK COMPLETE

package/agents/design-planner.md

@@ -349,4 +349,14 @@ You MUST NOT:
 @.design/intel/dependencies.json (if present)
 @.design/intel/graph.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.
+
 ## PLANNING COMPLETE

package/agents/design-reflector.md

@@ -172,4 +172,14 @@ Aggregate per agent across cycles:
 - Proposals are additive — propose additions, not deletions of existing content, unless the evidence is clear (e.g., wrong frontmatter value).
 - Maximum 20 proposals per reflection file. If more are warranted, batch the lowest-priority ones into a single summary note at the end.
 
+## 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.
+
 ## REFLECTION COMPLETE

package/agents/design-research-synthesizer.md

@@ -163,4 +163,14 @@ Read .design/STATE.md
 
 Single file: `.design/DESIGN-CONTEXT.md`.
 
+## 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.
+
 ## SYNTHESIZE COMPLETE

package/agents/design-start-writer.md

@@ -219,3 +219,13 @@ The JSON block at the bottom is the contract future `/gdd:fast` / `/gdd:do` invo
 - Do not omit any of the seven H2 sections — even empty, they must exist for downstream regression fixtures.
 
 ## START-WRITER 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/design-update-checker.md

@@ -115,3 +115,13 @@ Last line of your response MUST be:
 ```
 
 The spawning skill greps for this marker to confirm you finished successfully. Emit it even on the "no cache" fallback path.
+
+## 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.