claude-flow-novice 2.3.7 → 2.3.9

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "claude-flow-novice",
-  "version": "2.3.7",
+  "version": "2.3.9",
   "description": "AI Agent Orchestration CLI",
   "main": "src/index.ts",
   "bin": {
-    "claude-flow-novice": "./src/cli/index.ts"
+    "claude-flow-novice": "./src/cli/index.ts",
+    "claude-flow-sync": "./scripts/sync-from-package.js"
   },
   "files": [
     "src",

package/scripts/categorize-agents.js

@@ -0,0 +1,255 @@
+#!/usr/bin/env node
+
+/**
+ * Categorize imported agents into subdirectories
+ * Analyzes YAML frontmatter and filenames to determine appropriate category
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const AGENTS_DIR = path.join(__dirname, '../agents');
+
+// Category definitions with keyword patterns
+const CATEGORIES = {
+  'development-engineering': {
+    keywords: ['backend', 'frontend', 'api', 'rest', 'graphql', 'react', 'angular', 'vue', 'typescript',
+               'javascript', 'python', 'java', 'rust', 'go', 'node', 'developer', 'engineer', 'code',
+               'programming', 'devops', 'kubernetes', 'docker', 'ci/cd', 'mobile', 'ios', 'android',
+               'web', 'fullstack', 'microservices', 'architecture-analyst', 'database', 'sql', 'nosql',
+               'git', 'version-control', 'deployment', 'container', 'orchestration', 'testing-specialist',
+               'acceptance-test', 'integration', 'unit-test', 'qa', 'quality-assurance', 'debugging'],
+    description: 'Backend, frontend, mobile, DevOps, API development, testing'
+  },
+  'ai-ml-automation': {
+    keywords: ['machine-learning', 'deep-learning', 'neural', 'tensorflow', 'pytorch', 'ai', 'ml',
+               'model', 'training', 'inference', 'nlp', 'computer-vision', 'data-science', 'mlops',
+               'automation', 'intelligent', 'prediction-engine', 'anomaly-detection', 'algorithm',
+               'optimization', 'reinforcement-learning', 'supervised', 'unsupervised'],
+    description: 'Machine learning, deep learning, neural networks, MLOps, automation'
+  },
+  'business-operations': {
+    keywords: ['business', 'strategy', 'growth', 'revenue', 'sales', 'marketing', 'customer',
+               'operations', 'management', 'planning', 'leadership', 'executive', 'roi', 'kpi',
+               'metrics', 'analytics-insights', 'competitive', 'market', 'venture', 'startup',
+               'scaling', 'transformation', 'change-management', 'stakeholder', 'organizational'],
+    description: 'Business strategy, growth, revenue, customer experience, operations'
+  },
+  'security-compliance': {
+    keywords: ['security', 'cybersecurity', 'compliance', 'audit', 'gdpr', 'privacy', 'threat',
+               'vulnerability', 'penetration', 'encryption', 'authentication', 'authorization',
+               'zero-trust', 'firewall', 'monitoring', 'incident', 'forensic', 'risk', 'pci',
+               'hipaa', 'sox', 'iso', 'regulatory', 'data-privacy', 'infosec'],
+    description: 'Cybersecurity, compliance, privacy, threat analysis, auditing'
+  },
+  'data-analytics': {
+    keywords: ['data', 'analytics', 'bi', 'business-intelligence', 'etl', 'elt', 'pipeline',
+               'warehouse', 'lake', 'visualization', 'dashboard', 'reporting', 'insights',
+               'forecasting', 'time-series', 'statistical', 'metrics', 'kpi-dashboard',
+               'real-time-analytics', 'stream-processing', 'batch-processing'],
+    description: 'Business intelligence, analytics, ETL, forecasting, data engineering'
+  },
+  'personal-professional': {
+    keywords: ['career', 'personal', 'professional', 'development', 'coaching', 'mentoring',
+               'leadership-development', 'emotional-intelligence', 'productivity', 'wellness',
+               'work-life', 'communication', 'networking', 'resume', 'interview', 'skill',
+               'learning', 'education', 'training', 'mindfulness', 'motivation', 'goal-setting',
+               'time-management', 'stress', 'wellness', 'active-listening'],
+    description: 'Career, leadership, emotional intelligence, productivity, personal growth'
+  },
+  'payment-financial': {
+    keywords: ['payment', 'stripe', 'paypal', 'square', 'braintree', 'checkout', 'transaction',
+               'financial', 'billing', 'invoice', 'subscription', 'bnpl', 'afterpay', 'klarna',
+               'affirm', 'gateway', 'merchant', 'pos', 'e-commerce-payment', 'apple-pay', 'google-pay',
+               'alipay', 'wechat-pay', 'cryptocurrency', 'blockchain-payment'],
+    description: 'Payment gateways, BNPL, financial transactions, billing systems'
+  },
+  'industry-specific': {
+    keywords: ['healthcare', 'medical', 'clinical', 'patient', 'diagnosis', 'telemedicine',
+               'finance-sector', 'banking', 'insurance', 'legal', 'law', 'compliance-legal',
+               'education', 'e-learning', 'academic', 'retail', 'manufacturing', 'logistics',
+               'supply-chain', 'real-estate', 'hospitality', 'tourism', 'energy', 'utilities',
+               'telecommunications', 'media', 'entertainment', 'sports', 'gaming'],
+    description: 'Healthcare, finance, legal, education, retail, manufacturing, etc.'
+  }
+};
+
+// Files to keep in root
+const META_FILES = ['CLAUDE.md', 'README.md', 'IMPORTED_AGENTS_README.md', 'MIGRATION_SUMMARY.md', '.gitkeep'];
+
+/**
+ * Extract YAML frontmatter from markdown file
+ */
+function extractFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return null;
+
+  const frontmatter = {};
+  const lines = match[1].split('\n');
+
+  for (const line of lines) {
+    const colonIndex = line.indexOf(':');
+    if (colonIndex === -1) continue;
+
+    const key = line.substring(0, colonIndex).trim();
+    const value = line.substring(colonIndex + 1).trim();
+    frontmatter[key] = value;
+  }
+
+  return frontmatter;
+}
+
+/**
+ * Categorize agent based on name and description
+ */
+function categorizeAgent(filename, content) {
+  const frontmatter = extractFrontmatter(content);
+  const searchText = (filename + ' ' + (frontmatter?.name || '') + ' ' + (frontmatter?.description || '')).toLowerCase();
+
+  let bestCategory = null;
+  let bestScore = 0;
+
+  for (const [category, config] of Object.entries(CATEGORIES)) {
+    let score = 0;
+    for (const keyword of config.keywords) {
+      if (searchText.includes(keyword.toLowerCase())) {
+        score++;
+      }
+    }
+
+    if (score > bestScore) {
+      bestScore = score;
+      bestCategory = category;
+    }
+  }
+
+  // Default to industry-specific if no clear match
+  return bestCategory || 'industry-specific';
+}
+
+/**
+ * Main categorization process
+ */
+async function categorizeAgents() {
+  console.log('🔍 Analyzing agent files...\n');
+
+  // Read all markdown files
+  const files = fs.readdirSync(AGENTS_DIR)
+    .filter(f => f.endsWith('.md') && !META_FILES.includes(f));
+
+  console.log(`Found ${files.length} agent files to categorize\n`);
+
+  // Categorize each file
+  const categorization = {};
+  for (const category of Object.keys(CATEGORIES)) {
+    categorization[category] = [];
+  }
+
+  for (const file of files) {
+    const filePath = path.join(AGENTS_DIR, file);
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const category = categorizeAgent(file, content);
+    categorization[category].push(file);
+  }
+
+  // Display categorization summary
+  console.log('📊 Categorization Summary:\n');
+  for (const [category, files] of Object.entries(categorization)) {
+    console.log(`${category}: ${files.length} agents`);
+  }
+  console.log('');
+
+  // Create directories and move files
+  console.log('📁 Creating category directories...\n');
+
+  for (const [category, config] of Object.entries(CATEGORIES)) {
+    const categoryDir = path.join(AGENTS_DIR, category);
+
+    // Create directory
+    if (!fs.existsSync(categoryDir)) {
+      fs.mkdirSync(categoryDir, { recursive: true });
+      console.log(`✓ Created ${category}/`);
+    }
+
+    // Move files
+    const filesToMove = categorization[category];
+    for (const file of filesToMove) {
+      const src = path.join(AGENTS_DIR, file);
+      const dest = path.join(categoryDir, file);
+      fs.renameSync(src, dest);
+    }
+
+    // Create index file
+    const indexContent = `# ${category.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ')}
+
+**Description:** ${config.description}
+**Agent Count:** ${filesToMove.length}
+
+## Available Agents
+
+${filesToMove.sort().map(f => `- [${f.replace('.md', '')}](./${f})`).join('\n')}
+`;
+
+    fs.writeFileSync(path.join(categoryDir, 'INDEX.md'), indexContent);
+  }
+
+  console.log('\n✅ Categorization complete!\n');
+
+  // Generate summary report
+  const summaryContent = `# Agent Categorization Summary
+
+**Total Agents:** ${files.length}
+**Categories:** ${Object.keys(CATEGORIES).length}
+**Generated:** ${new Date().toISOString()}
+
+## Category Breakdown
+
+${Object.entries(categorization).map(([cat, files]) => {
+  const config = CATEGORIES[cat];
+  return `### ${cat.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ')} (${files.length} agents)
+
+**Description:** ${config.description}
+**Location:** \`agents/${cat}/\`
+
+<details>
+<summary>View agents in this category</summary>
+
+${files.sort().map(f => `- ${f.replace('.md', '')}`).join('\n')}
+
+</details>
+`;
+}).join('\n')}
+
+## Quick Navigation
+
+${Object.entries(categorization).map(([cat, files]) =>
+  `- [${cat}](${cat}/INDEX.md) - ${files.length} agents`
+).join('\n')}
+
+## Usage
+
+\`\`\`bash
+# List agents in a category
+ls agents/development-engineering/
+
+# Find specific agent
+find agents -name "*react*"
+
+# Search across all agents
+grep -r "keyword" agents/
+\`\`\`
+`;
+
+  fs.writeFileSync(path.join(AGENTS_DIR, 'CATEGORIZATION_SUMMARY.md'), summaryContent);
+  console.log('📄 Generated CATEGORIZATION_SUMMARY.md\n');
+
+  // Final statistics
+  console.log('📈 Final Statistics:\n');
+  console.log(`Total agents categorized: ${files.length}`);
+  console.log(`Categories created: ${Object.keys(CATEGORIES).length}`);
+  console.log(`Meta files preserved: ${META_FILES.filter(f => fs.existsSync(path.join(AGENTS_DIR, f))).length}`);
+  console.log('\n✨ Done!\n');
+}
+
+// Run
+categorizeAgents().catch(console.error);

