claude-flow 2.0.0-alpha.77 → 2.0.0-alpha.78

package/README.md

@@ -45,8 +45,9 @@
 # 1. Install Claude Code globally
 npm install -g @anthropic-ai/claude-code
 
-# 2. Activate Claude Code with permissions
-claude --dangerously-skip-permissions
+# 2. (Optional) Skip permissions check for faster setup
+# Only use if you understand the security implications
+# claude --dangerously-skip-permissions
 ```
 
 💡 **Windows Note**: If you encounter SQLite errors, Claude Flow will automatically use in-memory storage. For persistent storage options, see our [Windows guide](https://github.com/ruvnet/claude-code-flow/blob/main/docs/windows-installation.md).
@@ -61,7 +62,7 @@ npx claude-flow@alpha init --force
 npx claude-flow@alpha --help
 
 # 3a. Quick AI coordination (recommended for most tasks)
-npx claude-flow@alpha swarm "build me a REST API" --claude
+npx claude-flow@alpha swarm "build me a REST API"
 
 # 3b. OR launch the full hive-mind system (for complex projects)
 npx claude-flow@alpha hive-mind wizard
@@ -269,7 +270,7 @@ Claude-Flow v2.0.0 introduces groundbreaking hive-mind architecture where a **Qu
 
 ```bash
 # Deploy intelligent swarm coordination
-npx claude-flow@alpha swarm "Build a full-stack application" --strategy development --claude
+npx claude-flow@alpha swarm "Build a full-stack application" --strategy development
 
 # Launch hive-mind with specific specializations
 npx claude-flow@alpha hive-mind spawn "Create microservices architecture" --agents 8 --claude
@@ -501,8 +502,7 @@ npx claude-flow@alpha workflow create --name "Development Pipeline" --parallel
 npx claude-flow@alpha hive-mind spawn "Build e-commerce platform with React, Node.js, and PostgreSQL" \
   --agents 10 \
   --strategy parallel \
-  --memory-namespace ecommerce \
-  --claude
+  --memory-namespace ecommerce
 
 # Monitor progress in real-time
 npx claude-flow@alpha swarm monitor --dashboard --real-time
@@ -514,8 +514,7 @@ npx claude-flow@alpha swarm monitor --dashboard --real-time
 npx claude-flow@alpha swarm "Research AI safety in autonomous systems" \
   --strategy research \
   --neural-patterns enabled \
-  --memory-compression high \
-  --claude
+  --memory-compression high
 
 # Analyze results with cognitive computing
 npx claude-flow@alpha cognitive analyze --target research-results

package/bin/claude-flow

@@ -1,7 +1,7 @@
 #!/bin/sh
 # Claude-Flow Smart Dispatcher - Detects and uses the best available runtime
 
-VERSION="2.0.0-alpha.77"
+VERSION="2.0.0-alpha.78"
 
 # Determine the correct path based on how the script is invoked
 if [ -L "$0" ]; then

package/bin/claude-flow.js

@@ -11,7 +11,7 @@ import { existsSync } from 'fs';
 import { spawn } from 'child_process';
 import process from 'process';
 
-const VERSION = "2.0.0-alpha.77";
+const VERSION = "2.0.0-alpha.78";
 
 // Get script directory and root directory
 const __filename = fileURLToPath(import.meta.url);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-flow",
