@hegemonart/get-design-done 1.20.0 → 1.21.0

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.20.0"
+    "version": "1.21.0"
   },
   "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.20.0",
+      "version": "1.21.0",
       "author": {
         "name": "hegemonart"
       },
@@ -62,16 +62,13 @@
         "cost-optimization",
         "cache-aware",
         "budget",
-        "component-specs",
-        "design-system-benchmarks",
-        "component-conformance",
-        "convergence-detector",
-        "i18n",
-        "user-research",
-        "information-architecture",
-        "form-patterns",
-        "data-viz",
-        "platforms"
+        "headless",
+        "cli",
+        "codex",
+        "gemini",
+        "mcp",
+        "parallel-agents",
+        "agent-sdk"
       ]
     }
   ]

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "get-design-done",
   "short_name": "gdd",
-  "version": "1.20.0",
+  "version": "1.21.0",
   "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",
@@ -53,36 +53,13 @@
     "cost-optimization",
     "cache-aware",
     "budget",
-    "iconography",
-    "brand-voice",
-    "performance-budget",
-    "framer-motion",
-    "motion-design",
-    "micro-polish",
-    "surfaces",
-    "make-interfaces-feel-better",
-    "palette-catalog",
-    "style-vocabulary",
-    "industry-palettes",
-    "ui-style-vocabulary",
-    "variable-fonts",
-    "container-queries",
-    "view-transitions",
-    "motion-vocabulary",
-    "motion-easings",
-    "transition-taxonomy",
-    "gesture-mechanics",
-    "clip-path-animation",
-    "component-specs",
-    "design-system-benchmarks",
-    "component-conformance",
-    "convergence-detector",
-    "i18n",
-    "user-research",
-    "information-architecture",
-    "form-patterns",
-    "data-viz",
-    "platforms"
+    "headless",
+    "cli",
+    "codex",
+    "gemini",
+    "mcp",
+    "parallel-agents",
+    "agent-sdk"
   ],
   "skills": [
     "./skills/"

package/CHANGELOG.md

@@ -4,6 +4,84 @@ All notable changes to get-design-done are documented here. Versions follow [sem
 
 ---
 
+## [1.21.0] — 2026-04-24
+
+Phase 21 GDD SDK Headless milestone — the plugin now runs unchanged on Claude Code, OpenAI Codex CLI, and Gemini CLI, and ships a full `gdd-sdk` CLI that executes the design pipeline without a harness. 12 plans (21-01 through 21-12), 50+ commits, 936 tests.
+
+### Added
+
+- **Headless SDK** — new `bin/gdd-sdk` CLI that runs the full design pipeline
+  without Claude Code. Subcommands: `run`, `stage <name>`, `query <op>`,
+  `audit`, `init`. Publishes as `gdd-sdk` in `package.json` `bin`. See
+  `docs/HEADLESS.md` (Phase 23 deliverable) for CI integration guidance.
+- **Session runner** (`scripts/lib/session-runner/`) — typed wrapper around
+  `@anthropic-ai/claude-agent-sdk` with USD/token budget caps, turn caps,
+  transcript capture, structured error mapping via `gdd-errors` taxonomy.
+  Emits `session.started`, `session.completed`, `session.budget_exceeded`
+  events on the shared event stream.
+- **Context engine** (`scripts/lib/context-engine/`) — per-stage file
+  manifest + markdown-aware truncation that preserves frontmatter, every
+  heading, and the first paragraph of each section for files larger than
+  8 KiB. Keeps session prompts within budget without dropping load-bearing
+  context.
+- **Tool scoping** (`scripts/lib/tool-scoping/`) — per-stage allowed-tools
+  enforcement at session creation. Verify is read-only; Explore adds web;
+  Design permits shell mutations. Per-agent frontmatter overrides via
+  `parseAgentTools()` for agent-level deviations.
+- **Structured logger** (`scripts/lib/logger/`) — leveled (debug/info/warn/
+  error) with JSONL output in headless mode, ANSI-colored stderr in
+  interactive mode. `warn`/`error` also emit `ErrorEvent` on the event
+  stream for CI consumers.
+- **Pipeline runner** (`scripts/lib/pipeline-runner/`) — brief → explore →
+  plan → design → verify state machine with retry-once, halt logic,
+  human-gate callbacks, config-driven step skipping. Emits
+  `pipeline.started`, `pipeline.completed`, `pipeline.halted`.
+- **Explore parallel runner** (`scripts/lib/explore-parallel-runner/`) —
+  4 mappers (token, component-taxonomy, a11y, visual-hierarchy) concurrent
+  with streaming synthesizer. Honors `parallelism_safe` agent frontmatter
+  for opt-in isolation.
+- **Discuss parallel runner** (`scripts/lib/discuss-parallel-runner/`) —
+  N discussant variants (user-journey, technical-constraint, brand-fit,
+  accessibility) concurrent, aggregator dedupes and clusters questions.
+- **`gdd-sdk init`** (`scripts/lib/init-runner/`) — new-project bootstrap
+  spawning 4 parallel researchers (design-system-audit, brand-context,
+  accessibility-baseline, competitive-references) + synthesizer producing
+  `.design/DESIGN-CONTEXT.md` draft.
+- **Cross-harness portability** (`scripts/lib/harness/`) — the plugin now
+  runs unchanged on Claude Code, OpenAI Codex CLI, and Gemini CLI. Ships
+  `reference/codex-tools.md`, `reference/gemini-tools.md`, `AGENTS.md`
+  (Codex), `GEMINI.md` (Gemini). The `gdd-state` MCP server works on all
+  three harnesses; harness detection is runtime-driven.
+- **E2E headless integration test** — `tests/e2e-headless.test.ts` with a
+  dry-run variant (always runs) and a live variant (gated on
+  `ANTHROPIC_API_KEY`). CI workflow gains an `e2e-headless` job.
+- **Phase 21 regression baseline** at `test-fixture/baselines/phase-21/` —
+  directory list, module list, agent list, connections list, CLI
+  subcommand list, event-type list. Enforced by
+  `tests/phase-21-baseline.test.cjs`.
+
+### Changed
+
+- `@anthropic-ai/claude-agent-sdk` added as a runtime dependency (was
+  previously only referenced in docs).
+- `package.json` `bin` now exports `gdd-sdk` in addition to
+  `get-design-done` and `gdd-state-mcp`.
+- `package.json` `files` adds `bin/` to the publish include list so the
+  `gdd-sdk` trampoline ships with the npm package.
+- `package.json` `keywords` expanded with headless / CLI / cross-harness
+  tokens (`headless`, `cli`, `codex`, `gemini`, `mcp`, `parallel-agents`,
+  `agent-sdk`) for npm search surface.
+
+### Infrastructure
+
+- New regression baseline at `test-fixture/baselines/phase-21/`.
+- CI workflow gains an `e2e-headless` job (dry-run on every PR; live on
+  main-branch push with `ANTHROPIC_API_KEY` secret).
+- `tests/semver-compare.test.cjs` `OFF_CADENCE_VERSIONS` now includes
+  `1.21.0` as the second off-cadence minor bump after `1.20.0`.
+
+---
+
 ## [1.20.0] — 2026-04-24
 
 Phase 20 SDK foundation milestone — the shift from "design pipeline" to "typed SDK + MCP server + resilience primitives + event stream". 16 plans (20-00 through 20-15), 50+ commits, 645+ tests.

package/README.md

@@ -29,7 +29,7 @@ npx @hegemonart/get-design-done@latest
 
 <br>
 
-[Why I Built This](#why-i-built-this) · [How It Works](#how-it-works) · [Canvas Tools](#ai-native-canvas-tools) · [Component Generators](#component-generators) · [Commands](#commands) · [Connections](#connections) · [Why It Works](#why-it-works)
+[Why I Built This](#why-i-built-this) · [How It Works](#how-it-works) · [Headless SDK](#headless-sdk) · [Canvas Tools](#ai-native-canvas-tools) · [Component Generators](#component-generators) · [Commands](#commands) · [Connections](#connections) · [Why It Works](#why-it-works)
 
 </div>
 
@@ -104,17 +104,27 @@ 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.20.0
+## What's New in v1.21.0
 
-**Resilience primitives** (headline upgrade) — the pipeline now survives Anthropic API rate limits, 429 responses, and context-overflow errors without manual restart. New modules: jittered backoff, rate-guard, error-classifier, iteration-budget. See [`reference/error-recovery.md`](reference/error-recovery.md) for the recovery protocol. Connection probes and long-running loops use these primitives instead of fixed sleeps.
+**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.
 
-**Typed state core** — `.design/STATE.md` mutations are now lockfile-safe. Parallel executors can concurrently update `task_progress` and `<blockers>` on the same file with zero corruption — validated by a 4-way race-condition test (2000 concurrent ops, <60s). The legacy `Read → regex → Write` pattern is deprecated in favor of the typed API.
+**Parallel researchers** — four new runners execute concurrent specialized agents with a streaming synthesizer: `explore-parallel-runner` (4 mappers: token, component-taxonomy, a11y, visual-hierarchy), `discuss-parallel-runner` (N discussants: user-journey, technical-constraint, brand-fit, accessibility), and `init-runner` (4 researchers for `gdd-sdk init` bootstrap). A `pipeline-runner` state machine orchestrates brief → explore → plan → design → verify with retry-once, halt logic, and human-gate callbacks.
 
-**`gdd-state` MCP server** — 11 typed tools (`gdd_state__get`, `__update_progress`, `__transition_stage`, `__add_blocker`, `__resolve_blocker`, `__add_decision`, `__add_must_have`, `__set_status`, `__checkpoint`, `__probe_connections`, `__frontmatter_update`) replace ad-hoc STATE.md edits. Every mutation emits a typed event to `.design/telemetry/events.jsonl`, giving downstream consumers a structured audit trail next to the existing `costs.jsonl` cost stream.
+**Cross-harness portability** — the plugin runs unchanged on Claude Code, OpenAI Codex CLI, and Gemini CLI. Codex auto-loads [`AGENTS.md`](AGENTS.md); Gemini auto-loads [`GEMINI.md`](GEMINI.md). Tool-name translations live in [`reference/codex-tools.md`](reference/codex-tools.md) and [`reference/gemini-tools.md`](reference/gemini-tools.md). The `gdd-state` MCP server works on all three harnesses.
 
-**TypeScript foundation** — `tsc --noEmit` typechecks the whole SDK; JSON schemas codegen to `reference/schemas/generated.d.ts`; hooks + Tier-1 scripts migrated to `.ts` and executed directly via Node 22 `--experimental-strip-types` (no bundler step).
+**Session primitives** — `session-runner` (typed wrapper around `@anthropic-ai/claude-agent-sdk` with USD/token budget caps, turn caps, transcript capture), `context-engine` (per-stage file manifest + markdown-aware truncation preserving frontmatter, headings, and first paragraph of each section), `tool-scoping` (per-stage allowed-tools enforcement with per-agent frontmatter overrides), and a structured `logger` (leveled, JSONL in headless mode, ANSI-colored in interactive mode).
 
-**Prompt sanitizer** — strips interactive-only constructs (AskUserQuestion, STOP, `/gdd:` slash commands) from skill bodies. Preparatory work for headless-runner support.
+**E2E headless integration test** — `tests/e2e-headless.test.ts` with a dry-run variant (always runs) and a live variant gated on `ANTHROPIC_API_KEY`. CI gains an `e2e-headless` job.
+
+### Previously in v1.20.0
+
+**Resilience primitives** — the pipeline survives Anthropic API rate limits, 429 responses, and context-overflow errors without manual restart. Modules: jittered backoff, rate-guard, error-classifier, iteration-budget. See [`reference/error-recovery.md`](reference/error-recovery.md).
+
+**Typed state core** — `.design/STATE.md` mutations are lockfile-safe. Parallel executors concurrently update `task_progress` and `<blockers>` on the same file with zero corruption (validated by 4-way race-condition test, 2000 concurrent ops, <60s).
+
+**`gdd-state` MCP server** — 11 typed tools (`gdd_state__get`, `__update_progress`, `__transition_stage`, `__add_blocker`, `__resolve_blocker`, `__add_decision`, `__add_must_have`, `__set_status`, `__checkpoint`, `__probe_connections`, `__frontmatter_update`) replace ad-hoc STATE.md edits. Every mutation emits a typed event to `.design/telemetry/events.jsonl`.
+
+**TypeScript foundation** — `tsc --noEmit` typechecks the whole SDK; JSON schemas codegen to `reference/schemas/generated.d.ts`; hooks + Tier-1 scripts migrated to `.ts` and executed directly via Node 22 `--experimental-strip-types`.
 
 ---
 
@@ -490,6 +500,37 @@ The watcher writes `.design/authority-report.md` — new entries classified into
 
 ---
 
+## Headless SDK
+
+Run the full GDD pipeline without Claude Code:
+
+```bash
+npx gdd-sdk init                      # bootstrap a new project
+npx gdd-sdk run                       # full pipeline (brief → verify)
+npx gdd-sdk stage explore --parallel  # single stage with parallel mappers
+npx gdd-sdk query position            # typed STATE.md read
+npx gdd-sdk audit --baseline <dir>    # regression check
+```
+
+Requires Node 22+ and an `ANTHROPIC_API_KEY`. Works on any CI runner.
+
+Internally the SDK stitches together the Phase-21 runner modules:
+`session-runner` (budget + turn cap + transcript), `context-engine` (per-stage
+file manifest + markdown truncation), `tool-scoping` (per-stage allowed-tools),
+`pipeline-runner` (brief → verify state machine with retry-once + human-gate
+callbacks), and `explore-parallel` / `discuss-parallel` / `init` for the
+concurrent researcher stages.
+
+### Cross-harness
+
+The plugin runs unchanged on Claude Code, OpenAI Codex CLI, and Gemini CLI.
+See [`reference/codex-tools.md`](reference/codex-tools.md) and
+[`reference/gemini-tools.md`](reference/gemini-tools.md) for the tool
+translations; Codex auto-loads [`AGENTS.md`](AGENTS.md) and Gemini auto-loads
+[`GEMINI.md`](GEMINI.md). The `gdd-state` MCP server works on all three.
+
+---
+
 ## AI-Native Canvas Tools
 
 get-design-done integrates with canvas tools that treat the design canvas as both source AND destination — enabling a full canvas→code→verify→canvas round-trip.

package/bin/gdd-sdk

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+// bin/gdd-sdk — Plan 21-09 Task 7 (SDK-21).
+//
+// CJS trampoline: spawns `node --experimental-strip-types` against the
+// real TS entry point in `scripts/lib/cli/index.ts` and forwards argv +
+// exit code. Windows-compatible (npm's generated .cmd shim on Windows
+// has no way to inject the --experimental-strip-types flag otherwise).
+//
+// Why a trampoline:
+//   POSIX shebangs can use `#!/usr/bin/env -S node --experimental-strip-types`,
+//   but Windows cmd.exe does not honor shebangs. npm's auto-generated
+//   .cmd shim invokes plain `node bin/gdd-sdk` without passing the
+//   experimental flag. The trampoline re-launches node with the flag
+//   explicitly so both platforms end up at the same TS entry.
+
+'use strict';
+
+const { spawn } = require('node:child_process');
+const path = require('node:path');
+
+const entry = path.resolve(
+  __dirname,
+  '..',
+  'scripts',
+  'lib',
+  'cli',
+  'index.ts',
+);
+
+const child = spawn(
+  process.execPath,
+  ['--experimental-strip-types', entry, ...process.argv.slice(2)],
+  { stdio: 'inherit', shell: false },
+);
+
+child.on('exit', (code, signal) => {
+  if (signal) {
+    // Re-raise the signal to ourselves so the parent shell sees the same
+    // termination mode (e.g., Ctrl+C propagates as SIGINT exit).
+    try {
+      process.kill(process.pid, signal);
+    } catch {
+      process.exit(1);
+    }
+    return;
+  }
+  process.exit(typeof code === 'number' ? code : 0);
+});
+
+child.on('error', (err) => {
+  // Failure to spawn node itself — extremely rare; surface to stderr.
+  // eslint-disable-next-line no-console
+  console.error('gdd-sdk: failed to launch TypeScript entry:', err.message);
+  process.exit(3);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.20.0",
+  "version": "1.21.0",
   "description": "A Claude Code plugin for systematic design improvement",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",
@@ -20,6 +20,7 @@
     "scripts/",
     "connections/",
     "reference/",
+    "bin/",
     "SKILL.md",
     "README.md",
     "CHANGELOG.md",
@@ -27,7 +28,8 @@
   ],
   "bin": {
     "get-design-done": "./scripts/install.cjs",
-    "gdd-state-mcp": "./scripts/mcp-servers/gdd-state/server.ts"
+    "gdd-state-mcp": "./scripts/mcp-servers/gdd-state/server.ts",
+    "gdd-sdk": "./bin/gdd-sdk"
   },
   "publishConfig": {
     "access": "public",
@@ -45,7 +47,9 @@
     "scan:injection": "node scripts/run-injection-scanner-ci.cjs",
     "test:size-budget": "node --test tests/agent-size-budget.test.cjs",
     "release:extract-changelog": "node scripts/extract-changelog-section.cjs",
-    "verify:version-sync": "node scripts/verify-version-sync.cjs"
+    "verify:version-sync": "node scripts/verify-version-sync.cjs",
+    "typecheck:session-runner": "tsc --noEmit",
+    "gdd-sdk": "node --experimental-strip-types scripts/lib/cli/index.ts"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
@@ -65,56 +69,20 @@
     "reflection",
     "tested",
     "ci",
-    "iconography",
-    "brand-voice",
-    "performance-budget",
-    "framer-motion",
-    "motion-design",
-    "micro-polish",
-    "surfaces",
-    "make-interfaces-feel-better",
-    "palette-catalog",
-    "style-vocabulary",
-    "industry-palettes",
-    "ui-style-vocabulary",
-    "variable-fonts",
-    "container-queries",
-    "view-transitions",
-    "motion-vocabulary",
-    "motion-easings",
-    "transition-taxonomy",
-    "gesture-mechanics",
-    "clip-path-animation",
-    "component-specs",
-    "design-system-benchmarks",
-    "i18n",
-    "user-research",
-    "information-architecture",
-    "form-patterns",
-    "data-viz",
-    "platforms",
-    "cross-cycle-memory",
-    "fts5",
-    "checkpoints",
-    "experience-archive",
-    "recall",
-    "relevance-counter",
-    "record-contract",
-    "first-principles",
-    "emotional-design",
-    "component-authoring",
-    "disney-12-principles",
-    "peak-end-rule",
-    "loss-aversion",
-    "cognitive-load",
-    "doherty-threshold",
-    "rams-lens"
+    "headless",
+    "cli",
+    "codex",
+    "gemini",
+    "mcp",
+    "parallel-agents",
+    "agent-sdk"
   ],
   "skills": [
     "SKILL.md"
   ],
   "hooks": "hooks/hooks.json",
   "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.119",
     "@modelcontextprotocol/sdk": "^1.0.0"
   }
 }

package/reference/codex-tools.md

@@ -0,0 +1,53 @@
+# Codex CLI Tool Map
+
+Last verified: 2026-04-24
+
+When a GDD skill references a Claude Code tool name, the Codex runtime
+translates to the equivalent below. Skills do NOT need to branch — the tool
+name in prose is authoritative; Codex resolves via this map.
+
+## Tool-name mapping
+
+| CC name | Codex name | Notes |
+| --- | --- | --- |
+| `Read` | `read_file` | Takes `path`; returns file content. |
+| `Write` | `apply_patch` (create mode) | Requires a diff-style patch; ensure tool call emits `{action:'create', path, content}`. |
+| `Edit` | `apply_patch` (update mode) | Emits `{action:'update', path, patch}` with unified diff. |
+| `Bash` | `shell` | Takes `{command: string, cwd?, timeout_sec?}`. |
+| `Grep` | `shell` | Compose a `rg` / `grep -rn` invocation; no native Codex grep tool. |
+| `Glob` | `shell` | Compose `ls` / `find`; no native Codex glob. |
+| `Task` | Sub-invocation via nested Codex | Codex spawns nested sessions via its own CLI, not a tool call. Skills requiring Task should prefer the MCP `gdd-state` tool layer instead. |
+| `WebSearch` | `web_search` | If enabled in Codex policy. |
+| `WebFetch` | `shell` (curl) or `web_search.open` | Prefer curl for deterministic output. |
+
+## MCP server `gdd-state`
+
+The gdd-state MCP server works unchanged on Codex. Configure Codex to load
+it by adding to `~/.codex/config.toml`:
+
+```toml
+[[mcp_servers]]
+name = "gdd-state"
+command = "node"
+args = ["--experimental-strip-types", "<pkg-root>/scripts/mcp-servers/gdd-state/server.ts"]
+```
+
+All 11 tools exposed by the server appear as `mcp__gdd_state__*` in Codex.
+
+## Known gaps
+
+- `Task` spawning: Codex does not expose nested-session as a tool call. For
+  now, skills that rely on `Task` (parallel mappers in Plan 21-06, parallel
+  discussants in Plan 21-07) should invoke the gdd-sdk CLI as a shell
+  subprocess: `shell("npx gdd-sdk stage explore --parallel")`. This is
+  documented in AGENTS.md.
+- `apply_patch` diff format differs from CC's Edit: Codex expects unified
+  diff (`---`/`+++`/`@@` hunks), while CC's Edit takes `old_string`/`new_string`.
+  The plugin's skill prose uses Edit's semantics; on Codex the runtime must
+  generate the unified diff from the old/new pair. A helper lives at
+  `scripts/lib/harness/edit-to-patch.ts` (reserved for Phase 22 wiring).
+
+---
+
+Last verified: 2026-04-24 — tool surface re-checked against Codex CLI docs
+current to this date. Revisit whenever Codex ships a tool-vocabulary change.

package/reference/gemini-tools.md

@@ -0,0 +1,53 @@
+# Gemini CLI Tool Map
+
+Last verified: 2026-04-24
+
+When a GDD skill references a Claude Code tool name, the Gemini runtime
+translates to the equivalent below. Skills do NOT need to branch — the tool
+name in prose is authoritative; Gemini resolves via this map.
+
+## Tool-name mapping
+
+| CC name | Gemini name | Notes |
+| --- | --- | --- |
+| `Read` | `read_file` | Takes `absolute_path`. |
+| `Write` | `write_file` | Takes `path`, `content`; overwrites. |
+| `Edit` | `replace` | Takes `file_path`, `old_string`, `new_string`. Semantics match CC. |
+| `Bash` | `run_shell_command` | Takes `{command: string, directory?}`. |
+| `Grep` | `search_file_content` | Native grep wrapper. |
+| `Glob` | `glob` | Native glob wrapper. |
+| `Task` | Sub-invocation via nested gemini CLI | Same gap as Codex. |
+| `WebSearch` | `google_web_search` | Built-in. |
+| `WebFetch` | `web_fetch` | Built-in. |
+
+## MCP server `gdd-state`
+
+The gdd-state MCP server works unchanged on Gemini. Configure Gemini to load
+it by adding to `~/.gemini/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "gdd-state": {
+      "command": "node",
+      "args": ["--experimental-strip-types", "<pkg-root>/scripts/mcp-servers/gdd-state/server.ts"]
+    }
+  }
+}
+```
+
+All 11 tools exposed by the server appear as `mcp__gdd_state__*` in Gemini.
+
+## Known gaps
+
+- `Task` spawning: same as Codex — prefer `run_shell_command("npx gdd-sdk stage ...")`.
+  See GEMINI.md for invocation details.
+- Gemini's `replace` has stricter uniqueness requirements than CC's Edit;
+  when `old_string` appears more than once, Gemini requires context lines.
+  Skill prose that calls Edit should include surrounding context in
+  `old_string` to satisfy both harnesses.
+
+---
+
+Last verified: 2026-04-24 — tool surface re-checked against Gemini CLI docs
+current to this date. Revisit whenever Gemini ships a tool-vocabulary change.

package/reference/registry.json

@@ -3,6 +3,20 @@
   "version": 1,
   "generated_at": "2026-04-24T00:00:00.000Z",
   "entries": [
+    {
+      "name": "codex-tools",
+      "path": "reference/codex-tools.md",
+      "type": "meta-rules",
+      "phase": 21,
+      "description": "Phase 21 cross-harness tool map — Claude Code → OpenAI Codex CLI tool-name equivalents for the gdd-sdk runner (Read→read_file, Write/Edit→apply_patch, Bash→shell, etc.)"
+    },
+    {
+      "name": "gemini-tools",
+      "path": "reference/gemini-tools.md",
+      "type": "meta-rules",
+      "phase": 21,
+      "description": "Phase 21 cross-harness tool map — Claude Code → Gemini CLI tool-name equivalents for the gdd-sdk runner"
+    },
     {
       "name": "error-recovery",
       "path": "reference/error-recovery.md",