package/scripts/subcategorize-agents.js

@@ -0,0 +1,427 @@
+#!/usr/bin/env node
+
+/**
+ * Create subcategories within each main agent category
+ * Provides finer-grained organization for easier browsing
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const AGENTS_DIR = path.join(__dirname, '../agents');
+
+// Subcategory definitions for each main category
+const SUBCATEGORIES = {
+  'development-engineering': {
+    'backend': {
+      keywords: ['backend', 'api', 'rest', 'graphql', 'server', 'node', 'django', 'flask', 'express', 'fastapi'],
+      description: 'Backend development, APIs, server-side programming'
+    },
+    'frontend': {
+      keywords: ['frontend', 'react', 'angular', 'vue', 'ui', 'javascript', 'typescript', 'css', 'html', 'web-ui'],
+      description: 'Frontend frameworks, UI development, client-side'
+    },
+    'mobile': {
+      keywords: ['mobile', 'ios', 'android', 'react-native', 'flutter', 'swift', 'kotlin'],
+      description: 'Mobile app development (iOS, Android)'
+    },
+    'devops': {
+      keywords: ['devops', 'docker', 'kubernetes', 'ci-cd', 'cicd', 'deployment', 'container', 'gitops', 'argocd', 'flux', 'jenkins'],
+      description: 'DevOps, CI/CD, containerization, orchestration'
+    },
+    'testing': {
+      keywords: ['test', 'qa', 'quality', 'acceptance', 'cypress', 'jest', 'playwright', 'e2e', 'integration-test', 'unit-test', 'fuzz'],
+      description: 'Testing, QA, quality assurance, test automation'
+    },
+    'database': {
+      keywords: ['database', 'sql', 'nosql', 'postgres', 'mysql', 'mongodb', 'redis', 'data-model'],
+      description: 'Database design, SQL, NoSQL, data modeling'
+    },
+    'architecture': {
+      keywords: ['architect', 'architecture', 'design-pattern', 'microservices', 'system-design', 'scalability'],
+      description: 'Software architecture, system design, patterns'
+    },
+    'integration': {
+      keywords: ['integration', 'api-integration', 'third-party', 'webhook', 'payment-integration', 'oauth'],
+      description: 'API integration, third-party services, webhooks'
+    }
+  },
+
+  'industry-specific': {
+    'healthcare': {
+      keywords: ['health', 'medical', 'clinical', 'patient', 'doctor', 'hospital', 'telemedicine', 'pharmaceutical'],
+      description: 'Healthcare, medical, clinical systems'
+    },
+    'finance': {
+      keywords: ['finance', 'banking', 'fintech', 'trading', 'investment', 'accounting', 'ledger', 'financial'],
+      description: 'Finance, banking, fintech, trading'
+    },
+    'legal': {
+      keywords: ['legal', 'law', 'attorney', 'court', 'litigation', 'contract', 'compliance-legal'],
+      description: 'Legal services, law firms, compliance'
+    },
+    'education': {
+      keywords: ['education', 'learning', 'student', 'teacher', 'academic', 'e-learning', 'training', 'course'],
+      description: 'Education, e-learning, academic systems'
+    },
+    'retail': {
+      keywords: ['retail', 'e-commerce', 'shop', 'store', 'pos', 'inventory', 'product', 'catalog'],
+      description: 'Retail, e-commerce, point-of-sale'
+    },
+    'manufacturing': {
+      keywords: ['manufactur', 'production', 'factory', 'supply-chain', 'logistics', 'warehouse', 'industrial'],
+      description: 'Manufacturing, production, supply chain'
+    },
+    'entertainment': {
+      keywords: ['entertainment', 'media', 'gaming', 'sports', 'music', 'video', 'streaming', 'content'],
+      description: 'Entertainment, media, gaming, sports'
+    },
+    'other': {
+      keywords: ['real-estate', 'hospitality', 'tourism', 'energy', 'utilities', 'telecom', 'insurance', 'nonprofit'],
+      description: 'Other industries (real estate, hospitality, etc.)'
+    }
+  },
+
+  'ai-ml-automation': {
+    'machine-learning': {
+      keywords: ['machine-learning', 'ml', 'supervised', 'unsupervised', 'classification', 'regression', 'scikit'],
+      description: 'Traditional machine learning, classification, regression'
+    },
+    'deep-learning': {
+      keywords: ['deep-learning', 'neural', 'tensorflow', 'pytorch', 'keras', 'cnn', 'rnn', 'transformer'],
+      description: 'Deep learning, neural networks, frameworks'
+    },
+    'nlp': {
+      keywords: ['nlp', 'natural-language', 'text', 'sentiment', 'chatbot', 'language-model', 'tokeniz'],
+      description: 'Natural language processing, text analysis'
+    },
+    'computer-vision': {
+      keywords: ['vision', 'image', 'video', 'object-detection', 'facial', 'ocr', 'recognition'],
+      description: 'Computer vision, image processing, object detection'
+    },
+    'mlops': {
+      keywords: ['mlops', 'model-deployment', 'training-pipeline', 'experiment-tracking', 'model-serving'],
+      description: 'MLOps, model deployment, training pipelines'
+    },
+    'automation': {
+      keywords: ['automation', 'intelligent-automation', 'workflow', 'orchestration', 'agent-based'],
+      description: 'Intelligent automation, workflow automation'
+    }
+  },
+
+  'business-operations': {
+    'strategy': {
+      keywords: ['strategy', 'strategic', 'planning', 'competitive', 'positioning', 'vision'],
+      description: 'Business strategy, strategic planning'
+    },
+    'growth': {
+      keywords: ['growth', 'scaling', 'expansion', 'market-expansion', 'growth-hacking'],
+      description: 'Business growth, scaling, expansion'
+    },
+    'revenue': {
+      keywords: ['revenue', 'sales', 'monetization', 'pricing', 'billing', 'subscription'],
+      description: 'Revenue optimization, sales, monetization'
+    },
+    'customer': {
+      keywords: ['customer', 'client', 'user-experience', 'crm', 'support', 'journey', 'satisfaction'],
+      description: 'Customer experience, CRM, support'
+    },
+    'operations': {
+      keywords: ['operations', 'operational', 'process', 'workflow', 'efficiency', 'optimization'],
+      description: 'Operations management, process optimization'
+    },
+    'leadership': {
+      keywords: ['leadership', 'management', 'executive', 'team-building', 'organizational'],
+      description: 'Leadership, management, organizational development'
+    }
+  },
+
+  'data-analytics': {
+    'business-intelligence': {
+      keywords: ['business-intelligence', 'bi', 'dashboard', 'reporting', 'kpi', 'metrics'],
+      description: 'Business intelligence, dashboards, reporting'
+    },
+    'data-engineering': {
+      keywords: ['etl', 'elt', 'pipeline', 'data-pipeline', 'warehouse', 'lake', 'ingestion'],
+      description: 'Data engineering, ETL/ELT, data pipelines'
+    },
+    'analytics': {
+      keywords: ['analytics', 'analysis', 'insights', 'statistical', 'predictive', 'prescriptive'],
+      description: 'Data analytics, statistical analysis, insights'
+    },
+    'forecasting': {
+      keywords: ['forecast', 'prediction', 'time-series', 'trend', 'anomaly-detection'],
+      description: 'Forecasting, time-series analysis, predictions'
+    },
+    'visualization': {
+      keywords: ['visualization', 'chart', 'graph', 'tableau', 'power-bi', 'data-viz'],
+      description: 'Data visualization, charts, dashboards'
+    }
+  },
+
+  'personal-professional': {
+    'career': {
+      keywords: ['career', 'job', 'interview', 'resume', 'job-search', 'promotion', 'transition'],
+      description: 'Career development, job search, interviews'
+    },
+    'leadership': {
+      keywords: ['leadership', 'leader', 'management', 'executive', 'mentoring', 'coaching'],
+      description: 'Leadership development, coaching, mentoring'
+    },
+    'productivity': {
+      keywords: ['productivity', 'time-management', 'efficiency', 'goal', 'planning', 'organization'],
+      description: 'Productivity, time management, goal setting'
+    },
+    'communication': {
+      keywords: ['communication', 'presentation', 'public-speaking', 'writing', 'listening', 'feedback'],
+      description: 'Communication skills, presentations, feedback'
+    },
+    'wellness': {
+      keywords: ['wellness', 'stress', 'work-life', 'balance', 'mindfulness', 'mental-health', 'emotional'],
+      description: 'Wellness, work-life balance, mental health'
+    }
+  },
+
+  'security-compliance': {
+    'cybersecurity': {
+      keywords: ['cybersecurity', 'security', 'threat', 'vulnerability', 'penetration', 'firewall', 'encryption'],
+      description: 'Cybersecurity, threat analysis, penetration testing'
+    },
+    'compliance': {
+      keywords: ['compliance', 'regulatory', 'audit', 'gdpr', 'hipaa', 'sox', 'pci', 'iso'],
+      description: 'Compliance, regulatory requirements, auditing'
+    },
+    'privacy': {
+      keywords: ['privacy', 'data-privacy', 'gdpr', 'personal-data', 'consent', 'anonymization'],
+      description: 'Data privacy, GDPR, personal data protection'
+    },
+    'access-control': {
+      keywords: ['access-control', 'authentication', 'authorization', 'identity', 'zero-trust', 'iam'],
+      description: 'Access control, authentication, identity management'
+    }
+  },
+
+  'payment-financial': {
+    'payment-gateways': {
+      keywords: ['stripe', 'paypal', 'square', 'braintree', 'checkout', 'payment-gateway', 'merchant'],
+      description: 'Payment gateways (Stripe, PayPal, Square, etc.)'
+    },
+    'bnpl': {
+      keywords: ['bnpl', 'afterpay', 'klarna', 'affirm', 'installment', 'buy-now-pay-later'],
+      description: 'Buy-now-pay-later, installment payments'
+    },
+    'cryptocurrency': {
+      keywords: ['crypto', 'bitcoin', 'ethereum', 'blockchain', 'wallet', 'web3'],
+      description: 'Cryptocurrency, blockchain, Web3 payments'
+    },
+    'billing': {
+      keywords: ['billing', 'invoice', 'subscription', 'recurring', 'pricing'],
+      description: 'Billing systems, invoicing, subscriptions'
+    }
+  }
+};
+
+/**
+ * Extract YAML frontmatter from markdown file
+ */
+function extractFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return null;
+
+  const frontmatter = {};
+  const lines = match[1].split('\n');
+
+  for (const line of lines) {
+    const colonIndex = line.indexOf(':');
+    if (colonIndex === -1) continue;
+
+    const key = line.substring(0, colonIndex).trim();
+    const value = line.substring(colonIndex + 1).trim();
+    frontmatter[key] = value;
+  }
+
+  return frontmatter;
+}
+
+/**
+ * Categorize agent into subcategory
+ */
+function subcategorizeAgent(filename, content, mainCategory) {
+  const subcategories = SUBCATEGORIES[mainCategory];
+  if (!subcategories) return null;
+
+  const frontmatter = extractFrontmatter(content);
+  const searchText = (filename + ' ' + (frontmatter?.name || '') + ' ' + (frontmatter?.description || '')).toLowerCase();
+
+  let bestSubcategory = null;
+  let bestScore = 0;
+
+  for (const [subcategory, config] of Object.entries(subcategories)) {
+    let score = 0;
+    for (const keyword of config.keywords) {
+      if (searchText.includes(keyword.toLowerCase())) {
+        score++;
+      }
+    }
+
+    if (score > bestScore) {
+      bestScore = score;
+      bestSubcategory = subcategory;
+    }
+  }
+
+  // Default to first subcategory or 'other' if no match
+  if (!bestSubcategory) {
+    bestSubcategory = subcategories.other ? 'other' : Object.keys(subcategories)[0];
+  }
+
+  return bestSubcategory;
+}
+
+/**
+ * Process a single main category
+ */
+function processCategory(mainCategory) {
+  const categoryDir = path.join(AGENTS_DIR, mainCategory);
+  if (!fs.existsSync(categoryDir)) {
+    console.log(`⏭️  Skipping ${mainCategory} (not found)`);
+    return null;
+  }
+
+  console.log(`\n📂 Processing ${mainCategory}...`);
+
+  // Read agent files
+  const files = fs.readdirSync(categoryDir)
+    .filter(f => f.endsWith('.md') && f !== 'INDEX.md');
+
+  if (files.length === 0) {
+    console.log(`  No agents found in ${mainCategory}`);
+    return null;
+  }
+
+  console.log(`  Found ${files.length} agents`);
+
+  // Categorize into subcategories
+  const subcategorization = {};
+  const subcategoryConfigs = SUBCATEGORIES[mainCategory];
+
+  for (const subcategory of Object.keys(subcategoryConfigs)) {
+    subcategorization[subcategory] = [];
+  }
+
+  for (const file of files) {
+    const filePath = path.join(categoryDir, file);
+    const content = fs.readFileSync(filePath, 'utf-8');
+    const subcategory = subcategorizeAgent(file, content, mainCategory);
+
+    if (subcategory && subcategorization[subcategory]) {
+      subcategorization[subcategory].push(file);
+    }
+  }
+
+  // Display subcategorization
+  console.log(`\n  Subcategories:`);
+  for (const [subcategory, files] of Object.entries(subcategorization)) {
+    if (files.length > 0) {
+      console.log(`    ${subcategory}: ${files.length} agents`);
+    }
+  }
+
+  // Create subdirectories and move files
+  for (const [subcategory, config] of Object.entries(subcategoryConfigs)) {
+    const subcategoryDir = path.join(categoryDir, subcategory);
+    const filesToMove = subcategorization[subcategory];
+
+    if (filesToMove.length === 0) continue;
+
+    // Create directory
+    if (!fs.existsSync(subcategoryDir)) {
+      fs.mkdirSync(subcategoryDir, { recursive: true });
+    }
+
+    // Move files
+    for (const file of filesToMove) {
+      const src = path.join(categoryDir, file);
+      const dest = path.join(subcategoryDir, file);
+      fs.renameSync(src, dest);
+    }
+
+    // Create subcategory index
+    const indexContent = `# ${subcategory.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ')}
+
+**Description:** ${config.description}
+**Agent Count:** ${filesToMove.length}
+
+## Available Agents
+
+${filesToMove.sort().map(f => `- [${f.replace('.md', '')}](./${f})`).join('\n')}
+`;
+
+    fs.writeFileSync(path.join(subcategoryDir, 'INDEX.md'), indexContent);
+  }
+
+  // Update main category index
+  const mainIndexContent = `# ${mainCategory.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ')}
+
+**Total Agents:** ${files.length}
+
+## Subcategories
+
+${Object.entries(subcategorization)
+  .filter(([_, files]) => files.length > 0)
+  .sort((a, b) => b[1].length - a[1].length)
+  .map(([subcat, files]) => {
+    const config = subcategoryConfigs[subcat];
+    return `### [${subcat}](${subcat}/INDEX.md) (${files.length} agents)
+
+${config.description}
+`;
+  }).join('\n')}
+
+## Quick Navigation
+
+${Object.entries(subcategorization)
+  .filter(([_, files]) => files.length > 0)
+  .map(([subcat, files]) => `- [${subcat}](${subcat}/INDEX.md) - ${files.length} agents`)
+  .join('\n')}
+`;
+
+  fs.writeFileSync(path.join(categoryDir, 'INDEX.md'), mainIndexContent);
+
+  return {
+    category: mainCategory,
+    totalAgents: files.length,
+    subcategories: Object.fromEntries(
+      Object.entries(subcategorization).filter(([_, files]) => files.length > 0)
+    )
+  };
+}
+
+/**
+ * Main subcategorization process
+ */
+async function subcategorizeAgents() {
+  console.log('🔍 Subcategorizing agents within each main category...\n');
+
+  const results = {};
+
+  for (const mainCategory of Object.keys(SUBCATEGORIES)) {
+    const result = processCategory(mainCategory);
+    if (result) {
+      results[mainCategory] = result;
+    }
+  }
+
+  console.log('\n\n✅ Subcategorization complete!\n');
+
+  // Generate summary
+  console.log('📊 Summary by Main Category:\n');
+  for (const [category, data] of Object.entries(results)) {
+    console.log(`${category}: ${data.totalAgents} agents in ${Object.keys(data.subcategories).length} subcategories`);
+  }
+
+  console.log('\n✨ Done!\n');
+}
+
+// Run
+subcategorizeAgents().catch(console.error);

