@hegemonart/get-design-done 1.28.5 → 1.28.7

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). v1.20.0 ships the SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream, and resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) for rate-limit + 429 + context-overflow recovery. Full CI/CD pipeline (Node 22/24 × Linux/macOS/Windows) and release automation (auto-tag + GitHub Release + release-time smoke test).",
-    "version": "1.28.5"
+    "version": "1.28.7"
   },
   "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. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, 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. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain.",
-      "version": "1.28.5",
+      "version": "1.28.7",
       "author": {
         "name": "hegemonart"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.28.5",
+  "version": "1.28.7",
   "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. Embeds NNG heuristics, WCAG thresholds, typographic systems, motion framework, 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. v1.20.0 SDK foundation: gdd-state MCP server (11 typed tools), lockfile-safe STATE.md mutations, event stream at .design/telemetry/events.jsonl, resilience primitives (jittered-backoff, rate-guard, error-classifier, iteration-budget) with rate-limit + 429 + context-overflow recovery, and TypeScript toolchain. v1.27.7 ships gdd-mcp (Phase 27.7): 12 read-only MCP tools for sub-3s priming. v1.28.0 (Phase 28): Foundational References Tier 2 — 5 new reference files (color-theory, composition, proportion-systems, i18n, contrast-advanced), 2 verifier i18n probes + 1 explore i18n-readiness probe, 12 additive cross-link insertions across 10 existing references, 2 orthogonal audit-scoring lens-tags (composition_alignment + i18n_readiness).",
   "author": {
     "name": "hegemonart",

package/CHANGELOG.md

@@ -4,6 +4,108 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.28.7] — 2026-05-19
+
+### Phase 28.7 — Multi-Runtime Install (Pragmatic Port from gsd-build)
+
+Replaces the Phase 24 `kind: 'agents-md'` placeholder (which dropped a single bare `AGENTS.md` into each non-Claude runtime's config dir — content the runtimes did not actually consume) with proper native install for all 14 claimed runtimes. Architecture ported from `gsd-build/get-shit-done` (MIT) — see `NOTICE` for the rollup attribution. Per Phase 28.7 D-02 we port the architecture rather than byte-copying the upstream `bin/install.js` monolith. Off-cadence decimal sub-phase from v1.28.0 parent — sequence 1.28.0 → 1.28.5 → 1.28.6 → 1.28.7. Re-interpretation of the original ROADMAP Phase 28.7 (verification-gated) per user direction 2026-05-18: skip field-test reports, trust gsd-build's upstream proving of the pattern. 10 plans across Waves A (foundations) / B (converters) / C (wire-up + test + closeout).
+
+#### New install infrastructure (Wave A)
+
+- `scripts/lib/install/runtime-homes.cjs` (28.7-01) — pure per-runtime config-dir resolver for all 14 runtimes. Handles env-var overrides (`CLAUDE_CONFIG_DIR`, `XDG_CONFIG_HOME`, etc.), XDG paths, and special-case nests (Antigravity under `~/.gemini/antigravity`, Windsurf under `~/.codeium/windsurf`). Pure function — no I/O.
+- `scripts/lib/install/runtime-artifact-layout.cjs` (28.7-02) — per-(runtime, scope) layout table mapping each combination to its `kinds[] = [{kind, destSubpath, prefix}]` shape. Claude global → `skills/<name>/`; Claude local → `commands/gsd/` + `agents/`; cursor/codex/copilot/antigravity/windsurf/augment/trae/qwen/codebuddy → `skills/<name>/`; opencode + kilo → `command/<name>` (slash-command dir, not skills); gemini → `commands/gsd/` (commands-only); cline → `kinds: []` (rules-based — embeds in `.clinerules` per D-09).
+- `scripts/lib/install/runtime-slash.cjs` (28.7-03) — per-runtime slash-command surface emitter. Codex uses `$gdd-<name>` shell-var form; all others use `/gdd-<name>`. Reserves a forward-compat seam for downstream slash-aware install behaviors.
+
+#### Per-runtime content converters (Wave B)
+
+- 13 per-runtime converters at `scripts/lib/install/converters/<runtime>.cjs` (28.7-04 through 28.7-07), plus `shared.cjs` (frontmatter pass-through, tool-name rewrite, brand pass-through utilities). Each runtime converter exports `convert(content, skillName, ctx) → { path, content }`. Cross-references the Phase 21 cross-harness tool-name maps (`reference/codex-tools.md`, `reference/gemini-tools.md`) — tool name rewrites only happen for runtimes whose native tool names differ from Claude's defaults.
+  - Wave 1 (28.7-04) — `cursor`, `codex`, `copilot`, `antigravity`.
+  - Wave 2 (28.7-05) — `windsurf`, `augment`, `trae`, `qwen`.
+  - Wave 3 (28.7-06) — `codebuddy`, `cline`. **Cline** (D-09) writes rule-block aggregation to `.clinerules` rather than a skills directory.
+  - Wave 4 (28.7-07) — `opencode`, `kilo`, `gemini`. Opencode + kilo use `command/<name>` (slash-command dir); gemini ships commands-only into `commands/gsd/`.
+- **Hermes is OUT of scope** (D-03 + D-10) — Phase 24 D-02 runtime-list invariant preserved. The Phase 28.6 baseline tests' "no hermes.cjs" guard is mirrored in the new Phase 28.7 baseline test.
+
+#### Installer wire-up (Wave C.1)
+
+- `scripts/lib/install/installer.cjs` (28.7-08) — replaces the broken `kind: 'agents-md'` placeholder with a proper multi-artifact dispatcher. Reads the layout table, invokes the appropriate per-runtime converter for each kind, lands files at the resolved destination per `runtime-homes.cjs`. Backward-compat retained for the existing invocation surface (`--claude`, `--opencode`, …, `--cline`, `--dry-run`, `--global`, `--local`, `--config-dir`). Scope propagation through to converter `ctx` per D-07.
+
+#### Per-runtime simulation suite (Wave C.2)
+
+- `tests/install-per-runtime.test.cjs` (28.7-09) — 14 simulation tests + 11 cross-runtime invariants. Each test creates a temp config dir via `mkdtempSync`, invokes the installer with `--config-dir <tmp> --<runtime>`, and asserts files land at the expected paths with content matching the converter output. macOS symlink discipline applied (`os.tmpdir()` + `fs.realpathSync` for path comparison) per Phase 27.6 lesson.
+
+#### Fixed
+
+- 13 non-Claude runtimes now actually receive their plugin payload. Before Phase 28.7: bare `AGENTS.md` drop with no runtime-side discovery. After: native artifact layout matching what each runtime expects (skills dir / command dir / agents dir / rule-block embedding).
+
+#### Closeout (Wave C.3)
+
+- 4-manifest lockstep at v1.28.7 (`package.json` + `.claude-plugin/plugin.json` + `.claude-plugin/marketplace.json` (metadata.version + plugins[0].version) + `test-fixture/baselines/phase-28/manifests-version.txt` forward-propagation).
+- `OFF_CADENCE_VERSIONS.add('1.28.7')` in `tests/semver-compare.test.cjs`.
+- README install section confirmed claims all 14 runtimes; no Experimental tier (D-04). Translated READMEs deferred (English authoritative for this phase).
+- `NOTICE` extended with Phase 28.7 gsd-build/get-shit-done (MIT) architectural-port attribution (D-02). Phase 27 (cc-multi-cli, Apache 2.0) + Phase 28.5 (mattpocock/skills, MIT) attributions unchanged.
+- Baseline at `test-fixture/baselines/phase-28.7/` (manifests-version, converter-inventory, registry-diff) + `phase-28.6/manifests-version.txt` and `phase-28/manifests-version.txt` forward-propagated to 1.28.7.
+- `phase-20/skill-list.txt` UNCHANGED (no skill add/remove this phase).
+- ROADMAP add + scoped flip (this section + overview entry, 10 inline plan checkboxes pre-flipped).
+- Phase 28.7 ports gsd-build's architecture rather than gating on field-test reports — re-interpretation of the original ROADMAP entry per user direction 2026-05-18 (CONTEXT.md D-01).
+
+---
+
+## [1.28.6] — 2026-05-18
+
+### Phase 28.6 — Skill Reference Co-Location (Corrective Follow-Up to Phase 28.5)
+
+Corrects Phase 28.5's CONTEXT.md D-06 over-generalization. Phase 28.5 extracted 20 skill-private procedure refs into a central `reference/` folder, but each of those refs is consumed by exactly 1 (or in 2 borderline cases, 2 sibling) skills. Per mattpocock/skills' actual structure at `https://github.com/mattpocock/skills/tree/main/skills`, skill-private procedure docs live next to the `SKILL.md` they describe. Phase 28.6 co-locates the 20 refs into per-skill folders and refreshes the contract's §D-06 to endorse the per-skill folder pattern for 1-/2-consumer content. No new features. No breaking changes. `git mv` preserves history on every file. Phase 28.5's contract spec, validator, CI gate, `zoom-out`, debug Phase 1 patch, CONTEXT.md + ADR project artifacts, decision-injector extension, and 70/70 length compliance are all PRESERVED; only the location of skill-private refs changes.
+
+#### Migrated refs (20 — `reference/<topic>.md` -> `skills/<owner>/<topic>.md`)
+
+- `apply-reflections-procedure.md` -> `skills/apply-reflections/`
+- `cache-policy.md` -> `skills/cache-manager/` (primary; `warm-cache` secondary via `./../cache-manager/cache-policy.md`)
+- `compare-rubric.md` -> `skills/compare/`
+- `connections-onboarding.md` -> `skills/connections/`
+- `darkmode-audit-procedure.md` -> `skills/darkmode/`
+- `debug-feedback-loops.md` -> `skills/debug/`
+- `design-procedure.md` -> `skills/design/`
+- `discover-procedure.md` -> `skills/discover/`
+- `explore-procedure.md` -> `skills/explore/`
+- `health-mcp-detection.md` -> `skills/health/`
+- `health-skill-length-report.md` -> `skills/health/`
+- `milestone-completeness-rubric.md` -> `skills/new-cycle/` (primary; `turn-closeout` secondary)
+- `peer-cli-protocol.md` -> `skills/peer-cli-add/` (primary; `peer-cli-customize` + `peers` secondary)
+- `plan-procedure.md` -> `skills/plan/`
+- `router-rules.md` -> `skills/router/`
+- `scan-procedure.md` -> `skills/scan/`
+- `start-procedure.md` -> `skills/start/`
+- `style-doc-procedure.md` -> `skills/style/`
+- `threat-modeling.md` -> `skills/quality-gate/`
+- `verify-procedure.md` -> `skills/verify/`
+
+#### Contract refresh
+
+- `reference/skill-authoring-contract.md` §D-06 refreshed: per-skill folder pattern explicitly endorsed for skill-private content. Three placement classes codified — 1-consumer in `skills/<owner>/<topic>.md`; 2-consumer in primary owner's folder with `./../<primary>/<topic>.md` secondary cross-link; multi-consumer (3+ skills across different domains) in `reference/<topic>.md`. The Phase 28.5 "rare exception only" framing is reversed.
+
+#### Registry purge
+
+- `reference/registry.json`: 20 entries removed (the migrated procedure refs are no longer tracked centrally; they're discoverable via the skill folder itself, per mattpocock's pattern). Universal refs (consumed by 3+ skills) remain in the registry.
+
+#### Phase 28.5 retrospective annotation
+
+- `.planning/phases/28.5-skill-authoring-contract/CONTEXT.md` D-06 annotated with a "Corrected by Phase 28.6" pointer for audit-trail preservation. Phase 28.5 decisions stay visible but flagged as superseded.
+
+#### Plans
+
+- 28.6-01 — `git mv` 20 refs + cross-link updates across 23 SKILL.md consumers (`./../reference/<topic>.md` -> `./<topic>.md` or `./../<primary>/<topic>.md`). (COLOC-01)
+- 28.6-02 — `reference/registry.json` 20-entry purge (D-03) + `reference/skill-authoring-contract.md` §D-06 refresh (D-04). (COLOC-02)
+- 28.6-03 — Validator + baseline + full `npm test` sweep (all green; D-05 confirmation that `scripts/validate-skill-length.cjs` globs `SKILL.md` only; no validator edit). (COLOC-03)
+- 28.6-04 — Closeout (4-manifest lockstep at v1.28.6, `OFF_CADENCE_VERSIONS.add('1.28.6')`, CHANGELOG, ROADMAP add + scoped flip, baseline at `test-fixture/baselines/phase-28.6/`, Phase 28.5 CONTEXT.md retrospective annotation). (COLOC-04)
+
+#### Non-changes
+
+- NOTICE unchanged — Phase 28.5's mattpocock/skills MIT attribution still applies (same content; file paths shifted only).
+- `test-fixture/baselines/phase-20/skill-list.txt` unchanged — no skills added or removed.
+- `scripts/validate-skill-length.cjs` unchanged — D-05 verified the validator globs `SKILL.md` only and is unaffected by co-located procedure refs.
+
+---
+
 ## [1.28.5] — 2026-05-18
 
 ### Phase 28.5 — Skill Authoring Contract + Skill Rework + Project Artifacts

package/README.md

@@ -139,6 +139,8 @@ The installer prompts you to choose:
 1. **Runtime** — Claude Code, OpenCode, Gemini, Kilo, Codex, Copilot, Cursor, Windsurf, Antigravity, Augment, Trae, Qwen Code, CodeBuddy, Cline, or all (interactive multi-select — pick multiple runtimes in a single session)
 2. **Location** — Global (all projects) or local (current project only)
 
+All 14 runtimes receive their native artifact layout (`skills/`, `command/`, `agents/`, or `.clinerules`) via per-runtime content converters — Claude SKILL.md sources are translated to each runtime's expected shape at install time (frontmatter pass-through, path rewrite, tool-name rewrite via the Phase 21 cross-harness maps). Architecture ported from `gsd-build/get-shit-done` (MIT — see `NOTICE`).
+
 Verify with:
 
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.28.5",
+  "version": "1.28.7",
   "description": "A design-quality pipeline for AI coding agents: brief, plan, implement, and verify UI work against your design system.",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",

package/reference/registry.json

@@ -819,13 +819,6 @@
       "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": "apply-reflections-procedure",
-      "path": "reference/apply-reflections-procedure.md",
-      "type": "heuristic",
-      "phase": 28.5,
-      "description": "Phase 28.5 — apply-reflections procedure extracted from skills/apply-reflections per progressive-disclosure rule. Read by skills/apply-reflections/SKILL.md."
-    },
     {
       "name": "architecture-vocabulary",
       "path": "reference/architecture-vocabulary.md",
@@ -833,27 +826,6 @@
       "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": "cache-policy",
-      "path": "reference/cache-policy.md",
-      "type": "heuristic",
-      "phase": 28.5,
-      "description": "Phase 28.5 — cache-policy reference extracted from skills/cache-manager + skills/warm-cache per progressive-disclosure rule (Bucket 3 orchestrator + utility rework)."
-    },
-    {
-      "name": "compare-rubric",
-      "path": "reference/compare-rubric.md",
-      "type": "heuristic",
-      "phase": 28.5,
-      "description": "Phase 28.5 — compare-rubric extracted from skills/compare per progressive-disclosure rule. Read by skills/compare/SKILL.md (Bucket 2 design-family rework)."
-    },
-    {
-      "name": "connections-onboarding",
-      "path": "reference/connections-onboarding.md",
-      "type": "meta-rules",
-      "phase": 28.5,
-      "description": "Phase 28.5 — connections-onboarding procedure extracted from skills/connections per progressive-disclosure rule (Bucket 2 design-family rework). Four-option setup prompt + onboarding flow."
-    },
     {
       "name": "context-md-format",
       "path": "reference/context-md-format.md",
@@ -861,124 +833,12 @@
       "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": "darkmode-audit-procedure",
-      "path": "reference/darkmode-audit-procedure.md",
-      "type": "meta-rules",
-      "phase": 28.5,
-      "description": "Phase 28.5 — darkmode audit procedure extracted from skills/darkmode per progressive-disclosure rule (Bucket 2 design-family rework)."
-    },
-    {
-      "name": "debug-feedback-loops",
-      "path": "reference/debug-feedback-loops.md",
-      "type": "heuristic",
-      "phase": 28.5,
-      "description": "Debug feedback-loop discipline — adapted from mattpocock/skills (MIT) engineering/diagnose Phase 1. 10 construction paths in priority order (failing test -> curl -> CLI fixture -> headless browser -> trace replay -> throwaway harness -> fuzz -> bisect harness -> differential loop -> HITL bash), iterate-on-loop sub-discipline, non-determinism reproduction-rate branch."
-    },
-    {
-      "name": "design-procedure",
-      "path": "reference/design-procedure.md",
-      "type": "meta-rules",
-      "phase": 28.5,
-      "description": "Phase 28.5 — design-stage procedure extracted from skills/design per progressive-disclosure rule (Bucket 1 pipeline-stage rework)."
-    },
-    {
-      "name": "discover-procedure",
-      "path": "reference/discover-procedure.md",
-      "type": "meta-rules",
-      "phase": 28.5,
-      "description": "Phase 28.5 — discover-stage procedure extracted from skills/discover per progressive-disclosure rule (Bucket 1 pipeline-stage rework)."
-    },
-    {
-      "name": "explore-procedure",
-      "path": "reference/explore-procedure.md",
-      "type": "meta-rules",
-      "phase": 28.5,
-      "description": "Phase 28.5 — explore-stage procedure extracted from skills/explore per progressive-disclosure rule (Bucket 1 pipeline-stage rework)."
-    },
-    {
-      "name": "health-mcp-detection",
-      "path": "reference/health-mcp-detection.md",
-      "type": "heuristic",
-      "phase": 28.5,
-      "description": "Phase 28.5 — health-MCP detection procedure extracted from skills/health per progressive-disclosure rule (D-10). Documents dismissal check, detection via scripts/lib/install/mcp-register.cjs, row rendering for claude/codex/both/neither, fallback for missing mcp-register.cjs."
-    },
-    {
-      "name": "health-skill-length-report",
-      "path": "reference/health-skill-length-report.md",
-      "type": "heuristic",
-      "phase": 28.5,
-      "description": "Phase 28.5 — health-skill-length-report contract documenting validate-skill-length.cjs JSON shape + threshold rationale. Read by skills/health/SKILL.md to render the skill-length report subsection."
-    },
-    {
-      "name": "milestone-completeness-rubric",
-      "path": "reference/milestone-completeness-rubric.md",
-      "type": "heuristic",
-      "phase": 28.5,
-      "description": "Phase 28.5 — milestone-completeness rubric extracted from skills/turn-closeout per progressive-disclosure rule (Bucket 4 analysis + audit rework). Turn-closeout / new-cycle completeness criteria."
-    },
-    {
-      "name": "peer-cli-protocol",
-      "path": "reference/peer-cli-protocol.md",
-      "type": "heuristic",
-      "phase": 28.5,
-      "description": "Phase 28.5 — peer-CLI protocol scaffold extracted from skills/peer-cli-add + skills/peer-cli-customize per progressive-disclosure rule (Bucket 4 analysis + audit rework). ACP + ASP adapter scaffolding patterns, verification ladder, Windows quirk handling."
-    },
-    {
-      "name": "plan-procedure",
-      "path": "reference/plan-procedure.md",
-      "type": "meta-rules",
-      "phase": 28.5,
-      "description": "Phase 28.5 — plan-stage procedure extracted from skills/plan per progressive-disclosure rule (Bucket 1 pipeline-stage rework)."
-    },
-    {
-      "name": "router-rules",
-      "path": "reference/router-rules.md",
-      "type": "heuristic",
-      "phase": 28.5,
-      "description": "Phase 28.5 — router-rules reference extracted from skills/router per progressive-disclosure rule (Bucket 3 orchestrator + utility rework). S/M/L/XL bucket assignments + path-selection heuristic."
-    },
-    {
-      "name": "scan-procedure",
-      "path": "reference/scan-procedure.md",
-      "type": "meta-rules",
-      "phase": 28.5,
-      "description": "Phase 28.5 — scan-stage procedure extracted from skills/scan per progressive-disclosure rule (Bucket 1 pipeline-stage rework)."
-    },
     {
       "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."
-    },
-    {
-      "name": "start-procedure",
-      "path": "reference/start-procedure.md",
-      "type": "heuristic",
-      "phase": 28.5,
-      "description": "Phase 28.5 — start-procedure reference extracted from skills/start per progressive-disclosure rule (Bucket 4 analysis + audit rework)."
-    },
-    {
-      "name": "style-doc-procedure",
-      "path": "reference/style-doc-procedure.md",
-      "type": "meta-rules",
-      "phase": 28.5,
-      "description": "Phase 28.5 — style-doc procedure extracted from skills/style per progressive-disclosure rule (Bucket 2 design-family rework)."
-    },
-    {
-      "name": "threat-modeling",
-      "path": "reference/threat-modeling.md",
-      "type": "heuristic",
-      "phase": 28.5,
-      "description": "Phase 28.5 — STRIDE threat-modeling patterns extracted from skills/quality-gate + audit-side scanning per progressive-disclosure rule (Bucket 4 analysis + audit rework). Audit-side threat-model invariants."
-    },
-    {
-      "name": "verify-procedure",
-      "path": "reference/verify-procedure.md",
-      "type": "meta-rules",
-      "phase": 28.5,
-      "description": "Phase 28.5 — verify-stage procedure extracted from skills/verify per progressive-disclosure rule (Bucket 1 pipeline-stage rework)."
     }
   ]
 }

