wogiflow 1.0.0

package/scripts/flow-skill-generator.js

@@ -0,0 +1,1046 @@
+#!/usr/bin/env node
+
+/**
+ * Skill Generator for Wogi Flow
+ * Fetches documentation via Context7 MCP and generates skill files
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Import helper functions from tech options
+let _techOptions = null;
+function getTechOptions() {
+  if (!_techOptions) {
+    try {
+      _techOptions = require('./flow-tech-options');
+    } catch (err) {
+      _techOptions = { getSkillType: () => 'library', getParentFramework: () => null };
+    }
+  }
+  return _techOptions;
+}
+
+// Lazy-load to avoid circular dependency
+let _syncDecisionsToRules = null;
+function syncDecisionsToRules() {
+  if (!_syncDecisionsToRules) {
+    _syncDecisionsToRules = require('./flow-rules-sync').syncDecisionsToRules;
+  }
+  return _syncDecisionsToRules();
+}
+
+// ============================================
+// CONFIGURATION
+// ============================================
+
+const SKILL_TOPICS = {
+  patterns: 'best practices common patterns',
+  antiPatterns: 'common mistakes anti-patterns pitfalls',
+  conventions: 'coding conventions style guide',
+  gettingStarted: 'getting started setup installation'
+};
+
+// Technology-specific keywords for better doc extraction
+const TECH_KEYWORDS = {
+  nextjs: ['app router', 'server components', 'server actions', 'middleware', 'api routes'],
+  react: ['hooks', 'context', 'suspense', 'concurrent', 'server components'],
+  tailwind: ['utility classes', 'responsive', 'dark mode', 'configuration'],
+  prisma: ['schema', 'migrations', 'queries', 'relations', 'transactions'],
+  nestjs: ['modules', 'controllers', 'providers', 'guards', 'interceptors'],
+  fastapi: ['routes', 'dependencies', 'pydantic', 'async', 'middleware'],
+  vue: ['composition api', 'reactivity', 'components', 'directives'],
+  svelte: ['stores', 'actions', 'transitions', 'ssr']
+};
+
+// ============================================
+// CONTEXT7 MCP INTEGRATION
+// ============================================
+
+/**
+ * This function is designed to work with Claude Code's MCP infrastructure.
+ * When run directly, it outputs instructions for manual Context7 fetching.
+ * When used via Claude, Claude should call Context7 MCP tools directly.
+ */
+async function fetchDocsViaContext7(technology) {
+  // When run via Claude, return null to signal Claude should use MCP
+  if (process.env.WOGI_MCP_MODE === 'true') {
+    return null; // Claude will use resolve-library-id + get-library-docs
+  }
+
+  // When run directly, we can't call MCP - output instructions
+  console.log(`\n  📚 Need to fetch docs for: ${technology.label}`);
+  console.log(`     Context7 ID: ${technology.context7}`);
+
+  return {
+    technology: technology.value,
+    context7Id: technology.context7,
+    needsMCPFetch: true
+  };
+}
+
+// ============================================
+// SKILL FILE GENERATION
+// ============================================
+
+function generateSkillMd(tech, docs) {
+  const date = new Date().toISOString().split('T')[0];
+
+  return `---
+name: ${tech.value}
+version: 1.0
+context7: ${tech.context7 || 'null'}
+generated: ${new Date().toISOString()}
+learningCount: 0
+successRate: null
+---
+
+# ${tech.label} Skill
+
+**Version**: Auto-generated ${date}
+**Context7 ID**: ${tech.context7 || 'N/A'}
+
+## Overview
+
+This skill provides patterns and conventions for ${tech.label} development.
+${docs?.overview || `Patterns extracted from ${tech.label} documentation.`}
+
+## When to Apply
+
+Apply this skill when:
+- Working on files related to ${tech.label}
+- Creating new ${tech.label} components/modules
+- Reviewing ${tech.label} code
+
+## Key Patterns
+
+See \`knowledge/patterns.md\` for detailed patterns.
+
+## Anti-Patterns to Avoid
+
+See \`knowledge/anti-patterns.md\` for common mistakes.
+
+## Conventions
+
+See \`rules/conventions.md\` for coding standards.
+
+---
+*Auto-generated by Wogi Flow Tech Stack Wizard*
+`;
+}
+
+function generatePatternsMd(tech, docs) {
+  const keywords = TECH_KEYWORDS[tech.value] || [];
+  const keywordsSection = keywords.length > 0
+    ? `\n## Key Concepts\n\n${keywords.map(k => `- ${k}`).join('\n')}\n`
+    : '';
+
+  return `# ${tech.label} Patterns
+
+Best practices and patterns for ${tech.label} development.
+${keywordsSection}
+## Patterns
+
+${docs?.patterns || `### Pattern 1: [To be populated]
+
+When fetching documentation via Context7, patterns will be extracted automatically.
+
+### Pattern 2: [To be populated]
+
+Run \`/wogi-setup-stack --regenerate\` after documentation is fetched.
+`}
+
+## Examples
+
+${docs?.examples || `Examples will be populated from documentation.`}
+
+---
+*Auto-generated - will be enhanced with Context7 documentation*
+`;
+}
+
+function generateAntiPatternsMd(tech, docs) {
+  return `# ${tech.label} Anti-Patterns
+
+Common mistakes and pitfalls to avoid with ${tech.label}.
+
+## Anti-Patterns
+
+${docs?.antiPatterns || `### Anti-Pattern 1: [To be populated]
+
+Anti-patterns will be extracted from ${tech.label} documentation.
+
+### Anti-Pattern 2: [To be populated]
+
+Common mistakes identified in documentation and community discussions.
+`}
+
+## Why to Avoid
+
+${docs?.whyAvoid || `Each anti-pattern includes reasoning for why it should be avoided.`}
+
+---
+*Auto-generated - will be enhanced with Context7 documentation*
+`;
+}
+
+function generateConventionsMd(tech, docs) {
+  return `# ${tech.label} Conventions
+
+Coding standards and conventions for ${tech.label}.
+
+## Naming Conventions
+
+${docs?.naming || `- Follow ${tech.label} community conventions
+- Use consistent naming across the codebase`}
+
+## File Structure
+
+${docs?.fileStructure || `Follow the recommended ${tech.label} project structure.`}
+
+## Code Style
+
+${docs?.codeStyle || `- Follow official ${tech.label} style guide
+- Use linting tools where available`}
+
+---
+*Auto-generated - will be enhanced with Context7 documentation*
+`;
+}
+
+// ============================================
+// HUB-SPOKE SKILL GENERATION
+// ============================================
+
+/**
+ * Generate ecosystem link file for a hub skill
+ * These files link to related spoke skills for token efficiency
+ */
+function generateEcosystemLinkMd(category, relatedSkills, parentFramework) {
+  const categoryLabels = {
+    stateManagement: 'State Management',
+    forms: 'Form Handling',
+    styling: 'Styling',
+    dataFetching: 'Data Fetching',
+    animation: 'Animation',
+    validation: 'Validation',
+    orm: 'ORM / Database',
+    auth: 'Authentication'
+  };
+
+  const label = categoryLabels[category] || category;
+  const skillLinks = relatedSkills.map(s => `- \`../${s}/skill.md\``).join('\n');
+
+  return `# ${label} for ${parentFramework}
+
+This is an ecosystem link file. For ${label.toLowerCase()} patterns, see the dedicated skill:
+
+${skillLinks || '- No specific skill configured yet'}
+
+## Quick Reference
+
+When working with ${label.toLowerCase()} in ${parentFramework}:
+1. Load the appropriate skill from the list above
+2. Follow patterns in that skill's \`knowledge/patterns.md\`
+3. Avoid anti-patterns in \`knowledge/anti-patterns.md\`
+
+---
+*This is a link file - see referenced skills for detailed patterns*
+`;
+}
+
+/**
+ * Generate skill.md for a hub (framework) skill
+ */
+function generateHubSkillMd(tech, docs, ecosystemSkills) {
+  const date = new Date().toISOString().split('T')[0];
+
+  const ecosystemSection = ecosystemSkills.length > 0
+    ? `## Ecosystem Skills
+
+This framework works with the following ecosystem skills (loaded on-demand):
+
+${ecosystemSkills.map(s => `- **${s.label}**: \`.claude/skills/${s.id}/\``).join('\n')}
+
+When you import or work with these libraries, load their dedicated skill for detailed patterns.
+`
+    : '';
+
+  return `---
+name: ${tech.value}
+version: 1.0
+type: framework
+context7: ${tech.context7 || 'null'}
+generated: ${new Date().toISOString()}
+learningCount: 0
+successRate: null
+---
+
+# ${tech.label} Skill
+
+**Version**: Auto-generated ${date}
+**Type**: Framework (Hub)
+**Context7 ID**: ${tech.context7 || 'N/A'}
+
+## Overview
+
+This is the main skill for ${tech.label} development. It contains core patterns and links to ecosystem skills.
+${docs?.overview || `Patterns extracted from ${tech.label} documentation.`}
+
+## When to Apply
+
+This skill is automatically loaded when:
+- Working on ${tech.label} files
+- Creating new ${tech.label} components/modules
+- Reviewing ${tech.label} code
+
+${ecosystemSection}
+## Core Patterns
+
+See \`knowledge/patterns.md\` for detailed ${tech.label} patterns.
+
+## Anti-Patterns to Avoid
+
+See \`knowledge/anti-patterns.md\` for common mistakes.
+
+## Conventions
+
+See \`rules/conventions.md\` for coding standards.
+
+---
+*Auto-generated by Wogi Flow Tech Stack Wizard*
+`;
+}
+
+/**
+ * Generate skill.md for a spoke (library) skill
+ */
+function generateSpokeSkillMd(tech, docs, parentFramework) {
+  const date = new Date().toISOString().split('T')[0];
+
+  const parentSection = parentFramework
+    ? `## Parent Framework
+
+This skill is part of the **${parentFramework}** ecosystem. See \`.claude/skills/${parentFramework}/\` for framework-level patterns.
+`
+    : '';
+
+  return `---
+name: ${tech.value}
+version: 1.0
+type: library
+context7: ${tech.context7 || 'null'}
+parentFramework: ${parentFramework || 'null'}
+generated: ${new Date().toISOString()}
+learningCount: 0
+successRate: null
+---
+
+# ${tech.label} Skill
+
+**Version**: Auto-generated ${date}
+**Type**: Library (Spoke)
+**Context7 ID**: ${tech.context7 || 'N/A'}
+
+## Overview
+
+This skill provides focused patterns for ${tech.label}.
+${docs?.overview || `Patterns extracted from ${tech.label} documentation.`}
+
+${parentSection}
+## When to Load
+
+This skill is loaded on-demand when:
+- File imports \`${tech.value}\` or related packages
+- Working on code that uses ${tech.label}
+- User explicitly asks about ${tech.label}
+
+## Patterns
+
+See \`knowledge/patterns.md\` for detailed patterns.
+
+## Anti-Patterns
+
+See \`knowledge/anti-patterns.md\` for common mistakes.
+
+---
+*Auto-generated by Wogi Flow Tech Stack Wizard*
+*This is a focused library skill - kept small for token efficiency*
+`;
+}
+
+// ============================================
+// SKILLS INDEX GENERATION (v2.0 Hub-Spoke)
+// ============================================
+
+/**
+ * Generate skills index with hub-spoke structure
+ * v2.0 format includes: type, ecosystem, loadWith, tokenCost
+ */
+function generateSkillsIndex(technologies, selections) {
+  const { getSkillType, getParentFramework, ECOSYSTEMS } = getTechOptions();
+  const skills = {};
+
+  // First pass: identify all technologies and their types
+  const techMap = new Map();
+  for (const tech of technologies) {
+    const skillId = tech.value.toLowerCase().replace(/[^a-z0-9]/g, '-');
+    const type = getSkillType(tech.value);
+    techMap.set(skillId, { tech, type });
+  }
+
+  // Second pass: build skill entries with relationships
+  for (const [skillId, { tech, type }] of techMap) {
+    const keywords = TECH_KEYWORDS[tech.value] || [];
+    const parentFramework = type === 'library' ? getParentFramework(tech.value, selections) : null;
+
+    // Find ecosystem members for framework skills
+    let ecosystem = [];
+    if (type === 'framework') {
+      for (const [otherId, other] of techMap) {
+        if (other.type === 'library') {
+          const otherParent = getParentFramework(other.tech.value, selections);
+          if (otherParent === tech.value) {
+            ecosystem.push(otherId);
+          }
+        }
+      }
+    }
+
+    // Determine loadWith - what skills should be loaded together
+    let loadWith = [];
+    if (type === 'framework' && ecosystem.length > 0) {
+      // Frameworks load with their most commonly used libraries
+      const defaultsToLoad = ['zustand', 'react-hook-form', 'tanstack-query', 'typeorm', 'passport'];
+      loadWith = ecosystem.filter(id => defaultsToLoad.some(d => id.includes(d)));
+    }
+
+    // Estimate token cost
+    const tokenCost = type === 'framework' ? 'medium' : 'low';
+
+    skills[skillId] = {
+      path: `.claude/skills/${skillId}/`,
+      label: tech.label,
+      context7: tech.context7,
+      type,
+      ecosystem: ecosystem.length > 0 ? ecosystem : undefined,
+      parentFramework: parentFramework || undefined,
+      loadWith: loadWith.length > 0 ? loadWith : undefined,
+      tokenCost,
+      covers: [tech.value, tech.label.toLowerCase(), ...keywords],
+      sections: {
+        overview: 'skill.md',
+        patterns: 'knowledge/patterns.md',
+        antiPatterns: 'knowledge/anti-patterns.md',
+        conventions: 'rules/conventions.md'
+      }
+    };
+  }
+
+  // Determine project stack from selections
+  const projectStack = technologies.map(t => t.value);
+
+  return {
+    version: '2.0',
+    generated: new Date().toISOString(),
+    projectType: selections.projectType,
+    focus: selections.focus,
+    loadingStrategy: {
+      framework: 'always',
+      library: 'on-demand'
+    },
+    skills,
+    projectStack
+  };
+}
+
+// ============================================
+// MIGRATION: skills/ -> .claude/skills/ (v2.1.0)
+// ============================================
+
+/**
+ * Migrate skills from old skills/ location to new .claude/skills/ location
+ * Called during skill generation to ensure consistency with Claude Code 2.1.0
+ */
+function migrateOldSkills(projectRoot) {
+  const oldSkillsDir = path.join(projectRoot, 'skills');
+  const newSkillsDir = path.join(projectRoot, '.claude', 'skills');
+
+  if (!fs.existsSync(oldSkillsDir)) {
+    return { migrated: [], skipped: [] };
+  }
+
+  const migrated = [];
+  const skipped = [];
+
+  try {
+    const entries = fs.readdirSync(oldSkillsDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      // Skip non-directories and special files
+      if (!entry.isDirectory()) {
+        // Handle skills-index.json specially
+        if (entry.name === 'skills-index.json') {
+          const oldPath = path.join(oldSkillsDir, entry.name);
+          const newPath = path.join(newSkillsDir, entry.name);
+
+          // Only migrate if new one doesn't exist
+          if (!fs.existsSync(newPath)) {
+            ensureDir(newSkillsDir);
+            fs.renameSync(oldPath, newPath);
+            migrated.push(`skills-index.json`);
+          } else {
+            fs.unlinkSync(oldPath);
+            skipped.push(`skills-index.json (newer exists in .claude/skills/)`);
+          }
+        }
+        continue;
+      }
+
+      const skillName = entry.name;
+      const oldSkillPath = path.join(oldSkillsDir, skillName);
+      const newSkillPath = path.join(newSkillsDir, skillName);
+
+      // Check if skill already exists in new location
+      if (fs.existsSync(newSkillPath)) {
+        // Skill exists in both places - keep new, remove old
+        fs.rmSync(oldSkillPath, { recursive: true, force: true });
+        skipped.push(`${skillName} (already in .claude/skills/)`);
+      } else {
+        // Move skill to new location
+        ensureDir(newSkillsDir);
+        fs.renameSync(oldSkillPath, newSkillPath);
+        migrated.push(skillName);
+      }
+    }
+
+    // Clean up empty skills/ directory
+    const remainingEntries = fs.readdirSync(oldSkillsDir);
+    if (remainingEntries.length === 0) {
+      fs.rmdirSync(oldSkillsDir);
+    }
+
+  } catch (error) {
+    console.warn(`  Warning: Could not migrate old skills: ${error.message}`);
+  }
+
+  return { migrated, skipped };
+}
+
+// ============================================
+// FILE WRITING
+// ============================================
+
+function ensureDir(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+/**
+ * Write skill files with hub-spoke awareness
+ * @param {Object} tech - Technology definition
+ * @param {Object} docs - Documentation content (optional)
+ * @param {string} projectRoot - Project root path
+ * @param {Object} skillContext - Additional context { type, parentFramework, ecosystemSkills }
+ */
+async function writeSkillFiles(tech, docs, projectRoot, skillContext = {}) {
+  const { getSkillType, getParentFramework } = getTechOptions();
+
+  const skillId = tech.value.toLowerCase().replace(/[^a-z0-9]/g, '-');
+  const skillDir = path.join(projectRoot, '.claude', 'skills', skillId);
+  const type = skillContext.type || getSkillType(tech.value);
+  const parentFramework = skillContext.parentFramework || null;
+  const ecosystemSkills = skillContext.ecosystemSkills || [];
+
+  // Create directory structure
+  ensureDir(skillDir);
+  ensureDir(path.join(skillDir, 'knowledge'));
+  ensureDir(path.join(skillDir, 'rules'));
+
+  // Framework (hub) skills get an ecosystem/ directory for link files
+  if (type === 'framework') {
+    ensureDir(path.join(skillDir, 'ecosystem'));
+    ensureDir(path.join(skillDir, 'templates'));
+  }
+
+  // Generate appropriate skill.md based on type
+  const skillMdContent = type === 'framework'
+    ? generateHubSkillMd(tech, docs, ecosystemSkills)
+    : generateSpokeSkillMd(tech, docs, parentFramework);
+
+  // Core files for all skills
+  const files = [
+    { path: 'skill.md', content: skillMdContent },
+    { path: 'knowledge/patterns.md', content: generatePatternsMd(tech, docs) },
+    { path: 'knowledge/anti-patterns.md', content: generateAntiPatternsMd(tech, docs) },
+    { path: 'knowledge/learnings.md', content: `# ${tech.label} Learnings\n\n*Empty - will be populated as you provide feedback during development.*\n` }
+  ];
+
+  // Framework skills get conventions, library skills are kept minimal
+  if (type === 'framework') {
+    files.push({ path: 'rules/conventions.md', content: generateConventionsMd(tech, docs) });
+  }
+
+  // Write all files
+  for (const file of files) {
+    const filePath = path.join(skillDir, file.path);
+    fs.writeFileSync(filePath, file.content, 'utf8');
+  }
+
+  return { skillDir, type, skillId };
+}
+
+/**
+ * Write ecosystem link files for a framework skill
+ */
+async function writeEcosystemLinks(frameworkId, ecosystemCategories, projectRoot) {
+  const ecosystemDir = path.join(projectRoot, '.claude', 'skills', frameworkId, 'ecosystem');
+  ensureDir(ecosystemDir);
+
+  for (const [category, relatedSkills] of Object.entries(ecosystemCategories)) {
+    if (relatedSkills.length > 0) {
+      const content = generateEcosystemLinkMd(category, relatedSkills, frameworkId);
+      const filePath = path.join(ecosystemDir, `${category}.md`);
+      fs.writeFileSync(filePath, content, 'utf8');
+    }
+  }
+}
+
+function updateDecisionsMd(selections, technologies, projectRoot) {
+  const decisionsPath = path.join(projectRoot, '.workflow', 'state', 'decisions.md');
+
+  // Build tech stack section
+  const lines = [
+    '\n## Tech Stack (auto-generated)\n',
+    `*Generated: ${new Date().toISOString().split('T')[0]}*\n`
+  ];
+
+  if (selections.frontend && selections.frontend !== 'none') {
+    const frontendOpt = technologies.find(t => t.value === selections.frontend);
+    lines.push(`- **Frontend**: ${frontendOpt?.label || selections.frontend}`);
+  }
+
+  if (selections.stateManagement && selections.stateManagement !== 'none') {
+    const stateOpt = technologies.find(t => t.value === selections.stateManagement);
+    lines.push(`- **State Management**: ${stateOpt?.label || selections.stateManagement}`);
+  }
+
+  if (selections.styling && selections.styling !== 'none') {
+    const { STYLING_OPTIONS } = require('./flow-tech-options');
+    const styleOpt = STYLING_OPTIONS?.find(o => o.value === selections.styling);
+    lines.push(`- **Styling**: ${styleOpt?.label || selections.styling}`);
+  }
+
+  if (selections.backend && selections.backend !== 'none') {
+    const backendOpt = technologies.find(t => t.value === selections.backend);
+    lines.push(`- **Backend**: ${backendOpt?.label || selections.backend}`);
+  }
+
+  if (selections.database && selections.database !== 'none') {
+    const dbOpt = technologies.find(t => t.value === selections.database);
+    lines.push(`- **Database**: ${dbOpt?.label || selections.database}`);
+  }
+
+  if (selections.testing && selections.testing !== 'none') {
+    const { TESTING_OPTIONS } = require('./flow-tech-options');
+    const testOpt = TESTING_OPTIONS?.find(o => o.value === selections.testing);
+    lines.push(`- **Testing**: ${testOpt?.label || selections.testing}`);
+  }
+
+  if (selections.additionalTools?.length > 0) {
+    lines.push(`- **Additional Tools**: ${selections.additionalTools.join(', ')}`);
+  }
+
+  lines.push('\nSee `.claude/skills/skills-index.json` for detailed patterns.\n');
+
+  const techStackSection = lines.join('\n');
+
+  // Read existing decisions.md or create new
+  let content = '';
+  if (fs.existsSync(decisionsPath)) {
+    content = fs.readFileSync(decisionsPath, 'utf8');
+
+    // Remove existing tech stack section if present
+    const techStackRegex = /\n## Tech Stack \(auto-generated\)[\s\S]*?(?=\n## |$)/;
+    content = content.replace(techStackRegex, '');
+  } else {
+    content = `# Project Decisions\n\nProject-specific coding decisions and patterns.\n`;
+    ensureDir(path.dirname(decisionsPath));
+  }
+
+  // Append tech stack section
+  content = content.trimEnd() + '\n' + techStackSection;
+
+  fs.writeFileSync(decisionsPath, content, 'utf8');
+
+  // Sync to .claude/rules/ for Claude Code integration
+  syncDecisionsToRules();
+}
+
+function updateConfigJson(technologies, projectRoot) {
+  const configPath = path.join(projectRoot, '.workflow', 'config.json');
+
+  if (!fs.existsSync(configPath)) {
+    console.log('  Warning: config.json not found, skipping skills registration');
+    return;
+  }
+
+  const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+
+  // Update skills section
+  if (!config.skills) config.skills = {};
+  config.skills.installed = technologies.map(t =>
+    t.value.toLowerCase().replace(/[^a-z0-9]/g, '-')
+  );
+
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf8');
+}
+
+// ============================================
+// MAIN GENERATION FUNCTION
+// ============================================
+
+async function generateSkills(technologies, selections) {
+  const projectRoot = process.cwd();
+  const { getSkillType, getParentFramework } = getTechOptions();
+
+  // Migrate any skills from old skills/ location to .claude/skills/
+  const migration = migrateOldSkills(projectRoot);
+  if (migration.migrated.length > 0) {
+    console.log('\n  Migrated skills from skills/ to .claude/skills/:');
+    for (const skill of migration.migrated) {
+      console.log(`    ✓ ${skill}`);
+    }
+  }
+  if (migration.skipped.length > 0) {
+    console.log('\n  Cleaned up old skill locations:');
+    for (const skill of migration.skipped) {
+      console.log(`    - ${skill}`);
+    }
+  }
+
+  // Categorize technologies into frameworks (hubs) and libraries (spokes)
+  const frameworks = [];
+  const libraries = [];
+
+  for (const tech of technologies) {
+    const type = getSkillType(tech.value);
+    if (type === 'framework') {
+      frameworks.push(tech);
+    } else {
+      libraries.push(tech);
+    }
+  }
+
+  console.log('\n  Generating skills with hub-spoke structure:');
+  console.log(`    Frameworks (hubs): ${frameworks.map(f => f.label).join(', ') || 'none'}`);
+  console.log(`    Libraries (spokes): ${libraries.map(l => l.label).join(', ') || 'none'}`);
+
+  // Track what needs MCP fetching
+  const needsMCPFetch = [];
+
+  // Build ecosystem mapping: which libraries belong to which frameworks
+  const frameworkEcosystems = new Map();
+  for (const fw of frameworks) {
+    frameworkEcosystems.set(fw.value, {
+      tech: fw,
+      libraries: [],
+      categories: {} // { stateManagement: ['zustand'], forms: ['react-hook-form'], ... }
+    });
+  }
+
+  // Associate libraries with their parent frameworks
+  for (const lib of libraries) {
+    const parent = getParentFramework(lib.value, selections);
+    if (parent && frameworkEcosystems.has(parent)) {
+      const ecosystem = frameworkEcosystems.get(parent);
+      ecosystem.libraries.push(lib);
+
+      // Categorize the library
+      const category = categorizeLibrary(lib.value);
+      if (!ecosystem.categories[category]) {
+        ecosystem.categories[category] = [];
+      }
+      ecosystem.categories[category].push(lib.value.toLowerCase().replace(/[^a-z0-9]/g, '-'));
+    }
+  }
+
+  // Generate framework (hub) skills first
+  for (const fw of frameworks) {
+    console.log(`\n  Processing framework: ${fw.label} (hub)...`);
+
+    const docResult = await fetchDocsViaContext7(fw);
+    if (docResult?.needsMCPFetch) {
+      needsMCPFetch.push(docResult);
+    }
+
+    const ecosystem = frameworkEcosystems.get(fw.value);
+    const ecosystemSkills = ecosystem.libraries.map(lib => ({
+      id: lib.value.toLowerCase().replace(/[^a-z0-9]/g, '-'),
+      label: lib.label
+    }));
+
+    const result = await writeSkillFiles(fw, null, projectRoot, {
+      type: 'framework',
+      ecosystemSkills
+    });
+
+    // Write ecosystem link files
+    if (Object.keys(ecosystem.categories).length > 0) {
+      await writeEcosystemLinks(result.skillId, ecosystem.categories, projectRoot);
+      console.log(`    ✓ Created ecosystem links in: ${result.skillId}/ecosystem/`);
+    }
+
+    console.log(`    ✓ Created: ${path.relative(projectRoot, result.skillDir)}`);
+  }
+
+  // Generate library (spoke) skills
+  for (const lib of libraries) {
+    console.log(`\n  Processing library: ${lib.label} (spoke)...`);
+
+    const docResult = await fetchDocsViaContext7(lib);
+    if (docResult?.needsMCPFetch) {
+      needsMCPFetch.push(docResult);
+    }
+
+    const parentFramework = getParentFramework(lib.value, selections);
+    const result = await writeSkillFiles(lib, null, projectRoot, {
+      type: 'library',
+      parentFramework
+    });
+
+    console.log(`    ✓ Created: ${path.relative(projectRoot, result.skillDir)}`);
+  }
+
+  // Generate skills index (v2.0)
+  const skillsIndex = generateSkillsIndex(technologies, selections);
+  const indexPath = path.join(projectRoot, '.claude', 'skills', 'skills-index.json');
+  ensureDir(path.dirname(indexPath));
+  fs.writeFileSync(indexPath, JSON.stringify(skillsIndex, null, 2), 'utf8');
+  console.log(`\n  ✓ Created: .claude/skills/skills-index.json (v2.0 format)`);
+
+  // Update decisions.md
+  updateDecisionsMd(selections, technologies, projectRoot);
+  console.log(`  ✓ Updated: .workflow/state/decisions.md`);
+
+  // Update config.json
+  updateConfigJson(technologies, projectRoot);
+  console.log(`  ✓ Updated: .workflow/config.json`);
+
+  // If running outside of Claude, provide MCP instructions
+  if (needsMCPFetch.length > 0) {
+    console.log('\n' + '='.repeat(60));
+    console.log('  Documentation Fetch Required');
+    console.log('='.repeat(60));
+    console.log('\n  Skill placeholders created. To populate with real documentation:');
+    console.log('\n  1. In Claude Code, run:');
+    console.log('     /wogi-setup-stack --fetch-docs\n');
+    console.log('  2. Claude will use Context7 MCP to fetch latest docs for:');
+    for (const tech of needsMCPFetch) {
+      console.log(`     - ${tech.technology} (${tech.context7Id})`);
+    }
+    console.log('\n  3. Skills will be updated with extracted patterns.');
+    console.log();
+  }
+
+  // Summary with hub-spoke info
+  console.log('\n' + '─'.repeat(60));
+  console.log('  Skills generated with hub-spoke structure:');
+  console.log('─'.repeat(60));
+  console.log(`  Frameworks (always loaded): ${frameworks.length}`);
+  console.log(`  Libraries (loaded on-demand): ${libraries.length}`);
+  console.log('\n  Loading strategy:');
+  console.log('    • Framework skills load when working on framework files');
+  console.log('    • Library skills load when file imports that library');
+  console.log('    • This saves tokens while keeping relevant context available');
+  console.log();
+
+  return {
+    skillsCreated: technologies.map(t => t.value),
+    indexPath,
+    needsMCPFetch,
+    hubSpokeStats: {
+      frameworks: frameworks.length,
+      libraries: libraries.length
+    }
+  };
+}
+
+/**
+ * Categorize a library into its ecosystem category
+ */
+function categorizeLibrary(libValue) {
+  const categories = {
+    stateManagement: ['zustand', 'redux', 'jotai', 'recoil', 'mobx', 'pinia', 'vuex', 'xstate'],
+    forms: ['react-hook-form', 'formik', 'vee-validate', 'formkit'],
+    styling: ['tailwind', 'shadcn', 'styled-components', 'emotion', 'vanilla-extract', 'sass'],
+    dataFetching: ['tanstack-query', 'swr', 'rtk-query', 'apollo'],
+    animation: ['framer-motion', 'react-spring', 'gsap', 'auto-animate'],
+    validation: ['zod', 'yup', 'class-validator', 'joi', 'valibot'],
+    orm: ['prisma', 'drizzle', 'typeorm', 'mikro-orm', 'mongoose', 'sequelize', 'sqlalchemy'],
+    auth: ['next-auth', 'clerk', 'auth0', 'supabase-auth', 'firebase-auth', 'passport', 'lucia'],
+    testing: ['vitest', 'jest', 'testing-library', 'playwright', 'cypress', 'pytest']
+  };
+
+  for (const [category, libs] of Object.entries(categories)) {
+    if (libs.includes(libValue)) {
+      return category;
+    }
+  }
+
+  return 'other';
+}
+
+/**
+ * Enhance a skill with documentation from Context7
+ * Called by Claude after fetching docs via MCP
+ */
+async function enhanceSkillWithDocs(skillId, docs) {
+  const projectRoot = process.cwd();
+  const skillDir = path.join(projectRoot, '.claude', 'skills', skillId);
+
+  if (!fs.existsSync(skillDir)) {
+    throw new Error(`Skill directory not found: ${skillDir}`);
+  }
+
+  // Parse the docs to extract patterns, anti-patterns, etc.
+  const parsed = parseDocumentation(docs);
+
+  // Update patterns.md
+  if (parsed.patterns) {
+    const patternsPath = path.join(skillDir, 'knowledge', 'patterns.md');
+    let content = fs.readFileSync(patternsPath, 'utf8');
+
+    // Replace placeholder patterns
+    content = content.replace(
+      /## Patterns[\s\S]*?(?=## Examples|---)/,
+      `## Patterns\n\n${parsed.patterns}\n\n`
+    );
+
+    if (parsed.examples) {
+      content = content.replace(
+        /## Examples[\s\S]*?(?=---)/,
+        `## Examples\n\n${parsed.examples}\n\n`
+      );
+    }
+
+    fs.writeFileSync(patternsPath, content, 'utf8');
+  }
+
+  // Update anti-patterns.md
+  if (parsed.antiPatterns) {
+    const antiPatternsPath = path.join(skillDir, 'knowledge', 'anti-patterns.md');
+    let content = fs.readFileSync(antiPatternsPath, 'utf8');
+
+    content = content.replace(
+      /## Anti-Patterns[\s\S]*?(?=## Why|---)/,
+      `## Anti-Patterns\n\n${parsed.antiPatterns}\n\n`
+    );
+
+    fs.writeFileSync(antiPatternsPath, content, 'utf8');
+  }
+
+  // Update conventions.md
+  if (parsed.conventions) {
+    const conventionsPath = path.join(skillDir, 'rules', 'conventions.md');
+    fs.writeFileSync(conventionsPath, parsed.conventions, 'utf8');
+  }
+
+  return { enhanced: true, skillId };
+}
+
+/**
+ * Parse documentation text to extract patterns, anti-patterns, and conventions
+ */
+function parseDocumentation(docs) {
+  // Simple parsing - in practice, Claude would do intelligent extraction
+  const result = {
+    patterns: null,
+    antiPatterns: null,
+    conventions: null,
+    examples: null
+  };
+
+  if (typeof docs === 'string') {
+    // Look for common section headers
+    const patternsMatch = docs.match(/(?:best practices|patterns|recommended)[\s\S]*?(?=\n#|$)/i);
+    if (patternsMatch) result.patterns = patternsMatch[0];
+
+    const antiMatch = docs.match(/(?:anti-patterns|avoid|common mistakes|pitfalls)[\s\S]*?(?=\n#|$)/i);
+    if (antiMatch) result.antiPatterns = antiMatch[0];
+
+    const examplesMatch = docs.match(/(?:examples|usage|code samples)[\s\S]*?(?=\n#|$)/i);
+    if (examplesMatch) result.examples = examplesMatch[0];
+  } else if (typeof docs === 'object') {
+    // Accept pre-parsed docs
+    result.patterns = docs.patterns;
+    result.antiPatterns = docs.antiPatterns;
+    result.conventions = docs.conventions;
+    result.examples = docs.examples;
+  }
+
+  return result;
+}
+
+// ============================================
+// EXPORTS
+// ============================================
+
+module.exports = {
+  generateSkills,
+  enhanceSkillWithDocs,
+  parseDocumentation,
+  generateSkillsIndex,
+  migrateOldSkills,
+  writeSkillFiles,
+  writeEcosystemLinks,
+  generateHubSkillMd,
+  generateSpokeSkillMd,
+  generateEcosystemLinkMd,
+  categorizeLibrary,
+  SKILL_TOPICS,
+  TECH_KEYWORDS
+};
+
+// CLI support
+if (require.main === module) {
+  const args = process.argv.slice(2);
+
+  if (args.includes('--help')) {
+    console.log(`
+Skill Generator for Wogi Flow
+
+Usage:
+  node flow-skill-generator.js [options]
+
+Options:
+  --from-selections    Generate from saved stack-selections.json
+  --help               Show this help
+
+This script is typically called by the Tech Stack Wizard.
+For manual use, run the wizard first: node flow-stack-wizard.js
+`);
+    process.exit(0);
+  }
+
+  if (args.includes('--from-selections')) {
+    const selectionsPath = path.join(process.cwd(), '.workflow', 'state', 'stack-selections.json');
+
+    if (!fs.existsSync(selectionsPath)) {
+      console.error('No stack-selections.json found. Run the wizard first.');
+      process.exit(1);
+    }
+
+    const selections = JSON.parse(fs.readFileSync(selectionsPath, 'utf8'));
+    const { collectTechnologiesFromSelections } = require('./flow-tech-options');
+    const technologies = collectTechnologiesFromSelections(selections);
+
+    generateSkills(technologies, selections)
+      .then(() => process.exit(0))
+      .catch((err) => {
+        console.error('Error:', err);
+        process.exit(1);
+      });
+  }
+}