@polymorphism-tech/morph-spec 4.21.0 → 5.0.1

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

@@ -1,461 +0,0 @@
-/**
- * dispatch-agents — Advisor for native Claude Code agent dispatch
- *
- * Reads activeAgents from state.json + agents.json and outputs a
- * recommendation of which agents to use and which tasks they handle.
- * Agent .md files in .claude/agents/ are self-contained — dispatch
- * does NOT compose prompts (except for tier-4 validators).
- *
- * Usage:
- *   morph-spec dispatch-agents <feature> <phase>
- *   morph-spec dispatch-agents <feature> <phase> --table
- *
- * Output (JSON):
- * {
- *   feature, phase, shouldDispatch, reason,
- *   recommended: { [group]: subagentType[] },
- *   tasks: { [group]: taskId[] },
- *   agents: [{ id, subagentType, title, tier, icon, group }],
- *   warnings: []
- * }
- */
-
-import { readFileSync, existsSync } from 'fs';
-import { join, dirname } from 'path';
-import { fileURLToPath } from 'url';
-import { loadState, stateExists, logDispatch } from '../../core/state/state-manager.js';
-import { buildValidatorPrompt } from '../../lib/standards/digest-builder.js';
-import { agentIdToSubagentType } from '../../utils/agent-id-mapper.js';
-import { shouldInstall, getProjectTags } from '../../lib/stack-filter.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));
-
-/** Path to agents.json in the installed package */
-const AGENTS_JSON_PATH = join(__dirname, '../../../framework/agents.json');
-
-/** Path to phases.json in the installed package */
-const PHASES_JSON_PATH = join(__dirname, '../../../framework/phases.json');
-
-/** Phases where agent dispatch is meaningful */
-const DISPATCHABLE_PHASES = ['design', 'plan', 'tasks', 'implement'];
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Required Skills Injection
-// ─────────────────────────────────────────────────────────────────────────────
-
-/**
- * Build a mandatory skills block for the given phase.
- * Reads requiredSkills from phases.json data and formats them as instructions for subagents.
- * Returns null if no required skills for this phase.
- *
- * @param {string} phase - Phase id (e.g. 'implement')
- * @param {Object|null} phasesData - Parsed phases.json content
- * @returns {string|null}
- */
-export function buildSkillsBlock(phase, phasesData) {
-  try {
-    const skills = phasesData?.phases?.[phase]?.requiredSkills;
-    if (!skills || skills.length === 0) return null;
-
-    const triggerLabel = trigger =>
-      trigger.replace(/([A-Z])/g, ' $1').toUpperCase().trim();
-
-    const lines = skills.map(s => `- ${triggerLabel(s.trigger)}: Invoke Skill(${s.skill})`);
-
-    return [
-      'Mandatory Skills (non-negotiable — invoke at the specified trigger points):',
-      ...lines,
-      '',
-      'Do NOT skip these skills. They are required by MORPH-SPEC for this phase.',
-    ].join('\n');
-  } catch {
-    return null;
-  }
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// MCP Awareness Injection
-// ─────────────────────────────────────────────────────────────────────────────
-
-/**
- * Build an MCP availability block for the given phase.
- * Reads recommendedMCPs from phases.json and MCP usage info from mcp-registry.json.
- * Returns null if no MCPs recommended for this phase.
- *
- * @param {string} phase - Phase id (e.g. 'implement')
- * @param {Object|null} phasesData - Parsed phases.json content
- * @param {Object} [opts] - Options
- * @param {string} [opts.registryPath] - Override path to mcp-registry.json
- * @returns {string|null}
- */
-export function buildMcpBlock(phase, phasesData, opts = {}) {
-  try {
-    const mcps = phasesData?.phases?.[phase]?.recommendedMCPs;
-    if (!mcps || mcps.length === 0) return null;
-
-    // Try to load registry for usage descriptions
-    let registry = null;
-    const registryPath = opts.registryPath || join(__dirname, '../../../framework/skills/level-0-meta/mcp-registry.json');
-    try {
-      if (existsSync(registryPath)) {
-        registry = JSON.parse(readFileSync(registryPath, 'utf8'));
-      }
-    } catch { /* non-blocking */ }
-
-    const lines = mcps.map(name => {
-      const usage = registry?.mcps?.[name]?.usage || '';
-      return usage ? `- ${name}: ${usage}` : `- ${name}`;
-    });
-
-    return [
-      `Available MCPs for ${phase} phase:`,
-      ...lines,
-      '',
-      'Use MCP tools when available; fall back to native tools (Bash, Read, Grep) when not.',
-    ].join('\n');
-  } catch {
-    return null;
-  }
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Helpers
-// ─────────────────────────────────────────────────────────────────────────────
-
-/**
- * Determine the parallel execution group for an agent.
- * 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) {
-  return agentData.group || 'backend';
-}
-
-/**
- * Check whether an agent should be dispatched for the given phase.
- *
- * 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
- * @param {string} phase
- * @returns {boolean}
- */
-function isRelevantForPhase(agentId, agentData, phase) {
-  if (agentData.tier === 4) return false;
-
-  const phases = agentData.active_phases;
-  if (Array.isArray(phases)) {
-    return phases.includes('*') || phases.includes(phase);
-  }
-
-  return phase === 'implement';
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Core Logic
-// ─────────────────────────────────────────────────────────────────────────────
-
-/**
- * Build dispatch config for a feature and phase.
- *
- * @param {string} projectPath - Absolute path to project root (cwd)
- * @param {string} featureName - Feature name
- * @param {string} phase - Phase: 'design' | 'tasks' | 'implement'
- * @param {Object} [opts] - Optional overrides (for testing)
- * @param {string} [opts.agentsJsonPath] - Override path to agents.json
- * @returns {Object} Dispatch config
- */
-export async function buildDispatchConfig(projectPath, featureName, phase, opts = {}) {
-  // Load state
-  const state = loadState(false);
-  if (!state) {
-    return {
-      shouldDispatch: false,
-      reason: 'state.json not found — run morph-spec state init',
-      recommended: {},
-      tasks: {},
-      agents: [],
-      warnings: [],
-    };
-  }
-
-  const feature = state.features?.[featureName];
-  if (!feature) {
-    return {
-      feature: featureName,
-      phase,
-      shouldDispatch: false,
-      reason: `Feature '${featureName}' not found in state.json`,
-      recommended: {},
-      tasks: {},
-      agents: [],
-      warnings: [],
-    };
-  }
-
-  // Load agents.json (opts.agentsJsonPath allows override for testing)
-  const agentsPath = opts.agentsJsonPath || AGENTS_JSON_PATH;
-  if (!existsSync(agentsPath)) {
-    return {
-      feature: featureName,
-      phase,
-      shouldDispatch: false,
-      reason: 'framework/agents.json not found',
-      recommended: {},
-      tasks: {},
-      agents: [],
-      warnings: [],
-    };
-  }
-
-  const agentsData = JSON.parse(readFileSync(agentsPath, 'utf8'));
-  const allAgents = agentsData.agents || {};
-
-  // Load project config for stack filtering
-  const configPath = join(projectPath, '.morph', 'config.json');
-  let projectTags = [];
-  try {
-    if (existsSync(configPath)) {
-      const config = JSON.parse(readFileSync(configPath, 'utf8'));
-      projectTags = getProjectTags(config);
-    }
-  } catch { /* non-blocking */ }
-
-  // Active agents from state (keyword-detected during setup phase)
-  const activeAgentIds = new Set(feature.activeAgents || []);
-
-  // Collect dispatchable agents
-  const isValidateMode = opts.mode === 'validate';
-  const processed = new Set();
-  let dispatchableAgents = [];
-
-  const candidateIds = [
-    ...activeAgentIds,
-    // Add always-active agents (active_phases includes '*')
-    ...Object.entries(allAgents)
-      .filter(([id, data]) => Array.isArray(data.active_phases) && data.active_phases.includes('*'))
-      .map(([id]) => id),
-    // In validate mode, also include tier-4 validators
-    ...(isValidateMode
-      ? Object.entries(allAgents)
-          .filter(([id, data]) => !id.startsWith('_comment') && data.tier === 4)
-          .map(([id]) => id)
-      : []),
-  ];
-
-  for (const agentId of candidateIds) {
-    if (processed.has(agentId)) continue;
-    processed.add(agentId);
-
-    const agentData = allAgents[agentId];
-    if (!agentData || agentId.startsWith('_comment')) continue;
-
-    const isTier4 = agentData.tier === 4;
-
-    // Must have a spawn_prompt (or be a tier-4 with hook_behavior in validate mode)
-    if (!agentData.teammate?.spawn_prompt && !(isValidateMode && isTier4 && agentData.hook_behavior)) continue;
-
-    // Phase relevance check (tier-4 bypass in validate mode)
-    if (!isRelevantForPhase(agentId, agentData, phase) && !(isValidateMode && isTier4)) continue;
-
-    // Stack filtering (Tier 1/2 exempt — always dispatched)
-    if (agentData.tier >= 3 && projectTags.length > 0) {
-      const agentStacks = agentData.stacks || [];
-      if (!shouldInstall(agentStacks, projectTags)) continue;
-    }
-
-    const group = getAgentGroup(agentId, agentData);
-
-    // Tier-4 validators in validate mode still get taskPrompt (dynamically generated)
-    const agentEntry = {
-      id: agentId,
-      subagentType: agentIdToSubagentType(agentId, agentData.tier),
-      title: agentData.title,
-      tier: agentData.tier,
-      icon: agentData.teammate?.icon || '🤖',
-      group,
-    };
-
-    if (isValidateMode && isTier4) {
-      agentEntry.taskPrompt = buildValidatorPrompt(agentId) || agentData.teammate?.spawn_prompt || '';
-    }
-
-    dispatchableAgents.push(agentEntry);
-  }
-
-  // Sort: domain-analysis first, then by tier (ascending), then alphabetically
-  const groupOrder = ['domain-analysis', 'backend', 'frontend', 'infra', 'tests', 'docs', 'support'];
-  dispatchableAgents.sort((a, b) => {
-    const gi = groupOrder.indexOf(a.group);
-    const gj = groupOrder.indexOf(b.group);
-    if (gi !== gj) return gi - gj;
-    if (a.tier !== b.tier) return a.tier - b.tier;
-    return a.id.localeCompare(b.id);
-  });
-
-  // Pre-flight: check agent files exist, skip missing (BUG-001)
-  const warnings = [];
-  const verifiedAgents = [];
-  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 — agent skipped from dispatch`,
-      });
-    } else {
-      verifiedAgents.push(agent);
-    }
-  }
-  dispatchableAgents = verifiedAgents;
-
-  const shouldDispatch = dispatchableAgents.length >= 2;
-
-  // ── Recommended agents by group ───────────────────────────────────────────
-  const recommended = {};
-  for (const agent of dispatchableAgents) {
-    if (!recommended[agent.group]) recommended[agent.group] = [];
-    recommended[agent.group].push(agent.subagentType);
-  }
-
-  // ── Tasks by group (implement phase only) ─────────────────────────────────
-  let tasks = {};
-  if (phase === 'implement') {
-    const tasksPath = join(projectPath, `.morph/features/${featureName}/4-tasks/tasks.md`);
-    tasks = parseAndGroupTasks(tasksPath);
-  }
-
-  return {
-    feature: featureName,
-    phase,
-    shouldDispatch,
-    reason: shouldDispatch
-      ? `${dispatchableAgents.length} dispatchable agents for phase '${phase}'`
-      : dispatchableAgents.length === 1
-        ? `Only 1 dispatchable agent — sequential execution preferred`
-        : `No dispatchable agents found for phase '${phase}'`,
-    recommended,
-    tasks,
-    agents: dispatchableAgents,
-    warnings,
-  };
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// CLI Handler
-// ─────────────────────────────────────────────────────────────────────────────
-
-/**
- * CLI command: morph-spec dispatch-agents <feature> <phase>
- */
-export async function dispatchAgentsCommand(featureName, phase, options = {}) {
-  if (!featureName || !phase) {
-    console.error(chalk.red('Usage: morph-spec dispatch-agents <feature> <phase>'));
-    console.error(chalk.gray('Phases: design | tasks | implement'));
-    process.exit(1);
-  }
-
-  const normalizedPhase = phase.toLowerCase();
-  if (!DISPATCHABLE_PHASES.includes(normalizedPhase)) {
-    console.error(chalk.red(`Invalid phase: '${phase}'. Must be one of: ${DISPATCHABLE_PHASES.join(', ')}`));
-    process.exit(1);
-  }
-
-  if (!stateExists()) {
-    console.error(chalk.red('No state.json found. Run morph-spec state init first.'));
-    process.exit(1);
-  }
-
-  try {
-    const dispatchOpts = {};
-    if (options.mode) dispatchOpts.mode = options.mode;
-    const config = await buildDispatchConfig(process.cwd(), featureName, normalizedPhase, dispatchOpts);
-
-    // Log dispatch to state.json so enforcement gates can verify it happened
-    if (config.agents?.length > 0) {
-      try {
-        logDispatch(featureName, {
-          timestamp: new Date().toISOString(),
-          phase: normalizedPhase,
-          agents: config.agents.map(a => ({
-            id: a.id,
-            subagentType: a.subagentType,
-            group: a.group,
-            tasks: config.tasks?.[a.group] || [],
-          })),
-        });
-      } catch {
-        // Non-blocking — dispatch output still succeeds even if log fails
-      }
-    }
-
-    if (options.table) {
-      // Human-readable table format
-      console.log(chalk.bold(`\n  Dispatch Config — ${featureName} (${normalizedPhase})`));
-      console.log('  ' + '─'.repeat(62));
-
-      const dispatchLabel = config.shouldDispatch ? chalk.green('YES') : chalk.yellow('NO');
-      console.log(`  Should dispatch: ${dispatchLabel}`);
-      console.log(`  Reason:          ${config.reason}`);
-
-      if (config.agents?.length > 0) {
-        console.log(`\n  Agents (${config.agents.length}):`);
-        console.log(`  ${'ID'.padEnd(28)} ${'Group'.padEnd(16)} Tier`);
-        console.log('  ' + '─'.repeat(50));
-        for (const agent of config.agents) {
-          console.log(
-            `  ${(agent.icon + ' ' + agent.id).padEnd(28)} ` +
-            `${chalk.cyan(agent.group.padEnd(16))} ` +
-            `${agent.tier}`
-          );
-        }
-      } else {
-        console.log(chalk.gray('\n  No dispatchable agents.'));
-      }
-
-      const recEntries = Object.entries(config.recommended || {});
-      if (recEntries.length > 0) {
-        console.log(`\n  Recommended:`);
-        console.log(`  ${'Group'.padEnd(20)} ${'Tasks'.padEnd(8)} Agents`);
-        console.log('  ' + '─'.repeat(50));
-        for (const [group, agentTypes] of recEntries) {
-          const taskCount = config.tasks?.[group]?.length || 0;
-          console.log(
-            `  ${group.padEnd(20)} ` +
-            `${String(taskCount).padEnd(8)} ` +
-            `${agentTypes.join(', ')}`
-          );
-        }
-      }
-      console.log();
-    } else {
-      // 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);
-    process.exit(1);
-  }
-}

package/src/commands/agents/index.js

@@ -1,13 +0,0 @@
-/**
- * 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';