claude-flow-novice 1.3.6 → 1.5.1

package/scripts/build/validate-agents.js

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+
+/**
+ * Agent Validation Script
+ * Validates Claude Code agent definitions before package distribution
+ */
+
+import fs from 'fs-extra';
+import path from 'path';
+import yaml from 'yaml';
+import { glob } from 'glob';
+
+const VALID_TOOLS = [
+  'Read', 'Write', 'Edit', 'MultiEdit', 'Bash', 'Glob', 'Grep',
+  'WebSearch', 'WebFetch', 'TodoWrite', 'Task', 'SlashCommand',
+  // MCP coordination tools
+  'mcp__claude-flow-novice__swarm_init', 'mcp__claude-flow-novice__agent_spawn',
+  'mcp__claude-flow-novice__task_orchestrate', 'mcp__claude-flow-novice__memory_usage'
+];
+
+const VALID_MODELS = ['sonnet', 'haiku', 'opus', 'inherit'];
+
+class AgentValidator {
+  constructor() {
+    this.errors = [];
+    this.warnings = [];
+    this.agentCount = 0;
+  }
+
+  log(message, type = 'info') {
+    const timestamp = new Date().toISOString();
+    const prefix = type === 'error' ? '❌' : type === 'warning' ? '⚠️' : 'ℹ️';
+    console.log(`${prefix} [${timestamp}] ${message}`);
+  }
+
+  addError(file, message) {
+    this.errors.push({ file, message });
+    this.log(`Error in ${file}: ${message}`, 'error');
+  }
+
+  addWarning(file, message) {
+    this.warnings.push({ file, message });
+    this.log(`Warning in ${file}: ${message}`, 'warning');
+  }
+
+  validateAgentFile(filePath) {
+    const relativePath = path.relative(process.cwd(), filePath);
+
+    try {
+      const content = fs.readFileSync(filePath, 'utf8');
+
+      // Check if file has YAML frontmatter
+      if (!content.startsWith('---')) {
+        this.addError(relativePath, 'Missing YAML frontmatter (should start with ---)');
+        return false;
+      }
+
+      // Extract frontmatter
+      const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/);
+      if (!frontmatterMatch) {
+        this.addError(relativePath, 'Invalid YAML frontmatter format');
+        return false;
+      }
+
+      let frontmatter;
+      try {
+        frontmatter = yaml.parse(frontmatterMatch[1]);
+      } catch (error) {
+        this.addError(relativePath, `Invalid YAML syntax: ${error.message}`);
+        return false;
+      }
+
+      // Validate required fields
+      this.validateRequiredFields(relativePath, frontmatter);
+      this.validateTools(relativePath, frontmatter);
+      this.validateModel(relativePath, frontmatter);
+      this.validateNaming(relativePath, frontmatter, filePath);
+      this.validateSystemPrompt(relativePath, content);
+
+      this.agentCount++;
+      return true;
+
+    } catch (error) {
+      this.addError(relativePath, `Failed to read file: ${error.message}`);
+      return false;
+    }
+  }
+
+  validateRequiredFields(file, frontmatter) {
+    const required = ['name', 'description'];
+
+    for (const field of required) {
+      if (!frontmatter[field]) {
+        this.addError(file, `Missing required field: ${field}`);
+      } else if (typeof frontmatter[field] !== 'string') {
+        this.addError(file, `Field '${field}' must be a string`);
+      }
+    }
+
+    // Validate description is meaningful
+    if (frontmatter.description && frontmatter.description.length < 20) {
+      this.addWarning(file, 'Description should be more descriptive (at least 20 characters)');
+    }
+  }
+
+  validateTools(file, frontmatter) {
+    if (frontmatter.tools) {
+      if (typeof frontmatter.tools === 'string') {
+        // Convert comma-separated string to array
+        const tools = frontmatter.tools.split(',').map(t => t.trim());
+        this.validateToolArray(file, tools);
+      } else if (Array.isArray(frontmatter.tools)) {
+        this.validateToolArray(file, frontmatter.tools);
+      } else {
+        this.addError(file, 'Tools field must be a string or array');
+      }
+    } else {
+      this.addWarning(file, 'No tools specified - agent will inherit all tools');
+    }
+  }
+
+  validateToolArray(file, tools) {
+    for (const tool of tools) {
+      if (!VALID_TOOLS.includes(tool)) {
+        this.addWarning(file, `Unknown tool: ${tool}. Valid tools: ${VALID_TOOLS.join(', ')}`);
+      }
+    }
+  }
+
+  validateModel(file, frontmatter) {
+    if (frontmatter.model && !VALID_MODELS.includes(frontmatter.model)) {
+      this.addWarning(file, `Unknown model: ${frontmatter.model}. Valid models: ${VALID_MODELS.join(', ')}`);
+    }
+  }
+
+  validateNaming(file, frontmatter, filePath) {
+    const fileName = path.basename(filePath, '.md');
+
+    // Check naming convention
+    if (!/^[a-z]+(-[a-z]+)*$/.test(fileName)) {
+      this.addError(file, 'File name should use lowercase-with-hyphens format');
+    }
+
+    // Check name matches file name
+    if (frontmatter.name && frontmatter.name !== fileName) {
+      this.addWarning(file, `Agent name '${frontmatter.name}' doesn't match file name '${fileName}'`);
+    }
+  }
+
+  validateSystemPrompt(file, content) {
+    // Extract system prompt (everything after frontmatter)
+    const promptMatch = content.match(/^---\n[\s\S]*?\n---\n\n?([\s\S]*)$/);
+    if (!promptMatch || !promptMatch[1].trim()) {
+      this.addError(file, 'Missing system prompt after YAML frontmatter');
+      return;
+    }
+
+    const prompt = promptMatch[1].trim();
+
+    // Check prompt length
+    if (prompt.length < 100) {
+      this.addWarning(file, 'System prompt should be more detailed (at least 100 characters)');
+    }
+
+    // Check for key elements
+    const hasExpertise = /expertise|expert|specialist|specializ/i.test(prompt);
+    const hasMethodology = /methodology|approach|process|workflow/i.test(prompt);
+    const hasUsage = /use this|when to|should be used/i.test(prompt);
+
+    if (!hasExpertise) {
+      this.addWarning(file, 'System prompt should define agent expertise');
+    }
+    if (!hasMethodology) {
+      this.addWarning(file, 'System prompt should describe methodology or approach');
+    }
+    if (!hasUsage) {
+      this.addWarning(file, 'System prompt should explain when to use this agent');
+    }
+  }
+
+  async validateAll() {
+    this.log('Starting agent validation...');
+
+    try {
+      // Find all agent files
+      const agentFiles = await glob('.claude/agents/**/*.md');
+
+      if (agentFiles.length === 0) {
+        this.addError('validation', 'No agent files found in .claude/agents/');
+        return false;
+      }
+
+      this.log(`Found ${agentFiles.length} agent files to validate`);
+
+      // Validate each file
+      for (const file of agentFiles) {
+        this.validateAgentFile(file);
+      }
+
+      // Summary
+      this.log(`\n📊 Validation Summary:`);
+      this.log(`   Agents validated: ${this.agentCount}`);
+      this.log(`   Errors: ${this.errors.length}`);
+      this.log(`   Warnings: ${this.warnings.length}`);
+
+      if (this.errors.length > 0) {
+        this.log('\n❌ Validation failed with errors:', 'error');
+        return false;
+      }
+
+      if (this.warnings.length > 0) {
+        this.log('\n⚠️ Validation passed with warnings', 'warning');
+      } else {
+        this.log('\n✅ All agents passed validation!');
+      }
+
+      return true;
+
+    } catch (error) {
+      this.addError('validation', `Validation failed: ${error.message}`);
+      return false;
+    }
+  }
+}
+
+// CLI usage
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const validator = new AgentValidator();
+
+  validator.validateAll().then(success => {
+    process.exit(success ? 0 : 1);
+  }).catch(error => {
+    console.error('❌ Validation crashed:', error);
+    process.exit(1);
+  });
+}
+
+export default AgentValidator;