convoke-agents 3.1.0 → 3.2.1

package/_bmad/bme/_team-factory/lib/cascade-logic.js

@@ -0,0 +1,184 @@
+'use strict';
+
+/**
+ * Pattern-aware decision elimination for the Team Factory.
+ * A6'-coupled — adding a third composition pattern = adding a third column to DECISION_CATALOGUE.
+ *
+ * @module cascade-logic
+ */
+
+const KNOWN_PATTERNS = ['Independent', 'Sequential'];
+
+/**
+ * Master catalogue of factory decisions with per-pattern relevance.
+ * Each entry defines whether the decision is active for a given pattern
+ * and whether it's required or optional.
+ *
+ * @type {Array<{id: string, step: string, description: string, patterns: Object}>}
+ */
+const DECISION_CATALOGUE = [
+  {
+    id: 'agent-scope',
+    step: 'scope',
+    description: 'Define agent roles and capabilities',
+    patterns: {
+      Independent: { active: true, required: true },
+      Sequential: { active: true, required: true },
+    },
+  },
+  {
+    id: 'pipeline-order',
+    step: 'scope',
+    description: 'Define agent execution sequence (pipeline positions)',
+    patterns: {
+      Independent: { active: false, required: false },
+      Sequential: { active: true, required: true },
+    },
+  },
+  {
+    id: 'handoff-contracts',
+    step: 'connect',
+    description: 'Design inter-agent handoff contracts',
+    patterns: {
+      Independent: { active: false, required: false },
+      Sequential: { active: true, required: true },
+    },
+  },
+  {
+    id: 'feedback-contracts',
+    step: 'connect',
+    description: 'Design feedback routing contracts (downstream → upstream)',
+    patterns: {
+      Independent: { active: false, required: false },
+      Sequential: { active: true, required: false },
+    },
+  },
+  {
+    id: 'contract-prefix',
+    step: 'connect',
+    description: 'Define naming prefix for contracts (e.g., HC, GC)',
+    patterns: {
+      Independent: { active: false, required: false },
+      Sequential: { active: true, required: true },
+    },
+  },
+  {
+    id: 'compass-routing',
+    step: 'connect',
+    description: 'Create compass routing reference for workflow navigation',
+    patterns: {
+      Independent: { active: true, required: false, defaultValue: 'per-agent' },
+      Sequential: { active: true, required: true, defaultValue: 'shared-reference' },
+    },
+  },
+  {
+    id: 'orchestration-workflow',
+    step: 'connect',
+    description: 'Create pipeline orchestration workflow',
+    patterns: {
+      Independent: { active: false, required: false },
+      Sequential: { active: true, required: true },
+    },
+  },
+  {
+    id: 'output-directory',
+    step: 'connect',
+    description: 'Define artifact output location',
+    patterns: {
+      Independent: { active: true, required: true, defaultValue: '_bmad-output/{team}-artifacts' },
+      Sequential: { active: true, required: true, defaultValue: '_bmad-output/{team}-artifacts' },
+    },
+  },
+  {
+    id: 'naming-enforcement',
+    step: 'scope',
+    description: 'Validate all naming conventions (agent IDs, file names, module directory)',
+    patterns: {
+      Independent: { active: true, required: true },
+      Sequential: { active: true, required: true },
+    },
+  },
+  {
+    id: 'overlap-detection',
+    step: 'scope',
+    description: 'Check proposed agents against existing agent manifest for collisions',
+    patterns: {
+      Independent: { active: true, required: true },
+      Sequential: { active: true, required: true },
+    },
+  },
+];
+
+/**
+ * Given a composition pattern, return which factory decisions are relevant
+ * and which are eliminated.
+ *
+ * @param {string} pattern - "Independent" or "Sequential"
+ * @returns {{ decisions: CascadeDecision[], eliminated: CascadeDecision[], error?: string }}
+ */
+function getCascadeForPattern(pattern) {
+  const validation = validatePattern(pattern);
+  if (!validation.valid) {
+    return { decisions: [], eliminated: [], error: validation.error };
+  }
+
+  const decisions = [];
+  const eliminated = [];
+
+  for (const entry of DECISION_CATALOGUE) {
+    const patternConfig = entry.patterns[pattern];
+    const decision = {
+      id: entry.id,
+      step: entry.step,
+      description: entry.description,
+      required: patternConfig.required,
+      defaultValue: patternConfig.defaultValue || undefined,
+    };
+
+    if (patternConfig.active) {
+      decisions.push(decision);
+    } else {
+      eliminated.push(decision);
+    }
+  }
+
+  return { decisions, eliminated };
+}
+
+/**
+ * Validate that a pattern string is recognized.
+ * @param {string} pattern
+ * @returns {{ valid: boolean, error?: string }}
+ */
+function validatePattern(pattern) {
+  if (!pattern || typeof pattern !== 'string') {
+    return { valid: false, error: 'Pattern must be a non-empty string' };
+  }
+  if (!KNOWN_PATTERNS.includes(pattern)) {
+    return { valid: false, error: `Unknown pattern "${pattern}". Expected one of: ${KNOWN_PATTERNS.join(', ')}` };
+  }
+  return { valid: true };
+}
+
+/**
+ * Get the list of known composition patterns.
+ * @returns {string[]}
+ */
+function getKnownPatterns() {
+  return [...KNOWN_PATTERNS];
+}
+
+/**
+ * @typedef {Object} CascadeDecision
+ * @property {string} id - Decision identifier
+ * @property {string} step - Factory step this belongs to (scope, connect, generate, validate)
+ * @property {string} description - Human-readable description
+ * @property {boolean} required - Whether mandatory for the pattern
+ * @property {string} [defaultValue] - Default if applicable
+ */
+
+module.exports = {
+  getCascadeForPattern,
+  validatePattern,
+  getKnownPatterns,
+};