package/reference/skill-authoring-contract.md

@@ -101,21 +101,52 @@ disable-model-invocation: true
 
 References-one-level-deep is the rule (D-06):
 
-- **One level deep.** `SKILL.md` may cross-link into `reference/<topic>.md`. A reference may
+- **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.
-- **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.
+### 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
 

package/scripts/install.cjs

@@ -167,6 +167,13 @@ async function main() {
     } else if (location === 'local') {
       opts.configDir = resolveLocalConfigDir(runtime);
     }
+    // Phase 28.7 D-07 — pass scope through to the installer. The new
+    // `multi-artifact` kind branches on `local` vs `global` in
+    // `runtime-artifact-layout.cjs` (claude local writes commands/+agents/;
+    // claude global writes skills/), so the installer needs to know the
+    // user's chosen scope, not just the resolved configDir. Default is
+    // `global` per D-07.
+    opts.scope = location;
     const result = uninstall
       ? uninstallRuntime(id, opts)
       : installRuntime(id, opts);

package/scripts/lib/install/converters/antigravity.cjs

@@ -0,0 +1,48 @@
+'use strict';
+
+/**
+ * scripts/lib/install/converters/antigravity.cjs — Phase 28.7 (Plan 28.7-04).
+ *
+ * Google Antigravity SKILL.md converter. Translates Claude-shape source
+ * into Antigravity's expected shape (which nests under `~/.gemini/antigravity/`
+ * per the runtime-homes resolver):
+ *
+ *   - Frontmatter `name:` normalized to `gdd-<skill>` (no double-prefix).
+ *   - Slash references in prose pass through as `/gdd-<name>` —
+ *     Antigravity accepts the Claude shape. Mixed-shape inputs are
+ *     normalized via the runtime-slash module.
+ *   - Tool names in code fences pass through unchanged — Antigravity
+ *     accepts the Claude vocabulary (Read/Write/Bash/Edit/Grep/Glob).
+ *   - A 1-line HTML adapter header is injected at the top of the body
+ *     to record that this file was auto-generated from Claude source.
+ *
+ * Architecture ported from gsd-build/get-shit-done (MIT) — per Phase
+ * 28.7 D-02 (port architecture, not source). See NOTICE for upstream
+ * attribution. gsd-build's equivalent function is
+ * `convertClaudeCommandToAntigravitySkill` in bin/install.js; our
+ * modular factor delegates the actual rewrites to ./shared.cjs.
+ *
+ * Pure / side-effect-free: no fs, no env, no path. `convert` is a
+ * deterministic string → string transform.
+ */
+
+const shared = require('./shared.cjs');
+
+/**
+ * Convert Claude-source SKILL.md content for the Antigravity runtime.
+ *
+ * @param {string} content        Full source SKILL.md content (frontmatter + body).
+ * @param {string} skillName      The bare skill name (e.g. `'help'`, `'explore'`).
+ * @param {{ runtime?: string }} [opts]  Optional context — `runtime` defaults
+ *   to `'antigravity'`. Currently informational only.
+ * @returns {string}
+ */
+function convert(content, skillName, opts) {
+  const { frontmatter, body } = shared.extractFrontmatterAndBody(content);
+  const fm = shared.buildFrontmatter(frontmatter, skillName, 'gdd-');
+  let out = shared.rewriteSlashRefs(body, 'antigravity');
+  out = shared.ensureAdapterHeader(out, 'Antigravity');
+  return fm + out;
+}
+
+module.exports = { convert };

