agileflow 2.55.0 → 2.56.0

package/README.md

@@ -4,9 +4,8 @@
 
 [![npm version](https://img.shields.io/npm/v/agileflow?color=brightgreen)](https://www.npmjs.com/package/agileflow)
 [![Commands](https://img.shields.io/badge/commands-41-blue)](docs/04-architecture/commands.md)
-[![Subagents](https://img.shields.io/badge/subagents-26-orange)](docs/04-architecture/subagents.md)
+[![Agents/Experts](https://img.shields.io/badge/agents%2Fexperts-26-orange)](docs/04-architecture/subagents.md)
 [![Skills](https://img.shields.io/badge/skills-23-purple)](docs/04-architecture/skills.md)
-[![Experts](https://img.shields.io/badge/experts-26-green)](docs/04-architecture/agent-expert-system.md)
 
 **AI-driven agile development for Claude Code, Cursor, Windsurf, OpenAI Codex CLI, and more.** Combining Scrum, Kanban, ADRs, and docs-as-code principles into one framework-agnostic system.
 
@@ -68,9 +67,8 @@ AgileFlow combines three proven methodologies:
 | Component | Count | Description |
 |-----------|-------|-------------|
 | [Commands](docs/04-architecture/commands.md) | 41 | Slash commands for agile workflows |
-| [Subagents](docs/04-architecture/subagents.md) | 26 | Specialized agents for focused work |
+| [Agents/Experts](docs/04-architecture/subagents.md) | 26 | Specialized agents with self-improving knowledge bases |
 | [Skills](docs/04-architecture/skills.md) | 23 | Auto-activated context helpers |
-| [Experts](docs/04-architecture/agent-expert-system.md) | 26 | Self-improving knowledge bases |
 
 ---
 
@@ -80,7 +78,7 @@ Full documentation lives in [`docs/04-architecture/`](docs/04-architecture/):
 
 ### Reference
 - [Commands](docs/04-architecture/commands.md) - All 41 slash commands
-- [Subagents](docs/04-architecture/subagents.md) - All 26 specialized agents
+- [Agents/Experts](docs/04-architecture/subagents.md) - 26 specialized agents with self-improving knowledge
 - [Skills](docs/04-architecture/skills.md) - 23 auto-loaded skills
 
 ### Architecture

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agileflow",
-  "version": "2.55.0",
+  "version": "2.56.0",
   "description": "AI-driven agile development system for Claude Code, Cursor, Windsurf, and more",
   "keywords": [
     "agile",

package/scripts/generators/agent-registry.js

@@ -5,58 +5,25 @@
  *
  * Scans agents/ directory and extracts metadata from frontmatter.
  * Returns structured agent registry for use in generators.
+ *
+ * Set DEBUG_REGISTRY=1 for verbose logging of skipped files.
  */
 
 const fs = require('fs');
 const path = require('path');
+const { extractFrontmatter, normalizeTools } = require('../lib/frontmatter-parser');
+
+// Debug mode: set DEBUG_REGISTRY=1 to see why files are skipped
+const DEBUG = process.env.DEBUG_REGISTRY === '1';
 
 /**
- * Extract YAML frontmatter from markdown file
- * Handles multi-line values like tools arrays
- * @param {string} filePath - Path to markdown file
- * @returns {object} Frontmatter object
+ * Log debug messages when DEBUG_REGISTRY=1
+ * @param {string} message - Message to log
  */
-function extractFrontmatter(filePath) {
-  const content = fs.readFileSync(filePath, 'utf-8');
-  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
-
-  if (!frontmatterMatch) {
-    return {};
-  }
-
-  const frontmatter = {};
-  const lines = frontmatterMatch[1].split('\n');
-  let currentKey = null;
-  let currentArray = null;
-
-  for (const line of lines) {
-    // Handle array items (lines starting with -)
-    if (line.trim().startsWith('-')) {
-      if (currentArray) {
-        currentArray.push(line.trim().substring(1).trim());
-      }
-      continue;
-    }
-
-    // Handle key-value pairs
-    const match = line.match(/^(\w+):\s*(.*)$/);
-    if (match) {
-      const [, key, value] = match;
-      currentKey = key;
-
-      // If value is empty, it's likely an array
-      if (!value) {
-        currentArray = [];
-        frontmatter[key] = currentArray;
-      } else {
-        // Remove quotes if present
-        frontmatter[key] = value.replace(/^["']|["']$/g, '');
-        currentArray = null;
-      }
-    }
+function debugLog(message) {
+  if (DEBUG) {
+    console.error(`[agent-registry] ${message}`);
   }
-
-  return frontmatter;
 }
 
 /**
@@ -93,25 +60,40 @@ function categorizeAgent(name, description) {
  */
 function scanAgents(agentsDir) {
   const agents = [];
-  const files = fs.readdirSync(agentsDir);
+  const skipped = [];
+
+  let files;
+  try {
+    files = fs.readdirSync(agentsDir);
+  } catch (err) {
+    debugLog(`Failed to read directory: ${err.message}`);
+    return agents;
+  }
+
+  debugLog(`Scanning ${files.length} files in ${agentsDir}`);
 
   for (const file of files) {
-    if (!file.endsWith('.md')) continue;
+    if (!file.endsWith('.md')) {
+      debugLog(`Skipping non-md file: ${file}`);
+      continue;
+    }
 
     const filePath = path.join(agentsDir, file);
     const frontmatter = extractFrontmatter(filePath);
     const name = file.replace('.md', '');
 
-    // Parse tools array if it exists
-    let tools = [];
-    if (frontmatter.tools) {
-      if (Array.isArray(frontmatter.tools)) {
-        tools = frontmatter.tools;
-      } else if (typeof frontmatter.tools === 'string') {
-        tools = frontmatter.tools.split(',').map(t => t.trim());
-      }
+    // Check if frontmatter was extracted successfully
+    if (Object.keys(frontmatter).length === 0) {
+      skipped.push({ file, reason: 'no frontmatter or parse error' });
+      debugLog(`Skipping ${file}: no frontmatter found`);
+      continue;
     }
 
+    // Normalize tools field (handles array or comma-separated string)
+    const tools = normalizeTools(frontmatter.tools);
+
+    debugLog(`Loaded ${file}: name="${frontmatter.name || name}", tools=${tools.length}`);
+
     agents.push({
       name,
       file,
@@ -133,6 +115,12 @@ function scanAgents(agentsDir) {
     return a.name.localeCompare(b.name);
   });
 
+  if (skipped.length > 0) {
+    debugLog(`Skipped ${skipped.length} files: ${skipped.map(s => s.file).join(', ')}`);
+  }
+
+  debugLog(`Found ${agents.length} agents`);
+
   return agents;
 }
 
@@ -159,7 +147,7 @@ function main() {
 }
 
 // Export for use in other scripts
-module.exports = { scanAgents, extractFrontmatter, categorizeAgent };
+module.exports = { scanAgents, categorizeAgent };
 
 // Run if called directly
 if (require.main === module) {

package/scripts/generators/command-registry.js

@@ -5,37 +5,25 @@
  *
  * Scans commands/ directory and extracts metadata from frontmatter.
  * Returns structured command registry for use in generators.
+ *
+ * Set DEBUG_REGISTRY=1 for verbose logging of skipped files.
  */
 
 const fs = require('fs');
 const path = require('path');
+const { extractFrontmatter } = require('../lib/frontmatter-parser');
+
+// Debug mode: set DEBUG_REGISTRY=1 to see why files are skipped
+const DEBUG = process.env.DEBUG_REGISTRY === '1';
 
 /**
- * Extract frontmatter from markdown file
- * @param {string} filePath - Path to markdown file
- * @returns {object} Frontmatter object
+ * Log debug messages when DEBUG_REGISTRY=1
+ * @param {string} message - Message to log
  */
-function extractFrontmatter(filePath) {
-  const content = fs.readFileSync(filePath, 'utf-8');
-  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
-
-  if (!frontmatterMatch) {
-    return {};
+function debugLog(message) {
+  if (DEBUG) {
+    console.error(`[command-registry] ${message}`);
   }
-
-  const frontmatter = {};
-  const lines = frontmatterMatch[1].split('\n');
-
-  for (const line of lines) {
-    const match = line.match(/^(\w+):\s*(.+)$/);
-    if (match) {
-      const [, key, value] = match;
-      // Remove quotes if present
-      frontmatter[key] = value.replace(/^["']|["']$/g, '');
-    }
-  }
-
-  return frontmatter;
 }
 
 /**
@@ -74,15 +62,37 @@ function categorizeCommand(name, description) {
  */
 function scanCommands(commandsDir) {
   const commands = [];
-  const files = fs.readdirSync(commandsDir);
+  const skipped = [];
+
+  let files;
+  try {
+    files = fs.readdirSync(commandsDir);
+  } catch (err) {
+    debugLog(`Failed to read directory: ${err.message}`);
+    return commands;
+  }
+
+  debugLog(`Scanning ${files.length} files in ${commandsDir}`);
 
   for (const file of files) {
-    if (!file.endsWith('.md')) continue;
+    if (!file.endsWith('.md')) {
+      debugLog(`Skipping non-md file: ${file}`);
+      continue;
+    }
 
     const filePath = path.join(commandsDir, file);
     const frontmatter = extractFrontmatter(filePath);
     const name = file.replace('.md', '');
 
+    // Check if frontmatter was extracted successfully
+    if (Object.keys(frontmatter).length === 0) {
+      skipped.push({ file, reason: 'no frontmatter or parse error' });
+      debugLog(`Skipping ${file}: no frontmatter found`);
+      continue;
+    }
+
+    debugLog(`Loaded ${file}: description="${frontmatter.description || '(none)'}"`);
+
     commands.push({
       name,
       file,
@@ -101,6 +111,12 @@ function scanCommands(commandsDir) {
     return a.name.localeCompare(b.name);
   });
 
+  if (skipped.length > 0) {
+    debugLog(`Skipped ${skipped.length} files: ${skipped.map(s => s.file).join(', ')}`);
+  }
+
+  debugLog(`Found ${commands.length} commands`);
+
   return commands;
 }
 
@@ -127,7 +143,7 @@ function main() {
 }
 
 // Export for use in other scripts
-module.exports = { scanCommands, extractFrontmatter, categorizeCommand };
+module.exports = { scanCommands, categorizeCommand };
 
 // Run if called directly
 if (require.main === module) {

package/scripts/generators/skill-registry.js

@@ -5,37 +5,25 @@
  *
  * Scans skills/ directory and extracts metadata from SKILL.md frontmatter.
  * Returns structured skill registry for use in generators.
+ *
+ * Set DEBUG_REGISTRY=1 for verbose logging of skipped files.
  */
 
 const fs = require('fs');
 const path = require('path');
+const { extractFrontmatter } = require('../lib/frontmatter-parser');
+
+// Debug mode: set DEBUG_REGISTRY=1 to see why files are skipped
+const DEBUG = process.env.DEBUG_REGISTRY === '1';
 
 /**
- * Extract YAML frontmatter from markdown file
- * @param {string} filePath - Path to markdown file
- * @returns {object} Frontmatter object
+ * Log debug messages when DEBUG_REGISTRY=1
+ * @param {string} message - Message to log
  */
-function extractFrontmatter(filePath) {
-  const content = fs.readFileSync(filePath, 'utf-8');
-  const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
-
-  if (!frontmatterMatch) {
-    return {};
-  }
-
-  const frontmatter = {};
-  const lines = frontmatterMatch[1].split('\n');
-
-  for (const line of lines) {
-    const match = line.match(/^(\w+):\s*(.+)$/);
-    if (match) {
-      const [, key, value] = match;
-      // Remove quotes if present
-      frontmatter[key] = value.replace(/^["']|["']$/g, '');
-    }
+function debugLog(message) {
+  if (DEBUG) {
+    console.error(`[skill-registry] ${message}`);
   }
-
-  return frontmatter;
 }
 
 /**
@@ -73,25 +61,58 @@ function categorizeSkill(name, description) {
  */
 function scanSkills(skillsDir) {
   const skills = [];
+  const skipped = [];
+
+  let skillDirs;
+  try {
+    skillDirs = fs.readdirSync(skillsDir);
+  } catch (err) {
+    debugLog(`Failed to read directory: ${err.message}`);
+    return skills;
+  }
 
-  // Each skill is in its own directory with a SKILL.md file
-  const skillDirs = fs.readdirSync(skillsDir);
+  debugLog(`Scanning ${skillDirs.length} entries in ${skillsDir}`);
 
   for (const skillDir of skillDirs) {
     const skillPath = path.join(skillsDir, skillDir);
 
     // Skip if not a directory
-    if (!fs.statSync(skillPath).isDirectory()) continue;
+    let stat;
+    try {
+      stat = fs.statSync(skillPath);
+    } catch (err) {
+      debugLog(`Failed to stat ${skillDir}: ${err.message}`);
+      continue;
+    }
+
+    if (!stat.isDirectory()) {
+      debugLog(`Skipping non-directory: ${skillDir}`);
+      continue;
+    }
 
     const skillFile = path.join(skillPath, 'SKILL.md');
 
     // Skip if SKILL.md doesn't exist
-    if (!fs.existsSync(skillFile)) continue;
+    if (!fs.existsSync(skillFile)) {
+      skipped.push({ dir: skillDir, reason: 'no SKILL.md file' });
+      debugLog(`Skipping ${skillDir}: no SKILL.md found`);
+      continue;
+    }
 
     const frontmatter = extractFrontmatter(skillFile);
+
+    // Check if frontmatter was extracted successfully
+    if (Object.keys(frontmatter).length === 0) {
+      skipped.push({ dir: skillDir, reason: 'no frontmatter or parse error' });
+      debugLog(`Skipping ${skillDir}: no frontmatter in SKILL.md`);
+      continue;
+    }
+
     const name = frontmatter.name || skillDir;
     const description = frontmatter.description || '';
 
+    debugLog(`Loaded ${skillDir}: name="${name}"`);
+
     skills.push({
       name,
       directory: skillDir,
@@ -110,6 +131,12 @@ function scanSkills(skillsDir) {
     return a.name.localeCompare(b.name);
   });
 
+  if (skipped.length > 0) {
+    debugLog(`Skipped ${skipped.length} directories: ${skipped.map(s => s.dir).join(', ')}`);
+  }
+
+  debugLog(`Found ${skills.length} skills`);
+
   return skills;
 }
 
@@ -136,7 +163,7 @@ function main() {
 }
 
 // Export for use in other scripts
-module.exports = { scanSkills, extractFrontmatter, categorizeSkill };
+module.exports = { scanSkills, categorizeSkill };
 
 // Run if called directly
 if (require.main === module) {

package/scripts/lib/frontmatter-parser.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+
+/**
+ * Frontmatter Parser - Shared YAML frontmatter extraction
+ *
+ * Consolidates frontmatter parsing logic used across:
+ * - command-registry.js
+ * - agent-registry.js
+ * - skill-registry.js
+ * - content-injector.js
+ */
+
+const fs = require('fs');
+const yaml = require('js-yaml');
+
+/**
+ * Parse YAML frontmatter from markdown content
+ * @param {string} content - Markdown content with frontmatter
+ * @returns {object} Parsed frontmatter object, or empty object if none found
+ */
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+
+  if (!match) {
+    return {};
+  }
+
+  try {
+    const parsed = yaml.load(match[1]);
+    // Return empty object if yaml.load returns null/undefined
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  } catch (err) {
+    // Return empty object on parse error (invalid YAML)
+    return {};
+  }
+}
+
+/**
+ * Extract frontmatter from a markdown file
+ * @param {string} filePath - Path to markdown file
+ * @returns {object} Parsed frontmatter object, or empty object if none/error
+ */
+function extractFrontmatter(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return parseFrontmatter(content);
+  } catch (err) {
+    // Return empty object on file read error
+    return {};
+  }
+}
+
+/**
+ * Extract markdown body (content after frontmatter)
+ * @param {string} content - Full markdown content
+ * @returns {string} Content after frontmatter, or original if no frontmatter
+ */
+function extractBody(content) {
+  const match = content.match(/^---\n[\s\S]*?\n---\n?([\s\S]*)/);
+  return match ? match[1].trim() : content.trim();
+}
+
+/**
+ * Normalize tools field - handles array or comma-separated string
+ * @param {string|Array} tools - Tools field from frontmatter
+ * @returns {Array} Array of tool names
+ */
+function normalizeTools(tools) {
+  if (!tools) return [];
+  if (Array.isArray(tools)) return tools;
+  if (typeof tools === 'string') {
+    return tools.split(',').map(t => t.trim()).filter(Boolean);
+  }
+  return [];
+}
+
+module.exports = {
+  parseFrontmatter,
+  extractFrontmatter,
+  extractBody,
+  normalizeTools,
+};

package/tools/cli/installers/ide/_base-ide.js

@@ -179,6 +179,61 @@ class BaseIdeSetup {
 
     return results;
   }
+
+  /**
+   * Recursively install markdown files from source to target directory
+   * Handles content injection and docs reference replacement.
+   * @param {string} sourceDir - Source directory path
+   * @param {string} targetDir - Target directory path
+   * @param {string} agileflowDir - AgileFlow installation directory (for dynamic content)
+   * @param {boolean} injectDynamic - Whether to inject dynamic content (only for top-level commands)
+   * @returns {Promise<{commands: number, subdirs: number}>} Count of installed items
+   */
+  async installCommandsRecursive(sourceDir, targetDir, agileflowDir, injectDynamic = false) {
+    let commandCount = 0;
+    let subdirCount = 0;
+
+    if (!(await this.exists(sourceDir))) {
+      return { commands: 0, subdirs: 0 };
+    }
+
+    await this.ensureDir(targetDir);
+
+    const entries = await fs.readdir(sourceDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const sourcePath = path.join(sourceDir, entry.name);
+      const targetPath = path.join(targetDir, entry.name);
+
+      if (entry.isFile() && entry.name.endsWith('.md')) {
+        // Read and process .md file
+        let content = await this.readFile(sourcePath);
+
+        // Inject dynamic content if enabled (for top-level commands)
+        if (injectDynamic) {
+          content = this.injectDynamicContent(content, agileflowDir);
+        }
+
+        // Replace docs/ references with custom folder name
+        content = this.replaceDocsReferences(content);
+
+        await this.writeFile(targetPath, content);
+        commandCount++;
+      } else if (entry.isDirectory()) {
+        // Recursively process subdirectory
+        const subResult = await this.installCommandsRecursive(
+          sourcePath,
+          targetPath,
+          agileflowDir,
+          false // Don't inject dynamic content in subdirectories
+        );
+        commandCount += subResult.commands;
+        subdirCount += 1 + subResult.subdirs;
+      }
+    }
+
+    return { commands: commandCount, subdirs: subdirCount };
+  }
 }
 
 module.exports = { BaseIdeSetup };

package/tools/cli/installers/ide/claude-code.js

@@ -19,60 +19,6 @@ class ClaudeCodeSetup extends BaseIdeSetup {
     this.commandsDir = 'commands';
   }
 
-  /**
-   * Recursively install commands from a source directory
-   * @param {string} sourceDir - Source directory path
-   * @param {string} targetDir - Target directory path
-   * @param {string} agileflowDir - AgileFlow installation directory (for dynamic content)
-   * @param {boolean} injectDynamic - Whether to inject dynamic content (only for top-level commands)
-   * @returns {Promise<{commands: number, subdirs: number}>} Count of installed items
-   */
-  async installCommandsRecursive(sourceDir, targetDir, agileflowDir, injectDynamic = false) {
-    let commandCount = 0;
-    let subdirCount = 0;
-
-    if (!(await this.exists(sourceDir))) {
-      return { commands: 0, subdirs: 0 };
-    }
-
-    await this.ensureDir(targetDir);
-
-    const entries = await fs.readdir(sourceDir, { withFileTypes: true });
-
-    for (const entry of entries) {
-      const sourcePath = path.join(sourceDir, entry.name);
-      const targetPath = path.join(targetDir, entry.name);
-
-      if (entry.isFile() && entry.name.endsWith('.md')) {
-        // Read and process .md file
-        let content = await this.readFile(sourcePath);
-
-        // Inject dynamic content if enabled (for top-level commands)
-        if (injectDynamic) {
-          content = this.injectDynamicContent(content, agileflowDir);
-        }
-
-        // Replace docs/ references with custom folder name
-        content = this.replaceDocsReferences(content);
-
-        await this.writeFile(targetPath, content);
-        commandCount++;
-      } else if (entry.isDirectory()) {
-        // Recursively process subdirectory
-        const subResult = await this.installCommandsRecursive(
-          sourcePath,
-          targetPath,
-          agileflowDir,
-          false // Don't inject dynamic content in subdirectories
-        );
-        commandCount += subResult.commands;
-        subdirCount += 1 + subResult.subdirs;
-      }
-    }
-
-    return { commands: commandCount, subdirs: subdirCount };
-  }
-
   /**
    * Setup Claude Code IDE configuration
    * @param {string} projectDir - Project directory

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

@@ -32,69 +32,39 @@ class CursorSetup extends BaseIdeSetup {
     // Clean up old installation first
     await this.cleanup(projectDir);
 
-    // Create .cursor/commands/agileflow directory
+    // Create .cursor/commands/AgileFlow directory
     const cursorDir = path.join(projectDir, this.configDir);
     const commandsDir = path.join(cursorDir, this.commandsDir);
     const agileflowCommandsDir = path.join(commandsDir, 'AgileFlow');
 
-    await this.ensureDir(agileflowCommandsDir);
-
-    // Get commands from AgileFlow installation
+    // Install commands using shared recursive method
     const commandsSource = path.join(agileflowDir, 'commands');
-    let commandCount = 0;
-
-    if (await this.exists(commandsSource)) {
-      const commands = await this.scanDirectory(commandsSource, '.md');
-
-      for (const command of commands) {
-        // Read the original command content
-        let content = await this.readFile(command.path);
-
-        // Inject dynamic content (agent lists, command lists)
-        content = this.injectDynamicContent(content, agileflowDir);
-
-        // Replace docs/ references with custom folder name
-        content = this.replaceDocsReferences(content);
-
-        const targetPath = path.join(agileflowCommandsDir, `${command.name}.md`);
-        await this.writeFile(targetPath, content);
-        commandCount++;
-      }
-    }
-
-    // Create agents subdirectory
-    const agileflowAgentsDir = path.join(agileflowCommandsDir, 'agents');
-    await this.ensureDir(agileflowAgentsDir);
-
-    // Get agents from AgileFlow installation
+    const commandResult = await this.installCommandsRecursive(
+      commandsSource,
+      agileflowCommandsDir,
+      agileflowDir,
+      true // Inject dynamic content
+    );
+
+    // Install agents as subdirectory
     const agentsSource = path.join(agileflowDir, 'agents');
-    let agentCount = 0;
-
-    if (await this.exists(agentsSource)) {
-      const agents = await this.scanDirectory(agentsSource, '.md');
-
-      for (const agent of agents) {
-        // Read the original agent content
-        let content = await this.readFile(agent.path);
-
-        // Replace docs/ references with custom folder name
-        content = this.replaceDocsReferences(content);
-
-        const targetPath = path.join(agileflowAgentsDir, `${agent.name}.md`);
-        await this.writeFile(targetPath, content);
-        agentCount++;
-      }
-    }
+    const agentsTargetDir = path.join(agileflowCommandsDir, 'agents');
+    const agentResult = await this.installCommandsRecursive(
+      agentsSource,
+      agentsTargetDir,
+      agileflowDir,
+      false // No dynamic content for agents
+    );
 
     console.log(chalk.green(`  ✓ ${this.displayName} configured:`));
-    console.log(chalk.dim(`    - ${commandCount} commands installed`));
-    console.log(chalk.dim(`    - ${agentCount} agents installed`));
+    console.log(chalk.dim(`    - ${commandResult.commands} commands installed`));
+    console.log(chalk.dim(`    - ${agentResult.commands} agents installed`));
     console.log(chalk.dim(`    - Path: ${path.relative(projectDir, agileflowCommandsDir)}`));
 
     return {
       success: true,
-      commands: commandCount,
-      agents: agentCount,
+      commands: commandResult.commands,
+      agents: agentResult.commands,
     };
   }
 

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

@@ -37,64 +37,34 @@ class WindsurfSetup extends BaseIdeSetup {
     const workflowsDir = path.join(windsurfDir, this.workflowsDir);
     const agileflowWorkflowsDir = path.join(workflowsDir, 'agileflow');
 
-    await this.ensureDir(agileflowWorkflowsDir);
-
-    // Get commands from AgileFlow installation
+    // Install commands using shared recursive method
     const commandsSource = path.join(agileflowDir, 'commands');
-    let commandCount = 0;
-
-    if (await this.exists(commandsSource)) {
-      const commands = await this.scanDirectory(commandsSource, '.md');
-
-      for (const command of commands) {
-        // Read the original command content
-        let content = await this.readFile(command.path);
-
-        // Inject dynamic content (agent lists, command lists)
-        content = this.injectDynamicContent(content, agileflowDir);
-
-        // Replace docs/ references with custom folder name
-        content = this.replaceDocsReferences(content);
-
-        const targetPath = path.join(agileflowWorkflowsDir, `${command.name}.md`);
-        await this.writeFile(targetPath, content);
-        commandCount++;
-      }
-    }
-
-    // Create agents subdirectory
-    const agileflowAgentsDir = path.join(agileflowWorkflowsDir, 'agents');
-    await this.ensureDir(agileflowAgentsDir);
-
-    // Get agents from AgileFlow installation
+    const commandResult = await this.installCommandsRecursive(
+      commandsSource,
+      agileflowWorkflowsDir,
+      agileflowDir,
+      true // Inject dynamic content
+    );
+
+    // Install agents as subdirectory
     const agentsSource = path.join(agileflowDir, 'agents');
-    let agentCount = 0;
-
-    if (await this.exists(agentsSource)) {
-      const agents = await this.scanDirectory(agentsSource, '.md');
-
-      for (const agent of agents) {
-        // Read the original agent content
-        let content = await this.readFile(agent.path);
-
-        // Replace docs/ references with custom folder name
-        content = this.replaceDocsReferences(content);
-
-        const targetPath = path.join(agileflowAgentsDir, `${agent.name}.md`);
-        await this.writeFile(targetPath, content);
-        agentCount++;
-      }
-    }
+    const agentsTargetDir = path.join(agileflowWorkflowsDir, 'agents');
+    const agentResult = await this.installCommandsRecursive(
+      agentsSource,
+      agentsTargetDir,
+      agileflowDir,
+      false // No dynamic content for agents
+    );
 
     console.log(chalk.green(`  ✓ ${this.displayName} configured:`));
-    console.log(chalk.dim(`    - ${commandCount} workflows installed`));
-    console.log(chalk.dim(`    - ${agentCount} agent workflows installed`));
+    console.log(chalk.dim(`    - ${commandResult.commands} workflows installed`));
+    console.log(chalk.dim(`    - ${agentResult.commands} agent workflows installed`));
     console.log(chalk.dim(`    - Path: ${path.relative(projectDir, agileflowWorkflowsDir)}`));
 
     return {
       success: true,
-      commands: commandCount,
-      agents: agentCount,
+      commands: commandResult.commands,
+      agents: agentResult.commands,
     };
   }
 

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

@@ -7,7 +7,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const yaml = require('js-yaml');
+const { parseFrontmatter, normalizeTools } = require('../../../scripts/lib/frontmatter-parser');
 
 /**
  * Scan agents directory and generate formatted agent list
@@ -22,34 +22,20 @@ function generateAgentList(agentsDir) {
     const filePath = path.join(agentsDir, file);
     const content = fs.readFileSync(filePath, 'utf8');
 
-    // Extract YAML frontmatter
-    const match = content.match(/^---\n([\s\S]*?)\n---/);
-    if (!match) continue;
-
-    try {
-      const frontmatter = yaml.load(match[1]);
-
-      // Skip if frontmatter is null or not an object
-      if (!frontmatter || typeof frontmatter !== 'object') {
-        continue;
-      }
-
-      // Handle tools field - can be array or string
-      let tools = frontmatter.tools || [];
-      if (typeof tools === 'string') {
-        tools = tools.split(',').map(t => t.trim());
-      }
-
-      agents.push({
-        name: frontmatter.name || path.basename(file, '.md'),
-        description: frontmatter.description || '',
-        tools: tools,
-        model: frontmatter.model || 'haiku',
-      });
-    } catch (err) {
-      // Silently skip files with parsing errors
+    // Parse frontmatter using shared parser
+    const frontmatter = parseFrontmatter(content);
+
+    // Skip if no frontmatter found
+    if (!frontmatter || Object.keys(frontmatter).length === 0) {
       continue;
     }
+
+    agents.push({
+      name: frontmatter.name || path.basename(file, '.md'),
+      description: frontmatter.description || '',
+      tools: normalizeTools(frontmatter.tools),
+      model: frontmatter.model || 'haiku',
+    });
   }
 
   // Sort alphabetically by name
@@ -82,29 +68,20 @@ function generateCommandList(commandsDir) {
     const filePath = path.join(commandsDir, file);
     const content = fs.readFileSync(filePath, 'utf8');
 
-    // Extract YAML frontmatter
-    const match = content.match(/^---\n([\s\S]*?)\n---/);
-    if (!match) continue;
-
-    try {
-      const frontmatter = yaml.load(match[1]);
-      const cmdName = path.basename(file, '.md');
-
-      // Skip if frontmatter is null or not an object
-      if (!frontmatter || typeof frontmatter !== 'object') {
-        continue;
-      }
-
-      commands.push({
-        name: cmdName,
-        description: frontmatter.description || '',
-        argumentHint: frontmatter['argument-hint'] || '',
-      });
-    } catch (err) {
-      // Silently skip files with parsing errors - they might be generated files
-      // with content that looks like frontmatter but isn't
+    // Parse frontmatter using shared parser
+    const frontmatter = parseFrontmatter(content);
+    const cmdName = path.basename(file, '.md');
+
+    // Skip if no frontmatter found
+    if (!frontmatter || Object.keys(frontmatter).length === 0) {
       continue;
     }
+
+    commands.push({
+      name: cmdName,
+      description: frontmatter.description || '',
+      argumentHint: frontmatter['argument-hint'] || '',
+    });
   }
 
   // Sort alphabetically by name

package/tools/cli/lib/npm-utils.js

@@ -2,14 +2,33 @@
  * AgileFlow CLI - npm Registry Utilities
  *
  * Utilities for interacting with the npm registry.
+ * Set DEBUG_NPM=1 environment variable for verbose error logging.
  */
 
 const https = require('https');
 
+// Debug mode: set DEBUG_NPM=1 to see error details
+const DEBUG = process.env.DEBUG_NPM === '1';
+
+/**
+ * Log debug messages when DEBUG_NPM=1
+ * @param {string} message - Message to log
+ * @param {*} data - Optional data to include
+ */
+function debugLog(message, data = null) {
+  if (DEBUG) {
+    console.error(`[npm-utils] ${message}`, data ? JSON.stringify(data) : '');
+  }
+}
+
 /**
  * Get the latest version of a package from npm registry
- * @param {string} packageName - Name of the package
- * @returns {Promise<string|null>} Latest version or null if error
+ *
+ * Returns null on any error (network, timeout, invalid response) since
+ * version checking should not block the CLI. Set DEBUG_NPM=1 to see errors.
+ *
+ * @param {string} packageName - Name of the package (e.g., 'agileflow' or '@scope/pkg')
+ * @returns {Promise<string|null>} Latest version string or null if unavailable
  */
 async function getLatestVersion(packageName) {
   return new Promise(resolve => {
@@ -23,6 +42,8 @@ async function getLatestVersion(packageName) {
       },
     };
 
+    debugLog('Fetching version', { package: packageName, path: options.path });
+
     const req = https.request(options, res => {
       let data = '';
 
@@ -31,24 +52,30 @@ async function getLatestVersion(packageName) {
       });
 
       res.on('end', () => {
+        if (res.statusCode !== 200) {
+          debugLog('Non-200 status', { statusCode: res.statusCode });
+          return resolve(null);
+        }
+
         try {
-          if (res.statusCode === 200) {
-            const json = JSON.parse(data);
-            resolve(json.version || null);
-          } else {
-            resolve(null);
-          }
+          const json = JSON.parse(data);
+          const version = json.version || null;
+          debugLog('Version found', { version });
+          resolve(version);
         } catch (err) {
+          debugLog('JSON parse error', { error: err.message });
           resolve(null);
         }
       });
     });
 
-    req.on('error', () => {
+    req.on('error', err => {
+      debugLog('Network error', { error: err.message });
       resolve(null);
     });
 
     req.setTimeout(5000, () => {
+      debugLog('Request timeout');
       req.destroy();
       resolve(null);
     });

package/tools/cli/lib/ui.js

@@ -8,6 +8,7 @@ const chalk = require('chalk');
 const inquirer = require('inquirer');
 const path = require('node:path');
 const fs = require('node:fs');
+const { IdeManager } = require('../installers/ide/manager');
 
 // Load package.json for version
 const packageJsonPath = path.join(__dirname, '..', '..', '..', 'package.json');
@@ -73,8 +74,27 @@ function info(message) {
   console.log(chalk.dim(`  ${message}`));
 }
 
+// IDE Manager instance for dynamic IDE discovery
+const ideManager = new IdeManager();
+
+/**
+ * Get available IDE choices dynamically from installed handlers
+ * @returns {Array} IDE choices formatted for inquirer
+ */
+function getIdeChoices() {
+  const ides = ideManager.getAvailableIdes();
+
+  return ides.map((ide, index) => ({
+    name: ide.name,
+    value: ide.value,
+    // First IDE (preferred) is checked by default
+    checked: ide.preferred || index === 0,
+  }));
+}
+
 /**
- * Available IDE configurations
+ * @deprecated Use getIdeChoices() instead - dynamically loaded from IDE handlers
+ * Legacy hardcoded IDE choices kept for backward compatibility
  */
 const IDE_CHOICES = [
   {
@@ -126,7 +146,7 @@ async function promptInstall() {
       type: 'checkbox',
       name: 'ides',
       message: 'Select your IDE(s):',
-      choices: IDE_CHOICES,
+      choices: getIdeChoices(),
       validate: input => {
         if (input.length === 0) {
           return 'Please select at least one IDE';
@@ -219,5 +239,6 @@ module.exports = {
   promptInstall,
   confirm,
   getIdeConfig,
-  IDE_CHOICES,
+  getIdeChoices,
+  IDE_CHOICES, // @deprecated - kept for backward compatibility
 };