agileflow 3.1.0 → 3.2.1

package/tools/cli/installers/ide/windsurf.js

@@ -1,14 +1,26 @@
 /**
  * AgileFlow CLI - Windsurf IDE Installer
  *
- * Installs AgileFlow workflows for Windsurf IDE.
- * Windsurf uses markdown files in .windsurf/workflows/
+ * Installs AgileFlow for Windsurf IDE:
+ * - Commands as workflows to .windsurf/workflows/agileflow/
+ * - Agents as skills to .windsurf/skills/agileflow-<NAME>/SKILL.md
+ * - Damage control hooks to .windsurf/hooks.json
+ *
+ * Windsurf supports 11 lifecycle events and 12,000 character limit per workflow.
+ * Skills follow agentskills.io specification with YAML frontmatter.
  */
 
 const path = require('node:path');
 const fs = require('fs-extra');
 const chalk = require('chalk');
+const { yaml } = require('../../../../lib/yaml-utils');
 const { BaseIdeSetup } = require('./_base-ide');
+const {
+  getFrontmatter,
+  stripFrontmatter,
+  replaceReferences,
+  IDE_REPLACEMENTS,
+} = require('../../lib/content-transformer');
 
 /**
  * Windsurf IDE setup handler
@@ -20,6 +32,187 @@ class WindsurfSetup extends BaseIdeSetup {
     this.workflowsDir = 'workflows';
   }
 
+  /**
+   * Convert an AgileFlow agent markdown file to Windsurf SKILL.md format
+   * Windsurf skills follow the agentskills.io specification with YAML frontmatter
+   *
+   * @param {string} content - Original agent markdown content
+   * @param {string} agentName - Agent name (e.g., 'database')
+   * @returns {string} Windsurf SKILL.md content
+   */
+  convertAgentToSkill(content, agentName) {
+    // Extract frontmatter using content-transformer
+    const frontmatter = getFrontmatter(content);
+    const description = frontmatter.description || `AgileFlow ${agentName} agent`;
+
+    // Create SKILL.md with YAML frontmatter (agentskills.io spec)
+    const skillFrontmatter = yaml
+      .dump({
+        name: `agileflow-${agentName}`,
+        description: description,
+      })
+      .trim();
+
+    // Remove original frontmatter from content using content-transformer
+    let bodyContent = stripFrontmatter(content);
+
+    // Add Windsurf-specific header
+    const windsurfHeader = `# AgileFlow: ${agentName.charAt(0).toUpperCase() + agentName.slice(1)} Skill
+
+> Use this skill via \`@agileflow-${agentName}\` or /cascade
+
+`;
+
+    // Replace Claude-specific references using content-transformer
+    bodyContent = replaceReferences(bodyContent, IDE_REPLACEMENTS.windsurf);
+
+    // Add Windsurf-specific replacements
+    bodyContent = replaceReferences(bodyContent, {
+      'Task tool': 'workflow chaining',
+      AskUserQuestion: 'numbered list prompt',
+      '.claude/agents/agileflow': '.windsurf/skills/agileflow',
+    });
+
+    // Replace /agileflow: prefix for Windsurf workflow chaining
+    // e.g., /agileflow:story:list → /agileflow-story-list
+    bodyContent = bodyContent.replace(/\/agileflow:([a-zA-Z0-9:_-]+)/g, (_match, rest) => {
+      return '/agileflow-' + rest.replace(/:/g, '-');
+    });
+
+    // Warn if content exceeds Windsurf's 12,000 character limit
+    const totalLength = skillFrontmatter.length + windsurfHeader.length + bodyContent.length;
+    if (totalLength > 12000) {
+      console.warn(
+        chalk.yellow(
+          `    ⚠ Skill '${agentName}' exceeds 12,000 character limit (${totalLength} chars). Consider splitting.`
+        )
+      );
+    }
+
+    return `---
+${skillFrontmatter}
+---
+
+${windsurfHeader}${bodyContent}`;
+  }
+
+  /**
+   * Install AgileFlow agents as Windsurf skills
+   * Skills are installed to .windsurf/skills/agileflow-{name}/SKILL.md
+   *
+   * @param {string} projectDir - Project directory
+   * @param {string} agileflowDir - AgileFlow installation directory
+   * @returns {Promise<number>} Number of skills installed
+   */
+  async installSkills(projectDir, agileflowDir) {
+    const agentsSource = path.join(agileflowDir, 'agents');
+    const skillsTarget = path.join(projectDir, this.configDir, 'skills');
+
+    if (!(await this.exists(agentsSource))) {
+      return 0;
+    }
+
+    let skillCount = 0;
+    const agents = await this.scanDirectory(agentsSource, '.md');
+
+    for (const agent of agents) {
+      const content = await this.readFile(agent.path);
+      const skillContent = this.convertAgentToSkill(content, agent.name);
+
+      // Create skill directory: .windsurf/skills/agileflow-{name}/
+      const skillDir = path.join(skillsTarget, `agileflow-${agent.name}`);
+      await this.ensureDir(skillDir);
+
+      // Write SKILL.md
+      await this.writeFile(path.join(skillDir, 'SKILL.md'), skillContent);
+      skillCount++;
+    }
+
+    return skillCount;
+  }
+
+  /**
+   * Setup damage control hooks for Windsurf
+   * Maps Claude Code's PreToolUse hooks to Windsurf's lifecycle events:
+   * - pre_run_command (for bash commands)
+   * - post_write_code (for file edits)
+   * - pre_mcp_tool_use (for MCP tools)
+   *
+   * @param {string} projectDir - Project directory
+   * @param {string} agileflowDir - AgileFlow installation directory
+   * @param {string} windsurfDir - .windsurf directory path
+   * @param {Object} options - Setup options
+   */
+  async setupDamageControlHooks(projectDir, agileflowDir, windsurfDir, options = {}) {
+    if (options.skipDamageControl) {
+      return;
+    }
+
+    const hooksPath = path.join(windsurfDir, 'hooks.json');
+    let hooks = [];
+
+    // Load existing hooks if they exist
+    if (fs.existsSync(hooksPath)) {
+      try {
+        const content = await fs.readFile(hooksPath, 'utf8');
+        const parsed = JSON.parse(content);
+        if (!Array.isArray(parsed)) {
+          console.warn(
+            '[AgileFlow] hooks.json exists but is not an array, preserving existing file'
+          );
+          return;
+        }
+        hooks = parsed;
+      } catch (e) {
+        console.warn(
+          `[AgileFlow] hooks.json exists but is malformed (${e.message}), preserving existing file`
+        );
+        return;
+      }
+    }
+
+    // Define damage control hooks for Windsurf
+    // Windsurf's hooks.json format differs from Cursor - it uses event, command, args
+    const damageControlHooks = [
+      {
+        event: 'pre_run_command',
+        command: 'node',
+        args: ['.agileflow/scripts/damage-control/damage-control-bash.js'],
+        description: 'AgileFlow damage control for shell commands',
+      },
+      {
+        event: 'post_write_code',
+        command: 'node',
+        args: ['.agileflow/scripts/damage-control/damage-control-edit.js'],
+        description: 'AgileFlow damage control for file edits',
+      },
+    ];
+
+    // Check if damage control hooks already exist and merge
+    let hasUpdates = false;
+    for (const newHook of damageControlHooks) {
+      const existingIdx = hooks.findIndex(
+        h =>
+          h.event === newHook.event &&
+          h.command === newHook.command &&
+          (h.args?.join(' ') === newHook.args?.join(' ') ||
+            (h.args && h.args.some(arg => arg.includes('damage-control'))))
+      );
+
+      if (existingIdx === -1) {
+        hooks.push(newHook);
+        hasUpdates = true;
+      }
+    }
+
+    // Only write if we have updates or if file didn't exist
+    if (hasUpdates || !fs.existsSync(hooksPath)) {
+      await fs.ensureDir(path.dirname(hooksPath));
+      await fs.writeFile(hooksPath, JSON.stringify(hooks, null, 2));
+      console.log(chalk.dim(`    - Damage control: hooks enabled`));
+    }
+  }
+
   /**
    * Setup Windsurf IDE configuration
    * @param {string} projectDir - Project directory
@@ -27,12 +220,37 @@ class WindsurfSetup extends BaseIdeSetup {
    * @param {Object} options - Setup options
    */
   async setup(projectDir, agileflowDir, options = {}) {
-    return this.setupStandard(projectDir, agileflowDir, {
+    console.log(chalk.hex('#e8683a')(`  Setting up ${this.displayName}...`));
+
+    // Note: cleanup is handled inside setupStandard(), no need to call explicitly
+
+    // 1. Install workflows using standard setup
+    const workflowsResult = await this.setupStandard(projectDir, agileflowDir, {
       targetSubdir: this.workflowsDir,
       agileflowFolder: 'agileflow',
       commandLabel: 'workflows',
       agentLabel: 'agent workflows',
     });
+
+    // 2. Install agents as skills
+    const skillCount = await this.installSkills(projectDir, agileflowDir);
+    if (skillCount > 0) {
+      console.log(chalk.dim(`    - ${skillCount} skills installed to .windsurf/skills/`));
+    }
+
+    // 3. Setup damage control hooks
+    const windsurfDir = path.join(projectDir, this.configDir);
+    await this.setupDamageControlHooks(projectDir, agileflowDir, windsurfDir, options);
+
+    console.log(chalk.green(`  ✓ ${this.displayName} configured:`));
+    console.log(chalk.dim(`    - Workflows: .windsurf/workflows/agileflow/`));
+    console.log(chalk.dim(`    - Skills: .windsurf/skills/agileflow-*/`));
+    console.log(chalk.dim(`    - Hooks: .windsurf/hooks.json`));
+
+    return {
+      ...workflowsResult,
+      skills: skillCount,
+    };
   }
 
   /**
@@ -40,11 +258,24 @@ class WindsurfSetup extends BaseIdeSetup {
    * @param {string} projectDir - Project directory
    */
   async cleanup(projectDir) {
-    const agileflowPath = path.join(projectDir, this.configDir, this.workflowsDir, 'agileflow');
-    if (await this.exists(agileflowPath)) {
-      await fs.remove(agileflowPath);
+    // Remove old workflows directory
+    const workflowsPath = path.join(projectDir, this.configDir, this.workflowsDir, 'agileflow');
+    if (await this.exists(workflowsPath)) {
+      await fs.remove(workflowsPath);
       console.log(chalk.dim(`    Removed old AgileFlow workflows from ${this.displayName}`));
     }
+
+    // Remove old skills directories
+    const skillsDir = path.join(projectDir, this.configDir, 'skills');
+    if (await this.exists(skillsDir)) {
+      const entries = await fs.readdir(skillsDir);
+      for (const entry of entries) {
+        if (entry.startsWith('agileflow-')) {
+          await fs.remove(path.join(skillsDir, entry));
+        }
+      }
+      console.log(chalk.dim(`    Removed old AgileFlow skills from ${this.displayName}`));
+    }
   }
 }
 

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