@hegemonart/get-design-done 1.23.5 → 1.24.1

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.23.5"
+    "version": "1.24.1"
   },
   "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.23.5",
+      "version": "1.24.1",
       "author": {
         "name": "hegemonart"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.23.5",
+  "version": "1.24.1",
   "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.",
   "author": {
     "name": "hegemonart",

package/CHANGELOG.md

@@ -4,6 +4,71 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.24.1] — 2026-04-25
+
+CodeQL code-scanning cleanup — closes all 10 open alerts on `main` (1 error, 9 warnings). No behavior change for end users; security/quality patch on top of v1.24.0.
+
+### Fixed
+
+- **`scripts/extract-changelog-section.cjs:31`** — `js/regex-injection` (error) + `js/incomplete-sanitization`. The CLI version arg was only escaping `.` before being interpolated into `new RegExp(...)`. Now escapes the full regex meta-char set `[.*+?^${}()|[\]\\]` via the same helper used elsewhere in the test suite.
+- **`tests/mapper-schema.test.cjs:15`** — `js/incomplete-sanitization`. `extractSchemaKeys()` now uses the full meta-char escape on the slice-name input before constructing the heading regex.
+- **`tests/skill-brief-mcp-migration.test.cjs:118`** — `js/identity-replacement`. The MCP-tool-presence check used `tool.replace(/_/g, '_')` (a no-op) inside `new RegExp(...)`. Replaced with a literal substring check (`assert.ok(fm.includes(tool))`) — MCP tool names are alphanumeric+underscore, so no regex is needed.
+- **`.github/workflows/ci.yml`** — `actions/missing-workflow-permissions` (×6 jobs). Added a top-level `permissions: contents: read` block. Inherited by all 6 jobs (lint / validate / test / security / size-budget / e2e-headless). Gitleaks runs with `GITLEAKS_ENABLE_COMMENTS: false` so it does not require `pull-requests: write`.
+
+### Tests
+
+- `tests/phase-24-baseline.test.cjs` — manifest-alignment assertions bumped to `1.24.1`.
+- `tests/semver-compare.test.cjs` `OFF_CADENCE_VERSIONS` gains `1.24.1`.
+
+---
+
+## [1.24.0] — 2026-04-25
+
+Phase 24 Multi-Runtime Installer milestone — `npx @hegemonart/get-design-done` with no flags now launches a polished interactive install session (`@clack/prompts`) that walks the user through a multi-select of all 14 supported AI coding runtimes plus a Global/Local radio. Scripted / CI installs continue to work via the existing flag surface unchanged. Strict superset over v1.23.5: any non-zero invocation still works exactly as before.
+
+### Added
+
+- **Per-runtime install matrix** — `scripts/lib/install/runtimes.cjs` exports a 14-entry frozen list. Each entry: `{id, displayName, configDirEnv, configDirFallback, kind, files, marketplaceEntry?}`. Two install kinds are supported: `claude-marketplace` (registers an `extraKnownMarketplaces` entry + flips `enabledPlugins[<plugin>@<marketplace>]`, today only Claude Code) and `agents-md` (drops a runtime-specific instructions file in the runtime's config dir, used by the other 13). Adding a new runtime is one append to this file + one append to `test-fixture/baselines/phase-24/runtimes.txt`. (Plan 24-01)
+
+- **14 runtimes scoped** — Claude Code, OpenCode, Gemini CLI, Kilo Code, OpenAI Codex CLI, GitHub Copilot CLI, Cursor, Windsurf, Antigravity, Augment, Trae, Qwen Code, CodeBuddy, Cline. Gemini drops `GEMINI.md`; the other 12 `agents-md` runtimes drop `AGENTS.md`. (Plan 24-01)
+
+- **Config-dir lookup chain** — `scripts/lib/install/config-dir.cjs` exposes `resolveConfigDir(runtimeId, opts)` and `resolveAllConfigDirs(opts)`. Precedence: explicit `--config-dir` flag > per-runtime env var (`CLAUDE_CONFIG_DIR`, `OPENCODE_CONFIG_DIR`, `GEMINI_CONFIG_DIR`, `CODEX_HOME`, `CURSOR_CONFIG_DIR`, …) > POSIX/Windows fallback at `$HOME/$USERPROFILE` joined with the runtime's `configDirFallback`. Mirrors GSD `install.js`'s lookup pattern. (Plan 24-01)
+
+- **Settings merge / unmerge primitives** — `scripts/lib/install/merge.cjs` exports pure `mergeClaudeSettings(existing, marketplaceEntry) → {next, changed}` and `removeClaudeSettings(existing, marketplaceEntry) → {next, changed}`. Both are idempotent and preserve unrelated user keys. `buildAgentsFileContent(runtime)` produces the runtime-tagged AGENTS.md/GEMINI.md payload with a `<!-- get-design-done plugin instructions -->` fingerprint. `isPluginOwned(content)` is the inverse used by uninstall + foreign-file detection. (Plan 24-02)
+
+- **Per-runtime install/uninstall orchestrator** — `scripts/lib/install/installer.cjs` exports `installRuntime(runtimeId, opts)` and `uninstallRuntime(runtimeId, opts)`, both returning a structured `Result = {runtime, path, action: 'created'|'updated'|'unchanged'|'removed'|'skipped-foreign', dryRun, reason?}`. Atomic writes (`.tmp-<pid>` + rename) throughout. Foreign AGENTS.md/GEMINI.md files (no plugin fingerprint) are never clobbered — install reports `skipped-foreign` with a remediation hint. `detectInstalled(opts)` scans every runtime's config dir and returns the IDs that have a plugin-owned install. (Plan 24-02)
+
+- **`@clack/prompts` interactive session** — `scripts/lib/install/interactive.cjs` exports `runInteractiveInstall()` (3 steps: multi-select runtimes → Global/Local radio → confirmation) and `runInteractiveUninstall(opts)` (2 steps: multi-select detected-installed → confirmation). ESC at any step returns `null` so the entrypoint exits 0 with a "cancelled" message — no partial writes. `@clack/prompts ^0.7.0` added as a runtime dependency (~8KB). (Plan 24-03)
+
+- **Multi-runtime entrypoint** — `scripts/install.cjs` rewritten as a router. Decision tree: zero flags + TTY → interactive multi-select; zero flags + non-TTY (CI, pipes) → defaults to `--claude --global` for backwards compatibility with v1.23.5; any explicit per-runtime flag (or `--all`) → scripted, no prompts. `--uninstall` with no runtime list also enters interactive mode and only shows runtimes detected as installed. Per-runtime summary printed at the end with per-runtime path + action. (Plan 24-04)
+
+- **Existing flag surface preserved 1:1** — `--claude`, `--opencode`, `--gemini`, `--kilo`, `--codex`, `--copilot`, `--cursor`, `--windsurf`, `--antigravity`, `--augment`, `--trae`, `--qwen`, `--codebuddy`, `--cline`, `--all`, `--global`, `--local`, `--uninstall`, `--config-dir <path>`, `--dry-run`, `--help`, `-h`. Existing CI installs (`CLAUDE_CONFIG_DIR=/tmp npx @hegemonart/get-design-done`) continue to work with no source changes. (Plan 24-04)
+
+- **Idempotent + foreign-safe install** — re-running install over an already-installed runtime emits `unchanged` with the v1.23.5 "already registered" message preserved. AGENTS.md / GEMINI.md files NOT authored by this plugin are detected via missing fingerprint and never overwritten or deleted by uninstall. (Plan 24-02)
+
+### Changed
+
+- `tests/semver-compare.test.cjs` `OFF_CADENCE_VERSIONS` gains `1.24.0`.
+- `scripts/install.cjs` — full rewrite. The original v1.23.5 single-runtime marketplace registration logic is now extracted into `scripts/lib/install/merge.cjs` (`mergeClaudeSettings` / `removeClaudeSettings`) and reused by the new orchestrator.
+
+### Tests
+
+- `tests/install-runtimes.test.cjs` — 14-entry shape, kind/file mapping per runtime, baseline-file alignment, ID uniqueness, unknown-runtime throws (10 tests).
+- `tests/install-config-dir.test.cjs` — env override, explicit override, fallback resolution, empty env-var fallthrough, all-runtimes resolution (8).
+- `tests/install-merge.test.cjs` — merge/remove idempotency + key preservation, fingerprint helpers, full install→idempotent→uninstall round-trips for both kinds, foreign-file refusal + missing-target uninstall (15).
+- `tests/phase-24-baseline.test.cjs` — 3-manifest version alignment at 1.24.0, `@clack/prompts` registration, surface-export contract per module, runtimes.txt baseline match, install.cjs rewrite anchor (8).
+- All 7 existing `tests/install-script.test.cjs` end-to-end spawn tests pass against the rewritten entrypoint.
+
+Total: 41 new tests. All Phase 20/21/22/23/23.5 tests still green.
+
+### Deferred
+
+- Stdin-simulation integration tests for the interactive flow itself (requires a PTY shim; manual smoke-test on Windows CMD / PowerShell / Windows Terminal covers v1).
+- Auto-detection of installed runtimes during the install flow (multi-select with all 14 visible is sufficient for v1; uninstall flow already filters to detected-installed via `detectInstalled`).
+- Per-runtime MCP server registration writes — each runtime's MCP entry format differs and the install matrix records the format but does not generate the entries.
+
+---
+
 ## [1.23.5] — 2026-04-25
 
 Phase 23.5 No-Regret Adaptive Layer milestone — turns the passive Phase 22–23 observability + validation infrastructure into a closed self-tuning loop. Three tightly-scoped no-regret algorithms sharing one feature-flag ladder. Single-user viable via informed Beta-prior bootstrap (no shared telemetry required). Ships as a decimal patch on the v1.23 minor — does NOT shift Phase 24 → v1.24.0.

package/README.md

@@ -104,7 +104,11 @@ Built-in quality gates catch real problems: Handoff Faithfulness scoring on Clau
 - **Component generators** — 21st.dev Magic MCP adds a prior-art gate before any greenfield build; Magic Patterns generates DS-aware components with a `preview_url` for visual verification. Both feed into a shared `design-component-generator` agent.
 - **Twelve tool connections** — Four new connections (paper.design, pencil.dev, 21st.dev, Magic Patterns) join the original eight. All are optional; the pipeline degrades gracefully to fallbacks when any connection is unavailable.
 
-## What's New in v1.21.0
+## What's New in v1.24.0
+
+**Multi-runtime installer** (headline upgrade) — `npx @hegemonart/get-design-done` with no flags now opens a polished interactive multi-select (`@clack/prompts`) for all 14 supported AI coding runtimes — Claude Code, OpenCode, Gemini CLI, Kilo Code, OpenAI Codex CLI, GitHub Copilot CLI, Cursor, Windsurf, Antigravity, Augment, Trae, Qwen Code, CodeBuddy, Cline. Pick any subset, choose Global or Local, confirm, done. Idempotent + foreign-AGENTS.md-safe. Scripted CI installs continue to work via the existing flag surface unchanged. See the [Getting Started](#getting-started) section below.
+
+### Previously in v1.21.0
 
 **Headless SDK** (headline upgrade) — the plugin now ships a `gdd-sdk` CLI that runs the full design pipeline without Claude Code. Five subcommands (`run`, `stage`, `query`, `audit`, `init`) work on any CI runner with Node 22+ and an `ANTHROPIC_API_KEY`. See the [Headless SDK](#headless-sdk) section below for examples.
 
@@ -134,14 +138,22 @@ Built-in quality gates catch real problems: Handoff Faithfulness scoring on Clau
 npx @hegemonart/get-design-done@latest
 ```
 
-That's it. The installer writes a `get-design-done` marketplace entry and enables the plugin in `~/.claude/settings.json` atomically. Restart Claude Code (or run `/reload-plugins`), and the pipeline is live.
+In a TTY this opens a polished interactive multi-select (`@clack/prompts`) — pick which AI runtimes to install into and whether to install Globally or Locally. Press `[a]` to select all 14 supported runtimes at once. In non-TTY contexts (CI, pipes), the same command falls back to `--claude --global` for full backwards compatibility with v1.23.5 and earlier.
+
+After install, restart the affected runtime(s) (or run `/reload-plugins` for Claude Code) and the pipeline is live.
+
+**Supported runtimes** *(v1.24.0+)*
+
+Claude Code, OpenCode, Gemini CLI, Kilo Code, OpenAI Codex CLI, GitHub Copilot CLI, Cursor, Windsurf, Antigravity, Augment, Trae, Qwen Code, CodeBuddy, Cline.
+
+Claude Code uses marketplace registration (`extraKnownMarketplaces` + `enabledPlugins` in `settings.json`); the other 13 runtimes follow the AGENTS.md / GEMINI.md convention — the installer drops a fingerprinted instructions file in the runtime's config dir (and refuses to overwrite an existing AGENTS.md it didn't author).
 
 **What the installer does**
 
-- Registers the `github:hegemonart/get-design-done` marketplace in `extraKnownMarketplaces`
-- Flips `enabledPlugins["get-design-done@get-design-done"]` to `true`
-- Preserves every other key in your settings — theme, permissions, other marketplaces — untouched
-- Idempotent: safe to re-run; no duplicate entries
+- For Claude Code: registers the `github:hegemonart/get-design-done` marketplace in `extraKnownMarketplaces` and flips `enabledPlugins["get-design-done@get-design-done"]` to `true`.
+- For AGENTS.md runtimes: drops a fingerprinted `AGENTS.md` (or `GEMINI.md`) in the runtime's config dir.
+- Preserves every other key in your settings — theme, permissions, other marketplaces — untouched.
+- Idempotent: safe to re-run; no duplicate entries; foreign AGENTS.md files are never overwritten.
 
 On first Claude Code launch after install, a `SessionStart` bootstrap hook provisions the companion reference library `~/.claude/libs/awesome-design-md` (idempotent — subsequent sessions run `git pull --ff-only`).
 
@@ -158,13 +170,30 @@ A one-line SessionStart nudge surfaces `/gdd:start` in fresh repos; run `/gdd:st
 ### Non-interactive install (CI, Docker, scripts)
 
 ```bash
-# Dry-run: print the diff, don't write
+# Dry-run: print the diff, don't write (Claude Code only by default)
 npx @hegemonart/get-design-done@latest --dry-run
 
 # Custom config dir (Docker, non-default Claude root)
 CLAUDE_CONFIG_DIR=/workspace/.claude npx @hegemonart/get-design-done@latest
+
+# Pick specific runtimes (any flag → scripted, no prompts)
+npx @hegemonart/get-design-done@latest --claude --opencode --gemini
+
+# Install into every supported runtime
+npx @hegemonart/get-design-done@latest --all
+
+# Local install (drops files into the current working directory)
+npx @hegemonart/get-design-done@latest --opencode --local
+
+# Uninstall — bare flag enters interactive multi-select of detected runtimes
+npx @hegemonart/get-design-done@latest --uninstall
+
+# Uninstall scripted (no prompt)
+npx @hegemonart/get-design-done@latest --uninstall --claude --gemini
 ```
 
+Per-runtime env-var overrides: `CLAUDE_CONFIG_DIR`, `OPENCODE_CONFIG_DIR`, `GEMINI_CONFIG_DIR`, `CODEX_HOME`, `CURSOR_CONFIG_DIR`, `KILO_CONFIG_DIR`, `COPILOT_CONFIG_DIR`, `WINDSURF_CONFIG_DIR`, `ANTIGRAVITY_CONFIG_DIR`, `AUGMENT_CONFIG_DIR`, `TRAE_CONFIG_DIR`, `QWEN_CONFIG_DIR`, `CODEBUDDY_CONFIG_DIR`, `CLINE_CONFIG_DIR`. Each falls back to `$HOME / $USERPROFILE` joined with the runtime's default subdirectory (e.g. `~/.claude`, `~/.gemini`, `~/.config/opencode`).
+
 ### Alternative: Claude Code CLI
 
 Prefer to skip the npm package entirely? Use the native plugin CLI:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.23.5",
+  "version": "1.24.1",
   "description": "A Claude Code plugin for systematic design improvement",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",
@@ -84,6 +84,7 @@
   "hooks": "hooks/hooks.json",
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.2.119",
+    "@clack/prompts": "^0.7.0",
     "@modelcontextprotocol/sdk": "^1.0.0"
   },
   "optionalDependencies": {

package/scripts/extract-changelog-section.cjs

@@ -28,7 +28,8 @@ if (!fs.existsSync(changelogPath)) {
 
 const body = fs.readFileSync(changelogPath, 'utf8').replace(/\r\n/g, '\n');
 const lines = body.split('\n');
-const headingRe = new RegExp(`^##\\s*\\[${version.replace(/\./g, '\\.')}\\]`);
+const escapedVersion = version.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const headingRe = new RegExp(`^##\\s*\\[${escapedVersion}\\]`);
 const nextHeadingRe = /^##\s*\[/;
 
 let capture = false;

package/scripts/install.cjs

@@ -2,153 +2,201 @@
 'use strict';
 
 // npx @hegemonart/get-design-done
-// One-command installer for the get-design-done Claude Code plugin.
+// Multi-runtime installer for the get-design-done plugin.
 //
-// Registers the github.com/hegemonart/get-design-done marketplace and enables
-// the plugin in ~/.claude/settings.json (or $CLAUDE_CONFIG_DIR/settings.json).
-// Claude Code fetches the plugin payload from the marketplace on next launch.
+// Runtime selection:
+//   • zero-flag in TTY      → @clack/prompts interactive multi-select
+//   • zero-flag in non-TTY  → defaults to --claude --global (back-compat)
+//   • any explicit flag     → scripted, no prompts
 //
-// Usage:
-//   npx @hegemonart/get-design-done           # install
-//   npx @hegemonart/get-design-done --dry-run # show what would change
-//   npx @hegemonart/get-design-done --help
-
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-
-const REPO = 'hegemonart/get-design-done';
-const MARKETPLACE_NAME = 'get-design-done';
-const PLUGIN_NAME = 'get-design-done';
-const ENABLED_KEY = `${PLUGIN_NAME}@${MARKETPLACE_NAME}`;
-
-const args = new Set(process.argv.slice(2));
-
-if (args.has('--help') || args.has('-h')) {
-  process.stdout.write(
-    [
-      'npx @hegemonart/get-design-done — install the plugin',
-      '',
-      'Registers the github.com/hegemonart/get-design-done marketplace and',
-      'enables the get-design-done plugin in your Claude Code settings.',
-      '',
-      'Flags:',
-      '  --dry-run    Print the diff without writing',
-      '  --help, -h   Show this message',
-      '',
-      'Environment:',
-      '  CLAUDE_CONFIG_DIR   Override the Claude config directory',
-      '                      (default: ~/.claude)',
-      '',
-      'After install, restart Claude Code to load the plugin.',
-      '',
-    ].join('\n'),
-  );
-  process.exit(0);
+// Per-runtime flags: --claude, --opencode, --gemini, --kilo, --codex,
+//   --copilot, --cursor, --windsurf, --antigravity, --augment, --trae,
+//   --qwen, --codebuddy, --cline. --all selects every runtime.
+//
+// Modifiers: --global (default) | --local; --uninstall; --dry-run;
+//   --config-dir <path>; --help / -h.
+
+const path = require('node:path');
+
+const { listRuntimes, listRuntimeIds } = require('./lib/install/runtimes.cjs');
+const { installRuntime, uninstallRuntime } = require('./lib/install/installer.cjs');
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  const flags = new Set();
+  let configDir = null;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--config-dir') {
+      configDir = args[++i] || null;
+      continue;
+    }
+    if (a.startsWith('--config-dir=')) {
+      configDir = a.slice('--config-dir='.length);
+      continue;
+    }
+    flags.add(a);
+  }
+  return { flags, configDir };
 }
 
-const DRY_RUN = args.has('--dry-run');
+function helpText() {
+  const ids = listRuntimes()
+    .map((r) => `  --${r.id.padEnd(12)} ${r.displayName}`)
+    .join('\n');
+  return [
+    'npx @hegemonart/get-design-done — install the plugin into one or more runtimes',
+    '',
+    'Zero-flag in a TTY launches the interactive multi-select.',
+    'Zero-flag in a non-TTY (CI, pipes) defaults to --claude --global.',
+    '',
+    'Per-runtime flags:',
+    ids,
+    '  --all           Select every runtime',
+    '',
+    'Modifiers:',
+    '  --global        Install at $HOME / $USERPROFILE level (default)',
+    '  --local         Install in current working directory',
+    '  --uninstall     Remove the plugin from selected runtimes',
+    '  --dry-run       Print the diff without writing',
+    '  --config-dir D  Override the config directory',
+    '  --help, -h      Show this message',
+    '',
+    'Environment overrides (per-runtime):',
+    '  CLAUDE_CONFIG_DIR, OPENCODE_CONFIG_DIR, GEMINI_CONFIG_DIR,',
+    '  CODEX_HOME, CURSOR_CONFIG_DIR, … (one per runtime)',
+    '',
+  ].join('\n');
+}
 
-function resolveConfigDir() {
-  if (process.env.CLAUDE_CONFIG_DIR && process.env.CLAUDE_CONFIG_DIR.trim()) {
-    return process.env.CLAUDE_CONFIG_DIR.trim();
+function runtimesFromFlags(flags) {
+  if (flags.has('--all')) return listRuntimeIds();
+  const picked = [];
+  for (const id of listRuntimeIds()) {
+    if (flags.has(`--${id}`)) picked.push(id);
   }
-  return path.join(os.homedir(), '.claude');
+  return picked;
 }
 
-function loadSettings(settingsPath) {
-  if (!fs.existsSync(settingsPath)) return {};
-  try {
-    const raw = fs.readFileSync(settingsPath, 'utf8');
-    if (!raw.trim()) return {};
-    return JSON.parse(raw);
-  } catch (err) {
-    process.stderr.write(
-      `get-design-done installer: cannot parse ${settingsPath} as JSON\n` +
-        `  ${err.message}\n` +
-        `  Fix the file manually or delete it, then re-run.\n`,
-    );
-    process.exit(1);
+async function pickRuntimesInteractively(opts) {
+  const { runInteractiveInstall, runInteractiveUninstall } = require('./lib/install/interactive.cjs');
+  if (opts.uninstall) {
+    return runInteractiveUninstall(opts);
   }
+  return runInteractiveInstall();
 }
 
-function mergeSettings(existing) {
-  const next = { ...existing };
-
-  const marketplaces = { ...(next.extraKnownMarketplaces || {}) };
-  const marketplaceEntry = {
-    source: { source: 'github', repo: REPO },
-  };
-  const marketplaceChanged =
-    JSON.stringify(marketplaces[MARKETPLACE_NAME]) !==
-    JSON.stringify(marketplaceEntry);
-  marketplaces[MARKETPLACE_NAME] = marketplaceEntry;
-  next.extraKnownMarketplaces = marketplaces;
-
-  const enabled = { ...(next.enabledPlugins || {}) };
-  const enabledChanged = enabled[ENABLED_KEY] !== true;
-  enabled[ENABLED_KEY] = true;
-  next.enabledPlugins = enabled;
-
-  return { next, changed: marketplaceChanged || enabledChanged };
+function resolveLocalConfigDir(runtime) {
+  return path.resolve(process.cwd(), runtime.configDirFallback);
 }
 
-function atomicWrite(target, contents) {
-  const tmp = `${target}.tmp-${process.pid}`;
-  fs.writeFileSync(tmp, contents, { encoding: 'utf8', mode: 0o600 });
-  fs.renameSync(tmp, target);
+function shouldUseInteractive(flags) {
+  // Any of these flags means "scripted mode":
+  //   per-runtime, --all, --uninstall (with explicit list), --help
+  if (flags.has('--all')) return false;
+  for (const id of listRuntimeIds()) {
+    if (flags.has(`--${id}`)) return false;
+  }
+  // Bare --uninstall (no runtime list) is itself a trigger for interactive
+  // select-which-to-remove flow, so it returns true.
+  return Boolean(process.stdout.isTTY) && Boolean(process.stdin.isTTY);
 }
 
-function main() {
-  const configDir = resolveConfigDir();
-  const settingsPath = path.join(configDir, 'settings.json');
+function summariseResults(results) {
+  const lines = [];
+  for (const r of results) {
+    const tag = r.dryRun ? '[dry-run] ' : '';
+    const status = r.action;
+    lines.push(`${tag}• ${r.runtime.padEnd(12)} ${status.padEnd(16)} ${r.path}`);
+    if (r.reason) lines.push(`    ${r.reason}`);
+  }
+  return lines.join('\n');
+}
 
-  if (!fs.existsSync(configDir)) {
-    if (DRY_RUN) {
-      process.stdout.write(
-        `[dry-run] would create ${configDir}\n`,
-      );
+async function main() {
+  const { flags, configDir } = parseArgs(process.argv);
+
+  if (flags.has('--help') || flags.has('-h')) {
+    process.stdout.write(helpText());
+    process.exit(0);
+  }
+
+  const dryRun = flags.has('--dry-run');
+  const uninstall = flags.has('--uninstall');
+  const local = flags.has('--local');
+  const explicitRuntimes = runtimesFromFlags(flags);
+
+  let runtimes = explicitRuntimes;
+  let location = local ? 'local' : 'global';
+
+  if (runtimes.length === 0) {
+    if (shouldUseInteractive(flags)) {
+      const opts = { uninstall };
+      const picked = await pickRuntimesInteractively(opts);
+      if (picked == null) {
+        process.exit(0);
+      }
+      runtimes = picked.runtimes;
+      if (picked.location) location = picked.location;
     } else {
-      fs.mkdirSync(configDir, { recursive: true });
+      // Non-TTY zero-flag fallback: back-compat with v1.23.5 behaviour.
+      runtimes = ['claude'];
+      location = local ? 'local' : 'global';
     }
   }
 
-  const existing = loadSettings(settingsPath);
-  const { next, changed } = mergeSettings(existing);
-  const formatted = `${JSON.stringify(next, null, 2)}\n`;
-
-  if (!changed) {
-    process.stdout.write(
-      `get-design-done is already registered in ${settingsPath}\n` +
-        `Nothing to do. Restart Claude Code if you haven't yet.\n`,
-    );
-    return;
+  const results = [];
+  const { getRuntime } = require('./lib/install/runtimes.cjs');
+  for (const id of runtimes) {
+    const runtime = getRuntime(id);
+    const opts = { dryRun };
+    if (configDir) {
+      opts.configDir = configDir;
+    } else if (location === 'local') {
+      opts.configDir = resolveLocalConfigDir(runtime);
+    }
+    const result = uninstall
+      ? uninstallRuntime(id, opts)
+      : installRuntime(id, opts);
+    results.push(result);
   }
 
-  if (DRY_RUN) {
+  const verb = uninstall ? 'uninstall' : 'install';
+  const allUnchanged = results.length > 0 && results.every((r) => r.action === 'unchanged');
+  if (allUnchanged && !dryRun) {
     process.stdout.write(
-      `[dry-run] would update ${settingsPath}\n` +
-        `  extraKnownMarketplaces["${MARKETPLACE_NAME}"] = { source: { source: "github", repo: "${REPO}" } }\n` +
-        `  enabledPlugins["${ENABLED_KEY}"] = true\n`,
+      [
+        `get-design-done is already registered (${runtimes.length} runtime(s) unchanged):`,
+        summariseResults(results),
+        '',
+        'Nothing to do. Restart the affected runtime(s) if you have not yet.',
+        '',
+      ].join('\n'),
     );
     return;
   }
-
-  atomicWrite(settingsPath, formatted);
-
   process.stdout.write(
     [
-      `✓ get-design-done registered in ${settingsPath}`,
-      `  marketplace: github:${REPO}`,
-      `  plugin:      ${ENABLED_KEY}`,
+      dryRun
+        ? `[dry-run] would ${verb} into ${runtimes.length} runtime(s):`
+        : `${verb} complete (${runtimes.length} runtime(s)):`,
+      summariseResults(results),
       '',
-      'Next steps:',
-      '  1. Restart Claude Code (or run /reload-plugins).',
-      '  2. Claude Code will fetch the plugin on first launch.',
-      '  3. Verify with: /plugin list',
+      uninstall
+        ? ''
+        : 'Restart the affected runtime(s) for the plugin to load.',
       '',
     ].join('\n'),
   );
 }
 
-main();
+main().catch((err) => {
+  if (err && err.code === 'EINSTALLER_BAD_JSON') {
+    process.stderr.write(`${err.message}\n`);
+  } else {
+    process.stderr.write(
+      `get-design-done installer error: ${err && err.stack ? err.stack : err}\n`,
+    );
+  }
+  process.exit(1);
+});

package/scripts/lib/install/config-dir.cjs

@@ -0,0 +1,55 @@
+'use strict';
+
+// Config-dir lookup chain for the get-design-done multi-runtime installer.
+//
+// Order of precedence (Phase 24 D-03):
+//   1. Explicit override (--config-dir <dir> from caller).
+//   2. Per-runtime env var (CLAUDE_CONFIG_DIR, OPENCODE_CONFIG_DIR, ...).
+//   3. POSIX/Windows fallback at $HOME / $USERPROFILE + the runtime's
+//      configDirFallback (e.g. ~/.claude, ~/.gemini, ~/.config/opencode).
+//
+// resolveConfigDir returns the absolute path the installer should target.
+// It does NOT verify the directory exists — that is the caller's job.
+
+const path = require('node:path');
+const os = require('node:os');
+
+const { getRuntime, listRuntimes } = require('./runtimes.cjs');
+
+function homeDir() {
+  return os.homedir();
+}
+
+function resolveConfigDir(runtimeId, opts) {
+  const runtime = getRuntime(runtimeId);
+  const overrides = (opts && opts.env) || process.env;
+  const explicit = opts && opts.configDir;
+
+  if (explicit && String(explicit).trim()) {
+    return path.resolve(String(explicit).trim());
+  }
+
+  const envValue = overrides[runtime.configDirEnv];
+  if (envValue && String(envValue).trim()) {
+    return path.resolve(String(envValue).trim());
+  }
+
+  const home = (opts && opts.home) || homeDir();
+  // configDirFallback may use POSIX separators (e.g. ".config/opencode") for
+  // cross-runtime portability — path.join + path.resolve normalises to the
+  // host platform's separator on output.
+  return path.resolve(path.join(home, ...runtime.configDirFallback.split('/')));
+}
+
+function resolveAllConfigDirs(opts) {
+  const out = {};
+  for (const runtime of listRuntimes()) {
+    out[runtime.id] = resolveConfigDir(runtime.id, opts);
+  }
+  return out;
+}
+
+module.exports = {
+  resolveConfigDir,
+  resolveAllConfigDirs,
+};

package/scripts/lib/install/installer.cjs

@@ -0,0 +1,244 @@
+'use strict';
+
+// Per-runtime install/uninstall orchestrator. Returns a structured Result
+// for every runtime touched so the caller can render a per-runtime summary.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { getRuntime } = require('./runtimes.cjs');
+const { resolveConfigDir } = require('./config-dir.cjs');
+const {
+  mergeClaudeSettings,
+  removeClaudeSettings,
+  buildAgentsFileContent,
+  isPluginOwned,
+} = require('./merge.cjs');
+
+function loadJsonOr(empty, filePath) {
+  if (!fs.existsSync(filePath)) return empty;
+  const raw = fs.readFileSync(filePath, 'utf8');
+  if (!raw.trim()) return empty;
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    const friendly = new Error(
+      `get-design-done installer: cannot parse ${filePath} as JSON\n  ${err.message}\n  Fix the file manually or delete it, then re-run.`,
+    );
+    friendly.code = 'EINSTALLER_BAD_JSON';
+    friendly.path = filePath;
+    throw friendly;
+  }
+}
+
+function atomicWrite(target, contents) {
+  const tmp = `${target}.tmp-${process.pid}`;
+  fs.writeFileSync(tmp, contents, { encoding: 'utf8', mode: 0o600 });
+  fs.renameSync(tmp, target);
+}
+
+function ensureDir(dir, dryRun) {
+  if (fs.existsSync(dir)) return false;
+  if (!dryRun) fs.mkdirSync(dir, { recursive: true });
+  return true;
+}
+
+function installRuntime(runtimeId, opts) {
+  const runtime = getRuntime(runtimeId);
+  const dryRun = Boolean(opts && opts.dryRun);
+  const configDir = resolveConfigDir(runtimeId, opts);
+
+  if (runtime.kind === 'claude-marketplace') {
+    return installClaudeMarketplace(runtime, configDir, dryRun);
+  }
+  if (runtime.kind === 'agents-md') {
+    return installAgentsMd(runtime, configDir, dryRun);
+  }
+  throw new Error(`Unsupported runtime kind: ${runtime.kind}`);
+}
+
+function uninstallRuntime(runtimeId, opts) {
+  const runtime = getRuntime(runtimeId);
+  const dryRun = Boolean(opts && opts.dryRun);
+  const configDir = resolveConfigDir(runtimeId, opts);
+
+  if (runtime.kind === 'claude-marketplace') {
+    return uninstallClaudeMarketplace(runtime, configDir, dryRun);
+  }
+  if (runtime.kind === 'agents-md') {
+    return uninstallAgentsMd(runtime, configDir, dryRun);
+  }
+  throw new Error(`Unsupported runtime kind: ${runtime.kind}`);
+}
+
+function installClaudeMarketplace(runtime, configDir, dryRun) {
+  const settingsPath = path.join(configDir, 'settings.json');
+  ensureDir(configDir, dryRun);
+  const existing = loadJsonOr({}, settingsPath);
+  const { next, changed } = mergeClaudeSettings(
+    existing,
+    runtime.marketplaceEntry,
+  );
+  if (!changed) {
+    return {
+      runtime: runtime.id,
+      path: settingsPath,
+      action: 'unchanged',
+      dryRun,
+    };
+  }
+  const formatted = `${JSON.stringify(next, null, 2)}\n`;
+  if (!dryRun) atomicWrite(settingsPath, formatted);
+  return {
+    runtime: runtime.id,
+    path: settingsPath,
+    action: fs.existsSync(settingsPath) ? 'updated' : 'created',
+    dryRun,
+  };
+}
+
+function uninstallClaudeMarketplace(runtime, configDir, dryRun) {
+  const settingsPath = path.join(configDir, 'settings.json');
+  if (!fs.existsSync(settingsPath)) {
+    return {
+      runtime: runtime.id,
+      path: settingsPath,
+      action: 'unchanged',
+      dryRun,
+    };
+  }
+  const existing = loadJsonOr({}, settingsPath);
+  const { next, changed } = removeClaudeSettings(
+    existing,
+    runtime.marketplaceEntry,
+  );
+  if (!changed) {
+    return {
+      runtime: runtime.id,
+      path: settingsPath,
+      action: 'unchanged',
+      dryRun,
+    };
+  }
+  const formatted = `${JSON.stringify(next, null, 2)}\n`;
+  if (!dryRun) atomicWrite(settingsPath, formatted);
+  return {
+    runtime: runtime.id,
+    path: settingsPath,
+    action: 'removed',
+    dryRun,
+  };
+}
+
+function installAgentsMd(runtime, configDir, dryRun) {
+  ensureDir(configDir, dryRun);
+  const fileName = (runtime.files && runtime.files[0]) || 'AGENTS.md';
+  const target = path.join(configDir, fileName);
+  const desired = buildAgentsFileContent(runtime);
+
+  if (fs.existsSync(target)) {
+    const current = fs.readFileSync(target, 'utf8');
+    if (current === desired) {
+      return {
+        runtime: runtime.id,
+        path: target,
+        action: 'unchanged',
+        dryRun,
+      };
+    }
+    if (!isPluginOwned(current)) {
+      // Don't clobber unrelated user-authored AGENTS.md / GEMINI.md.
+      return {
+        runtime: runtime.id,
+        path: target,
+        action: 'skipped-foreign',
+        dryRun,
+        reason: `Existing ${fileName} was not authored by this plugin; refusing to overwrite. Move it aside or pass --force (not yet supported) to replace.`,
+      };
+    }
+    if (!dryRun) atomicWrite(target, desired);
+    return {
+      runtime: runtime.id,
+      path: target,
+      action: 'updated',
+      dryRun,
+    };
+  }
+  if (!dryRun) atomicWrite(target, desired);
+  return {
+    runtime: runtime.id,
+    path: target,
+    action: 'created',
+    dryRun,
+  };
+}
+
+function uninstallAgentsMd(runtime, configDir, dryRun) {
+  const fileName = (runtime.files && runtime.files[0]) || 'AGENTS.md';
+  const target = path.join(configDir, fileName);
+  if (!fs.existsSync(target)) {
+    return {
+      runtime: runtime.id,
+      path: target,
+      action: 'unchanged',
+      dryRun,
+    };
+  }
+  const current = fs.readFileSync(target, 'utf8');
+  if (!isPluginOwned(current)) {
+    return {
+      runtime: runtime.id,
+      path: target,
+      action: 'skipped-foreign',
+      dryRun,
+      reason: `Existing ${fileName} was not authored by this plugin; not removing.`,
+    };
+  }
+  if (!dryRun) fs.unlinkSync(target);
+  return {
+    runtime: runtime.id,
+    path: target,
+    action: 'removed',
+    dryRun,
+  };
+}
+
+function detectInstalled(opts) {
+  const installed = [];
+  const { listRuntimes } = require('./runtimes.cjs');
+  for (const runtime of listRuntimes()) {
+    const configDir = resolveConfigDir(runtime.id, opts);
+    if (runtime.kind === 'claude-marketplace') {
+      const settingsPath = path.join(configDir, 'settings.json');
+      if (!fs.existsSync(settingsPath)) continue;
+      try {
+        const data = loadJsonOr({}, settingsPath);
+        const key = `${runtime.marketplaceEntry.pluginName}@${runtime.marketplaceEntry.name}`;
+        if (data.enabledPlugins && data.enabledPlugins[key] === true) {
+          installed.push(runtime.id);
+        }
+      } catch {
+        // ignore
+      }
+      continue;
+    }
+    if (runtime.kind === 'agents-md') {
+      const fileName = (runtime.files && runtime.files[0]) || 'AGENTS.md';
+      const target = path.join(configDir, fileName);
+      if (!fs.existsSync(target)) continue;
+      try {
+        const content = fs.readFileSync(target, 'utf8');
+        if (isPluginOwned(content)) installed.push(runtime.id);
+      } catch {
+        // ignore
+      }
+    }
+  }
+  return installed;
+}
+
+module.exports = {
+  installRuntime,
+  uninstallRuntime,
+  detectInstalled,
+};

package/scripts/lib/install/interactive.cjs

@@ -0,0 +1,142 @@
+'use strict';
+
+// @clack/prompts wrapper for the multi-runtime installer.
+//
+// runInteractiveInstall walks the user through three steps:
+//   1. Multi-select runtimes (with [a] all shortcut).
+//   2. Radio: Global vs Local install.
+//   3. Confirmation summary.
+//
+// runInteractiveUninstall walks the user through:
+//   1. Multi-select detected-installed runtimes.
+//   2. Confirmation summary.
+//
+// Both return null when the user cancels at any step (ESC / ctrl-c). The
+// caller is responsible for translating null into a "cancelled" exit-0
+// message.
+
+const { listRuntimes, getRuntime } = require('./runtimes.cjs');
+const { detectInstalled } = require('./installer.cjs');
+
+let clackCache = null;
+function loadClack() {
+  if (clackCache) return clackCache;
+  try {
+    clackCache = require('@clack/prompts');
+  } catch (err) {
+    throw new Error(
+      [
+        'Interactive install requires @clack/prompts.',
+        'Install it (npm i @clack/prompts) or pass an explicit runtime flag',
+        '(e.g. --claude --global) to skip the interactive session.',
+        `Original error: ${err && err.message}`,
+      ].join('\n'),
+    );
+  }
+  return clackCache;
+}
+
+function isCancel(p, value) {
+  return typeof p.isCancel === 'function' ? p.isCancel(value) : false;
+}
+
+async function runInteractiveInstall() {
+  const p = loadClack();
+
+  p.intro('get-design-done — multi-runtime installer');
+
+  const runtimes = listRuntimes();
+  const options = runtimes.map((r) => ({
+    value: r.id,
+    label: r.displayName,
+    hint: r.kind === 'claude-marketplace' ? 'marketplace registration' : `drops ${r.files[0] || 'AGENTS.md'}`,
+  }));
+
+  const picked = await p.multiselect({
+    message: 'Pick the runtimes to install into (space to toggle, [a] all):',
+    options,
+    required: true,
+  });
+  if (isCancel(p, picked)) {
+    p.cancel('Install cancelled.');
+    return null;
+  }
+
+  const location = await p.select({
+    message: 'Install location:',
+    options: [
+      { value: 'global', label: 'Global ($HOME-level config dir)' },
+      { value: 'local', label: 'Local (current working directory)' },
+    ],
+    initialValue: 'global',
+  });
+  if (isCancel(p, location)) {
+    p.cancel('Install cancelled.');
+    return null;
+  }
+
+  const summary = picked
+    .map((id) => `  • ${getRuntime(id).displayName}`)
+    .join('\n');
+  const confirmed = await p.confirm({
+    message: `Install into:\n${summary}\nLocation: ${location}\n\nProceed?`,
+    initialValue: true,
+  });
+  if (isCancel(p, confirmed) || confirmed === false) {
+    p.cancel('Install cancelled.');
+    return null;
+  }
+
+  return { runtimes: picked, location };
+}
+
+async function runInteractiveUninstall(opts) {
+  const p = loadClack();
+
+  p.intro('get-design-done — uninstall');
+
+  const installed = detectInstalled(opts || {});
+  if (installed.length === 0) {
+    p.note(
+      'No runtimes appear to have the get-design-done plugin installed.',
+      'Nothing to do.',
+    );
+    p.outro('Done.');
+    return null;
+  }
+
+  const options = installed.map((id) => ({
+    value: id,
+    label: getRuntime(id).displayName,
+    hint: 'installed',
+  }));
+
+  const picked = await p.multiselect({
+    message: 'Pick the runtimes to uninstall from:',
+    options,
+    required: true,
+  });
+  if (isCancel(p, picked)) {
+    p.cancel('Uninstall cancelled.');
+    return null;
+  }
+
+  const summary = picked
+    .map((id) => `  • ${getRuntime(id).displayName}`)
+    .join('\n');
+  const confirmed = await p.confirm({
+    message: `Uninstall from:\n${summary}\n\nProceed?`,
+    initialValue: true,
+  });
+  if (isCancel(p, confirmed) || confirmed === false) {
+    p.cancel('Uninstall cancelled.');
+    return null;
+  }
+
+  return { runtimes: picked };
+}
+
+module.exports = {
+  runInteractiveInstall,
+  runInteractiveUninstall,
+};

package/scripts/lib/install/merge.cjs

@@ -0,0 +1,103 @@
+'use strict';
+
+// Pure merge / mutation helpers for the multi-runtime installer.
+//
+// mergeClaudeSettings — extracted from the v1.23.5 entrypoint. Adds a
+//   marketplace registration + flips enabledPlugins[<plugin>@<marketplace>].
+//
+// removeClaudeSettings — inverse: removes the marketplace + the
+//   enabledPlugins entry. Leaves untouched anything we did not write.
+//
+// agentsFileFingerprint — first-line marker we drop into every AGENTS.md /
+//   GEMINI.md write so uninstall can confirm the file is plugin-owned.
+
+const PLUGIN_FINGERPRINT = 'get-design-done plugin instructions';
+
+function mergeClaudeSettings(existing, marketplaceEntry) {
+  const next = { ...(existing || {}) };
+
+  const marketplaces = { ...(next.extraKnownMarketplaces || {}) };
+  const desired = {
+    source: { source: 'github', repo: marketplaceEntry.repo },
+  };
+  const marketplaceChanged =
+    JSON.stringify(marketplaces[marketplaceEntry.name]) !==
+    JSON.stringify(desired);
+  marketplaces[marketplaceEntry.name] = desired;
+  next.extraKnownMarketplaces = marketplaces;
+
+  const enabled = { ...(next.enabledPlugins || {}) };
+  const enabledKey = `${marketplaceEntry.pluginName}@${marketplaceEntry.name}`;
+  const enabledChanged = enabled[enabledKey] !== true;
+  enabled[enabledKey] = true;
+  next.enabledPlugins = enabled;
+
+  return { next, changed: marketplaceChanged || enabledChanged };
+}
+
+function removeClaudeSettings(existing, marketplaceEntry) {
+  const next = { ...(existing || {}) };
+
+  const marketplaces = { ...(next.extraKnownMarketplaces || {}) };
+  const marketplaceChanged = Object.prototype.hasOwnProperty.call(
+    marketplaces,
+    marketplaceEntry.name,
+  );
+  delete marketplaces[marketplaceEntry.name];
+  if (Object.keys(marketplaces).length > 0) {
+    next.extraKnownMarketplaces = marketplaces;
+  } else if ('extraKnownMarketplaces' in next) {
+    delete next.extraKnownMarketplaces;
+  }
+
+  const enabled = { ...(next.enabledPlugins || {}) };
+  const enabledKey = `${marketplaceEntry.pluginName}@${marketplaceEntry.name}`;
+  const enabledChanged = Object.prototype.hasOwnProperty.call(
+    enabled,
+    enabledKey,
+  );
+  delete enabled[enabledKey];
+  if (Object.keys(enabled).length > 0) {
+    next.enabledPlugins = enabled;
+  } else if ('enabledPlugins' in next) {
+    delete next.enabledPlugins;
+  }
+
+  return { next, changed: marketplaceChanged || enabledChanged };
+}
+
+function agentsFileFingerprint() {
+  return PLUGIN_FINGERPRINT;
+}
+
+function buildAgentsFileContent(runtime, payloadHeader) {
+  const lines = [
+    `<!-- ${PLUGIN_FINGERPRINT} -->`,
+    '',
+    `# ${runtime.displayName} — get-design-done plugin`,
+    '',
+    'This file was written by `npx @hegemonart/get-design-done`. It loads',
+    'the GDD plugin instructions for this runtime. Re-run the installer to',
+    'refresh; run `npx @hegemonart/get-design-done --uninstall` to remove.',
+    '',
+    payloadHeader || '',
+    '',
+    `Plugin repository: https://github.com/hegemonart/get-design-done`,
+    '',
+  ];
+  return lines.join('\n');
+}
+
+function isPluginOwned(content) {
+  if (!content || typeof content !== 'string') return false;
+  return content.includes(PLUGIN_FINGERPRINT);
+}
+
+module.exports = {
+  mergeClaudeSettings,
+  removeClaudeSettings,
+  agentsFileFingerprint,
+  buildAgentsFileContent,
+  isPluginOwned,
+  PLUGIN_FINGERPRINT,
+};

package/scripts/lib/install/runtimes.cjs

@@ -0,0 +1,172 @@
+'use strict';
+
+// Per-runtime install matrix for the get-design-done plugin.
+//
+// Each entry is pure data describing how to install / uninstall the plugin
+// into one runtime. The 14 runtimes listed below are roadmap-locked
+// (Phase 24 D-02). Two `kind`s exist:
+//
+//   - `claude-marketplace` — register a marketplace entry + flip
+//     `enabledPlugins[<name>@<marketplace>]` in settings.json. Today only
+//     Claude Code uses this.
+//
+//   - `agents-md` — drop a runtime-specific instructions file (AGENTS.md /
+//     GEMINI.md) into the runtime's config directory. Most modern AI coding
+//     CLIs follow this convention.
+//
+// Adding a new runtime: append to RUNTIMES below, append the same id to the
+// alphabetised baseline at test-fixture/baselines/phase-24/runtimes.txt.
+
+const REPO = 'hegemonart/get-design-done';
+const MARKETPLACE_NAME = 'get-design-done';
+const PLUGIN_NAME = 'get-design-done';
+
+const RUNTIMES = Object.freeze([
+  {
+    id: 'claude',
+    displayName: 'Claude Code',
+    configDirEnv: 'CLAUDE_CONFIG_DIR',
+    configDirFallback: '.claude',
+    kind: 'claude-marketplace',
+    files: [],
+    marketplaceEntry: {
+      name: MARKETPLACE_NAME,
+      pluginName: PLUGIN_NAME,
+      repo: REPO,
+    },
+  },
+  {
+    id: 'opencode',
+    displayName: 'OpenCode',
+    configDirEnv: 'OPENCODE_CONFIG_DIR',
+    configDirFallback: '.config/opencode',
+    kind: 'agents-md',
+    files: ['AGENTS.md'],
+  },
+  {
+    id: 'gemini',
+    displayName: 'Gemini CLI',
+    configDirEnv: 'GEMINI_CONFIG_DIR',
+    configDirFallback: '.gemini',
+    kind: 'agents-md',
+    files: ['GEMINI.md'],
+  },
+  {
+    id: 'kilo',
+    displayName: 'Kilo Code',
+    configDirEnv: 'KILO_CONFIG_DIR',
+    configDirFallback: '.kilo',
+    kind: 'agents-md',
+    files: ['AGENTS.md'],
+  },
+  {
+    id: 'codex',
+    displayName: 'OpenAI Codex CLI',
+    configDirEnv: 'CODEX_HOME',
+    configDirFallback: '.codex',
+    kind: 'agents-md',
+    files: ['AGENTS.md'],
+  },
+  {
+    id: 'copilot',
+    displayName: 'GitHub Copilot CLI',
+    configDirEnv: 'COPILOT_CONFIG_DIR',
+    configDirFallback: '.copilot',
+    kind: 'agents-md',
+    files: ['AGENTS.md'],
+  },
+  {
+    id: 'cursor',
+    displayName: 'Cursor',
+    configDirEnv: 'CURSOR_CONFIG_DIR',
+    configDirFallback: '.cursor',
+    kind: 'agents-md',
+    files: ['AGENTS.md'],
+  },
+  {
+    id: 'windsurf',
+    displayName: 'Windsurf',
+    configDirEnv: 'WINDSURF_CONFIG_DIR',
+    configDirFallback: '.windsurf',
+    kind: 'agents-md',
+    files: ['AGENTS.md'],
+  },
+  {
+    id: 'antigravity',
+    displayName: 'Antigravity',
+    configDirEnv: 'ANTIGRAVITY_CONFIG_DIR',
+    configDirFallback: '.antigravity',
+    kind: 'agents-md',
+    files: ['AGENTS.md'],
+  },
+  {
+    id: 'augment',
+    displayName: 'Augment',
+    configDirEnv: 'AUGMENT_CONFIG_DIR',
+    configDirFallback: '.augment',
+    kind: 'agents-md',
+    files: ['AGENTS.md'],
+  },
+  {
+    id: 'trae',
+    displayName: 'Trae',
+    configDirEnv: 'TRAE_CONFIG_DIR',
+    configDirFallback: '.trae',
+    kind: 'agents-md',
+    files: ['AGENTS.md'],
+  },
+  {
+    id: 'qwen',
+    displayName: 'Qwen Code',
+    configDirEnv: 'QWEN_CONFIG_DIR',
+    configDirFallback: '.qwen',
+    kind: 'agents-md',
+    files: ['AGENTS.md'],
+  },
+  {
+    id: 'codebuddy',
+    displayName: 'CodeBuddy',
+    configDirEnv: 'CODEBUDDY_CONFIG_DIR',
+    configDirFallback: '.codebuddy',
+    kind: 'agents-md',
+    files: ['AGENTS.md'],
+  },
+  {
+    id: 'cline',
+    displayName: 'Cline',
+    configDirEnv: 'CLINE_CONFIG_DIR',
+    configDirFallback: '.cline',
+    kind: 'agents-md',
+    files: ['AGENTS.md'],
+  },
+]);
+
+const BY_ID = new Map(RUNTIMES.map((r) => [r.id, r]));
+
+function getRuntime(id) {
+  const r = BY_ID.get(id);
+  if (!r) {
+    throw new RangeError(
+      `Unknown runtime "${id}". Known: ${[...BY_ID.keys()].join(', ')}`,
+    );
+  }
+  return r;
+}
+
+function listRuntimes() {
+  return RUNTIMES;
+}
+
+function listRuntimeIds() {
+  return RUNTIMES.map((r) => r.id);
+}
+
+module.exports = {
+  RUNTIMES,
+  REPO,
+  MARKETPLACE_NAME,
+  PLUGIN_NAME,
+  getRuntime,
+  listRuntimes,
+  listRuntimeIds,
+};

package/scripts/lib/iteration-budget.cjs

@@ -21,7 +21,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 
-const { acquire } = require('./lockfile.cjs');
+const { acquire, renameWithRetry } = require('./lockfile.cjs');
 
 const STATE_PATH_REL = path.join('.design', 'iteration-budget.json');
 const DEFAULT_BUDGET = 50;
@@ -82,7 +82,7 @@ async function writeStateAtomic(state) {
     const merged = state.mergeFn ? state.mergeFn(latest || state.seed) : state.seed;
     const tmp = `${p}.tmp.${process.pid}.${Date.now()}`;
     fs.writeFileSync(tmp, JSON.stringify(merged, null, 2) + '\n', 'utf8');
-    fs.renameSync(tmp, p);
+    await renameWithRetry(tmp, p);
     return merged;
   } finally {
     await release();

package/scripts/lib/lockfile.cjs

@@ -76,9 +76,14 @@ async function acquire(path, opts) {
       if (existing === null) continue;
 
       const parsed = parseLock(existing);
-      if (parsed === null || isStale(parsed, staleMs)) {
-        // Clear stale/garbage lock; race-tolerant — if it's already gone
-        // we'll just get ENOENT, no-op.
+      // Only clear when we're confident the lock is stale: the payload
+      // parses AND the PID/age check says so. An unparseable payload is
+      // treated as fresh — on Windows, AV/indexer can transiently deny
+      // reads (EACCES/EPERM/EBUSY), and clearing under that condition
+      // would let two writers race and lose increments.
+      if (parsed !== null && isStale(parsed, staleMs)) {
+        // Clear stale lock; race-tolerant — if it's already gone we get
+        // ENOENT, no-op.
         try { fs.unlinkSync(lockPath); } catch { /* ignore */ }
         continue;
       }
@@ -174,4 +179,23 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-module.exports = { acquire };
+/**
+ * `fs.renameSync` wrapper that retries once on Windows EPERM/EBUSY/EACCES.
+ * AV scanners and the file-indexer can briefly hold a destination open
+ * after another process closed it, causing rename to fail even when the
+ * advisory lock is correctly held.
+ *
+ * Mirrors the inline retry in scripts/lib/gdd-state/index.ts mutate().
+ */
+async function renameWithRetry(from, to) {
+  try {
+    fs.renameSync(from, to);
+  } catch (err) {
+    const code = err && typeof err === 'object' ? err.code : undefined;
+    if (code !== 'EPERM' && code !== 'EBUSY' && code !== 'EACCES') throw err;
+    await sleep(50);
+    fs.renameSync(from, to);
+  }
+}
+
+module.exports = { acquire, renameWithRetry };

package/scripts/lib/rate-guard.cjs

@@ -30,7 +30,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 
-const { acquire } = require('./lockfile.cjs');
+const { acquire, renameWithRetry } = require('./lockfile.cjs');
 
 const STATE_DIR_REL = path.join('.design', 'rate-limits');
 const LOCK_MAX_WAIT_MS = 3_000;
@@ -203,7 +203,7 @@ async function atomicWriteState(absPath, state) {
   try {
     const tmp = `${absPath}.tmp.${process.pid}.${Date.now()}`;
     fs.writeFileSync(tmp, JSON.stringify(state, null, 2) + '\n', 'utf8');
-    fs.renameSync(tmp, absPath);
+    await renameWithRetry(tmp, absPath);
   } finally {
     await release();
   }