agileflow 2.43.0 → 2.44.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agileflow",
-  "version": "2.43.0",
+  "version": "2.44.0",
   "description": "AI-driven agile development system for Claude Code, Cursor, Windsurf, and more",
   "keywords": [
     "agile",
@@ -31,6 +31,7 @@
   "files": [
     "tools/",
     "src/",
+    "scripts/",
     "LICENSE",
     "README.md"
   ],

package/scripts/generate-all.sh

@@ -0,0 +1,77 @@
+#!/bin/bash
+
+###############################################################################
+# AgileFlow Content Generation Script
+#
+# Regenerates all dynamic content in AgileFlow plugin files.
+# Run this after:
+# - Adding/removing/renaming commands
+# - Adding/removing/renaming agents
+# - Adding/removing/renaming skills
+# - Changing command/agent/skill descriptions or metadata
+#
+# Usage:
+#   bash scripts/generate-all.sh
+#   npm run generate  (if added to package.json)
+###############################################################################
+
+set -e  # Exit on error
+
+# Get script directory
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+GENERATORS_DIR="$SCRIPT_DIR/generators"
+
+# Colors for output
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+NC='\033[0m' # No Color
+
+echo -e "${BLUE}============================================================${NC}"
+echo -e "${BLUE}  AgileFlow Content Generation System${NC}"
+echo -e "${BLUE}============================================================${NC}"
+echo ""
+
+# Check if Node.js is available
+if ! command -v node &> /dev/null; then
+    echo -e "${RED}❌ Error: Node.js is not installed or not in PATH${NC}"
+    exit 1
+fi
+
+# Check if generators directory exists
+if [ ! -d "$GENERATORS_DIR" ]; then
+    echo -e "${RED}❌ Error: Generators directory not found: $GENERATORS_DIR${NC}"
+    exit 1
+fi
+
+# Run the orchestrator
+echo -e "${YELLOW}Running content generators...${NC}"
+echo ""
+
+cd "$GENERATORS_DIR"
+node index.js
+
+EXIT_CODE=$?
+
+if [ $EXIT_CODE -eq 0 ]; then
+    echo ""
+    echo -e "${GREEN}============================================================${NC}"
+    echo -e "${GREEN}✅ Content generation completed successfully!${NC}"
+    echo -e "${GREEN}============================================================${NC}"
+    echo ""
+    echo -e "${YELLOW}Next steps:${NC}"
+    echo "1. Review the changes: git diff"
+    echo "2. Test the plugin to ensure everything works"
+    echo "3. Commit the generated content: git add -A && git commit -m 'chore: regenerate plugin content'"
+    echo ""
+else
+    echo ""
+    echo -e "${RED}============================================================${NC}"
+    echo -e "${RED}❌ Content generation failed${NC}"
+    echo -e "${RED}============================================================${NC}"
+    echo ""
+    echo -e "${YELLOW}Please check the errors above and fix any issues.${NC}"
+    echo ""
+    exit 1
+fi

package/scripts/generators/agent-registry.js

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+
+/**
+ * Agent Registry Scanner
+ *
+ * Scans agents/ directory and extracts metadata from frontmatter.
+ * Returns structured agent registry for use in generators.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Extract YAML frontmatter from markdown file
+ * Handles multi-line values like tools arrays
+ * @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');
+  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;
+      }
+    }
+  }
+
+  return frontmatter;
+}
+
+/**
+ * Categorize agent based on its role
+ * @param {string} name - Agent name
+ * @param {string} description - Agent description
+ * @returns {string} Category name
+ */
+function categorizeAgent(name, description) {
+  const categories = {
+    'Core Development': ['ui', 'api', 'database', 'devops', 'ci'],
+    'Specialized Development': ['mobile', 'integrations', 'datamigration'],
+    'Quality & Testing': ['qa', 'testing', 'security', 'accessibility'],
+    'Architecture & Design': ['design', 'adr-writer', 'epic-planner', 'product'],
+    'Maintenance & Optimization': ['refactor', 'performance', 'monitoring'],
+    'Documentation & Knowledge': ['documentation', 'readme-updater', 'research'],
+    'Compliance & Governance': ['compliance', 'analytics'],
+    'Mentorship': ['mentor']
+  };
+
+  for (const [category, keywords] of Object.entries(categories)) {
+    if (keywords.some(kw => name.includes(kw))) {
+      return category;
+    }
+  }
+
+  return 'Other';
+}
+
+/**
+ * Scan agents directory and build registry
+ * @param {string} agentsDir - Path to agents directory
+ * @returns {Array} Array of agent metadata objects
+ */
+function scanAgents(agentsDir) {
+  const agents = [];
+  const files = fs.readdirSync(agentsDir);
+
+  for (const file of files) {
+    if (!file.endsWith('.md')) 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());
+      }
+    }
+
+    agents.push({
+      name,
+      file,
+      path: filePath,
+      displayName: frontmatter.name || name,
+      description: frontmatter.description || '',
+      tools,
+      model: frontmatter.model || 'haiku',
+      color: frontmatter.color || 'blue',
+      category: categorizeAgent(name, frontmatter.description || '')
+    });
+  }
+
+  // Sort by category, then by name
+  agents.sort((a, b) => {
+    if (a.category !== b.category) {
+      return a.category.localeCompare(b.category);
+    }
+    return a.name.localeCompare(b.name);
+  });
+
+  return agents;
+}
+
+/**
+ * Main function
+ */
+function main() {
+  const rootDir = path.resolve(__dirname, '../..');
+  const agentsDir = path.join(rootDir, 'src/core/agents');
+
+  if (!fs.existsSync(agentsDir)) {
+    console.error(`Agents directory not found: ${agentsDir}`);
+    process.exit(1);
+  }
+
+  const agents = scanAgents(agentsDir);
+
+  // If called directly, output JSON
+  if (require.main === module) {
+    console.log(JSON.stringify(agents, null, 2));
+  }
+
+  return agents;
+}
+
+// Export for use in other scripts
+module.exports = { scanAgents, extractFrontmatter, categorizeAgent };
+
+// Run if called directly
+if (require.main === module) {
+  main();
+}

