agileflow 3.1.0 → 3.2.0

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

@@ -1,8 +1,11 @@
 /**
  * AgileFlow CLI - Cursor IDE Installer
  *
- * Installs AgileFlow commands for Cursor IDE.
- * Cursor uses plain Markdown files in .cursor/commands/
+ * Installs AgileFlow commands, agents, and hooks for Cursor IDE.
+ * Cursor uses:
+ * - Plain Markdown files in .cursor/commands/ for slash commands
+ * - Markdown files in .cursor/agents/ for subagents (with YAML frontmatter)
+ * - .cursor/hooks.json for lifecycle hooks
  */
 
 const path = require('node:path');
@@ -27,10 +30,162 @@ class CursorSetup extends BaseIdeSetup {
    * @param {Object} options - Setup options
    */
   async setup(projectDir, agileflowDir, options = {}) {
-    return this.setupStandard(projectDir, agileflowDir, {
+    // Use standard setup for commands and agents
+    const result = await this.setupStandard(projectDir, agileflowDir, {
       targetSubdir: this.commandsDir,
       agileflowFolder: 'AgileFlow',
     });
+
+    const { ideDir, agileflowTargetDir } = result;
+    const agentsSource = path.join(agileflowDir, 'agents');
+
+    // Cursor specific: Install agents as spawnable subagents (.cursor/agents/AgileFlow/)
+    // This allows Cursor's async subagent spawning feature
+    const spawnableAgentsDir = path.join(ideDir, 'agents', 'AgileFlow');
+
+    // Clean existing spawnable agents directory to prevent duplicates during update
+    if (await fs.pathExists(spawnableAgentsDir)) {
+      await fs.remove(spawnableAgentsDir);
+    }
+
+    const agentInstallResult = await this.installCommandsRecursive(
+      agentsSource,
+      spawnableAgentsDir,
+      agileflowDir,
+      false
+    );
+    console.log(chalk.dim(`    - Spawnable agents: .cursor/agents/AgileFlow/`));
+
+    // Cursor specific: Setup damage control hooks
+    await this.setupDamageControlHooks(projectDir, agileflowDir, ideDir, options);
+
+    return {
+      ...result,
+      agents: agentInstallResult.commands,
+    };
+  }
+
+  /**
+   * Setup damage control hooks for Cursor
+   * Maps Claude Code's PreToolUse hooks to Cursor's lifecycle events:
+   * - beforeShellExecution (for bash commands)
+   * - afterFileEdit (for file edits)
+   *
+   * @param {string} projectDir - Project directory
+   * @param {string} agileflowDir - AgileFlow installation directory
+   * @param {string} cursorDir - .cursor directory path
+   * @param {Object} options - Setup options
+   */
+  async setupDamageControlHooks(projectDir, agileflowDir, cursorDir, options = {}) {
+    if (options.skipDamageControl) {
+      return;
+    }
+
+    const hooksPath = path.join(cursorDir, 'hooks.json');
+    let hooks = [];
+
+    // Load existing hooks if they exist
+    if (fs.existsSync(hooksPath)) {
+      try {
+        const content = await fs.readFile(hooksPath, 'utf8');
+        hooks = JSON.parse(content);
+        if (!Array.isArray(hooks)) {
+          hooks = [];
+        }
+      } catch (e) {
+        hooks = [];
+      }
+    }
+
+    // Define damage control hooks for Cursor
+    // Cursor's hooks.json format: Array of {event, command, args, order}
+    const damageControlHooks = [
+      {
+        event: 'beforeShellExecution',
+        command: 'node',
+        args: ['$CURSOR_PROJECT_DIR/.cursor/hooks/damage-control/bash-tool-damage-control.js'],
+        order: 1,
+      },
+      {
+        event: 'afterFileEdit',
+        command: 'node',
+        args: ['$CURSOR_PROJECT_DIR/.cursor/hooks/damage-control/edit-tool-damage-control.js'],
+        order: 1,
+      },
+    ];
+
+    // 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`));
+    }
+
+    // Copy damage control scripts
+    await this.setupDamageControlScripts(agileflowDir, cursorDir);
+  }
+
+  /**
+   * Copy damage control scripts to .cursor/hooks/damage-control/
+   * @param {string} agileflowDir - AgileFlow installation directory
+   * @param {string} cursorDir - .cursor directory path
+   */
+  async setupDamageControlScripts(agileflowDir, cursorDir) {
+    const damageControlSource = path.join(agileflowDir, 'scripts', 'damage-control');
+    const damageControlTarget = path.join(cursorDir, 'hooks', 'damage-control');
+
+    if (!fs.existsSync(damageControlSource)) {
+      return;
+    }
+
+    await this.ensureDir(damageControlTarget);
+
+    // Copy hook scripts
+    const scripts = [
+      'bash-tool-damage-control.js',
+      'edit-tool-damage-control.js',
+      'write-tool-damage-control.js',
+    ];
+
+    for (const script of scripts) {
+      const src = path.join(damageControlSource, script);
+      const dest = path.join(damageControlTarget, script);
+      if (fs.existsSync(src)) {
+        await fs.copy(src, dest);
+      }
+    }
+
+    // Copy lib/damage-control-utils.js (required by hook scripts)
+    const libSource = path.join(agileflowDir, 'scripts', 'lib', 'damage-control-utils.js');
+    const libTarget = path.join(cursorDir, 'hooks', 'lib', 'damage-control-utils.js');
+    if (fs.existsSync(libSource)) {
+      await this.ensureDir(path.dirname(libTarget));
+      await fs.copy(libSource, libTarget);
+    }
+
+    // Copy patterns.yaml (preserve existing)
+    const patternsSource = path.join(damageControlSource, 'patterns.yaml');
+    const patternsTarget = path.join(damageControlTarget, 'patterns.yaml');
+    if (fs.existsSync(patternsSource) && !fs.existsSync(patternsTarget)) {
+      await fs.copy(patternsSource, patternsTarget);
+    }
   }
 
   /**
@@ -45,11 +200,17 @@ class CursorSetup extends BaseIdeSetup {
       console.log(chalk.dim(`    Removed old AgileFlow rules from ${this.displayName}`));
     }
 
-    // Remove .cursor/commands/agileflow (for re-installation)
+    // Remove .cursor/commands/AgileFlow (for re-installation)
     const commandsPath = path.join(projectDir, this.configDir, this.commandsDir, 'AgileFlow');
     if (await this.exists(commandsPath)) {
       await fs.remove(commandsPath);
     }
+
+    // Remove .cursor/agents/AgileFlow (for re-installation)
+    const agentsPath = path.join(projectDir, this.configDir, 'agents', 'AgileFlow');
+    if (await this.exists(agentsPath)) {
+      await fs.remove(agentsPath);
+    }
   }
 }
 

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}`));
+    }
   }
 }