@hegemonart/get-design-done 1.20.0 → 1.22.0

package/hooks/gdd-trajectory-capture.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+/**
+ * gdd-trajectory-capture.js — PostToolUse:Agent hook (Plan 22-03).
+ *
+ * Reads the standard Claude Code hook JSON from stdin:
+ *   { tool_name, tool_input, tool_response, session_id, ... }
+ *
+ * Writes one JSONL line to `.design/telemetry/trajectories/<cycle>.jsonl`
+ * via `scripts/lib/trajectory/index.cjs`. Silent-on-failure: telemetry
+ * never blocks the parent agent's tool call.
+ *
+ * Cycle resolution:
+ *   * env var GDD_CYCLE wins (used by Phase 21 pipeline runner)
+ *   * fallback: 'current'
+ */
+
+'use strict';
+
+const { recordCall } = require('../scripts/lib/trajectory/index.cjs');
+
+let raw = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => {
+  raw += chunk;
+});
+process.stdin.on('end', () => {
+  try {
+    const input = raw.trim() ? JSON.parse(raw) : {};
+    const toolName = input.tool_name || input.toolName || 'unknown';
+    const toolInput = input.tool_input ?? input.toolInput ?? null;
+    const toolResponse = input.tool_response ?? input.toolResponse ?? null;
+    const sessionId = input.session_id ?? input.sessionId ?? null;
+    const status =
+      toolResponse && typeof toolResponse === 'object' && toolResponse.is_error === true
+        ? 'error'
+        : 'ok';
+    const latency = typeof input.latency_ms === 'number' ? input.latency_ms : 0;
+
+    recordCall({
+      cycle: process.env.GDD_CYCLE || 'current',
+      session_id: sessionId,
+      agent: input.agent || process.env.GDD_AGENT || 'unknown',
+      tool: toolName,
+      args: toolInput,
+      result: toolResponse,
+      latency_ms: latency,
+      status,
+    });
+  } catch (err) {
+    try {
+      process.stderr.write(
+        `[gdd-trajectory] hook failed: ${err && err.message ? err.message : String(err)}\n`,
+      );
+    } catch {
+      /* swallow */
+    }
+  }
+  // Always emit a non-blocking continue verdict.
+  try {
+    process.stdout.write(JSON.stringify({ continue: true, suppressOutput: true }));
+  } catch {
+    /* swallow */
+  }
+});

package/hooks/hooks.json

@@ -83,6 +83,15 @@
           }
         ]
       },
