@opengsd/gsd-core 1.16.0 → 1.18.0

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "gsd-core",
       "description": "GSD Core is a meta-prompting, context engineering, and spec-driven development system for AI coding agents.",
-      "version": "1.16.0",
+      "version": "1.18.0",
       "source": "./",
       "author": {
         "name": "open-gsd",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "gsd-core",
   "displayName": "GSD Core",
-  "version": "1.16.0",
+  "version": "1.18.0",
   "description": "GSD Core is a meta-prompting, context engineering, and spec-driven development system for AI coding agents.",
   "author": {
     "name": "open-gsd",
@@ -18,6 +18,5 @@
     "claude-code",
     "gsd"
   ],
-  "commands": "./commands/gsd/",
   "skills": "./skills/"
 }

package/.opencode/plugins/gsd-core.js

@@ -146,6 +146,11 @@ const TOOL_NAME_MAP = {
   websearch: "WebSearch",
   task: "Task",
   subagent: "Task",
+  // >>> gsd:opencode-v2
+  // OpenCode 2.x tool ids (ADR-5331 E4): `shell` replaces `bash`, `patch` replaces `apply_patch`.
+  shell: "Bash",
+  patch: "MultiEdit",
+  // <<< gsd:opencode-v2
 };
 
 function mapToolName(tool) {
@@ -239,6 +244,18 @@ function gitProbingGuardTimeoutMs() {
   return GIT_PROBING_GUARD_FALLBACK_TIMEOUT_MS;
 }
 
+// Hooks are Node scripts. `process.execPath` is only a JS runtime when the host is Node or Bun
+// itself; inside OpenCode's single-file binary (1.x and 2.x) spawning it with a .js path boots
+// OpenCode instead and exits 0, silently disabling every guard (#4849). So: an explicit
+// GSD_HOOK_RUNTIME wins, then a Node/Bun host's own executable, else `node` from PATH.
+let warnedMissingRuntime = false;
+function hookRuntime() {
+  const fromEnv = process.env.GSD_HOOK_RUNTIME;
+  if (typeof fromEnv === "string" && fromEnv.length > 0) return fromEnv;
+  const base = path.basename(process.execPath).toLowerCase().replace(/\.exe$/, "");
+  return base === "node" || base === "bun" ? process.execPath : "node";
+}
+
 function runHook(hookFile, payload, opts = {}) {
   const hookPath = path.join(HOOKS_DIR, hookFile);
   if (!fs.existsSync(hookPath)) {
@@ -261,7 +278,7 @@ function runHook(hookFile, payload, opts = {}) {
     (GIT_PROBING_GUARDS.has(hookFile) ? gitProbingGuardTimeoutMs() : 8000);
   let result;
   try {
-    result = spawnSync(process.execPath, [hookPath], {
+    result = spawnSync(hookRuntime(), [hookPath], {
       input: JSON.stringify(payload),
       encoding: "utf8",
       timeout,
@@ -273,6 +290,15 @@ function runHook(hookFile, payload, opts = {}) {
     return { stdout: "", exitCode: 0, timedOut: false };
   }
 
+  if (result.error && !warnedMissingRuntime) {
+    // The runtime could not be started: the guard did not run. Fail open (adapter contract) but
+    // never silently (#4849).
+    warnedMissingRuntime = true;
+    console.error(
+      `[gsd-core] cannot start hook runtime '${hookRuntime()}' (${result.error.code || result.error.message}) — ` +
+        "GSD hooks are NOT enforced. Install Node.js or set GSD_HOOK_RUNTIME to a node/bun executable.",
+    );
+  }
   const stdout = (result.stdout || "").trim();
   const exitCode = result.status == null ? 0 : result.status;
   return { stdout, exitCode, timedOut: result.signal === "SIGTERM" };
@@ -358,9 +384,81 @@ function handleHookResult(hookResult, output) {
     }
     // Best-effort visibility when metadata isn't surfaced to the model
     console.error(advisory);
+    // >>> gsd:opencode-parity
+    deliverAdvisory(advisory, output);
+    // <<< gsd:opencode-parity
+  }
+}
+// >>> gsd:opencode-parity (ADR-5331 Phase 3; OpenCode-only — the Kilo mirror omits this block)
+// The four opt-in community hooks are bash scripts. Their gates (hooks.community, graphify.*) are
+// re-checked here in-process so a project that has not opted in never pays a bash spawn per tool call.
+function readProjectConfig(cwd) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(cwd, ".planning", "config.json"), "utf8"));
+  } catch {
+    return null;
   }
 }
 
+function communityHooksEnabled(cwd) {
+  const config = readProjectConfig(cwd);
+  return !!config && config.hooks && config.hooks.community === true;
+}
+
+function graphifyAutoUpdateEnabled(cwd) {
+  const config = readProjectConfig(cwd);
+  return !!config && !process.env.CI && !!config.graphify &&
+    config.graphify.enabled === true && config.graphify.auto_update === true;
+}
+
+/**
+ * Run a GSD `.sh` hook under bash with the hook payload on stdin. Fails open: a missing script or no
+ * bash on PATH (a Windows host without Git Bash) is the same as the hook not being installed.
+ */
+function runShellHook(hookFile, payload, opts = {}) {
+  const hookPath = path.join(HOOKS_DIR, hookFile);
+  if (!fs.existsSync(hookPath)) return { stdout: "", exitCode: 0, timedOut: false };
+  let result;
+  try {
+    result = spawnSync(process.env.GSD_HOOK_SHELL || "bash", [hookPath], {
+      input: JSON.stringify(payload),
+      encoding: "utf8",
+      timeout: opts.timeout ?? 15000,
+      cwd: opts.cwd || currentCwd,
+      windowsHide: true,
+    });
+  } catch {
+    return { stdout: "", exitCode: 0, timedOut: false };
+  }
+  if (result.error) return { stdout: "", exitCode: 0, timedOut: false };
+  return {
+    stdout: (result.stdout || "").trim(),
+    exitCode: result.status == null ? 0 : result.status,
+    timedOut: result.signal === "SIGTERM",
+  };
+}
+
+// The SessionStart orientation text, produced once per session and handed to the model with its next request.
+let pendingSessionContext = null;
+
+// Advisories (read-before-edit, injection findings, phase-boundary, context warnings) were logged to stderr
+// only — OpenCode does not show a plugin's stderr or metadata to the model. They are appended to the tool's
+// own output instead, which is the one channel the model reads on both generations. An advisory raised before
+// the tool runs waits here for that tool's result.
+const pendingAdvisories = [];
+function deliverAdvisory(text, output) {
+  if (output && typeof output.output === "string") {
+    output.output += "\n\n[GSD advisory] " + text;
+    return;
+  }
+  if (!pendingAdvisories.includes(text) && pendingAdvisories.length < 5) pendingAdvisories.push(text);
+}
+function flushPendingAdvisories(output) {
+  if (!output || typeof output.output !== "string") return;
+  while (pendingAdvisories.length > 0) output.output += "\n\n[GSD advisory] " + pendingAdvisories.shift();
+}
+// <<< gsd:opencode-parity
+
 // ---------------------------------------------------------------------------
 // Frontmatter helpers (for config registration)
 // ---------------------------------------------------------------------------
@@ -667,6 +765,13 @@ const GsdCorePlugin = async ({ directory } = {}) => {
         const r = runHook("gsd-secret-read-guard.js", prePayload());
         handleHookResult(r, output);
       }
+      // >>> gsd:opencode-parity
+      // 7. gsd-validate-commit.sh — Conventional Commits gate (opt-in: hooks.community)
+      if (claudeTool === "Bash" && communityHooksEnabled(cwd)) {
+        const r = runShellHook("gsd-validate-commit.sh", prePayload());
+        handleHookResult(r, output);
+      }
+      // <<< gsd:opencode-parity
     },
 
     // ── tool.execute.after — PostToolUse hooks ─────────────────────────
@@ -690,6 +795,25 @@ const GsdCorePlugin = async ({ directory } = {}) => {
             : String(output.output);
         output.output = rewriteContent(content);
       }
+      // >>> gsd:opencode-parity
+      flushPendingAdvisories(output);
+      // gsd-phase-boundary.sh — reminder when .planning/ files change outside the workflow (opt-in)
+      // gsd-graphify-update.sh — rebuild the knowledge graph after a HEAD-advancing git op (opt-in)
+      {
+        const postPayload = {
+          hook_event_name: "PostToolUse",
+          tool_name: claudeTool,
+          tool_input: toolInput,
+          cwd,
+        };
+        if ((claudeTool === "Write" || claudeTool === "Edit") && communityHooksEnabled(cwd)) {
+          handleHookResult(runShellHook("gsd-phase-boundary.sh", postPayload), output);
+        }
+        if (claudeTool === "Bash" && graphifyAutoUpdateEnabled(cwd)) {
+          handleHookResult(runShellHook("gsd-graphify-update.sh", postPayload, { timeout: 8000 }), output);
+        }
+      }
+      // <<< gsd:opencode-parity
 
       // gsd-read-injection-scanner.js — scan Read/WebFetch/WebSearch results
       if (
@@ -727,6 +851,16 @@ const GsdCorePlugin = async ({ directory } = {}) => {
         handleHookResult(r, output);
       }
     },
+    // >>> gsd:opencode-parity
+    // ── experimental.chat.system.transform — SessionStart orientation (gsd-session-state.sh) ──
+    "experimental.chat.system.transform": async (_input, output) => {
+      if (!pendingSessionContext) return;
+      const text = pendingSessionContext;
+      pendingSessionContext = null;
+      output.system = output.system || [];
+      output.system.push(text);
+    },
+    // <<< gsd:opencode-parity
 
     // ── experimental.session.compacting — PreCompact ───────────────────
     "experimental.session.compacting": async (_input, output) => {
@@ -770,6 +904,23 @@ const GsdCorePlugin = async ({ directory } = {}) => {
           session_id: currentSessionId,
           cwd: currentCwd,
         });
+        // >>> gsd:opencode-parity
+        // gsd-session-state.sh — project state orientation for the session (opt-in: hooks.community)
+        if (communityHooksEnabled(currentCwd)) {
+          const r = runShellHook("gsd-session-state.sh", {
+            hook_event_name: "SessionStart",
+            session_id: currentSessionId,
+            cwd: currentCwd,
+          });
+          try {
+            const parsed = JSON.parse(r.stdout);
+            const text = parsed && parsed.hookSpecificOutput && parsed.hookSpecificOutput.additionalContext;
+            pendingSessionContext = typeof text === "string" && text ? text : null;
+          } catch {
+            pendingSessionContext = null;
+          }
+        }
+        // <<< gsd:opencode-parity
         return;
       }
 
@@ -864,7 +1015,106 @@ GsdCorePlugin._internals = {
   GsdCorePlugin,
 };
 
+// >>> gsd:opencode-v2 (ADR-5331 D2; OpenCode 2.x entrypoint — the Kilo mirror omits this block)
+// OpenCode 2.x calls `setup(ctx)` with a `ctx` exposing `ctx.tool.hook(...)`; 1.x loads `server`
+// and never calls `setup` with such a ctx. `setup` therefore returns at once unless it is
+// handed a 2.x ctx. The 1.x hook handlers are reused through thin adapters so both generations
+// run the same guards.
+function v2ResultText(result) {
+  const first = result && Array.isArray(result.content) ? result.content[0] : null;
+  return first && typeof first.text === "string" ? first.text : null;
+}
+
+async function setupV2(ctx) {
+  if (!(ctx && ctx.tool && typeof ctx.tool.hook === "function")) return undefined;
+  const hooks = await GsdCorePlugin({ directory: ctx.directory });
+  // A thrown error in a 2.x before-hook blocks the tool (verified on 2.0.27), as in 1.x.
+  await ctx.tool.hook("execute.before", async (e) => {
+    await hooks["tool.execute.before"]({ tool: e.tool }, { args: e.input || {} });
+  });
+  await ctx.tool.hook("execute.after", async (e) => {
+    if (e.status !== "completed") return;
+    const text = v2ResultText(e.result);
+    const out = { output: text, metadata: {} };
+    await hooks["tool.execute.after"]({ tool: e.tool, args: e.input || {} }, out);
+    if (text !== null && typeof out.output === "string" && out.output !== text) {
+      e.result.content[0].text = out.output;
+    }
+    // 2.x emits no file.edited event (observed on 2.0.27), so derive it from the edit tools: the
+    // only consumer is the .planning/config.json reload hook.
+    const claudeTool = mapToolName(e.tool);
+    if (claudeTool === "Write" || claudeTool === "Edit" || claudeTool === "MultiEdit") {
+      const edited = mapToolInput(e.input || {}).file_path;
+      if (typeof edited === "string" && edited.endsWith("config.json")) {
+        await hooks.event({
+          event: { type: "file.edited", properties: { file: edited, cwd: path.dirname(path.dirname(edited)) } },
+        });
+      }
+    }
+  });
+  if (ctx.session && typeof ctx.session.hook === "function") {
+    // 2.x compaction event: { sessionID, system: [{ type: "text", text }], messages, … }; items added
+    // to `system` reach the summarizer (observed on 2.0.27).
+    // gsd:opencode-parity: SessionStart orientation reaches the model through the 2.x context hook.
+    await ctx.session.hook("context", async (e) => {
+      if (!e || !Array.isArray(e.system)) return;
+      const out = { system: [] };
+      await hooks["experimental.chat.system.transform"]({}, out);
+      for (const line of out.system) e.system.push({ type: "text", text: String(line) });
+    });
+    await ctx.session.hook("compaction", async (e) => {
+      if (!e || !Array.isArray(e.system)) return;
+      const out = { context: [] };
+      await hooks["experimental.session.compacting"]({}, out);
+      for (const line of out.context) e.system.push({ type: "text", text: String(line) });
+    });
+  }
+  if (ctx.shell && typeof ctx.shell.hook === "function") {
+    await ctx.shell.hook("create.before", async (e) => {
+      if (e && e.env && typeof e.env === "object") e.env.GSD_DIR = GSD_CORE;
+    });
+  }
+  let stop = null;
+  const seenSessions = new Set();
+  if (ctx.event && typeof ctx.event.subscribe === "function") {
+    const ac = new AbortController();
+    stop = () => ac.abort();
+    (async () => {
+      for await (const ev of ctx.event.subscribe({ signal: ac.signal })) {
+        // 2.0.27 shape (observed): { type, location: { directory }, data: { sessionID, … } }.
+        const d = (ev && ev.data) || {};
+        const dir = (ev && ev.location && ev.location.directory) || (d.location && d.location.directory);
+        try {
+          // A 2.x `run` never emits `session.created` (observed on 2.0.27: the first event of a session is
+          // `session.inbox.enqueued`). The first event that names a session is its SessionStart.
+          if (ev.type !== "session.created" && typeof d.sessionID === "string" && !seenSessions.has(d.sessionID)) {
+            seenSessions.add(d.sessionID);
+            await hooks.event({
+              event: { type: "session.created", properties: { info: { id: d.sessionID, directory: dir } }, sessionID: d.sessionID },
+            });
+          } else if (ev.type === "session.created" && typeof d.sessionID === "string") {
+            seenSessions.add(d.sessionID);
+          }
+          await hooks.event({
+            event: {
+              type: ev.type,
+              properties: { info: { id: d.sessionID, directory: dir }, file: d.file, cwd: dir },
+              sessionID: d.sessionID,
+            },
+          });
+        } catch {
+          // one bad event must not end the subscription
+        }
+      }
+    })().catch(() => {});
+  }
+  return stop || undefined;
+}
+// <<< gsd:opencode-v2
 const gsdCorePluginExport = { server: GsdCorePlugin };
+// >>> gsd:opencode-v2
+Object.defineProperty(gsdCorePluginExport, "setup", { value: setupV2, enumerable: false });
+// <<< gsd:opencode-v2
 Object.defineProperty(gsdCorePluginExport, "id", {
   value: "gsd-core",
   enumerable: false,

package/.opencode/plugins/gsd-statusline/tui.tsx

@@ -0,0 +1,55 @@
+// GSD statusline and update banner for the OpenCode 2.x terminal client (ADR-5331 Phase 3).
+//
+// A CLI plugin (https://opencode.ai/v2/docs/build/plugins/cli): OpenCode 2.x loads `tui.tsx` from a
+// directory under plugins/ and renders the slots registered here. The line itself comes from GSD's own
+// hooks/gsd-statusline.js — the script Claude Code runs — so state, progress, git and update-available
+// output stay one implementation. OpenCode 1.x never loads this directory (it scans plugins/*.js|ts only).
+import { Plugin } from "@opencode/plugin/tui"
+import { execFile } from "node:child_process"
+import { existsSync } from "node:fs"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+
+const REFRESH_MS = 10_000
+// Strip terminal colour codes: the host styles its own footer.
+const ANSI = /\u001b\[[0-9;?]*[ -/]*[@-~]/g
+
+function hooksDir() {
+  // <config>/plugins/gsd-statusline/tui.tsx  →  <config>/hooks
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..", "hooks")
+}
+
+function runtime() {
+  return process.env.GSD_HOOK_RUNTIME || "node"
+}
+
+function render(directory: string, model: string, done: (line: string) => void) {
+  const script = path.join(hooksDir(), "gsd-statusline.js")
+  // Only inside a GSD project, and only when the script is installed.
+  if (!existsSync(script) || !existsSync(path.join(directory, ".planning"))) return done("")
+  const child = execFile(runtime(), [script], { cwd: directory, timeout: 4000, windowsHide: true }, (error, stdout) => {
+    done(error ? "" : String(stdout).replace(ANSI, "").split("\n")[0].trim())
+  })
+  child.stdin?.end(JSON.stringify({ model: { display_name: model }, workspace: { current_dir: directory } }))
+}
+
+export default Plugin.define({
+  id: "gsd.statusline",
+  setup(context) {
+    const directory = context.location?.directory ?? context.data.location.default().directory
+    const [state, update] = context.storage.memory("line", { initial: { text: "" } })
+    const refresh = () => {
+      const selected = context.ui.model.current()
+      render(directory, selected?.modelID || "OpenCode", (text) => update((draft: { text: string }) => { draft.text = text }))
+    }
+    refresh()
+    const timer = setInterval(refresh, REFRESH_MS)
+    const stopHome = context.ui.slot({ append: "home.footer.status", render: () => <text>{state.text}</text> })
+    const stopPrompt = context.ui.slot({ append: "prompt.footer.status", render: () => <text>{state.text}</text> })
+    return () => {
+      clearInterval(timer)
+      stopHome?.()
+      stopPrompt?.()
+    }
+  },
+})

package/GEMINI.md

@@ -25,7 +25,7 @@ files rather than in the conversation.
 > run the dedicated installer:
 >
 > ```bash
-> npx gsd-core --antigravity --global
+> npx @opengsd/gsd-core@latest --antigravity --global
 > ```
 >
 > The commands below are available only once that installer has run.

package/agents/gsd-advisor-researcher.compact.md

@@ -15,7 +15,7 @@ grounded in project context.
 
 @~/.claude/gsd-core/references/untrusted-input-boundary.md
 
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-advisor-researcher`)
 
 <documentation_lookup>
 @~/.claude/gsd-core/references/research-documentation-lookup.md

package/agents/gsd-advisor-researcher.md

@@ -19,7 +19,7 @@ Spawned by `discuss-phase` via `Task()`. You do NOT present output directly to t
 
 @~/.claude/gsd-core/references/untrusted-input-boundary.md
 
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-advisor-researcher`)
 
 <documentation_lookup>
 @~/.claude/gsd-core/references/research-documentation-lookup.md

package/agents/gsd-assumptions-analyzer.compact.md

@@ -11,7 +11,7 @@ GSD assumptions analyzer. Deeply analyze the codebase for ONE phase; produce str
 
 @~/.claude/gsd-core/references/untrusted-input-boundary.md
 
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-assumptions-analyzer`)
 
 <input>
 Via prompt: `<phase>` (number/name), `<phase_goal>` (ROADMAP.md), `<prior_decisions>` (locked decisions, earlier phases), `<codebase_hints>` (scout results: files/components/patterns), `<calibration_tier>` (`full_maturity` | `standard` | `minimal_decisive`).

package/agents/gsd-assumptions-analyzer.md

@@ -20,7 +20,7 @@ Spawned by `discuss-phase-assumptions` via `Task()`. You do NOT present output d
 
 @~/.claude/gsd-core/references/untrusted-input-boundary.md
 
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-assumptions-analyzer`)
 
 <input>
 Agent receives via prompt:

package/agents/gsd-code-fixer.compact.md

@@ -21,7 +21,7 @@ Job: read REVIEW.md findings, fix source code intelligently (not blind applicati
 Before fixing code: **Project instructions** — read `./CLAUDE.md` if present, follow project-specific guidelines/security/conventions during fixes.
 
 **Project skills:** check `.claude/skills/` or `.agents/skills/`.
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-code-fixer`)
 1. List available skills 2. Read `SKILL.md` for each (~130 lines) 3. Load specific `rules/*.md` as needed 4. Do NOT load full `AGENTS.md` (100KB+) 5. Follow skill rules relevant to your fix tasks.
 </project_context>
 

package/agents/gsd-code-fixer.md

@@ -25,7 +25,7 @@ Before fixing code, discover project context:
 
 **Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
 
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-code-fixer`)
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during implementation

package/agents/gsd-code-reviewer.compact.md

@@ -38,7 +38,7 @@ Read `./CLAUDE.md` if present — follow project guidelines, security requiremen
 
 **Project skills:** check `.claude/skills/` or `.agents/skills/`: list skill subdirectories, read each `SKILL.md` (lightweight index ~130 lines), load specific `rules/*.md` as needed. Do NOT load full `AGENTS.md` files (100KB+ context cost). Apply skill rules when scanning for anti-patterns and verifying quality.
 
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-code-reviewer`)
 </project_context>
 
 <review_scope>

package/agents/gsd-code-reviewer.md

@@ -41,7 +41,7 @@ Before reviewing, discover project context:
 
 **Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
 
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-code-reviewer`)
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during review

package/agents/gsd-codebase-mapper.compact.md

@@ -27,7 +27,7 @@ Explore thoroughly, then write document(s) directly. Return confirmation only.
 
 **Project skills:** check `.claude/skills/` or `.agents/skills/` if either exists.
 
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md — list skill subdirs, read each `SKILL.md` (~130-line index), load `rules/*.md` as needed. NEVER load full `AGENTS.md` (100KB+ cost). Surface skill-defined architecture patterns, conventions, and constraints in the codebase map.
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-codebase-mapper`) — list skill subdirs, read each `SKILL.md` (~130-line index), load `rules/*.md` as needed. NEVER load full `AGENTS.md` (100KB+ cost). Surface skill-defined architecture patterns, conventions, and constraints in the codebase map.
 
 <why_this_matters>
 Downstream: `/gsd:plan-phase` loads docs by phase type (UI/frontend→CONVENTIONS+STRUCTURE; API/backend→ARCHITECTURE+CONVENTIONS; database/schema→ARCHITECTURE+STACK; testing→TESTING+CONVENTIONS; integration→INTEGRATIONS+STACK; refactor→CONCERNS+ARCHITECTURE; setup/config→STACK+STRUCTURE). `/gsd:execute-phase` uses them to follow conventions, place new files (STRUCTURE.md), match test patterns (TESTING.md), avoid adding debt (CONCERNS.md).

package/agents/gsd-codebase-mapper.md

@@ -30,7 +30,7 @@ If the prompt contains a `<required_reading>` block, you MUST use the `Read` too
 
 **Project skills:** Check `.claude/skills/` or `.agents/skills/` directory if either exists:
 
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-codebase-mapper`)
 1. List available skills (subdirectories)
 2. Read `SKILL.md` for each skill (lightweight index ~130 lines)
 3. Load specific `rules/*.md` files as needed during implementation

package/agents/gsd-debug-session-manager.compact.md

@@ -111,6 +111,12 @@ only "spawn continuation agent" without naming a format, so they inherit this ru
 a flag written at each one — which is exactly why Step 2 must remain the only `Agent()` spawn
 literal in this file.
 
+**Never spawn the debugger through Bash — #5214.** The only way to start `gsd-debugger` is the Step 2
+`Agent()` call above. A `Bash` command such as `claude --agent gsd-debugger …`, with or without
+`run_in_background`, starts a detached process that returns no structured header, so the checkpoint
+never advances. The Bash guard hook denies it (`debugger-cli-spawn`). If the `Agent` call itself fails,
+stop and return that error to the orchestrator; do not improvise a shell spawn.
+
 Resolve the debugger model before spawning (canonical `gsd_run` preamble — established once here, the single definition this agent carries):
 ```bash
 _GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; _gsd_at() { for _p; do if [ -f "$_p" ]; then GSD_TOOLS="$_p"; return 0; fi; done; return 1; }; _gsd_id_ok() { case "$("$1" runtime-identity --raw 2>/dev/null || true)" in '{"packageName":"@opengsd/gsd-core"'*'}') return 0;; *) return 1;; esac; }; _gsd_homes() { set -- "${CLAUDE_CONFIG_DIR:-$HOME/.claude}" "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}" "$HOME/.gemini/antigravity-ide" "$HOME/.gemini/antigravity-cli" "${AUGMENT_CONFIG_DIR:-$HOME/.augment}" "${CLINE_CONFIG_DIR:-$HOME/.cline}" "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}" "${CODEX_HOME:-$HOME/.codex}" "${COPILOT_CONFIG_DIR:-${COPILOT_HOME:-$HOME/.copilot}}" "${CURSOR_CONFIG_DIR:-$HOME/.cursor}" "${HERMES_HOME:-$HOME/.hermes}" "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}" "${KIMI_CONFIG_DIR:-$HOME/.config/agents}" "$HOME/.agents" "${KIMI_CODE_HOME:-$HOME/.kimi-code}" "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}" "${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}" "${QWEN_CONFIG_DIR:-$HOME/.qwen}" "${TRAE_CONFIG_DIR:-$HOME/.trae}" "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}" "${ZCODE_CONFIG_DIR:-$HOME/.zcode}" "${GROK_AGENTS_HOME:-$HOME/.agents}"; for _h; do _gsd_at "$_h/gsd-core/bin/${_GSD_SHIM_NAME}" && return 0; done; return 1; }; if _gsd_at "${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}" "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" "${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}"; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif _gsd_homes; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif unset -f gsd_run; _G="$(command -v gsd_run)"; [ -n "$_G" ] && _gsd_id_ok "$_G"; then GSD_TOOLS="$_G"; gsd_run() { "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and no identity-proving gsd_run is on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi; GSD_IDENTITY_STATUS=unverified; _gsd_id_ok gsd_run && GSD_IDENTITY_STATUS=ok; export GSD_IDENTITY_STATUS; [ "$GSD_IDENTITY_STATUS" = ok ] || echo "WARNING: \"$GSD_TOOLS\" did not prove it is @opengsd/gsd-core - it is either a different package or an @opengsd/gsd-core older than the runtime-identity verb. See docs/how-to/diagnose-a-foreign-gsd-tools.md" >&2; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${GSD_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${GSD_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi

package/agents/gsd-debug-session-manager.md

@@ -117,6 +117,12 @@ only "spawn continuation agent" without naming a format, so they inherit this ru
 a flag written at each one — which is exactly why Step 2 must remain the only `Agent()` spawn
 literal in this file.
 
+**Never spawn the debugger through Bash — #5214.** The only way to start `gsd-debugger` is the Step 2
+`Agent()` call above. A `Bash` command such as `claude --agent gsd-debugger …`, with or without
+`run_in_background`, starts a detached process that returns no structured header, so the checkpoint
+never advances. The Bash guard hook denies it (`debugger-cli-spawn`). If the `Agent` call itself fails,
+stop and return that error to the orchestrator; do not improvise a shell spawn.
+
 Resolve the debugger model before spawning:
 ```bash
 _GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; _gsd_at() { for _p; do if [ -f "$_p" ]; then GSD_TOOLS="$_p"; return 0; fi; done; return 1; }; _gsd_id_ok() { case "$("$1" runtime-identity --raw 2>/dev/null || true)" in '{"packageName":"@opengsd/gsd-core"'*'}') return 0;; *) return 1;; esac; }; _gsd_homes() { set -- "${CLAUDE_CONFIG_DIR:-$HOME/.claude}" "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}" "$HOME/.gemini/antigravity-ide" "$HOME/.gemini/antigravity-cli" "${AUGMENT_CONFIG_DIR:-$HOME/.augment}" "${CLINE_CONFIG_DIR:-$HOME/.cline}" "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}" "${CODEX_HOME:-$HOME/.codex}" "${COPILOT_CONFIG_DIR:-${COPILOT_HOME:-$HOME/.copilot}}" "${CURSOR_CONFIG_DIR:-$HOME/.cursor}" "${HERMES_HOME:-$HOME/.hermes}" "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}" "${KIMI_CONFIG_DIR:-$HOME/.config/agents}" "$HOME/.agents" "${KIMI_CODE_HOME:-$HOME/.kimi-code}" "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}" "${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}" "${QWEN_CONFIG_DIR:-$HOME/.qwen}" "${TRAE_CONFIG_DIR:-$HOME/.trae}" "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}" "${ZCODE_CONFIG_DIR:-$HOME/.zcode}" "${GROK_AGENTS_HOME:-$HOME/.agents}"; for _h; do _gsd_at "$_h/gsd-core/bin/${_GSD_SHIM_NAME}" && return 0; done; return 1; }; if _gsd_at "${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}" "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" "${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}"; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif _gsd_homes; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif unset -f gsd_run; _G="$(command -v gsd_run)"; [ -n "$_G" ] && _gsd_id_ok "$_G"; then GSD_TOOLS="$_G"; gsd_run() { "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and no identity-proving gsd_run is on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi; GSD_IDENTITY_STATUS=unverified; _gsd_id_ok gsd_run && GSD_IDENTITY_STATUS=ok; export GSD_IDENTITY_STATUS; [ "$GSD_IDENTITY_STATUS" = ok ] || echo "WARNING: \"$GSD_TOOLS\" did not prove it is @opengsd/gsd-core - it is either a different package or an @opengsd/gsd-core older than the runtime-identity verb. See docs/how-to/diagnose-a-foreign-gsd-tools.md" >&2; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${GSD_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${GSD_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi

package/agents/gsd-debugger.md

@@ -40,7 +40,7 @@ Your job: Find the root cause through hypothesis testing, maintain debug file st
 - Load `rules/*.md` as needed during **investigation and fix**.
 - Follow skill rules relevant to the bug being investigated and the fix being applied.
 
-**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md
+**agent_skills:** self-load per @~/.claude/gsd-core/references/agent-skills-bootstrap.md (agent type: `gsd-debugger`)
 
 <philosophy>
 

package/agents/gsd-doc-verifier.compact.md

@@ -14,7 +14,7 @@ color: orange
 <role>
 A documentation file has been submitted for factual verification against the live codebase. Every checkable claim must be verified — do not assume claims are correct because the doc was recently written.
 
-Spawned by the `/gsd:docs-update` workflow. Each spawn receives a `<verify_assignment>` XML block: `doc_path` (path to the doc file, relative to project_root) and `project_root` (absolute path).
+Spawned by the `/gsd:docs-update` workflow. Each spawn receives a `<verify_assignment>` XML block: `doc_path` (path to the doc file, relative to project_root), `project_root` (absolute path) and `result_path` (absolute path of the JSON file to write, always under `project_root`, named by the doc's full relative path).
 
 Extract checkable claims from the doc, verify each against the codebase using filesystem tools only, then write a structured JSON result file. Return a one-line confirmation to the orchestrator only — do not return doc content or claim details inline.
 
@@ -90,7 +90,7 @@ Follow in order:
 
 **Step 5: Aggregate results.** Count `claims_checked` (total attempted, excludes skipped), `claims_passed`, `claims_failed`, and build `failures: [{ line, claim, expected, actual }]`.
 
-**Step 6: Write result JSON.** Create `.planning/tmp/` if needed. Write to `.planning/tmp/verify-{doc_filename}.json` where `{doc_filename}` is the basename of `doc_path` (e.g. `README.md` → `verify-README.md.json`), using the exact shape in `<output_format>`.
+**Step 6: Write result JSON.** Create the parent directory of `result_path` if needed and write to exactly `result_path` (from the assignment — never a path you derive, never relative to your working directory), using the exact shape in `<output_format>`.
 </verification_process>
 
 <output_format>
@@ -115,7 +115,7 @@ Verification complete for {doc_path}: {claims_passed}/{claims_checked} claims pa
 ```
 If `claims_failed > 0`, append:
 ```
-{claims_failed} failure(s) written to .planning/tmp/verify-{doc_filename}.json
+{claims_failed} failure(s) written to {result_path}
 ```
 </output_format>
 
@@ -134,7 +134,7 @@ If `claims_failed > 0`, append:
 - [ ] All five claim categories extracted line-by-line
 - [ ] Skip rules applied during extraction
 - [ ] Each claim verified using filesystem tools only
-- [ ] Result JSON written to `.planning/tmp/verify-{doc_filename}.json`
+- [ ] Result JSON written to the assigned `result_path`
 - [ ] Confirmation returned to orchestrator
 - [ ] `claims_failed` equals `failures.length`
 - [ ] No modifications made to any doc file

package/agents/gsd-doc-verifier.md

@@ -17,6 +17,7 @@ A documentation file has been submitted for factual verification against the liv
 Spawned by the `/gsd:docs-update` workflow. Each spawn receives a `<verify_assignment>` XML block containing:
 - `doc_path`: path to the doc file to verify (relative to project_root)
 - `project_root`: absolute path to project root
+- `result_path`: absolute path of the JSON file to write (always under `project_root`, named by the doc's full relative path so same-named docs never collide)
 
 Extract checkable claims from the doc, verify each against the codebase using filesystem tools only, then write a structured JSON result file. Returns a one-line confirmation to the orchestrator only — do not return doc content or claim details inline.
 
@@ -143,7 +144,7 @@ Count:
 - `failures`: array of `{ line, claim, expected, actual }` objects for each failure
 
 **Step 6: Write result JSON**
-Create `.planning/tmp/` directory if it does not exist. Write the result to `.planning/tmp/verify-{doc_filename}.json` where `{doc_filename}` is the basename of `doc_path` with extension (e.g., `README.md` → `verify-README.md.json`).
+Create the parent directory of `result_path` if it does not exist, then write the result to exactly `result_path` — do not derive a path of your own, and do not write relative to your working directory, which is not guaranteed to be `project_root`.
 
 Use the exact JSON shape from `<output_format>`.
 </verification_process>
@@ -190,7 +191,7 @@ Verification complete for {doc_path}: {claims_passed}/{claims_checked} claims pa
 If `claims_failed > 0`, append:
 
 ```
-{claims_failed} failure(s) written to .planning/tmp/verify-{doc_filename}.json
+{claims_failed} failure(s) written to {result_path}
 ```
 </output_format>
 
@@ -209,7 +210,7 @@ If `claims_failed > 0`, append:
 - [ ] All five claim categories extracted line-by-line
 - [ ] Skip rules applied during extraction
 - [ ] Each claim verified using filesystem tools only
-- [ ] Result JSON written to `.planning/tmp/verify-{doc_filename}.json`
+- [ ] Result JSON written to the assigned `result_path`
 - [ ] Confirmation returned to orchestrator
 - [ ] `claims_failed` equals `failures.length`
 - [ ] No modifications made to any doc file