@hegemonart/get-design-done 1.0.7

package/reference/schemas/intel.schema.json

@@ -0,0 +1,191 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://get-design-done.example/schemas/intel.schema.json",
+  "title": ".design/intel/*.json",
+  "description": "Shape of intel-store slice files per reference/intel-schema.md. Each slice has a generated timestamp and one array-valued payload key matching the slice name.",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["generated"],
+  "properties": {
+    "generated": { "type": "string" },
+    "git_hash": { "type": "string" },
+    "files": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["path", "type"],
+        "properties": {
+          "path": { "type": "string" },
+          "type": {
+            "type": "string",
+            "enum": ["skill", "agent", "reference", "connection", "script", "hook", "config", "test", "other"]
+          },
+          "mtime": { "type": "string" },
+          "size_bytes": { "type": "integer", "minimum": 0 },
+          "git_hash": { "type": "string" }
+        }
+      }
+    },
+    "exports": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["file", "kind", "name"],
+        "properties": {
+          "file": { "type": "string" },
+          "kind": {
+            "type": "string",
+            "enum": ["skill", "agent", "reference", "other"]
+          },
+          "name": { "type": "string" },
+          "command": { "type": "string" }
+        }
+      }
+    },
+    "symbols": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["file", "heading"],
+        "properties": {
+          "file": { "type": "string" },
+          "heading": { "type": "string" },
+          "level": { "type": "integer", "minimum": 1, "maximum": 6 },
+          "anchor": { "type": "string" },
+          "line": { "type": "integer", "minimum": 1 }
+        }
+      }
+    },
+    "tokens": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["file", "token"],
+        "properties": {
+          "file": { "type": "string" },
+          "token": { "type": "string" },
+          "category": {
+            "type": "string",
+            "enum": ["color", "spacing", "typography", "radius", "shadow", "motion", "other"]
+          },
+          "line": { "type": "integer", "minimum": 1 },
+          "context": { "type": "string" }
+        }
+      }
+    },
+    "components": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["file", "component"],
+        "properties": {
+          "file": { "type": "string" },
+          "component": { "type": "string" },
+          "role": {
+            "type": "string",
+            "enum": ["definition", "reference", "example"]
+          },
+          "line": { "type": "integer", "minimum": 1 }
+        }
+      }
+    },
+    "patterns": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["name"],
+        "properties": {
+          "name": { "type": "string" },
+          "category": {
+            "type": "string",
+            "enum": ["color-system", "spacing-system", "typography-system", "component-styling", "layout", "interaction", "other"]
+          },
+          "source_file": { "type": "string" },
+          "description": { "type": "string" }
+        }
+      }
+    },
+    "dependencies": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["from", "to"],
+        "properties": {
+          "from": { "type": "string" },
+          "to": { "type": "string" },
+          "kind": {
+            "type": "string",
+            "enum": ["at-reference", "reads-from", "skill-calls-agent", "agent-calls-agent"]
+          },
+          "line": { "type": "integer", "minimum": 1 }
+        }
+      }
+    },
+    "decisions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["id", "summary"],
+        "properties": {
+          "id": { "type": "string" },
+          "summary": { "type": "string" },
+          "source_file": { "type": "string" },
+          "line": { "type": "integer", "minimum": 1 },
+          "date": { "type": "string" }
+        }
+      }
+    },
+    "debt": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["id", "summary"],
+        "properties": {
+          "id": { "type": "string" },
+          "summary": { "type": "string" },
+          "severity": {
+            "type": "string",
+            "enum": ["high", "medium", "low"]
+          },
+          "source_file": { "type": "string" },
+          "line": { "type": "integer", "minimum": 1 }
+        }
+      }
+    },
+    "nodes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["id"],
+        "properties": {
+          "id": { "type": "string" },
+          "type": { "type": "string" },
+          "name": { "type": "string" }
+        }
+      }
+    },
+    "edges": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": ["from", "to"],
+        "properties": {
+          "from": { "type": "string" },
+          "to": { "type": "string" },
+          "kind": { "type": "string" }
+        }
+      }
+    }
+  }
+}

