@hegemonart/get-design-done 1.28.0 → 1.28.6

package/reference/context-md-format.md

@@ -0,0 +1,106 @@
+---
+name: context-md-format
+type: meta-rules
+version: 1.0.0
+phase: 28.5
+tags: [context-md, glossary, ubiquitous-language, ddd, project-scoped]
+last_updated: 2026-05-18
+---
+
+Source: mattpocock/skills (MIT) — adapted with permission. See `../NOTICE` for the full attribution block.
+
+# CONTEXT.md Format
+
+`CONTEXT.md` is a project-scoped ubiquitous-language glossary kept at the repository root.
+It captures domain terms the user and the agent have agreed upon so the next session does
+not re-litigate naming. `STATE.md` is cycle-scoped and rotates per pipeline run; `CONTEXT.md`
+outlives the cycle and compounds across runs. The `discuss` and `brief` skills write to it
+inline during interviews (no batching) — see Phase 28.5 plan `28.5-08` for the writer
+behavior. See `./adr-format.md` for the heavier project-scoped artifact (decisions that meet
+the 3-criteria gate).
+
+## Term entry
+
+Each entry is a `##` heading whose text is the term, followed by a body paragraph that
+defines it. The required surface is the heading and the definition; everything else is
+optional GDD adaptation.
+
+```markdown
+## <Term Name>
+
+<Definition — 1-3 sentences in plain language. Use existing CONTEXT.md vocabulary where
+possible (compounding effect — terms defined earlier in the file are reused in later
+definitions).>
+
+**First seen:** <cycle-id-or-NN> *(optional, GDD addition for traceability)*
+**Aliases:** [<term1>, <term2>] *(optional, GDD addition for term-merging — see §Aliases)*
+**Examples:** *(optional)*
+
+- <Concrete usage 1>
+- <Concrete usage 2>
+```
+
+- **Required fields.** The heading (term name) and the definition paragraph.
+- **Optional fields.** `**First seen:**`, `**Aliases:**`, `**Examples:**` — added by
+  `discuss` / `brief` skills as ergonomic. `first-seen` ties the term to an originating
+  cycle's `STATE.md`; `aliases` enables term-merging; examples concretize usage.
+
+## Lazy creation
+
+`CONTEXT.md` is created on the FIRST term resolution and never batched. The writing skill
+just appends — no precondition prompts, no "should we create CONTEXT.md?" question (D-04).
+
+- **Trigger.** A fuzzy phrase becomes a sharpened term (e.g., "thingy" → "materialization
+  cascade"), a new noun gets named, or two phrases collapse to one.
+- **Location.** Project root: `./CONTEXT.md`. Repos that span multiple bounded contexts use
+  `CONTEXT-MAP.md` plus per-area `<area>/CONTEXT.md` — see `## Multi-context`.
+- **No batching.** Do NOT wait to gather "enough" terms. Each resolved term lands
+  immediately so the file reflects the conversation at every checkpoint.
+
+## Aliases
+
+When two terms collapse to one canonical name, the loser becomes an entry in the winner's
+`**Aliases:**` line. The agent never silently drops a term — the alias preserves the prior
+vocabulary for grep, for the `decision-injector` hook, and for the user's mental model.
+
+```markdown
+## Materialization cascade
+
+The chain of steps that turns a sketch into a real, deployable artifact. Triggered by the
+prototype gate; spans sketch → spike → real-thing.
+
+**First seen:** v1.28.5
+**Aliases:** [making-things-real, materialize, "real-ification"]
+```
+
+- `decision-injector` (extended in plan `28.5-08`) searches `aliases` against task
+  descriptions so the canonical term surfaces even when the user types the old phrase.
+- Aliases are kebab-case OR quoted; mix freely.
+
+## Multi-context
+
+When the repo spans multiple bounded contexts (a monorepo with `apps/web` and `apps/api`,
+say), each context gets its own `<area>/CONTEXT.md` and the top-level `CONTEXT-MAP.md` lists
+them. Same entry format inside each file; `CONTEXT-MAP.md` is just an index.
+
+```markdown
+# Context Map
+
+## Web App
+`apps/web/CONTEXT.md`
+
+## API
+`apps/api/CONTEXT.md`
+```
+
+`discuss` / `brief` resolve which `CONTEXT.md` to write to by matching the active file
+paths in the conversation against the map. When no map exists, the single-file default
+(`./CONTEXT.md`) applies.
+
+## Cross-references
+
+- Decisions that outlive the cycle AND meet the 3-criteria gate (hard-to-reverse AND
+  surprising-without-context AND real-tradeoff) become ADRs — see `./adr-format.md`.
+- Cycle-scoped decisions stay in `STATE.md` — see `./STATE-TEMPLATE.md`.
+- Skill structural rules (length cap, frontmatter, progressive disclosure) — see
+  `./skill-authoring-contract.md`.

package/reference/heuristics.md

@@ -269,3 +269,87 @@ For each NNG heuristic (H-01 through H-10), rate 0–4:
 - 75–89: Good, minor issues
 - 60–74: Acceptable, improvement needed
 - <60: Significant UX problems, redesign required
+
+---
+
+## Dependency-cycle detection
+
+Algorithm consumed by `skills/analyze-dependencies/SKILL.md` Analysis 4. Detects cycles
+in the `@`-reference graph (File A → File B → File A) by DFS with path-tracking.
+
+**Input:** adjacency map `{from: [to, ...]}` built from `.design/intel/graph.json#edges`.
+
+**Algorithm:**
+
+```text
+visited = {}; path = []; cycles = []
+function dfs(node):
+  if node in path:
+    cycle_start = path.index(node)
+    cycles.append(path[cycle_start:] + [node])
+    return
+  if node in visited: return
+  visited.add(node); path.append(node)
+  for neighbor in adjacency[node]: dfs(neighbor)
+  path.pop()
+```
+
+**Bias notes:** the DFS visits each node at most once per traversal, so duplicate cycles
+across multiple entry points are deduped by the `visited` guard. The `path.index(node)`
+slice captures only the cycle suffix; nodes before the entry point are not part of the
+cycle. Pre-existing acyclic chains stay invisible — only back-edges surface.
+
+---
+
+## Version-cadence
+
+Reference for `skills/check-update/SKILL.md` and `skills/complete-cycle/SKILL.md` when
+comparing versions across releases.
+
+**Delta classification** (consumer of `.design/update-cache.json#delta`):
+
+| Delta | Meaning | When |
+|-------|---------|------|
+| `major` | Breaking change | `current.major < latest.major` |
+| `minor` | New features | Major same; `current.minor < latest.minor` |
+| `patch` | Bug fixes only | Major + minor same; `current.patch < latest.patch` |
+| `off-cadence` | Insertion-style version (`.5`, `.6`, `.7`) | Listed in `OFF_CADENCE_VERSIONS` in `tests/semver-compare.test.cjs` |
+| `none` | Same version | All segments equal |
+
+**Off-cadence handling:** versions like `v1.14.5`, `v1.27.5`, `v1.28.5` slot between regular
+minor bumps. They register via `OFF_CADENCE_VERSIONS.add('<version>')` in
+`tests/semver-compare.test.cjs`. The semver-compare test treats them as if they had a
+canonical predecessor (`v1.28.5` after `v1.28.0`, not `v1.28.4`).
+
+**Preview-suffix trap:** model IDs with `-preview` (`gpt-5-preview` vs `gpt-5`) drift — today's
+preview is tomorrow's GA. Tooling MUST store the parent name in `provider_model_id` and treat
+the suffix as decorative. See `./peer-cli-protocol.md` for the peer-CLI-side context.
+
+---
+
+## Optimization rules
+
+Reference catalog for `skills/optimize/SKILL.md`. Four deterministic rules; rule-based
+analysis applied in order. Each rule inspects per-agent aggregates from
+`.design/agent-metrics.json` and emits zero or more rows to the recommendations table.
+
+**R1 — Low cache hit rate.**
+- *Condition:* `total_spawns >= --min-spawns` AND `cache_hit_rate < 0.20`.
+- *Emit:* `"Consider batching tasks for agent {agent} — cache hit rate is {rate*100}%. Investigate cache-aligned ordering (see reference/shared-preamble.md) and whether input paths can be normalized."`
+- *Proposed action:* Batch similar tasks; confirm shared-preamble import ordering.
+
+**R2 — Expensive and rarely lazy-skipped.**
+- *Condition:* `total_cost_usd > 0.50` AND `lazy_skip_rate < 0.10`.
+- *Emit:* `"Agent {agent} is expensive (${cost}) and rarely skipped ({rate*100}% lazy-skip). Consider adding a lazy gate heuristic at agents/{agent}-gate.md (see plan 10.1-04 pattern)."`
+- *Proposed action:* Add lazy-gate agent.
+
+**R3 — Tier override churn.**
+- *Condition:* Multiple telemetry rows show recorded `tier` differing from frontmatter `default-tier` (e.g., frontmatter `opus` but measured rows consistently `haiku` from budget.json override or soft-threshold downgrade).
+- *Emit:* `"Tier override churn detected for {agent}: frontmatter says {frontmatter-tier} but measured tier is {measured-tier} in {N} of last {M} rows. Consider updating frontmatter default-tier or removing the budget.json override."`
+- *Proposed action:* Update frontmatter default-tier OR prune budget.json `tier_overrides` entry.
+
+**R4 — Typical duration drift.**
+- *Condition:* Measured `typical_duration_seconds` (computed as avg wall-clock between paired spawn/complete rows; fall back to frontmatter when pairing unavailable) differs from frontmatter `typical-duration-seconds` by more than 50%.
+- *Emit:* `"Typical duration for {agent} has drifted: frontmatter {old}s vs measured {new}s ({delta_pct}% drift). Update frontmatter typical-duration-seconds: {new}."`
+- *Proposed action:* Edit `agents/{agent}.md` frontmatter.
+- *Note:* v1 only computes wall-clock duration when telemetry ledger carries both spawn AND complete rows with matching correlation IDs. If unavailable, R4 flags "insufficient data" rather than emitting a false proposal. Phase 11 reflector can add a PostToolUse writer.

package/reference/registry.json

@@ -1,7 +1,7 @@
 {
   "$schema": "./schemas/registry.schema.json",
   "version": 1,
-  "generated_at": "2026-04-24T00:00:00.000Z",
+  "generated_at": "2026-05-18T12:47:59.666Z",
   "entries": [
     {
       "name": "codex-tools",
@@ -811,6 +811,34 @@
       "path": "reference/visual-hierarchy-layout.md",
       "type": "heuristic",
       "description": "Z-order, whitespace, grids, F/Z patterns, 24 landing archetypes"
+    },
+    {
+      "name": "adr-format",
+      "path": "reference/adr-format.md",
+      "type": "meta-rules",
+      "phase": 28.5,
+      "description": "ADR (Architecture Decision Record) format — adapted from mattpocock/skills (MIT). 3-criteria offer gate (hard-to-reverse AND surprising-without-context AND real-tradeoff), 4-state status lifecycle. GDD addition: optional cycle-id + phase-id cross-refs to STATE.md."
+    },
+    {
+      "name": "architecture-vocabulary",
+      "path": "reference/architecture-vocabulary.md",
+      "type": "principles",
+      "phase": 28.5,
+      "description": "Ousterhout glossary (A Philosophy of Software Design) ported via mattpocock/skills LANGUAGE.md (MIT). 8 core terms (Module / Interface / Implementation / Depth / Seam / Adapter / Leverage / Locality) + 3 principles (deletion test, interface-is-test-surface, two-adapters-rule)."
+    },
+    {
+      "name": "context-md-format",
+      "path": "reference/context-md-format.md",
+      "type": "meta-rules",
+      "phase": 28.5,
+      "description": "CONTEXT.md format — adapted from mattpocock/skills (MIT) CONTEXT-FORMAT.md. DDD-style ubiquitous-language glossary schema, inline-write trigger, multi-context CONTEXT-MAP.md pattern. GDD additions: optional first-seen + aliases on term entries."
+    },
+    {
+      "name": "skill-authoring-contract",
+      "path": "reference/skill-authoring-contract.md",
+      "type": "meta-rules",
+      "phase": 28.5,
+      "description": "Phase 28.5 skill-authoring contract — adapted from mattpocock/skills (MIT). SKILL.md <=100-line cap (warn >=100, block >=250 in CI), 1024-char description cap, <what>. Use when <triggers>. form (lax-mode default per Phase 33 A/B pending), frontmatter required fields, progressive-disclosure one-level-deep rule. Validator at scripts/validate-skill-length.cjs."
     }
   ]
 }

package/reference/registry.schema.json

@@ -45,7 +45,7 @@
             ]
           },
           "tier": { "enum": ["L0", "L1", "L2"] },
