@polymorphism-tech/morph-spec 4.10.5 → 4.10.7

package/src/commands/agents/detect-agents.js

@@ -0,0 +1,275 @@
+/**
+ * detect-agents — Detect relevant agents for a feature based on keywords
+ *
+ * Supports single string input (legacy) and multi-source TextSource[] input
+ * with weighted keyword scoring. Also provides refreshAgents() for additive
+ * agent detection at phase boundaries.
+ *
+ * Usage:
+ *   morph-spec detect-agents <feature> [--proposal <path>] [--refresh] [--json] [--table]
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import chalk from 'chalk';
+import { collectPhaseOutputs } from '../../lib/agents/output-collector.js';
+import { loadAgentsFile } from '../../lib/agents/agents-manager.js';
+import { loadState, saveState, addAgent } from '../../core/state/state-manager.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/** Default path to agents.json in the installed package */
+const AGENTS_JSON_PATH = join(__dirname, '../../../framework/agents.json');
+
+/** Match weight constants */
+const MATCH_WEIGHTS = {
+  heading: 3,
+  body: 1,
+  domain: 2,
+};
+
+/**
+ * Detect agents relevant to a feature.
+ *
+ * @param {string|Array<{source: string, content: string, weight: number}>} sourcesOrText - Text sources or legacy string
+ * @param {Object} agentsJson - Parsed agents.json content
+ * @param {Object} [opts] - Options
+ * @param {string[]} [opts.excludeIds] - Agent IDs to exclude from detection
+ * @returns {{ detected: Array<{id: string, reason: string, keywords_matched: string[], score: number, sources: Array}>, skipped: Array<{id: string, reason: string}> }}
+ */
+export function detectAgents(sourcesOrText, agentsJson, opts = {}) {
+  // Backward compatibility: wrap string as single source
+  const sources = typeof sourcesOrText === 'string'
+    ? [{ source: 'proposal.md', content: sourcesOrText, weight: 1.0 }]
+    : sourcesOrText;
+
+  const allAgents = agentsJson.agents || {};
+  const excludeIds = new Set(opts.excludeIds || []);
+
+  const detected = [];
+  const skipped = [];
+
+  for (const [agentId, agentData] of Object.entries(allAgents)) {
+    if (excludeIds.has(agentId)) continue;
+    if (!agentData || typeof agentData !== 'object' || !agentData.tier) continue;
+
+    // Always-active agents (active_phases includes '*')
+    if (Array.isArray(agentData.active_phases) && agentData.active_phases.includes('*')) {
+      detected.push({
+        id: agentId,
+        reason: 'active_phases: *',
+        keywords_matched: [],
+        score: 0,
+        sources: [],
+      });
+      continue;
+    }
+
+    // Score across all sources
+    const keywords = agentData.keywords || [];
+    const domains = agentData.domains || [];
+    let totalScore = 0;
+    const allMatched = new Set();
+    const sourceBreakdown = [];
+
+    for (const src of sources) {
+      const textLower = src.content.toLowerCase();
+      const lines = src.content.split('\n');
+      let srcScore = 0;
+      const srcKeywords = [];
+
+      // Check keywords
+      for (const kw of keywords) {
+        const kwLower = kw.toLowerCase();
+        if (!textLower.includes(kwLower)) continue;
+
+        allMatched.add(kw);
+        srcKeywords.push(kw);
+
+        // Check if keyword appears in a heading line
+        const inHeading = lines.some(line =>
+          /^#{1,6}\s/.test(line) && line.toLowerCase().includes(kwLower)
+        );
+        srcScore += (inHeading ? MATCH_WEIGHTS.heading : MATCH_WEIGHTS.body) * src.weight;
+      }
+
+      // Check domains
+      for (const domain of domains) {
+        const domLower = domain.toLowerCase();
+        if (!textLower.includes(domLower)) continue;
+
+        allMatched.add(domain);
+        srcKeywords.push(domain);
+        srcScore += MATCH_WEIGHTS.domain * src.weight;
+      }
+
+      if (srcScore > 0) {
+        sourceBreakdown.push({
+          source: src.source,
+          keywords: srcKeywords,
+          score: srcScore,
+        });
+        totalScore += srcScore;
+      }
+    }
+
+    if (totalScore > 0) {
+      detected.push({
+        id: agentId,
+        reason: 'keyword',
+        keywords_matched: [...allMatched],
+        score: totalScore,
+        sources: sourceBreakdown,
+      });
+    } else {
+      skipped.push({
+        id: agentId,
+        reason: 'no_keyword_match',
+      });
+    }
+  }
+
+  return { detected, skipped };
+}
+
+/**
+ * Refresh agent detection using all available phase outputs.
+ * Additive only — never removes existing agents.
+ *
+ * @param {string} projectRoot - Absolute path
+ * @param {string} featureName - Feature name
+ * @returns {Promise<{added: Array, unchanged: number, total: number}>}
+ */
+export async function refreshAgents(projectRoot, featureName) {
+  const state = loadState(false);
+  const feature = state?.features?.[featureName];
+  if (!feature) {
+    return { added: [], unchanged: 0, total: 0 };
+  }
+
+  const currentAgents = new Set(feature.activeAgents || []);
+
+  const sources = collectPhaseOutputs(projectRoot, featureName);
+  if (sources.length === 0) {
+    return { added: [], unchanged: currentAgents.size, total: currentAgents.size };
+  }
+
+  let agentsJson;
+  try {
+    agentsJson = loadAgentsFile(AGENTS_JSON_PATH);
+  } catch {
+    return { added: [], unchanged: currentAgents.size, total: currentAgents.size };
+  }
+  const { detected } = detectAgents(sources, agentsJson);
+
+  const added = detected.filter(a => !currentAgents.has(a.id));
+
+  // Additive: add new agents to state
+  for (const agent of added) {
+    await addAgent(featureName, agent.id);
+  }
+
+  return {
+    added,
+    unchanged: currentAgents.size,
+    total: currentAgents.size + added.length,
+  };
+}
+
+/**
+ * Display detection diff after refresh.
+ *
+ * @param {{added: Array, unchanged: number, total: number}} result
+ * @param {string} fromPhase
+ * @param {string} toPhase
+ */
+export function displayDetectionDiff(result, fromPhase, toPhase) {
+  console.log(chalk.cyan(`\nAgent Detection Refresh (${fromPhase} \u2192 ${toPhase}):`));
+
+  for (const agent of result.added) {
+    const kws = agent.keywords_matched.join('", "');
+    console.log(chalk.green(`  + ${agent.id.padEnd(24)} (keyword: "${kws}" | score: ${agent.score})`));
+  }
+
+  console.log(chalk.gray(`  = ${result.unchanged} agents unchanged`));
+  console.log(chalk.white(`  Total: ${result.total} active agents\n`));
+}
+
+/**
+ * CLI command: morph-spec detect-agents <feature>
+ */
+export async function detectAgentsCommand(featureName, options = {}) {
+  if (!featureName) {
+    console.error(chalk.red('Usage: morph-spec detect-agents <feature> [--proposal <path>] [--refresh] [--json] [--table]'));
+    process.exit(1);
+  }
+
+  // --refresh mode: use all phase outputs and mutate state
+  if (options.refresh) {
+    const result = await refreshAgents(process.cwd(), featureName);
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      displayDetectionDiff(result, 'manual', 'refresh');
+    }
+    return;
+  }
+
+  // Resolve proposal path
+  const proposalPath = options.proposal
+    || join(process.cwd(), `.morph/features/${featureName}/0-proposal/proposal.md`);
+
+  if (!existsSync(proposalPath)) {
+    console.error(chalk.red(`Proposal not found: ${proposalPath}`));
+    console.error(chalk.gray('Create the proposal first or use --proposal <path> to specify a custom path.'));
+    process.exit(1);
+  }
+
+  // Load agents.json
+  const agentsPath = options.agentsJson || AGENTS_JSON_PATH;
+  let agentsJson;
+  try {
+    agentsJson = loadAgentsFile(agentsPath);
+  } catch (err) {
+    console.error(chalk.red(err.message));
+    process.exit(1);
+  }
+
+  const proposalText = readFileSync(proposalPath, 'utf8');
+
+  const result = detectAgents(proposalText, agentsJson, {
+    excludeIds: options.exclude ? options.exclude.split(',') : [],
+  });
+
+  const output = {
+    feature: featureName,
+    ...result,
+  };
+
+  if (options.table) {
+    // Human-readable table
+    console.log(chalk.bold(`\n  Detected Agents \u2014 ${featureName}`));
+    console.log('  ' + '\u2500'.repeat(62));
+
+    if (result.detected.length > 0) {
+      console.log(`  ${'ID'.padEnd(28)} ${'Reason'.padEnd(16)} Keywords`);
+      console.log('  ' + '\u2500'.repeat(62));
+      for (const agent of result.detected) {
+        const reason = agent.reason === 'active_phases: *' ? 'always' : agent.reason;
+        const kw = agent.keywords_matched.length > 0 ? agent.keywords_matched.join(', ') : '\u2014';
+        console.log(
+          `  ${agent.id.padEnd(28)} ${chalk.cyan(reason.padEnd(16))} ${kw}`
+        );
+      }
+    } else {
+      console.log(chalk.gray('  No agents detected.'));
+    }
+
+    console.log(`\n  Skipped: ${result.skipped.length} agents (no keyword match)`);
+    console.log();
+  } else {
+    // JSON output (default)
+    console.log(JSON.stringify(output, null, 2));
+  }
+}