package/reference/schemas/marketplace.schema.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://get-design-done.example/schemas/marketplace.schema.json",
+  "title": "Claude marketplace.json",
+  "description": "Shape of .claude-plugin/marketplace.json — the plugin marketplace descriptor.",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["name", "owner", "metadata", "plugins"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "minLength": 1
+    },
+    "owner": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["name"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 }
+      }
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["description", "version"],
+      "properties": {
+        "description": { "type": "string", "minLength": 1 },
+        "version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" }
+      }
+    },
+    "plugins": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "required": [
+          "name",
+          "source",
+          "description",
+          "version",
+          "author",
+          "repository",
+          "license",
+          "category",
+          "keywords"
+        ],
+        "properties": {
+          "name": { "type": "string", "minLength": 1 },
+          "source": { "type": "string", "minLength": 1 },
+          "description": { "type": "string", "minLength": 1 },
+          "version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" },
+          "author": {
+            "type": "object",
+            "additionalProperties": true,
+            "required": ["name"],
+            "properties": {
+              "name": { "type": "string", "minLength": 1 }
+            }
+          },
+          "homepage": { "type": "string" },
+          "repository": { "type": "string" },
+          "license": { "type": "string" },
+          "category": { "type": "string" },
+          "keywords": {
+            "type": "array",
+            "items": { "type": "string" }
+          }
+        }
+      }
+    }
+  }
+}

package/reference/schemas/plugin.schema.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://get-design-done.example/schemas/plugin.schema.json",
+  "title": "Claude plugin.json",
+  "description": "Shape of .claude-plugin/plugin.json — the plugin manifest consumed by Claude Code.",
+  "type": "object",
+  "additionalProperties": true,
+  "required": [
+    "name",
+    "short_name",
+    "version",
+    "description",
+    "author",
+    "repository",
+    "license",
+    "keywords",
+    "skills",
+    "hooks"
+  ],
+  "properties": {
+    "name": {
+      "type": "string",
+      "minLength": 1
+    },
+    "short_name": {
+      "type": "string",
+      "minLength": 1
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$"
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1
+    },
+    "author": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["name"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "url": { "type": "string" }
+      }
+    },
+    "homepage": { "type": "string" },
+    "repository": { "type": "string" },
+    "license": { "type": "string" },
+    "keywords": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "skills": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "hooks": { "type": "string" }
+  }
+}

package/reference/shared-preamble.md

