ultra-dex 2.2.0 → 3.1.0

package/lib/swarm/tiers.js

@@ -0,0 +1,485 @@
+/**
+ * Ultra-Dex Agent Tier System v3.0
+ * Defines the hierarchical structure of agents and their dependencies.
+ */
+
+// ============================================================================
+// TIER DEFINITIONS
+// ============================================================================
+
+/**
+ * Tier structure for all 16 agents.
+ * Lower tier numbers indicate higher-level strategic roles.
+ */
+export const TIERS = {
+  META: {
+    id: 0,
+    name: 'Meta Orchestration',
+    description: 'Coordinates all other agents',
+    agents: ['orchestrator']
+  },
+  LEADERSHIP: {
+    id: 1,
+    name: 'Leadership',
+    description: 'Strategic planning and technology decisions',
+    agents: ['cto', 'planner', 'research']
+  },
+  DEVELOPMENT: {
+    id: 2,
+    name: 'Development',
+    description: 'Core implementation of features',
+    agents: ['backend', 'frontend', 'database']
+  },
+  SECURITY: {
+    id: 3,
+    name: 'Security',
+    description: 'Authentication, authorization, and security audits',
+    agents: ['auth', 'security']
+  },
+  DEVOPS: {
+    id: 4,
+    name: 'DevOps',
+    description: 'Deployment and infrastructure management',
+    agents: ['devops']
+  },
+  QUALITY: {
+    id: 5,
+    name: 'Quality',
+    description: 'Testing, debugging, and code review',
+    agents: ['testing', 'reviewer', 'debugger', 'documentation']
+  },
+  SPECIALIST: {
+    id: 6,
+    name: 'Specialist',
+    description: 'Advanced optimization and code improvement',
+    agents: ['performance', 'refactoring']
+  }
+};
+
+// ============================================================================
+// AGENT REGISTRY
+// ============================================================================
+
+/**
+ * Complete agent registry with metadata.
+ */
+export const AGENTS = {
+  // Tier 0: Meta
+  orchestrator: {
+    name: 'Orchestrator',
+    tier: 0,
+    tierName: 'Meta Orchestration',
+    role: 'Coordinate all agents for complete features',
+    invocation: '@orchestrator',
+    file: '0-orchestration/orchestrator.md',
+    capabilities: ['task_decomposition', 'agent_selection', 'pipeline_execution', 'result_synthesis'],
+    canInvoke: ['all']
+  },
+
+  // Tier 1: Leadership
+  cto: {
+    name: 'CTO',
+    tier: 1,
+    tierName: 'Leadership',
+    role: 'Architecture & tech stack decisions',
+    invocation: '@cto',
+    file: '1-leadership/cto.md',
+    capabilities: ['architecture_design', 'tech_selection', 'system_design'],
+    canInvoke: ['research']
+  },
+  planner: {
+    name: 'Planner',
+    tier: 1,
+    tierName: 'Leadership',
+    role: 'Task breakdown & sprint planning',
+    invocation: '@planner',
+    file: '1-leadership/planner.md',
+    capabilities: ['task_breakdown', 'estimation', 'prioritization'],
+    canInvoke: []
+  },
+  research: {
+    name: 'Research',
+    tier: 1,
+    tierName: 'Leadership',
+    role: 'Technology evaluation & comparison',
+    invocation: '@research',
+    file: '1-leadership/research.md',
+    capabilities: ['technology_evaluation', 'comparison', 'recommendations'],
+    canInvoke: []
+  },
+
+  // Tier 2: Development
+  backend: {
+    name: 'Backend',
+    tier: 2,
+    tierName: 'Development',
+    role: 'API & server implementation',
+    invocation: '@backend',
+    file: '2-development/backend.md',
+    capabilities: ['api_development', 'business_logic', 'integrations'],
+    canInvoke: ['database']
+  },
+  frontend: {
+    name: 'Frontend',
+    tier: 2,
+    tierName: 'Development',
+    role: 'UI & component implementation',
+    invocation: '@frontend',
+    file: '2-development/frontend.md',
+    capabilities: ['ui_development', 'components', 'state_management'],
+    canInvoke: []
+  },
+  database: {
+    name: 'Database',
+    tier: 2,
+    tierName: 'Development',
+    role: 'Schema design & query optimization',
+    invocation: '@database',
+    file: '2-development/database.md',
+    capabilities: ['schema_design', 'migrations', 'query_optimization'],
+    canInvoke: []
+  },
+
+  // Tier 3: Security
+  auth: {
+    name: 'Auth',
+    tier: 3,
+    tierName: 'Security',
+    role: 'Authentication & authorization',
+    invocation: '@auth',
+    file: '3-security/auth.md',
+    capabilities: ['authentication', 'authorization', 'session_management'],
+    canInvoke: ['backend', 'database']
+  },
+  security: {
+    name: 'Security',
+    tier: 3,
+    tierName: 'Security',
+    role: 'Security audits & vulnerability fixes',
+    invocation: '@security',
+    file: '3-security/security.md',
+    capabilities: ['security_audit', 'vulnerability_detection', 'hardening'],
+    canInvoke: []
+  },
+
+  // Tier 4: DevOps
+  devops: {
+    name: 'DevOps',
+    tier: 4,
+    tierName: 'DevOps',
+    role: 'Deployment & infrastructure',
+    invocation: '@devops',
+    file: '4-devops/devops.md',
+    capabilities: ['deployment', 'ci_cd', 'infrastructure', 'monitoring'],
+    canInvoke: []
+  },
+
+  // Tier 5: Quality
+  testing: {
+    name: 'Testing',
+    tier: 5,
+    tierName: 'Quality',
+    role: 'QA & test automation',
+    invocation: '@testing',
+    file: '5-quality/testing.md',
+    capabilities: ['unit_testing', 'integration_testing', 'e2e_testing'],
+    canInvoke: []
+  },
+  reviewer: {
+    name: 'Reviewer',
+    tier: 5,
+    tierName: 'Quality',
+    role: 'Code review & quality checks',
+    invocation: '@reviewer',
+    file: '5-quality/reviewer.md',
+    capabilities: ['code_review', 'best_practices', 'quality_gates'],
+    canInvoke: []
+  },
+  debugger: {
+    name: 'Debugger',
+    tier: 5,
+    tierName: 'Quality',
+    role: 'Bug investigation & fixes',
+    invocation: '@debugger',
+    file: '5-quality/debugger.md',
+    capabilities: ['debugging', 'root_cause_analysis', 'bug_fixing'],
+    canInvoke: ['backend', 'frontend', 'database']
+  },
+  documentation: {
+    name: 'Documentation',
+    tier: 5,
+    tierName: 'Quality',
+    role: 'Technical writing & docs maintenance',
+    invocation: '@documentation',
+    file: '5-quality/documentation.md',
+    capabilities: ['technical_writing', 'api_docs', 'user_guides'],
+    canInvoke: []
+  },
+
+  // Tier 6: Specialist
+  performance: {
+    name: 'Performance',
+    tier: 6,
+    tierName: 'Specialist',
+    role: 'Performance optimization',
+    invocation: '@performance',
+    file: '6-specialist/performance.md',
+    capabilities: ['profiling', 'optimization', 'caching', 'load_testing'],
+    canInvoke: ['backend', 'frontend', 'database']
+  },
+  refactoring: {
+    name: 'Refactoring',
+    tier: 6,
+    tierName: 'Specialist',
+    role: 'Code quality & design patterns',
+    invocation: '@refactoring',
+    file: '6-specialist/refactoring.md',
+    capabilities: ['code_cleanup', 'design_patterns', 'architecture_improvement'],
+    canInvoke: ['backend', 'frontend']
+  }
+};
+
+// ============================================================================
+// TIER DEPENDENCY GRAPH
+// ============================================================================
+
+/**
+ * Defines standard execution flow between tiers.
+ * This represents the typical order of operations for a full feature.
+ */
+export const TIER_FLOW = {
+  standard: [
+    { tier: 1, phase: 'Planning', required: true },
+    { tier: 2, phase: 'Implementation', required: true },
+    { tier: 3, phase: 'Security', required: false },
+    { tier: 5, phase: 'Quality', required: true },
+    { tier: 4, phase: 'Deployment', required: false },
+    { tier: 6, phase: 'Optimization', required: false }
+  ],
+  hotfix: [
+    { tier: 5, phase: 'Debug', agents: ['debugger'], required: true },
+    { tier: 5, phase: 'Test', agents: ['testing'], required: true },
+    { tier: 4, phase: 'Deploy', agents: ['devops'], required: true }
+  ],
+  optimization: [
+    { tier: 6, phase: 'Optimize', required: true },
+    { tier: 5, phase: 'Test', agents: ['testing'], required: true },
+    { tier: 5, phase: 'Review', agents: ['reviewer'], required: true }
+  ]
+};
+
+/**
+ * Agent dependency graph - which agents depend on outputs from others.
+ */
+export const AGENT_DEPENDENCIES = {
+  // Leadership tier has no dependencies (entry points)
+  planner: [],
+  cto: ['planner'],
+  research: ['planner'],
+
+  // Development depends on leadership decisions
+  database: ['cto'],
+  backend: ['cto', 'database'],
+  frontend: ['cto', 'backend'],
+
+  // Security depends on implementation
+  auth: ['backend', 'database'],
+  security: ['backend', 'frontend', 'auth'],
+
+  // Quality depends on implementation
+  testing: ['backend', 'frontend'],
+  reviewer: ['backend', 'frontend', 'testing'],
+  debugger: [],  // Can be invoked anytime
+  documentation: ['backend', 'frontend'],
+
+  // DevOps depends on quality approval
+  devops: ['testing', 'reviewer'],
+
+  // Specialist can run after implementation
+  performance: ['backend', 'frontend'],
+  refactoring: ['backend', 'frontend']
+};
+
+// ============================================================================
+// UTILITY FUNCTIONS
+// ============================================================================
+
+/**
+ * Get agent by name.
+ */
+export function getAgent(name) {
+  const normalized = name.toLowerCase().replace('@', '');
+  return AGENTS[normalized] || null;
+}
+
+/**
+ * Get all agents in a tier.
+ */
+export function getAgentsByTier(tierId) {
+  return Object.values(AGENTS).filter(agent => agent.tier === tierId);
+}
+
+/**
+ * Get tier by ID.
+ */
+export function getTier(tierId) {
+  return Object.values(TIERS).find(tier => tier.id === tierId) || null;
+}
+
+/**
+ * Get tier by agent name.
+ */
+export function getTierForAgent(agentName) {
+  const agent = getAgent(agentName);
+  return agent ? getTier(agent.tier) : null;
+}
+
+/**
+ * Get dependencies for an agent.
+ */
+export function getAgentDependencies(agentName) {
+  const normalized = agentName.toLowerCase().replace('@', '');
+  return AGENT_DEPENDENCIES[normalized] || [];
+}
+
+/**
+ * Check if agent A can invoke agent B.
+ */
+export function canInvoke(agentA, agentB) {
+  const a = getAgent(agentA);
+  if (!a) return false;
+  if (a.canInvoke.includes('all')) return true;
+  return a.canInvoke.includes(agentB.toLowerCase().replace('@', ''));
+}
+
+/**
+ * Get execution order for a set of agents based on dependencies.
+ */
+export function getExecutionOrder(agentNames) {
+  const normalized = agentNames.map(n => n.toLowerCase().replace('@', ''));
+  const visited = new Set();
+  const order = [];
+
+  function visit(agent) {
+    if (visited.has(agent)) return;
+    visited.add(agent);
+
+    const deps = AGENT_DEPENDENCIES[agent] || [];
+    for (const dep of deps) {
+      if (normalized.includes(dep)) {
+        visit(dep);
+      }
+    }
+    order.push(agent);
+  }
+
+  for (const agent of normalized) {
+    visit(agent);
+  }
+
+  return order;
+}
+
+/**
+ * Identify parallel execution opportunities.
+ */
+export function findParallelGroups(agentNames) {
+  const order = getExecutionOrder(agentNames);
+  const groups = [];
+  const scheduled = new Set();
+
+  while (scheduled.size < order.length) {
+    const group = [];
+    
+    for (const agent of order) {
+      if (scheduled.has(agent)) continue;
+      
+      const deps = AGENT_DEPENDENCIES[agent] || [];
+      const depsInList = deps.filter(d => order.includes(d));
+      const depsMet = depsInList.every(d => scheduled.has(d));
+      
+      if (depsMet) {
+        group.push(agent);
+      }
+    }
+
+    if (group.length === 0) break; // Prevent infinite loop
+    
+    for (const agent of group) {
+      scheduled.add(agent);
+    }
+    groups.push(group);
+  }
+
+  return groups;
+}
+
+/**
+ * Generate a tier summary for display.
+ */
+export function getTierSummary() {
+  return Object.values(TIERS).map(tier => ({
+    id: tier.id,
+    name: tier.name,
+    description: tier.description,
+    agentCount: tier.agents.length,
+    agents: tier.agents.map(a => AGENTS[a]?.name || a)
+  }));
+}
+
+/**
+ * Validate a pipeline for dependency violations.
+ */
+export function validatePipeline(pipeline) {
+  const errors = [];
+  const completed = new Set();
+
+  for (let i = 0; i < pipeline.length; i++) {
+    const step = pipeline[i];
+    const agent = step.agent?.toLowerCase().replace('@', '');
+    const deps = AGENT_DEPENDENCIES[agent] || [];
+
+    for (const dep of deps) {
+      // Check if dependency is in pipeline and comes before
+      const depIndex = pipeline.findIndex(s => 
+        s.agent?.toLowerCase().replace('@', '') === dep
+      );
+      
+      if (depIndex > i) {
+        errors.push({
+          step: i + 1,
+          agent,
+          error: `Depends on ${dep} which is scheduled after (step ${depIndex + 1})`
+        });
+      }
+    }
+
+    completed.add(agent);
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+
+// ============================================================================
+// EXPORTS
+// ============================================================================
+
+export default {
+  TIERS,
+  AGENTS,
+  TIER_FLOW,
+  AGENT_DEPENDENCIES,
+  getAgent,
+  getAgentsByTier,
+  getTier,
+  getTierForAgent,
+  getAgentDependencies,
+  canInvoke,
+  getExecutionOrder,
+  findParallelGroups,
+  getTierSummary,
+  validatePipeline
+};

package/lib/templates/context.js

@@ -1,4 +1,4 @@
-import { githubBlobUrl, githubTreeUrl } from '../config/urls.js';
+import { githubBlobUrl, githubWebUrl } from '../config/urls.js';
 
 export const CONTEXT_TEMPLATE = `# {{PROJECT_NAME}} - Context
 
@@ -21,6 +21,6 @@ export const CONTEXT_TEMPLATE = `# {{PROJECT_NAME}} - Context
 Setting up the implementation plan.
 
 ## Resources
-- [Ultra-Dex Template](${githubTreeUrl('')})
+- [Ultra-Dex Template](${githubWebUrl()})
 - [TaskFlow Example](${githubBlobUrl('@%20Ultra%20DeX/Saas%20plan/Examples/TaskFlow-Complete.md')})
 `;

package/lib/templates/custom-agent.md

@@ -0,0 +1,10 @@
+---
+name: {{name}}
+tier: {{tier}}
+role: {{role}}
+---
+# {{name}} Agent
+## Expertise
+{{expertise}}
+## System Prompt
+{{prompt}}

package/lib/utils/fallback.js

@@ -26,11 +26,13 @@ export async function copyWithFallback(primaryPath, fallbackPath, destinationPat
 
 export async function listWithFallback(primaryPath, fallbackPath) {
   try {
-    return await fs.readdir(primaryPath);
+    const files = await fs.readdir(primaryPath);
+    return { files, sourcePath: primaryPath };
   } catch (primaryError) {
     if (!fallbackPath) {
       throw primaryError;
     }
-    return await fs.readdir(fallbackPath);
+    const files = await fs.readdir(fallbackPath);
+    return { files, sourcePath: fallbackPath };
   }
 }

package/lib/utils/files.js

@@ -21,47 +21,20 @@ export async function pathExists(targetPath, type = 'file') {
   }
 }
 
-export async function copyWithFallback({ primary, fallback, destination, onPrimaryMissing }) {
-  try {
-    await fs.copyFile(primary, destination);
-    return 'primary';
-  } catch (primaryError) {
-    if (onPrimaryMissing) {
-      onPrimaryMissing(primaryError);
-    }
-    if (!fallback) {
-      throw primaryError;
-    }
-    await fs.copyFile(fallback, destination);
-    return 'fallback';
-  }
-}
-
-export async function readWithFallback({ primary, fallback, encoding = 'utf-8' }) {
-  try {
-    return await fs.readFile(primary, encoding);
-  } catch (primaryError) {
-    if (!fallback) {
-      throw primaryError;
-    }
-    return await fs.readFile(fallback, encoding);
-  }
-}
-
 export function resolveAssetPath(basePath, relativePath) {
   return path.join(basePath, relativePath);
 }
 
-export async function copyDirectory(srcDir, destDir) {
-  await fs.mkdir(destDir, { recursive: true });
-  const entries = await fs.readdir(srcDir, { withFileTypes: true });
+export async function copyDirectory(sourceDir, targetDir) {
+  await fs.mkdir(targetDir, { recursive: true });
+  const entries = await fs.readdir(sourceDir, { withFileTypes: true });
   for (const entry of entries) {
-    const srcPath = path.join(srcDir, entry.name);
-    const destPath = path.join(destDir, entry.name);
+    const sourcePath = path.join(sourceDir, entry.name);
+    const targetPath = path.join(targetDir, entry.name);
     if (entry.isDirectory()) {
-      await copyDirectory(srcPath, destPath);
+      await copyDirectory(sourcePath, targetPath);
     } else if (entry.isFile()) {
-      await fs.copyFile(srcPath, destPath);
+      await fs.copyFile(sourcePath, targetPath);
     }
   }
 }

package/lib/utils/graph.js

@@ -0,0 +1,108 @@
+/**
+ * Graph Utility (CPG Implementation)
+ * Manages the Code Property Graph (CPG) for architectural memory
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import { glob } from 'glob';
+
+/**
+ * Build a simple Code Property Graph (CPG)
+ * Maps files, functions, and dependencies
+ */
+export async function buildGraph() {
+  const files = await glob('**/*.{js,ts,jsx,tsx}', { 
+    ignore: ['node_modules/**', '.git/**', 'dist/**', 'build/**'],
+    nodir: true 
+  });
+
+  const graph = {
+    nodes: [],
+    edges: [],
+    lastUpdated: new Date().toISOString()
+  };
+
+  for (const file of files) {
+    try {
+      const content = await fs.readFile(file, 'utf8');
+      const fileNode = {
+        id: file,
+        type: 'file',
+        path: file,
+        exports: [],
+        imports: []
+      };
+
+      // Naive parsing using Regex (Phase 2.1)
+      // In Phase 2.2+ this would use tree-sitter
+      
+      // Extract imports
+      const importRegex = /import\s+.*?\s+from\s+['"](.+?)['"]/g;
+      let match;
+      while ((match = importRegex.exec(content)) !== null) {
+        fileNode.imports.push(match[1]);
+        graph.edges.push({
+          source: file,
+          target: match[1],
+          type: 'depends_on'
+        });
+      }
+
+      // Extract function declarations
+      const funcRegex = /(?:export\s+)?(?:async\s+)?function\s+([a-zA-Z0-9_]+)/g;
+      while ((match = funcRegex.exec(content)) !== null) {
+        const funcName = match[1];
+        const funcId = `${file}:${funcName}`;
+        graph.nodes.push({
+          id: funcId,
+          type: 'function',
+          name: funcName,
+          parent: file
+        });
+        graph.edges.push({
+          source: funcId,
+          target: file,
+          type: 'contained_in'
+        });
+        fileNode.exports.push(funcName);
+      }
+
+      graph.nodes.push(fileNode);
+    } catch (e) {
+      // Skip files that can't be read
+    }
+  }
+
+  return graph;
+}
+
+/**
+ * Find the impact of changing a file
+ * @param {Object} graph - The CPG
+ * @param {string} filePath - The file being changed
+ */
+export function getImpactAnalysis(graph, filePath) {
+  const impactedBy = graph.edges
+    .filter(edge => edge.target === filePath || filePath.endsWith(edge.target))
+    .map(edge => edge.source);
+  
+  return [...new Set(impactedBy)];
+}
+
+/**
+ * Find structural truth (exact subgraph)
+ * @param {Object} graph - The CPG
+ * @param {string} query - Symbol name
+ */
+export function queryGraph(graph, query) {
+  return graph.nodes.filter(node => 
+    node.id.includes(query) || (node.name && node.name === query)
+  );
+}
+
+export default {
+  buildGraph,
+  getImpactAnalysis,
+  queryGraph
+};