package/src/commands/agents/dispatch-agents.js

@@ -21,6 +21,9 @@ import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
 import { loadState, stateExists } from '../../core/state/state-manager.js';
 import { buildAgentBriefing, buildValidatorPrompt } from '../../lib/standards/digest-builder.js';
+import { agentIdToSubagentType } from '../../utils/agent-id-mapper.js';
+import { parseAndGroupTasks } from '../../lib/tasks/task-parser.js';
+export { parseAndGroupTasks } from '../../lib/tasks/task-parser.js';
 import chalk from 'chalk';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -34,62 +37,6 @@ const PHASES_JSON_PATH = join(__dirname, '../../../framework/phases.json');
 /** Phases where agent dispatch is meaningful */
 const DISPATCHABLE_PHASES = ['design', 'tasks', 'implement'];
 
-/**
- * Domain → parallel group mapping.
- * Agents inherit group from their first matching domain.
- */
-const DOMAIN_TO_GROUP = {
-  'backend': 'backend',
-  'backend-data': 'backend',
-  'backend-jobs': 'backend',
-  'backend-events': 'backend',
-  'frontend': 'frontend',
-  'frontend-blazor': 'frontend',
-  'frontend-nextjs': 'frontend',
-  'frontend-css': 'frontend',
-  'frontend-design': 'frontend',
-  'infrastructure': 'infra',
-  'cloud-azure': 'infra',
-  'devops': 'infra',
-  'domain': 'domain-analysis',
-  'domain-modeling': 'domain-analysis',
-  'architecture': 'domain-analysis',
-  'ai-orchestration': 'domain-analysis',
-  'testing': 'tests',
-  'qa': 'tests',
-};
-
-/** Agent-level group overrides (higher priority than domain mapping) */
-const AGENT_GROUP_OVERRIDES = {
-  'domain-architect': 'domain-analysis',
-  'standards-architect': 'domain-analysis',
-  'ai-system-architect': 'domain-analysis',
-  'popm-advisor': 'domain-analysis',
-  'dotnet-senior': 'backend',
-  'infra-architect': 'infra',
-  'ui-designer': 'frontend',
-  'testing-specialist': 'tests',
-  'code-analyzer': 'tests',
-  'load-testing-expert': 'tests',
-  'documentation-specialist': 'docs',
-  'troubleshooting-expert': 'support',
-};
-
-/**
- * Task category → parallel group mapping for implement-phase task splitting.
- * Matches task categories defined in phase-tasks SKILL.md.
- */
-const TASK_CATEGORY_TO_GROUP = {
-  'domain': 'backend',
-  'domain-bc': 'backend',
-  'infrastructure': 'backend',
-  'application': 'backend',
-  'presentation': 'frontend',
-  'tests': 'tests',
-  'infra': 'infra',
-  'docs': 'docs',
-};
-
 // ─────────────────────────────────────────────────────────────────────────────
 // Required Skills Injection
 // ─────────────────────────────────────────────────────────────────────────────