package/scripts/generators/command-registry.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+
+/**
+ * Command Registry Scanner
+ *
+ * Scans commands/ directory and extracts metadata from frontmatter.
+ * Returns structured command registry for use in generators.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Extract 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 command based on its name/description
+ * @param {string} name - Command name
+ * @param {string} description - Command description
+ * @returns {string} Category name
+ */
+function categorizeCommand(name, description) {
+  const categories = {
+    'Story Management': ['story', 'epic', 'assign', 'status'],
+    'Development': ['verify', 'baseline', 'resume', 'session-init', 'babysit'],
+    'Quality & Testing': ['tests', 'review', 'ci'],
+    'Documentation': ['docs', 'adr', 'readme-sync'],
+    'Planning & Metrics': ['sprint', 'velocity', 'metrics', 'board', 'deps'],
+    'Research & Strategy': ['research', 'product'],
+    'Deployment & Operations': ['deploy', 'packages'],
+    'Collaboration': ['update', 'handoff', 'feedback', 'retro'],
+    'Maintenance': ['debt', 'compress', 'template'],
+    'System': ['setup', 'help', 'diagnose', 'auto', 'agent']
+  };
+
+  for (const [category, keywords] of Object.entries(categories)) {
+    if (keywords.some(kw => name.includes(kw))) {
+      return category;
+    }
+  }
+
+  return 'Other';
+}
+
+/**
+ * Scan commands directory and build registry
+ * @param {string} commandsDir - Path to commands directory
+ * @returns {Array} Array of command metadata objects
+ */
+function scanCommands(commandsDir) {
+  const commands = [];
+  const files = fs.readdirSync(commandsDir);
+
+  for (const file of files) {
+    if (!file.endsWith('.md')) continue;
+
+    const filePath = path.join(commandsDir, file);
+    const frontmatter = extractFrontmatter(filePath);
+    const name = file.replace('.md', '');
+
+    commands.push({
+      name,
+      file,
+      path: filePath,
+      description: frontmatter.description || '',
+      argumentHint: frontmatter['argument-hint'] || '',
+      category: categorizeCommand(name, frontmatter.description || '')
+    });
+  }
+
+  // Sort by category, then by name
+  commands.sort((a, b) => {
+    if (a.category !== b.category) {
+      return a.category.localeCompare(b.category);
+    }
+    return a.name.localeCompare(b.name);
+  });
+
+  return commands;
+}
+
+/**
+ * Main function
+ */
+function main() {
+  const rootDir = path.resolve(__dirname, '../..');
+  const commandsDir = path.join(rootDir, 'src/core/commands');
+
+  if (!fs.existsSync(commandsDir)) {
+    console.error(`Commands directory not found: ${commandsDir}`);
+    process.exit(1);
+  }
+
+  const commands = scanCommands(commandsDir);
+
+  // If called directly, output JSON
+  if (require.main === module) {
+    console.log(JSON.stringify(commands, null, 2));
+  }
+
+  return commands;
+}
+
+// Export for use in other scripts
+module.exports = { scanCommands, extractFrontmatter, categorizeCommand };
+
+// Run if called directly
+if (require.main === module) {
+  main();
+}

