@opengsd/gsd-core 1.5.0-rc.3 → 1.5.0-rc.4

package/gsd-core/bin/lib/roadmap-parser.cjs

@@ -319,8 +319,17 @@ function stripFencedLines(text) {
 /**
  * Returns a filter function that checks whether a phase directory belongs
  * to the current milestone based on ROADMAP.md phase headings.
+ *
+ * @param cwd - Project working directory.
+ * @param versionOverride - Optional version string to scope the phase filter
+ *   to a specific milestone (e.g. 'v1.2').
+ * @param phaseIdConvention - The resolved `phase_id_convention` config value.
+ *   When `'milestone-prefixed'`, a deprecation warning is emitted for
+ *   free-form ROADMAPs that lack versioned milestone headings. When absent or
+ *   any other value, the warning is suppressed — legacy/default projects must
+ *   never see spurious warnings.
  */
-function getMilestonePhaseFilter(cwd, versionOverride) {
+function getMilestonePhaseFilter(cwd, versionOverride, phaseIdConvention) {
     const milestonePhaseNums = new Set();
     let missingExplicitVersion = false;
     try {
@@ -331,9 +340,10 @@ function getMilestonePhaseFilter(cwd, versionOverride) {
         let roadmap = extractCurrentMilestone(roadmapContent, cwd);
         const hasVersionedMilestonesGlobal = /^#{1,3}\s+.*v\d+\.\d+/mi.test(roadmapContent);
         const hasPhaseHeadings = /#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+[\w]/i.test(roadmapContent);
-        if (!hasVersionedMilestonesGlobal && hasPhaseHeadings) {
+        if (!hasVersionedMilestonesGlobal && hasPhaseHeadings && phaseIdConvention === 'milestone-prefixed') {
             console.warn('[gsd] Deprecated: free-form ROADMAP.md detected (no versioned milestone headings). ' +
-                'Set phase_id_convention in config.json to suppress this warning.');
+                'The project has phase_id_convention set to "milestone-prefixed" in config.json but the ' +
+                'ROADMAP does not use versioned milestone headings. Run `gsd-tools roadmap upgrade --convention milestone-prefixed` to migrate (dry-run by default).');
         }
         if (versionOverride) {
             const escapedVersion = escapeRegex(versionOverride);

package/gsd-core/bin/lib/runtime-artifact-conversion.cjs

@@ -1607,6 +1607,238 @@ function convertClaudeToKiloFrontmatter(content, { isAgent = false } = {}) {
     const newFrontmatter = newLines.join('\n').trim();
     return `---\n${newFrontmatter}\n---${body}`;
 }
+// ── Agent converters — #1182 extraction ─────────────────────────────────────
+// These were previously only in bin/install.js. Extracted here so the module
+// is self-contained and #1173 descriptor-driven dispatch can call them without
+// reaching through the Installer Module.
+// NOTE: Do NOT remove the inline copies from bin/install.js in this PR —
+// that is #1175. This PR only adds them to the module's export surface.
+// Copilot tool name mapping — Claude Code tools to GitHub Copilot tools
+// Tool mapping applies ONLY to agents, NOT to skills (per CONTEXT.md decision)
+const claudeToCopilotTools = {
+    Read: 'read',
+    Write: 'edit',
+    Edit: 'edit',
+    Bash: 'execute',
+    Grep: 'search',
+    Glob: 'search',
+    Task: 'agent',
+    WebSearch: 'web',
+    WebFetch: 'web',
+    TodoWrite: 'todo',
+    AskUserQuestion: 'ask_user',
+    SlashCommand: 'skill',
+};
+// Tool name mapping from Claude Code to Gemini CLI
+// Gemini CLI uses snake_case built-in tool names
+const claudeToGeminiTools = {
+    Read: 'read_file',
+    Write: 'write_file',
+    Edit: 'replace',
+    Bash: 'run_shell_command',
+    Glob: 'glob',
+    Grep: 'search_file_content',
+    WebSearch: 'google_web_search',
+    WebFetch: 'web_fetch',
+    TodoWrite: 'write_todos',
+};
+/**
+ * Convert a Claude Code tool name to Gemini CLI format
+ * - Applies Claude→Gemini mapping (Read→read_file, Bash→run_shell_command, etc.)
+ * - Filters out MCP tools (mcp__*) — they are auto-discovered at runtime in Gemini
+ * - Filters out Task/Agent — agents are auto-registered as tools in Gemini
+ * @returns {string|null} Gemini tool name, or null if tool should be excluded
+ */
+function convertGeminiToolName(claudeTool) {
+    // MCP tools: exclude — auto-discovered from mcpServers config at runtime
+    if (claudeTool.startsWith('mcp__')) {
+        return null;
+    }
+    // Task/Agent: exclude — agents are auto-registered as callable tools.
+    // AskUserQuestion: exclude — Gemini CLI does not expose an ask_user tool;
+    // emitting it causes frontmatter validation errors (#3362).
+    if (claudeTool === 'Task' ||
+        claudeTool === 'Agent' ||
+        claudeTool === 'AskUserQuestion' ||
+        claudeTool === 'ask_user') {
+        return null;
+    }
+    // Check for explicit mapping
+    if (claudeToGeminiTools[claudeTool]) {
+        return claudeToGeminiTools[claudeTool];
+    }
+    // Default: lowercase
+    return claudeTool.toLowerCase();
+}
+/**
+ * Convert a Claude Code tool name to GitHub Copilot format.
+ * - Applies explicit mapping from claudeToCopilotTools
+ * - Handles mcp__context7__* prefix → io.github.upstash/context7/*
+ * - Falls back to lowercase for unknown tools
+ */
+function convertCopilotToolName(claudeTool) {
+    // mcp__context7__* wildcard → io.github.upstash/context7/*
+    if (claudeTool.startsWith('mcp__context7__')) {
+        return 'io.github.upstash/context7/' + claudeTool.slice('mcp__context7__'.length);
+    }
+    // Check explicit mapping
+    if (claudeToCopilotTools[claudeTool]) {
+        return claudeToCopilotTools[claudeTool];
+    }
+    // mcp__{tavily,ref,jina,exa,firecrawl}__* use the generic MCP passthrough like exa/firecrawl;
+    // add explicit Copilot registry mappings when the io.github ids are confirmed (#657 follow-up)
+    // Default: lowercase
+    return claudeTool.toLowerCase();
+}
+/**
+ * Convert a Claude agent (.md) to a GitHub Copilot agent.
+ * CONV-04: JSON array format. CONV-05: Tool name mapping.
+ */
+function convertClaudeAgentToCopilotAgent(content, isGlobal = false) {
+    const converted = convertClaudeToCopilotContent(content, isGlobal);
+    const { frontmatter, body } = extractFrontmatterAndBody(converted);
+    if (!frontmatter)
+        return converted;
+    const name = extractFrontmatterField(frontmatter, 'name') || 'unknown';
+    const description = extractFrontmatterField(frontmatter, 'description') || '';
+    const color = extractFrontmatterField(frontmatter, 'color');
+    const toolsRaw = extractFrontmatterField(frontmatter, 'tools') || '';
+    // CONV-04 + CONV-05: Map tools, deduplicate, format as JSON array
+    const claudeTools = toolsRaw.split(',').map(t => t.trim()).filter(Boolean);
+    const mappedTools = claudeTools.map(t => convertCopilotToolName(t));
+    const uniqueTools = [...new Set(mappedTools)];
+    const toolsArray = uniqueTools.length > 0
+        ? "['" + uniqueTools.join("', '") + "']"
+        : '[]';
+    // Reconstruct frontmatter in Copilot format. Quote description (#2876)
+    // so a leading YAML flow indicator (`[BETA] …`, `{ … }`, etc.) doesn't
+    // crash the Copilot frontmatter loader.
+    let fm = `---\nname: ${name}\ndescription: ${yamlQuote(description)}\ntools: ${toolsArray}\n`;
+    if (color)
+        fm += `color: ${color}\n`;
+    fm += '---';
+    return `${fm}\n${body}`;
+}
+/**
+ * Convert a Claude agent (.md) to an Antigravity agent.
+ * Uses Gemini tool names since Antigravity runs on Gemini 3 backend.
+ */
+function convertClaudeAgentToAntigravityAgent(content, isGlobal = false) {
+    const converted = convertClaudeToAntigravityContent(content, isGlobal);
+    const { frontmatter, body } = extractFrontmatterAndBody(converted);
+    if (!frontmatter)
+        return converted;
+    const name = extractFrontmatterField(frontmatter, 'name') || 'unknown';
+    const description = extractFrontmatterField(frontmatter, 'description') || '';
+    const color = extractFrontmatterField(frontmatter, 'color');
+    const toolsRaw = extractFrontmatterField(frontmatter, 'tools') || '';
+    // Map tools to Gemini equivalents (reuse existing convertGeminiToolName)
+    const claudeTools = toolsRaw.split(',').map(t => t.trim()).filter(Boolean);
+    const mappedTools = claudeTools.map(t => convertGeminiToolName(t)).filter(Boolean);
+    // #2876: quote description for the same reason as the skill variant.
+    let fm = `---\nname: ${name}\ndescription: ${yamlQuote(description)}\ntools: ${mappedTools.join(', ')}\n`;
+    if (color)
+        fm += `color: ${color}\n`;
+    fm += '---';
+    return `${fm}\n${body}`;
+}
+/**
+ * Convert Claude Code agent markdown to Cursor agent format.
+ * Strips frontmatter fields Cursor doesn't support (color, skills),
+ * converts tool references, and adds a role context header.
+ */
+function convertClaudeAgentToCursorAgent(content) {
+    const converted = convertClaudeToCursorMarkdown(content);
+    const { frontmatter, body } = extractFrontmatterAndBody(converted);
+    if (!frontmatter)
+        return converted;
+    const name = extractFrontmatterField(frontmatter, 'name') || 'unknown';
+    const description = extractFrontmatterField(frontmatter, 'description') || '';
+    const cleanFrontmatter = `---\nname: ${yamlIdentifier(name)}\ndescription: ${yamlQuote(toSingleLine(description))}\n---`;
+    return `${cleanFrontmatter}\n${body}`;
+}
+/**
+ * Convert Claude Code agent markdown to Windsurf agent format.
+ * Strips frontmatter fields Windsurf doesn't support (color, skills),
+ * converts tool references, and adds a role context header.
+ */
+function convertClaudeAgentToWindsurfAgent(content) {
+    const converted = convertClaudeToWindsurfMarkdown(content);
+    const { frontmatter, body } = extractFrontmatterAndBody(converted);
+    if (!frontmatter)
+        return converted;
+    const name = extractFrontmatterField(frontmatter, 'name') || 'unknown';
+    const description = extractFrontmatterField(frontmatter, 'description') || '';
+    const cleanFrontmatter = `---\nname: ${yamlIdentifier(name)}\ndescription: ${yamlQuote(toSingleLine(description))}\n---`;
+    return `${cleanFrontmatter}\n${body}`;
+}
+/**
+ * Convert Claude Code agent markdown to Augment agent format.
+ * Strips frontmatter fields Augment doesn't support (color, skills),
+ * converts tool references, and cleans up for Augment agents.
+ */
+function convertClaudeAgentToAugmentAgent(content) {
+    const converted = convertClaudeToAugmentMarkdown(content);
+    const { frontmatter, body } = extractFrontmatterAndBody(converted);
+    if (!frontmatter)
+        return converted;
+    const name = extractFrontmatterField(frontmatter, 'name') || 'unknown';
+    const description = extractFrontmatterField(frontmatter, 'description') || '';
+    const cleanFrontmatter = `---\nname: ${yamlIdentifier(name)}\ndescription: ${yamlQuote(toSingleLine(description))}\n---`;
+    return `${cleanFrontmatter}\n${body}`;
+}
+function convertClaudeAgentToTraeAgent(content) {
+    const converted = convertClaudeToTraeMarkdown(content);
+    const { frontmatter, body } = extractFrontmatterAndBody(converted);
+    if (!frontmatter)
+        return converted;
+    const name = extractFrontmatterField(frontmatter, 'name') || 'unknown';
+    const description = extractFrontmatterField(frontmatter, 'description') || '';
+    const cleanFrontmatter = `---\nname: ${yamlIdentifier(name)}\ndescription: ${yamlQuote(toSingleLine(description))}\n---`;
+    return `${cleanFrontmatter}\n${body}`;
+}
+function convertClaudeAgentToCodebuddyAgent(content) {
+    const converted = convertClaudeToCodebuddyMarkdown(content);
+    const { frontmatter, body } = extractFrontmatterAndBody(converted);
+    if (!frontmatter)
+        return converted;
+    const name = extractFrontmatterField(frontmatter, 'name') || 'unknown';
+    const description = extractFrontmatterField(frontmatter, 'description') || '';
+    const cleanFrontmatter = `---\nname: ${yamlIdentifier(name)}\ndescription: ${yamlQuote(toSingleLine(description))}\n---`;
+    return `${cleanFrontmatter}\n${body}`;
+}
+function convertClaudeAgentToClineAgent(content) {
+    const converted = convertClaudeToCliineMarkdown(content);
+    const { frontmatter, body } = extractFrontmatterAndBody(converted);
+    if (!frontmatter)
+        return converted;
+    const name = extractFrontmatterField(frontmatter, 'name') || 'unknown';
+    const description = extractFrontmatterField(frontmatter, 'description') || '';
+    const cleanFrontmatter = `---\nname: ${yamlIdentifier(name)}\ndescription: ${yamlQuote(toSingleLine(description))}\n---`;
+    return `${cleanFrontmatter}\n${body}`;
+}
+/**
+ * Convert Claude Code agent markdown to Codex agent format.
+ * Applies base markdown conversions, then adds a <codex_agent_role> header
+ * and cleans up frontmatter (removes tools/color fields).
+ */
+function convertClaudeAgentToCodexAgent(content) {
+    const converted = convertClaudeToCodexMarkdown(content);
+    const { frontmatter, body } = extractFrontmatterAndBody(converted);
+    if (!frontmatter)
+        return converted;
+    const name = extractFrontmatterField(frontmatter, 'name') || 'unknown';
+    const description = extractFrontmatterField(frontmatter, 'description') || '';
+    const tools = extractFrontmatterField(frontmatter, 'tools') || '';
+    const roleHeader = `<codex_agent_role>
+role: ${name}
+tools: ${tools}
+purpose: ${toSingleLine(description)}
+</codex_agent_role>`;
+    const cleanFrontmatter = `---\nname: ${yamlQuote(name)}\ndescription: ${yamlQuote(toSingleLine(description))}\n---`;
+    return `${cleanFrontmatter}\n\n${roleHeader}\n${body}`;
+}
+// ── End agent converters #1182 ───────────────────────────────────────────────
 /**
  * Shared SKILL.md writer for the OpenCode-family runtimes (OpenCode + Kilo),
  * which share a config schema (Kilo derives from OpenCode). OpenCode discovers
@@ -1697,4 +1929,18 @@ module.exports = {
     convertClaudeCommandToKiloSkill,
     readGsdCommandNames,
     transformContentToHyphen,
+    // #1182: agent converters + tool-name table dependency closure
+    claudeToCopilotTools,
+    convertCopilotToolName,
+    claudeToGeminiTools,
+    convertGeminiToolName,
+    convertClaudeAgentToCopilotAgent,
+    convertClaudeAgentToAntigravityAgent,
+    convertClaudeAgentToCursorAgent,
+    convertClaudeAgentToWindsurfAgent,
+    convertClaudeAgentToAugmentAgent,
+    convertClaudeAgentToTraeAgent,
+    convertClaudeAgentToCodebuddyAgent,
+    convertClaudeAgentToClineAgent,
+    convertClaudeAgentToCodexAgent,
 };

package/gsd-core/bin/lib/runtime-artifact-layout.cjs

@@ -19,7 +19,7 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_os_1 = __importDefault(require("node:os"));
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const installProfiles = require("./install-profiles.cjs");
-const { stageSkillsForProfile, stageAgentsForProfile, stageSkillsForRuntimeAsSkills, stageCommandsForRuntimeFlat, } = installProfiles;
+const { stageSkillsForProfile, stageAgentsForProfile, stageAgentsForRuntimeWithConverter, stageSkillsForRuntimeAsSkills, stageCommandsForRuntimeFlat, } = installProfiles;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const runtimeArtifactConversion = require("./runtime-artifact-conversion.cjs");
 const conversionExports = runtimeArtifactConversion;
@@ -146,6 +146,35 @@ function agentsKind(destSubpath, prefix, configDir) {
         stage: (resolved) => stageAgentsForProfile(findAgentsSourceRoot(configDir), resolved),
     };
 }
+/**
+ * Build a converted-agents kind descriptor for runtimes whose agent `.md` files
+ * need runtime-specific frontmatter/body conversion (e.g. Copilot, Cursor, Codex).
+ *
+ * Unlike `agentsKind` (which raw-copies source files), this kind applies
+ * `converterName` from Runtime Artifact Conversion exports to each agent file
+ * during staging, writing flat `${name}.md` files to the staged directory.
+ *
+ * Agent filenames are preserved verbatim (the prefix is already embedded in the
+ * agent stem — e.g. `gsd-planner.md`).
+ *
+ * Mirrors the `convertedCommandsKind` pattern (#785).
+ *
+ * @param destSubpath   destination subpath within configDir (e.g. 'agents')
+ * @param prefix        filename prefix (informational; not applied here)
+ * @param converterName name of converter function in Runtime Artifact Conversion exports
+ * @param configDir     runtime config dir (for .gsd-source marker resolution)
+ */
+function convertedAgentsKind(destSubpath, prefix, converterName, configDir) {
+    return {
+        kind: 'agents',
+        destSubpath,
+        prefix,
+        stage: (resolved) => {
+            const converter = conversionExports[converterName];
+            return stageAgentsForRuntimeWithConverter(findAgentsSourceRoot(configDir), resolved, converter);
+        },
+    };
+}
 function kimiAgentsKind(destSubpath, prefix, configDir) {
     return {
         kind: 'kimi-agents',
@@ -262,7 +291,10 @@ function dispatchKindEntry(entry, runtime, configDir, scope) {
             }
             return convertedCommandsKind(destSubpath, prefix, converter, configDir);
         case 'agents':
-            return agentsKind(destSubpath, prefix, configDir);
+            if (converter == null) {
+                return agentsKind(destSubpath, prefix, configDir);
+            }
+            return convertedAgentsKind(destSubpath, prefix, converter, configDir);
         case 'skills':
             if (converter == null) {
                 throw new TypeError(`resolveRuntimeArtifactLayout: skills entry for '${runtime}' has converter=null (converter is required for skills)`);