agileflow 3.4.2 → 4.0.0-alpha.1

package/scripts/generators/inject-help.js

@@ -1,125 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * Help Command Content Injector
- *
- * Injects command list into /agileflow:help command file.
- * Finds AUTOGEN markers and replaces content with generated command directory.
- */
-
-const fs = require('fs');
-const fsp = require('fs').promises;
-const path = require('path');
-const { scanCommands } = require('./command-registry');
-
-/**
- * Generate command list content as category summary with counts and examples.
- * Uses compact format with discovery pointer instead of listing every command.
- * Research (arXiv:2602.11988): Full lists increase context cost without improving performance.
- * @param {Array} commands - Array of command metadata
- * @returns {string} Formatted command category summary
- */
-function generateCommandList(commands) {
-  const lines = [];
-
-  // Group commands by category
-  const categories = {};
-  for (const cmd of commands) {
-    if (!categories[cmd.category]) {
-      categories[cmd.category] = [];
-    }
-    categories[cmd.category].push(cmd);
-  }
-
-  lines.push(
-    `**${commands.length} commands** across ${Object.keys(categories).length} categories:`
-  );
-  lines.push('');
-
-  // Generate compact category summary with examples
-  for (const [category, cmds] of Object.entries(categories)) {
-    const examples = cmds
-      .slice(0, 3)
-      .map(c => c.name)
-      .join(', ');
-    const more = cmds.length > 3 ? `, +${cmds.length - 3} more` : '';
-    lines.push(`- **${category}** (${cmds.length}): ${examples}${more}`);
-  }
-
-  lines.push('');
-  lines.push('Browse all: `ls .agileflow/commands/` or run `/agileflow:help`');
-
-  return lines.join('\n');
-}
-
-/**
- * Inject content between AUTOGEN markers
- * @param {string} content - Original file content
- * @param {string} generated - Generated content to inject
- * @returns {string} Updated file content
- */
-function injectContent(content, generated) {
-  const startMarker = '<!-- AUTOGEN:COMMAND_LIST:START -->';
-  const endMarker = '<!-- AUTOGEN:COMMAND_LIST:END -->';
-
-  const startIdx = content.indexOf(startMarker);
-  const endIdx = content.indexOf(endMarker);
-
-  if (startIdx === -1 || endIdx === -1) {
-    console.error('AUTOGEN markers not found in file');
-    return content;
-  }
-
-  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)
-  );
-}
-
-/**
- * Main function
- */
-async function main() {
-  const rootDir = path.resolve(__dirname, '../..');
-  const helpFile = path.join(rootDir, 'src/core/commands/help.md');
-  const commandsDir = path.join(rootDir, 'src/core/commands');
-
-  // Check if help file exists
-  if (!fs.existsSync(helpFile)) {
-    console.error(`Help file not found: ${helpFile}`);
-    process.exit(1);
-  }
-
-  // Scan commands
-  console.log('Scanning commands...');
-  const commands = scanCommands(commandsDir);
-  console.log(`Found ${commands.length} commands`);
-
-  // Generate command list
-  console.log('Generating command list...');
-  const commandList = generateCommandList(commands);
-
-  // Read help file
-  const helpContent = await fsp.readFile(helpFile, 'utf-8');
-
-  // Inject content
-  console.log('Injecting content into help.md...');
-  const updatedContent = injectContent(helpContent, commandList);
-
-  // Write back
-  await fsp.writeFile(helpFile, updatedContent, 'utf-8');
-  console.log('✅ Successfully updated help.md');
-}
-
-// Export for use in orchestrator
-module.exports = { generateCommandList, injectContent };
-
-// Run if called directly
-if (require.main === module) {
-  main().catch(err => {
-    console.error(err);
-    process.exit(1);
-  });
-}

package/scripts/generators/inject-readme.js