package/_bmad/bme/_team-factory/lib/collision-detector.js

@@ -0,0 +1,228 @@
+'use strict';
+
+const fs = require('fs-extra');
+
+/**
+ * Detect collisions between a new team spec and existing framework state.
+ * Handles Level 1 (exact ID match) and Level 2 (name similarity).
+ * Level 3 (capability overlap) is LLM reasoning in the workflow step.
+ *
+ * @param {Object} specData - Parsed team spec
+ * @param {string} manifestPath - Absolute path to agent-manifest.csv
+ * @param {string} [bmeDir] - Path to _bmad/bme/ directory for submodule name checks
+ * @returns {Promise<CollisionResult>}
+ */
+async function detectCollisions(specData, manifestPath, bmeDir) {
+  const blocks = [];
+  const warnings = [];
+
+  const dataWarnings = [];
+
+  // Parse existing agent manifest
+  const { agents: existingAgents, warning: manifestWarning } = await parseManifest(manifestPath);
+  if (manifestWarning) dataWarnings.push(manifestWarning);
+
+  // Parse existing submodule directories
+  const { modules: existingModules, warning: modulesWarning } = bmeDir
+    ? await listSubmodules(bmeDir)
+    : { modules: [], warning: null };
+  if (modulesWarning) dataWarnings.push(modulesWarning);
+
+  const proposedTeam = specData.team_name_kebab || '';
+  const proposedAgents = (specData.agents || []).map(a => a.id).filter(Boolean);
+
+  // --- Level 1: Exact submodule name collision ---
+  if (proposedTeam && existingModules.includes(`_${proposedTeam}`)) {
+    blocks.push({
+      level: 'exact',
+      field: 'submodule_name',
+      newValue: `_${proposedTeam}`,
+      existingValue: `_${proposedTeam}`,
+      existingModule: proposedTeam,
+      suggestion: `Module directory _bmad/bme/_${proposedTeam}/ already exists. Choose a different team name.`,
+    });
+  }
+
+  // --- Level 1: Exact agent ID collision ---
+  for (const agentId of proposedAgents) {
+    const match = existingAgents.find(a => a.id === agentId);
+    if (match) {
+      blocks.push({
+        level: 'exact',
+        field: 'agent_id',
+        newValue: agentId,
+        existingValue: match.id,
+        existingModule: match.module,
+        suggestion: `Agent ID "${agentId}" already exists in module "${match.module}". Rename your agent.`,
+      });
+    }
+  }
+
+  // --- Level 2: Similar agent name detection ---
+  for (const agentId of proposedAgents) {
+    for (const existing of existingAgents) {
+      if (existing.id === agentId) continue; // Already caught by Level 1
+
+      const dist = levenshtein(agentId, existing.id);
+      const sharePrefix = sharedPrefix(agentId, existing.id);
+
+      if (dist <= 2 || (sharePrefix >= 4 && dist <= 3)) {
+        warnings.push({
+          level: 'similar',
+          field: 'agent_id',
+          newValue: agentId,
+          existingValue: existing.id,
+          existingModule: existing.module,
+          suggestion: `"${agentId}" is similar to existing "${existing.id}" (${existing.module}). Intentional?`,
+        });
+      }
+    }
+  }
+
+  return {
+    blocks,
+    warnings,
+    dataWarnings,
+    hasBlocking: blocks.length > 0,
+  };
+}
+
+/**
+ * Parse agent-manifest.csv to extract agent IDs and their modules.
+ * @param {string} manifestPath
+ * @returns {Promise<{agents: Array<{id: string, module: string}>, warning: string|null}>}
+ */
+async function parseManifest(manifestPath) {
+  try {
+    const content = await fs.readFile(manifestPath, 'utf8');
+    const lines = content.split('\n').filter(l => l.trim());
+    if (lines.length < 2) return { agents: [], warning: null };
+
+    const results = [];
+    // Skip header (line 0), parse data rows
+    for (let i = 1; i < lines.length; i++) {
+      const fields = parseCSVLine(lines[i]);
+      if (fields.length >= 10) {
+        const id = fields[0].replace(/^"|"$/g, '').trim();
+        const module = fields[9].replace(/^"|"$/g, '').trim();
+        if (id) results.push({ id, module });
+      }
+    }
+    return { agents: results, warning: null };
+  } catch (err) {
+    return { agents: [], warning: `Could not read agent manifest at ${manifestPath}: ${err.message}. Collision detection may be incomplete.` };
+  }
+}
+
+/**
+ * Parse a single CSV line handling quoted fields.
+ * @param {string} line
+ * @returns {string[]}
+ */
+function parseCSVLine(line) {
+  const fields = [];
+  let current = '';
+  let inQuotes = false;
+
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    if (inQuotes) {
+      if (ch === '"' && line[i + 1] === '"') {
+        current += '"';
+        i++; // skip escaped quote
+      } else if (ch === '"') {
+        inQuotes = false;
+      } else {
+        current += ch;
+      }
+    } else {
+      if (ch === '"') {
+        inQuotes = true;
+      } else if (ch === ',') {
+        fields.push(current);
+        current = '';
+      } else {
+        current += ch;
+      }
+    }
+  }
+  fields.push(current);
+  return fields;
+}
+
+/**
+ * List existing submodule directory names under _bmad/bme/.
+ * @param {string} bmeDir
+ * @returns {Promise<{modules: string[], warning: string|null}>}
+ */
+async function listSubmodules(bmeDir) {
+  try {
+    const entries = await fs.readdir(bmeDir, { withFileTypes: true });
+    const modules = entries
+      .filter(e => e.isDirectory() && e.name.startsWith('_'))
+      .map(e => e.name);
+    return { modules, warning: null };
+  } catch (err) {
+    return { modules: [], warning: `Could not read bme directory at ${bmeDir}: ${err.message}. Submodule collision detection skipped.` };
+  }
+}
+
+/**
+ * Compute Levenshtein edit distance between two strings.
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+function levenshtein(a, b) {
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+
+  const matrix = Array.from({ length: b.length + 1 }, (_, i) => [i]);
+  for (let j = 0; j <= a.length; j++) matrix[0][j] = j;
+
+  for (let i = 1; i <= b.length; i++) {
+    for (let j = 1; j <= a.length; j++) {
+      const cost = a[j - 1] === b[i - 1] ? 0 : 1;
+      matrix[i][j] = Math.min(
+        matrix[i - 1][j] + 1,
+        matrix[i][j - 1] + 1,
+        matrix[i - 1][j - 1] + cost,
+      );
+    }
+  }
+
+  return matrix[b.length][a.length];
+}
+
+/**
+ * Count shared prefix length between two strings.
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+function sharedPrefix(a, b) {
+  let i = 0;
+  while (i < a.length && i < b.length && a[i] === b[i]) i++;
+  return i;
+}
+
+/**
+ * @typedef {Object} CollisionResult
+ * @property {CollisionEntry[]} blocks - Level 1: exact matches, must be resolved
+ * @property {CollisionEntry[]} warnings - Level 2: similar names, review recommended
+ * @property {boolean} hasBlocking - true if any blocks exist
+ */
+
+/**
+ * @typedef {Object} CollisionEntry
+ * @property {string} level - "exact" or "similar"
+ * @property {string} field - "agent_id", "submodule_name", or "workflow_name"
+ * @property {string} newValue
+ * @property {string} existingValue
+ * @property {string} existingModule
+ * @property {string} suggestion
+ */
+
+module.exports = {
+  detectCollisions,
+};