-  "version": "2.0.0-alpha.77",
+  "version": "2.0.0-alpha.78",
   "description": "Enterprise-grade AI agent orchestration with ruv-swarm integration (Alpha Release)",
   "main": "cli.mjs",
   "bin": {
@@ -122,7 +122,8 @@
     "ora": "^7.0.1",
     "p-queue": "^8.1.0",
     "ruv-swarm": "^1.0.14",
-    "ws": "^8.18.3"
+    "ws": "^8.18.3",
+    "yaml": "^2.8.0"
   },
   "optionalDependencies": {
     "better-sqlite3": "^12.2.0",

package/src/agents/agent-loader.ts

@@ -0,0 +1,247 @@
+/**
+ * Dynamic Agent Loader - Reads agent definitions from .claude/agents/ directory
+ * This is the single source of truth for all agent types in the system
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { glob } from 'glob';
+import { resolve, dirname } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+
+export interface AgentDefinition {
+  name: string;
+  type?: string;
+  color?: string;
+  description: string;
+  capabilities?: string[];
+  priority?: 'low' | 'medium' | 'high' | 'critical';
+  hooks?: {
+    pre?: string;
+    post?: string;
+  };
+  content?: string; // The markdown content after frontmatter
+}
+
+export interface AgentCategory {
+  name: string;
+  agents: AgentDefinition[];
+}
+
+class AgentLoader {
+  private agentCache: Map<string, AgentDefinition> = new Map();
+  private categoriesCache: AgentCategory[] = [];
+  private lastLoadTime = 0;
+  private cacheExpiry = 60000; // 1 minute cache
+
+  /**
+   * Get the .claude/agents directory path
+   */
+  private getAgentsDirectory(): string {
+    // Start from current working directory and walk up to find .claude/agents
+    let currentDir = process.cwd();
+    
+    while (currentDir !== '/') {
+      const claudeAgentsPath = resolve(currentDir, '.claude', 'agents');
+      if (existsSync(claudeAgentsPath)) {
+        return claudeAgentsPath;
+      }
+      currentDir = dirname(currentDir);
+    }
+    
+    // Fallback to relative path
+    return resolve(process.cwd(), '.claude', 'agents');
+  }
+
+  /**
+   * Parse agent definition from markdown file
+   */
+  private parseAgentFile(filePath: string): AgentDefinition | null {
+    try {
+      const content = readFileSync(filePath, 'utf-8');
+      
+      // Split frontmatter and content
+      const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+      if (!frontmatterMatch) {
+        console.warn(`No frontmatter found in ${filePath}`);
+        return null;
+      }
+
+      const [, yamlContent, markdownContent] = frontmatterMatch;
+      const frontmatter = parseYaml(yamlContent);
+
+      if (!frontmatter.name || !frontmatter.metadata?.description) {
+        console.warn(`Missing required fields (name, metadata.description) in ${filePath}`);
+        return null;
+      }
+
+      return {
+        name: frontmatter.name,
+        type: frontmatter.type,
+        color: frontmatter.color,
+        description: frontmatter.metadata.description,
+        capabilities: frontmatter.metadata.capabilities || frontmatter.capabilities || [],
+        priority: frontmatter.priority || 'medium',
+        hooks: frontmatter.hooks,
+        content: markdownContent.trim(),
+      };
+    } catch (error) {
+      console.error(`Error parsing agent file ${filePath}:`, error);
+      return null;
+    }
+  }
+
+  /**
+   * Load all agent definitions from .claude/agents directory
+   */
+  private async loadAgents(): Promise<void> {
+    const agentsDir = this.getAgentsDirectory();
+    
+    if (!existsSync(agentsDir)) {
+      console.warn(`Agents directory not found: ${agentsDir}`);
+      return;
+    }
+
+    // Find all .md files in the agents directory
+    const agentFiles = await glob('**/*.md', {
+      cwd: agentsDir,
+      ignore: ['**/README.md', '**/MIGRATION_SUMMARY.md'],
+      absolute: true,
+    });
+
+    // Clear cache
+    this.agentCache.clear();
+    this.categoriesCache = [];
+
+    // Track categories
+    const categoryMap = new Map<string, AgentDefinition[]>();
+
+    // Parse each agent file
+    for (const filePath of agentFiles) {
+      const agent = this.parseAgentFile(filePath);
+      if (agent) {
+        this.agentCache.set(agent.name, agent);
+        
+        // Determine category from file path
+        const relativePath = filePath.replace(agentsDir, '');
+        const pathParts = relativePath.split('/');
+        const category = pathParts[1] || 'uncategorized'; // First directory after agents/
+        
+        if (!categoryMap.has(category)) {
+          categoryMap.set(category, []);
+        }
+        categoryMap.get(category)!.push(agent);
+      }
+    }
+
+    // Build categories array
+    this.categoriesCache = Array.from(categoryMap.entries()).map(([name, agents]) => ({
+      name,
+      agents: agents.sort((a, b) => a.name.localeCompare(b.name)),
+    }));
+
+    this.lastLoadTime = Date.now();
+  }
+
+  /**
+   * Check if cache needs refresh
+   */
+  private needsRefresh(): boolean {
+    return Date.now() - this.lastLoadTime > this.cacheExpiry;
+  }
+
+  /**
+   * Ensure agents are loaded and cache is fresh
+   */
+  private async ensureLoaded(): Promise<void> {
+    if (this.agentCache.size === 0 || this.needsRefresh()) {
+      await this.loadAgents();
+    }
+  }
+
+  /**
+   * Get all available agent types
+   */
+  async getAvailableAgentTypes(): Promise<string[]> {
+    await this.ensureLoaded();
+    return Array.from(this.agentCache.keys()).sort();
+  }
+
+  /**
+   * Get agent definition by name
+   */
+  async getAgent(name: string): Promise<AgentDefinition | null> {
+    await this.ensureLoaded();
+    return this.agentCache.get(name) || null;
+  }
+
+  /**
+   * Get all agent definitions
+   */
+  async getAllAgents(): Promise<AgentDefinition[]> {
+    await this.ensureLoaded();
+    return Array.from(this.agentCache.values()).sort((a, b) => a.name.localeCompare(b.name));
+  }
+
+  /**
+   * Get agents organized by category
+   */
+  async getAgentCategories(): Promise<AgentCategory[]> {
+    await this.ensureLoaded();
+    return this.categoriesCache;
+  }
+
+  /**
+   * Search agents by capabilities, description, or name
+   */
+  async searchAgents(query: string): Promise<AgentDefinition[]> {
+    await this.ensureLoaded();
+    const lowerQuery = query.toLowerCase();
+    
+    return Array.from(this.agentCache.values()).filter(agent => {
+      return (
+        agent.name.toLowerCase().includes(lowerQuery) ||
+        agent.description.toLowerCase().includes(lowerQuery) ||
+        agent.capabilities?.some(cap => cap.toLowerCase().includes(lowerQuery)) ||
+        false
+      );
+    });
+  }
+
+  /**
+   * Check if an agent type is valid
+   */
+  async isValidAgentType(name: string): Promise<boolean> {
+    await this.ensureLoaded();
+    return this.agentCache.has(name);
+  }
+
+  /**
+   * Get agents by category name
+   */
+  async getAgentsByCategory(category: string): Promise<AgentDefinition[]> {
+    const categories = await this.getAgentCategories();
+    const found = categories.find(cat => cat.name === category);
+    return found?.agents || [];
+  }
+
+  /**
+   * Force refresh the agent cache
+   */
+  async refresh(): Promise<void> {
+    this.lastLoadTime = 0; // Force reload
+    await this.loadAgents();
+  }
+}
+
+// Singleton instance
+export const agentLoader = new AgentLoader();
+
+// Convenience functions
+export const getAvailableAgentTypes = () => agentLoader.getAvailableAgentTypes();
+export const getAgent = (name: string) => agentLoader.getAgent(name);
+export const getAllAgents = () => agentLoader.getAllAgents();
+export const getAgentCategories = () => agentLoader.getAgentCategories();
+export const searchAgents = (query: string) => agentLoader.searchAgents(query);
+export const isValidAgentType = (name: string) => agentLoader.isValidAgentType(name);
+export const getAgentsByCategory = (category: string) => agentLoader.getAgentsByCategory(category);
+export const refreshAgents = () => agentLoader.refresh();