package/scripts/generators/index.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+
+/**
+ * Content Generation Orchestrator
+ *
+ * Runs all content generators to update AgileFlow plugin files.
+ * Single source of truth: frontmatter and directory structure.
+ */
+
+const path = require('path');
+const { execSync } = require('child_process');
+
+/**
+ * Run a generator script
+ * @param {string} scriptName - Name of the generator script
+ * @returns {boolean} Success status
+ */
+function runGenerator(scriptName) {
+  const scriptPath = path.join(__dirname, scriptName);
+
+  console.log(`\n${'='.repeat(60)}`);
+  console.log(`Running: ${scriptName}`);
+  console.log('='.repeat(60));
+
+  try {
+    execSync(`node "${scriptPath}"`, {
+      cwd: __dirname,
+      stdio: 'inherit'
+    });
+    console.log(`✅ ${scriptName} completed successfully`);
+    return true;
+  } catch (error) {
+    console.error(`❌ ${scriptName} failed:`, error.message);
+    return false;
+  }
+}
+
+/**
+ * Main orchestrator
+ */
+function main() {
+  console.log('🚀 AgileFlow Content Generation System');
+  console.log('Generating content from metadata...\n');
+
+  const generators = [
+    'inject-help.js',
+    'inject-babysit.js',
+    'inject-readme.js'
+  ];
+
+  const results = [];
+
+  for (const generator of generators) {
+    const success = runGenerator(generator);
+    results.push({ generator, success });
+  }
+
+  // Summary
+  console.log(`\n${'='.repeat(60)}`);
+  console.log('GENERATION SUMMARY');
+  console.log('='.repeat(60));
+
+  let allSuccess = true;
+  for (const { generator, success } of results) {
+    const status = success ? '✅' : '❌';
+    console.log(`${status} ${generator}`);
+    if (!success) allSuccess = false;
+  }
+
+  console.log('');
+
+  if (allSuccess) {
+    console.log('🎉 All generators completed successfully!');
+    console.log('📝 Generated content is ready for commit.');
+    process.exit(0);
+  } else {
+    console.log('⚠️  Some generators failed. Please check errors above.');
+    process.exit(1);
+  }
+}
+
+// Run if called directly
+if (require.main === module) {
+  main();
+}
+
+module.exports = { runGenerator };