@@ -1,166 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * README Content Injector
- *
- * Injects stats, agent tables, and skill lists into README.md.
- * Handles multiple AUTOGEN sections for different content types.
- */
-
-const fs = require('fs');
-const fsp = require('fs').promises;
-const path = require('path');
-const { scanAgents } = require('./agent-registry');
-const { scanCommands } = require('./command-registry');
-const { scanSkills } = require('./skill-registry');
-
-/**
- * Generate stats content (command/agent/skill counts)
- * @param {Object} counts - {commands, agents, skills}
- * @returns {string} Formatted stats
- */
-function generateStats(counts) {
-  return `- **${counts.commands}** slash commands\n- **${counts.agents}** specialized agents\n- **${counts.skills}** code generation skills`;
-}
-
-/**
- * Generate agent table (markdown table format)
- * @param {Array} agents - Array of agent metadata
- * @returns {string} Formatted table
- */
-function generateAgentTable(agents) {
-  const lines = [];
-
-  lines.push('| Agent | Description | Model | Category |');
-  lines.push('|-------|-------------|-------|----------|');
-
-  for (const agent of agents) {
-    const tools = agent.tools.slice(0, 3).join(', ') + (agent.tools.length > 3 ? '...' : '');
-    lines.push(`| ${agent.name} | ${agent.description} | ${agent.model} | ${agent.category} |`);
-  }
-
-  return lines.join('\n');
-}
-
-/**
- * Generate skill list (bulleted list grouped by category)
- * @param {Array} skills - Array of skill metadata
- * @returns {string} Formatted list
- */
-function generateSkillList(skills) {
-  const lines = [];
-
-  // Group by category
-  const categories = {};
-  for (const skill of skills) {
-    if (!categories[skill.category]) {
-      categories[skill.category] = [];
-    }
-    categories[skill.category].push(skill);
-  }
-
-  for (const [category, categorySkills] of Object.entries(categories)) {
-    lines.push(`**${category}:**`);
-    for (const skill of categorySkills) {
-      lines.push(`- **${skill.name}**: ${skill.description}`);
-    }
-    lines.push('');
-  }
-
-  return lines.join('\n');
-}
-
-/**
- * Inject content between specified AUTOGEN markers
- * @param {string} content - Original file content
- * @param {string} markerName - Name of the marker (e.g., STATS, AGENT_TABLE)
- * @param {string} generated - Generated content to inject
- * @returns {string} Updated file content
- */
-function injectContentByMarker(content, markerName, generated) {
-  const startMarker = `<!-- AUTOGEN:${markerName}:START -->`;
-  const endMarker = `<!-- AUTOGEN:${markerName}:END -->`;
-
-  const startIdx = content.indexOf(startMarker);
-  const endIdx = content.indexOf(endMarker);
-
-  if (startIdx === -1 || endIdx === -1) {
-    console.warn(`AUTOGEN:${markerName} markers not found - skipping`);
-    return content;
-  }
-
-  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)
-  );
-}
-
-/**
- * Main function
- */
-async function main() {
-  const cliDir = path.resolve(__dirname, '../..');
-  const rootDir = path.resolve(cliDir, '../..');
-  const readmeFile = path.join(rootDir, 'README.md');
-  const agentsDir = path.join(cliDir, 'src/core/agents');
-  const commandsDir = path.join(cliDir, 'src/core/commands');
-  const skillsDir = path.join(cliDir, 'src/core/skills');
-
-  // Check if README exists
-  if (!fs.existsSync(readmeFile)) {
-    console.error(`README not found: ${readmeFile}`);
-    process.exit(1);
-  }
-
-  // Scan all registries in parallel
-  console.log('Scanning commands, agents, and skills...');
-  const [commands, agents, skills] = await Promise.all([
-    Promise.resolve(scanCommands(commandsDir)),
-    Promise.resolve(scanAgents(agentsDir)),
-    Promise.resolve(scanSkills(skillsDir)),
-  ]);
-
-  console.log(
-    `Found: ${commands.length} commands, ${agents.length} agents, ${skills.length} skills`
-  );
-
-  // Read README
-  let readmeContent = await fsp.readFile(readmeFile, 'utf-8');
-
-  // Generate content
-  console.log('Generating stats...');
-  const stats = generateStats({
-    commands: commands.length,
-    agents: agents.length,
-    skills: skills.length,
-  });
-
-  console.log('Generating agent table...');
-  const agentTable = generateAgentTable(agents);
-
-  console.log('Generating skill list...');
-  const skillList = generateSkillList(skills);
-
-  // Inject content
-  console.log('Injecting content into README.md...');
-  readmeContent = injectContentByMarker(readmeContent, 'STATS', stats);
-  readmeContent = injectContentByMarker(readmeContent, 'AGENT_TABLE', agentTable);
-  readmeContent = injectContentByMarker(readmeContent, 'SKILL_LIST', skillList);
-
-  // Write back
-  await fsp.writeFile(readmeFile, readmeContent, 'utf-8');
-  console.log('✅ Successfully updated README.md');
-}
-
-// Export for use in orchestrator
-module.exports = { generateStats, generateAgentTable, generateSkillList, injectContentByMarker };
-
-// Run if called directly
-if (require.main === module) {
-  main().catch(err => {
-    console.error(err);
-    process.exit(1);
-  });
-}

