@opengsd/gsd-pi 1.0.2-dev.e9a1b49 → 1.0.2-dev.fb7ddf1

package/src/resources/extensions/shared/tests/interview-ui-border.test.ts

@@ -0,0 +1,163 @@
+// gsd-pi — Shared interview UI dialog border contract
+
+import assert from "node:assert/strict";
+import { before, describe, it } from "node:test";
+
+import { visibleWidth } from "@gsd/pi-tui";
+import { initTheme } from "@gsd/pi-coding-agent";
+import {
+	showInterviewRound,
+	showWrapUpScreen,
+	type Question,
+	type RoundResult,
+	type WrapUpResult,
+} from "../interview-ui.js";
+
+const ANSI_PATTERN = /\x1b\[[0-9;?]*[ -/]*[@-~]/g;
+const ENTER = "\r";
+const ESC = "\x1b";
+
+before(() => { initTheme(); });
+
+type RenderWidget = {
+	render(width: number): string[];
+	handleInput(input: string): void;
+};
+
+function stripAnsi(text: string): string {
+	return text.replace(ANSI_PATTERN, "");
+}
+
+function assertFullOuterBorder(lines: string[], width: number): void {
+	assert.ok(lines.length >= 2, "dialog must include top and bottom borders");
+
+	for (const [index, line] of lines.entries()) {
+		assert.equal(visibleWidth(line), width, `line ${index} must fill dialog width`);
+	}
+
+	const top = stripAnsi(lines[0] ?? "");
+	const bottom = stripAnsi(lines.at(-1) ?? "");
+	assert.match(top, /^╭.*╮$/, `top border missing full corners: ${top}`);
+	assert.match(bottom, /^╰.*╯$/, `bottom border missing full corners: ${bottom}`);
+
+	for (let index = 1; index < lines.length - 1; index++) {
+		const line = stripAnsi(lines[index] ?? "");
+		assert.match(line, /^[│├]/, `line ${index} missing left border: ${line}`);
+		assert.match(line, /[│┤]$/, `line ${index} missing right border: ${line}`);
+	}
+}
+
+function mockTheme() {
+	return {
+		fg: (_color: string, text: string) => text,
+		bold: (text: string) => text,
+		dim: (text: string) => text,
+		italic: (text: string) => text,
+		strikethrough: (text: string) => text,
+		accent: (text: string) => text,
+		success: (text: string) => text,
+		warning: (text: string) => text,
+		error: (text: string) => text,
+		info: (text: string) => text,
+		muted: (text: string) => text,
+		dimmed: (text: string) => text,
+	};
+}
+
+async function captureInterviewWidget(
+	questions: Question[],
+): Promise<RenderWidget> {
+	let widget: RenderWidget | undefined;
+
+	await showInterviewRound(questions, {}, {
+		ui: {
+			custom: (factory: any) => {
+				widget = factory(
+					{ requestRender: () => {} },
+					mockTheme(),
+					{},
+					(_result: RoundResult) => {},
+				);
+				return Promise.resolve({ endInterview: false, answers: {} });
+			},
+		},
+	} as any);
+
+	assert.ok(widget, "interview widget should be created");
+	return widget;
+}
+
+async function captureWrapUpWidget(): Promise<RenderWidget> {
+	let widget: RenderWidget | undefined;
+
+	await showWrapUpScreen({
+		headline: "Ready to wrap up?",
+		progress: "4 questions answered",
+		keepGoingLabel: "Keep going",
+		satisfiedLabel: "I'm satisfied",
+	}, {
+		ui: {
+			custom: (factory: any) => {
+				widget = factory(
+					{ requestRender: () => {} },
+					mockTheme(),
+					{},
+					(_result: WrapUpResult) => {},
+				);
+				return Promise.resolve({ satisfied: false });
+			},
+		},
+	} as any);
+
+	assert.ok(widget, "wrap-up widget should be created");
+	return widget;
+}
+
+describe("interview-ui dialog borders", () => {
+	const questions: Question[] = [
+		{
+			id: "project_type",
+			header: "Project Type",
+			question: "What type of project?",
+			options: [
+				{ label: "Web App", description: "Frontend or full-stack" },
+				{ label: "CLI Tool", description: "Command-line utility" },
+			],
+		},
+	];
+
+	it("renders the main question screen with a full border", async () => {
+		const widget = await captureInterviewWidget(questions);
+		assertFullOuterBorder(widget.render(80), 80);
+	});
+
+	it("renders the preview split screen with a full border", async () => {
+		const widget = await captureInterviewWidget([{
+			...questions[0],
+			options: [
+				{
+					label: "Web App",
+					description: "Frontend or full-stack",
+					preview: "### Stack\n\nUse React with a typed API boundary.",
+				},
+			],
+		}]);
+		assertFullOuterBorder(widget.render(100), 100);
+	});
+
+	it("renders review and exit confirmation screens with full borders", async () => {
+		const widget = await captureInterviewWidget(questions);
+
+		widget.handleInput(ENTER);
+		assertFullOuterBorder(widget.render(80), 80);
+
+		const exitWidget = await captureInterviewWidget(questions);
+		exitWidget.handleInput(ESC);
+		assertFullOuterBorder(exitWidget.render(80), 80);
+	});
+
+	it("renders the wrap-up screen with a full border", async () => {
+		const widget = await captureWrapUpWidget();
+		assertFullOuterBorder(widget.render(80), 80);
+	});
+});

package/src/resources/extensions/shared/tests/next-action-ui-hasui.test.ts

@@ -15,9 +15,27 @@
 
 import { describe, it } from "node:test";
 import assert from "node:assert/strict";
+import { stripVTControlCharacters } from "node:util";
+import { visibleWidth } from "@gsd/pi-tui";
 
 import { showNextAction } from "../next-action-ui.js";
 
+function assertFullOuterBorder(lines: string[], width: number): void {
+  assert.ok(lines.length >= 2, "dialog must include top and bottom borders");
+  for (const [index, line] of lines.entries()) {
+    assert.equal(visibleWidth(line), width, `line ${index} must fill dialog width`);
+  }
+  const top = stripVTControlCharacters(lines[0] ?? "");
+  const bottom = stripVTControlCharacters(lines.at(-1) ?? "");
+  assert.match(top, /^[╭┌].*[╮┐]$/);
+  assert.match(bottom, /^[╰└].*[╯┘]$/);
+  for (let index = 1; index < lines.length - 1; index++) {
+    const line = stripVTControlCharacters(lines[index] ?? "");
+    assert.match(line, /^[│┃├]/, `line ${index} missing left border: ${line}`);
+    assert.match(line, /[│┃┤]$/, `line ${index} missing right border: ${line}`);
+  }
+}
+
 describe("showNextAction ctx.hasUI guard (#5125 lockup root protection)", () => {
   it("returns 'not_yet' immediately when ctx.hasUI is false (no UI calls)", async () => {
     let customCalled = 0;
@@ -152,4 +170,41 @@ describe("showNextAction ctx.hasUI guard (#5125 lockup root protection)", () =>
     assert.equal(result, "beta", "TUI selection should be returned verbatim");
     assert.equal(selectCalled, 0, "ctx.ui.select fallback must NOT fire when custom returns a value");
   });
+
+  it("renders the interactive next-action menu inside a full border", async () => {
+    let rendered: string[] = [];
+    const theme = {
+      fg: (_color: string, text: string) => text,
+      bold: (text: string) => text,
+    };
+
+    const ctx = {
+      hasUI: true,
+      ui: {
+        custom: async (factory: any) => {
+          let resolved: string | undefined;
+          const component = factory({ requestRender() {} }, theme, null, (value: string) => {
+            resolved = value;
+          });
+          rendered = component.render(80);
+          component.handleInput("\r");
+          return resolved as never;
+        },
+        select: async () => undefined,
+      },
+    };
+
+    const result = await showNextAction(ctx as any, {
+      title: "GSD — test",
+      summary: ["summary"],
+      actions: [
+        { id: "alpha", label: "Alpha", description: "first", recommended: true },
+        { id: "beta", label: "Beta", description: "second" },
+      ],
+    });
+
+    assert.equal(result, "alpha");
+    assertFullOuterBorder(rendered, 80);
+    assert.match(stripVTControlCharacters(rendered[0] ?? ""), /GSD Next Action/);
+  });
 });

package/src/resources/extensions/subagent/index.ts

@@ -732,18 +732,18 @@ const TaskItem = Type.Object({
 	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process" })),
 	model: Type.Optional(Type.String({ description: "Model override for this task (e.g. 'claude-sonnet-4-6')" })),
 	context: Type.Optional(StringEnum(["fresh", "fork"] as const, {
-		description: 'Context mode for this task. "fresh" keeps the existing isolated context behavior; "fork" branches the parent session.',
+		description: 'Context mode for this task (see context field on the top-level params).',
 		default: "fresh",
 	})),
 });
 
 const ChainItem = Type.Object({
 	agent: Type.String({ description: "Name of the agent to invoke" }),
-	task: Type.String({ description: "Task with optional {previous} placeholder for prior output" }),
+	task: Type.String({ description: "Task with optional {previous} placeholder for prior step output" }),
 	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process" })),
 	model: Type.Optional(Type.String({ description: "Model override for this step (e.g. 'claude-sonnet-4-6')" })),
 	context: Type.Optional(StringEnum(["fresh", "fork"] as const, {
-		description: 'Context mode for this step. "fresh" keeps the existing isolated context behavior; "fork" branches the parent session.',
+		description: 'Context mode for this step (see context field on the top-level params).',
 		default: "fresh",
 	})),
 });
@@ -817,21 +817,14 @@ export default function (pi: ExtensionAPI) {
 		name: "subagent",
 		label: "Subagent",
 		description: [
-			"Delegate tasks to specialized subagents with isolated context windows.",
-			"Each subagent is a separate pi process with its own tools, model, and system prompt.",
-			"Modes: single ({ agent, task }), parallel ({ tasks: [{agent, task},...] }), chain ({ chain: [{agent, task},...] } with {previous} placeholder).",
-			"Agents are defined as .md files in ~/.gsd/agent/agents/ (user) or .gsd/agents/ (project).",
-			"Use the /subagent command to list available agents and their descriptions.",
-			"Use chain mode to pipeline: scout finds context, planner designs, worker implements.",
+			"Delegate tasks to specialized subagents, each a separate pi process with its own isolated context window, tools, model, and system prompt.",
+			"Modes: single ({ agent, task }), parallel ({ tasks: [{agent, task},...] }), chain ({ chain: [{agent, task},...] } where each step's {previous} placeholder receives the prior output).",
+			"Agents are defined as .md files in ~/.gsd/agent/agents/ (user) or .gsd/agents/ (project); list them with the /subagent command.",
 		].join(" "),
 		promptGuidelines: [
-			"Prefer subagent dispatch over inline work whenever a task is self-contained — recon, planning, review, refactor, test writing, security audit, doc writing. Each dispatch gets a fresh context window, so your main session stays focused on synthesis.",
-			"Before reading more than ~3 files to understand something, dispatch the scout agent and work from its compressed report instead.",
-			"Before any change touching ≥2 packages, the orchestration kernel, auto-mode, or a public API, dispatch the planner agent first. Plan first, then implement.",
+			"Prefer subagent dispatch over inline work for self-contained tasks (recon, planning, review, refactor, test writing, security audit, docs); each dispatch gets a fresh context window so the main session stays focused on synthesis.",
 			"You MUST use parallel mode when ≥2 ready tasks are independent of each other's output. Do not serialize independent tasks manually — that wastes wall time and context.",
-			"Use chain mode for sequential pipelines where each step's output feeds the next: scout → planner → worker, or worker → reviewer → worker.",
-			"Before opening a PR or marking a slice complete, dispatch the reviewer agent (and security agent if the change touches auth, network, parsing, file IO, or shell exec).",
-			"Always check available agents with /subagent before choosing one — there are bundled specialists plus any project-scoped agents.",
+			"Check available agents with /subagent before choosing one — there are bundled specialists plus any project-scoped agents.",
 		],
 		parameters: SubagentParams,
 

package/src/resources/shared/package-manager-detection.ts

@@ -0,0 +1,39 @@
+import { homedir } from 'node:os'
+import { join, resolve as resolvePath, sep } from 'node:path'
+
+function hasPnpmPath(value: string | undefined): boolean {
+  if (!value) return false
+  const normalized = value.replace(/\\/g, '/').toLowerCase()
+  return (
+    normalized.includes('/.pnpm/') ||
+    normalized.endsWith('/pnpm') ||
+    normalized.endsWith('/pnpm.cjs') ||
+    normalized.endsWith('/pnpm.js')
+  )
+}
+
+function pathStartsWith(pathValue: string | undefined, dir: string): boolean {
+  if (!pathValue) return false
+  const resolvedPath = resolvePath(pathValue)
+  const resolvedDir = resolvePath(dir)
+  return resolvedPath === resolvedDir || resolvedPath.startsWith(resolvedDir + sep)
+}
+
+// Shared by update-check.ts and gsd command handlers. The JS installer keeps a
+// parallel copy because it runs before TypeScript output exists.
+export function isPnpmInstall(
+  argv1: string | undefined = process.argv[1],
+  env: NodeJS.ProcessEnv = process.env,
+): boolean {
+  if (env.npm_config_user_agent?.startsWith('pnpm/')) return true
+  if (hasPnpmPath(env.npm_execpath)) return true
+  if (hasPnpmPath(argv1)) return true
+  if (!argv1) return false
+
+  const pnpmBinDirs: string[] = []
+  if (env.PNPM_HOME) pnpmBinDirs.push(env.PNPM_HOME)
+  pnpmBinDirs.push(join(homedir(), 'Library', 'pnpm'))
+  pnpmBinDirs.push(join(homedir(), '.local', 'share', 'pnpm'))
+
+  return pnpmBinDirs.some((dir) => pathStartsWith(argv1, dir) || pathStartsWith(env.npm_execpath, dir))
+}

package/src/resources/skills/agent-browser/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-browser
-description: Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to "open a website", "fill out a form", "click a button", "take a screenshot", "scrape data from a page", "test this web app", "login to a site", "automate browser actions", or any task requiring programmatic web interaction.
+description: Browser automation CLI for AI agents. Use when interacting with websites — navigating pages, filling forms, clicking buttons, taking screenshots, scraping/extracting data, logging in, or testing web apps. Triggers on "open a website", "fill out a form", "take a screenshot", "scrape data from a page", "test this web app", "automate browser actions", or any programmatic web interaction.
 allowed-tools: Bash(npx agent-browser:*), Bash(agent-browser:*)
 ---
 

package/src/resources/skills/api-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: api-design
-description: Design or review an HTTP/REST/GraphQL API for versioning, pagination, error shapes, idempotency, auth, and evolvability. Use when asked to "design an API", "shape the endpoints", "design the schema", "add a new endpoint", "review this API", or when building/modifying a public or internal HTTP surface. Complements `design-an-interface` (which is interface-agnostic) by covering HTTP-specific concerns like status codes, cache headers, and breaking-change management.
+description: Design or review an HTTP/REST/GraphQL API for versioning, pagination, error shapes, idempotency, auth, status codes, cache headers, and breaking-change management. Use when asked to "design an API", "shape the endpoints", "design the schema", "add a new endpoint", "review this API", or when building/modifying a public or internal HTTP surface. HTTP-specific complement to `design-an-interface`.
 ---
 
 <objective>

package/src/resources/skills/code-optimizer/SKILL.md

@@ -1,17 +1,12 @@
 ---
 name: code-optimizer
 description: >
-  Deep code optimization audit using parallel specialist agents. Each agent hunts for performance
-  anti-patterns, inefficiencies, and suboptimal code using pattern-based detection (Grep/Glob)
-  WITHOUT reading the full source code first — avoiding anchoring bias on existing implementations.
-  Covers ALL optimization domains: database queries, memory leaks, algorithmic complexity,
-  concurrency, bundle size, dead code, I/O & network, rendering/UI, data structures,
-  error handling, caching, build config, security-performance, logging, and infrastructure.
-  Use when asked to: "optimize my code", "find performance issues", "audit code quality",
-  "speed up my app", "find bottlenecks", "code review for performance", "find anti-patterns",
-  "improve code efficiency", "reduce latency", "optimize performance", "code smell detection",
-  "find slow code", "optimize this project", "performance audit", "code optimization".
-  Also triggers on: "optimizar codigo", "encontrar cuellos de botella", "mejorar rendimiento".
+  Deep code optimization audit using parallel specialist agents that hunt performance
+  anti-patterns via pattern-based detection, avoiding anchoring bias. Covers DB queries,
+  memory leaks, algorithmic complexity, concurrency, bundle size, dead code, I/O/network,
+  rendering, caching, and build config. Use when asked to optimize code, find performance
+  issues or bottlenecks, speed up an app, reduce latency, detect code smells, or run a
+  performance/quality audit.
 ---
 
 # Code Optimizer

package/src/resources/skills/create-gsd-extension/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: create-gsd-extension
-description: Create, debug, and iterate on GSD extensions (TypeScript modules that add tools, commands, event hooks, custom UI, and providers to GSD). Use when asked to build an extension, add a tool the LLM can call, register a slash command, hook into GSD events, create custom TUI components, or modify GSD behavior. Triggers on "create extension", "build extension", "add a tool", "register command", "hook into gsd", "custom tool", "gsd plugin", "gsd extension".
+description: Create, debug, and iterate on GSD extensions (TypeScript modules adding tools, commands, event hooks, custom UI, and providers). Use when asked to build an extension, add a tool the LLM can call, register a slash command, hook into GSD events, create custom TUI components, or modify GSD behavior. Triggers on "create/build extension", "add a tool", "register command", "hook into gsd", "gsd plugin".
 ---
 
 <essential_principles>

package/src/resources/skills/create-mcp-server/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: create-mcp-server
-description: Build, iterate, and evaluate Model Context Protocol (MCP) servers that expose external services as tools an LLM can call. Use when asked to "build an MCP server", "create an MCP tool", "wrap this API as MCP", "expose X to Claude", or when extending GSD with custom tool integrations. Covers research, schema/tool design, error handling, pagination, testing via MCP Inspector, and producing a 10-question eval set that proves the server actually enables real work.
+description: Build, iterate, and evaluate Model Context Protocol (MCP) servers that expose external services as tools an LLM can call. Covers schema/tool design, error handling, pagination, MCP Inspector testing, and an eval set. Use when asked to "build an MCP server", "create an MCP tool", "wrap this API as MCP", "expose X to Claude", or when extending GSD with custom tool integrations.
 ---
 
 <objective>

package/src/resources/skills/create-skill/references/gsd-skill-ecosystem.md

@@ -31,7 +31,7 @@ GSD auto-discovers skills at session start and during auto-mode:
 
 **Session start:** All discovered skills are enumerated and their names + descriptions are injected into the system prompt as `<available_skills>`.
 
-**Auto-mode discovery:** `skill-discovery.ts` takes a snapshot of the skills directory at auto-mode start. On each unit boundary it diffs against the snapshot. Any new skills found are injected via a `<newly_discovered_skills>` XML block so the LLM sees them without requiring `/reload`.
+**Auto-mode discovery:** `skill-discovery.ts` snapshots installed skill names at auto-mode start. When new skills appear mid-run, GSD reloads the resource catalog so they appear in the standard `<available_skills>` block (no separate XML injection).
 
 **Manual reload:** Running `/reload` re-scans the skill directories and updates the available skills list mid-session.
 </skill_discovery>

package/src/resources/skills/create-skill/workflows/verify-skill.md

@@ -82,11 +82,7 @@ which {tool-name}
 ```
 
 ### For API/Service Skills
-Use Context7 to fetch current documentation:
-```
-mcp__context7__resolve-library-id: {service-name}
-mcp__context7__get-library-docs: {library-id}, topic: {relevant-topic}
-```
+Use the active Context7 documentation tools to fetch current documentation if they are available. Resolve the library ID first, then fetch docs for `{library-id}` with `topic: {relevant-topic}`; use the exact tool names from the active tool list.
 
 Compare skill's documented patterns against current docs:
 - Are endpoints still valid?
@@ -94,11 +90,7 @@ Compare skill's documented patterns against current docs:
 - Are there deprecated methods being used?
 
 ### For Framework Skills
-Use Context7:
-```
-mcp__context7__resolve-library-id: {framework-name}
-mcp__context7__get-library-docs: {library-id}, topic: {specific-api}
-```
+Use the active Context7 documentation tools if they are available. Resolve the library ID first, then fetch docs for `{library-id}` with `topic: {specific-api}`; use the exact tool names from the active tool list.
 
 Check:
 - Are documented APIs still current?

package/src/resources/skills/debug-like-expert/references/when-to-research.md

@@ -175,11 +175,7 @@ DO reason through it:
 - Learning correct usage patterns
 
 **How**:
-```
-Use mcp__context7__resolve-library-id with library name
-Then mcp__context7__get-library-docs with library ID
-Ask specific questions about the library
-```
+Use the active Context7 documentation tools if they are available: resolve the library ID with the library name, then fetch docs with the library ID. Ask specific questions about the library, and use exact tool names from the active tool list.
 
 **Good uses**:
 - "How do I use Prisma transactions?"

package/src/resources/skills/decompose-into-slices/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: decompose-into-slices
-description: Break a plan or milestone brief into independently-grabbable vertical slices (tracer bullets). Produces slices in `M###-ROADMAP.md` by default, or GitHub issues only with explicit user confirmation. Use when asked to "break this into slices", "decompose the plan", "vertical slices", "break into issues", or when a plan is ready but needs task-level decomposition. Prefers many thin slices over few thick ones; marks dependency order explicitly.
+description: Break a plan or milestone brief into independently-grabbable vertical slices (tracer bullets), written to `M###-ROADMAP.md` by default (GitHub issues only on explicit confirmation). Prefers many thin slices over few thick ones and marks dependency order. Use when asked to "break this into slices", "decompose the plan", "vertical slices", "break into issues", or when a plan needs task-level decomposition.
 ---
 
 <objective>
@@ -31,7 +31,7 @@ Typical invocation points:
 1. Read `M###-CONTEXT.md` for the active milestone — the brief is the source of truth for scope.
 2. Read `M###-ROADMAP.md` if one exists — you may be refining rather than creating from scratch.
 3. Read `src/resources/extensions/gsd/templates/roadmap.md` for the exact slice format. The parser depends on it.
-4. If the plan came from a GitHub issue (user passed a URL or number), fetch it with `mcp__github__issue_read`.
+4. If the plan came from a GitHub issue (user passed a URL or number), fetch it with the active GitHub issue-read tool if one is available; use the exact tool name from the active tool list.
 
 ## Step 2: Explore the codebase briefly
 
@@ -84,7 +84,7 @@ Use `write` to the path `.gsd/milestones/<MID>/<MID>-ROADMAP.md`. Do not edit ch
 
 ## Step 6: Optionally file as GitHub issues
 
-If the user explicitly asks (and only if — outward actions need confirmation), create one GitHub issue per slice with `mcp__github__issue_write`. Create in dependency order so "Blocked by" references can cite real issue numbers.
+If the user explicitly asks (and only if — outward actions need confirmation), create one GitHub issue per slice with the active GitHub issue-write tool if one is available; use the exact tool name from the active tool list. Create in dependency order so "Blocked by" references can cite real issue numbers.
 
 ### Issue body template
 

package/src/resources/skills/dependency-upgrade/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dependency-upgrade
-description: Plan, batch, and verify dependency upgrades safely. Triages outdated packages into risk tiers, upgrades in order (dev/minor/patch first, runtime majors last), verifies each batch before moving on, and produces an auditable commit sequence. Use when asked to "upgrade deps", "bump packages", "update node_modules", "fix vulnerabilities", "upgrade React/Node/TypeScript", or after `/gsd start dep-upgrade`. Complements the dep-upgrade workflow template with execution-level rigor.
+description: Plan, batch, and verify dependency upgrades safely. Triages outdated packages into risk tiers, upgrades in order (dev/minor/patch first, runtime majors last), verifies each batch, and produces an auditable commit sequence. Use when asked to "upgrade deps", "bump packages", "update node_modules", "fix vulnerabilities", "upgrade React/Node/TypeScript", or after `/gsd start dep-upgrade`.
 ---
 
 <objective>

package/src/resources/skills/forensics/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: forensics
-description: Post-mortem a failed GSD auto-mode run. Traces from symptom to root cause using `.gsd/activity/*.jsonl`, `.gsd/journal/YYYY-MM-DD.jsonl`, `.gsd/metrics.json`, and `.gsd/auto.lock`. Produces a filing-ready bug report with file:line references and a concrete fix suggestion. Use when asked to "forensics", "post-mortem", "why did auto-mode fail", "trace the stuck loop", "debug the crash", after `/gsd forensics` is invoked, or when a session ended in an unexpected terminal state. Reads existing artifacts — does NOT re-run anything.
+description: Post-mortem a failed GSD auto-mode run. Traces symptom to root cause via `.gsd/` activity, journal, metrics, and lock artifacts, producing a filing-ready bug report with file:line refs and a fix suggestion. Use when asked to "forensics", "post-mortem", "why did auto-mode fail", "trace the stuck loop", "debug the crash", after `/gsd forensics`, or when a session ended in an unexpected terminal state. Reads artifacts only — re-runs nothing.
 ---
 
 <objective>
@@ -126,7 +126,7 @@ Format the output as a GitHub-issue-ready report:
 <high / medium / low> — <what would change this confidence>
 ```
 
-Offer to file this as a GitHub issue via `mcp__github__issue_write` — explicit confirmation required per the outward-action rule. Also save a copy to `.gsd/forensics/<slug>.md` for future reference.
+Offer to file this as a GitHub issue via the active GitHub issue-write tool if one is available, using its exact active tool name — explicit confirmation required per the outward-action rule. Also save a copy to `.gsd/forensics/<slug>.md` for future reference.
 
 </process>
 

package/src/resources/skills/grill-me/SKILL.md

@@ -66,7 +66,7 @@ At the end, offer the user one of:
 
 1. Append resolved decisions to `.gsd/DECISIONS.md` (one line each, dated).
 2. Write or update `M###-CONTEXT.md` or `S##-CONTEXT.md` for the active milestone/slice.
-3. Draft a GitHub issue via `mcp__github__issue_write` (only with explicit confirmation per the outward-action rule).
+3. Draft a GitHub issue via the active GitHub issue-write tool if one is available, using its exact active tool name (only with explicit confirmation per the outward-action rule).
 4. Leave it as conversation context if the work is ephemeral.
 
 Default: ask which they want. Do not auto-write.

package/src/resources/skills/handoff/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: handoff
-description: Prepare a clean cross-session handoff so the next agent (or you tomorrow) can pick up exactly where you left off. Writes a focused `continue.md` in the active slice directory and ensures `STATE.md` + summary artifacts are current. Use when asked to "hand off", "prepare handoff", "pause work", "bookmark this", "I'll come back to this later", before running out of context budget, or at the end of a long session with unfinished work. Closes the v1 `/gsd-pause-work` parity gap.
+description: Prepare a clean cross-session handoff so the next agent can pick up where you left off. Writes a focused `continue.md` in the active slice dir and ensures `STATE.md` + summary artifacts are current. Use when asked to "hand off", "prepare handoff", "pause work", "bookmark this", "I'll come back to this later", before running out of context budget, or ending a long session with unfinished work.
 ---
 
 <objective>

package/src/resources/skills/make-interfaces-feel-better/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: make-interfaces-feel-better
-description: Design engineering principles for making interfaces feel polished. Use when building UI components, reviewing frontend code, implementing animations, hover states, shadows, borders, typography, micro-interactions, enter/exit animations, or any visual detail work. Triggers on UI polish, design details, "make it feel better", "feels off", stagger animations, border radius, optical alignment, font smoothing, tabular numbers, image outlines, box shadows.
+description: Design-engineering principles for making interfaces feel polished. Use when building UI components or doing visual detail work — animations, hover states, shadows, borders, typography, micro-interactions. Triggers on "make it feel better", "feels off", stagger animations, border radius, optical alignment, font smoothing, tabular numbers, box shadows.
 ---
 
 # Details that make interfaces feel better

package/src/resources/skills/observability/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: observability
-description: Add agent-first observability to code — structured logs, health endpoints, failure-state persistence, and explicit failure modes — so the next agent hitting a problem at 3am has the signals it needs to diagnose. Use when asked to "add logging", "add observability", "add metrics", "debug later", "make this observable", or when building/refactoring a subsystem that will run unattended (auto-mode engine, background jobs, servers, watchers). Operationalizes VISION.md's "agent-first observability" principle.
+description: Add agent-first observability — structured logs, health endpoints, failure-state persistence, explicit failure modes — so the next agent can diagnose problems unattended. Use when asked to "add logging", "add observability", "add metrics", "make this observable", or when building/refactoring a subsystem that runs unattended (auto-mode engine, background jobs, servers, watchers).
 ---
 
 <objective>

package/src/resources/skills/security-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: security-review
-description: Threat-model-driven security review of a change, feature, or subsystem. Runs a STRIDE-style pass (Spoofing, Tampering, Repudiation, Info disclosure, Denial of service, Elevation of privilege), examines the actual code, and produces a filing-ready report with severity, exploit scenario, and concrete remediation. Use when asked to "security review", "threat model", "check for vulnerabilities", "audit this for security", "secure this", or before shipping any change that touches auth, input handling, data access, or external surfaces.
+description: Threat-model-driven security review of a change, feature, or subsystem. Runs a STRIDE-style pass over the actual code and produces a filing-ready report with severity, exploit scenario, and remediation. Use when asked to "security review", "threat model", "check for vulnerabilities", "audit for security", "secure this", or before shipping changes touching auth, input handling, data access, or external surfaces.
 ---
 
 <objective>

package/src/resources/skills/spike-wrap-up/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: spike-wrap-up
-description: Package findings from a completed spike into a durable, project-local skill that auto-loads on future similar work. Reads the most recent `.gsd/workflows/spikes/` directory, interviews the user briefly on what's reusable, then writes `.claude/skills/<name>/SKILL.md`. Use when asked to "wrap up the spike", "package this as a skill", "make this reusable", "turn findings into a skill", or at the end of the synthesize phase of `/gsd start spike`. Closes the parity gap with GSD v1's `/gsd-spike-wrap-up`.
+description: Package findings from a completed spike into a durable project-local skill that auto-loads on future similar work. Reads the latest `.gsd/workflows/spikes/` dir, interviews the user on what's reusable, then writes `.claude/skills/<name>/SKILL.md`. Use when asked to "wrap up the spike", "package this as a skill", "make this reusable", "turn findings into a skill", or at the synthesize phase of `/gsd start spike`.
 ---
 
 <objective>

package/src/resources/skills/tdd/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tdd
-description: Test-driven development with red-green-refactor loops built around vertical slices (tracer bullets), not horizontal layers. Use when asked to "use TDD", "write test-first", "red-green-refactor", "build this with tests", or whenever a feature has a clear observable contract and would benefit from tests that outlive refactors. Complements the bundled test and add-tests skills — use this for the discipline, use those for the mechanics.
+description: Test-driven development with red-green-refactor loops around vertical slices (tracer bullets), not horizontal layers. Use when asked to "use TDD", "write test-first", "red-green-refactor", "build this with tests", or when a feature has a clear observable contract. The discipline complement to the test/add-tests skills (the mechanics).
 ---
 
 <objective>

package/src/resources/skills/write-docs/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: write-docs
 description: >-
-  Collaborative document authoring workflow for proposals, technical specs, decision docs, README sections, ADRs, and long-form prose that must work for fresh readers. Use when asked to "write the docs", "draft a proposal", "write a spec", "write an RFC", "write the README", or when a document needs to be understandable by someone without this session's context. Three stages: gather context, iterate on structure, reader-test for a stranger.
+  Collaborative authoring workflow for proposals, technical specs, decision docs, READMEs, ADRs, and long-form prose that must work for fresh readers. Three stages: gather context, iterate on structure, reader-test for a stranger. Use when asked to "write the docs", "draft a proposal", "write a spec", "write an RFC", "write the README", or when a doc must be understandable without this session's context.
 ---
 
 <objective>

package/src/resources/skills/write-milestone-brief/SKILL.md

@@ -78,7 +78,7 @@ Then append a one-line summary to `.gsd/DECISIONS.md` for any genuinely hard-to-
 After writing, offer the user (do not auto-execute):
 
 1. **Proceed to planning** — run `/gsd dispatch plan` to generate `M###-ROADMAP.md` from this brief.
-2. **File as GitHub issue** — use `mcp__github__issue_write` to create a tracking issue. Requires explicit "yes" per the outward-action rule. Use the PRD template below for the body.
+2. **File as GitHub issue** — use the active GitHub issue-write tool if one is available, using its exact active tool name. Requires explicit "yes" per the outward-action rule. Use the PRD template below for the body.
 3. **Iterate on the brief** — if something feels wrong, run `grill-me` to stress-test before moving on.
 
 ### GitHub issue body template (only if user chooses option 2)