agileflow 2.42.0 → 2.44.0

package/scripts/generators/inject-help.js

@@ -0,0 +1,109 @@
+#!/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 path = require('path');
+const { scanCommands } = require('./command-registry');
+
+/**
+ * Generate command list content grouped by category
+ * @param {Array} commands - Array of command metadata
+ * @returns {string} Formatted command list
+ */
+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);
+  }
+
+  // Generate markdown for each category
+  for (const [category, cmds] of Object.entries(categories)) {
+    lines.push(`**${category}:**`);
+    for (const cmd of cmds) {
+      const hint = cmd.argumentHint ? ` ${cmd.argumentHint}` : '';
+      lines.push(`- \`/agileflow:${cmd.name}${hint}\` - ${cmd.description}`);
+    }
+    lines.push(''); // Blank line between categories
+  }
+
+  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
+ */
+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 = fs.readFileSync(helpFile, 'utf-8');
+
+  // Inject content
+  console.log('Injecting content into help.md...');
+  const updatedContent = injectContent(helpContent, commandList);
+
+  // Write back
+  fs.writeFileSync(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();
+}

package/scripts/generators/inject-readme.js

@@ -0,0 +1,156 @@
+#!/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 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
+ */
+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
+  console.log('Scanning commands, agents, and skills...');
+  const commands = scanCommands(commandsDir);
+  const agents = scanAgents(agentsDir);
+  const skills = scanSkills(skillsDir);
+
+  console.log(`Found: ${commands.length} commands, ${agents.length} agents, ${skills.length} skills`);
+
+  // Read README
+  let readmeContent = fs.readFileSync(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
+  fs.writeFileSync(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();
+}

package/scripts/generators/skill-registry.js

@@ -0,0 +1,144 @@
+#!/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.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Extract YAML frontmatter from markdown file
+ * @param {string} filePath - Path to markdown file
+ * @returns {object} Frontmatter object
+ */
+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, '');
+    }
+  }
+
+  return frontmatter;
+}
+
+/**
+ * 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 {Array} Array of skill metadata objects
+ */
+function scanSkills(skillsDir) {
+  const skills = [];
+
+  // Each skill is in its own directory with a SKILL.md file
+  const skillDirs = fs.readdirSync(skillsDir);
+
+  for (const skillDir of skillDirs) {
+    const skillPath = path.join(skillsDir, skillDir);
+
+    // Skip if not a directory
+    if (!fs.statSync(skillPath).isDirectory()) continue;
+
+    const skillFile = path.join(skillPath, 'SKILL.md');
+
+    // Skip if SKILL.md doesn't exist
+    if (!fs.existsSync(skillFile)) continue;
+
+    const frontmatter = extractFrontmatter(skillFile);
+    const name = frontmatter.name || skillDir;
+    const description = frontmatter.description || '';
+
+    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);
+  });
+
+  return skills;
+}
+
+/**
+ * Main function
+ */
+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 = 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, extractFrontmatter, categorizeSkill };
+
+// Run if called directly
+if (require.main === module) {
+  main();
+}

package/src/core/agents/accessibility.md

@@ -5,6 +5,14 @@ tools: Read, Write, Edit, Bash, Glob, Grep
 model: haiku
 ---
 
+## STEP 0: Gather Context
+
+```bash
+node scripts/obtain-context.js accessibility
+```
+
+---
+
 <!-- COMPACT_SUMMARY_START -->
 # AG-ACCESSIBILITY Quick Reference
 

package/src/core/agents/adr-writer.md

@@ -5,6 +5,14 @@ tools: Read, Write, Edit, Glob, Grep
 model: haiku
 ---
 
+## STEP 0: Gather Context
+
+```bash
+node scripts/obtain-context.js adr-writer
+```
+
+---
+
 <!-- COMPACT_SUMMARY_START -->
 # ADR-WRITER Quick Reference
 

package/src/core/agents/analytics.md

@@ -5,6 +5,14 @@ tools: Read, Write, Edit, Bash, Glob, Grep
 model: haiku
 ---
 
+## STEP 0: Gather Context
+
+```bash
+node scripts/obtain-context.js analytics
+```
+
+---
+
 <!-- COMPACT_SUMMARY_START -->
 # AG-ANALYTICS Quick Reference
 

package/src/core/agents/api.md

@@ -5,6 +5,14 @@ tools: Read, Write, Edit, Bash, Glob, Grep
 model: haiku
 ---
 
+## STEP 0: Gather Context
+
+```bash
+node scripts/obtain-context.js api
+```
+
+---
+
 **⚡ Execution Policy**: Slash commands are autonomous (run without asking), file operations require diff + YES/NO confirmation. See CLAUDE.md Command Safety Policy for full details.
 
 <!-- COMPACT_SUMMARY_START -->
@@ -433,8 +441,6 @@ RESEARCH INTEGRATION
 
 PLAN MODE FOR COMPLEX API WORK
 
-**Reference**: `@docs/02-practices/plan-mode.md`
-
 Before implementing, evaluate complexity:
 
 | Situation | Action |

package/src/core/agents/ci.md

@@ -5,6 +5,14 @@ tools: Read, Write, Edit, Bash, Glob, Grep
 model: haiku
 ---
 
+## STEP 0: Gather Context
+
+```bash
+node scripts/obtain-context.js ci
+```
+
+---
+
 <!-- COMPACT_SUMMARY_START -->
 # AG-CI Quick Reference
 

package/src/core/agents/compliance.md

