@polymorphism-tech/morph-spec 4.10.6 → 4.10.8

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

@@ -1,4 +1,13 @@
-/**
- * Agent Commands
- */
-export { dispatchAgentsCommand, buildDispatchConfig } from './dispatch-agents.js';
+/**
+ * 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';

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

@@ -0,0 +1,352 @@
+/**
+ * manage-agents.js — CLI command handlers for agent management
+ *
+ * Thin wrappers around agents-manager.js core functions.
+ * Each handler: parses args -> calls core -> formats output via logger.
+ *
+ * @module manage-agents
+ */
+
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createInterface } from 'node:readline';
+import { existsSync, readFileSync } from 'node:fs';
+import chalk from 'chalk';
+import { logger } from '../../utils/logger.js';
+import {
+  loadAgentsFile,
+  saveAgentsFile,
+  listAgents,
+  showAgent,
+  addAgent,
+  editAgent,
+  removeAgent,
+  TIER_LABELS,
+  KNOWN_PHASES,
+} from '../../lib/agents/agents-manager.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENTS_PATH = join(__dirname, '../../../framework/agents.json');
+
+/**
+ * Resolve the agents.json path.
+ * Uses the canonical framework/agents.json (v4 schema).
+ * If running inside a client project (not the framework repo), falls back
+ * to .morph/framework/agents.json.
+ */
+function getAgentsPath() {
+  // Prefer the framework source file (always v4 schema)
+  if (existsSync(AGENTS_PATH)) return AGENTS_PATH;
+  // Fallback for client projects
+  const clientPath = join(process.cwd(), '.morph', 'framework', 'agents.json');
+  if (existsSync(clientPath)) return clientPath;
+  return AGENTS_PATH;
+}
+
+// ── List ────────────────────────────────────────────────────────────────────────
+
+export async function agentListCommand(options) {
+  const agentsData = loadAgentsFile(getAgentsPath());
+  const filters = {};
+  if (options.group) filters.group = options.group;
+  if (options.tier) filters.tier = parseInt(options.tier, 10);
+
+  const result = listAgents(agentsData, filters);
+
+  if (options.json) {
+    console.log(JSON.stringify(result.agents, null, 2));
+    return;
+  }
+
+  if (result.total === 0) {
+    logger.info('No agents found matching filters.');
+    return;
+  }
+
+  logger.header(`Agents (${result.total} total)`);
+
+  // Table header
+  const header = `  ${'ID'.padEnd(28)} ${'Tier'.padEnd(6)} ${'Group'.padEnd(18)} ${'Phases'.padEnd(16)} Keywords`;
+  console.log(chalk.dim(header));
+  console.log(chalk.dim('  ' + '\u2500'.repeat(90)));
+
+  for (const a of result.agents) {
+    const tierLabel = `T${a.tier}`;
+    const group = (a.group || '\u2014').padEnd(18);
+    const phases = (a.phases || '*').padEnd(16);
+    console.log(`  ${a.id.padEnd(28)} ${tierLabel.padEnd(6)} ${group} ${phases} ${a.keywords || '\u2014'}`);
+  }
+
+  logger.blank();
+  const groups = Object.entries(result.groupCounts).map(([g, c]) => `${g}(${c})`).join(' ');
+  logger.dim(`Groups: ${groups}`);
+}
+
+// ── Show ────────────────────────────────────────────────────────────────────────
+
+export async function agentShowCommand(id, options) {
+  const agentsData = loadAgentsFile(getAgentsPath());
+  const agent = showAgent(agentsData, id);
+
+  if (!agent) {
+    const ids = Object.keys(agentsData.agents || {});
+    const similar = ids.filter(aid => levenshtein(aid, id) <= 3);
+    logger.error(`Agent '${id}' not found.`);
+    if (similar.length > 0) {
+      logger.dim(`Did you mean: ${similar.join(', ')}?`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify({ [id]: agent }, null, 2));
+    return;
+  }
+
+  logger.header(`Agent: ${id}`);
+  logger.info(`Title:        ${agent.title}`);
+  logger.info(`Tier:         ${agent.tier} (${TIER_LABELS[agent.tier] || '?'})`);
+  logger.info(`Group:        ${agent.group}`);
+  logger.info(`Phases:       ${(agent.active_phases || []).join(', ')}`);
+  logger.info(`Reports to:   ${agent.reports_to}`);
+  logger.info(`Domains:      ${(agent.domains || []).join(', ') || '\u2014'}`);
+  logger.info(`Keywords:     ${(agent.keywords || []).join(', ') || '\u2014'}`);
+  logger.info(`Validators:   ${(agent.validators || []).join(', ') || '\u2014'}`);
+
+  if (agent.stacks?.length > 0) {
+    logger.info(`Stacks:       ${agent.stacks.join(', ')}`);
+  }
+
+  if (agent.standards?.length > 0) {
+    logger.blank();
+    logger.info('Standards:');
+    for (const s of agent.standards) {
+      logger.dim(`  ${s.id} (scope: ${s.scope}, priority: ${s.priority})`);
+    }
+  }
+
+  if (agent.teammate) {
+    logger.blank();
+    logger.info('Teammate:');
+    logger.dim(`  Role: ${agent.teammate.role}`);
+    logger.dim(`  Icon: ${agent.teammate.icon}`);
+    const prompt = agent.teammate.spawn_prompt || '';
+    const truncated = options.full ? prompt : (prompt.length > 200 ? prompt.slice(0, 200) + '...' : prompt);
+    logger.dim(`  Prompt: ${truncated}`);
+  } else {
+    logger.blank();
+    logger.dim('No teammate configured.');
+  }
+}
+
+// ── Add ─────────────────────────────────────────────────────────────────────────
+
+export async function agentAddCommand(id, options) {
+  const agentsData = loadAgentsFile(getAgentsPath());
+
+  let fields;
+  if (options.nonInteractive) {
+    fields = parseNonInteractiveFlags(options);
+  } else {
+    fields = await runAddWizard(id, agentsData);
+  }
+
+  const result = addAgent(agentsData, id, fields);
+
+  if (!result.success) {
+    for (const e of result.errors) logger.error(e);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (result.warnings?.length > 0) {
+    for (const w of result.warnings) logger.warn(w);
+  }
+
+  saveAgentsFile(getAgentsPath(), result.data);
+  logger.success(`Created agent '${id}' in agents.json`);
+  logger.dim(`Run 'morph-spec setup-infra' to install the .claude/agents/ file`);
+}
+
+// ── Edit ────────────────────────────────────────────────────────────────────────
+
+export async function agentEditCommand(id, options) {
+  const agentsData = loadAgentsFile(getAgentsPath());
+  const changes = {};
+
+  if (options.tier) changes.tier = parseInt(options.tier, 10);
+  if (options.title) changes.title = options.title;
+  if (options.group) changes.group = options.group;
+  if (options.activePhases) changes.active_phases = options.activePhases.split(',').map(s => s.trim());
+  if (options.reportsTo) changes.reports_to = options.reportsTo;
+  if (options.keywords) changes.keywords = options.keywords.split(',').map(s => s.trim());
+  if (options.domains) changes.domains = options.domains.split(',').map(s => s.trim());
+  if (options.spawnPrompt) changes.spawn_prompt = options.spawnPrompt;
+
+  if (Object.keys(changes).length === 0) {
+    logger.error('No changes specified. Use flags like --title, --tier, --keywords, etc.');
+    process.exitCode = 1;
+    return;
+  }
+
+  const result = editAgent(agentsData, id, changes);
+
+  if (!result.success) {
+    for (const e of result.errors) logger.error(e);
+    process.exitCode = 1;
+    return;
+  }
+
+  saveAgentsFile(getAgentsPath(), result.data);
+  logger.success(`Updated agent '${id}'`);
+  for (const c of result.changes) logger.dim(`  ${c}`);
+}
+
+// ── Remove ──────────────────────────────────────────────────────────────────────
+
+export async function agentRemoveCommand(id, options) {
+  const agentsData = loadAgentsFile(getAgentsPath());
+  const agent = showAgent(agentsData, id);
+
+  if (!agent) {
+    logger.error(`Agent '${id}' not found.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  // Show summary
+  logger.info(`Agent: ${id} (T${agent.tier} ${agent.group})`);
+
+  // Check for dependents
+  const dependents = Object.entries(agentsData.agents)
+    .filter(([aid, a]) => aid !== id && a.reports_to === id)
+    .map(([aid]) => aid);
+
+  if (dependents.length > 0) {
+    logger.warn(`These agents report to '${id}': ${dependents.join(', ')}`);
+  }
+
+  // Check state.json for active references (advisory)
+  checkActiveFeatures(id);
+
+  if (!options.force) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise(resolve => {
+      rl.question(chalk.yellow('  Remove this agent? (y/N) '), resolve);
+    });
+    rl.close();
+    if (answer.toLowerCase() !== 'y') {
+      logger.info('Cancelled.');
+      return;
+    }
+  }
+
+  const result = removeAgent(agentsData, id);
+  saveAgentsFile(getAgentsPath(), result.data);
+  logger.success(`Removed agent '${id}' from agents.json`);
+  logger.dim(`Run 'morph-spec setup-infra' to clean up .claude/agents/ files`);
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Levenshtein distance between two strings.
+ * Used for "did you mean?" suggestions on typos.
+ */
+export function levenshtein(a, b) {
+  const m = a.length;
+  const n = b.length;
+  const dp = Array.from({ length: m + 1 }, (_, i) => Array(n + 1).fill(0));
+  for (let i = 0; i <= m; i++) dp[i][0] = i;
+  for (let j = 0; j <= n; j++) dp[0][j] = j;
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      dp[i][j] = a[i - 1] === b[j - 1]
+        ? dp[i - 1][j - 1]
+        : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+    }
+  }
+  return dp[m][n];
+}
+
+/**
+ * Interactive wizard for adding an agent.
+ */
+async function runAddWizard(id, agentsData) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (q) => new Promise(resolve => rl.question(q, resolve));
+
+  console.log(chalk.bold(`\n  Adding agent: ${id}\n`));
+
+  const knownGroups = [...new Set(Object.values(agentsData.agents || {}).map(a => a.group))];
+
+  const tier = parseInt(await ask(`  ? Tier (1=${TIER_LABELS[1]}, 2=${TIER_LABELS[2]}, 3=${TIER_LABELS[3]}, 4=${TIER_LABELS[4]}): `), 10);
+  const title = await ask('  ? Title: ');
+  console.log(chalk.dim(`    Known groups: ${knownGroups.join(', ')}`));
+  const group = await ask('  ? Group: ');
+  const phasesRaw = await ask('  ? Active phases (comma-sep, or * for all): ');
+  const active_phases = phasesRaw.trim() === '*' ? ['*'] : phasesRaw.split(',').map(s => s.trim());
+
+  const existingIds = Object.keys(agentsData.agents || {});
+  console.log(chalk.dim(`    Valid: ${existingIds.slice(0, 5).join(', ')}... or "user"`));
+  const reports_to = await ask('  ? Reports to: ');
+
+  const domainsRaw = await ask('  ? Domains (comma-sep): ');
+  const domains = domainsRaw.split(',').map(s => s.trim()).filter(Boolean);
+  const keywordsRaw = await ask('  ? Keywords (comma-sep): ');
+  const keywords = keywordsRaw.split(',').map(s => s.trim()).filter(Boolean);
+
+  let teammate = null;
+  if (tier >= 3) {
+    const role = await ask('  ? Teammate role: ');
+    const icon = await ask('  ? Teammate icon (emoji): ');
+    const spawn_prompt = await ask('  ? Spawn prompt: ');
+    teammate = { role, icon, spawn_prompt };
+  }
+
+  rl.close();
+
+  return { tier, title, group, active_phases, reports_to, domains, keywords, teammate };
+}
+
+/**
+ * Parse --non-interactive flags into fields object.
+ */
+function parseNonInteractiveFlags(options) {
+  return {
+    tier: options.tier ? parseInt(options.tier, 10) : undefined,
+    title: options.title,
+    group: options.group,
+    active_phases: options.activePhases ? options.activePhases.split(',').map(s => s.trim()) : ['implement'],
+    reports_to: options.reportsTo || 'user',
+    domains: options.domains ? options.domains.split(',').map(s => s.trim()) : [],
+    keywords: options.keywords ? options.keywords.split(',').map(s => s.trim()) : [],
+    teammate: options.spawnPrompt ? {
+      role: options.role || 'specialist',
+      icon: options.icon || '\u{1F527}',
+      spawn_prompt: options.spawnPrompt,
+    } : null,
+  };
+}
+
+/**
+ * Advisory check: is this agent referenced in active features?
+ * Fail-open — any errors are silently ignored.
+ */
+function checkActiveFeatures(agentId) {
+  try {
+    const statePath = join(process.cwd(), '.morph', 'state.json');
+    if (!existsSync(statePath)) return;
+    const state = JSON.parse(readFileSync(statePath, 'utf8'));
+    const activeIn = [];
+    for (const [fname, fdata] of Object.entries(state.features || {})) {
+      if (fdata.activeAgents?.includes(agentId)) activeIn.push(fname);
+    }
+    if (activeIn.length > 0) {
+      logger.warn(`Agent '${agentId}' is active in features: ${activeIn.join(', ')}. Removing from agents.json does not affect state.`);
+    }
+  } catch {
+    /* ignore — state check is advisory */
+  }
+}