package/src/cli/help-text.js

@@ -5,14 +5,14 @@
 
 import { HelpFormatter } from './help-formatter.js';
 
-export const VERSION = '2.0.0-alpha.77';
+export const VERSION = '2.0.0-alpha.78';
 
 export const MAIN_HELP = `
 🌊 Claude-Flow v${VERSION} - Enterprise-Grade AI Agent Orchestration Platform
 
 🎯 ENTERPRISE FEATURES: Complete ruv-swarm integration with 87 MCP tools, neural networking, and production-ready infrastructure
 🐝 NEW: Advanced Hive Mind System with Queen-led coordination, collective intelligence, and unlimited scaling
-⚡ ALPHA 77: Enhanced hooks pre-task exit handling with timeout protection
+⚡ ALPHA 78: Removed legacy Deno warnings, enhanced SPARC slash commands
 
 USAGE:
   claude-flow <command> [options]

package/src/cli/simple-commands/init/claude-commands/slash-commands.js

@@ -51,6 +51,7 @@ export async function createClaudeSlashCommands(workingDir) {
     // Create claude-flow specific commands
     await createClaudeFlowCommands(workingDir);
   } catch (err) {
-    console.log(`  ⚠️  Could not create Claude Code slash commands: ${err.message}`);
+    // Legacy slash command creation - silently skip if it fails
+    // SPARC slash commands are already created successfully
   }
 }

package/src/cli/simple-commands/init/index.js

@@ -299,7 +299,8 @@ export async function initCommand(subArgs, flags) {
               await createClaudeSlashCommands(workingDir);
             }
           } catch (err) {
-            printWarning(`Could not create Claude Code slash commands: ${err.message}`);
+            // Legacy slash command creation - silently skip if it fails
+            // SPARC slash commands are already created successfully above
           }
         }
       }
@@ -1069,7 +1070,7 @@ ${commands.map((cmd) => `- [${cmd}](./${cmd}.md)`).join('\n')}
     }
 
     // Create helper scripts
-    const helpers = ['setup-mcp.sh', 'quick-start.sh', 'github-setup.sh'];
+    const helpers = ['setup-mcp.sh', 'quick-start.sh', 'github-setup.sh', 'github-safe.js'];
     for (const helper of helpers) {
       if (!dryRun) {
         const content = createHelperScript(helper);
@@ -1308,17 +1309,20 @@ ${commands.map((cmd) => `- [${cmd}](./${cmd}.md)`).join('\n')}
     console.log('\n📚 Quick Start:');
     if (isClaudeCodeInstalled()) {
       console.log('1. View available commands: ls .claude/commands/');
-      console.log('2. Start a swarm: npx claude-flow swarm init');
-      console.log('3. Use MCP tools in Claude Code for enhanced coordination');
+      console.log('2. Start a swarm: npx claude-flow@alpha swarm "your objective" --claude');
+      console.log('3. Use hive-mind: npx claude-flow@alpha hive-mind spawn "command" --claude');
+      console.log('4. Use MCP tools in Claude Code for enhanced coordination');
     } else {
       console.log('1. Install Claude Code: npm install -g @anthropic-ai/claude-code');
       console.log('2. Add MCP servers (see instructions above)');
       console.log('3. View available commands: ls .claude/commands/');
-      console.log('4. Start a swarm: npx claude-flow swarm init');
+      console.log('4. Start a swarm: npx claude-flow@alpha swarm "your objective" --claude');
+      console.log('5. Use hive-mind: npx claude-flow@alpha hive-mind spawn "command" --claude');
     }
     console.log('\n💡 Tips:');
     console.log('• Check .claude/commands/ for detailed documentation');
     console.log('• Use --help with any command for options');
+    console.log('• Run commands with --claude flag for best Claude Code integration');
     console.log('• Enable GitHub integration with .claude/helpers/github-setup.sh');
   } catch (err) {
     printError(`Failed to initialize Claude Flow v2.0.0: ${err.message}`);

package/src/cli/simple-commands/init/template-copier.js

@@ -311,7 +311,7 @@ async function copyHelperScripts(templatesDir, targetDir, options, results) {
       await fs.mkdir(helpersDir, { recursive: true });
     }
 
-    const helpers = ['setup-mcp.sh', 'quick-start.sh', 'github-setup.sh'];
+    const helpers = ['setup-mcp.sh', 'quick-start.sh', 'github-setup.sh', 'github-safe.js'];
     const { createHelperScript } = await import('./templates/enhanced-templates.js');
     
     for (const helper of helpers) {

package/src/cli/simple-commands/init/templates/enhanced-templates.js

@@ -1061,6 +1061,113 @@ echo "  - npx claude-flow github swarm"
 echo "  - npx claude-flow repo analyze"
 echo "  - npx claude-flow pr enhance"
 echo "  - npx claude-flow issue triage"
+`,
+    'github-safe.js': `#!/usr/bin/env node
+
+/**
+ * Safe GitHub CLI Helper
+ * Prevents timeout issues when using gh commands with special characters
+ * 
+ * Usage:
+ *   ./github-safe.js issue comment 123 "Message with \`backticks\`"
+ *   ./github-safe.js pr create --title "Title" --body "Complex body"
+ */
+
+import { execSync } from 'child_process';
+import { writeFileSync, unlinkSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { randomBytes } from 'crypto';
+
+const args = process.argv.slice(2);
+
+if (args.length < 2) {
+  console.log(\`
+Safe GitHub CLI Helper
+
+Usage:
+  ./github-safe.js issue comment <number> <body>
+  ./github-safe.js pr comment <number> <body>
+  ./github-safe.js issue create --title <title> --body <body>
+  ./github-safe.js pr create --title <title> --body <body>
+
+This helper prevents timeout issues with special characters like:
+- Backticks in code examples
+- Command substitution \\$(...)
+- Directory paths
+- Special shell characters
+\`);
+  process.exit(1);
+}
+
+const [command, subcommand, ...restArgs] = args;
+
+// Handle commands that need body content
+if ((command === 'issue' || command === 'pr') && 
+    (subcommand === 'comment' || subcommand === 'create')) {
+  
+  let bodyIndex = -1;
+  let body = '';
+  
+  if (subcommand === 'comment' && restArgs.length >= 2) {
+    // Simple format: github-safe.js issue comment 123 "body"
+    body = restArgs[1];
+    bodyIndex = 1;
+  } else {
+    // Flag format: --body "content" 
+    bodyIndex = restArgs.indexOf('--body');
+    if (bodyIndex !== -1 && bodyIndex < restArgs.length - 1) {
+      body = restArgs[bodyIndex + 1];
+    }
+  }
+  
+  if (body) {
+    // Use temporary file for body content
+    const tmpFile = join(tmpdir(), \`gh-body-\${randomBytes(8).toString('hex')}.tmp\`);
+    
+    try {
+      writeFileSync(tmpFile, body, 'utf8');
+      
+      // Build new command with --body-file
+      const newArgs = [...restArgs];
+      if (subcommand === 'comment' && bodyIndex === 1) {
+        // Replace body with --body-file
+        newArgs[1] = '--body-file';
+        newArgs.push(tmpFile);
+      } else if (bodyIndex !== -1) {
+        // Replace --body with --body-file
+        newArgs[bodyIndex] = '--body-file';
+        newArgs[bodyIndex + 1] = tmpFile;
+      }
+      
+      // Execute safely
+      const ghCommand = \`gh \${command} \${subcommand} \${newArgs.join(' ')}\`;
+      console.log(\`Executing: \${ghCommand}\`);
+      
+      const result = execSync(ghCommand, { 
+        stdio: 'inherit',
+        timeout: 30000 // 30 second timeout
+      });
+      
+    } catch (error) {
+      console.error('Error:', error.message);
+      process.exit(1);
+    } finally {
+      // Clean up
+      try {
+        unlinkSync(tmpFile);
+      } catch (e) {
+        // Ignore cleanup errors
+      }
+    }
+  } else {
+    // No body content, execute normally
+    execSync(\`gh \${args.join(' ')}\`, { stdio: 'inherit' });
+  }
+} else {
+  // Other commands, execute normally
+  execSync(\`gh \${args.join(' ')}\`, { stdio: 'inherit' });
+}
 `,
   };
 

