agileflow 3.1.0 → 3.2.0

package/tools/cli/lib/content-transformer.js

@@ -23,7 +23,7 @@ const { parseFrontmatter, extractBody } = require('../../../scripts/lib/frontmat
  * @example
  * // Object form (simple string replacement)
  * replaceReferences(content, {
- *   'Claude Code': 'Codex CLI',
+ *   'Claude Code': 'OpenAI Codex',
  *   '.claude/': '.codex/',
  *   'CLAUDE.md': 'AGENTS.md'
  * });
@@ -31,7 +31,7 @@ const { parseFrontmatter, extractBody } = require('../../../scripts/lib/frontmat
  * @example
  * // Array form (with regex flags)
  * replaceReferences(content, [
- *   { pattern: 'Claude Code', replacement: 'Codex CLI', flags: 'gi' },
+ *   { pattern: 'Claude Code', replacement: 'OpenAI Codex', flags: 'gi' },
  *   { pattern: /\.claude\//g, replacement: '.codex/' }
  * ]);
  */
@@ -54,7 +54,10 @@ function replaceReferences(content, replacements) {
         const flags = item.flags || 'g';
         regex = new RegExp(escapeRegex(item.pattern), flags);
       }
-      result = result.replace(regex, item.replacement || '');
+      result = result.replace(
+        regex,
+        item.replacement !== undefined && item.replacement !== null ? item.replacement : ''
+      );
     }
   } else if (typeof replacements === 'object' && replacements !== null) {
     // Object form: {pattern: replacement}
@@ -176,11 +179,11 @@ function getFrontmatter(content) {
  */
 const IDE_REPLACEMENTS = {
   /**
-   * Claude Code to Codex CLI conversions
+   * Claude Code to OpenAI Codex conversions
    */
   codex: {
-    'Claude Code': 'Codex CLI',
-    'claude code': 'Codex CLI',
+    'Claude Code': 'OpenAI Codex',
+    'claude code': 'OpenAI Codex',
     CLAUDE_CODE: 'CODEX_CLI',
     'CLAUDE.md': 'AGENTS.md',
     '.claude/': '.codex/',
@@ -197,6 +200,10 @@ const IDE_REPLACEMENTS = {
     'claude code': 'Cursor',
     '.claude/': '.cursor/',
     '.claude\\': '.cursor\\',
+    '.claude/agents/agileflow': '.cursor/agents/AgileFlow',
+    'Task tool': 'subagent spawning',
+    'Task agent': 'subagent',
+    AskUserQuestion: 'numbered list prompt',
   },
 
   /**
@@ -207,9 +214,173 @@ const IDE_REPLACEMENTS = {
     'claude code': 'Windsurf',
     '.claude/': '.windsurf/',
     '.claude\\': '.windsurf\\',
+    'Task tool': 'workflow chaining',
+    'Task agent': 'workflow',
+    AskUserQuestion: 'numbered list prompt',
+    '.claude/agents/agileflow': '.windsurf/skills/agileflow',
   },
 };
 
+/**
+ * Tool reference replacements for IDE capability-aware transformation
+ * Maps Claude Code tool/pattern names to IDE-appropriate alternatives
+ *
+ * @private
+ */
+const TOOL_REFERENCE_REPLACEMENTS = {
+  /**
+   * Cursor: Has subagents but no structured AskUserQuestion
+   * Replaces abstract tool patterns with concrete instructions
+   */
+  cursor: [
+    // AskUserQuestion references
+    {
+      pattern: /call the AskUserQuestion tool/gi,
+      replacement: 'ask the user to reply with their choice (as a numbered list)',
+    },
+    {
+      pattern: /\bAskUserQuestion\b/g,
+      replacement: 'numbered list prompt',
+    },
+    // Task-related references (keep Task, but clarify it's for subagents)
+    {
+      pattern: /Task\(\s*$/gm,
+      replacement: '/* Use Cursor subagents to spawn async work */',
+    },
+    // Task tracking references (not available in Cursor)
+    {
+      pattern: /TaskCreate\b/g,
+      replacement: '(not available - track progress in conversation)',
+    },
+    {
+      pattern: /TaskUpdate\b/g,
+      replacement: '(not available in Cursor)',
+    },
+    {
+      pattern: /TaskList\b/g,
+      replacement: '(not available in Cursor)',
+    },
+  ],
+
+  /**
+   * Windsurf: No subagents, suggests workflow chaining instead
+   * Uses "megaplan" for plan mode
+   */
+  windsurf: [
+    // AskUserQuestion references
+    {
+      pattern: /call the AskUserQuestion tool/gi,
+      replacement: 'ask the user to reply with their choice (as a numbered list)',
+    },
+    {
+      pattern: /\bAskUserQuestion\b/g,
+      replacement: 'numbered list prompt',
+    },
+    // Task references - suggest workflows instead
+    {
+      pattern: /\bTask\s*tool\b/gi,
+      replacement: 'workflow chaining',
+    },
+    {
+      pattern: /call the Task tool/gi,
+      replacement: 'suggest running the relevant /workflow',
+    },
+    {
+      pattern: /Task\(\s*$/gm,
+      replacement: '/* Suggest running /agileflow workflow via cascade */',
+    },
+    // Subagent type references - convert to workflow
+    {
+      pattern: /subagent_type:\s*"agileflow-([^"]+)"/g,
+      replacement: 'workflow: "/agileflow-$1"',
+    },
+    // Task tracking (not available)
+    {
+      pattern: /TaskCreate\b/g,
+      replacement: '(not available - use conversation comments)',
+    },
+    {
+      pattern: /TaskUpdate\b/g,
+      replacement: '(not available)',
+    },
+    {
+      pattern: /TaskList\b/g,
+      replacement: '(not available)',
+    },
+    // Plan mode - use megaplan keyword
+    {
+      pattern: /EnterPlanMode/g,
+      replacement: 'megaplan',
+    },
+    {
+      pattern: /ExitPlanMode/g,
+      replacement: '(end megaplan)',
+    },
+  ],
+
+  /**
+   * Codex: Most limited - no plan mode, hooks, or subagents
+   * Suggests skills and text-only interaction instead
+   */
+  codex: [
+    // AskUserQuestion references - use text-only function
+    {
+      pattern: /call the AskUserQuestion tool/gi,
+      replacement: 'call ask_user_question (text-only, no menus)',
+    },
+    {
+      pattern: /\bAskUserQuestion\b/g,
+      replacement: 'ask_user_question',
+    },
+    // Task/delegation references - suggest skills instead
+    {
+      pattern: /\bTask\s*tool\b/gi,
+      replacement: 'skill invocation',
+    },
+    {
+      pattern: /call the Task tool/gi,
+      replacement: 'invoke the relevant $agileflow skill',
+    },
+    {
+      pattern: /Task\(\s*$/gm,
+      replacement: '/* Invoke relevant skill via $agileflow-name */',
+    },
+    // Subagent type references - convert to skill syntax
+    {
+      pattern: /subagent_type:\s*"agileflow-([^"]+)"/g,
+      replacement: 'skill: "$agileflow-$1"',
+    },
+    // Task tracking (not available)
+    {
+      pattern: /TaskCreate\b/g,
+      replacement: '(not available in Codex)',
+    },
+    {
+      pattern: /TaskUpdate\b/g,
+      replacement: '(not available)',
+    },
+    {
+      pattern: /TaskList\b/g,
+      replacement: '(not available)',
+    },
+    // Plan mode (available in Codex since v0.96 - keep references)
+    // EnterPlanMode and ExitPlanMode are native in Codex, no transformation needed
+    // Hooks (not available)
+    {
+      pattern: /PreToolUse\b/g,
+      replacement: '(not available - no hooks)',
+    },
+    {
+      pattern: /PostToolUse\b/g,
+      replacement: '(not available - no hooks)',
+    },
+    {
+      pattern: /SessionStart\b/g,
+      replacement: '(not available - no hooks)',
+    },
+  ],
+};
+
 /**
  * Create docs folder reference replacements
  *
@@ -231,18 +402,63 @@ function createDocsReplacements(targetFolder) {
   };
 }
 
+/**
+ * Transform tool references in content based on IDE capabilities.
+ * Replaces Claude Code tool names and patterns with IDE-appropriate alternatives.
+ *
+ * For Claude Code (canonical format), returns content unchanged.
+ * For other IDEs, replaces tool references with alternatives based on capabilities:
+ * - Cursor: Converts AskUserQuestion to "numbered list prompt", Task stays as subagents
+ * - Windsurf: Converts to "megaplan" and workflow suggestions, removes Task references
+ * - Codex: Converts to skill invocations, text-only prompts, removes Plan mode
+ *
+ * @param {string} content - Content with Claude Code tool references
+ * @param {string} targetIde - Target IDE name: 'claude-code', 'cursor', 'windsurf', 'codex'
+ * @returns {string} Content with IDE-appropriate tool references
+ *
+ * @example
+ * const content = 'Use the AskUserQuestion tool to get user input';
+ * const cursor = transformToolReferences(content, 'cursor');
+ * // Returns: 'Use numbered list prompt to get user input'
+ *
+ * @example
+ * const content = 'Call the Task tool with subagent_type: "agileflow-test"';
+ * const windsurf = transformToolReferences(content, 'windsurf');
+ * // Returns: 'Suggest running the relevant /workflow with workflow: "/agileflow-test"'
+ */
+function transformToolReferences(content, targetIde) {
+  // Claude Code is the canonical format - return unchanged
+  if (targetIde === 'claude-code') {
+    return content;
+  }
+
+  if (!content || typeof content !== 'string') {
+    return content || '';
+  }
+
+  const replacements = TOOL_REFERENCE_REPLACEMENTS[targetIde];
+  if (!replacements) {
+    // Unknown IDE - return unchanged
+    return content;
+  }
+
+  // Apply all replacements in order
+  return replaceReferences(content, replacements);
+}
+
 /**
  * Transform content for a specific IDE target
  *
  * @param {string} content - Source content
- * @param {string} targetIde - Target IDE: 'codex', 'cursor', 'windsurf'
+ * @param {string} targetIde - Target IDE: 'codex', 'cursor', 'windsurf', 'claude-code'
  * @param {Object} [options] - Additional options
  * @param {string} [options.docsFolder] - Custom docs folder name
  * @param {Object} [options.additionalReplacements] - Extra replacements to apply
+ * @param {boolean} [options.transformTools] - Apply tool reference transformations (default: false for backward compatibility)
  * @returns {string} Transformed content
  */
 function transformForIde(content, targetIde, options = {}) {
-  const { docsFolder, additionalReplacements = {} } = options;
+  const { docsFolder, additionalReplacements = {}, transformTools = false } = options;
 
   // Start with IDE-specific replacements
   const replacements = { ...(IDE_REPLACEMENTS[targetIde] || {}) };
@@ -255,7 +471,14 @@ function transformForIde(content, targetIde, options = {}) {
   // Add any additional custom replacements
   Object.assign(replacements, additionalReplacements);
 
-  return replaceReferences(content, replacements);
+  let result = replaceReferences(content, replacements);
+
+  // Apply tool reference transformations if requested
+  if (transformTools) {
+    result = transformToolReferences(result, targetIde);
+  }
+
+  return result;
 }
 
 module.exports = {
@@ -266,6 +489,8 @@ module.exports = {
   getFrontmatter,
   escapeRegex,
   IDE_REPLACEMENTS,
+  TOOL_REFERENCE_REPLACEMENTS,
   createDocsReplacements,
+  transformToolReferences,
   transformForIde,
 };

package/tools/cli/lib/docs-setup.js

@@ -190,7 +190,7 @@ Project-level planning and tracking.
 - **milestones.md**: Release milestones
 - **risks.md**: Project risks and mitigation strategies
 - **ideation/**: Ideation reports from \`/agileflow:ideate:new\`
-- **logic-audits/**: Logic audit reports from \`/agileflow:logic:audit\`
+- **logic-audits/**: Logic audit reports from \`/agileflow:audit:logic\`
 `,
 
     [`${docsFolder}/09-agents/README.md`]: `# Agent Status Tracking

package/tools/cli/lib/ide-generator.js

@@ -0,0 +1,357 @@
+/**
+ * ide-generator.js - Build-time IDE-specific prompt/skill/agent generator
+ *
+ * Integrates IDE capability profiles with content transformer to produce
+ * IDE-native commands and agents during the install process.
+ *
+ * Main entry points:
+ * - generateForIde(content, targetIde, options) - Base transformation
+ * - generateCommandForIde(content, commandName, targetIde, options) - Command-specific
+ * - generateAgentForIde(content, agentName, targetIde, options) - Agent-specific
+ */
+
+const {
+  transformForIde,
+  transformToolReferences,
+  replaceReferences,
+  stripFrontmatter,
+  getFrontmatter,
+  convertFrontmatter,
+} = require('./content-transformer');
+
+// Lazy-load profile loader - only if profiles are needed
+let profileLoader = null;
+
+function getProfileLoader() {
+  if (!profileLoader) {
+    try {
+      profileLoader = require('../../../src/core/profiles/loader');
+    } catch (e) {
+      // Profiles not available - return null to indicate fallback mode
+      return null;
+    }
+  }
+  return profileLoader;
+}
+
+/**
+ * Get the IDE prefix style for commands
+ * Claude Code uses "/agileflow:", others use "/" or "$" as prefix
+ * @param {string} targetIde - Target IDE: 'claude-code', 'cursor', 'windsurf', 'codex'
+ * @returns {string} Command prefix pattern
+ * @private
+ */
+function getCommandPrefix(targetIde) {
+  const prefixes = {
+    'claude-code': '/agileflow:',
+    cursor: '/',
+    windsurf: '/',
+    codex: '$agileflow-',
+  };
+  return prefixes[targetIde] || '/agileflow:';
+}
+
+/**
+ * Convert /agileflow:style:commands to IDE-specific format
+ * - Claude Code: /agileflow:foo:bar → /agileflow:foo:bar (unchanged)
+ * - Cursor: /agileflow:foo:bar → /foo-bar
+ * - Windsurf: /agileflow:foo:bar → /agileflow-foo-bar
+ * - Codex: /agileflow:foo:bar → $agileflow-foo-bar
+ *
+ * @param {string} content - Content with command references
+ * @param {string} targetIde - Target IDE
+ * @returns {string} Content with converted command prefixes
+ * @private
+ */
+function convertCommandPrefixes(content, targetIde) {
+  if (targetIde === 'claude-code') {
+    return content; // No conversion needed
+  }
+
+  let result = content;
+
+  if (targetIde === 'cursor') {
+    // /agileflow:foo:bar → /foo-bar
+    result = result.replace(/\/agileflow:([a-zA-Z0-9:_-]+)/g, (_match, rest) => {
+      return '/' + rest.replace(/:/g, '-');
+    });
+  } else if (targetIde === 'windsurf') {
+    // /agileflow:foo:bar → /agileflow-foo-bar
+    result = result.replace(/\/agileflow:([a-zA-Z0-9:_-]+)/g, (_match, rest) => {
+      return '/agileflow-' + rest.replace(/:/g, '-');
+    });
+  } else if (targetIde === 'codex') {
+    // /agileflow:foo:bar → $agileflow-foo-bar
+    result = result.replace(/\/agileflow:([a-zA-Z0-9:_-]+)/g, (_match, rest) => {
+      return '$agileflow-' + rest.replace(/:/g, '-');
+    });
+  }
+
+  return result;
+}
+
+/**
+ * Main entry point for IDE-specific content generation
+ * Takes canonical Claude Code markdown content and transforms it for a target IDE
+ *
+ * @param {string} content - Source content (Claude Code format)
+ * @param {string} targetIde - Target IDE: 'claude-code', 'cursor', 'windsurf', 'codex'
+ * @param {Object} [options] - Generation options
+ * @param {string} [options.docsFolder] - Custom docs folder name
+ * @param {boolean} [options.transformTools] - Apply tool reference transformations (default: true)
+ * @param {boolean} [options.transformPrefixes] - Convert command prefixes (default: true)
+ * @param {Object} [options.additionalReplacements] - Extra IDE-specific replacements
+ * @returns {string} Transformed content for target IDE
+ *
+ * @example
+ * const content = await fs.readFile('command.md', 'utf8');
+ * const cursorVersion = generateForIde(content, 'cursor', { transformTools: true });
+ */
+function generateForIde(content, targetIde, options = {}) {
+  if (!content || typeof content !== 'string') {
+    return content || '';
+  }
+
+  // Claude Code is canonical format - return as-is
+  if (targetIde === 'claude-code') {
+    return content;
+  }
+
+  const {
+    docsFolder,
+    transformTools = true,
+    transformPrefixes = true,
+    additionalReplacements = {},
+  } = options;
+
+  // Step 1: Apply IDE-specific replacements and docs folder updates
+  let result = transformForIde(content, targetIde, {
+    docsFolder,
+    additionalReplacements,
+    transformTools: false, // Will apply separately
+  });
+
+  // Step 2: Apply tool reference transformations if requested
+  if (transformTools) {
+    result = transformToolReferences(result, targetIde);
+  }
+
+  // Step 3: Convert command prefixes if requested
+  if (transformPrefixes) {
+    result = convertCommandPrefixes(result, targetIde);
+  }
+
+  return result;
+}
+
+/**
+ * Generate IDE-specific command content with IDE-native wrapping
+ *
+ * For Codex, adds {{input}} placeholder at end for context injection.
+ * For other IDEs, uses base generateForIde() transformation.
+ *
+ * @param {string} content - Source command content (Claude Code format)
+ * @param {string} commandName - Command name for display
+ * @param {string} targetIde - Target IDE
+ * @param {Object} [options] - Generation options (same as generateForIde)
+ * @returns {string} IDE-native command content
+ *
+ * @example
+ * const cmd = await fs.readFile('commands/deploy.md', 'utf8');
+ * const codexPrompt = generateCommandForIde(cmd, 'deploy', 'codex');
+ */
+function generateCommandForIde(content, commandName, targetIde, options = {}) {
+  // Handle null/undefined content
+  if (content === null || content === undefined || typeof content !== 'string') {
+    return '';
+  }
+
+  // Start with base transformation
+  let result = generateForIde(content, targetIde, options);
+
+  // Codex-specific wrapping: Add {{input}} placeholder
+  if (targetIde === 'codex' && result !== '') {
+    // Strip frontmatter for Codex format
+    const bodyContent = stripFrontmatter(result);
+    const frontmatter = getFrontmatter(content);
+    const description = frontmatter.description || `AgileFlow ${commandName} command`;
+
+    const header = `# AgileFlow: ${commandName}
+
+> ${description}
+
+## Instructions
+
+`;
+
+    const footer = `
+
+## Context
+
+{{input}}
+`;
+
+    result = header + bodyContent + footer;
+  }
+
+  return result;
+}
+
+/**
+ * Generate IDE-specific agent/skill content
+ *
+ * Performs IDE-specific transformations including:
+ * - For Codex: Converts to SKILL.md format with skill-specific frontmatter
+ * - For Windsurf: Converts to agentskills.io format with skill-specific frontmatter
+ * - For Cursor: Adds agent-specific frontmatter for spawnable agents
+ * - For Claude Code: Returns unchanged (canonical format)
+ *
+ * @param {string} content - Source agent content (Claude Code format)
+ * @param {string} agentName - Agent name (e.g., 'database', 'security')
+ * @param {string} targetIde - Target IDE: 'claude-code', 'cursor', 'windsurf', 'codex'
+ * @param {Object} [options] - Generation options
+ * @param {string} [options.docsFolder] - Custom docs folder name
+ * @param {boolean} [options.transformTools] - Apply tool reference transformations (default: true)
+ * @returns {string} IDE-native agent/skill content
+ *
+ * @example
+ * const agent = await fs.readFile('agents/security.md', 'utf8');
+ * const windsurfSkill = generateAgentForIde(agent, 'security', 'windsurf');
+ */
+function generateAgentForIde(content, agentName, targetIde, options = {}) {
+  if (!content || typeof content !== 'string') {
+    return content || '';
+  }
+
+  // Claude Code is canonical format
+  if (targetIde === 'claude-code') {
+    return content;
+  }
+
+  const { docsFolder, transformTools = true } = options;
+
+  // Get base transformations
+  const baseContent = generateForIde(content, targetIde, {
+    docsFolder,
+    transformTools,
+    transformPrefixes: false, // Don't convert prefixes in agent bodies
+  });
+
+  // Extract frontmatter and body
+  const frontmatter = getFrontmatter(content);
+  const description = frontmatter.description || `AgileFlow ${agentName} agent`;
+
+  // Apply IDE-specific formatting
+  if (targetIde === 'codex') {
+    return formatAgentForCodex(baseContent, agentName, description);
+  } else if (targetIde === 'windsurf') {
+    return formatAgentForWindsurf(baseContent, agentName, description);
+  } else if (targetIde === 'cursor') {
+    return formatAgentForCursor(baseContent, agentName, description);
+  }
+
+  return baseContent;
+}
+
+/**
+ * Format agent content for Codex SKILL.md format
+ * @private
+ */
+function formatAgentForCodex(content, agentName, description) {
+  const yaml = require('../../../lib/yaml-utils').yaml;
+
+  const bodyContent = stripFrontmatter(content);
+
+  // Create SKILL.md with YAML frontmatter
+  const skillFrontmatter = yaml
+    .dump({
+      name: `agileflow-${agentName}`,
+      description: description,
+      version: '1.0.0',
+    })
+    .trim();
+
+  const codexHeader = `# AgileFlow: ${agentName.charAt(0).toUpperCase() + agentName.slice(1)} Agent
+
+> Invoke with \`$agileflow-${agentName}\` or via \`/skills\`
+
+`;
+
+  return `---
+${skillFrontmatter}
+---
+
+${codexHeader}${bodyContent}`;
+}
+
+/**
+ * Format agent content for Windsurf SKILL.md (agentskills.io spec)
+ * @private
+ */
+function formatAgentForWindsurf(content, agentName, description) {
+  const yaml = require('../../../lib/yaml-utils').yaml;
+
+  const bodyContent = stripFrontmatter(content);
+
+  // Create SKILL.md with YAML frontmatter (agentskills.io spec)
+  const skillFrontmatter = yaml
+    .dump({
+      name: `agileflow-${agentName}`,
+      description: description,
+    })
+    .trim();
+
+  const windsurfHeader = `# AgileFlow: ${agentName.charAt(0).toUpperCase() + agentName.slice(1)} Skill
+
+> Use this skill via \`@agileflow-${agentName}\` or /cascade
+
+`;
+
+  return `---
+${skillFrontmatter}
+---
+
+${windsurfHeader}${bodyContent}`;
+}
+
+/**
+ * Format agent content for Cursor spawnable agent
+ * Cursor agents use YAML frontmatter with name, description, and model fields
+ * @private
+ */
+function formatAgentForCursor(content, agentName, description) {
+  const yaml = require('../../../lib/yaml-utils').yaml;
+
+  // Extract frontmatter from source
+  const sourceFrontmatter = getFrontmatter(content);
+  const bodyContent = stripFrontmatter(content);
+
+  // Create agent frontmatter for Cursor
+  const agentFrontmatter = yaml
+    .dump({
+      name: `agileflow-${agentName}`,
+      description: description,
+      model: sourceFrontmatter.model || 'claude-3-5-sonnet',
+      readonly: false,
+    })
+    .trim();
+
+  return `---
+${agentFrontmatter}
+---
+
+${bodyContent}`;
+}
+
+module.exports = {
+  generateForIde,
+  generateCommandForIde,
+  generateAgentForIde,
+  getCommandPrefix,
+  // Export private functions for testing
+  _convertCommandPrefixes: convertCommandPrefixes,
+  _getProfileLoader: getProfileLoader,
+  _formatAgentForCodex: formatAgentForCodex,
+  _formatAgentForWindsurf: formatAgentForWindsurf,
+  _formatAgentForCursor: formatAgentForCursor,
+};

package/tools/cli/lib/ide-registry.js

@@ -98,13 +98,13 @@ const IDE_REGISTRY = {
   },
   codex: {
     name: 'codex',
-    displayName: 'OpenAI Codex CLI',
+    displayName: 'OpenAI Codex',
     configDir: '.codex',
     commandsSubdir: 'skills',
     agileflowFolder: 'agileflow',
     targetSubdir: 'skills', // Codex uses skills directory
     preferred: false,
-    description: "OpenAI's Codex CLI",
+    description: "OpenAI's Codex",
     handler: 'CodexSetup',
     labels: {
       commands: 'prompts',