package/scripts/generators/skill-registry.js

@@ -1,188 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * Skill Registry Scanner
- *
- * 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 fsp = require('fs').promises;
-const path = require('path');
-const { extractFrontmatter } = require('../lib/frontmatter-parser');
-const { getCached, setCached } = require('../../lib/registry-cache');
-
-// Debug mode: set DEBUG_REGISTRY=1 to see why files are skipped
-const DEBUG = process.env.DEBUG_REGISTRY === '1';
-
-/**
- * Log debug messages when DEBUG_REGISTRY=1
- * @param {string} message - Message to log
- */
-function debugLog(message) {
-  if (DEBUG) {
-    console.error(`[skill-registry] ${message}`);
-  }
-}
-
-/**
- * Categorize skill based on its name/description
- * @param {string} name - Skill name
- * @param {string} description - Skill description
- * @returns {string} Category name
- */
-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'],
-  };
-
-  const lowerName = name.toLowerCase();
-  const lowerDesc = description.toLowerCase();
-
-  for (const [category, keywords] of Object.entries(categories)) {
-    if (keywords.some(kw => lowerName.includes(kw) || lowerDesc.includes(kw))) {
-      return category;
-    }
-  }
-
-  return 'Other';
-}
-
-/**
- * Scan skills directory and build registry
- * @param {string} skillsDir - Path to skills directory
- * @returns {Promise<Array>} Array of skill metadata objects
- */
-async function scanSkills(skillsDir) {
-  // Check cache first
-  const cached = getCached(skillsDir);
-  if (cached) {
-    debugLog(`Using cached skills for ${skillsDir}`);
-    return cached;
-  }
-
-  const skills = [];
-  const skipped = [];
-
-  let skillDirs;
-  try {
-    skillDirs = await fsp.readdir(skillsDir);
-  } catch (err) {
-    debugLog(`Failed to read directory: ${err.message}`);
-    return skills;
-  }
-
-  debugLog(`Scanning ${skillDirs.length} entries in ${skillsDir}`);
-
-  for (const skillDir of skillDirs) {
-    const skillPath = path.join(skillsDir, skillDir);
-
-    // Skip if not a directory
-    let stat;
-    try {
-      stat = await fsp.stat(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
-    try {
-      await fsp.access(skillFile);
-    } catch (err) {
-      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),
-    });
-  }
-
-  // Sort by category, then by name
-  skills.sort((a, b) => {
-    if (a.category !== b.category) {
-      return a.category.localeCompare(b.category);
-    }
-    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`);
-
-  // Cache the result
-  setCached(skillsDir, skills);
-
-  return skills;
-}
-
-/**
- * Main function
- */
-async function main() {
-  const rootDir = path.resolve(__dirname, '../..');
-  const skillsDir = path.join(rootDir, 'src/core/skills');
-
-  if (!fs.existsSync(skillsDir)) {
-    console.error(`Skills directory not found: ${skillsDir}`);
-    process.exit(1);
-  }
-
-  const skills = await scanSkills(skillsDir);
-
-  // If called directly, output JSON
-  if (require.main === module) {
-    console.log(JSON.stringify(skills, null, 2));
-  }
-
-  return skills;
-}
-
-// Export for use in other scripts
-module.exports = { scanSkills, categorizeSkill };
-
-// Run if called directly
-if (require.main === module) {
-  main().catch(err => {
-    console.error('Error:', err.message);
-    process.exit(1);
-  });
-}

package/scripts/get-env.js

@@ -1,225 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * get-env.js - Helper script to output environment information
- *
- * This script can be called from hooks or other automation to get
- * consistent environment information about the AgileFlow project.
- *
- * Usage:
- *   node scripts/get-env.js [--json] [--compact]
- *
- * Flags:
- *   --json     Output as JSON
- *   --compact  Minimal output for status line
- */
-
-const fs = require('fs');
-const path = require('path');
-const os = require('os');
-const { execFileSync } = require('child_process');
-
-// Import centralized path utilities
-const { getStatusPath } = require('../lib/paths');
-
-// Import centralized file cache (US-0176: deduplicated status.json access)
-const { readJSONCached } = require('../lib/file-cache');
-
-function getProjectInfo() {
-  const rootDir = path.resolve(__dirname, '..');
-
-  // Read package.json files
-  let cliPackage = {};
-  let rootPackage = {};
-
-  try {
-    cliPackage = JSON.parse(
-      fs.readFileSync(path.join(rootDir, 'packages/cli/package.json'), 'utf8')
-    );
-  } catch (err) {
-    // Ignore if not found
-  }
-
-  try {
-    rootPackage = JSON.parse(fs.readFileSync(path.join(rootDir, 'package.json'), 'utf8'));
-  } catch (err) {
-    // Ignore if not found
-  }
-
-  // Get git info
-  let gitBranch = 'unknown';
-  let gitCommit = 'unknown';
-  let recentCommits = [];
-
-  try {
-    gitBranch = execFileSync('git', ['branch', '--show-current'], {
-      cwd: rootDir,
-      encoding: 'utf8',
-    }).trim();
-    gitCommit = execFileSync('git', ['rev-parse', '--short', 'HEAD'], {
-      cwd: rootDir,
-      encoding: 'utf8',
-    }).trim();
-
-    // Get recent commits (last 5)
-    const commitLog = execFileSync('git', ['log', '--oneline', '-5'], {
-      cwd: rootDir,
-      encoding: 'utf8',
-    }).trim();
-    recentCommits = commitLog.split('\n').filter(Boolean);
-  } catch (err) {
-    // Ignore if git not available
-  }
-
-  // Get AgileFlow status info
-  const activeStories = [];
-  let wipCount = 0;
-  let blockedCount = 0;
-  const activeEpics = [];
-
-  try {
-    const statusPath = getStatusPath(rootDir);
-    // Use centralized file cache (US-0176: 60s TTL, shared across all consumers)
-    const status = readJSONCached(statusPath, { ttlMs: 60000 });
-
-    if (status) {
-      // Get active stories
-      if (status.stories) {
-        Object.entries(status.stories).forEach(([id, story]) => {
-          if (story.status === 'in-progress') {
-            activeStories.push({ id, title: story.title, owner: story.owner });
-            wipCount++;
-          }
-          if (story.status === 'blocked') {
-            blockedCount++;
-          }
-        });
-      }
-
-      // Get active epics
-      if (status.epics) {
-        Object.entries(status.epics).forEach(([id, epic]) => {
-          if (epic.status !== 'complete') {
-            activeEpics.push({ id, title: epic.title });
-          }
-        });
-      }
-    }
-  } catch (err) {
-    // Ignore if status.json not available
-  }
-
-  return {
-    project: {
-      name: cliPackage.name || rootPackage.name || 'AgileFlow',
-      version: cliPackage.version || rootPackage.version || 'unknown',
-      description: cliPackage.description || rootPackage.description || '',
-      rootDir: rootDir,
-    },
-    git: {
-      branch: gitBranch,
-      commit: gitCommit,
-      recentCommits: recentCommits,
-    },
-    agileflow: {
-      activeStories: activeStories,
-      wipCount: wipCount,
-      blockedCount: blockedCount,
-      activeEpics: activeEpics,
-    },
-    system: {
-      node: process.version,
-      platform: os.platform(),
-      arch: os.arch(),
-      hostname: os.hostname(),
-      user: os.userInfo().username,
-    },
-    timestamp: new Date().toISOString(),
-  };
-}
-
-function formatOutput(info, asJson = false, compact = false) {
-  if (asJson) {
-    return JSON.stringify(info, null, 2);
-  }
-
-  if (compact) {
-    // Minimal output for status line
-    const story = info.agileflow.activeStories[0];
-    const storyStr = story ? `${story.id}: ${story.title.substring(0, 30)}` : 'No active story';
-    return `[${info.git.branch}] ${storyStr} | WIP: ${info.agileflow.wipCount}`;
-  }
-
-  // ANSI colors (including brand color #e8683a as RGB)
-  const c = {
-    reset: '\x1b[0m',
-    bold: '\x1b[1m',
-    dim: '\x1b[2m',
-    green: '\x1b[32m',
-    yellow: '\x1b[33m',
-    blue: '\x1b[34m',
-    cyan: '\x1b[36m',
-    red: '\x1b[31m',
-    brand: '\x1b[38;2;232;104;58m', // #e8683a - AgileFlow brand orange
-
-    // Vibrant 256-color palette (modern, sleek look)
-    mintGreen: '\x1b[38;5;158m', // Healthy/success states
-    peach: '\x1b[38;5;215m', // Warning states
-    coral: '\x1b[38;5;203m', // Critical/error states
-    lightGreen: '\x1b[38;5;194m', // Session healthy
-    skyBlue: '\x1b[38;5;117m', // Directories/paths
-    lavender: '\x1b[38;5;147m', // Model info
-  };
-
-  // Beautiful compact colorful format (using vibrant 256-color palette)
-  const lines = [];
-
-  // Header line with project info (brand color name, dim version, colored branch)
-  const branchColor = info.git.branch === 'main' ? c.mintGreen : c.skyBlue;
-  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 (peach WIP, coral blocked)
-  const wipColor = info.agileflow.wipCount > 0 ? c.peach : c.dim;
-  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.coral}Blocked: ${info.agileflow.blockedCount}${c.reset}`;
-  }
-  lines.push(statusLine);
-
-  // Active story (if any) - just the first one (sky blue label)
-  if (info.agileflow.activeStories.length > 0) {
-    const story = info.agileflow.activeStories[0];
-    lines.push(`${c.skyBlue}Current:${c.reset} ${story.id} - ${story.title}`);
-  }
-
-  // Last commit (just one, dim)
-  if (info.git.recentCommits.length > 0) {
-    lines.push(`${c.dim}Last: ${info.git.recentCommits[0]}${c.reset}`);
-  }
-
-  return lines.join('\n');
-}
-
-// Main execution
-if (require.main === module) {
-  const args = process.argv.slice(2);
-  const asJson = args.includes('--json');
-  const compact = args.includes('--compact');
-
-  try {
-    const info = getProjectInfo();
-    console.log(formatOutput(info, asJson, compact));
-    process.exit(0);
-  } catch (err) {
-    console.error('Error getting environment info:', err.message);
-    process.exit(1);
-  }
-}
-
-// Export for use as module
-module.exports = { getProjectInfo, formatOutput };