agileflow 2.55.0 → 2.57.0

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/src/core/commands/whats-new.md

@@ -0,0 +1,94 @@
+---
+description: Show what's new in AgileFlow
+---
+
+# /agileflow:whats-new
+
+Display recent AgileFlow updates and version history.
+
+---
+
+## Prompt
+
+ROLE: AgileFlow Version Reporter
+
+**STEP 1: Get current version and changelog**
+
+Read the AgileFlow CHANGELOG.md:
+
+```bash
+cat .agileflow/CHANGELOG.md 2>/dev/null || echo "Changelog not found"
+```
+
+Also check the installed version:
+```bash
+cat .agileflow/package.json 2>/dev/null | grep '"version"' || echo "Version unknown"
+```
+
+**STEP 2: Parse and display**
+
+Parse the CHANGELOG.md and display:
+
+1. **Current installed version** at the top
+2. **Last 3-5 versions** with their changes
+3. Use clear formatting with headers and bullets
+
+**FORMAT:**
+
+```
+╭─────────────────────────────────────────────────────╮
+│  AgileFlow Changelog                                │
+│  Current: v2.57.0                                   │
+╰─────────────────────────────────────────────────────╯
+
+## v2.57.0 (2025-12-27)
+
+### Added
+• Auto-update system with configurable check frequency
+• Update notifications in welcome message and status line
+• Changelog display after updates
+
+---
+
+## v2.56.0 (2025-12-27)
+
+### Added
+• Dynamic IDE discovery - Codex CLI now in setup
+
+### Changed
+• Replaced hardcoded IDE list with dynamic loading
+
+---
+
+## v2.55.0 (2025-12-26)
+
+### Changed
+• Consolidated code improvements and debugging
+
+---
+
+📖 Full changelog: https://github.com/projectquestorg/AgileFlow/blob/main/packages/cli/CHANGELOG.md
+🔄 Check for updates: npx agileflow update
+⚙️  Configure auto-update: /agileflow:configure --auto-update
+```
+
+**STEP 3: Check for updates**
+
+After displaying, check if an update is available:
+
+```bash
+npm view agileflow version 2>/dev/null
+```
+
+If a newer version exists, show:
+```
+⚡ Update available: v2.57.0 → v2.58.0
+   Run: npx agileflow update
+```
+
+**RULES:**
+- Show max 5 versions (most recent first)
+- Use clear section headers
+- Include dates if available
+- Always show the GitHub link for full history
+- Mention update availability if applicable

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