package/_bmad/bme/_team-factory/lib/manifest-tracker.js

@@ -0,0 +1,214 @@
+'use strict';
+
+const path = require('path');
+
+/** @typedef {import('./types/factory-types').ManifestEntry} ManifestEntry */
+
+/**
+ * Build a file manifest from spec data and generation context.
+ * The manifest is built from tracked generation variables — NOT filesystem scanning.
+ *
+ * @param {Object} specData - Parsed team spec (needs team_name_kebab, spec_file_path)
+ * @param {Object} generationContext - Context from Step 4
+ * @param {string[]} generationContext.agent_files - Agent .md file paths
+ * @param {string[]} generationContext.workflow_dirs - Workflow directory paths
+ * @param {string[]} [generationContext.contract_files] - Contract .md file paths
+ * @param {string} generationContext.config_yaml_path - Path to config.yaml
+ * @param {string} generationContext.module_help_csv_path - Path to module-help.csv
+ * @param {string} generationContext.module_root - Module root directory
+ * @returns {ManifestEntry[]}
+ */
+function buildManifest(specData, generationContext) {
+  const entries = [];
+  const moduleName = specData.team_name_kebab || 'unknown';
+
+  // Agent files — created
+  for (const agentFile of (generationContext.agent_files || [])) {
+    entries.push({ path: agentFile, operation: 'created', module: moduleName });
+  }
+
+  // Workflow directories — each gets a workflow.md and SKILL.md
+  for (const wfDir of (generationContext.workflow_dirs || [])) {
+    entries.push({ path: path.join(wfDir, 'workflow.md'), operation: 'created', module: moduleName });
+    entries.push({ path: path.join(wfDir, 'SKILL.md'), operation: 'created', module: moduleName });
+  }
+
+  // Contract files — created
+  for (const contractFile of (generationContext.contract_files || [])) {
+    entries.push({ path: contractFile, operation: 'created', module: moduleName });
+  }
+
+  // Compass routing reference — created (if exists in generated_files)
+  const compassFile = path.join(generationContext.module_root || '', 'compass-routing-reference.md');
+  const generatedFiles = generationContext.generated_files || [];
+  if (generatedFiles.includes(compassFile)) {
+    entries.push({ path: compassFile, operation: 'created', module: moduleName });
+  }
+
+  // Config.yaml — created
+  if (generationContext.config_yaml_path) {
+    entries.push({ path: generationContext.config_yaml_path, operation: 'created', module: moduleName });
+  }
+
+  // Module-help.csv — created
+  if (generationContext.module_help_csv_path) {
+    entries.push({ path: generationContext.module_help_csv_path, operation: 'created', module: moduleName });
+  }
+
+  // agent-registry.js — modified
+  entries.push({ path: 'scripts/update/lib/agent-registry.js', operation: 'modified', module: moduleName });
+
+  // Spec file — modified (progress updated)
+  if (specData.spec_file_path) {
+    entries.push({ path: specData.spec_file_path, operation: 'modified', module: moduleName });
+  }
+
+  return entries;
+}
+
+/**
+ * Format a manifest as a human-readable markdown table.
+ * @param {ManifestEntry[]} entries
+ * @returns {string}
+ */
+function formatManifest(entries) {
+  const lines = [];
+  lines.push('| # | Path | Operation | Module |');
+  lines.push('|---|------|-----------|--------|');
+  entries.forEach((entry, i) => {
+    lines.push(`| ${i + 1} | \`${entry.path}\` | ${entry.operation} | ${entry.module} |`);
+  });
+  return lines.join('\n');
+}
+
+/**
+ * Format abort/removal instructions from a manifest.
+ * Created files get `rm`, modified files get `git checkout --`.
+ * @param {ManifestEntry[]} entries
+ * @returns {string}
+ */
+function formatAbortInstructions(entries) {
+  const lines = [];
+  lines.push('# Removal instructions');
+  lines.push('');
+
+  const created = entries.filter(e => e.operation === 'created');
+  const modified = entries.filter(e => e.operation === 'modified');
+
+  if (created.length > 0) {
+    lines.push('# Created files — remove:');
+    for (const entry of created) {
+      lines.push(`rm "${entry.path}"`);
+    }
+    lines.push('');
+  }
+
+  if (modified.length > 0) {
+    lines.push('# Modified files — revert:');
+    for (const entry of modified) {
+      lines.push(`git checkout -- "${entry.path}"`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Build a file manifest for an extension operation (add agent to existing team).
+ * New agent/workflow/contract files are "created"; config, CSV, and registry are "modified".
+ *
+ * @param {Object} extensionContext
+ * @param {string} extensionContext.new_agent_id - New agent ID (for module label)
+ * @param {string[]} extensionContext.new_agent_files - New agent .md file paths
+ * @param {string[]} extensionContext.new_workflow_dirs - New workflow directory paths
+ * @param {string[]} [extensionContext.new_contract_files] - New contract file paths
+ * @param {string} extensionContext.config_yaml_path - Path to config.yaml (modified)
+ * @param {string} extensionContext.module_help_csv_path - Path to module-help.csv (modified)
+ * @returns {ManifestEntry[]}
+ */
+function buildExtensionManifest(extensionContext) {
+  const entries = [];
+  const moduleName = extensionContext.new_agent_id || 'unknown-agent';
+
+  // New agent files — created
+  for (const agentFile of (extensionContext.new_agent_files || [])) {
+    entries.push({ path: agentFile, operation: 'created', module: moduleName });
+  }
+
+  // New workflow directories — each gets workflow.md and SKILL.md
+  for (const wfDir of (extensionContext.new_workflow_dirs || [])) {
+    entries.push({ path: path.join(wfDir, 'workflow.md'), operation: 'created', module: moduleName });
+    entries.push({ path: path.join(wfDir, 'SKILL.md'), operation: 'created', module: moduleName });
+  }
+
+  // New contract files — created
+  for (const contractFile of (extensionContext.new_contract_files || [])) {
+    entries.push({ path: contractFile, operation: 'created', module: moduleName });
+  }
+
+  // Config.yaml — modified (agent appended)
+  if (extensionContext.config_yaml_path) {
+    entries.push({ path: extensionContext.config_yaml_path, operation: 'modified', module: moduleName });
+  }
+
+  // Module-help.csv — modified (row appended)
+  if (extensionContext.module_help_csv_path) {
+    entries.push({ path: extensionContext.module_help_csv_path, operation: 'modified', module: moduleName });
+  }
+
+  // agent-registry.js — modified (agent appended to existing block)
+  entries.push({ path: 'scripts/update/lib/agent-registry.js', operation: 'modified', module: moduleName });
+
+  return entries;
+}
+
+/**
+ * Build a file manifest for a skill/workflow extension (add workflow to existing agent).
+ * New workflow files are "created"; agent .md, config, CSV, and registry are "modified".
+ *
+ * @param {Object} skillContext
+ * @param {string} skillContext.new_workflow_name - New workflow name (for module label)
+ * @param {string} skillContext.agent_id - Target agent ID
+ * @param {string[]} skillContext.new_workflow_files - New workflow file paths (workflow.md, template)
+ * @param {string} [skillContext.agent_file_path] - Agent .md file path (modified for menu)
+ * @param {string} skillContext.config_yaml_path - Path to config.yaml (modified)
+ * @param {string} skillContext.module_help_csv_path - Path to module-help.csv (modified)
+ * @returns {ManifestEntry[]}
+ */
+function buildSkillExtensionManifest(skillContext) {
+  const entries = [];
+  const moduleName = skillContext.new_workflow_name || 'unknown-workflow';
+
+  // New workflow files — created
+  for (const wfFile of (skillContext.new_workflow_files || [])) {
+    entries.push({ path: wfFile, operation: 'created', module: moduleName });
+  }
+
+  // Agent .md file — modified (menu item added)
+  if (skillContext.agent_file_path) {
+    entries.push({ path: skillContext.agent_file_path, operation: 'modified', module: moduleName });
+  }
+
+  // Config.yaml — modified (workflow appended)
+  if (skillContext.config_yaml_path) {
+    entries.push({ path: skillContext.config_yaml_path, operation: 'modified', module: moduleName });
+  }
+
+  // Module-help.csv — modified (row appended)
+  if (skillContext.module_help_csv_path) {
+    entries.push({ path: skillContext.module_help_csv_path, operation: 'modified', module: moduleName });
+  }
+
+  // agent-registry.js — modified (workflow appended to existing block)
+  entries.push({ path: 'scripts/update/lib/agent-registry.js', operation: 'modified', module: moduleName });
+
+  return entries;
+}
+
+module.exports = {
+  buildManifest,
+  buildExtensionManifest,
+  buildSkillExtensionManifest,
+  formatManifest,
+  formatAbortInstructions,
+};