@polymorphism-tech/morph-spec 2.3.0 → 3.0.0

package/src/lib/team-orchestrator.js

@@ -0,0 +1,322 @@
+/**
+ * @fileoverview Hierarchical Agent Teams Orchestrator
+ *
+ * Builds Agent Teams using 4-tier hierarchy:
+ * - Tier 1: Orchestrators (Team Lead in delegate mode)
+ * - Tier 2: Domain Leaders (Squad Leaders)
+ * - Tier 3: Specialists (Domain experts)
+ * - Tier 4: Validators (Run in hooks, not teammates)
+ *
+ * @module team-orchestrator
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * Load agents.json with hierarchical structure
+ * @param {string} projectPath - Root path of the project
+ * @returns {Promise<Object>} Parsed agents configuration
+ */
+async function loadAgentsConfig(projectPath) {
+  const agentsPath = path.join(projectPath, 'content/.morph/config/agents.json');
+  const content = await fs.readFile(agentsPath, 'utf8');
+  return JSON.parse(content);
+}
+
+/**
+ * Detect if Agent Teams should be spawned based on complexity
+ * @param {Object} options
+ * @param {string[]} options.activeAgents - Agent IDs detected for feature
+ * @param {string} options.complexity - Complexity level (trivial|low|medium|high|critical)
+ * @param {number} options.estimatedFiles - Estimated files to modify
+ * @param {boolean} options.multiDomain - Does feature span multiple domains?
+ * @returns {Object} { shouldSpawn: boolean, reason: string, recommendedMode: string }
+ */
+export function shouldSpawnAgentTeam(options) {
+  const { activeAgents = [], complexity, estimatedFiles = 0, multiDomain = false } = options;
+
+  // Never spawn for trivial/low complexity
+  if (complexity === 'trivial' || complexity === 'low') {
+    return {
+      shouldSpawn: false,
+      reason: 'Complexity too low - single session sufficient',
+      recommendedMode: 'single'
+    };
+  }
+
+  // Always spawn for critical complexity
+  if (complexity === 'critical') {
+    return {
+      shouldSpawn: true,
+      reason: 'Critical complexity - parallel coordination essential',
+      recommendedMode: 'tmux'
+    };
+  }
+
+  // Spawn if multi-domain (backend + frontend + infra)
+  if (multiDomain) {
+    return {
+      shouldSpawn: true,
+      reason: 'Multi-domain feature - benefits from parallel squads',
+      recommendedMode: 'auto'
+    };
+  }
+
+  // Spawn if 3+ independent modules (high file count)
+  if (estimatedFiles >= 15) {
+    return {
+      shouldSpawn: true,
+      reason: 'High file count - parallel implementation recommended',
+      recommendedMode: 'auto'
+    };
+  }
+
+  // Spawn if 5+ specialists active (indicates complex coordination)
+  if (activeAgents.length >= 5) {
+    return {
+      shouldSpawn: true,
+      reason: '5+ specialists active - team coordination beneficial',
+      recommendedMode: 'auto'
+    };
+  }
+
+  // Default: single session for medium complexity
+  return {
+    shouldSpawn: false,
+    reason: 'Medium complexity - single session with subagents OK',
+    recommendedMode: 'single'
+  };
+}
+
+/**
+ * Build hierarchical team structure from active agents
+ * @param {string[]} activeAgentIds - Agent IDs to include in team
+ * @param {Object} agentsConfig - Loaded agents.json
+ * @returns {Object} Team structure with lead, domain leaders, specialists
+ */
+export function buildTeamHierarchy(activeAgentIds, agentsConfig) {
+  const agents = agentsConfig.agents;
+  const activeAgents = activeAgentIds
+    .filter(id => !id.startsWith('_comment') && agents[id])
+    .map(id => ({ id, ...agents[id] }));
+
+  // Tier 1: Orchestrator (Team Lead)
+  const orchestrators = activeAgents.filter(a => a.tier === 1 && a.role === 'orchestrator');
+  const teamLead = orchestrators.find(a => a.id === 'standards-architect') || orchestrators[0];
+
+  // Tier 2: Domain Leaders
+  const domainLeaders = activeAgents.filter(a => a.tier === 2 && a.role === 'domain-leader');
+
+  // Tier 3: Specialists (group by domain)
+  const specialists = activeAgents.filter(a => a.tier === 3 && a.role === 'specialist');
+
+  // Tier 4: Validators (run in hooks, NOT teammates)
+  const validators = activeAgents.filter(a => a.tier === 4 && a.role === 'validator');
+
+  // Group specialists under their Domain Leaders
+  const squads = {};
+  domainLeaders.forEach(leader => {
+    const squadMembers = specialists.filter(specialist => {
+      // Check if specialist reports to this leader
+      return specialist.relationships?.reports_to === leader.id;
+    });
+
+    if (squadMembers.length > 0) {
+      squads[leader.id] = {
+        leader,
+        members: squadMembers
+      };
+    }
+  });
+
+  return {
+    teamLead,
+    squads,
+    validators, // Not in teammates, run as hooks
+    totalTeammates: 1 + domainLeaders.length + specialists.length // Lead + Leaders + Specialists
+  };
+}
+
+/**
+ * Generate teammate spawn instructions for Agent Teams
+ * @param {Object} teamHierarchy - Output from buildTeamHierarchy
+ * @param {string} featureName - Feature name
+ * @param {string} phase - Current MORPH phase
+ * @returns {Object[]} Array of teammate configs for Agent Teams
+ */
+export function generateTeammateConfigs(teamHierarchy, featureName, phase) {
+  const teammates = [];
+  const { teamLead, squads } = teamHierarchy;
+
+  // Add Team Lead (standards-architect in delegate mode)
+  if (teamLead && teamLead.teammate) {
+    teammates.push({
+      id: teamLead.id,
+      tier: teamLead.tier,
+      role: teamLead.teammate.role,
+      icon: teamLead.teammate.icon,
+      spawnPrompt: `${teamLead.teammate.spawn_prompt}
+
+Feature: ${featureName}
+Phase: ${phase}
+
+Your Domain Leaders:
+${Object.values(squads).map(s => `- ${s.leader.title} (${s.leader.id})`).join('\n')}
+
+DO NOT implement code yourself. Coordinate Domain Leaders, resolve conflicts, synthesize results.`
+    });
+  }
+
+  // Add Domain Leaders + their squad members
+  Object.entries(squads).forEach(([leaderId, squad]) => {
+    const leader = squad.leader;
+
+    // Add Domain Leader
+    if (leader.teammate) {
+      teammates.push({
+        id: leader.id,
+        tier: leader.tier,
+        role: leader.teammate.role,
+        icon: leader.teammate.icon,
+        spawnPrompt: `${leader.teammate.spawn_prompt}
+
+Feature: ${featureName}
+Phase: ${phase}
+
+Your Squad (${squad.members.length} specialists):
+${squad.members.map(m => `- ${m.title} (${m.id})`).join('\n')}
+
+Coordinate your specialists. Escalate conflicts to ${leader.relationships.escalates_to}.`
+      });
+    }
+
+    // Add Specialists in this squad
+    squad.members.forEach(specialist => {
+      if (specialist.teammate) {
+        teammates.push({
+          id: specialist.id,
+          tier: specialist.tier,
+          role: specialist.teammate.role,
+          icon: specialist.teammate.icon,
+          spawnPrompt: `${specialist.teammate.spawn_prompt}
+
+Feature: ${featureName}
+Phase: ${phase}
+
+Reports to: ${specialist.relationships.reports_to}
+Escalate to: ${specialist.relationships.escalates_to}
+
+${specialist.relationships.collaborates_with ?
+  `Collaborate with: ${specialist.relationships.collaborates_with.join(', ')}` : ''}`
+        });
+      }
+    });
+  });
+
+  return teammates;
+}
+
+/**
+ * Generate Agent Teams command for spawning
+ * @param {Object[]} teammates - Output from generateTeammateConfigs
+ * @param {string} displayMode - 'auto' | 'in-process' | 'tmux'
+ * @returns {string} Command to spawn Agent Teams
+ */
+export function generateSpawnCommand(teammates, displayMode = 'auto') {
+  // Agent Teams are spawned via Claude Code's Task tool with subagent_type="general-purpose"
+  // and special teammate configs. This is a conceptual representation.
+
+  const command = {
+    tool: 'Task',
+    subagent_type: 'general-purpose',
+    agent_teams_enabled: true,
+    display_mode: displayMode,
+    teammates: teammates.map(t => ({
+      id: t.id,
+      role: t.role,
+      icon: t.icon,
+      prompt: t.spawnPrompt
+    }))
+  };
+
+  return JSON.stringify(command, null, 2);
+}
+
+/**
+ * Main orchestration function - decides if/when to spawn Agent Teams
+ * @param {Object} options
+ * @param {string} options.projectPath - Project root path
+ * @param {string} options.featureName - Feature name
+ * @param {string} options.phase - MORPH phase
+ * @param {string[]} options.activeAgents - Active agent IDs
+ * @param {string} options.complexity - Complexity level
+ * @param {number} options.estimatedFiles - Estimated file count
+ * @param {boolean} options.multiDomain - Multi-domain feature?
+ * @returns {Promise<Object>} Team orchestration result
+ */
+export async function orchestrateTeam(options) {
+  const {
+    projectPath,
+    featureName,
+    phase,
+    activeAgents = [],
+    complexity,
+    estimatedFiles = 0,
+    multiDomain = false
+  } = options;
+
+  // Step 1: Decide if Agent Teams should spawn
+  const spawnDecision = shouldSpawnAgentTeam({
+    activeAgents,
+    complexity,
+    estimatedFiles,
+    multiDomain
+  });
+
+  if (!spawnDecision.shouldSpawn) {
+    return {
+      useAgentTeams: false,
+      reason: spawnDecision.reason,
+      recommendation: 'Use single session with Task tool for subagents'
+    };
+  }
+
+  // Step 2: Load agents config and build hierarchy
+  const agentsConfig = await loadAgentsConfig(projectPath);
+  const teamHierarchy = buildTeamHierarchy(activeAgents, agentsConfig);
+
+  // Step 3: Generate teammate configs
+  const teammates = generateTeammateConfigs(teamHierarchy, featureName, phase);
+
+  // Step 4: Generate spawn command
+  const spawnCommand = generateSpawnCommand(teammates, spawnDecision.recommendedMode);
+
+  return {
+    useAgentTeams: true,
+    reason: spawnDecision.reason,
+    displayMode: spawnDecision.recommendedMode,
+    teamHierarchy: {
+      teamLead: teamHierarchy.teamLead?.id,
+      squads: Object.keys(teamHierarchy.squads),
+      totalTeammates: teamHierarchy.totalTeammates,
+      validators: teamHierarchy.validators.map(v => v.id)
+    },
+    teammates,
+    spawnCommand,
+    recommendation: `Spawn ${teamHierarchy.totalTeammates} teammates in ${spawnDecision.recommendedMode} mode`
+  };
+}
+
+/**
+ * Get agent squad assignments (for informational purposes)
+ * @param {Object} agentsConfig - Loaded agents.json
+ * @returns {Object} Squad information
+ */
+export function getSquadInfo(agentsConfig) {
+  return agentsConfig.squads || {};
+}