@@ -0,0 +1,82 @@
+# GSD Agent Shared Preamble
+
+> **This file is imported via `@reference/shared-preamble.md` as the first line of every agent body in `agents/*.md`. Its placement is load-bearing for Anthropic's 5-minute prompt cache (see `reference/model-tiers.md` and phase 10.1 decision D-08 Layer A): because every agent opens with the identical preamble prefix, the second and subsequent agent spawns in a session pay `cached_input_per_1m` rates rather than full `input_per_1m` rates for these bytes. Do not inline this content into agent bodies — always import.**
+
+## Framework Identity
+
+You are a GSD agent operating under the `get-design-done` plugin contract (see `agents/README.md` for the full authoring contract). You are spawned by a pipeline stage (or by another agent) via the Claude Code `Task` tool with a fully self-contained prompt. You have **zero session memory** — everything you need is in the prompt string and the files listed inside its `<required_reading>` block.
+
+You are one step in a pipeline. You do not own the pipeline. The orchestrator decides what runs next based on your output.
+
+## Required Reading Discipline
+
+When the orchestrator's prompt contains a `<required_reading>` block, you MUST read every file it lists with the `Read` tool before taking any other action. Paths prefixed with `@` are file paths — pass them directly to `Read`. Skipping required reading is a hard violation: you will produce stale output that the downstream verifier catches, wasting a full spawn cycle.
+
+## Writes Protocol
+
+Only write files declared in your frontmatter `writes:` list. Agents with `reads-only: true` must never call `Write` or `Edit` on any file. If the task appears to require writing outside your declared scope, stop and return a `<blocker>` in STATE.md rather than expanding your write surface.
+
+If your agent runs in a phase that enforces atomic commits (most do), commit only files in your declared `writes:` list. Use the repo commit convention: `docs(phase-N-P): short imperative description` for documentation-class changes, `feat(phase-N-P): ...` for new capability, `fix(phase-N-P): ...` for bug fixes. Phase and plan numbers come from `.design/STATE.md` `phase:` and the invoking plan's frontmatter.
+
+## Deviation Handling
+
+If an expected file is missing, a required reading entry fails to load, or the prompt references an artifact that contradicts STATE.md, **stop** before taking any destructive action. Return a structured blocker to STATE.md and terminate your response with your completion marker:
+
+```markdown
+<blocker>
+type: missing-artifact | stale-state | contract-violation
+detail: <one sentence>
+suggested-fix: <one sentence or leave blank>
+</blocker>
+
+## {STAGE} COMPLETE
+```
+
+Valid completion markers per agent class (from `agents/README.md` §Completion Markers):
+- Research agent → `## RESEARCH COMPLETE`
+- Planning agent → `## PLANNING COMPLETE`
+- Execution agent → `## EXECUTION COMPLETE`
+- Verification agent → `## VERIFICATION COMPLETE`
+- Stage-specific agents → the stage name: `## SCAN COMPLETE`, `## DISCOVER COMPLETE`, `## PLAN COMPLETE`, `## DESIGN COMPLETE`, `## VERIFY COMPLETE`.
+
+The orchestrator detects failure by reading STATE.md for a `<blocker>`, not by the absence of a marker. Always emit the marker.
+
+## Context-Exhaustion Hook Awareness
+
+A PostToolUse hook at `hooks/context-exhaustion.js` watches your tool output for the string `<context-exhaustion>` in your response. If you determine you cannot finish the task in the remaining context, emit:
+
+```xml
+<context-exhaustion>
+reason: <one-sentence cause — e.g., "required_reading totals 47KB exceeding remaining context">
+resume-hint: <one-sentence instruction for a resumption spawn>
+</context-exhaustion>
+```
+
+…before your completion marker. The hook captures this into STATE.md so the orchestrator can re-spawn you with a narrower scope. Do not guess when you're near exhaustion — only emit when a concrete obstacle (file too large to read, required diff too wide) forced the call.
+
+## Budget-Enforcer Hook Awareness (Phase 10.1)
+
+A PreToolUse hook at `hooks/budget-enforcer.js` intercepts every `Task` spawn (including the one that invoked you). The hook may:
+- **Short-circuit** your spawn with a cached result from `.design/cache-manifest.json` (transparent — you never run).
+- **Downgrade** your tier to Haiku at the 80% per-task cap soft-threshold, silently (`auto_downgrade_on_cap: true` in `.design/budget.json`, D-03).
+- **Hard-block** your spawn at the 100% per-task or per-phase cap with an actionable error (D-02).
+
+Implication for you as the agent: **do not assume a specific model tier is live.** Your output must be correct whether you run on Haiku, Sonnet, or Opus. If a task genuinely requires reasoning density beyond Haiku, the `size_budget` + `default-tier` combination should have been set at authoring time so the router routes it correctly — the remedy is a frontmatter update (a Phase 11 reflector proposal), not a mid-run assumption.
+
+## Ordering Convention (D-17)
+
+Your agent body is structured in this exact order so the cache prefix stays stable:
+
+1. **Shared preamble import** — this file, imported at the top via `@reference/shared-preamble.md`. Same bytes across every agent → caches.
+2. **Agent-specific role, tools contract, and output format** — unique to you, the "role" section the orchestrator relies on. Stable across invocations of the same agent → caches per-agent after the first call.
+3. **Dynamic task-specific content** — the `<required_reading>` block, per-invocation inputs, the concrete task description. Different every call → never caches.
+
+Do not reorder. Do not inline this preamble. Do not splice dynamic content ahead of your stable role description. Every deviation costs the cache.
+
+## Pre-Warming
+
+The `/gdd:warm-cache` command (ships in Plan 10.1-02) pre-warms this identical prefix in the Anthropic cache before a design sprint, so the first real agent spawn of the sprint is already a cache hit on the shared-preamble bytes. You do not need to do anything special to participate — just keep the import directive at the top of your body.
+
+---
+
+*Imported by: every file under `agents/*.md` (except `agents/README.md`). Maintained as part of Phase 10.1 (OPT-07). Edits to this file affect every agent simultaneously — verify across the full agent suite before committing.*

package/reference/typography.md