+      {
+        "matcher": "Agent",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/gdd-trajectory-capture.js\""
+          }
+        ]
+      },
       {
         "hooks": [
           {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.20.0",
+  "version": "1.22.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,9 @@
   ],
   "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",
+    "gdd-events": "./scripts/cli/gdd-events.mjs"
   },
   "publishConfig": {
     "access": "public",
@@ -45,7 +48,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 +70,23 @@
     "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"
+  },
+  "optionalDependencies": {
+    "ws": "^8.20.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",

package/scripts/cli/gdd-events.mjs

@@ -0,0 +1,283 @@
+#!/usr/bin/env -S node --experimental-strip-types
+// scripts/cli/gdd-events.mjs — CLI transport for the event stream
+// (Plan 22-06).
+//
+// Subcommands:
+//   gdd-events tail [--follow] [--path=<p>]
+//     - dump events.jsonl to stdout, line-by-line
+//     - --follow re-polls every 250ms appending new content (no native
+//       inotify dep; portable across platforms)
+//
+//   gdd-events grep <filter> [--path=<p>]
+//     - filter language (space-separated terms, all AND'd):
+//         type=<exact-string>           — match `type` field
+//         payload.<dotted.path>=<value> — drill into payload by '.'-path
+//         !type=<exact-string>          — negate
+//         !payload.<path>=<value>       — negate
+//     - prints matching events to stdout as JSONL (compact)
+//
+//   gdd-events cat [--path=<p>]
+//     - alias for tail without --follow, but pretty-prints with a
+//       leading timestamp+type prefix per line
+//
+//   gdd-events list-types
+//     - prints the runtime KNOWN_EVENT_TYPES list (from Plan 22-01)
+//
+//   gdd-events serve [--port=<n>] [--token=<t>] [--tail=<file>]
+//     - WebSocket transport (Plan 22-07). Loaded lazily via
+//       probe-optional; helpful error if `ws` is not installed.
+//
+// Default --path is `.design/telemetry/events.jsonl` (relative to cwd).
+
+import { existsSync, statSync, openSync, readSync, closeSync } from 'node:fs';
+import { resolve, isAbsolute } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { argv, exit, stdout, stderr } from 'node:process';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+const DEFAULT_PATH = '.design/telemetry/events.jsonl';
+
+function usage() {
+  stderr.write(
+    [
+      'gdd-events — Phase 22 event-stream CLI',
+      '',
+      'Usage:',
+      '  gdd-events tail [--follow] [--path=<p>]',
+      '  gdd-events grep <filter…> [--path=<p>]',
+      '  gdd-events cat [--path=<p>]',
+      '  gdd-events list-types',
+      '  gdd-events serve [--port=<n>] [--token=<t>] [--tail=<file>]',
+      '',
+      'Filter language (grep): type=<s>  payload.<dotted.path>=<s>  !type=<s>',
+      '',
+    ].join('\n'),
+  );
+}
+
+function parseArgs(args) {
+  const out = { _: [], flags: {} };
+  for (const a of args) {
+    if (a.startsWith('--')) {
+      const eq = a.indexOf('=');
+      if (eq === -1) {
+        out.flags[a.slice(2)] = true;
+      } else {
+        out.flags[a.slice(2, eq)] = a.slice(eq + 1);
+      }
+    } else {
+      out._.push(a);
+    }
+  }
+  return out;
+}
+
+function resolvePath(flagPath) {
+  const raw = flagPath || DEFAULT_PATH;
+  return isAbsolute(raw) ? raw : resolve(process.cwd(), raw);
+}
+
+/** Compile filter terms like "type=foo", "!payload.x=1" into a predicate. */
+export function compileFilter(terms) {
+  /** @type {Array<(ev: any) => boolean>} */
+  const checks = [];
+  for (const term of terms) {
+    let negate = false;
+    let body = term;
+    if (body.startsWith('!')) {
+      negate = true;
+      body = body.slice(1);
+    }
+    const eq = body.indexOf('=');
+    if (eq === -1) {
+      throw new Error(`gdd-events: bad filter term: ${term}`);
+    }
+    const key = body.slice(0, eq);
+    const want = body.slice(eq + 1);
+    /** @type {(ev: any) => boolean} */
+    let test;
+    if (key === 'type') {
+      test = (ev) => ev?.type === want;
+    } else if (key.startsWith('payload.')) {
+      const path = key.slice('payload.'.length).split('.');
+      test = (ev) => {
+        let cur = ev?.payload;
+        for (const part of path) {
+          if (cur == null || typeof cur !== 'object') return false;
+          cur = cur[part];
+        }
+        return String(cur) === want;
+      };
+    } else if (key === 'stage') {
+      test = (ev) => ev?.stage === want;
+    } else if (key === 'cycle') {
+      test = (ev) => ev?.cycle === want;
+    } else if (key === 'sessionId') {
+      test = (ev) => ev?.sessionId === want;
+    } else {
+      throw new Error(`gdd-events: unsupported filter key: ${key}`);
+    }
+    checks.push(negate ? (ev) => !test(ev) : test);
+  }
+  return (ev) => checks.every((c) => c(ev));
+}
+
+async function cmdTail(parsed) {
+  const path = resolvePath(parsed.flags.path);
+  const { readEvents } = await import('../lib/event-stream/reader.ts');
+  if (!parsed.flags.follow) {
+    for await (const ev of readEvents({ path })) {
+      stdout.write(JSON.stringify(ev) + '\n');
+    }
+    return 0;
+  }
+  // Follow mode: stream existing content, then poll for appends.
+  let offset = 0;
+  if (existsSync(path)) {
+    for await (const ev of readEvents({ path })) {
+      stdout.write(JSON.stringify(ev) + '\n');
+    }
+    offset = statSync(path).size;
+  }
+  // Poll loop. Reads new bytes since last offset, splits on \n, writes each.
+  let buf = '';
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    await new Promise((r) => setTimeout(r, 250));
+    if (!existsSync(path)) continue;
+    const size = statSync(path).size;
+    if (size <= offset) continue;
+    const fd = openSync(path, 'r');
+    try {
+      const need = size - offset;
+      const chunk = Buffer.allocUnsafe(need);
+      const n = readSync(fd, chunk, 0, need, offset);
+      offset += n;
+      buf += chunk.subarray(0, n).toString('utf8');
+      const lines = buf.split('\n');
+      buf = lines.pop() || '';
+      for (const line of lines) {
+        if (line.trim() === '') continue;
+        stdout.write(line + '\n');
+      }
+    } finally {
+      closeSync(fd);
+    }
+  }
+}
+
+async function cmdGrep(parsed) {
+  const path = resolvePath(parsed.flags.path);
+  const terms = parsed._;
+  if (terms.length === 0) {
+    stderr.write('gdd-events grep: at least one filter term required\n');
+    return 2;
+  }
+  const predicate = compileFilter(terms);
+  const { readEvents } = await import('../lib/event-stream/reader.ts');
+  for await (const ev of readEvents({ path, predicate })) {
+    stdout.write(JSON.stringify(ev) + '\n');
+  }
+  return 0;
+}
+
+async function cmdCat(parsed) {
+  const path = resolvePath(parsed.flags.path);
+  const { readEvents } = await import('../lib/event-stream/reader.ts');
+  for await (const ev of readEvents({ path })) {
+    const ts = ev.timestamp ?? '?';
+    const tp = ev.type ?? '?';
+    stdout.write(`${ts}  ${tp.padEnd(28)}  ${JSON.stringify(ev.payload ?? {})}\n`);
+  }
+  return 0;
+}
+
+async function cmdListTypes() {
+  const { KNOWN_EVENT_TYPES } = await import('../lib/event-stream/types.ts');
+  for (const t of KNOWN_EVENT_TYPES) stdout.write(t + '\n');
+  return 0;
+}
+
+async function cmdServe(parsed) {
+  let mod;
+  try {
+    mod = require('../lib/transports/ws.cjs');
+  } catch (err) {
+    stderr.write(
+      'gdd-events serve: WebSocket transport requires the optional `ws` package.\n' +
+        '  install: npm i -D ws\n' +
+        `  ${err && err.message ? err.message : String(err)}\n`,
+    );
+    return 1;
+  }
+  const port = Number(parsed.flags.port) || 9595;
+  const token = parsed.flags.token || process.env.GDD_EVENTS_TOKEN;
+  if (!token) {
+    stderr.write('gdd-events serve: --token=<t> or GDD_EVENTS_TOKEN env required\n');
+    return 2;
+  }
+  const tailFrom = parsed.flags.tail
+    ? resolvePath(parsed.flags.tail)
+    : resolvePath(undefined);
+  // Bridge live bus → ws transport. The transport is CommonJS and cannot
+  // require .ts directly, so we import the bus here and pass subscribeAll
+  // as a callback factory.
+  const { subscribeAll } = await import('../lib/event-stream/index.ts');
+  const subscribe = (handler) => subscribeAll(handler);
+  const handle = await mod.startServer({ port, token, tailFrom, subscribe });
+  stderr.write(`gdd-events: WebSocket listening on :${port} (auth required)\n`);
+  // Keep the process alive until SIGINT/SIGTERM.
+  await new Promise((resolve) => {
+    const close = () => {
+      handle.close();
+      resolve();
+    };
+    process.once('SIGINT', close);
+    process.once('SIGTERM', close);
+  });
+  return 0;
+}
+
+async function main() {
+  const parsed = parseArgs(argv.slice(2));
+  const sub = parsed._.shift();
+  try {
+    switch (sub) {
+      case 'tail':
+        return await cmdTail(parsed);
+      case 'grep':
+        return await cmdGrep(parsed);
+      case 'cat':
+        return await cmdCat(parsed);
+      case 'list-types':
+        return await cmdListTypes();
+      case 'serve':
+        return await cmdServe(parsed);
+      case '-h':
+      case '--help':
+      case 'help':
+        usage();
+        return 0;
+      default:
+        usage();
+        return sub === undefined ? 0 : 2;
+    }
+  } catch (err) {
+    stderr.write(`gdd-events: ${err && err.message ? err.message : String(err)}\n`);
+    return 1;
+  }
+}
+
+// Compare module URL via pathToFileURL — Windows paths use backslashes
+// and need proper file:// URL canonicalisation; the simpler `file://${argv[1]}`
+// form drops to false on Windows and the CLI silently no-ops.
+const isCli = process.argv[1] !== undefined &&
+  import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isCli) {
+  main().then((code) => exit(code), (err) => {
+    stderr.write(`gdd-events fatal: ${err}\n`);
+    exit(1);
+  });
+}