package/src/lib/troubleshoot-grep.js

@@ -0,0 +1,194 @@
+/**
+ * Troubleshoot Grep Fallback
+ * Searches markdown files for matching content when index doesn't find results
+ */
+
+import { readFileSync, readdirSync, existsSync } from 'fs';
+import { join, dirname, basename } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+// Directories to search
+const SEARCH_PATHS = [
+  'framework/standards',
+  'content/.morph/standards',
+  '.wiki'
+];
+
+/**
+ * Get all markdown files from search paths
+ * @param {string} basePath - Base path of the project
+ * @returns {string[]} Array of file paths
+ */
+function getMarkdownFiles(basePath) {
+  const files = [];
+
+  for (const searchPath of SEARCH_PATHS) {
+    const fullPath = join(basePath, searchPath);
+
+    if (!existsSync(fullPath)) {
+      continue;
+    }
+
+    try {
+      const entries = readdirSync(fullPath, { withFileTypes: true });
+
+      for (const entry of entries) {
+        if (entry.isFile() && entry.name.endsWith('.md')) {
+          files.push(join(fullPath, entry.name));
+        }
+      }
+    } catch (error) {
+      // Skip directories we can't read
+    }
+  }
+
+  return files;
+}
+
+/**
+ * Extract section containing the match
+ * @param {string} content - File content
+ * @param {number} matchIndex - Index of the match
+ * @returns {Object} Section object with title and content
+ */
+function extractSection(content, matchIndex) {
+  const lines = content.split('\n');
+  let charCount = 0;
+  let matchLineIndex = 0;
+
+  // Find the line containing the match
+  for (let i = 0; i < lines.length; i++) {
+    charCount += lines[i].length + 1; // +1 for newline
+    if (charCount > matchIndex) {
+      matchLineIndex = i;
+      break;
+    }
+  }
+
+  // Find the section header (## heading) above the match
+  let sectionTitle = 'Unknown Section';
+  let sectionStart = 0;
+
+  for (let i = matchLineIndex; i >= 0; i--) {
+    if (lines[i].startsWith('## ')) {
+      sectionTitle = lines[i].replace('## ', '').trim();
+      sectionStart = i;
+      break;
+    }
+  }
+
+  // Find the end of the section (next ## or end of file)
+  let sectionEnd = lines.length;
+  for (let i = sectionStart + 1; i < lines.length; i++) {
+    if (lines[i].startsWith('## ')) {
+      sectionEnd = i;
+      break;
+    }
+  }
+
+  // Extract section content (limit to ~20 lines around match)
+  const contextStart = Math.max(sectionStart, matchLineIndex - 10);
+  const contextEnd = Math.min(sectionEnd, matchLineIndex + 10);
+  const sectionContent = lines.slice(contextStart, contextEnd).join('\n');
+
+  return {
+    title: sectionTitle,
+    content: sectionContent,
+    lineNumber: matchLineIndex + 1
+  };
+}
+
+/**
+ * Search a file for keywords
+ * @param {string} filePath - Path to the file
+ * @param {string[]} keywords - Keywords to search for
+ * @returns {Object[]} Array of matches
+ */
+function searchFile(filePath, keywords) {
+  const matches = [];
+
+  try {
+    const content = readFileSync(filePath, 'utf-8');
+    const contentLower = content.toLowerCase();
+
+    for (const keyword of keywords) {
+      const keywordLower = keyword.toLowerCase();
+      let index = contentLower.indexOf(keywordLower);
+
+      while (index !== -1) {
+        const section = extractSection(content, index);
+
+        // Check if we already have a match for this section
+        const existingMatch = matches.find(m => m.section === section.title);
+
+        if (existingMatch) {
+          existingMatch.matchCount++;
+          existingMatch.keywords.add(keyword);
+        } else {
+          matches.push({
+            file: filePath,
+            fileName: basename(filePath),
+            section: section.title,
+            content: section.content,
+            lineNumber: section.lineNumber,
+            matchCount: 1,
+            keywords: new Set([keyword])
+          });
+        }
+
+        index = contentLower.indexOf(keywordLower, index + 1);
+      }
+    }
+  } catch (error) {
+    // Skip files we can't read
+  }
+
+  return matches;
+}
+
+/**
+ * Search all markdown files for keywords
+ * @param {string[]} keywords - Keywords to search for
+ * @param {Object} options - Search options
+ * @returns {Object[]} Array of matches sorted by relevance
+ */
+export function searchGrep(keywords, options = {}) {
+  // Determine base path
+  const basePath = options.basePath || join(__dirname, '../..');
+
+  const files = getMarkdownFiles(basePath);
+  let allMatches = [];
+
+  for (const file of files) {
+    const matches = searchFile(file, keywords);
+    allMatches = allMatches.concat(matches);
+  }
+
+  // Convert keywords Set to Array and calculate score
+  const results = allMatches.map(match => ({
+    ...match,
+    keywords: Array.from(match.keywords),
+    score: match.matchCount * 5 + match.keywords.size * 3,
+    source: 'grep'
+  }));
+
+  // Sort by score (higher is better) and deduplicate
+  const seen = new Set();
+  const uniqueResults = results
+    .sort((a, b) => b.score - a.score)
+    .filter(r => {
+      const key = `${r.file}:${r.section}`;
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+
+  return uniqueResults.slice(0, 10); // Limit to top 10
+}
+
+export default {
+  searchGrep
+};

package/src/lib/troubleshoot-index.js

@@ -0,0 +1,144 @@
+/**
+ * Troubleshoot Index Search
+ * Searches the troubleshooting-index.json for matching problems
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * Load the troubleshooting index
+ * @returns {Object} The index object or null if not found
+ */
+export function loadIndex() {
+  const indexPath = join(__dirname, '../../framework/index/troubleshooting-index.json');
+
+  if (!existsSync(indexPath)) {
+    return null;
+  }
+
+  try {
+    const content = readFileSync(indexPath, 'utf-8');
+    return JSON.parse(content);
+  } catch (error) {
+    console.error('Error loading troubleshooting index:', error.message);
+    return null;
+  }
+}
+
+/**
+ * Calculate relevance score for a problem based on keywords
+ * @param {Object} problem - The problem object from index
+ * @param {string[]} searchTerms - Search terms from user
+ * @returns {number} Relevance score (higher is better)
+ */
+function calculateScore(problem, searchTerms) {
+  let score = 0;
+  const searchLower = searchTerms.map(t => t.toLowerCase());
+
+  // Check keywords
+  for (const keyword of problem.keywords) {
+    const keywordLower = keyword.toLowerCase();
+    for (const term of searchLower) {
+      if (keywordLower.includes(term) || term.includes(keywordLower)) {
+        score += 10;
+      }
+    }
+  }
+
+  // Check title
+  const titleLower = problem.title.toLowerCase();
+  for (const term of searchLower) {
+    if (titleLower.includes(term)) {
+      score += 5;
+    }
+  }
+
+  // Check error pattern (regex match on search string)
+  if (problem.errorPattern) {
+    try {
+      const regex = new RegExp(problem.errorPattern, 'i');
+      const searchString = searchTerms.join(' ');
+      if (regex.test(searchString)) {
+        score += 20; // High score for error pattern match
+      }
+    } catch (e) {
+      // Invalid regex, skip
+    }
+  }
+
+  // Boost critical severity
+  if (problem.severity === 'critical') {
+    score *= 1.2;
+  }
+
+  return score;
+}
+
+/**
+ * Search the index for problems matching the keywords
+ * @param {string[]} keywords - Search keywords
+ * @param {Object} options - Search options
+ * @param {string} options.category - Filter by category
+ * @returns {Object[]} Array of matching problems with scores
+ */
+export function searchIndex(keywords, options = {}) {
+  const index = loadIndex();
+
+  if (!index || !index.problems) {
+    return [];
+  }
+
+  let problems = index.problems;
+
+  // Filter by category if specified
+  if (options.category) {
+    problems = problems.filter(p => p.category === options.category);
+  }
+
+  // Score and filter problems
+  const results = problems
+    .map(problem => ({
+      ...problem,
+      score: calculateScore(problem, keywords)
+    }))
+    .filter(p => p.score > 0)
+    .sort((a, b) => b.score - a.score);
+
+  return results;
+}
+
+/**
+ * Get all categories from the index
+ * @returns {Object} Categories object
+ */
+export function getCategories() {
+  const index = loadIndex();
+  return index?.categories || {};
+}
+
+/**
+ * Get a specific problem by ID
+ * @param {string} id - Problem ID
+ * @returns {Object|null} Problem object or null
+ */
+export function getProblemById(id) {
+  const index = loadIndex();
+
+  if (!index || !index.problems) {
+    return null;
+  }
+
+  return index.problems.find(p => p.id === id) || null;
+}
+
+export default {
+  loadIndex,
+  searchIndex,
+  getCategories,
+  getProblemById
+};