agileflow 2.51.0 → 2.56.0

package/scripts/generators/inject-readme.js

@@ -91,7 +91,9 @@ function injectContentByMarker(content, markerName, generated) {
   const timestamp = new Date().toISOString().split('T')[0];
   const injectedContent = `${startMarker}\n<!-- Auto-generated on ${timestamp}. Do not edit manually. -->\n\n${generated}\n${endMarker}`;
 
-  return content.substring(0, startIdx) + injectedContent + content.substring(endIdx + endMarker.length);
+  return (
+    content.substring(0, startIdx) + injectedContent + content.substring(endIdx + endMarker.length)
+  );
 }
 
 /**
@@ -117,7 +119,9 @@ function main() {
   const agents = scanAgents(agentsDir);
   const skills = scanSkills(skillsDir);
 
-  console.log(`Found: ${commands.length} commands, ${agents.length} agents, ${skills.length} skills`);
+  console.log(
+    `Found: ${commands.length} commands, ${agents.length} agents, ${skills.length} skills`
+  );
 
   // Read README
   let readmeContent = fs.readFileSync(readmeFile, 'utf-8');
@@ -127,7 +131,7 @@ function main() {
   const stats = generateStats({
     commands: commands.length,
     agents: agents.length,
-    skills: skills.length
+    skills: skills.length,
   });
 
   console.log('Generating agent table...');

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;
 }
 
 /**
@@ -48,10 +36,10 @@ function categorizeSkill(name, description) {
   const categories = {
     'Story & Planning': ['story', 'epic', 'sprint', 'acceptance-criteria'],
     'Code Generation': ['type-definitions', 'validation-schema', 'error-handler'],
-    'Testing': ['test-case'],
-    'Documentation': ['adr', 'api-documentation', 'changelog', 'pr-description'],
-    'Architecture': ['sql-schema', 'diagram'],
-    'Deployment': ['deployment-guide', 'migration-checklist']
+    Testing: ['test-case'],
+    Documentation: ['adr', 'api-documentation', 'changelog', 'pr-description'],
+    Architecture: ['sql-schema', 'diagram'],
+    Deployment: ['deployment-guide', 'migration-checklist'],
   };
 
   const lowerName = name.toLowerCase();
@@ -73,32 +61,65 @@ 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,
       file: 'SKILL.md',
       path: skillFile,
       description,
-      category: categorizeSkill(name, description)
+      category: categorizeSkill(name, description),
     });
   }
 
@@ -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/get-env.js

@@ -35,9 +35,7 @@ function getProjectInfo() {
   }
 
   try {
-    rootPackage = JSON.parse(
-      fs.readFileSync(path.join(rootDir, 'package.json'), 'utf8')
-    );
+    rootPackage = JSON.parse(fs.readFileSync(path.join(rootDir, 'package.json'), 'utf8'));
   } catch (err) {
     // Ignore if not found
   }
@@ -50,17 +48,17 @@ function getProjectInfo() {
   try {
     gitBranch = execSync('git branch --show-current', {
       cwd: rootDir,
-      encoding: 'utf8'
+      encoding: 'utf8',
     }).trim();
     gitCommit = execSync('git rev-parse --short HEAD', {
       cwd: rootDir,
-      encoding: 'utf8'
+      encoding: 'utf8',
     }).trim();
 
     // Get recent commits (last 5)
     const commitLog = execSync('git log --oneline -5 2>/dev/null', {
       cwd: rootDir,
-      encoding: 'utf8'
+      encoding: 'utf8',
     }).trim();
     recentCommits = commitLog.split('\n').filter(Boolean);
   } catch (err) {
@@ -68,10 +66,10 @@ function getProjectInfo() {
   }
 
   // Get AgileFlow status info
-  let activeStories = [];
+  const activeStories = [];
   let wipCount = 0;
   let blockedCount = 0;
-  let activeEpics = [];
+  const activeEpics = [];
 
   try {
     const statusPath = path.join(rootDir, 'docs/09-agents/status.json');
@@ -163,13 +161,16 @@ function formatOutput(info, asJson = false, compact = false) {
 
   // Header line with project info (brand color name, dim version, colored branch)
   const branchColor = info.git.branch === 'main' ? c.green : c.cyan;
-  lines.push(`${c.brand}${c.bold}${info.project.name}${c.reset} ${c.dim}v${info.project.version}${c.reset} | ${branchColor}${info.git.branch}${c.reset} ${c.dim}(${info.git.commit})${c.reset}`);
+  lines.push(
+    `${c.brand}${c.bold}${info.project.name}${c.reset} ${c.dim}v${info.project.version}${c.reset} | ${branchColor}${info.git.branch}${c.reset} ${c.dim}(${info.git.commit})${c.reset}`
+  );
 
   // Status line (yellow WIP, red blocked)
   const wipColor = info.agileflow.wipCount > 0 ? c.yellow : c.dim;
-  let statusLine = info.agileflow.wipCount > 0
-    ? `${wipColor}WIP: ${info.agileflow.wipCount}${c.reset}`
-    : `${c.dim}No active work${c.reset}`;
+  let statusLine =
+    info.agileflow.wipCount > 0
+      ? `${wipColor}WIP: ${info.agileflow.wipCount}${c.reset}`
+      : `${c.dim}No active work${c.reset}`;
   if (info.agileflow.blockedCount > 0) {
     statusLine += ` | ${c.red}Blocked: ${info.agileflow.blockedCount}${c.reset}`;
   }

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/scripts/obtain-context.js

@@ -28,7 +28,11 @@ if (commandName) {
   if (fs.existsSync(sessionStatePath)) {
     try {
       const state = JSON.parse(fs.readFileSync(sessionStatePath, 'utf8'));
-      state.active_command = { name: commandName, activated_at: new Date().toISOString(), state: {} };
+      state.active_command = {
+        name: commandName,
+        activated_at: new Date().toISOString(),
+        state: {},
+      };
       fs.writeFileSync(sessionStatePath, JSON.stringify(state, null, 2) + '\n');
     } catch (e) {
       // Silently continue if session state can't be updated
@@ -92,9 +96,16 @@ function safeExec(cmd) {
 function generateSummary() {
   // Box drawing characters
   const box = {
-    tl: '╭', tr: '╮', bl: '╰', br: '╯',
-    h: '─', v: '│',
-    lT: '├', rT: '┤', tT: '┬', bT: '┴',
+    tl: '╭',
+    tr: '╮',
+    bl: '╰',
+    br: '╯',
+    h: '─',
+    v: '│',
+    lT: '├',
+    rT: '┤',
+    tT: '┬',
+    bT: '┴',
     cross: '┼',
   };
 
@@ -144,7 +155,8 @@ function generateSummary() {
     return `${C.dim}${box.v}${C.reset} ${pad(leftStr, L)} ${C.dim}${box.v}${C.reset} ${pad(rightStr, R)} ${C.dim}${box.v}${C.reset}\n`;
   }
 
-  const divider = () => `${C.dim}${box.lT}${box.h.repeat(L + 2)}${box.cross}${box.h.repeat(R + 2)}${box.rT}${C.reset}\n`;
+  const divider = () =>
+    `${C.dim}${box.lT}${box.h.repeat(L + 2)}${box.cross}${box.h.repeat(R + 2)}${box.rT}${C.reset}\n`;
   const headerTopBorder = `${C.dim}${box.tl}${box.h.repeat(W + 2)}${box.tr}${C.reset}\n`;
   const headerDivider = `${C.dim}${box.lT}${box.h.repeat(L + 2)}${box.tT}${box.h.repeat(R + 2)}${box.rT}${C.reset}\n`;
   const bottomBorder = `${C.dim}${box.bl}${box.h.repeat(L + 2)}${box.bT}${box.h.repeat(R + 2)}${box.br}${C.reset}\n`;
@@ -156,12 +168,15 @@ function generateSummary() {
   const statusLines = (safeExec('git status --short') || '').split('\n').filter(Boolean);
   const statusJson = safeReadJSON('docs/09-agents/status.json');
   const sessionState = safeReadJSON('docs/09-agents/session-state.json');
-  const researchFiles = safeLs('docs/10-research').filter(f => f.endsWith('.md') && f !== 'README.md').sort().reverse();
+  const researchFiles = safeLs('docs/10-research')
+    .filter(f => f.endsWith('.md') && f !== 'README.md')
+    .sort()
+    .reverse();
   const epicFiles = safeLs('docs/05-epics').filter(f => f.endsWith('.md') && f !== 'README.md');
 
   // Count stories by status
-  let byStatus = {};
-  let readyStories = [];
+  const byStatus = {};
+  const readyStories = [];
   if (statusJson && statusJson.stories) {
     Object.entries(statusJson.stories).forEach(([id, story]) => {
       const s = story.status || 'unknown';
@@ -187,23 +202,45 @@ function generateSummary() {
   const title = commandName ? `Context [${commandName}]` : 'Context Summary';
   const branchColor = branch === 'main' ? C.green : branch.startsWith('fix') ? C.red : C.cyan;
   const maxBranchLen = 20;
-  const branchDisplay = branch.length > maxBranchLen ? branch.substring(0, maxBranchLen - 2) + '..' : branch;
+  const branchDisplay =
+    branch.length > maxBranchLen ? branch.substring(0, maxBranchLen - 2) + '..' : branch;
   const header = `${C.brand}${C.bold}${title}${C.reset}  ${branchColor}${branchDisplay}${C.reset} ${C.dim}(${lastCommitShort})${C.reset}`;
   summary += `${C.dim}${box.v}${C.reset} ${pad(header, W)} ${C.dim}${box.v}${C.reset}\n`;
 
   summary += headerDivider;
 
   // Story counts with colorful labels
-  summary += row('In Progress', byStatus['in-progress'] ? `${byStatus['in-progress']}` : '0', C.yellow, byStatus['in-progress'] ? C.brightYellow : C.dim);
-  summary += row('Blocked', byStatus['blocked'] ? `${byStatus['blocked']}` : '0', C.red, byStatus['blocked'] ? C.red : C.dim);
-  summary += row('Ready', byStatus['ready'] ? `${byStatus['ready']}` : '0', C.cyan, byStatus['ready'] ? C.brightCyan : C.dim);
+  summary += row(
+    'In Progress',
+    byStatus['in-progress'] ? `${byStatus['in-progress']}` : '0',
+    C.yellow,
+    byStatus['in-progress'] ? C.brightYellow : C.dim
+  );
+  summary += row(
+    'Blocked',
+    byStatus['blocked'] ? `${byStatus['blocked']}` : '0',
+    C.red,
+    byStatus['blocked'] ? C.red : C.dim
+  );
+  summary += row(
+    'Ready',
+    byStatus['ready'] ? `${byStatus['ready']}` : '0',
+    C.cyan,
+    byStatus['ready'] ? C.brightCyan : C.dim
+  );
   const completedColor = `${C.bold}${C.green}`;
-  summary += row('Completed', byStatus['done'] ? `${byStatus['done']}` : '0', completedColor, byStatus['done'] ? completedColor : C.dim);
+  summary += row(
+    'Completed',
+    byStatus['done'] ? `${byStatus['done']}` : '0',
+    completedColor,
+    byStatus['done'] ? completedColor : C.dim
+  );
 
   summary += divider();
 
   // Git status
-  const uncommittedStatus = statusLines.length > 0 ? `${statusLines.length} uncommitted` : '✓ clean';
+  const uncommittedStatus =
+    statusLines.length > 0 ? `${statusLines.length} uncommitted` : '✓ clean';
   summary += row('Git', uncommittedStatus, C.blue, statusLines.length > 0 ? C.yellow : C.green);
 
   // Session
@@ -228,10 +265,12 @@ function generateSummary() {
     { path: 'docs/04-architecture/README.md', label: 'arch' },
     { path: 'docs/02-practices/README.md', label: 'practices' },
   ];
-  const keyFileStatus = keyFileChecks.map(f => {
-    const exists = fs.existsSync(f.path);
-    return exists ? `${C.brightGreen}✓${C.reset}${f.label}` : `${C.dim}○${f.label}${C.reset}`;
-  }).join(' ');
+  const keyFileStatus = keyFileChecks
+    .map(f => {
+      const exists = fs.existsSync(f.path);
+      return exists ? `${C.brightGreen}✓${C.reset}${f.label}` : `${C.dim}○${f.label}${C.reset}`;
+    })
+    .join(' ');
   summary += row('Key files', keyFileStatus, C.magenta, '');
 
   // Research
@@ -245,7 +284,12 @@ function generateSummary() {
   summary += divider();
 
   // Last commit
-  summary += row('Last commit', `${C.yellow}${lastCommitShort}${C.reset} ${lastCommitMsg}`, C.dim, '');
+  summary += row(
+    'Last commit',
+    `${C.yellow}${lastCommitShort}${C.reset} ${lastCommitMsg}`,
+    C.dim,
+    ''
+  );
 
   summary += bottomBorder;
 
@@ -276,8 +320,9 @@ function generateFullContent() {
   content += `Last commit: ${C.dim}${lastCommit}${C.reset}\n`;
   if (statusLines.length > 0) {
     content += `Uncommitted: ${C.yellow}${statusLines.length} file(s)${C.reset}\n`;
-    statusLines.slice(0, 10).forEach(line => content += `  ${C.dim}${line}${C.reset}\n`);
-    if (statusLines.length > 10) content += `  ${C.dim}... and ${statusLines.length - 10} more${C.reset}\n`;
+    statusLines.slice(0, 10).forEach(line => (content += `  ${C.dim}${line}${C.reset}\n`));
+    if (statusLines.length > 10)
+      content += `  ${C.dim}... and ${statusLines.length - 10} more${C.reset}\n`;
   } else {
     content += `Uncommitted: ${C.green}clean${C.reset}\n`;
   }
@@ -289,7 +334,11 @@ function generateFullContent() {
 
   if (statusJson) {
     content += `${C.dim}${'─'.repeat(50)}${C.reset}\n`;
-    content += JSON.stringify(statusJson, null, 2).split('\n').map(l => `  ${l}`).join('\n') + '\n';
+    content +=
+      JSON.stringify(statusJson, null, 2)
+        .split('\n')
+        .map(l => `  ${l}`)
+        .join('\n') + '\n';
     content += `${C.dim}${'─'.repeat(50)}${C.reset}\n`;
   } else {
     content += `${C.dim}No status.json found${C.reset}\n`;
@@ -321,7 +370,11 @@ function generateFullContent() {
   content += `\n${C.cyan}${C.bold}═══ Documentation ═══${C.reset}\n`;
   const docsDir = 'docs';
   const docFolders = safeLs(docsDir).filter(f => {
-    try { return fs.statSync(path.join(docsDir, f)).isDirectory(); } catch { return false; }
+    try {
+      return fs.statSync(path.join(docsDir, f)).isDirectory();
+    } catch {
+      return false;
+    }
   });
 
   if (docFolders.length > 0) {
@@ -330,7 +383,7 @@ function generateFullContent() {
       const files = safeLs(folderPath);
       const mdFiles = files.filter(f => f.endsWith('.md'));
       const jsonFiles = files.filter(f => f.endsWith('.json') || f.endsWith('.jsonl'));
-      let info = [];
+      const info = [];
       if (mdFiles.length > 0) info.push(`${mdFiles.length} md`);
       if (jsonFiles.length > 0) info.push(`${jsonFiles.length} json`);
       content += `  ${C.dim}${folder}/${C.reset} ${info.length > 0 ? `(${info.join(', ')})` : ''}\n`;
@@ -344,7 +397,7 @@ function generateFullContent() {
   if (researchFiles.length > 0) {
     researchFiles.sort().reverse();
     content += `${C.dim}───${C.reset} Available Research Notes\n`;
-    researchFiles.forEach(file => content += `  ${C.dim}${file}${C.reset}\n`);
+    researchFiles.forEach(file => (content += `  ${C.dim}${file}${C.reset}\n`));
 
     const mostRecentFile = researchFiles[0];
     const mostRecentPath = path.join(researchDir, mostRecentFile);
@@ -414,7 +467,7 @@ function generateFullContent() {
   content += `\n${C.cyan}${C.bold}═══ Epic Files ═══${C.reset}\n`;
   const epicFiles = safeLs('docs/05-epics').filter(f => f.endsWith('.md') && f !== 'README.md');
   if (epicFiles.length > 0) {
-    epicFiles.forEach(file => content += `  ${C.dim}${file}${C.reset}\n`);
+    epicFiles.forEach(file => (content += `  ${C.dim}${file}${C.reset}\n`));
   } else {
     content += `${C.dim}No epic files${C.reset}\n`;
   }