@opengsd/gsd-pi 1.2.0-dev.b1abb545 → 1.2.0-dev.d6c5343c

package/src/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/src/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/src/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/src/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.

package/dist/resources/extensions/gsd/user-input-boundary.js

@@ -1,218 +0,0 @@
-const USER_APPROVAL_UNIT_TYPES = new Set([
-    "discuss-project",
-    "discuss-requirements",
-    "discuss-milestone",
-    "research-decision",
-]);
-const REMOTE_QUESTION_FAILURE_RE = /(?:Remote (?:auth failed|questions failed|channel configured but returned no result|questions timed out|questions timed out or failed)|Failed to send questions via)/i;
-const APPROVAL_WAIT_RE = /\bwait(?:ing)?\s+for\s+(?:your\s+)?(?:confirmation|approval|input|response|answer)\b/i;
-const APPROVAL_QUESTION_RE = /\b(?:confirm|confirmation|approve|approval|approved|captured|correct|correctly|happy\s+with|ready\s+to\s+(?:write|save|proceed|ship)|(?:want|need)\s+to\s+adjust|should\s+I\s+(?:write|save|proceed)|do\s+you\s+want\s+me\s+to\s+(?:write|save|proceed)|ship\s+it)\b/i;
-const APPROVAL_RIGHT_QUESTION_RE = /\b(?:does|do|is|are|was|were|did)\b[^\n?]{0,120}\bright\b/i;
-const APPROVAL_CHANGE_QUESTION_RE = /\b(?:anything\s+else|anything|something)\s+to\s+(?:adjust|add|remove|reclassify)\b/i;
-const RESEARCH_DECISION_QUESTION_RE = /\b(?:research|skip)\b/i;
-function extractVisibleTextFromMessage(msg) {
-    if (!msg || typeof msg !== "object")
-        return "";
-    const content = msg.content;
-    if (typeof content === "string")
-        return content;
-    if (!Array.isArray(content))
-        return "";
-    const parts = [];
-    for (const block of content) {
-        if (!block || typeof block !== "object")
-            continue;
-        const typed = block;
-        if (typed.type === "text" && typeof typed.text === "string") {
-            parts.push(typed.text);
-        }
-        // thinking blocks intentionally excluded — they are internal reasoning, not user-visible
-    }
-    return parts.join("\n");
-}
-function extractTextFromMessage(msg) {
-    if (!msg || typeof msg !== "object")
-        return "";
-    const content = msg.content;
-    if (typeof content === "string")
-        return content;
-    if (!Array.isArray(content))
-        return "";
-    const parts = [];
-    for (const block of content) {
-        if (!block || typeof block !== "object")
-            continue;
-        const typed = block;
-        if (typed.type === "text" && typeof typed.text === "string") {
-            parts.push(typed.text);
-        }
-        if (typed.type === "thinking" && typeof typed.thinking === "string") {
-            parts.push(typed.thinking);
-        }
-    }
-    return parts.join("\n");
-}
-export function lastAssistantText(messages) {
-    if (!Array.isArray(messages))
-        return "";
-    for (let i = messages.length - 1; i >= 0; i--) {
-        const msg = messages[i];
-        if (!msg || typeof msg !== "object")
-            continue;
-        if (msg.role !== "assistant")
-            continue;
-        const text = extractTextFromMessage(msg).trim();
-        if (text)
-            return text;
-    }
-    return "";
-}
-function lastAssistantVisibleText(messages) {
-    if (!Array.isArray(messages))
-        return "";
-    for (let i = messages.length - 1; i >= 0; i--) {
-        const msg = messages[i];
-        if (!msg || typeof msg !== "object")
-            continue;
-        if (msg.role !== "assistant")
-            continue;
-        const text = extractVisibleTextFromMessage(msg).trim();
-        if (text)
-            return text;
-    }
-    return "";
-}
-function anyMessageMatches(messages, pattern) {
-    if (!Array.isArray(messages))
-        return false;
-    return messages.some((msg) => {
-        if (!msg || typeof msg !== "object")
-            return false;
-        if (msg.role === "user")
-            return false;
-        return pattern.test(extractVisibleTextFromMessage(msg));
-    });
-}
-function hasApprovalQuestion(text) {
-    for (let i = 0; i < text.length; i++) {
-        if (text[i] !== "?")
-            continue;
-        const previousBreak = Math.max(text.lastIndexOf("\n", i), text.lastIndexOf(".", i), text.lastIndexOf("!", i), text.lastIndexOf("?", i - 1));
-        const fragment = text.slice(previousBreak + 1, i + 1);
-        if (APPROVAL_QUESTION_RE.test(fragment))
-            return true;
-        if (APPROVAL_RIGHT_QUESTION_RE.test(fragment))
-            return true;
-        if (APPROVAL_CHANGE_QUESTION_RE.test(fragment))
-            return true;
-    }
-    return false;
-}
-function hasResearchDecisionQuestion(text) {
-    for (let i = 0; i < text.length; i++) {
-        if (text[i] !== "?")
-            continue;
-        const previousBreak = Math.max(text.lastIndexOf("\n", i), text.lastIndexOf(".", i), text.lastIndexOf("!", i), text.lastIndexOf("?", i - 1));
-        const fragment = text.slice(previousBreak + 1, i + 1);
-        if (RESEARCH_DECISION_QUESTION_RE.test(fragment))
-            return true;
-    }
-    return false;
-}
-export function approvalGateIdForUnit(unitType, unitId) {
-    if (!unitType)
-        return null;
-    if (unitType === "discuss-project")
-        return "depth_verification_project_confirm";
-    if (unitType === "discuss-requirements")
-        return "depth_verification_requirements_confirm";
-    if (unitType === "research-decision")
-        return "depth_verification_research_decision_confirm";
-    if (unitType === "discuss-milestone") {
-        const safeUnitId = typeof unitId === "string" && /^[A-Za-z0-9_-]+$/.test(unitId)
-            ? unitId
-            : "milestone";
-        return `depth_verification_${safeUnitId}_confirm`;
-    }
-    return null;
-}
-const CHANGE_REQUEST_RESPONSE_RE = /\b(?:no|nope|nah|not\s+yet|don't|do\s+not|change|add|remove|reclassify|adjust|clarify|missing|instead|but|however|wait|hold)\b/i;
-const APPROVAL_RESPONSE_RE = /^(?:y|yes|yeah|yep|approve|approved|confirm|confirmed|correct|right|looks\s+(?:good|right)|sounds\s+good|all\s+good|ok|okay|go\s+ahead|proceed|write\s+it|save\s+it|do\s+it)\b/i;
-const RESEARCH_DECISION_RESPONSE_RE = /^(?:research|run\s+research|do\s+research|skip|skip\s+research|no\s+research)\b/i;
-export function isExplicitApprovalResponse(input, pendingGateId) {
-    const text = input?.trim() ?? "";
-    if (!text)
-        return false;
-    if (pendingGateId?.includes("research_decision")) {
-        return RESEARCH_DECISION_RESPONSE_RE.test(text);
-    }
-    if (CHANGE_REQUEST_RESPONSE_RE.test(text))
-        return false;
-    return APPROVAL_RESPONSE_RE.test(text);
-}
-export function isAwaitingUserInput(messages) {
-    if (anyMessageMatches(messages, /ask_user_questions was cancelled before receiving a response/i))
-        return true;
-    if (anyMessageMatches(messages, REMOTE_QUESTION_FAILURE_RE))
-        return true;
-    const text = lastAssistantVisibleText(messages);
-    if (!text)
-        return false;
-    if (APPROVAL_WAIT_RE.test(text))
-        return true;
-    const lines = text.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
-    if (lines.some((line) => line.endsWith("?")))
-        return true;
-    return hasApprovalQuestion(text);
-}
-export function isAwaitingApprovalBoundary(messages) {
-    if (anyMessageMatches(messages, /ask_user_questions was cancelled before receiving a response/i))
-        return true;
-    if (anyMessageMatches(messages, REMOTE_QUESTION_FAILURE_RE))
-        return true;
-    const text = lastAssistantVisibleText(messages);
-    if (!text)
-        return false;
-    if (APPROVAL_WAIT_RE.test(text))
-        return true;
-    return hasApprovalQuestion(text);
-}
-/** True when an assistant message already has an in-flight ask_user_questions tool call. */
-export function messageHasPendingAskUserQuestionsTool(message) {
-    if (!message || typeof message !== "object")
-        return false;
-    const content = message.content;
-    if (!Array.isArray(content))
-        return false;
-    return content.some((block) => {
-        if (!block || typeof block !== "object")
-            return false;
-        // Claude Code marks completion by attaching externalResult, not by setting state.
-        // Streaming blocks often carry no state; serverToolUse is the claude-code-cli MCP path.
-        const tool = block;
-        if (tool.type !== "toolCall" && tool.type !== "serverToolUse")
-            return false;
-        const name = String(tool.name ?? "").toLowerCase();
-        if (!name.includes("ask_user_questions"))
-            return false;
-        if (tool.externalResult !== undefined)
-            return false;
-        return tool.state !== "completed" && tool.state !== "done";
-    });
-}
-export function shouldPauseForUserApprovalQuestion(unitType, messages) {
-    if (!unitType || !USER_APPROVAL_UNIT_TYPES.has(unitType))
-        return false;
-    if (anyMessageMatches(messages, /ask_user_questions was cancelled before receiving a response/i))
-        return true;
-    if (anyMessageMatches(messages, REMOTE_QUESTION_FAILURE_RE))
-        return true;
-    const text = lastAssistantVisibleText(messages);
-    if (!text)
-        return false;
-    if (APPROVAL_WAIT_RE.test(text))
-        return true;
-    if (unitType === "research-decision")
-        return hasResearchDecisionQuestion(text);
-    return hasApprovalQuestion(text);
-}

package/src/resources/extensions/gsd/tests/user-input-boundary.test.ts

@@ -1,173 +0,0 @@
-import test from "node:test";
-import assert from "node:assert/strict";
-
-import * as userInputBoundary from "../user-input-boundary.ts";
-import {
-  isAwaitingUserInput,
-  messageHasPendingAskUserQuestionsTool,
-  shouldPauseForUserApprovalQuestion,
-} from "../user-input-boundary.ts";
-
-test("lastAssistantText extracts the latest assistant text block content", () => {
-  const lastAssistantText = (userInputBoundary as {
-    lastAssistantText?: (messages: unknown[] | null | undefined) => string;
-  }).lastAssistantText;
-
-  assert.equal(typeof lastAssistantText, "function");
-  assert.equal(
-    lastAssistantText?.([
-      { role: "assistant", content: "Older message" },
-      {
-        role: "assistant",
-        content: [
-          { type: "text", text: "First line" },
-          { type: "text", text: "Second line" },
-        ],
-      },
-    ]),
-    "First line\nSecond line",
-  );
-  assert.equal(lastAssistantText?.(null), "");
-});
-
-test("lastAssistantText includes thinking blocks so rate-limit notices are not dropped", () => {
-  const lastAssistantText = (userInputBoundary as {
-    lastAssistantText?: (messages: unknown[] | null | undefined) => string;
-  }).lastAssistantText;
-
-  assert.equal(typeof lastAssistantText, "function");
-  // Turn with only a thinking block (no text block) — must not return ""
-  const result = lastAssistantText?.([
-    {
-      role: "assistant",
-      content: [
-        { type: "thinking", thinking: "You've hit your limit · resets in 2h" },
-      ],
-    },
-  ]);
-  assert.ok(result?.includes("You've hit your limit"), `expected rate-limit text, got: ${JSON.stringify(result)}`);
-});
-
-test("isAwaitingUserInput does not trigger on thinking-block question marks", () => {
-  // A thinking block with a question mark must NOT pause auto-mode —
-  // it's internal reasoning, not a user-visible prompt.
-  const messages = [
-    {
-      role: "assistant",
-      content: [
-        { type: "thinking", thinking: "Should I skip research? Let me check the config." },
-      ],
-    },
-  ];
-  assert.equal(isAwaitingUserInput(messages), false);
-  assert.equal(shouldPauseForUserApprovalQuestion("discuss-project", messages), false);
-});
-
-test("isAwaitingUserInput does not trigger on thinking-block approval phrases", () => {
-  // A thinking block with approval phrases must NOT pause auto-mode.
-  const messages = [
-    {
-      role: "assistant",
-      content: [
-        { type: "thinking", thinking: "The user confirmed and approved the plan. Should I proceed?" },
-      ],
-    },
-  ];
-  assert.equal(isAwaitingUserInput(messages), false);
-  assert.equal(shouldPauseForUserApprovalQuestion("discuss-requirements", messages), false);
-});
-
-test("messageHasPendingAskUserQuestionsTool detects in-flight structured question tools", () => {
-  // state: "running" with no externalResult → still in-flight
-  assert.equal(
-    messageHasPendingAskUserQuestionsTool({
-      role: "assistant",
-      content: [
-        { type: "text", text: "Which direction?" },
-        { type: "toolCall", name: "mcp__gsd-workflow__ask_user_questions", state: "running" },
-      ],
-    }),
-    true,
-  );
-
-  // no state, no externalResult — streaming block that hasn't completed yet
-  assert.equal(
-    messageHasPendingAskUserQuestionsTool({
-      role: "assistant",
-      content: [
-        { type: "toolCall", name: "ask_user_questions" },
-      ],
-    }),
-    true,
-  );
-
-  // state: "completed" — legacy state-based completion
-  assert.equal(
-    messageHasPendingAskUserQuestionsTool({
-      role: "assistant",
-      content: [
-        { type: "toolCall", name: "ask_user_questions", state: "completed" },
-      ],
-    }),
-    false,
-  );
-
-  // externalResult present — Claude Code signals completion via externalResult, not state
-  assert.equal(
-    messageHasPendingAskUserQuestionsTool({
-      role: "assistant",
-      content: [
-        { type: "toolCall", name: "ask_user_questions", externalResult: { content: [], isError: false } },
-      ],
-    }),
-    false,
-  );
-  assert.equal(
-    messageHasPendingAskUserQuestionsTool({
-      role: "assistant",
-      content: [
-        {
-          type: "toolCall",
-          name: "ask_user_questions",
-          externalResult: { content: [{ type: "text", text: "answer" }], isError: false },
-        },
-      ],
-    }),
-    false,
-  );
-
-  // serverToolUse shape (claude-code-cli MCP path) — no externalResult → in-flight
-  assert.equal(
-    messageHasPendingAskUserQuestionsTool({
-      role: "assistant",
-      content: [
-        { type: "serverToolUse", name: "mcp__gsd-workflow__ask_user_questions" },
-      ],
-    }),
-    true,
-  );
-  // serverToolUse shape — externalResult present → completed
-  assert.equal(
-    messageHasPendingAskUserQuestionsTool({
-      role: "assistant",
-      content: [
-        { type: "serverToolUse", name: "ask_user_questions", externalResult: { content: [], isError: false } },
-      ],
-    }),
-    false,
-  );
-});
-
-test("isAwaitingUserInput still triggers on text-block question marks when thinking is also present", () => {
-  // When thinking + text are both present and the text asks a question, it should still pause.
-  const messages = [
-    {
-      role: "assistant",
-      content: [
-        { type: "thinking", thinking: "Internal reasoning without questions." },
-        { type: "text", text: "Does this look correct?" },
-      ],
-    },
-  ];
-  assert.equal(isAwaitingUserInput(messages), true);
-});