package/src/cli/simple-commands/init/templates/github-safe.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+
+/**
+ * Safe GitHub CLI Helper
+ * Prevents timeout issues when using gh commands with special characters
+ * 
+ * Usage:
+ *   ./github-safe.js issue comment 123 "Message with `backticks`"
+ *   ./github-safe.js pr create --title "Title" --body "Complex body"
+ */
+
+import { execSync } from 'child_process';
+import { writeFileSync, unlinkSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { randomBytes } from 'crypto';
+
+const args = process.argv.slice(2);
+
+if (args.length < 2) {
+  console.log(`
+Safe GitHub CLI Helper
+
+Usage:
+  ./github-safe.js issue comment <number> <body>
+  ./github-safe.js pr comment <number> <body>
+  ./github-safe.js issue create --title <title> --body <body>
+  ./github-safe.js pr create --title <title> --body <body>
+
+This helper prevents timeout issues with special characters like:
+- Backticks in code examples
+- Command substitution \$(...)
+- Directory paths
+- Special shell characters
+`);
+  process.exit(1);
+}
+
+const [command, subcommand, ...restArgs] = args;
+
+// Handle commands that need body content
+if ((command === 'issue' || command === 'pr') && 
+    (subcommand === 'comment' || subcommand === 'create')) {
+  
+  let bodyIndex = -1;
+  let body = '';
+  
+  if (subcommand === 'comment' && restArgs.length >= 2) {
+    // Simple format: github-safe.js issue comment 123 "body"
+    body = restArgs[1];
+    bodyIndex = 1;
+  } else {
+    // Flag format: --body "content" 
+    bodyIndex = restArgs.indexOf('--body');
+    if (bodyIndex !== -1 && bodyIndex < restArgs.length - 1) {
+      body = restArgs[bodyIndex + 1];
+    }
+  }
+  
+  if (body) {
+    // Use temporary file for body content
+    const tmpFile = join(tmpdir(), `gh-body-${randomBytes(8).toString('hex')}.tmp`);
+    
+    try {
+      writeFileSync(tmpFile, body, 'utf8');
+      
+      // Build new command with --body-file
+      const newArgs = [...restArgs];
+      if (subcommand === 'comment' && bodyIndex === 1) {
+        // Replace body with --body-file
+        newArgs[1] = '--body-file';
+        newArgs.push(tmpFile);
+      } else if (bodyIndex !== -1) {
+        // Replace --body with --body-file
+        newArgs[bodyIndex] = '--body-file';
+        newArgs[bodyIndex + 1] = tmpFile;
+      }
+      
+      // Execute safely
+      const ghCommand = `gh ${command} ${subcommand} ${newArgs.join(' ')}`;
+      console.log(`Executing: ${ghCommand}`);
+      
+      const result = execSync(ghCommand, { 
+        stdio: 'inherit',
+        timeout: 30000 // 30 second timeout
+      });
+      
+    } catch (error) {
+      console.error('Error:', error.message);
+      process.exit(1);
+    } finally {
+      // Clean up
+      try {
+        unlinkSync(tmpFile);
+      } catch (e) {
+        // Ignore cleanup errors
+      }
+    }
+  } else {
+    // No body content, execute normally
+    execSync(`gh ${args.join(' ')}`, { stdio: 'inherit' });
+  }
+} else {
+  // Other commands, execute normally
+  execSync(`gh ${args.join(' ')}`, { stdio: 'inherit' });
+}

package/src/constants/agent-types.ts

@@ -1,37 +1,56 @@
 /**
- * Central source of truth for agent types
- * This file ensures consistency across TypeScript types and runtime validation
+ * Agent Types - Dynamic loading from .claude/agents/ directory
+ * This file provides type-safe access to dynamically loaded agent definitions
  */
 
-export const AGENT_TYPES = {
-  COORDINATOR: 'coordinator',
-  RESEARCHER: 'researcher',
-  CODER: 'coder',
-  ANALYST: 'analyst',
-  ARCHITECT: 'architect',
-  TESTER: 'tester',
-  REVIEWER: 'reviewer',
-  OPTIMIZER: 'optimizer',
-  DOCUMENTER: 'documenter',
-  MONITOR: 'monitor',
-  SPECIALIST: 'specialist',
+import { getAvailableAgentTypes, isValidAgentType as validateAgentType } from '../agents/agent-loader.js';
+
+// Dynamic agent type - will be a string that matches available agents
+export type AgentType = string;
+
+// Legacy agent type mapping for backward compatibility
+export const LEGACY_AGENT_MAPPING = {
+  analyst: 'code-analyzer',
+  coordinator: 'task-orchestrator', 
+  optimizer: 'perf-analyzer',
+  documenter: 'api-docs',
+  monitor: 'performance-benchmarker',
+  specialist: 'system-architect',
+  architect: 'system-architect',
 } as const;
 
-export type AgentType = (typeof AGENT_TYPES)[keyof typeof AGENT_TYPES];
+/**
+ * Get all valid agent types dynamically
+ */
+export async function getValidAgentTypes(): Promise<string[]> {
+  return await getAvailableAgentTypes();
+}
 
-// Array of all valid agent types for runtime validation
-export const VALID_AGENT_TYPES = Object.values(AGENT_TYPES);
+/**
+ * Helper function to validate agent type
+ */
+export async function isValidAgentType(type: string): Promise<boolean> {
+  return await validateAgentType(type);
+}
 
-// JSON Schema for agent type validation
-export const AGENT_TYPE_SCHEMA = {
-  type: 'string',
-  enum: VALID_AGENT_TYPES,
-  description: 'Type of AI agent',
-};
+/**
+ * Resolve legacy agent types to current equivalents
+ */
+export function resolveLegacyAgentType(legacyType: string): string {
+  const mapped = LEGACY_AGENT_MAPPING[legacyType as keyof typeof LEGACY_AGENT_MAPPING];
+  return mapped || legacyType;
+}
 
-// Helper function to validate agent type
-export function isValidAgentType(type: string): type is AgentType {
-  return VALID_AGENT_TYPES.includes(type as AgentType);
+/**
+ * Create JSON Schema for agent type validation (async)
+ */
+export async function getAgentTypeSchema() {
+  const validTypes = await getValidAgentTypes();
+  return {
+    type: 'string',
+    enum: validTypes,
+    description: 'Type of specialized AI agent',
+  };
 }
 
 // Strategy types

package/src/mcp/claude-flow-tools.ts

@@ -4,17 +4,49 @@
 
 import type { MCPTool, MCPContext, AgentProfile, Task, MemoryEntry } from '../utils/types.js';
 import type { ILogger } from '../core/logger.js';
+import { getAvailableAgentTypes, getAgentTypeSchema } from '../constants/agent-types.js';
 import type { Permissions } from './auth.js';
 
 export interface ClaudeFlowToolContext extends MCPContext {
   orchestrator?: any; // Reference to orchestrator instance
 }
 
+/**
+ * Enhance tool schema with dynamic agent types
+ */
+async function enhanceToolWithAgentTypes(tool: MCPTool): Promise<MCPTool> {
+  const availableTypes = await getAvailableAgentTypes();
+  
+  // Clone the tool to avoid modifying the original
+  const enhancedTool = JSON.parse(JSON.stringify(tool));
+  
+  // Find and populate enum fields for agent types
+  function addEnumToAgentTypeFields(obj: any) {
+    if (typeof obj !== 'object' || obj === null) return;
+    
+    for (const [key, value] of Object.entries(obj)) {
+      if (typeof value === 'object' && value !== null) {
+        // Check if this is an agent type field
+        if (key === 'type' || key === 'filterByType' || key === 'assignToAgentType') {
+          const field = value as any;
+          if (field.type === 'string' && field.description?.includes('loaded dynamically from .claude/agents/')) {
+            field.enum = availableTypes;
+          }
+        }
+        addEnumToAgentTypeFields(value);
+      }
+    }
+  }
+  
+  addEnumToAgentTypeFields(enhancedTool.inputSchema);
+  return enhancedTool;
+}
+
 /**
  * Create all Claude-Flow specific MCP tools
  */
-export function createClaudeFlowTools(logger: ILogger): MCPTool[] {
-  return [
+export async function createClaudeFlowTools(logger: ILogger): Promise<MCPTool[]> {
+  const tools = [
     // Agent management tools
     createSpawnAgentTool(logger),
     createListAgentsTool(logger),
@@ -55,6 +87,13 @@ export function createClaudeFlowTools(logger: ILogger): MCPTool[] {
     createListTerminalsTool(logger),
     createCreateTerminalTool(logger),
   ];
+
+  // Enhance tools with dynamic agent types
+  const enhancedTools = await Promise.all(
+    tools.map(tool => enhanceToolWithAgentTypes(tool))
+  );
+
+  return enhancedTools;
 }
 
 function createSpawnAgentTool(logger: ILogger): MCPTool {
@@ -66,20 +105,8 @@ function createSpawnAgentTool(logger: ILogger): MCPTool {
       properties: {
         type: {
           type: 'string',
-          enum: [
-            'coordinator',
-            'researcher',
-            'coder',
-            'analyst',
-            'architect',
-            'tester',
-            'reviewer',
-            'optimizer',
-            'documenter',
-            'monitor',
-            'specialist',
-          ],
-          description: 'Type of agent to spawn',
+          // Note: enum will be populated dynamically at runtime
+          description: 'Type of specialized agent to spawn (loaded dynamically from .claude/agents/)',
         },
         name: {
           type: 'string',
@@ -161,20 +188,8 @@ function createListAgentsTool(logger: ILogger): MCPTool {
         },
         filterByType: {
           type: 'string',
-          enum: [
-            'coordinator',
-            'researcher',
-            'coder',
-            'analyst',
-            'architect',
-            'tester',
-            'reviewer',
-            'optimizer',
-            'documenter',
-            'monitor',
-            'specialist',
-          ],
-          description: 'Filter agents by type',
+          // Note: enum will be populated dynamically at runtime
+          description: 'Filter agents by type (loaded dynamically from .claude/agents/)',
         },
       },
     },
@@ -317,20 +332,8 @@ function createCreateTaskTool(logger: ILogger): MCPTool {
         },
         assignToAgentType: {
           type: 'string',
-          enum: [
-            'coordinator',
-            'researcher',
-            'coder',
-            'analyst',
-            'architect',
-            'tester',
-            'reviewer',
-            'optimizer',
-            'documenter',
-            'monitor',
-            'specialist',
-          ],
-          description: 'Type of agent to assign the task to',
+          // Note: enum will be populated dynamically at runtime
+          description: 'Type of specialized agent to assign the task to (loaded dynamically from .claude/agents/)',
         },
         input: {
           type: 'object',

package/src/utils/github-cli-safe.js

@@ -0,0 +1,201 @@
+/**
+ * Safe GitHub CLI command execution utilities
+ * Prevents shell injection and timeout issues with special characters
+ */
+
+import { promises as fs } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { randomBytes } from 'crypto';
+import { spawn } from 'child_process';
+
+/**
+ * Execute GitHub CLI command with safe body content handling
+ * @param {string} command - The gh command (e.g., 'issue comment')
+ * @param {string} target - Target (issue/PR number or repo)
+ * @param {string} body - Body content that may contain special characters
+ * @param {Object} options - Additional options
+ * @returns {Promise<string>} - Command output
+ */
+export async function safeGhCommand(command, target, body, options = {}) {
+  const tmpFile = join(tmpdir(), `gh-body-${randomBytes(8).toString('hex')}.tmp`);
+  
+  try {
+    // Write body content to temporary file
+    await fs.writeFile(tmpFile, body, 'utf8');
+    
+    // Build command arguments
+    const args = command.split(' ');
+    args.push(target);
+    args.push('--body-file', tmpFile);
+    
+    // Add any additional options
+    Object.entries(options).forEach(([key, value]) => {
+      args.push(`--${key}`, value);
+    });
+    
+    // Execute command with timeout
+    const result = await executeWithTimeout('gh', args, options.timeout || 30000);
+    return result;
+  } finally {
+    // Clean up temp file
+    try {
+      await fs.unlink(tmpFile);
+    } catch (err) {
+      // Ignore cleanup errors
+    }
+  }
+}
+
+/**
+ * Execute command with timeout and proper cleanup
+ * @param {string} command - Command to execute
+ * @param {string[]} args - Command arguments
+ * @param {number} timeout - Timeout in milliseconds
+ * @returns {Promise<string>} - Command output
+ */
+function executeWithTimeout(command, args, timeout) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      shell: false, // Important: don't use shell
+    });
+    
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+    
+    // Set timeout
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill('SIGTERM');
+      setTimeout(() => child.kill('SIGKILL'), 5000); // Force kill after 5s
+    }, timeout);
+    
+    child.stdout.on('data', (data) => {
+      stdout += data.toString();
+    });
+    
+    child.stderr.on('data', (data) => {
+      stderr += data.toString();
+    });
+    
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      
+      if (timedOut) {
+        reject(new Error(`Command timed out after ${timeout}ms`));
+      } else if (code !== 0) {
+        reject(new Error(`Command failed with exit code ${code}: ${stderr}`));
+      } else {
+        resolve(stdout.trim());
+      }
+    });
+    
+    child.on('error', (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+  });
+}
+
+/**
+ * Safe methods for common GitHub CLI operations
+ */
+export const gh = {
+  /**
+   * Create issue comment safely
+   * @param {number|string} issue - Issue number
+   * @param {string} body - Comment body
+   * @param {Object} options - Additional options
+   */
+  async issueComment(issue, body, options = {}) {
+    return safeGhCommand('issue comment', issue.toString(), body, options);
+  },
+  
+  /**
+   * Create PR comment safely
+   * @param {number|string} pr - PR number
+   * @param {string} body - Comment body
+   * @param {Object} options - Additional options
+   */
+  async prComment(pr, body, options = {}) {
+    return safeGhCommand('pr comment', pr.toString(), body, options);
+  },
+  
+  /**
+   * Create issue safely
+   * @param {Object} params - Issue parameters
+   */
+  async createIssue({ title, body, labels = [], assignees = [] }) {
+    const tmpFile = join(tmpdir(), `gh-issue-${randomBytes(8).toString('hex')}.tmp`);
+    
+    try {
+      await fs.writeFile(tmpFile, body, 'utf8');
+      
+      const args = ['issue', 'create', '--title', title, '--body-file', tmpFile];
+      
+      if (labels.length > 0) {
+        args.push('--label', labels.join(','));
+      }
+      
+      if (assignees.length > 0) {
+        args.push('--assignee', assignees.join(','));
+      }
+      
+      return await executeWithTimeout('gh', args, 30000);
+    } finally {
+      try {
+        await fs.unlink(tmpFile);
+      } catch (err) {
+        // Ignore cleanup errors
+      }
+    }
+  },
+  
+  /**
+   * Create PR safely
+   * @param {Object} params - PR parameters
+   */
+  async createPR({ title, body, base = 'main', head, draft = false }) {
+    const tmpFile = join(tmpdir(), `gh-pr-${randomBytes(8).toString('hex')}.tmp`);
+    
+    try {
+      await fs.writeFile(tmpFile, body, 'utf8');
+      
+      const args = ['pr', 'create', '--title', title, '--body-file', tmpFile, '--base', base];
+      
+      if (head) {
+        args.push('--head', head);
+      }
+      
+      if (draft) {
+        args.push('--draft');
+      }
+      
+      return await executeWithTimeout('gh', args, 30000);
+    } finally {
+      try {
+        await fs.unlink(tmpFile);
+      } catch (err) {
+        // Ignore cleanup errors
+      }
+    }
+  }
+};
+
+/**
+ * Example usage:
+ * 
+ * import { gh } from './github-cli-safe.js';
+ * 
+ * // Safe issue comment with special characters
+ * await gh.issueComment(123, 'Code: `npm install` and $(echo test)');
+ * 
+ * // Safe PR creation with complex body
+ * await gh.createPR({
+ *   title: 'Fix: Handle special characters',
+ *   body: 'This fixes issues with `backticks` and .claude/agents/ paths',
+ *   base: 'main'
+ * });
+ */