@hegemonart/get-design-done 1.28.0 → 1.28.5

package/reference/shared-preamble.md

@@ -1,11 +1,29 @@
+---
+name: shared-preamble
+type: preamble
+version: 2.0.0
+phase: 28.5
+tags: [shared, preamble, principles, design-quality, agent-import, cache-prefix, extracted]
+last_updated: 2026-05-18
+---
+
 # 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.**
+> **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 `./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.**
+>
+> **As of Phase 14.5 this file is an aggregator.** The framework-invariant subsections (Required Reading Discipline, Writes Protocol, Deviation Handling, Completion Markers, Context-Exhaustion & Budget awareness) live in `./meta-rules.md` (tier L0) so the L2 heuristics/anti-patterns/checklists churn never invalidates the L0 prefix.
 >
-> **As of Phase 14.5 this file is an aggregator.** The framework-invariant subsections (Required Reading Discipline, Writes Protocol, Deviation Handling, Completion Markers, Context-Exhaustion & Budget awareness) live in `reference/meta-rules.md` (tier L0) so the L2 heuristics/anti-patterns/checklists churn never invalidates the L0 prefix.
+> **As of Phase 28.5 this file also serves the design-family skills.** Sections below the agent-preamble block (## Design Quality Pillars, ## Token-First Reasoning, ## Output Contract Reminders, ## Connection Handshake Summary) are the canonical home for principle-recitation that previously inlined across `skills/audit`, `skills/style`, `skills/darkmode`, `skills/compare`, `skills/figma-write`, `skills/connections`, `skills/benchmark`. Skills cross-link here instead of restating these lists.
 
 @reference/meta-rules.md
 
+## When to use this file
+
+Two distinct consumers, one canonical home:
+
+1. **Agents** (`agents/*.md`) import this file via `@reference/shared-preamble.md` to inherit the GSD framework identity + L0 invariants (cache-stable prefix). Agents do not "read" the design-family sections below; those are passive content the cache covers for free.
+2. **Skills** (`skills/<name>/SKILL.md`) cross-link to specific sections (`./shared-preamble.md#design-quality-pillars`, etc.) instead of restating recurring principle lists inline. This is the D-10 extract-then-link discipline from Phase 28.5: principle text lives in one place; skills point at it.
+
 ## 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.
@@ -30,12 +48,66 @@ The `/gdd:warm-cache` command (ships in Plan 10.1-02) pre-warms this identical p
 
 The framework is anchored to three design philosophy references that agents may read during brief, audit, and verify stages:
 
-- `reference/first-principles.md` — 3-invariant framework (body, attention, memory); reducibility test for every design element
-- `reference/emotional-design.md` — Norman's visceral / behavioral / reflective cross-cutting scoring lens
-- `reference/component-authoring.md` — Kowalski/Sonner 6-principle component quality standard (P-01 through P-06)
+- `./first-principles.md` — 3-invariant framework (body, attention, memory); reducibility test for every design element
+- `./emotional-design.md` — Norman's visceral / behavioral / reflective cross-cutting scoring lens
+- `./component-authoring.md` — Kowalski/Sonner 6-principle component quality standard (P-01 through P-06)
 
 These references encode *why* the heuristics and anti-patterns exist — not rules to follow, but constraints derived from human biology and cognition. Agents that read these files apply them as lenses, not checklists.
 
 ---
 
-*Imported by: every file under `agents/*.md` (except `agents/README.md`). Maintained as part of Phase 10.1 (OPT-07) and Phase 14.5 (L0/L2 split). Edits to this file affect every agent simultaneously — verify across the full agent suite before committing.*
+## Design Quality Pillars
+
+Seven pillars score every design audit (see `./audit-scoring.md` for the weighted-rubric detail; this section is the one-paragraph summary that the design-family skills cross-link). Used by `skills/audit`, `skills/style`, `skills/compare`.
+
+1. **Accessibility** — WCAG 2.1 AA threshold compliance; keyboard navigation; non-color signalling. See also `./contrast-advanced.md` (APCA / WCAG 3 perceptual layer).
+2. **Visual hierarchy** — F/Z scanning paths; primary action prominence; section pacing. See `./visual-hierarchy-layout.md`.
+3. **Typography** — type scale ratio (1.125 → 1.5), font-pair count cap (≤2), reading rhythm (`./typography.md`).
+4. **Color** — palette source-of-truth, contrast pair density, OKLCH discipline, semantic-token coverage (`./palette-catalog.md`, `./color-theory.md`).
+5. **Spacing & rhythm** — 4 px or 8 px modular scale, vertical-rhythm consistency (`./composition.md`, `./proportion-systems.md`).
+6. **Component coherence** — minimal API surface, animation as state, edge honesty (`./component-authoring.md`).
+7. **Anti-patterns** — BAN-*, SLOP-* tags from `./anti-patterns.md`; emotional design conflict patterns from `./emotional-design.md`.
+
+Score range per pillar: 0–10. Audit-overall = weighted average per `./audit-scoring.md` weights.
+
+## Token-First Reasoning
+
+Design tokens are the discipline that prevents the 60+ raw-hex `#5C5C5C` audit-failure pattern. The rule:
+
+> **Every reachable color, spacing, type-scale value must be a token reference, not a raw literal.**
+
+Three audit signals:
+
+- **Raw-hex ratio** — `grep -rEo "#[0-9a-fA-F]{6}" src/` divided by total color uses. Healthy < 5 %.
+- **Token coverage** — every semantic role (primary, surface, on-surface, etc.) has a defined token. Cross-check with `./palette-catalog.md` for naming convention.
+- **Light/dark parity** — every light-mode color token has a dark-mode override (see `skills/darkmode` audit for the contrast-pair check, and `./color-theory.md` §OKLCH for the modern hue-rotation contract).
+
+Used by: `skills/style`, `skills/darkmode`, `skills/figma-write`, `skills/audit`, `skills/compare`.
+
+## Output Contract Reminders
+
+Every design-family skill writes ONE artifact (D-06 / utility-skill discipline). Recurring constraints (cited by `skills/audit`, `skills/compare`, `skills/darkmode`, `skills/figma-write`, `skills/style`):
+
+- **MUST NOT write** to pipeline-reserved paths: `DESIGN.md`, `DESIGN-CONTEXT.md`, `DESIGN-PLAN.md`, `DESIGN-SUMMARY.md`, `DESIGN-VERIFICATION.md`, `.design/STATE.md` (unless the skill IS a pipeline stage — design-family skills are NOT).
+- **MUST write** the declared artifact name with a non-conflicting prefix (`DESIGN-STYLE-*`, `DARKMODE-AUDIT.md`, `COMPARE-REPORT.md`, etc.).
+- **MUST emit** a completion marker line (e.g., `## STYLE COMPLETE`, `## DARKMODE AUDIT COMPLETE`, `## COMPARE COMPLETE`) so the orchestrator can detect skill exit.
+- **MUST NOT invoke** the pipeline router (these are leaf skills, not pipeline stages).
+- **MUST NOT mutate** source files (audit-only — fixes belong in the design pipeline's color/typography/etc. task types).
+
+Reference paths used by completion-marker probes: see each skill's `## Completion` section for the literal artifact path.
+
+## Connection Handshake Summary
+
+The 12 external integrations (`figma`, `refero`, `preview`, `storybook`, `chromatic`, `graphify`, `pinterest`, `claude-design`, `paper-design`, `pencil-dev`, `21st-dev`, `magic-patterns`) share a probe pattern. The single-source spec lives in `connections/connections.md` (capability matrix + probe-pattern); per-connection setup lives in `connections/<name>.md`. The `skills/connections` skill orchestrates probes; the AI-native interface contract is `./ai-native-tool-interface.md`.
+
+Probe pattern (used by `skills/darkmode`, `skills/compare`, `skills/figma-write`, `skills/connections`, `skills/benchmark`):
+
+1. **ToolSearch first** — `ToolSearch({ query: "<server-name>", max_results: 5 })`. Empty result → `not_configured`. Non-empty → step 2.
+2. **Live tool call** — invoke a metadata endpoint (e.g., `preview_list`, `get_metadata`). Success → `available`. Error → `unavailable`.
+3. **Write to STATE.md `<connections>`** — three-value schema (`available | unavailable | not_configured`). Never add new values.
+
+For full per-connection probe scripts (figma, refero, preview, etc.) see the individual `connections/<name>.md` files. For the onboarding wizard flow, see `./connections-onboarding.md` (Phase 28.5 extract).
+
+---
+
+*Imported by: every file under `agents/*.md` (except `agents/README.md`). Cross-linked by: design-family skills under `skills/{audit,style,darkmode,compare,figma-write,connections,benchmark}/SKILL.md`. Maintained as part of Phase 10.1 (OPT-07), Phase 14.5 (L0/L2 split), and Phase 28.5 (Bucket 2 design-family rework — D-10). Edits to this file affect every agent simultaneously — verify across the full agent suite before committing.*

package/reference/skill-authoring-contract.md

@@ -0,0 +1,128 @@
+---
+name: skill-authoring-contract
+type: meta-rules
+version: 1.0.0
+phase: 28.5
+tags: [skill, authoring, contract, length-cap, description, frontmatter, progressive-disclosure]
+last_updated: 2026-05-18
+---
+
+Source: mattpocock/skills (MIT) — adapted with permission. See `../NOTICE` for the full attribution block.
+
+# Skill Authoring Contract
+
+This file codifies the structural discipline that every `skills/<name>/SKILL.md` in this repo
+must obey. It exists because a 2026-05-02 audit found skill lengths ranging from 23 to 731
+lines, descriptions oscillating between under-spec and over-cap, and no shared rule for when
+to extract domain content out of a SKILL.md and into a centralized reference. The contract
+pulls every skill into a predictable band so agent context stays small and first-token latency
+stays low. Validator: `node scripts/validate-skill-length.cjs --quiet --json`. See
+`./context-md-format.md` and `./adr-format.md` for the project-scoped artifact contracts that
+ship in the same phase.
+
+## Length cap
+
+Two-tier threshold, enforced by the validator (D-01):
+
+- **Warn at `≥100` lines.** Validator emits a warning. CI does NOT fail. Treat as a forcing
+  function: a 110-line skill is fine; a 180-line skill needs a hard look at what can be
+  extracted.
+- **Block at `≥250` lines.** Validator emits an error. CI FAILS. No exceptions —
+  multi-stage orchestrator skills push extraction harder, they do not waive the cap.
+
+When a skill exceeds the cap, use the extract-then-link discipline (D-10) — NEVER delete
+content. Move it. Steps:
+
+1. Identify load-bearing workflow + decision-tree content. Keep this in `SKILL.md`.
+2. Identify domain content — heuristics, framework matrices, glossaries, extended examples.
+   Extract to an existing `reference/<topic>.md` if the topic matches; create a new
+   `reference/<topic>.md` if it does not.
+3. Replace the extracted content with a single-sentence summary + cross-link.
+
+Concrete callouts at the time of writing: `skills/scan/SKILL.md` (731 lines) is the
+worst-offender and is scheduled for Bucket 1 rework in plan `28.5-04`. `skills/help/SKILL.md`
+(86 lines) is an in-band example of a well-scoped utility shortcut.
+
+## Description format
+
+Two rules:
+
+- **Length cap is STRICT.** `description ≤ 1024 chars` — no flag, no override. Under 20 chars
+  is also blocked as under-specification.
+- **Recommended form is LAX by default.** `<what>. Use when <triggers>.` — third person,
+  first sentence what the skill does, second sentence the trigger conditions. Validator
+  enforces the form regex only under `--strict-description` or `STRICT_DESCRIPTION=1`. Default
+  is length-only.
+
+Why lax-by-default (D-02): `obra/superpowers/skills/writing-skills/SKILL.md` documents a
+shortcut-effect where an agent reads the description and skips the body — the more
+load-bearing the description summary, the more often this happens. Phase 33 ships an A/B
+study at `.design/research/description-format-ab.md`; until then the regex stays advisory.
+
+Examples (both 20–1024 chars, both pass the length check):
+
+```text
+# Strict-mode-compliant
+Renders an OKLCH gamut comparison chart. Use when the user asks to see the visible difference between a target gamut and sRGB.
+
+# Lax-mode-only acceptable
+Compares OKLCH gamut coverage against sRGB and prints a visual diff chart.
+```
+
+## Frontmatter
+
+Required fields (validator blocks if absent):
+
+- `name` — kebab-case skill identifier; matches `^[a-z0-9][a-z0-9-._]*$`.
+- `description` — 20–1024 chars; see `## Description format` above.
+
+Optional fields (recognized by the Claude Code agent loader):
+
+- `argument-hint` — usage hint shown in the slash-command picker.
+- `tools` — comma-separated allowed tool list (e.g. `Read, Grep`).
+- `disable-model-invocation: true|false` — when `true`, the skill fires ONLY on explicit
+  user invocation and the router will not auto-trigger it. Allowed ONLY on the D-09
+  whitelist (pure shortcuts like `help`, `stats`, `note`, `health`, `zoom-out`). The
+  validator blocks if a non-whitelisted skill sets this field to `true`.
+- `user-invocable: true|false` — whether the slash-command picker exposes the skill.
+
+Concrete example:
+
+```yaml
+---
+name: help
+description: "Lists all available get-design-done commands with one-line descriptions. Use when the user asks for help, a command list, or wants to know what is available."
+tools: Read
+disable-model-invocation: true
+---
+```
+
+## Progressive disclosure
+
+References-one-level-deep is the rule (D-06):
+
+- **One level deep.** `SKILL.md` may cross-link into `reference/<topic>.md`. A reference may
+  cross-link into another reference. `SKILL.md` does NOT instruct the agent to follow a
+  reference's references — load the first level only.
+- **Centralized refs.** `reference/typography.md`, `reference/palette-catalog.md`,
+  `reference/audit-scoring.md` and friends are consumed by 15+ skills each. NEVER bundle
+  them per-skill. Per-skill folders are allowed ONLY for content that is truly
+  single-skill-private (rare; typically a fixture or schema only the owning skill reads).
+- **When to add `scripts/`.** Per mattpocock's three criteria, add a script only when the
+  step is deterministic, repeated across runs, and the failure mode needs explicit error
+  handling. Anything ad-hoc or once-off stays inline as agent prose.
+
+Concrete example: a skill that lists 10 framework matrices inline (~150 lines) extracts the
+matrices to `reference/<framework>-matrices.md` and replaces them with a one-sentence
+summary + cross-link. SKILL.md drops to ~80 lines, the matrices stay discoverable, no
+institutional knowledge is lost.
+
+## Validator usage
+
+```text
+node scripts/validate-skill-length.cjs --quiet --json
+```
+
+Exit codes: `0` clean, `1` warnings only, `2` blockers present. Flags: `--quiet` suppresses
+per-skill output, `--strict-description` adds the form regex check, `--json` emits
+machine-readable output. Env: `STRICT_DESCRIPTION=1` and `SKILLS_DIR=<path>` are honored.

package/reference/start-procedure.md

@@ -0,0 +1,115 @@
+---
+name: start-procedure
+type: heuristic
+version: 1.0.0
+phase: 28.5
+tags: [start, first-run, proof-path, scan, writer-agent, handoff]
+last_updated: 2026-05-18
+---
+
+# Start Skill — Full Procedure
+
+Extracted from `skills/start/SKILL.md` per Phase 28.5 D-10 (extract-then-link, never delete
+content). The skill keeps its arguments table, step headings, and non-goals; the per-step
+operational detail (interview JSON shape, scan invocation, writer spawn payload, handoff
+template) lives here so the SKILL stays under the 100-line cap.
+
+The companion file `./start-interview.md` (Phase 27 ship) holds the 5-question copy,
+defaults, and validation rules. This file documents what `/gdd:start` does WITH the answers.
+
+## Step 0 — Dismiss-only shortcut
+
+If invoked with `--dismiss-nudge`:
+
+1. `touch ~/.claude/gdd-nudge-dismissed` (Windows: equivalent). Ignore errors silently.
+2. Print exactly: `Nudge dismissed. Delete ~/.claude/gdd-nudge-dismissed to re-enable.`
+3. Exit with `## START COMPLETE` marker.
+
+Do not proceed to any other step.
+
+## Step 1 — Detect UI root
+
+Run the detector:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/lib/detect-ui-root.cjs" "$(pwd)"
+```
+
+Capture the JSON output. Branches:
+
+- `kind: "backend-only"` → print the frontend-only diagnostic below, write nothing, exit with `## START COMPLETE`. The diagnostic copy is:
+  > `/gdd:start` is for frontend codebases. This repo looks backend-only (detected `<framework>`). The plugin can still help with design references and component libraries imported by your clients — but there is no UI surface here to scan. Exiting without creating `.design/`.
+- `kind: null` (no package.json, no UI dir) → print a short "Nothing recognizable here — point me at a frontend repo and try again." and exit.
+- Any other `kind` → proceed with `detected.path` as the scan root.
+
+## Step 2 — Run the 5-question interview
+
+Read `./start-interview.md` for the exact question copy, defaults, and validation rules.
+
+If `--skip-interview`, skip this step and use the defaults documented in that file.
+
+Otherwise, ask the five questions in order using `AskUserQuestion`:
+
+1. Pain point (text, required, single-line cap 120 chars)
+2. Target area confirmation (detected path)
+3. Budget / latency preference (enum: fast / balanced / thorough)
+4. Framework + design-system confirmation (from detection)
+5. Figma / canvas workflow (enum: figma / canvas / neither / skip)
+
+Any early exit at Q1 → abort with a one-line pointer to `/gdd:scan`.
+
+Store the answers + detection result in `.design/.start-context.json`:
+
+```json
+{
+  "schema_version": "1.0",
+  "detected": { "kind": "...", "path": "...", "framework": "...", "design_system": "...", "confidence": 0.85 },
+  "interview": { "pain": "...", "target_area": "...", "budget": "balanced", "framework_confirmed": true, "design_system_confirmed": true, "figma_workflow": "skip" },
+  "generated_at": "<ISO-8601>"
+}
+```
+
+`.design/` is created here for the first time. `.design/STATE.md` is NOT written.
+
+## Step 3 — Scan findings
+
+Run the findings engine:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/lib/start-findings-engine.cjs" \
+  --root "<detected.path>" \
+  --budget "<budget>" \
+  --pain "<pain_point>"
+```
+
+Capture the JSON. The output carries at most three findings, each with stable IDs `F1`..`F3`, plus `bestFirstProofId` (may be null).
+
+Append the engine output to `.design/.start-context.json` under a `scan` key.
+
+## Step 4 — Spawn the writer
+
+Dispatch `Task` with:
+
+- `subagent_type: design-start-writer`
+- `description: "Write .design/START-REPORT.md"`
+- `prompt:` a short instruction pointing the agent at `.design/.start-context.json` and asking it to emit the report per its Output contract. Include a reminder that it must produce exactly 7 H2 sections plus the JSON block, and must not write `STATE.md`.
+
+Wait for the agent to complete. The agent writes `.design/START-REPORT.md`.
+
+## Step 5 — Print the handoff
+
+Read the final line of `.design/START-REPORT.md` to capture the suggested command.
+
+Print exactly (one line, no emoji):
+
+```
+Report written to .design/START-REPORT.md. Next: run <suggested_command> to see the first proof.
+```
+
+If `bestFirstProofId` was null, the suggested command is `/gdd:brief` (the default fallback).
+
+Emit `## START COMPLETE` and exit.
+
+## Failure handling
+
+Every error path exits with `## START COMPLETE` and a one-line pointer. Do not half-write files: if the writer agent fails, keep `.design/.start-context.json` and tell the user they can rerun. Do not delete `.design/` unless it was empty before the run.

package/reference/style-doc-procedure.md

@@ -0,0 +1,150 @@
+---
+name: style-doc-procedure
+type: meta-rules
+version: 1.0.0
+phase: 28.5
+tags: [style, handoff, component-spec, doc-writer, procedure, extracted]
+last_updated: 2026-05-18
+---
+
+Source: extracted from `skills/style/SKILL.md` (Phase 28.5 rework — D-10 extract-then-link).
+The skill's load-bearing routing + mode-detection stays in `../skills/style/SKILL.md`; this file
+holds the agent-spawn payload, source-resolution paths, and the per-section spec the
+`design-doc-writer` agent produces. See `./shared-preamble.md#output-contract-reminders` for
+the cross-skill output discipline.
+
+# Style Doc Procedure
+
+Detailed procedure for the `get-design-done:style` standalone command — companion to
+`../skills/style/SKILL.md`. Read this file when executing the agent-spawn step (Step 4 in the
+skill) or when wiring the source-resolution fallback chain. The SKILL.md keeps the load-bearing
+mode detection + decision tree; this file holds the deep methodology.
+
+---
+
+## Mode Detection
+
+```
+If .design/DESIGN-SUMMARY.md exists:
+  mode = post-pipeline   (STYL-03)
+  pipeline_complete = true
+
+Elif .design/DESIGN.md exists:
+  mode = pre-pipeline    (STYL-04)
+  pipeline_complete = false
+
+Else:
+  Abort: "No .design/ artifacts found. Run /get-design-done scan first to initialize."
+```
+
+The mode controls which files are supplied to the agent in `<required_reading>`.
+
+---
+
+## Component Source Resolution
+
+Search for a source file matching the provided ComponentName (case-insensitive):
+
+1. `src/components/[ComponentName].tsx`
+2. `src/components/[ComponentName].jsx`
+3. `src/components/[ComponentName].vue`
+4. `src/components/[ComponentName].svelte`
+5. `src/**/[ComponentName]/index.tsx`
+6. `src/**/[ComponentName]/index.jsx`
+7. `components/[ComponentName].tsx`
+8. `components/[ComponentName].jsx`
+9. `components/[ComponentName].vue`
+10. `components/[ComponentName].svelte`
+
+**If multiple matches found:** Present the list to the user and prompt them to specify the exact path. Do not proceed until a single file is selected.
+
+**If zero matches found:** Abort with: "Component [ComponentName] not found in expected paths. Verify the name matches a file in src/components/ or components/."
+
+When `$ARGUMENTS` is empty, the skill enters **list mode** — glob the same source roots, also list task names from `.design/tasks/*.md` (if directory exists), display the list, and prompt the user to specify a ComponentName. Exit without generating any file.
+
+---
+
+## Agent Spawn Payload
+
+Once mode and source path are resolved, spawn the `design-doc-writer` agent:
+
+```
+Task("design-doc-writer", """
+<required_reading>
+[If pipeline_complete=true:]
+@.design/STATE.md
+@.design/DESIGN-SUMMARY.md
+@.design/DESIGN-CONTEXT.md
+@<component_source_path>
+[Else (pipeline_complete=false):]
+@.design/DESIGN.md
+@<component_source_path>
+@reference/anti-patterns.md
+@reference/audit-scoring.md
+</required_reading>
+
+Generate a handoff spec for component <ComponentName>.
+
+Context:
+  component_name: <ComponentName>
+  component_source_path: <resolved absolute path>
+  pipeline_complete: <true|false>
+  output_path: .design/DESIGN-STYLE-<ComponentName>.md
+
+Produce the doc per STYL-05 sections:
+  - Spacing Tokens (used by component)
+  - Color Tokens (used by component)
+  - Typography Scale (used by component)
+  - Component States (default, hover, focus, active, disabled, etc.)
+  - Token Semantic Health Score (raw-hex-ratio formula — see ./shared-preamble.md#token-first-reasoning)
+  - AI-Slop Detection (using ./anti-patterns.md BAN/SLOP patterns)
+  [If pipeline_complete=true:]
+  - Decisions Applied (D-XX from DESIGN-SUMMARY.md that mention this component)
+
+Emit ## DOC COMPLETE when the output file is written.
+""")
+```
+
+After the agent emits `## DOC COMPLETE`, confirm the file exists at `output_path` and report success to the user.
+
+---
+
+## STYL-05 Section Spec
+
+Each generated `.design/DESIGN-STYLE-[ComponentName].md` SHOULD contain (in this order):
+
+1. **Spacing Tokens** — every spacing token the component uses (paddings, gaps, margins). Cross-reference `./composition.md` for the 4 px / 8 px modular scale discipline.
+2. **Color Tokens** — every color token the component uses (background, foreground, border, focus ring, state-overlays). Cross-reference `./palette-catalog.md` for naming convention and `./shared-preamble.md#token-first-reasoning` for the raw-hex audit threshold.
+3. **Typography Scale** — type ramps the component reaches into (label, body, code, etc.) with size + line-height + weight. Cross-reference `./typography.md`.
+4. **Component States** — default, hover, focus, active, disabled, loading, error. Each row: token diff vs default.
+5. **Token Semantic Health Score** — raw-hex ratio = `raw_hex_count / total_color_uses`. Healthy < 5 %.
+6. **AI-Slop Detection** — apply `./anti-patterns.md` `BAN-*` and `SLOP-*` patterns to the component source. List violations.
+7. **Decisions Applied** (post-pipeline only) — D-XX entries from `DESIGN-SUMMARY.md` that name or describe this component.
+
+---
+
+## Examples
+
+**Example 1: Named component**
+
+```
+/get-design-done style Button
+```
+
+- Resolves component: `src/components/Button.tsx`
+- Detects mode: DESIGN-SUMMARY.md exists → post-pipeline
+- Spawns `design-doc-writer` with `pipeline_complete: true`
+- Output: `.design/DESIGN-STYLE-Button.md`
+
+**Example 2: No argument (list mode)**
+
+```
+/get-design-done style
+```
+
+- Globs component files from `src/components/`
+- Displays available components and exits without generating any file.
+
+---
+
+*Imported by: `../skills/style/SKILL.md`. Maintained as part of Phase 28.5 (Bucket 2 rework).*

package/reference/threat-modeling.md

@@ -0,0 +1,101 @@
+---
+name: threat-modeling
+type: heuristic
+version: 1.0.0
+phase: 28.5
+tags: [threat-modeling, stride, audit, security, trust-boundary, disposition]
+last_updated: 2026-05-18
+---
+
+# Threat Modeling
+
+Audit-side STRIDE / threat-modeling reference. Centralizes the categories, trust-boundary
+identification heuristics, and disposition framework (mitigate / accept / transfer) so
+consumer skills can cross-link rather than inline. Extracted as part of Phase 28.5 from
+inline content in `skills/quality-gate/SKILL.md` (the four-tier classification) and the
+shared verifier / audit family. See `./audit-scoring.md` for the design-side scoring
+framework, which uses STRIDE as one of its lenses.
+
+## When to use
+
+Apply STRIDE during:
+
+- **Verify entry** (Stage 5) when the changeset touches a trust boundary (auth, ingress,
+  deserialization, subprocess spawn).
+- **Audit pillar runs** when a heuristic flags potential security surface.
+- **Plan-phase risk-register population** when the plan touches user input, network
+  endpoints, file IO from user paths, or persisted state.
+- **Threat register on plans that ship new endpoints** — assign one of {mitigate, accept,
+  transfer} to every identified threat before the plan ships.
+
+## STRIDE categories
+
+| Letter | Threat                  | Audit lens                                         |
+|--------|-------------------------|----------------------------------------------------|
+| S      | Spoofing                | Auth surfaces — login, session, token issuance     |
+| T      | Tampering               | Data integrity — write paths, persisted state      |
+| R      | Repudiation             | Audit trails / logging — proof of action           |
+| I      | Information Disclosure  | PII / secret leakage — logs, errors, side channels |
+| D      | Denial of Service       | Resource exhaustion — unbounded loops, large reads |
+| E      | Elevation of Privilege  | AuthZ bypass — role checks, capability tokens      |
+
+## Trust boundaries
+
+A trust boundary is a point where untrusted input crosses into trusted code. Identify
+trust boundaries before applying STRIDE — each boundary is one analysis sweep.
+
+Identification heuristics:
+
+- **Network ingress** — HTTP, gRPC, WebSocket, MCP transport, any TCP/UDP listen socket.
+- **File reads from user-writable paths** — uploads, `$HOME` configs, user-supplied paths
+  from CLI args, drag-drop.
+- **Subprocess spawns with user-supplied args** — `exec`/`spawn` where any argv element
+  is reachable from user input (URL params, env vars, config keys).
+- **Deserialization of persisted format** — JSON, YAML, MsgPack, Protobuf, custom
+  formats. The deserializer is the boundary, regardless of where the bytes came from.
+- **Third-party SDK callouts** — when gdd hands data to a peer-CLI, the data leaves the
+  trust boundary; treat the return path as untrusted on re-entry.
+
+## Disposition framework
+
+Every identified threat MUST carry a disposition before the plan ships. Three values:
+
+| Disposition | When to use                                                                  |
+|-------------|------------------------------------------------------------------------------|
+| Mitigate    | Threat has both impact and likelihood; ASVS L1 requires the control. Build  |
+|             | the control as part of the plan; cite the test that proves it.               |
+| Accept      | Low impact AND low likelihood. Documented rationale in the threat register;  |
+|             | no code change required. Re-visit if the threat-surface scope grows.         |
+| Transfer    | Third-party owns the control surface (e.g., the OS, the runtime, a peer's   |
+|             | sandbox). Document the boundary; do not re-implement the control.            |
+
+Mitigations on Plan tasks are correctness requirements — the executor applies Rule 2
+(missing critical functionality) if a mitigation disposition is present but the
+implementation lacks the control.
+
+## Threat register schema
+
+When a plan carries a `<threat_model>` block in its frontmatter, each entry follows:
+
+```yaml
+- id: T-01
+  category: spoofing       # S, T, R, I, D, or E
+  surface: auth/login      # path or component the threat hits
+  description: "<one-line description>"
+  disposition: mitigate    # mitigate, accept, or transfer
+  control: "rate-limit + ASVS V2.2.1 password policy"   # required when mitigate
+  rationale: "<why accept/transfer>"                    # required when accept/transfer
+```
+
+Multiple threats per plan are normal. The disposition column is the load-bearing field —
+the executor scans it; the verifier scans it.
+
+## Cross-references
+
+- `./audit-scoring.md` — design-side audit-scoring rubric; STRIDE is one of its lenses.
+- `./anti-patterns.md` — concrete anti-patterns mapped to STRIDE categories where
+  applicable (e.g., `eval`-on-user-input → Tampering + EoP).
+- `./accessibility.md` — accessibility is the orthogonal lens; threat-modeling does not
+  cover it.
+- ASVS (OWASP Application Security Verification Standard) — external authority for the
+  control catalog. Cited in plan threat-registers as `ASVS V<chapter>.<section>`.