@opengsd/gsd-pi 1.2.0-dev.844675c9 → 1.2.0-dev.84c56d87

package/dist/resources/extensions/shared/gsd-browser-cli.js

@@ -38,6 +38,12 @@ function compareSemverLocal(a, b) {
 function parseGsdBrowserVersion(output) {
     return output.match(/\b(\d+\.\d+\.\d+)\b/)?.[1] ?? null;
 }
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function resolveExplicitGsdBrowserCliPath(env) {
+    return env.GSD_BROWSER_CLI_PATH?.trim() || env.GSD_BROWSER_BIN_PATH?.trim() || undefined;
+}
 function resolveBundledGsdBrowserPackageVersion() {
     try {
         const requireFromHere = createRequire(import.meta.url);
@@ -49,12 +55,19 @@ function resolveBundledGsdBrowserPackageVersion() {
         return null;
     }
 }
+// The `gsd-browser --version` subprocess result cannot change mid-session (the
+// engine-switch guard forbids restarting with a different engine), and both the
+// availability probe and the launch-config resolution ask for it at session
+// start — memoize so the up-to-2s spawn happens once per process.
+let cachedPathProbeVersion;
 function resolvePathGsdBrowserVersion(env) {
     const explicit = env.GSD_BROWSER_PATH_VERSION?.trim();
     if (explicit)
         return parseGsdBrowserVersion(explicit);
+    if (cachedPathProbeVersion !== undefined)
+        return cachedPathProbeVersion;
     try {
-        return parseGsdBrowserVersion(execFileSync("gsd-browser", ["--version"], {
+        cachedPathProbeVersion = parseGsdBrowserVersion(execFileSync("gsd-browser", ["--version"], {
             encoding: "utf-8",
             env,
             stdio: ["ignore", "pipe", "ignore"],
@@ -62,8 +75,9 @@ function resolvePathGsdBrowserVersion(env) {
         }));
     }
     catch {
-        return null;
+        cachedPathProbeVersion = null;
     }
+    return cachedPathProbeVersion;
 }
 function shouldPreferPathGsdBrowser(env) {
     const pathVersion = resolvePathGsdBrowserVersion(env);
@@ -73,7 +87,7 @@ function shouldPreferPathGsdBrowser(env) {
     return !bundledVersion || compareSemverLocal(pathVersion, bundledVersion) > 0;
 }
 export function resolveBundledGsdBrowserCliPath(env = process.env) {
-    const explicit = env.GSD_BROWSER_CLI_PATH?.trim() || env.GSD_BROWSER_BIN_PATH?.trim();
+    const explicit = resolveExplicitGsdBrowserCliPath(env);
     if (explicit)
         return explicit;
     try {
@@ -96,6 +110,36 @@ export function resolveBundledGsdBrowserCliPath(env = process.env) {
     }
     return null;
 }
+/**
+ * Cheap availability probe for the gsd-browser CLI: explicit env overrides,
+ * then the bundled @opengsd/gsd-browser binary (filesystem checks only), then
+ * a PATH lookup (one short subprocess, memoized). Used by Browser Automation
+ * Engine resolution to decide whether the managed engine is provable before
+ * preferring it over legacy Playwright. `via` names the provable source, not
+ * necessarily the launch source — resolveGsdBrowserMcpLaunchConfig may still
+ * prefer a newer PATH CLI over the bundled one.
+ */
+export function resolveGsdBrowserCliAvailability(env = process.env) {
+    const explicitCommand = env.GSD_BROWSER_MCP_COMMAND?.trim();
+    if (explicitCommand) {
+        return { available: true, via: "explicit-env", detail: `GSD_BROWSER_MCP_COMMAND=${explicitCommand}` };
+    }
+    const explicitCliPath = resolveExplicitGsdBrowserCliPath(env);
+    if (explicitCliPath) {
+        return existsSync(explicitCliPath)
+            ? { available: true, via: "explicit-env", detail: `CLI at ${explicitCliPath}` }
+            : { available: false, detail: `configured gsd-browser CLI path does not exist: ${explicitCliPath}` };
+    }
+    const bundledCliPath = resolveBundledGsdBrowserCliPath(env);
+    if (bundledCliPath) {
+        return { available: true, via: "bundled", detail: `bundled CLI at ${bundledCliPath}` };
+    }
+    const pathVersion = resolvePathGsdBrowserVersion(env);
+    if (pathVersion) {
+        return { available: true, via: "path", detail: `gsd-browser ${pathVersion} on PATH` };
+    }
+    return { available: false, detail: "no bundled or PATH gsd-browser CLI found" };
+}
 export function buildGsdBrowserSessionName(projectRoot, suffix) {
     const resolvedProjectRoot = resolve(projectRoot);
     const base = sanitizeSessionSegment(basename(resolvedProjectRoot)) || "project";
@@ -103,13 +147,37 @@ export function buildGsdBrowserSessionName(projectRoot, suffix) {
     const cleanSuffix = suffix ? sanitizeSessionSegment(suffix) : "";
     return cleanSuffix ? `gsd-${base}-${hash}-${cleanSuffix}` : `gsd-${base}-${hash}`;
 }
+/**
+ * Recognize an MCP server config (from .mcp.json / Claude settings) as a
+ * gsd-browser server. Paired with resolveGsdBrowserMcpLaunchConfig: this module
+ * writes the config shape, so it also owns recognizing it. New launch shapes
+ * are taught here, in one place.
+ */
+export function isGsdBrowserMcpServerConfig(config) {
+    if (!isRecord(config))
+        return false;
+    const command = typeof config.command === "string" ? config.command : "";
+    if (command.includes("gsd-browser") || command.includes("@opengsd/gsd-browser")) {
+        return true;
+    }
+    if (isRecord(config.env)) {
+        const env = config.env;
+        if (typeof env.GSD_BROWSER_CLI_PATH === "string"
+            || typeof env.GSD_BROWSER_BIN_PATH === "string"
+            || typeof env.GSD_BROWSER_MCP_COMMAND === "string") {
+            return true;
+        }
+    }
+    const args = Array.isArray(config.args) ? config.args.filter((arg) => typeof arg === "string") : [];
+    return args.some((arg) => arg.includes("gsd-browser") || arg.includes("@opengsd/gsd-browser"));
+}
 export function resolveGsdBrowserMcpLaunchConfig(projectRoot, env = process.env, options = {}) {
     const resolvedProjectRoot = resolve(projectRoot);
     const serverName = env.GSD_BROWSER_MCP_NAME?.trim() || GSD_BROWSER_MCP_SERVER_NAME;
     const explicitArgs = parseJsonEnv(env, "GSD_BROWSER_MCP_ARGS");
     const explicitEnv = parseJsonEnv(env, "GSD_BROWSER_MCP_ENV");
     const explicitCommand = env.GSD_BROWSER_MCP_COMMAND?.trim();
-    const explicitCliPath = env.GSD_BROWSER_CLI_PATH?.trim() || env.GSD_BROWSER_BIN_PATH?.trim();
+    const explicitCliPath = resolveExplicitGsdBrowserCliPath(env);
     const preferPathCli = !explicitCommand && !explicitCliPath && shouldPreferPathGsdBrowser(env);
     const bundledCliPath = !explicitCommand && !explicitCliPath && !preferPathCli
         ? resolveBundledGsdBrowserCliPath(env)

package/dist/resources/extensions/shared/interview-ui.js

@@ -146,7 +146,7 @@ export async function showInterviewRound(questions, opts, ctx) {
         }
         // External cancellation (e.g. remote channel won the race)
         if (opts.signal) {
-            const onAbort = () => finish({ endInterview: false, answers: {} });
+            const onAbort = () => finish({ endInterview: false, answers: {}, interrupted: true });
             if (opts.signal.aborted) {
                 onAbort();
             }
@@ -800,5 +800,5 @@ export async function showInterviewRound(questions, opts, ctx) {
             invalidate: () => { cachedLines = undefined; },
             handleInput,
         };
-    });
+    }, opts.overlay ? { overlay: true } : undefined);
 }

package/dist/resources/shared/claude-runtime-floor.js

@@ -0,0 +1,182 @@
+import { execFileSync as nodeExecFileSync } from 'node:child_process';
+import { existsSync as nodeExistsSync, realpathSync as nodeRealpathSync, readFileSync as nodeReadFileSync } from 'node:fs';
+import { delimiter, dirname, extname, join, resolve as resolvePath } from 'node:path';
+export const CLAUDE_CODE_RUNTIME_FLOOR = '2.1.168';
+export const CLAUDE_CODE_PROVIDER = 'claude-code';
+export const CLAUDE_CODE_PACKAGE = '@anthropic-ai/claude-code';
+const VERSION_TIMEOUT_MS = 5_000;
+function compareVersionTriplets(a, b) {
+    const left = a.split('.').map(Number);
+    const right = b.split('.').map(Number);
+    for (let index = 0; index < Math.max(left.length, right.length); index++) {
+        const leftValue = left[index] || 0;
+        const rightValue = right[index] || 0;
+        if (leftValue > rightValue)
+            return 1;
+        if (leftValue < rightValue)
+            return -1;
+    }
+    return 0;
+}
+export function parseClaudeRuntimeVersion(output) {
+    return output.match(/\b(\d+\.\d+\.\d+)\b/)?.[1] ?? null;
+}
+export function isClaudeCodeConfigured(settings) {
+    if (settings.defaultProvider === CLAUDE_CODE_PROVIDER)
+        return true;
+    return settings.defaultModel?.startsWith(`${CLAUDE_CODE_PROVIDER}/`) ?? false;
+}
+function readSettingsFile(path, deps) {
+    try {
+        if (!deps.existsSync(path))
+            return {};
+        const raw = JSON.parse(deps.readFileSync(path, 'utf-8'));
+        return {
+            ...(typeof raw.defaultProvider === 'string' ? { defaultProvider: raw.defaultProvider } : {}),
+            ...(typeof raw.defaultModel === 'string' ? { defaultModel: raw.defaultModel } : {}),
+        };
+    }
+    catch {
+        return {};
+    }
+}
+export function loadClaudeRuntimeSettings(options) {
+    const deps = {
+        existsSync: options.existsSync ?? nodeExistsSync,
+        readFileSync: options.readFileSync ?? nodeReadFileSync,
+    };
+    const globalSettings = readSettingsFile(join(options.agentDir, 'settings.json'), deps);
+    const projectSettings = options.cwd
+        ? readSettingsFile(join(options.cwd, '.gsd', 'settings.json'), deps)
+        : {};
+    return {
+        ...globalSettings,
+        ...projectSettings,
+    };
+}
+export function buildClaudeSpawnInvocation(command, args, platform = process.platform) {
+    if (platform === 'win32') {
+        return { command: 'cmd', args: ['/c', command, ...args] };
+    }
+    return { command, args };
+}
+export function getClaudeRuntimeCommandCandidates(platform = process.platform) {
+    return platform === 'win32' ? ['claude.cmd', 'claude.exe', 'claude'] : ['claude'];
+}
+function pathEntries(env) {
+    return (env.PATH ?? '')
+        .split(delimiter)
+        .map(entry => entry.trim())
+        .filter(Boolean);
+}
+function executableNames(command, env, platform) {
+    if (platform !== 'win32' || extname(command))
+        return [command];
+    const extensions = (env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD')
+        .split(';')
+        .map(value => value.trim().toLowerCase())
+        .filter(Boolean);
+    return [command, ...extensions.map(extension => `${command}${extension}`)];
+}
+export function resolveExecutablePath(command, env = process.env, platform = process.platform, existsSync = nodeExistsSync) {
+    if (dirname(command) !== '.') {
+        return existsSync(command) ? resolvePath(command) : null;
+    }
+    for (const entry of pathEntries(env)) {
+        for (const name of executableNames(command, env, platform)) {
+            const candidate = join(entry, name);
+            if (existsSync(candidate))
+                return resolvePath(candidate);
+        }
+    }
+    return null;
+}
+function realpathOrNull(path, realpathSync) {
+    if (!path)
+        return null;
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return path;
+    }
+}
+export function probeClaudeRuntime(options = {}) {
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const execFileSync = options.execFileSync ?? nodeExecFileSync;
+    const existsSync = options.existsSync ?? nodeExistsSync;
+    const realpathSync = options.realpathSync ?? nodeRealpathSync;
+    for (const command of getClaudeRuntimeCommandCandidates(platform)) {
+        try {
+            const invocation = buildClaudeSpawnInvocation(command, ['--version'], platform);
+            const output = execFileSync(invocation.command, invocation.args, {
+                encoding: 'utf-8',
+                env,
+                stdio: ['ignore', 'pipe', 'ignore'],
+                timeout: VERSION_TIMEOUT_MS,
+            });
+            const version = parseClaudeRuntimeVersion(String(output));
+            if (!version)
+                continue;
+            const displayPath = resolveExecutablePath(command, env, platform, existsSync);
+            return {
+                command,
+                displayPath,
+                realPath: realpathOrNull(displayPath, realpathSync),
+                version,
+            };
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+function normalizedPath(value) {
+    return (value ?? '').replace(/\\/g, '/').toLowerCase();
+}
+export function inferClaudeRuntimeUpgradeCommand(probe, platform = process.platform) {
+    const combined = `${normalizedPath(probe.displayPath)}\n${normalizedPath(probe.realPath)}`;
+    if (combined.includes('/.pnpm/') && combined.includes('@anthropic-ai+claude-code@')) {
+        return { command: `pnpm add -g ${CLAUDE_CODE_PACKAGE}@latest`, source: 'pnpm' };
+    }
+    if (combined.includes('/node_modules/') && combined.includes('/@anthropic-ai/claude-code/')) {
+        return { command: `npm install -g ${CLAUDE_CODE_PACKAGE}@latest`, source: 'npm' };
+    }
+    if (combined.includes('/.bun/') || combined.includes('/bun/install/global/')) {
+        return { command: `bun add -g ${CLAUDE_CODE_PACKAGE}@latest`, source: 'bun' };
+    }
+    if (combined.includes('/homebrew/') || combined.includes('/caskroom/claude-code')) {
+        return { command: 'brew upgrade claude-code', source: 'homebrew' };
+    }
+    if (platform === 'win32' && (combined.includes('/winget/') || combined.includes('/anthropic.claudecode'))) {
+        return { command: 'winget upgrade Anthropic.ClaudeCode', source: 'winget' };
+    }
+    if (combined.includes('claude code.app') || combined.includes('/anthropic/claude')) {
+        return { command: null, source: 'native' };
+    }
+    return { command: null, source: 'unknown' };
+}
+export function formatClaudeRuntimeFloorAdvisory(probe, floor = CLAUDE_CODE_RUNTIME_FLOOR, platform = process.platform) {
+    const upgrade = inferClaudeRuntimeUpgradeCommand(probe, platform);
+    const pathText = probe.displayPath ? ` at ${probe.displayPath}` : '';
+    const base = `Warning: Claude Code Runtime is below GSD's validated floor: detected v${probe.version}, expected >= v${floor}. ` +
+        'GSD can still update, but older Claude Code may silently reduce output quality or miss model/runtime features.';
+    if (upgrade.command) {
+        return `${base} Upgrade the claude binary${pathText} with: ${upgrade.command}`;
+    }
+    return (`${base} Upgrade the claude binary${pathText} using the method you installed it with. ` +
+        'See docs/user-docs/claude-code-subscription.md#upgrade-claude-code.');
+}
+export function buildClaudeRuntimeFloorAdvisory(options) {
+    const settings = loadClaudeRuntimeSettings(options);
+    if (!isClaudeCodeConfigured(settings))
+        return null;
+    const probe = probeClaudeRuntime(options);
+    if (!probe)
+        return null;
+    if (compareVersionTriplets(probe.version, CLAUDE_CODE_RUNTIME_FLOOR) >= 0)
+        return null;
+    return formatClaudeRuntimeFloorAdvisory(probe, CLAUDE_CODE_RUNTIME_FLOOR, options.platform);
+}

package/dist/resources/skills/create-skill/references/executable-code.md

@@ -45,7 +45,7 @@ skill-name/
 **Reference pattern**: In SKILL.md, reference scripts using the `scripts/` path:
 
 ```bash
-python ~/.claude/skills/skill-name/scripts/analyze.py input.har
+python ~/.agents/skills/skill-name/scripts/analyze.py input.har
 ```
 </scripts_directory>
 </file_organization>

package/dist/resources/skills/create-skill/workflows/add-reference.md

@@ -10,16 +10,21 @@
 ## Step 1: Select the Skill
 
 ```bash
-ls ~/.claude/skills/
+# User-global skills
+ls ~/.agents/skills/ 2>/dev/null
+# Project-local skills
+ls .agents/skills/ 2>/dev/null
 ```
 
 Present numbered list, ask: "Which skill needs a new reference?"
 
+Determine `{skill-path}`: use `.agents/skills/{skill-name}` (project-local) if found there, otherwise `~/.agents/skills/{skill-name}` (user-global). Project-local takes precedence because the skill catalog loads it first on name collision.
+
 ## Step 2: Analyze Current Structure
 
 ```bash
-cat ~/.claude/skills/{skill-name}/SKILL.md
-ls ~/.claude/skills/{skill-name}/references/ 2>/dev/null
+cat {skill-path}/SKILL.md
+ls {skill-path}/references/ 2>/dev/null
 ```
 
 Determine:

package/dist/resources/skills/create-skill/workflows/add-script.md

@@ -12,6 +12,8 @@ Ask (if not already provided):
 - Which skill needs a script?
 - What operation should the script perform?
 
+Determine `{skill-path}`: use `.agents/skills/{skill-name}` (project-local) if found there, otherwise `~/.agents/skills/{skill-name}` (user-global). Project-local takes precedence because the skill catalog loads it first on name collision.
+
 ## Step 2: Analyze Script Need
 
 Confirm this is a good script candidate:
@@ -24,7 +26,7 @@ If not a good fit, suggest alternatives (inline code in workflow, reference exam
 ## Step 3: Create Scripts Directory
 
 ```bash
-mkdir -p ~/.claude/skills/{skill-name}/scripts
+mkdir -p {skill-path}/scripts
 ```
 
 ## Step 4: Design Script
@@ -58,7 +60,7 @@ set -euo pipefail
 ## Step 6: Make Executable (if bash)
 
 ```bash
-chmod +x ~/.claude/skills/{skill-name}/scripts/{script-name}.sh
+chmod +x {skill-path}/scripts/{script-name}.sh
 ```
 
 ## Step 7: Update Workflow to Use Script

package/dist/resources/skills/create-skill/workflows/add-template.md

@@ -12,6 +12,8 @@ Ask (if not already provided):
 - Which skill needs a template?
 - What output does this template structure?
 
+Determine `{skill-path}`: use `.agents/skills/{skill-name}` (project-local) if found there, otherwise `~/.agents/skills/{skill-name}` (user-global). Project-local takes precedence because the skill catalog loads it first on name collision.
+
 ## Step 2: Analyze Template Need
 
 Confirm this is a good template candidate:
@@ -24,7 +26,7 @@ If not a good fit, suggest alternatives (workflow guidance, reference examples).
 ## Step 3: Create Templates Directory
 
 ```bash
-mkdir -p ~/.claude/skills/{skill-name}/templates
+mkdir -p {skill-path}/templates
 ```
 
 ## Step 4: Design Template Structure

package/dist/resources/skills/create-skill/workflows/add-workflow.md

@@ -12,17 +12,22 @@
 **DO NOT use AskUserQuestion** - there may be many skills.
 
 ```bash
-ls ~/.claude/skills/
+# User-global skills
+ls ~/.agents/skills/ 2>/dev/null
+# Project-local skills
+ls .agents/skills/ 2>/dev/null
 ```
 
 Present numbered list, ask: "Which skill needs a new workflow?"
 
+Determine `{skill-path}`: use `.agents/skills/{skill-name}` (project-local) if found there, otherwise `~/.agents/skills/{skill-name}` (user-global). Project-local takes precedence because the skill catalog loads it first on name collision.
+
 ## Step 2: Analyze Current Structure
 
 Read the skill:
 ```bash
-cat ~/.claude/skills/{skill-name}/SKILL.md
-ls ~/.claude/skills/{skill-name}/workflows/ 2>/dev/null
+cat {skill-path}/SKILL.md
+ls {skill-path}/workflows/ 2>/dev/null
 ```
 
 Determine:

package/dist/resources/skills/create-skill/workflows/upgrade-to-router.md

@@ -10,17 +10,22 @@
 ## Step 1: Select the Skill
 
 ```bash
-ls ~/.claude/skills/
+# User-global skills
+ls ~/.agents/skills/ 2>/dev/null
+# Project-local skills
+ls .agents/skills/ 2>/dev/null
 ```
 
 Present numbered list, ask: "Which skill should be upgraded to the router pattern?"
 
+Determine `{skill-path}`: use `.agents/skills/{skill-name}` (project-local) if found there, otherwise `~/.agents/skills/{skill-name}` (user-global). Project-local takes precedence because the skill catalog loads it first on name collision.
+
 ## Step 2: Verify It Needs Upgrading
 
 Read the skill:
 ```bash
-cat ~/.claude/skills/{skill-name}/SKILL.md
-ls ~/.claude/skills/{skill-name}/
+cat {skill-path}/SKILL.md
+ls {skill-path}/
 ```
 
 **Already a router?** (has workflows/ and intake question)
@@ -65,8 +70,8 @@ Ask: "Does this breakdown look right? Any adjustments?"
 ## Step 4: Create Directory Structure
 
 ```bash
-mkdir -p ~/.claude/skills/{skill-name}/workflows
-mkdir -p ~/.claude/skills/{skill-name}/references
+mkdir -p {skill-path}/workflows
+mkdir -p {skill-path}/references
 ```
 
 ## Step 5: Extract Workflows

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

@@ -15,18 +15,23 @@ Skills contain claims about external things: APIs, CLI tools, frameworks, servic
 ## Step 1: Select the Skill
 
 ```bash
-ls ~/.claude/skills/
+# User-global skills
+ls ~/.agents/skills/ 2>/dev/null
+# Project-local skills
+ls .agents/skills/ 2>/dev/null
 ```
 
 Present numbered list, ask: "Which skill should I verify for accuracy?"
 
+Determine `{skill-path}`: use `.agents/skills/{skill-name}` (project-local) if found there, otherwise `~/.agents/skills/{skill-name}` (user-global). Project-local takes precedence because the skill catalog loads it first on name collision.
+
 ## Step 2: Read and Categorize
 
 Read the entire skill (SKILL.md + workflows/ + references/):
 ```bash
-cat ~/.claude/skills/{skill-name}/SKILL.md
-cat ~/.claude/skills/{skill-name}/workflows/*.md 2>/dev/null
-cat ~/.claude/skills/{skill-name}/references/*.md 2>/dev/null
+cat {skill-path}/SKILL.md
+cat {skill-path}/workflows/*.md 2>/dev/null
+cat {skill-path}/references/*.md 2>/dev/null
 ```
 
 Categorize by primary dependency type:

package/dist/resources/skills/gsd-browser/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gsd-browser
-description: Use gsd-browser for browser automation and UAT: navigating local apps, inspecting pages, clicking or filling controls, taking screenshots, asserting UI behavior, collecting console/network diagnostics, visual diffing, and creating evidence bundles. Prefer this over legacy Playwright browser tooling when both are available.
+description: "Use gsd-browser for browser automation and UAT: navigating local apps, inspecting pages, clicking or filling controls, taking screenshots, asserting UI behavior, collecting console/network diagnostics, visual diffing, and creating evidence bundles. Prefer this over legacy Playwright browser tooling when both are available."
 allowed-tools: Bash(gsd-browser:*), Bash(gsd-browser *)
 ---
 

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

@@ -1,16 +1,16 @@
 ---
 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 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`.
+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 `.agents/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>
-Convert the output of a research spike (`SCOPE.md`, `research/*.md`, `RECOMMENDATION.md`) into a project-local skill under `.claude/skills/` so that the next time a similar task comes up, the agent loads the skill automatically. This is how throwaway spikes become durable capital.
+Convert the output of a research spike (`SCOPE.md`, `research/*.md`, `RECOMMENDATION.md`) into a project-local skill under `.agents/skills/` so that the next time a similar task comes up, the agent loads the skill automatically. This is how throwaway spikes become durable capital.
 </objective>
 
 <context>
 GSD's spike workflow (`src/resources/extensions/gsd/workflow-templates/spike.md`) produces documents in `.gsd/workflows/spikes/<slug>/`. Those documents are useful once and then forgotten unless something packages them for reuse.
 
-GSD already watches `.claude/skills/` (and `.agents/skills/`) at both user and project levels — see `src/resources/extensions/gsd/skill-discovery.ts`. Any skill written there is picked up on the next session without further wiring. This skill is the bridge from "spike done" to "skill available."
+GSD already watches `.agents/skills/` (and `.claude/skills/` as a legacy compat path) at both user and project levels — see `src/resources/extensions/gsd/skill-discovery.ts`. Any skill written there is picked up on the next session without further wiring. This skill is the bridge from "spike done" to "skill available."
 
 Invocation points:
 - End of Phase 3 (synthesize) in `/gsd start spike` — prompt suggests running this skill
@@ -21,7 +21,7 @@ Invocation points:
 <core_principle>
 **NOT EVERY SPIKE DESERVES A SKILL.** If the recommendation was "don't do X," there may be no reusable guidance. Ask the user first; exit without writing if the answer is no.
 
-**PROJECT-LOCAL, NOT USER-GLOBAL.** Write to `.claude/skills/` in the repo, not `~/.claude/skills/`. The skill encodes project-specific choices that should not leak into unrelated projects.
+**PROJECT-LOCAL, NOT USER-GLOBAL.** Write to `.agents/skills/` in the project root, not `~/.agents/skills/`. The skill encodes project-specific choices that should not leak into unrelated projects.
 
 **DESCRIPTION IS THE DISCOVERABILITY SIGNAL.** The `description` field in frontmatter is the primary signal the agent uses to judge relevance and decide whether to load the skill — it is a heuristic, not a deterministic trigger. Write it as keywords the future agent will plausibly encounter, not a summary.
 </core_principle>
@@ -65,7 +65,7 @@ Show this sketch to the user. One round of feedback. Iterate.
 
 ## Step 4: Write the skill
 
-Write to `.claude/skills/<name>/SKILL.md` (create the directory). Match the frontmatter + XML-tag structure used by other bundled skills — see `src/resources/skills/review/SKILL.md` for the canonical shape.
+Write to `.agents/skills/<name>/SKILL.md` (create the directory). Match the frontmatter + XML-tag structure used by other bundled skills — see `src/resources/skills/review/SKILL.md` for the canonical shape.
 
 Minimum structure:
 
@@ -102,7 +102,7 @@ description: <one sentence with trigger keywords>
 </success_criteria>
 ```
 
-If the spike produced a reusable template (a config file, a starter script), copy it into `.claude/skills/<name>/templates/` or `.claude/skills/<name>/references/` and reference it from the skill body.
+If the spike produced a reusable template (a config file, a starter script), copy it into `.agents/skills/<name>/templates/` or `.agents/skills/<name>/references/` and reference it from the skill body.
 
 ## Step 5: Archive the spike, link from the skill
 
@@ -112,13 +112,13 @@ If the spike produced a reusable template (a config file, a starter script), cop
 
 ## Step 6: Confirm pickup
 
-Tell the user the skill will be surfaced on the next session via `skill-discovery.ts`. If they want to use it immediately, they can `Read .claude/skills/<name>/SKILL.md` now.
+Tell the user the skill will be surfaced on the next session via `skill-discovery.ts`. If they want to use it immediately, they can `Read .agents/skills/<name>/SKILL.md` now.
 
 </process>
 
 <anti_patterns>
 
-- **Writing to `~/.claude/skills/`.** That's user-global. Project spikes produce project skills — keep them scoped.
+- **Writing to `~/.claude/skills/` or `.claude/skills/`.** These are legacy Claude Code compatibility paths. Write project skills to `.agents/skills/` in the project root instead.
 - **Verbose frontmatter description.** The description is an index entry, not a tutorial. Keywords over prose.
 - **Packaging every spike.** If the outcome was "we decided X once," append to DECISIONS.md and move on.
 - **Copy-pasting the spike verbatim into the skill.** The spike is research; the skill is executable guidance. Re-author.
@@ -128,7 +128,7 @@ Tell the user the skill will be surfaced on the next session via `skill-discover
 
 <success_criteria>
 
-- [ ] A new `.claude/skills/<name>/SKILL.md` exists with well-formed frontmatter.
+- [ ] A new `.agents/skills/<name>/SKILL.md` exists with well-formed frontmatter.
 - [ ] The `description` field uses keywords that will plausibly match future agent work.
 - [ ] The skill body is executable on its own without re-reading the originating spike.
 - [ ] The originating spike is referenced from the skill.