@@ -0,0 +1,229 @@
+# Typography — Scale, Pairing, and Hierarchy
+
+---
+
+## Type Scale Systems
+
+### Modular Scale (Recommended)
+
+Choose a ratio and base size. Common ratios:
+
+| Ratio | Name | Use case |
+|---|---|---|
+| 1.067 | Minor Second | Dense UIs, data-heavy dashboards |
+| 1.125 | Major Second | Conservative, corporate |
+| 1.200 | Minor Third | Balanced — most SaaS products |
+| 1.250 | Major Third | Consumer, editorial |
+| 1.333 | Perfect Fourth | Strong hierarchy, marketing |
+| 1.414 | Augmented Fourth | Bold, magazine-style |
+| 1.500 | Perfect Fifth | Very dramatic hierarchy |
+| 1.618 | Golden Ratio | Maximum visual drama |
+
+**Standard scale (base 16px, ratio 1.25 — Major Third):**
+
+| Token | Size | Use |
+|---|---|---|
+| `text-xs` | 12px | Captions, badges, timestamps |
+| `text-sm` | 14px | Secondary labels, helper text |
+| `text-base` | 16px | Body text (minimum) |
+| `text-lg` | 18px / 20px | Lead paragraphs, emphasized body |
+| `text-xl` | 20px / 24px | Section headings (h3) |
+| `text-2xl` | 24px / 32px | Page headings (h2) |
+| `text-3xl` | 30px / 40px | Section titles (h1 secondary) |
+| `text-4xl` | 36px / 48px | Hero headings |
+| `text-5xl+` | 48px+ | Display, marketing hero |
+
+Never create a scale ad-hoc. Pick one ratio, generate the scale, use only values in the scale.
+
+---
+
+## Line Height
+
+| Context | Line height | Notes |
+|---|---|---|
+| Body text | **1.5 – 1.75** | More generous = more readable |
+| Headings | **1.1 – 1.3** | Tight heading stacks look intentional |
+| Captions / small text | **1.4** | Smaller text needs more breathing room |
+| Code blocks | **1.6 – 1.8** | Line scanning for code |
+| Display / hero | **0.9 – 1.1** | Can go very tight for dramatic effect |
+
+---
+
+## Line Length (Measure)
+
+| Context | Characters per line | Notes |
+|---|---|---|
+| Desktop body | **65 – 75 chars** | Optimal reading comfort |
+| Mobile body | **35 – 55 chars** | Narrower viewport forces shorter |
+| Hero/display | **35 – 55 chars** | Headings should never wrap awkwardly |
+| Data/tables | No limit | Tables have own structure |
+
+Enforce with `max-width`: `65ch` for body containers works with any font size.
+
+---
+
+## Font Weight Hierarchy
+
+| Role | Weight | Notes |
+|---|---|---|
+| Display headings | **700 – 900** | Bold commands attention |
+| Page headings | **600 – 700** | Strong but not display-level |
+| Section headings | **500 – 600** | Distinguish from body |
+| Body text | **400** | Regular — no emphasis weight |
+| UI labels | **500** | Slightly heavier than body |
+| Captions | **400** | Regular — size reduces emphasis |
+| Monospace code | **400 – 500** | |
+
+**Rule**: Never use `font-weight: 300` (light) on small text. It becomes illegible below 16px.
+
+---
+
+## Proven Font Pairings
+
+### For SaaS / Productivity
+- **Plus Jakarta Sans** (headers) + **Plus Jakarta Sans** (body) — single-family, geometric, modern
+- **DM Sans** (headers) + **DM Sans** (body) — clean, contemporary
+- **Outfit** + **Work Sans** — geometric, startup feel
+
+### For Consumer / Marketing
+- **Playfair Display** + **Inter** — editorial contrast (serif header, sans body)
+- **Cormorant Garamond** + **Montserrat** — luxury, refined
+- **Syne** + **Manrope** — fashion-forward, editorial
+
+### For Finance / Enterprise
+- **IBM Plex Sans** (all) — technical, neutral, reliable
+- **Lexend** + **Source Sans 3** — corporate, trustworthy, accessible
+- **Libre Bodoni** + **Public Sans** — news editorial, authority
+
+### For Developer Tools / Technical
+- **JetBrains Mono** (code) + **IBM Plex Sans** (UI) — technical, consistent
+- **Fira Code** + **Fira Sans** — same family, harmonious
+- **Geist Mono** + **Geist** (Vercel) — modern technical
+
+### For Bold / Expressive
+- **Bebas Neue** + **Source Sans 3** — display contrast, impactful
+- **Syne** + **Epilogue** — editorial, contemporary
+- **Clash Display** + **Satoshi** — startup bold, premium
+
+### For Accessibility-First
+- **Atkinson Hyperlegible** (all) — designed for low-vision readers
+- **Lexend** (all) — designed to improve reading fluency
+
+---
+
+## Typographic Anti-Patterns
+
+**Inter as the default** — Inter is excellent but requires a reason. "I used Inter" is not a typographic decision. If there's no brand reason for Inter specifically, explore the pairing list above.
+
+**Space Grotesk without purpose** — frequently used as a "quirky technical" font. Overused.
+
+**Mismatched personality** — serif heading on a developer tool, playful font on a medical platform, condensed display on body text.
+
+**Too many families** — maximum **2 font families** in a UI. More than that = chaos. (Exceptions: monospace for code is a 3rd that doesn't count.)
+
+**Light weights on small text** — `font-weight: 300` below 16px fails contrast and readability.
+
+**All caps body text** — reserved for: labels, badges, category markers, short UI labels only. Never for sentences or paragraphs.
+
+**Inconsistent tracking** — only use `letter-spacing` intentionally. Positive tracking on uppercase labels is fine. Negative tracking on small body text reduces readability. Random tracking changes across components signal lack of system.
+
+---
+
+## Letter Spacing Rules
+
+| Use case | letter-spacing |
+|---|---|
+| Body text | `0` (default) |
+| Uppercase labels / badges | `0.05em – 0.1em` |
+| Display headings | `−0.02em – 0.01em` |
+| Monospace code | `0` or slight positive |
+
+---
+
+## Hierarchy Without Size (Advanced)
+
+Strong typographic hierarchy comes from **multiple signals combined**, not just font-size:
+
+```
+SIZE + WEIGHT + COLOR + FAMILY + SPACING
+```
+
+Example of weak hierarchy: h2 = 24px regular Inter, h3 = 20px regular Inter, body = 16px regular Inter.
+Example of strong hierarchy: h2 = 32px 700 Playfair Display, h3 = 18px 600 Inter, body = 16px 400 Inter.
+
+Test: Can you tell which element is a heading just from the weight/family, without looking at size? If yes, hierarchy is working.
+
+---
+
+## Number Formatting in Data UIs
+
+- Use **tabular figures** (`font-variant-numeric: tabular-nums`) for all numbers in tables, dashboards, and metric displays. This aligns decimal points.
+- `JetBrains Mono`, `IBM Plex Mono`, `Roboto Mono` have tabular figures by default.
+- Most modern sans-serifs support it via CSS property even without a separate mono font.
+
+```css
+.metric-value,
+.table-number {
+  font-variant-numeric: tabular-nums;
+}
+```
+
+---
+
+## Brand Archetype Quick Guide
+
+Pick the archetype closest to the project brief; use the recommended pairing
+as a starting point (adjust for specific constraints).
+
+| Archetype | Character | Recommended Pairing |
+|-----------|-----------|---------------------|
+| SaaS / productivity | clear, neutral, utilitarian | Inter (UI) + Inter (body) — single family |
+| Consumer / editorial | warm, opinionated, expressive | Fraunces or GT Sectra (display) + Inter (body) |
+| Enterprise / finance | authoritative, conservative | IBM Plex Sans (UI) + IBM Plex Serif (body) |
+| Developer tools | technical, efficient | Geist (UI) + Geist Mono (code) |
+| Bold / expressive | high-energy, distinctive | Söhne or Mona Sans (display) + Inter (body) |
+
+**Selection heuristic:** If the brief uses words like "professional", "trustworthy", "clean" → SaaS or Enterprise. If "warm", "editorial", "narrative" → Consumer. If "bold", "energetic", "distinctive" → Bold. If "technical", "efficient", "fast" → Dev tools.
+
+---
+
+## Variable Fonts
+
+Variable fonts expose typographic axes that can be animated or set per-context
+via `font-variation-settings`. Prefer variable fonts over static family fallbacks
+when available — one file covers all weights and widths.
+
+### Common axes
+
+| Axis | Range | Purpose |
+|------|-------|---------|
+| wght | 100–900 | Weight (Thin → Black) |
+| wdth | 50%–150% | Width (Condensed → Extended) |
+| ital | 0 / 1 | Italic toggle (discrete in most) |
+| opsz | font-size value | Optical size (auto-applies when `font-optical-sizing: auto`) |
+
+### @font-face format
+
+```css
+@font-face {
+  font-family: 'InterVariable';
+  src: url('/fonts/InterVariable.woff2') format('woff2-variations');
+  font-weight: 100 900;
+  font-style: normal;
+}
+```
+
+### Usage via font-variation-settings
+
+```css
+.heading { font-variation-settings: "wght" 700, "opsz" 32; }
+.body    { font-variation-settings: "wght" 400; }
+```
+
+### Fallback strategy
+
+Always include a non-variable fallback of the same family in the font stack:
+
+```css
+font-family: 'InterVariable', 'Inter', -apple-system, system-ui, sans-serif;
+```