package/scripts/generators/inject-babysit.js

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+
+/**
+ * Babysit Command Content Injector
+ *
+ * Injects agent list and command references into /agileflow:babysit command file.
+ * Handles multiple AUTOGEN sections.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { scanAgents } = require('./agent-registry');
+const { scanCommands } = require('./command-registry');
+
+/**
+ * Generate agent list content with details
+ * @param {Array} agents - Array of agent metadata
+ * @returns {string} Formatted agent list
+ */
+function generateAgentList(agents) {
+  const lines = [];
+
+  lines.push(`**AVAILABLE AGENTS** (${agents.length} total):`);
+  lines.push('');
+
+  let count = 1;
+  for (const agent of agents) {
+    lines.push(`${count}. **${agent.name}** (model: ${agent.model})`);
+    lines.push(`   - **Purpose**: ${agent.description}`);
+    lines.push(`   - **Tools**: ${agent.tools.join(', ')}`);
+    lines.push(`   - **Category**: ${agent.category}`);
+    lines.push('');
+    count++;
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Generate command reference list (compact format for babysit)
+ * @param {Array} commands - Array of command metadata
+ * @returns {string} Formatted command list
+ */
+function generateCommandReference(commands) {
+  const lines = [];
+
+  // Group by category
+  const categories = {};
+  for (const cmd of commands) {
+    if (!categories[cmd.category]) {
+      categories[cmd.category] = [];
+    }
+    categories[cmd.category].push(cmd);
+  }
+
+  for (const [category, cmds] of Object.entries(categories)) {
+    const cmdNames = cmds.map(c => c.name).join(', ');
+    lines.push(`- **${category}**: ${cmdNames}`);
+  }
+
+  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., AGENT_LIST, COMMAND_REF)
+ * @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);
+}
+
+/**
+ * Add AUTOGEN markers to babysit file if they don't exist
+ * @param {string} content - Original file content
+ * @returns {string} Updated content with markers
+ */
+function addMarkersIfMissing(content) {
+  let updated = content;
+
+  // Add AGENT_LIST markers around the agent list section
+  if (!content.includes('<!-- AUTOGEN:AGENT_LIST:START -->')) {
+    // Find "**AVAILABLE AGENTS**" and wrap it
+    const agentSectionStart = content.indexOf('**AVAILABLE AGENTS**');
+    if (agentSectionStart !== -1) {
+      // Find the end of the agent list (before "**WHEN TO SPAWN AGENTS**")
+      const agentSectionEnd = content.indexOf('**WHEN TO SPAWN AGENTS**', agentSectionStart);
+      if (agentSectionEnd !== -1) {
+        const before = content.substring(0, agentSectionStart);
+        const agentSection = content.substring(agentSectionStart, agentSectionEnd);
+        const after = content.substring(agentSectionEnd);
+
+        updated = `${before}<!-- AUTOGEN:AGENT_LIST:START -->\n${agentSection}<!-- AUTOGEN:AGENT_LIST:END -->\n\n${after}`;
+        console.log('✅ Added AGENT_LIST markers to babysit.md');
+      }
+    }
+  }
+
+  return updated;
+}
+
+/**
+ * Main function
+ */
+function main() {
+  const rootDir = path.resolve(__dirname, '../..');
+  const babysitFile = path.join(rootDir, 'src/core/commands/babysit.md');
+  const agentsDir = path.join(rootDir, 'src/core/agents');
+  const commandsDir = path.join(rootDir, 'src/core/commands');
+
+  // Check if babysit file exists
+  if (!fs.existsSync(babysitFile)) {
+    console.error(`Babysit file not found: ${babysitFile}`);
+    process.exit(1);
+  }
+
+  // Scan agents and commands
+  console.log('Scanning agents...');
+  const agents = scanAgents(agentsDir);
+  console.log(`Found ${agents.length} agents`);
+
+  console.log('Scanning commands...');
+  const commands = scanCommands(commandsDir);
+  console.log(`Found ${commands.length} commands`);
+
+  // Read babysit file
+  let babysitContent = fs.readFileSync(babysitFile, 'utf-8');
+
+  // Add markers if missing
+  babysitContent = addMarkersIfMissing(babysitContent);
+
+  // Generate content
+  console.log('Generating agent list...');
+  const agentList = generateAgentList(agents);
+
+  // Inject content
+  console.log('Injecting content into babysit.md...');
+  babysitContent = injectContentByMarker(babysitContent, 'AGENT_LIST', agentList);
+
+  // Write back
+  fs.writeFileSync(babysitFile, babysitContent, 'utf-8');
+  console.log('✅ Successfully updated babysit.md');
+}
+
+// Export for use in orchestrator
+module.exports = { generateAgentList, generateCommandReference, injectContentByMarker, addMarkersIfMissing };
+
+// Run if called directly
+if (require.main === module) {
+  main();
+}

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/commands/context.md