package/scripts/sync-from-package.js

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+/**
+ * Sync agents, commands, and hooks from npm package to local project
+ * Usage: npx claude-flow-novice sync [--force] [--backup] [--agents] [--commands] [--hooks]
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const args = process.argv.slice(2);
+const flags = {
+  force: args.includes('--force'),
+  backup: args.includes('--backup'),
+  agents: args.includes('--agents') || args.length === 0,
+  commands: args.includes('--commands') || args.length === 0,
+  hooks: args.includes('--hooks') || args.length === 0,
+  help: args.includes('--help') || args.includes('-h')
+};
+
+if (flags.help) {
+  console.log(`
+Claude Flow Novice - Sync Script
+
+Syncs agents, commands, and hooks from npm package to your local project.
+
+Usage:
+  npx claude-flow-novice sync [options]
+
+Options:
+  --agents     Sync .claude/agents/ only
+  --commands   Sync .claude/commands/ only  
+  --hooks      Sync config/hooks/ only
+  --force      Overwrite existing files without prompting
+  --backup     Create backup before syncing (recommended)
+  --help, -h   Show this help message
+
+Examples:
+  npx claude-flow-novice sync                    # Sync everything
+  npx claude-flow-novice sync --agents --backup  # Sync agents with backup
+  npx claude-flow-novice sync --force --backup   # Force sync all with backup
+`);
+  process.exit(0);
+}
+
+// Find package location
+const packagePath = path.join(__dirname, '..');
+const projectRoot = process.cwd();
+
+console.log('🚀 Claude Flow Novice - Sync Script\n');
+console.log(`📦 Package: ${packagePath}`);
+console.log(`📁 Project: ${projectRoot}\n`);
+
+const syncItems = [
+  {
+    name: 'agents',
+    enabled: flags.agents,
+    source: path.join(packagePath, '.claude', 'agents'),
+    dest: path.join(projectRoot, '.claude', 'agents'),
+    description: 'Agent definitions'
+  },
+  {
+    name: 'commands',
+    enabled: flags.commands,
+    source: path.join(packagePath, '.claude', 'commands'),
+    dest: path.join(projectRoot, '.claude', 'commands'),
+    description: 'Slash commands'
+  },
+  {
+    name: 'hooks',
+    enabled: flags.hooks,
+    source: path.join(packagePath, 'config', 'hooks'),
+    dest: path.join(projectRoot, 'config', 'hooks'),
+    description: 'Validation hooks'
+  }
+];
+
+// Backup function
+function createBackup(destPath) {
+  if (!fs.existsSync(destPath)) return null;
+  
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-').split('T')[0];
+  const backupPath = `${destPath}.backup-${timestamp}`;
+  
+  console.log(`  📋 Creating backup: ${path.basename(backupPath)}`);
+  execSync(`cp -r "${destPath}" "${backupPath}"`);
+  return backupPath;
+}
+
+// Copy directory recursively
+function copyDir(src, dest) {
+  if (!fs.existsSync(src)) {
+    console.error(`  ❌ Source not found: ${src}`);
+    return false;
+  }
+
+  // Create destination directory
+  if (!fs.existsSync(dest)) {
+    fs.mkdirSync(dest, { recursive: true });
+  }
+
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  let fileCount = 0;
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+      fileCount++;
+    }
+  }
+
+  return fileCount;
+}
+
+// Count files in directory
+function countFiles(dir) {
+  if (!fs.existsSync(dir)) return 0;
+  
+  let count = 0;
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      count += countFiles(path.join(dir, entry.name));
+    } else {
+      count++;
+    }
+  }
+  
+  return count;
+}
+
+// Main sync process
+let totalSynced = 0;
+
+for (const item of syncItems) {
+  if (!item.enabled) continue;
+
+  console.log(`\n📂 Syncing ${item.description}...`);
+  console.log(`   Source: ${item.source}`);
+  console.log(`   Dest:   ${item.dest}`);
+
+  // Check if source exists
+  if (!fs.existsSync(item.source)) {
+    console.log(`  ⚠️  Source directory not found, skipping`);
+    continue;
+  }
+
+  // Backup if requested
+  if (flags.backup) {
+    createBackup(item.dest);
+  }
+
+  // Check if destination exists and not forcing
+  if (fs.existsSync(item.dest) && !flags.force) {
+    const beforeCount = countFiles(item.dest);
+    console.log(`  ⚠️  Destination exists with ${beforeCount} files`);
+    console.log(`  💡 Use --force to overwrite or --backup to create backup first`);
+    continue;
+  }
+
+  // Perform sync
+  const fileCount = copyDir(item.source, item.dest);
+  console.log(`  ✅ Synced ${fileCount} files`);
+  totalSynced += fileCount;
+}
+
+console.log(`\n✨ Sync complete! ${totalSynced} files synced.\n`);
+
+if (totalSynced > 0) {
+  console.log('Next steps:');
+  console.log('  1. Review synced files');
+  console.log('  2. Customize as needed for your project');
+  console.log('  3. Commit changes to version control\n');
+}