@@ -175,34 +122,24 @@ export function buildMcpBlock(phase, phasesData, opts = {}) {
 
 /**
  * Determine the parallel execution group for an agent.
- * Priority: explicit override → domain mapping → tier fallback.
+ * Reads from the `group` field in agents.json v4; falls back to 'backend'.
  *
  * @param {string} agentId
  * @param {Object} agentData
  * @returns {string} group name
  */
 function getAgentGroup(agentId, agentData) {
-  if (AGENT_GROUP_OVERRIDES[agentId]) return AGENT_GROUP_OVERRIDES[agentId];
-
-  const domains = agentData.domains || [];
-  for (const domain of domains) {
-    if (DOMAIN_TO_GROUP[domain]) return DOMAIN_TO_GROUP[domain];
-  }
-
-  // Tier-2 domain leaders default to backend if no domain matched
-  if (agentData.tier === 2) return 'backend';
-  return 'backend';
+  return agentData.group || 'backend';
 }
 
 /**
  * Check whether an agent should be dispatched for the given phase.
  *
- * Rules (in priority order):
- * 1. Tier-4 validators → never dispatch (no task work) [overridden by validate mode]
- * 2. Agent-level `active_phases` array → use that list
- * 3. Relationships-level `active_phases` array → use that list
- * 4. `always_active: true` → dispatchable for all DISPATCHABLE_PHASES
- * 5. Default: specialists without active_phases → implement only
+ * Rules:
+ * 1. Tier-4 validators → never dispatch (validate mode bypasses this)
+ * 2. `active_phases` includes '*' → all dispatchable phases
+ * 3. `active_phases` includes the phase → dispatch
+ * 4. Default (no active_phases): implement only
  *
  * @param {string} agentId
  * @param {Object} agentData
@@ -210,72 +147,16 @@ function getAgentGroup(agentId, agentData) {
  * @returns {boolean}
  */
 function isRelevantForPhase(agentId, agentData, phase) {
-  // Tier-4 validators have no implementation tasks (validate mode bypasses this)
   if (agentData.tier === 4) return false;
 
-  // Explicit active_phases on agent root
-  if (Array.isArray(agentData.active_phases)) {
-    return agentData.active_phases.includes(phase);
+  const phases = agentData.active_phases;
+  if (Array.isArray(phases)) {
+    return phases.includes('*') || phases.includes(phase);
   }
 
-  // active_phases nested in relationships
-  const relPhases = agentData.relationships?.active_phases;
-  if (Array.isArray(relPhases)) {
-    return relPhases.includes(phase);
-  }
-
-  // always_active agents: dispatch for all recognised phases
-  if (agentData.always_active && DISPATCHABLE_PHASES.includes(phase)) return true;
-
-  // Specialists without active_phases: implement phase only
   return phase === 'implement';
 }
 
-/**
- * Parse tasks.md and return a map of { parallelGroup → taskId[] }.
- * Gracefully returns {} if the file doesn't exist or is unparseable.
- *
- * @param {string} tasksPath - Absolute path to tasks.md
- * @returns {Object}
- */
-export function parseAndGroupTasks(tasksPath) {
-  if (!existsSync(tasksPath)) return {};
-
-  try {
-    const content = readFileSync(tasksPath, 'utf8');
-    const groups = {};
-
-    // Match task headings: ### T001 — Title  or  ### T001: Title
-    const taskHeadingRe = /^###\s+(T\d{3,})\s*[—–:\-]\s*(.+)$/gm;
-    // Match category line within a task block: **category**: `domain`  or  - category: application
-    const categoryRe = /(?:\*\*category\*\*\s*:\s*`?([a-z-]+)`?|category:\s*([a-z-]+))/i;
-
-    let headingMatch;
-    const taskPositions = [];
-
-    while ((headingMatch = taskHeadingRe.exec(content)) !== null) {
-      taskPositions.push({ id: headingMatch[1], pos: headingMatch.index });
-    }
-
-    for (let i = 0; i < taskPositions.length; i++) {
-      const { id, pos } = taskPositions[i];
-      const end = i + 1 < taskPositions.length ? taskPositions[i + 1].pos : content.length;
-      const block = content.slice(pos, end);
-
-      const catMatch = categoryRe.exec(block);
-      const category = (catMatch?.[1] || catMatch?.[2] || 'application').toLowerCase();
-      const group = TASK_CATEGORY_TO_GROUP[category] || 'backend';
-
-      if (!groups[group]) groups[group] = [];
-      groups[group].push(id);
-    }
-
-    return groups;
-  } catch {
-    return {};
-  }
-}
-
 // ─────────────────────────────────────────────────────────────────────────────
 // Core Logic
 // ─────────────────────────────────────────────────────────────────────────────
@@ -345,16 +226,15 @@ export async function buildDispatchConfig(projectPath, featureName, phase, opts
   const activeAgentIds = new Set(feature.activeAgents || []);
 
   // Collect dispatchable agents
-  // Process all agents: active ones from state + always_active ones not yet in state
   const isValidateMode = opts.mode === 'validate';
   const processed = new Set();
   const dispatchableAgents = [];
 
   const candidateIds = [
     ...activeAgentIds,
-    // Add always_active agents that might not have been explicitly detected
+    // Add always-active agents (active_phases includes '*')
     ...Object.entries(allAgents)
-      .filter(([id, data]) => !id.startsWith('_comment') && data.always_active)
+      .filter(([id, data]) => Array.isArray(data.active_phases) && data.active_phases.includes('*'))
       .map(([id]) => id),
     // In validate mode, also include tier-4 validators
     ...(isValidateMode
@@ -402,6 +282,7 @@ export async function buildDispatchConfig(projectPath, featureName, phase, opts
 
     dispatchableAgents.push({
       id: agentId,
+      subagentType: agentIdToSubagentType(agentId, agentData.tier),
       title: agentData.title,
       tier: agentData.tier,
       icon: agentData.teammate?.icon || '🤖',
@@ -452,6 +333,7 @@ export async function buildDispatchConfig(projectPath, featureName, phase, opts
       const groupAgent = dispatchableAgents.find(a => a.parallelGroup === group);
       taskGroups[group] = {
         agentId: groupAgent?.id ?? null,
+        subagentType: groupAgent?.subagentType ?? null,
         description: `${group} implementation tasks for feature '${featureName}'`,
         tasks: taskIds,
         canRunParallel: true,
@@ -467,6 +349,7 @@ export async function buildDispatchConfig(projectPath, featureName, phase, opts
 
       taskGroups[agent.parallelGroup] = {
         agentId: agent.id,
+        subagentType: agent.subagentType,
         description: agent.role,
         tasks: [],
         canRunParallel: true,
@@ -475,6 +358,19 @@ export async function buildDispatchConfig(projectPath, featureName, phase, opts
     }
   }
 
+  // ── Pre-flight: check agent files exist ──────────────────────────────────
+  const warnings = [];
+  for (const agent of dispatchableAgents) {
+    const agentFile = join(projectPath, '.claude', 'agents', `${agent.subagentType}.md`);
+    if (!existsSync(agentFile)) {
+      warnings.push({
+        agentId: agent.id,
+        subagentType: agent.subagentType,
+        message: `File .claude/agents/${agent.subagentType}.md not found`,
+      });
+    }
+  }
+
   return {
     feature: featureName,
     phase,
@@ -487,6 +383,7 @@ export async function buildDispatchConfig(projectPath, featureName, phase, opts
         : `No dispatchable agents found for phase '${phase}'`,
     agents: dispatchableAgents,
     taskGroups,
+    warnings,
   };
 }
 
@@ -563,6 +460,15 @@ export async function dispatchAgentsCommand(featureName, phase, options = {}) {
       // JSON (default — consumed by phase skills / LLM)
       console.log(JSON.stringify(config, null, 2));
     }
+
+    // Pre-flight mode: exit with code 1 if warnings exist
+    if (options.preflight && config.warnings?.length > 0) {
+      console.error(chalk.yellow(`\n  ⚠ Pre-flight: ${config.warnings.length} missing agent file(s):`));
+      for (const w of config.warnings) {
+        console.error(chalk.yellow(`    - ${w.agentId}: ${w.message}`));
+      }
+      process.exit(1);
+    }
   } catch (err) {
     console.error(chalk.red(`Error: ${err.message}`));
     if (options.verbose) console.error(err.stack);

package/src/commands/agents/index.js

@@ -2,3 +2,12 @@
  * Agent Commands
  */
 export { dispatchAgentsCommand, buildDispatchConfig } from './dispatch-agents.js';
+export { auditDispatchCommand } from './audit-dispatch.js';
+export { detectAgentsCommand, detectAgents } from './detect-agents.js';
+export {
+  agentListCommand,
+  agentShowCommand,
+  agentAddCommand,
+  agentEditCommand,
+  agentRemoveCommand,
+} from './manage-agents.js';