@@ -1,6 +1,6 @@
 ---
 description: Generate context export for web AI tools
-argument-hint: [MODE=full|export|note|research] [NOTE=<text>] [TOPIC=<text>] [DETAILS=<text>]
+argument-hint: [MODE=full|export|note|research|import] [NOTE=<text>] [TOPIC=<text>] [DETAILS=<text>] [CONTENT=<text>] [SOURCE=<url>]
 ---
 
 <!-- COMPACT_SUMMARY_START
@@ -12,11 +12,12 @@ This section is extracted by the PreCompact hook to preserve essential context a
 Web AI Context Manager - Generates/exports/manages project context briefs for web AI tools (ChatGPT, Perplexity, Gemini, Claude web).
 
 ### Critical Behavioral Rules
-- **ALWAYS create TodoWrite list** for MODE=full and MODE=research to track multi-step workflows
+- **ALWAYS create TodoWrite list** for MODE=full, MODE=research, and MODE=import to track multi-step workflows
 - **Diff-first approach**: Show changes and wait for YES/NO confirmation before ANY file writes
 - **Preserve user-written content**: Only update managed sections in docs/context.md
 - **No writes in export mode**: MODE=export outputs text only, never writes files
 - **Research is two-step**: STEP 1 generates prompt, STEP 2 stores results when user returns
+- **Import is one-step**: Process CONTENT immediately and create research file
 - **Link research files**: Always reference research from ADRs/Epics/Stories that use it
 
 ### Core Workflow
@@ -50,6 +51,16 @@ Web AI Context Manager - Generates/exports/manages project context briefs for we
 7. Ask if user wants ADR/Epic/Story created from research
 8. Add research reference to created ADR/Epic/Story
 
+**MODE=import**
+1. Create todo list tracking: validate inputs, process content, extract key points, extract code, generate actions, suggest stories, format research file, save, update index
+2. Validate TOPIC and CONTENT are provided
+3. Process raw content (transcript, article, etc.) by: summarizing key points, extracting code snippets, generating action items, suggesting user stories
+4. Format into structured research file with all extracted sections
+5. Save to docs/10-research/YYYYMMDD-topic-slug.md
+6. Update docs/10-research/README.md index
+7. Ask if user wants ADR/Epic/Story created from imported content
+8. Add research reference to created ADR/Epic/Story
+
 ### Key Files
 - docs/context.md - Main context brief (managed sections + user content)
 - docs/10-research/YYYYMMDD-topic-slug.md - Research results storage
@@ -68,9 +79,11 @@ Generate, export, or manage the web AI context brief.
 ROLE: Web AI Context Manager
 
 INPUTS (optional)
-- MODE=full|export|note|research (default: full)
+- MODE=full|export|note|research|import (default: full)
 - NOTE=<text> (required if MODE=note)
-- TOPIC=<text> (required if MODE=research)
+- TOPIC=<text> (required if MODE=research or MODE=import)
+- CONTENT=<text> (required if MODE=import - raw content to process)
+- SOURCE=<url> (optional for MODE=import - original source URL)
 
 ---
 
@@ -249,6 +262,124 @@ When user pastes research results back:
 
 ---
 