package/scripts/lib/install/converters/augment.cjs

@@ -0,0 +1,68 @@
+'use strict';
+
+/**
+ * scripts/lib/install/converters/augment.cjs — Phase 28.7 (Plan 28.7-05).
+ *
+ * Augment Code SKILL.md converter. Translates Claude-shape source into
+ * Augment's expected shape:
+ *
+ *   - Frontmatter `name:` normalized to `gdd-<skill>` (no double-prefix).
+ *   - Slash references in prose pass through as `/gdd-<name>` —
+ *     Augment accepts the Claude shape for slash references.
+ *   - Tool names in code fences are rewritten per `AUGMENT_TOOL_MAP`:
+ *       Bash → launch-process
+ *       Edit → str-replace-editor
+ *     Read/Write/Grep/Glob/WebSearch/WebFetch pass through unchanged —
+ *     Augment recognizes the Claude vocabulary for those tools.
+ *   - Prose mentions of tool names (e.g. "use the Bash tool") are NOT
+ *     rewritten — only the parenthesized invocation form inside fenced
+ *     blocks gets rewritten. This matches the codex converter's policy
+ *     (Phase 28.7 D-06).
+ *   - A 1-line HTML adapter header is injected at the top of the body
+ *     to record that this file was auto-generated from Claude source.
+ *
+ * Architecture ported from gsd-build/get-shit-done (MIT) — per Phase
+ * 28.7 D-02 (port architecture, not source). See NOTICE for upstream
+ * attribution. gsd-build's equivalent function is
+ * `convertClaudeCommandToAugmentSkill` in bin/install.js; our modular
+ * factor delegates the actual rewrites to ./shared.cjs.
+ *
+ * Pure / side-effect-free: no fs, no env, no path. `convert` is a
+ * deterministic string → string transform.
+ */
+
+const shared = require('./shared.cjs');
+
+/**
+ * Claude tool name → Augment tool name. Per Augment's documented tool
+ * surface (launch-process for shell execution, str-replace-editor for
+ * file edits). Frozen to prevent accidental mutation.
+ *
+ * Future: extract AUGMENT_TOOL_MAP to reference/augment-tools.md per
+ * the Phase 21 pattern (cf. CODEX_TOOL_MAP in shared.cjs) if scope grows
+ * beyond two entries.
+ */
+const AUGMENT_TOOL_MAP = Object.freeze({
+  Bash: 'launch-process',
+  Edit: 'str-replace-editor',
+});
+
+/**
+ * Convert Claude-source SKILL.md content for the Augment runtime.
+ *
+ * @param {string} content        Full source SKILL.md content (frontmatter + body).
+ * @param {string} skillName      The bare skill name (e.g. `'help'`, `'explore'`).
+ * @param {{ runtime?: string }} [opts]  Optional context — `runtime` defaults
+ *   to `'augment'`. Currently informational only.
+ * @returns {string}
+ */
+function convert(content, skillName, opts) {
+  const { frontmatter, body } = shared.extractFrontmatterAndBody(content);
+  const fm = shared.buildFrontmatter(frontmatter, skillName, 'gdd-');
+  let out = shared.rewriteSlashRefs(body, 'augment');
+  out = shared.rewriteCodeFenceTools(out, AUGMENT_TOOL_MAP);
+  out = shared.ensureAdapterHeader(out, 'Augment');
+  return fm + out;
+}
+
+module.exports = { convert, AUGMENT_TOOL_MAP };