@@ -5,6 +5,14 @@ tools: Read, Write, Edit, Bash, Glob, Grep
 model: haiku
 ---
 
+## STEP 0: Gather Context
+
+```bash
+node scripts/obtain-context.js compliance
+```
+
+---
+
 <!-- COMPACT_SUMMARY_START -->
 # AG-COMPLIANCE Quick Reference
 

package/src/core/agents/configuration/archival.md

@@ -12,6 +12,14 @@ tools:
 model: haiku
 ---
 
+## STEP 0: Gather Context
+
+```bash
+node scripts/obtain-context.js configuration-archival
+```
+
+---
+
 # Configuration Agent: Auto-Archival System
 
 Configure auto-archival system to manage status.json file size.
@@ -20,7 +28,21 @@ Configure auto-archival system to manage status.json file size.
 
 ROLE: Auto-Archival Configurator
 
-🔴 **AskUserQuestion Format**: NEVER ask users to "type" anything. Use proper options with XML invoke format. See `docs/02-practices/ask-user-question.md`.
+🔴 **AskUserQuestion Format**: NEVER ask users to "type" anything. Use proper options:
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "How many days before archiving completed stories?",
+  "header": "Threshold",
+  "multiSelect": false,
+  "options": [
+    {"label": "7 days (Recommended)", "description": "Archive after 1 week"},
+    {"label": "14 days", "description": "Archive after 2 weeks"},
+    {"label": "30 days", "description": "Archive after 1 month"}
+  ]
+}]</parameter>
+</invoke>
+```
 
 OBJECTIVE
 Configure the auto-archival system that prevents `docs/09-agents/status.json` from exceeding Claude Code's token limit by automatically moving old completed stories to an archive.

package/src/core/agents/configuration/attribution.md

@@ -12,6 +12,14 @@ tools:
 model: haiku
 ---
 
+## STEP 0: Gather Context
+
+```bash
+node scripts/obtain-context.js configuration-attribution
+```
+
+---
+
 # Configuration Agent: Attribution Settings
 
 Configure CLAUDE.md file with git attribution preferences.
@@ -20,7 +28,20 @@ Configure CLAUDE.md file with git attribution preferences.
 
 ROLE: Attribution Configurator
 
-🔴 **AskUserQuestion Format**: NEVER ask users to "type" anything. Use proper options with XML invoke format. See `docs/02-practices/ask-user-question.md`.
+🔴 **AskUserQuestion Format**: NEVER ask users to "type" anything. Use proper options:
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "How should git commits be attributed?",
+  "header": "Attribution",
+  "multiSelect": false,
+  "options": [
+    {"label": "No AI attribution (Recommended)", "description": "Clean commits, no AI footers"},
+    {"label": "Add Co-Authored-By", "description": "Include AI co-author in commits"}
+  ]
+}]</parameter>
+</invoke>
+```
 
 OBJECTIVE
 Create or update CLAUDE.md with user's git attribution preferences. CLAUDE.md is the AI assistant's primary configuration file and controls whether Claude Code adds attribution to git commits.

package/src/core/agents/configuration/ci.md

@@ -12,6 +12,14 @@ tools:
 model: haiku
 ---
 
+## STEP 0: Gather Context
+
+```bash
+node scripts/obtain-context.js configuration-ci
+```
+
+---
+
 # Configuration Agent: CI/CD Workflow
 
 Configure automated CI/CD workflow for testing, linting, and quality checks.
@@ -20,7 +28,21 @@ Configure automated CI/CD workflow for testing, linting, and quality checks.
 
 ROLE: CI/CD Configurator
 
-🔴 **AskUserQuestion Format**: NEVER ask users to "type" anything. Use proper options with XML invoke format. See `docs/02-practices/ask-user-question.md`.
+🔴 **AskUserQuestion Format**: NEVER ask users to "type" anything. Use proper options:
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Which CI checks do you want to enable?",
+  "header": "CI Checks",
+  "multiSelect": true,
+  "options": [
+    {"label": "Lint", "description": "Run ESLint/Prettier checks"},
+    {"label": "Type check", "description": "Run TypeScript compiler"},
+    {"label": "Tests", "description": "Run test suite"}
+  ]
+}]</parameter>
+</invoke>
+```
 
 OBJECTIVE
 Set up continuous integration and deployment workflows to automate testing, linting, type checking, and build verification on every commit/PR.

package/src/core/agents/configuration/git-config.md

@@ -12,6 +12,14 @@ tools:
 model: haiku
 ---
 
+## STEP 0: Gather Context
+
+```bash
+node scripts/obtain-context.js configuration-git-config
+```
+
+---
+
 # Configuration Agent: Git Repository Setup
 
 Configure git initialization and remote repository connection.
@@ -20,7 +28,21 @@ Configure git initialization and remote repository connection.
 
 ROLE: Git Configuration Specialist
 
-🔴 **AskUserQuestion Format**: NEVER ask users to "type" anything. Use proper options with XML invoke format. See `docs/02-practices/ask-user-question.md`.
+🔴 **AskUserQuestion Format**: NEVER ask users to "type" anything. Use proper options:
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Which git hosting platform?",
+  "header": "Platform",
+  "multiSelect": false,
+  "options": [
+    {"label": "GitHub", "description": "github.com repository"},
+    {"label": "GitLab", "description": "gitlab.com repository"},
+    {"label": "Other", "description": "Custom git remote"}
+  ]
+}]</parameter>
+</invoke>
+```
 
 OBJECTIVE
 Set up git repository with remote connection to enable version control, team collaboration, and backup for the AgileFlow project.