+## MODE=import
+Import raw content (transcripts, articles, notes) and convert to structured research file.
+
+### Input
+- TOPIC=<text> (required - name for the research file)
+- CONTENT=<text> (required - raw content to process: transcript, article, notes, etc.)
+- SOURCE=<url> (optional - original source URL for reference)
+
+### Use Cases
+- YouTube video transcripts
+- Conference talk notes
+- Podcast transcripts
+- Blog posts / articles
+- Documentation pages
+- Forum discussions / Stack Overflow threads
+- Meeting notes
+
+### TODO LIST TRACKING
+**CRITICAL**: Immediately create a todo list using TodoWrite tool to track import workflow:
+```
+1. Validate TOPIC and CONTENT are provided
+2. Analyze and summarize key points from content
+3. Extract any code snippets
+4. Generate action items based on content
+5. Create user story suggestions (if applicable)
+6. Format into structured research markdown
+7. Show diff for review
+8. Save to docs/10-research/YYYYMMDD-topic-slug.md
+9. Update docs/10-research/README.md index
+10. Ask about creating ADR/Epic/Story from research
+```
+
+Mark each step complete as you finish it.
+
+### Processing Steps
+
+1. **Validate Inputs**
+   - Verify TOPIC is provided (error if missing)
+   - Verify CONTENT is provided (error if missing)
+   - SOURCE is optional but recommended for attribution
+
+2. **Analyze Content**
+   Extract from the raw content:
+   - **Summary**: 2-3 paragraph TL;DR of the main points
+   - **Key Findings**: Bullet list of important takeaways
+   - **Code Snippets**: Any code blocks, commands, or configuration (preserve exactly)
+   - **Action Items**: Concrete next steps mentioned or implied
+   - **Story Suggestions**: Potential user stories/epics based on content
+
+3. **Format Research File**
+   ```markdown
+   # [Topic Title]
+
+   **Import Date**: YYYY-MM-DD
+   **Topic**: [original topic]
+   **Source**: [URL if provided, or "Direct import"]
+   **Content Type**: [transcript/article/notes/etc.]
+
+   ## Summary
+   [2-3 paragraph executive summary of the content]
+
+   ## Key Findings
+   - [Main point 1 with details]
+   - [Main point 2 with details]
+   - [Main point 3 with details]
+   - ...
+
+   ## Code Snippets
+   [Preserve all code snippets exactly as they appeared]
+   ```language
+   [code here]
+   ```
+
+   ## Action Items
+   - [ ] [Action 1 - concrete next step]
+   - [ ] [Action 2 - concrete next step]
+   - [ ] [Action 3 - concrete next step]
+
+   ## Story Suggestions
+   [If content suggests feature work, list potential stories]
+
+   ### Potential Epic: [Epic Title]
+   - **US-XXXX**: [Story 1 title]
+     - AC: [acceptance criteria bullet]
+   - **US-XXXX**: [Story 2 title]
+     - AC: [acceptance criteria bullet]
+
+   ## Raw Content Reference
+   <details>
+   <summary>Original content (click to expand)</summary>
+
+   [First 500 chars of original content for reference...]
+   </details>
+
+   ## References
+   - Source: [URL or "Direct import"]
+   - Import date: [YYYY-MM-DD]
+   ```
+
+4. **Save and Index**
+   - Save to `docs/10-research/YYYYMMDD-<topic-slug>.md`
+   - Update `docs/10-research/README.md` with new entry
+
+5. **Offer Next Steps**
+   Ask user via AskUserQuestion:
+   - Create an ADR referencing this research?
+   - Create an Epic/Stories based on the story suggestions?
+   - Link this research to an existing Epic/Story?
+
+### Rules
+- Diff-first; YES/NO before writing research file
+- Preserve ALL code snippets exactly as provided
+- Generate actionable items (not vague suggestions)
+- Keep raw content reference collapsed to save space
+- Always update the research index
+
+---
+
 ## Usage Examples
 
 ```bash
@@ -262,9 +393,13 @@ When user pastes research results back:
 # Add a quick note
 /agileflow:context MODE=note NOTE="User reported auth bug in production"
 
-# Build research prompt
+# Build research prompt for web AI
 /agileflow:context MODE=research TOPIC="Implement OAuth 2.0 with Google"
 /agileflow:context MODE=research TOPIC="Add Stripe payments" DETAILS="Launch by end of sprint"
+
+# Import external content (transcripts, articles, notes)
+/agileflow:context MODE=import TOPIC="React Server Components" CONTENT="[paste transcript here]"
+/agileflow:context MODE=import TOPIC="Stripe Webhooks Tutorial" SOURCE="https://youtube.com/..." CONTENT="[paste transcript here]"
 ```
 
 ---
@@ -276,3 +411,4 @@ Depending on MODE:
 - **export**: Text output ready to paste into web AI tool
 - **note**: Appended note to docs/context.md (after YES confirmation)
 - **research**: Research prompt in code block ready to paste into web AI tool
+- **import**: Processed research file saved to docs/10-research/ (after YES confirmation)