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

package/src/resources/extensions/gsd/skill-discovery.ts

@@ -2,21 +2,17 @@
  * GSD Skill Discovery
  *
  * Detects skills installed during auto-mode by comparing the current
- * skills directory against a snapshot taken at auto-mode start.
+ * installed catalog and skill directories against a snapshot taken at auto-mode start.
  *
- * New skills are injected into the system prompt via before_agent_start,
- * making them visible to all subsequent units without requiring a reload.
+ * New skills are surfaced via resource reload when possible, with a fallback
+ * prompt block when reload fails before the next agent turn.
  */
 
-import { existsSync, readdirSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, readdirSync, readFileSync, type Dirent } from "node:fs";
 import { homedir } from "node:os";
+import { join } from "node:path";
 import { gsdHome } from "./gsd-home.js";
-
-/** Skills directories — GSD bundled, skills.sh ecosystem, and Claude Code official */
-const GSD_SKILLS_DIR = join(gsdHome(), "agent", "skills");
-const SKILLS_DIR = join(homedir(), ".agents", "skills");
-const CLAUDE_SKILLS_DIR = join(homedir(), ".claude", "skills");
+import { getInstalledSkills, normalizeSkillName } from "./skills.js";
 
 export interface DiscoveredSkill {
   name: string;
@@ -24,14 +20,14 @@ export interface DiscoveredSkill {
   location: string;
 }
 
-/** Snapshot of skill names at auto-mode start */
+/** Snapshot of normalized skill names at auto-mode start */
 let baselineSkills: Set<string> | null = null;
 
 /**
- * Snapshot the current skills directory. Call at auto-mode start.
+ * Snapshot the current installed skill catalog. Call at auto-mode start.
  */
 export function snapshotSkills(): void {
-  baselineSkills = new Set(listSkillDirs());
+  baselineSkills = snapshotCurrentSkillNames();
 }
 
 /**
@@ -50,82 +46,158 @@ export function hasSkillSnapshot(): boolean {
 
 /**
  * Detect skills installed since the snapshot was taken.
- * Returns skill metadata for any new skills found.
+ * Returns skill metadata for any new skills found in the loader catalog or on disk.
  */
 export function detectNewSkills(): DiscoveredSkill[] {
   if (!baselineSkills) return [];
 
-  const current = listSkillDirs();
   const newSkills: DiscoveredSkill[] = [];
-
-  for (const dir of current) {
-    if (baselineSkills.has(dir)) continue;
-
-    // Check both skill directories for the SKILL.md file
-    const skillMdPath = resolveSkillMdPath(dir);
-    if (!skillMdPath) continue;
-
-    const meta = parseSkillFrontmatter(skillMdPath);
-    if (meta) {
-      newSkills.push({
-        name: meta.name || dir,
-        description: meta.description || `Skill: ${dir}`,
-        location: skillMdPath,
-      });
-    }
+  for (const skill of getCurrentSkillsForDiscovery()) {
+    const normalized = normalizeSkillName(skill.name);
+    if (baselineSkills.has(normalized)) continue;
+    newSkills.push(skill);
   }
 
   return newSkills;
 }
 
 /**
- * Format discovered skills as an XML block matching pi's <available_skills> format.
- * This can be appended to the system prompt so the LLM sees them naturally.
+ * Reload the skill catalog when auto-mode detects newly installed skills.
+ * Returns discovered skills even if reload fails so callers can surface them
+ * in the prompt. Updates the snapshot baseline only after a successful reload
+ * so detection is retried after failures.
  */
-export function formatSkillsXml(skills: DiscoveredSkill[]): string {
-  if (skills.length === 0) return "";
+export async function refreshCatalogForNewSkills(options?: {
+  reload?: () => Promise<void>;
+  notify?: (message: string, level: "info" | "warning") => void;
+}): Promise<DiscoveredSkill[]> {
+  const newSkills = detectNewSkills();
+  if (newSkills.length === 0) return [];
+
+  if (options?.reload) {
+    try {
+      await options.reload();
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      options.notify?.(`GSD: failed to reload skill catalog: ${message}`, "warning");
+      return newSkills;
+    }
+  }
 
-  const entries = skills.map(s => `  <skill>
-    <name>${escapeXml(s.name)}</name>
-    <description>${escapeXml(s.description)}</description>
-    <location>${escapeXml(s.location)}</location>
-  </skill>`).join("\n");
+  snapshotSkills();
+  const names = newSkills.map((skill) => skill.name).join(", ");
+  options?.notify?.(`GSD: loaded new skills: ${names}`, "info");
+  return newSkills;
+}
 
-  return `\n<newly_discovered_skills>
-The following skills were installed during this auto-mode session.
-Use the read tool to load a skill's file when the task matches its description.
+export function appendDiscoveredSkillsFallback(systemPrompt: string, skills: DiscoveredSkill[]): string {
+  const missingSkills = skills.filter(skill => !systemPrompt.includes(skill.location));
+  if (missingSkills.length === 0) return systemPrompt;
 
-${entries}
-</newly_discovered_skills>`;
+  return `${systemPrompt}\n\n${formatDiscoveredSkillsXml(missingSkills)}`;
 }
 
 // ─── Internals ────────────────────────────────────────────────────────────────
 
-function listSkillDirsFrom(dir: string): string[] {
-  if (!existsSync(dir)) return [];
-  try {
-    return readdirSync(dir, { withFileTypes: true })
-      .filter(d => d.isDirectory())
-      .map(d => d.name);
-  } catch {
-    return [];
+function formatDiscoveredSkillsXml(skills: DiscoveredSkill[]): string {
+  const lines = [
+    "<newly_discovered_skills>",
+    "  <note>These skills were detected after this session started and may be absent from &lt;available_skills&gt;. If relevant, read the skill file at its location before using it.</note>",
+  ];
+
+  for (const skill of skills) {
+    lines.push(
+      "  <skill>",
+      `    <name>${escapeXml(skill.name)}</name>`,
+      `    <description>${escapeXml(skill.description)}</description>`,
+      `    <location>${escapeXml(skill.location)}</location>`,
+      "  </skill>",
+    );
+  }
+
+  lines.push("</newly_discovered_skills>");
+  return lines.join("\n");
+}
+
+function escapeXml(value: string): string {
+  return value.replace(/[<>&'"]/g, (char) => {
+    switch (char) {
+      case "<": return "&lt;";
+      case ">": return "&gt;";
+      case "&": return "&amp;";
+      case "'": return "&apos;";
+      case "\"": return "&quot;";
+      default: return char;
+    }
+  });
+}
+
+function skillSearchDirs(): string[] {
+  return [
+    join(gsdHome(), "agent", "skills"),
+    join(homedir(), ".agents", "skills"),
+    join(homedir(), ".claude", "skills"),
+  ];
+}
+
+function snapshotCurrentSkillNames(): Set<string> {
+  return new Set(getCurrentSkillsForDiscovery().map(skill => normalizeSkillName(skill.name)));
+}
+
+function getCurrentSkillsForDiscovery(): DiscoveredSkill[] {
+  const skills = new Map<string, DiscoveredSkill>();
+  for (const skill of getInstalledSkills()) {
+    const normalized = normalizeSkillName(skill.name);
+    skills.set(normalized, {
+      name: skill.name,
+      description: skill.description || `Skill: ${skill.name}`,
+      location: skill.filePath,
+    });
+  }
+
+  for (const skill of getDiskSkills()) {
+    const normalized = normalizeSkillName(skill.name);
+    if (!skills.has(normalized)) skills.set(normalized, skill);
   }
+
+  return [...skills.values()];
 }
 
-function listSkillDirs(): string[] {
-  const names = new Set<string>();
-  for (const name of listSkillDirsFrom(GSD_SKILLS_DIR)) names.add(name);
-  for (const name of listSkillDirsFrom(SKILLS_DIR)) names.add(name);
-  for (const name of listSkillDirsFrom(CLAUDE_SKILLS_DIR)) names.add(name);
-  return [...names];
+function getDiskSkills(): DiscoveredSkill[] {
+  const skills = new Map<string, DiscoveredSkill>();
+  for (const dir of skillSearchDirs()) {
+    if (!existsSync(dir)) continue;
+    let entries: Dirent[];
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+
+    for (const entry of entries) {
+      if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+      const skillMdPath = join(dir, entry.name, "SKILL.md");
+      if (!existsSync(skillMdPath)) continue;
+
+      const meta = parseSkillFrontmatter(skillMdPath);
+      const name = meta?.name || entry.name;
+      const normalized = normalizeSkillName(name);
+      if (skills.has(normalized)) continue;
+      skills.set(normalized, {
+        name,
+        description: meta?.description || `Skill: ${name}`,
+        location: skillMdPath,
+      });
+    }
+  }
+  return [...skills.values()];
 }
 
 function parseSkillFrontmatter(path: string): { name?: string; description?: string } | null {
   try {
     const content = readFileSync(path, "utf-8");
-    // Use indexOf instead of [\s\S]*? regex to avoid backtracking (#468)
-    if (!content.startsWith('---\n')) return null;
-    const endIdx = content.indexOf('\n---', 4);
+    if (!content.startsWith("---\n")) return null;
+    const endIdx = content.indexOf("\n---", 4);
     if (endIdx === -1) return null;
 
     const fm = content.slice(4, endIdx);
@@ -142,19 +214,3 @@ function parseSkillFrontmatter(path: string): { name?: string; description?: str
     return null;
   }
 }
-
-function resolveSkillMdPath(skillName: string): string | null {
-  for (const dir of [GSD_SKILLS_DIR, SKILLS_DIR, CLAUDE_SKILLS_DIR]) {
-    const candidate = join(dir, skillName, "SKILL.md");
-    if (existsSync(candidate)) return candidate;
-  }
-  return null;
-}
-
-function escapeXml(text: string): string {
-  return text
-    .replace(/&/g, "&amp;")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;")
-    .replace(/"/g, "&quot;");
-}

package/src/resources/extensions/gsd/skill-scope.ts

@@ -0,0 +1,63 @@
+/**
+ * Per-unit skill catalog scoping for GSD auto and workflow dispatch.
+ */
+
+import type { ExtensionAPI } from "@gsd/pi-coding-agent";
+
+import { resolveSkillManifest } from "./skill-manifest.js";
+import { normalizeSkillName } from "./skills.js";
+import { resolveManifest } from "./unit-context-manifest.js";
+
+/**
+ * Resolve which skill names should appear in `<available_skills>` for a unit.
+ * Returns `undefined` for full catalog, `[]` for suppressed catalog, or a
+ * name list for allowlist mode.
+ */
+export function resolveVisibleSkillNames(unitType: string | undefined): string[] | undefined {
+  if (!unitType) return undefined;
+
+  const unitManifest = resolveManifest(unitType);
+  if (unitManifest) {
+    switch (unitManifest.skills.mode) {
+      case "none":
+        return [];
+      case "all":
+        return undefined;
+      case "allowlist":
+        return [...unitManifest.skills.skills];
+    }
+  }
+
+  const legacyAllowlist = resolveSkillManifest(unitType);
+  return legacyAllowlist ?? undefined;
+}
+
+/** Whether this unit narrows or suppresses the skill catalog (not mode "all"). */
+export function unitHasSkillManifest(unitType: string | undefined): boolean {
+  if (!unitType) return false;
+  const unitManifest = resolveManifest(unitType);
+  if (unitManifest) {
+    return unitManifest.skills.mode !== "all";
+  }
+  return resolveSkillManifest(unitType) !== null;
+}
+
+/** Apply unit manifest skill policy via setVisibleSkills. */
+export function applyUnitSkillVisibility(
+  pi: Pick<ExtensionAPI, "setVisibleSkills">,
+  unitType: string | undefined,
+): void {
+  pi.setVisibleSkills(resolveVisibleSkillNames(unitType));
+}
+
+/** Installed skill names visible for a unit per manifest policy. */
+export function effectiveSkillNamesForUnit(
+  unitType: string | undefined,
+  installed: string[],
+): string[] {
+  const visible = resolveVisibleSkillNames(unitType);
+  if (visible === undefined) return installed;
+  if (visible.length === 0) return [];
+  const allowed = new Set(visible.map(normalizeSkillName));
+  return installed.filter((name) => allowed.has(normalizeSkillName(name)));
+}

package/src/resources/extensions/gsd/skill-telemetry.ts

@@ -6,15 +6,12 @@
  * "actively loaded" skills (read via tool calls during execution).
  *
  * Data flow:
- *   1. At dispatch, captureAvailableSkills() records skills from the system prompt
+ *   1. At dispatch, captureAvailableSkills(names) records catalog skill names
  *   2. During execution, recordSkillRead() tracks explicit SKILL.md reads
  *   3. At unit completion, getAndClearSkills() returns the loaded list for metrics
  */
 
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { join } from "node:path";
-import { gsdHome } from "./gsd-home.js";
-import { homedir } from "node:os";
+import { getInstalledSkillNames } from "./skills.js";
 
 // ─── In-memory state ──────────────────────────────────────────────────────────
 
@@ -28,17 +25,10 @@ const activelyLoadedSkills = new Set<string>();
 
 /**
  * Capture the list of available skill names at dispatch time.
- * Called before each unit starts.
+ * Callers should pass names from resourceLoader / {@link getInstalledSkillNames}.
  */
-export function captureAvailableSkills(): void {
-  const gsdSkillsDir = join(gsdHome(), "agent", "skills");
-  const skillsDir = join(homedir(), ".agents", "skills");
-  const claudeSkillsDir = join(homedir(), ".claude", "skills");
-  const gsdNames = listSkillNames(gsdSkillsDir);
-  const names = listSkillNames(skillsDir);
-  const claudeNames = listSkillNames(claudeSkillsDir);
-  const all = new Set([...gsdNames, ...names, ...claudeNames]);
-  availableSkills = [...all];
+export function captureAvailableSkills(skillNames: string[]): void {
+  availableSkills = [...skillNames];
   activelyLoadedSkills.clear();
 }
 
@@ -104,17 +94,7 @@ export function detectStaleSkills(
   const lastUsed = getSkillLastUsed(units);
   const cutoff = Date.now() - (thresholdDays * 24 * 60 * 60 * 1000);
   const stale: string[] = [];
-
-  // Check all installed skills, not just those with usage data
-  const gsdSkillsDir = join(gsdHome(), "agent", "skills");
-  const skillsDir = join(homedir(), ".agents", "skills");
-  const claudeSkillsDir = join(homedir(), ".claude", "skills");
-  const installedSet = new Set([
-    ...listSkillNames(gsdSkillsDir),
-    ...listSkillNames(skillsDir),
-    ...listSkillNames(claudeSkillsDir),
-  ]);
-  const installed = [...installedSet];
+  const installed = getInstalledSkillNames();
 
   for (const skill of installed) {
     const lastTs = lastUsed.get(skill);
@@ -125,17 +105,3 @@ export function detectStaleSkills(
 
   return stale;
 }
-
-// ─── Internals ────────────────────────────────────────────────────────────────
-
-function listSkillNames(skillsDir: string): string[] {
-  if (!existsSync(skillsDir)) return [];
-  try {
-    return readdirSync(skillsDir, { withFileTypes: true })
-      .filter(d => d.isDirectory() && !d.name.startsWith("."))
-      .filter(d => existsSync(join(skillsDir, d.name, "SKILL.md")))
-      .map(d => d.name);
-  } catch {
-    return [];
-  }
-}

package/src/resources/extensions/gsd/skills/gsd-headless/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gsd-headless
-description: Orchestrate GSD (Git Ship Done) projects programmatically via headless CLI. Use when an agent needs to create milestones from specs, execute software development workflows, monitor task progress, check project status, or control GSD execution (pause/stop/skip/steer). Triggers on requests to "run gsd", "create milestone", "execute project", "check gsd status", "orchestrate development", "run headless workflow", or any programmatic interaction with the GSD project management system. Essential for building orchestrators that coordinate multiple GSD workers.
+description: Orchestrate GSD (Git Ship Done) projects programmatically via headless CLI. Use when an agent needs to create milestones from specs, execute dev workflows, monitor progress, check status, or control execution (pause/stop/skip/steer). Triggers on "run gsd", "create milestone", "execute project", "check gsd status", "orchestrate development", "run headless workflow", or building orchestrators that coordinate multiple GSD workers.
 ---
 
 # GSD Headless Orchestration

package/src/resources/extensions/gsd/skills.ts

@@ -0,0 +1,75 @@
+/**
+ * Canonical skill access for GSD extension code.
+ *
+ * Prefer {@link getInstalledSkills} (ResourceLoader / getLoadedSkills cache)
+ * over ad-hoc directory scans.
+ */
+
+import { getLoadedSkills, type Skill } from "@gsd/pi-coding-agent";
+import { resolveSkillReference, type SkillResolution } from "./preferences-skills.js";
+
+/** Normalize a skill reference the same way preference matching does. */
+export function normalizeSkillName(ref: string): string {
+  return ref.trim().toLowerCase();
+}
+
+/** Installed skills from the pi loader cache, or an explicit override (tests). */
+export function getInstalledSkills(override?: Skill[]): Skill[] {
+  if (override) return override;
+  return typeof getLoadedSkills === "function" ? getLoadedSkills() : [];
+}
+
+/** Skill names from the installed catalog. */
+export function getInstalledSkillNames(skills?: Skill[]): string[] {
+  return getInstalledSkills(skills).map((skill) => skill.name);
+}
+
+/** Snapshot normalized skill names for auto-mode diffing. */
+export function snapshotInstalledSkillNames(skills?: Skill[]): Set<string> {
+  return new Set(getInstalledSkillNames(skills).map(normalizeSkillName));
+}
+
+/** Names present now but absent from `baseline`. */
+export function detectNewlyInstalledSkills(baseline: Set<string>, skills?: Skill[]): string[] {
+  const current = snapshotInstalledSkillNames(skills);
+  return [...current].filter((name) => !baseline.has(name));
+}
+
+export type InstalledSkillResolution = SkillResolution & { skill?: Skill };
+
+/**
+ * Resolve a preference skill reference to a path, validating against the
+ * installed catalog when loader data is available.
+ */
+export function resolveInstalledSkill(
+  ref: string,
+  cwd: string,
+  skills?: Skill[],
+): InstalledSkillResolution {
+  const resolution = resolveSkillReference(ref, cwd);
+  const installed = getInstalledSkills(skills);
+  if (installed.length === 0) {
+    return resolution;
+  }
+
+  const byName = new Map(installed.map((skill) => [normalizeSkillName(skill.name), skill]));
+  const normalizedRef = normalizeSkillName(ref);
+  const byRef = byName.get(normalizedRef);
+  if (byRef) {
+    return {
+      ...resolution,
+      resolvedPath: byRef.filePath,
+      method: resolution.method === "unresolved" ? "user-skill" : resolution.method,
+      skill: byRef,
+    };
+  }
+
+  if (resolution.resolvedPath) {
+    const match = installed.find((skill) => skill.filePath === resolution.resolvedPath);
+    if (match) {
+      return { ...resolution, skill: match };
+    }
+  }
+
+  return resolution;
+}