-          "phase": { "type": "integer", "description": "Phase that introduced this entry" },
+          "phase": { "type": "number", "description": "Phase that introduced this entry. Numbers are allowed (e.g., 19.6, 27.5, 27.6, 27.7, 28.5) — decimal phases are valid per the long-standing precedent established by Phases 19.6 / 27.5 / 27.6 / 27.7 / 28.5." },
           "description": { "type": "string" },
           "registered_at": { "type": "string", "format": "date-time" }
         },

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,159 @@
+---
+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 a reference. 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.
+- **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.
+
+### Reference placement classes
+
+Three placement classes by cross-domain consumer count (D-06, refreshed by Phase 28.6 D-04):
+
+- **1-consumer (skill-private procedure refs).** Live in `skills/<owner>/<topic>.md` next
+  to the SKILL.md they describe. Cross-link from SKILL.md as `./<topic>.md`. Matches
+  mattpocock's per-skill folder pattern. Examples: `skills/scan/scan-procedure.md`,
+  `skills/debug/debug-feedback-loops.md`.
+- **2-consumer (same-domain pair).** Live in the primary owner's skill folder. Secondary
+  consumer cross-links via `../<primary>/<topic>.md`. Examples:
+  `skills/cache-manager/cache-policy.md` (skills/warm-cache cross-links in);
+  `skills/peer-cli-add/peer-cli-protocol.md` (skills/peer-cli-customize + skills/peers
+  cross-link in).
+- **Multi-consumer (3+ cross-domain).** Live in `reference/<topic>.md`. Used by 3+ skills
+  across different domains. Examples: `reference/typography.md`,
+  `reference/palette-catalog.md`, `reference/audit-scoring.md` (each consumed by 15+
+  skills).
+
+### Migration policy
+
+When a reference grows from 1-consumer to 3+ cross-domain consumers, migrate from
+`skills/<owner>/` to `reference/` and update cross-links accordingly. When a centralized
+ref shrinks to 1–2 consumers (or its consumers turn out to be same-domain), migrate the
+other direction. Document the migration in the relevant phase's SUMMARY.md.
+
+### Phase 28.6 retrospective
+
+Phase 28.5 D-06 over-generalized by centralizing all extracted refs in `reference/`,
+including procedure refs read by exactly one skill. Phase 28.6 corrected this by migrating
+20 skill-private procedure refs back into their owning skill folders (D-01) and refreshing
+this section to endorse per-skill folders as the canonical placement for 1-consumer
+content (D-04). See
+`.planning/phases/28.6-skill-reference-co-location/CONTEXT.md` for the full discipline.
+
+Concrete example: a skill that lists 10 framework matrices inline (~150 lines) extracts
+the matrices to `reference/<framework>-matrices.md` (if 3+ skills will consume them) or
+`skills/<owner>/<framework>-matrices.md` (if only the owning skill reads them), then
+replaces the inline content 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.