@opengsd/gsd-pi 1.0.2-dev.867e002 → 1.0.2-dev.a271e2d

package/dist/resources/extensions/gsd/preferences-skills.js

@@ -11,10 +11,17 @@ import { gsdHome } from "./gsd-home.js";
 import { statSync } from "node:fs";
 import { validatePreferences } from "./preferences-validation.js";
 /**
- * Known skill directories, in priority order.
- * GSD bundled skills live in ~/.gsd/agent/skills/ and win name collisions.
- * User-global and project-local ecosystem directories remain available as
- * read-only discovery sources, followed by Claude Code compatibility paths.
+ * Known skill directories for **preference reference resolution** (bare skill names).
+ *
+ * Search order (first match wins):
+ * 1. ~/.gsd/agent/skills/ (GSD bundled)
+ * 2. ~/.agents/skills/ (ecosystem global)
+ * 3. .agents/skills/ (project ecosystem)
+ * 4. ~/.claude/skills/ and .claude/skills/ (Claude Code compatibility)
+ *
+ * Note: the ResourceLoader catalog uses PackageManager precedence instead —
+ * project `.gsd/skills` and `.agents/skills` can override bundled GSD skills
+ * on name collision. See docs/dev/what-is-pi/09-the-customization-stack.md.
  */
 export function getSkillSearchDirs(cwd) {
     const dirs = [

package/dist/resources/extensions/gsd/preferences.js

@@ -455,9 +455,10 @@ function mergePreDispatchHooks(base, override) {
     return merged.length > 0 ? merged : undefined;
 }
 // ─── System Prompt Rendering ──────────────────────────────────────────────────
-export function renderPreferencesForSystemPrompt(preferences, resolutions) {
+export function renderPreferencesForSystemPrompt(preferences, resolutions, options) {
     const validated = validatePreferences(preferences);
     const lines = ["## GSD Skill Preferences"];
+    const includeResolvedPaths = options?.includeResolvedPaths ?? true;
     if (validated.errors.length > 0) {
         lines.push("- Validation: some preference values were ignored because they were invalid.");
     }
@@ -466,7 +467,18 @@ export function renderPreferencesForSystemPrompt(preferences, resolutions) {
     }
     preferences = validated.preferences;
     lines.push("- Treat these as explicit skill-selection policy for GSD work.", "- If a listed skill exists and is relevant, load and follow it instead of treating it as a vague suggestion.", "- Current user instructions still override these defaults.");
-    const fmt = (ref) => resolutions ? formatSkillRef(ref, resolutions) : ref;
+    const fmt = (ref) => {
+        if (!resolutions)
+            return ref;
+        if (!includeResolvedPaths) {
+            const resolution = resolutions.get(ref);
+            if (!resolution || resolution.method === "unresolved") {
+                return `${ref} (⚠ not found — check skill name or path)`;
+            }
+            return ref;
+        }
+        return formatSkillRef(ref, resolutions);
+    };
     if (preferences.always_use_skills && preferences.always_use_skills.length > 0) {
         lines.push("- Always use these skills when relevant:");
         for (const skill of preferences.always_use_skills) {

package/dist/resources/extensions/gsd/prompt-loader.js

@@ -21,6 +21,7 @@ import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { logWarning } from "./workflow-logger.js";
 import { gsdHome } from "./gsd-home.js";
+import { chooseVisionAskVariant } from "./vision-ask.js";
 function hasRequiredExtensionAssets(rootDir, exists = existsSync) {
     return (exists(join(rootDir, "prompts")) &&
         exists(join(rootDir, "templates", "task-summary.md")));
@@ -168,6 +169,7 @@ export function loadPrompt(name, vars = {}) {
         planTemplatePath: join(getTemplatesDir(), "plan.md"),
         taskPlanTemplatePath: join(getTemplatesDir(), "task-plan.md"),
         taskSummaryTemplatePath: join(getTemplatesDir(), "task-summary.md"),
+        visionAsk: chooseVisionAskVariant(),
         skillActivation: "If a `GSD Skill Preferences` block is present in system context, use it and the `<available_skills>` catalog in your system prompt to decide which skills to load and follow for this unit, without relaxing required verification or artifact rules.",
         ...vars,
     };

package/dist/resources/extensions/gsd/prompts/discuss.md

@@ -1,8 +1,10 @@
 {{preamble}}
 
-Ask: "What's the vision?" once, then use the reply as vision input.
+Ask exactly this once: "{{visionAsk}}" Then use the user's reply as vision input.
 
-**Special handling:** If the **user's** message is status, branch state, clarification, or any other non-project-description, treat it as vision input and proceed instead of repeating "What's the vision?" Do **not** treat the system preamble above (e.g. "New milestone M00X.") as vision input — wait for the user.
+The opener is intentionally variable so GSD feels alive across project starts. Keep it natural, easy to answer, and assistant/developer shaped: plain language, light guidance, no corporate wording, no roleplay.
+
+**Special handling:** If the **user's** message is status, branch state, clarification, or any other non-project-description, treat it as vision input and proceed instead of repeating the opener. Do **not** treat the system preamble above (e.g. "New milestone M00X.") as vision input — wait for the user.
 
 ## Reflection Step
 

package/dist/resources/extensions/gsd/prompts/guided-discuss-milestone.md

@@ -4,6 +4,8 @@ Discuss milestone {{milestoneId}} ("{{milestoneTitle}}"). Identify real gray are
 
 **Structured questions available: {{structuredQuestionsAvailable}}**
 
+**Conversation opener:** For the first user-facing question round, if you need a broad starting question, use: "{{visionAsk}}" Pair it with investigation-shaped follow-ups. Keep the tone natural and easy to answer, like an assistant/developer helping the user shape the next piece of work.
+
 {{inlinedTemplates}}
 
 ---

package/dist/resources/extensions/gsd/prompts/system.md

@@ -19,9 +19,7 @@ Leave the project ready for the next agent to understand and continue. Artifacts
 
 ## Skills
 
-GSD ships with bundled skills. When the task matches, load the relevant skill file with `read` before starting. Use bare skill names; GSD resolves paths.
-
-{{bundledSkillsTable}}
+GSD ships with bundled skills. Installed skills are listed in `<available_skills>` in your system prompt — load the relevant skill file with `read` using the path shown there before starting matching work. Use bare skill names in preferences; GSD resolves paths.
 
 ## Hard Rules
 

package/dist/resources/extensions/gsd/queue-reorder-ui.js

@@ -8,9 +8,9 @@
  * Conflicting depends_on entries are auto-removed on confirm.
  */
 import { Key, matchesKey, truncateToWidth } from "@gsd/pi-tui";
-import { makeUI } from "../shared/tui.js";
 import { GLYPH } from "../shared/mod.js";
 import { validateQueueOrder } from "./queue-order.js";
+import { renderDialogFrame, renderKeyHints } from "./tui/render-kit.js";
 /**
  * Show the queue reorder overlay.
  * Returns the new order + deps to remove, or null if cancelled.
@@ -26,6 +26,7 @@ export async function showQueueReorder(ctx, completed, pending) {
         let grabbed = false;
         let scrollOffset = 0;
         let cachedLines;
+        let cachedWidth;
         let validation;
         // Mutable deps map — tracks removals during this session
         const liveDeps = new Map();
@@ -42,6 +43,7 @@ export async function showQueueReorder(ctx, completed, pending) {
         revalidate();
         function refresh() {
             cachedLines = undefined;
+            cachedWidth = undefined;
             tui.requestRender();
         }
         function swapItems(fromIdx, toIdx) {
@@ -125,17 +127,14 @@ export async function showQueueReorder(ctx, completed, pending) {
             }
         }
         function render(width) {
-            if (cachedLines)
+            if (cachedLines && cachedWidth === width)
                 return cachedLines;
-            const ui = makeUI(theme, width);
+            const contentWidth = Math.max(1, width - 4);
             const lines = [];
             const queueRows = [];
-            const push = (...rows) => { for (const r of rows)
-                lines.push(...r); };
-            const add = (s) => truncateToWidth(s, width);
+            const add = (s) => truncateToWidth(s, contentWidth);
             let cursorQueueRow = 0;
-            const headerText = grabbed ? "  Queue Reorder — Moving Item" : "  Queue Reorder";
-            push(ui.bar(), ui.blank(), ui.header(headerText), ui.blank());
+            const headerText = grabbed ? "Queue Reorder - Moving Item" : "Queue Reorder";
             // Completed milestones (dimmed)
             if (completed.length > 0) {
                 lines.push(add(theme.fg("dim", "  Completed:")));
@@ -143,7 +142,7 @@ export async function showQueueReorder(ctx, completed, pending) {
                     const label = m.title && m.title !== m.id ? `${m.id}  ${m.title}` : m.id;
                     lines.push(add(`    ${theme.fg("dim", `${GLYPH.statusDone} ${label}`)}`));
                 }
-                push(ui.blank());
+                lines.push("");
             }
             // Pending milestones
             const queueLabel = grabbed ? "  Queue (space to release, ↑/↓ to move):" : "  Queue (space to grab, ↑/↓ to navigate):";
@@ -190,7 +189,7 @@ export async function showQueueReorder(ctx, completed, pending) {
             // Removed deps feedback
             const trailingLines = [];
             if (removedDeps.length > 0) {
-                trailingLines.push(...ui.blank());
+                trailingLines.push("");
                 for (const r of removedDeps) {
                     trailingLines.push(add(`  ${theme.fg("success", `${GLYPH.statusDone} Removed: ${r.milestone} depends_on ${r.dep}`)}`));
                 }
@@ -198,10 +197,9 @@ export async function showQueueReorder(ctx, completed, pending) {
             // Circular warning
             const circ = validation.violations.find(v => v.type === 'circular');
             if (circ) {
-                trailingLines.push(...ui.blank());
+                trailingLines.push("");
                 trailingLines.push(add(`  ${theme.fg("error", `${GLYPH.statusWarning} ${circ.message}`)}`));
             }
-            trailingLines.push(...ui.blank());
             // Hints — context-sensitive based on grab state
             const hints = [];
             if (grabbed) {
@@ -221,9 +219,9 @@ export async function showQueueReorder(ctx, completed, pending) {
                 hints.push("enter ok");
             }
             hints.push("esc");
-            trailingLines.push(...ui.hints(hints), ...ui.bar());
             const maxOverlayRows = Math.max(10, process.stdout.rows ? Math.floor(process.stdout.rows * 0.8) : 24);
-            const availableQueueRows = Math.max(1, maxOverlayRows - lines.length - trailingLines.length);
+            const frameRows = 4;
+            const availableQueueRows = Math.max(1, maxOverlayRows - frameRows - lines.length - trailingLines.length);
             const maxScroll = Math.max(0, queueRows.length - availableQueueRows);
             if (cursorQueueRow < scrollOffset) {
                 scrollOffset = cursorQueueRow;
@@ -232,11 +230,23 @@ export async function showQueueReorder(ctx, completed, pending) {
                 scrollOffset = cursorQueueRow - availableQueueRows + 1;
             }
             scrollOffset = Math.min(Math.max(scrollOffset, 0), maxScroll);
-            lines.push(...queueRows.slice(scrollOffset, scrollOffset + availableQueueRows), ...trailingLines);
-            cachedLines = lines;
-            return lines;
+            const queueStartRow = lines.length;
+            const visibleQueueRows = queueRows.slice(scrollOffset, scrollOffset + availableQueueRows);
+            lines.push(...visibleQueueRows, ...trailingLines);
+            cachedLines = renderDialogFrame(theme, headerText, lines, width, {
+                footer: renderKeyHints(theme, hints, contentWidth),
+                scroll: {
+                    offset: scrollOffset,
+                    visibleRows: availableQueueRows,
+                    totalRows: queueRows.length,
+                    trackOffset: queueStartRow,
+                    trackRows: visibleQueueRows.length,
+                },
+            });
+            cachedWidth = width;
+            return cachedLines;
         }
-        return { render, invalidate: () => { cachedLines = undefined; }, handleInput };
+        return { render, invalidate: () => { cachedLines = undefined; cachedWidth = undefined; }, handleInput };
     }, {
         overlay: true,
         overlayOptions: { width: "70%", minWidth: 50, maxHeight: "80%", anchor: "center" },

package/dist/resources/extensions/gsd/repository-registry.js

@@ -50,7 +50,9 @@ function resolveGitWorkingTreeRoot(basePath) {
  */
 export function createRepositoryRegistry(basePath, workspacePrefs) {
     const contract = resolveGsdPathContract(basePath);
-    const projectRoot = resolveGitWorkingTreeRoot(contract.workRoot) ?? contract.projectRoot;
+    const projectRoot = contract.isWorktree
+        ? resolveGitWorkingTreeRoot(contract.workRoot) ?? contract.projectRoot
+        : contract.projectRoot;
     const mode = workspacePrefs?.mode ?? "project";
     const repoMap = new Map();
     // "project" is reserved: always maps to projectRoot and cannot be overridden.

package/dist/resources/extensions/gsd/safety/evidence-collector.js

@@ -15,14 +15,15 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, unlinkS
 import { join, dirname } from "node:path";
 import { randomBytes } from "node:crypto";
 const EXECUTION_TOOL_NAMES = new Set([
-    "bash",
-    "Bash",
-    "PowerShell",
     "async_bash",
+    "bash",
+    "exec_command",
+    "functions.exec_command",
     "gsd_exec",
     "gsd_exec_search",
     "mcp__gsd-workflow__gsd_exec",
     "mcp__gsd-workflow__gsd_exec_search",
+    "powershell",
 ]);
 // ─── Module State ───────────────────────────────────────────────────────────
 let unitEvidence = [];
@@ -45,6 +46,12 @@ export function getFilePaths() {
         .filter((e) => e.kind === "write" || e.kind === "edit")
         .map(e => e.path);
 }
+/** True when a tool name represents a shell/command execution surface. */
+export function isExecutionToolName(name) {
+    if (typeof name !== "string")
+        return false;
+    return EXECUTION_TOOL_NAMES.has(name.trim().toLowerCase());
+}
 // ─── Persistence (Bug #4385 — evidence must survive session restarts) ────────
 /**
  * Build the path for the evidence JSON file for a given unit.
@@ -139,7 +146,7 @@ export function clearEvidenceFromDisk(basePath, milestoneId, sliceId, taskId) {
  * Exit codes and output are filled in by recordToolResult after execution.
  */
 export function recordToolCall(toolCallId, toolName, input) {
-    if (EXECUTION_TOOL_NAMES.has(toolName)) {
+    if (isExecutionToolName(toolName)) {
         unitEvidence.push({
             kind: "bash",
             toolCallId,

package/dist/resources/extensions/gsd/skill-activation.js

@@ -0,0 +1,233 @@
+/**
+ * Skill activation and discovery prompt blocks for GSD auto-mode units.
+ */
+import { basename } from "node:path";
+import { parseTaskPlanFile } from "./files.js";
+import { loadEffectiveGSDPreferences, resolveAllSkillReferences, resolveSkillDiscoveryMode, } from "./preferences.js";
+import { filterSkillsByManifest, resolveSkillManifest, warnIfManifestHasMissingSkills } from "./skill-manifest.js";
+import { getInstalledSkills } from "./skills.js";
+import { logWarning } from "./workflow-logger.js";
+function normalizeSkillReference(ref) {
+    const normalized = ref.replace(/\\/g, "/").trim();
+    const base = basename(normalized).replace(/\.md$/i, "");
+    const name = /^SKILL$/i.test(base)
+        ? basename(normalized.replace(/\/SKILL(?:\.md)?$/i, ""))
+        : base;
+    return name.trim().toLowerCase();
+}
+function tokenizeSkillContext(...parts) {
+    const tokens = new Set();
+    const addVariants = (raw) => {
+        const value = raw.trim().toLowerCase();
+        if (!value || value.length < 2)
+            return;
+        tokens.add(value);
+        tokens.add(value.replace(/[-_]+/g, " "));
+        tokens.add(value.replace(/\s+/g, "-"));
+        tokens.add(value.replace(/\s+/g, ""));
+    };
+    for (const part of parts) {
+        if (!part)
+            continue;
+        const text = part.toLowerCase();
+        const phraseMatches = text.match(/[a-z0-9][a-z0-9+.#/_-]{1,}/g) ?? [];
+        for (const match of phraseMatches) {
+            addVariants(match);
+            for (const piece of match.split(/[^a-z0-9+.#]+/g)) {
+                if (piece.length >= 3)
+                    addVariants(piece);
+            }
+        }
+    }
+    return tokens;
+}
+function skillMatchesContext(skill, contextTokens) {
+    const haystacks = [
+        skill.name.toLowerCase(),
+        skill.name.toLowerCase().replace(/[-_]+/g, " "),
+        skill.description.toLowerCase(),
+    ];
+    return [...contextTokens].some(token => token.length >= 3 && haystacks.some(haystack => haystack.includes(token)));
+}
+function resolvePreferenceSkillNames(refs, base) {
+    if (refs.length === 0)
+        return [];
+    const prefs = { always_use_skills: refs };
+    const report = resolveAllSkillReferences(prefs, base);
+    return refs.map(ref => {
+        const resolution = report.resolutions.get(ref);
+        return normalizeSkillReference(resolution?.resolvedPath ?? ref);
+    }).filter(Boolean);
+}
+function ruleMatchesContext(when, contextTokens) {
+    const whenTokens = tokenizeSkillContext(when);
+    return [...whenTokens].some(token => contextTokens.has(token) || [...contextTokens].some(ctx => ctx.includes(token) || token.includes(ctx)));
+}
+function resolveSkillRuleMatches(prefs, contextTokens, base) {
+    if (!prefs?.skill_rules?.length)
+        return { include: [], avoid: [] };
+    const include = [];
+    const avoid = [];
+    for (const rule of prefs.skill_rules) {
+        if (!ruleMatchesContext(rule.when, contextTokens))
+            continue;
+        include.push(...resolvePreferenceSkillNames([...(rule.use ?? []), ...(rule.prefer ?? [])], base));
+        avoid.push(...resolvePreferenceSkillNames(rule.avoid ?? [], base));
+    }
+    return { include, avoid };
+}
+function resolvePreferredSkillNames(prefs, visibleSkills, contextTokens, base) {
+    if (!prefs?.prefer_skills?.length)
+        return [];
+    const preferred = new Set(resolvePreferenceSkillNames(prefs.prefer_skills, base));
+    return visibleSkills
+        .filter(skill => preferred.has(normalizeSkillReference(skill.name)) && skillMatchesContext(skill, contextTokens))
+        .map(skill => normalizeSkillReference(skill.name));
+}
+/** Skill names must be lowercase alphanumeric with hyphens — reject anything else
+ *  to prevent prompt injection via crafted directory names. */
+const SAFE_SKILL_NAME = /^[a-z0-9][a-z0-9-]*$/;
+function formatSkillActivationBlock(skillNames) {
+    const safe = skillNames.filter(name => SAFE_SKILL_NAME.test(name));
+    if (safe.length === 0)
+        return "";
+    // Use explicit parameter syntax so LLMs pass { skill: "..." } instead of { name: "..." }.
+    // The function-call-like syntax `Skill('name')` led LLMs to infer a positional
+    // parameter name, causing tool validation failures — see #2224.
+    const calls = safe.map(name => `Call Skill({ skill: '${name}' })`).join('. ');
+    return `<skill_activation>${calls}.</skill_activation>`;
+}
+/**
+ * Manifest-driven recommendations block — informational only, does NOT
+ * auto-invoke. Lists per-unit-type skills that are installed but not already
+ * activated by explicit user intent (always_use_skills / prefer_skills /
+ * skill_rules / task-plan skills_used). Surfaces relevant skills to the
+ * model so they can be invoked when the model judges them useful.
+ *
+ * This is the additive complement to the existing activation directive:
+ * activation force-invokes (explicit intent), recommendations remind
+ * (manifest defaults). User intent is preserved as the stronger signal
+ * (RFC #4779 design principle); this block only adds visibility.
+ */
+function formatSkillRecommendationsBlock(unitType, skillNames) {
+    if (!unitType)
+        return "";
+    const safe = skillNames.filter(name => SAFE_SKILL_NAME.test(name));
+    if (safe.length === 0)
+        return "";
+    return `<skill_recommendations unit="${unitType}">For this unit type, also consider invoking: ${safe.join(", ")}. Use Skill({ skill: 'name' }) when relevant — these are recommendations, not requirements.</skill_recommendations>`;
+}
+export function buildSkillActivationBlock(params) {
+    const prefs = params.preferences ?? loadEffectiveGSDPreferences(params.base)?.preferences;
+    const contextTokens = tokenizeSkillContext(params.milestoneId, params.milestoneTitle, params.sliceId, params.sliceTitle, params.taskId, params.taskTitle);
+    const loaded = getInstalledSkills(params.skills).filter(skill => !skill.disableModelInvocation);
+    // Skill activation here is driven entirely by explicit sources
+    // (always_use_skills, prefer_skills, skill_rules, task-plan skills_used).
+    // Every match is an explicit user/project intent and must not be dropped
+    // by the unit-type manifest — user intent is stronger signal than
+    // defaults. The manifest's real home is the skill catalog rendering
+    // layer (pi-coding-agent `formatSkillsForPrompt`); that wiring is tracked
+    // as the "load-time short-circuit" follow-up to RFC #4779.
+    //
+    // `unitType` stays plumbed so the strict-mode warning can surface
+    // manifest entries that reference uninstalled skills, and so the
+    // activation-block site is ready to opt in once PR B lands.
+    const visibleSkills = loaded;
+    const manifestScopedSkills = filterSkillsByManifest(visibleSkills, params.unitType);
+    const installedNames = new Set(visibleSkills.map(skill => normalizeSkillReference(skill.name)));
+    warnIfManifestHasMissingSkills(params.unitType, installedNames);
+    const avoided = new Set(resolvePreferenceSkillNames(prefs?.avoid_skills ?? [], params.base));
+    const matched = new Set();
+    for (const name of resolvePreferenceSkillNames(prefs?.always_use_skills ?? [], params.base)) {
+        matched.add(name);
+    }
+    const ruleMatches = resolveSkillRuleMatches(prefs, contextTokens, params.base);
+    for (const name of ruleMatches.include)
+        matched.add(name);
+    for (const name of ruleMatches.avoid)
+        avoided.add(name);
+    for (const name of resolvePreferredSkillNames(prefs, visibleSkills, contextTokens, params.base)) {
+        matched.add(name);
+    }
+    if (params.taskPlanContent) {
+        try {
+            const taskPlan = parseTaskPlanFile(params.taskPlanContent);
+            for (const skillName of taskPlan.frontmatter.skills_used) {
+                matched.add(normalizeSkillReference(skillName));
+            }
+        }
+        catch (err) {
+            logWarning("prompt", `parseTaskPlanFile failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // Heuristic auto-match (gated on skill_discovery: "auto").
+    // For each installed skill, check if its name or description appears in the
+    // unit's context tokens (milestone/slice/task titles). Only consider skills
+    // already on the unit-type manifest allowlist — this keeps the heuristic
+    // narrow and avoids wildly off-topic activations.
+    // Users who set `skill_discovery: "off"` or "suggest" do not get
+    // auto-matched skills (the recommendations block still surfaces manifest
+    // skills passively); only "auto" actually adds them to the activation
+    // directive set. Default `skill_discovery` is "suggest", so this is opt-in.
+    if ((prefs?.skill_discovery ?? "suggest") === "auto") {
+        for (const skill of manifestScopedSkills) {
+            const normalized = normalizeSkillReference(skill.name);
+            if (matched.has(normalized) || avoided.has(normalized))
+                continue;
+            if (skillMatchesContext(skill, contextTokens)) {
+                matched.add(normalized);
+            }
+        }
+    }
+    const ordered = [...matched]
+        .filter(name => installedNames.has(name) && !avoided.has(name))
+        .sort();
+    const activationBlock = formatSkillActivationBlock(ordered);
+    // Omit recommendations when the system catalog is manifest-scoped for this
+    // unit — skill names are already listed in <available_skills>.
+    let recommendationsBlock = "";
+    if (resolveSkillManifest(params.unitType) === null) {
+        const matchedSet = new Set(ordered);
+        const recommendations = (resolveSkillManifest(params.unitType) ?? [])
+            .filter(name => installedNames.has(name) && !avoided.has(name) && !matchedSet.has(name))
+            .sort();
+        recommendationsBlock = formatSkillRecommendationsBlock(params.unitType, recommendations);
+    }
+    if (!activationBlock && !recommendationsBlock)
+        return "";
+    if (!activationBlock)
+        return recommendationsBlock;
+    if (!recommendationsBlock)
+        return activationBlock;
+    return `${activationBlock}\n${recommendationsBlock}`;
+}
+/**
+ * Build the skill discovery template variables for research prompts.
+ * Returns { skillDiscoveryMode, skillDiscoveryInstructions } for template substitution.
+ */
+export function buildSkillDiscoveryVars() {
+    const mode = resolveSkillDiscoveryMode();
+    if (mode === "off") {
+        return {
+            skillDiscoveryMode: "off",
+            skillDiscoveryInstructions: " Skill discovery is disabled. Skip this step.",
+        };
+    }
+    if (mode === "suggest") {
+        return {
+            skillDiscoveryMode: mode,
+            skillDiscoveryInstructions: `
+   Check \`<available_skills>\` for installed skills matching core technologies. For gaps, run \`npx skills find "<technology>"\` and note promising install commands in your research output — do NOT install.`,
+        };
+    }
+    const autoInstall = mode === "auto";
+    const instructions = autoInstall
+        ? `
+   Check \`<available_skills>\` first. For missing core-technology skills, run \`npx skills find "<technology>"\`, install relevant matches with \`npx skills add <owner/repo@skill> -g -y\`, and record them in "Skills Discovered".`
+        : `
+   Check \`<available_skills>\` first. For missing core-technology skills, run \`npx skills find "<technology>"\` and note install commands in your research output — do NOT install.`;
+    return {
+        skillDiscoveryMode: mode,
+        skillDiscoveryInstructions: instructions,
+    };
+}