convoke-agents 3.0.4 → 3.2.0

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,
+};

package/_bmad/bme/_team-factory/lib/spec-differ.js

@@ -0,0 +1,176 @@
+'use strict';
+
+const fs = require('fs-extra');
+const yaml = require('js-yaml');
+
+/** @typedef {import('./types/factory-types').TeamSpec} TeamSpec */
+
+/**
+ * Step completion states.
+ * @type {Object<string, string>}
+ */
+const STEP_ORDER = ['orient', 'scope', 'connect', 'review', 'generate', 'validate'];
+
+/**
+ * Determine the resume point for a spec file by reading its progress section.
+ * Returns the first step that is not 'complete'.
+ *
+ * For the 'generate' step, also checks per-agent completion status
+ * and returns which agents still need generation.
+ *
+ * @param {string} specPath - Absolute path to the spec file
+ * @returns {Promise<ResumeResult>}
+ */
+async function findResumePoint(specPath) {
+  let raw;
+  try {
+    raw = await fs.readFile(specPath, 'utf8');
+  } catch (err) {
+    return { resumable: false, resumeStep: null, pendingAgents: [], errors: [`Cannot read spec file: ${err.message}`] };
+  }
+
+  let doc;
+  try {
+    doc = yaml.load(raw);
+  } catch (err) {
+    return { resumable: false, resumeStep: null, pendingAgents: [], errors: [`Invalid YAML: ${err.message}`] };
+  }
+
+  if (!doc || !doc.progress) {
+    return { resumable: false, resumeStep: null, pendingAgents: [], errors: ['Spec file has no progress section'] };
+  }
+
+  const progress = doc.progress;
+
+  // Find first non-complete step
+  for (const step of STEP_ORDER) {
+    const status = typeof progress[step] === 'string' ? progress[step] : null;
+
+    if (step === 'generate' && typeof progress[step] === 'object') {
+      // Generate step has per-agent tracking
+      const pending = [];
+      for (const [agentId, agentStatus] of Object.entries(progress[step])) {
+        if (agentStatus !== 'complete') {
+          pending.push(agentId);
+        }
+      }
+      if (pending.length > 0) {
+        return { resumable: true, resumeStep: 'generate', pendingAgents: pending, errors: [] };
+      }
+      // All agents complete — continue to next step
+      continue;
+    }
+
+    if (status !== 'complete') {
+      return { resumable: true, resumeStep: step, pendingAgents: [], errors: [] };
+    }
+  }
+
+  // All steps complete
+  return { resumable: false, resumeStep: null, pendingAgents: [], errors: [], allComplete: true };
+}
+
+/**
+ * Compare two spec objects and return which fields changed.
+ * Used for displaying diffs when resuming or in express mode.
+ *
+ * @param {TeamSpec} oldSpec - Previous spec state
+ * @param {TeamSpec} newSpec - Current spec state
+ * @returns {SpecDiff}
+ */
+function diffSpecs(oldSpec, newSpec) {
+  const changes = [];
+
+  // Compare top-level scalar fields
+  const scalarFields = ['team_name', 'team_name_kebab', 'description', 'composition_pattern', 'factory_version'];
+  for (const field of scalarFields) {
+    if (oldSpec[field] !== newSpec[field]) {
+      changes.push({ field, oldValue: oldSpec[field], newValue: newSpec[field] });
+    }
+  }
+
+  // Compare agent count
+  const oldAgentCount = (oldSpec.agents || []).length;
+  const newAgentCount = (newSpec.agents || []).length;
+  if (oldAgentCount !== newAgentCount) {
+    changes.push({ field: 'agents.length', oldValue: String(oldAgentCount), newValue: String(newAgentCount) });
+  }
+
+  // Compare agent IDs
+  const oldIds = (oldSpec.agents || []).map(a => a.id).sort();
+  const newIds = (newSpec.agents || []).map(a => a.id).sort();
+  const addedAgents = newIds.filter(id => !oldIds.includes(id));
+  const removedAgents = oldIds.filter(id => !newIds.includes(id));
+  if (addedAgents.length > 0) {
+    changes.push({ field: 'agents.added', oldValue: '', newValue: addedAgents.join(', ') });
+  }
+  if (removedAgents.length > 0) {
+    changes.push({ field: 'agents.removed', oldValue: removedAgents.join(', '), newValue: '' });
+  }
+
+  // Compare contract count (Sequential only)
+  const oldContracts = (oldSpec.contracts || []).length;
+  const newContracts = (newSpec.contracts || []).length;
+  if (oldContracts !== newContracts) {
+    changes.push({ field: 'contracts.length', oldValue: String(oldContracts), newValue: String(newContracts) });
+  }
+
+  // Compare progress
+  for (const step of STEP_ORDER) {
+    const oldStatus = typeof oldSpec.progress?.[step] === 'string' ? oldSpec.progress[step] : stableStringify(oldSpec.progress?.[step]);
+    const newStatus = typeof newSpec.progress?.[step] === 'string' ? newSpec.progress[step] : stableStringify(newSpec.progress?.[step]);
+    if (oldStatus !== newStatus) {
+      changes.push({ field: `progress.${step}`, oldValue: oldStatus || 'undefined', newValue: newStatus || 'undefined' });
+    }
+  }
+
+  return {
+    hasChanges: changes.length > 0,
+    changeCount: changes.length,
+    changes,
+  };
+}
+
+/**
+ * JSON.stringify with sorted keys for order-independent comparison.
+ * @param {*} obj
+ * @returns {string}
+ */
+function stableStringify(obj) {
+  if (obj === null || obj === undefined) return String(obj);
+  if (typeof obj !== 'object') return JSON.stringify(obj);
+  const sorted = Object.keys(obj).sort().reduce((acc, key) => {
+    acc[key] = obj[key];
+    return acc;
+  }, {});
+  return JSON.stringify(sorted);
+}
+
+/**
+ * @typedef {Object} ResumeResult
+ * @property {boolean} resumable - True if there's a step to resume from
+ * @property {string|null} resumeStep - The step to resume from
+ * @property {string[]} pendingAgents - For generate step: agents still pending
+ * @property {string[]} errors
+ * @property {boolean} [allComplete] - True if all steps are complete
+ */
+
+/**
+ * @typedef {Object} SpecDiff
+ * @property {boolean} hasChanges
+ * @property {number} changeCount
+ * @property {SpecChange[]} changes
+ */
+
+/**
+ * @typedef {Object} SpecChange
+ * @property {string} field - Dot-path to the changed field
+ * @property {string} oldValue
+ * @property {string} newValue
+ */
+
+module.exports = {
+  findResumePoint,
+  diffSpecs,
+  STEP_ORDER,
+};

package/_bmad/bme/_team-factory/lib/spec-parser.js

@@ -0,0 +1,201 @@
+'use strict';
+
+const fs = require('fs-extra');
+const path = require('path');
+const yaml = require('js-yaml');
+
+/** @typedef {import('./types/factory-types').TeamSpec} TeamSpec */
+
+const SCHEMAS_DIR = path.join(__dirname, '..', 'schemas');
+
+/**
+ * Load and validate a team spec YAML file.
+ * Selects schema by composition_pattern, validates required fields and naming.
+ *
+ * @param {string} specPath - Absolute path to team spec YAML file
+ * @returns {Promise<{ valid: boolean, spec: TeamSpec|null, errors: string[] }>}
+ */
+async function parseSpec(specPath) {
+  let raw;
+  try {
+    raw = await fs.readFile(specPath, 'utf8');
+  } catch (err) {
+    return { valid: false, spec: null, errors: [`Cannot read spec file: ${err.message}`] };
+  }
+
+  let doc;
+  try {
+    doc = yaml.load(raw);
+  } catch (err) {
+    return { valid: false, spec: null, errors: [`Invalid YAML: ${err.message}`] };
+  }
+
+  if (!doc || typeof doc !== 'object') {
+    return { valid: false, spec: null, errors: ['Spec file is empty or not an object'] };
+  }
+
+  // Determine pattern and load schema
+  const pattern = doc.composition_pattern;
+  if (!pattern) {
+    return { valid: false, spec: null, errors: ['Missing required field: composition_pattern'] };
+  }
+
+  const schemaFile = pattern === 'Sequential'
+    ? 'schema-sequential.json'
+    : pattern === 'Independent'
+      ? 'schema-independent.json'
+      : null;
+
+  if (!schemaFile) {
+    return { valid: false, spec: null, errors: [`Unknown composition_pattern: "${pattern}". Expected "Independent" or "Sequential"`] };
+  }
+
+  // Load schema for reference (structural validation below)
+  const schemaPath = path.join(SCHEMAS_DIR, schemaFile);
+  let schema;
+  try {
+    schema = JSON.parse(await fs.readFile(schemaPath, 'utf8'));
+  } catch (err) {
+    return { valid: false, spec: null, errors: [`Cannot load schema ${schemaFile}: ${err.message}`] };
+  }
+
+  // Validate against schema required fields and patterns
+  const errors = validateAgainstSchema(doc, schema, pattern);
+
+  if (errors.length > 0) {
+    return { valid: false, spec: null, errors };
+  }
+
+  return { valid: true, spec: doc, errors: [] };
+}
+
+/**
+ * Validate a parsed document against schema required fields, types, and patterns.
+ * Lightweight validation without ajv — checks required fields, naming patterns, and structural rules.
+ *
+ * @param {Object} doc - Parsed YAML document
+ * @param {Object} schema - JSON Schema object
+ * @param {string} pattern - "Independent" or "Sequential"
+ * @returns {string[]} errors
+ */
+function validateAgainstSchema(doc, schema, pattern) {
+  const errors = [];
+
+  // Check required root fields
+  const required = schema.required || [];
+  for (const field of required) {
+    if (doc[field] === undefined || doc[field] === null) {
+      errors.push(`Missing required field: ${field}`);
+    }
+  }
+
+  // Type checks on key fields
+  if (doc.schema_version !== undefined && typeof doc.schema_version !== 'string') {
+    errors.push(`schema_version must be a string, got ${typeof doc.schema_version}`);
+  } else if (doc.schema_version && !/^\d+\.\d+$/.test(doc.schema_version)) {
+    errors.push(`schema_version "${doc.schema_version}" does not match pattern "N.N" (e.g., "1.0")`);
+  }
+
+  if (doc.composition_pattern !== undefined && doc.composition_pattern !== pattern) {
+    errors.push(`composition_pattern "${doc.composition_pattern}" does not match expected "${pattern}"`);
+  }
+
+  if (doc.team_name !== undefined && (typeof doc.team_name !== 'string' || doc.team_name.length === 0)) {
+    errors.push('team_name must be a non-empty string');
+  }
+
+  // Validate naming patterns
+  const KEBAB_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+  const AGENT_ID_RE = /^[a-z]+(-[a-z]+)*$/;
+
+  if (doc.team_name_kebab && !KEBAB_RE.test(doc.team_name_kebab)) {
+    errors.push(`team_name_kebab "${doc.team_name_kebab}" does not match kebab-case pattern: ${KEBAB_RE}`);
+  }
+
+  // Validate agents array
+  if (Array.isArray(doc.agents)) {
+    if (doc.agents.length === 0) {
+      errors.push('agents array must contain at least one agent');
+    }
+    for (let i = 0; i < doc.agents.length; i++) {
+      const agent = doc.agents[i];
+      if (!agent.id) {
+        errors.push(`agents[${i}]: missing required field "id"`);
+      } else if (!AGENT_ID_RE.test(agent.id)) {
+        errors.push(`agents[${i}].id "${agent.id}" does not match agent ID pattern: ${AGENT_ID_RE}`);
+      }
+      if (!agent.role) {
+        errors.push(`agents[${i}]: missing required field "role"`);
+      }
+
+      // Sequential-specific: pipeline_position required
+      if (pattern === 'Sequential' && agent.pipeline_position === undefined) {
+        errors.push(`agents[${i}]: Sequential pattern requires pipeline_position`);
+      }
+    }
+
+    // Check for duplicate agent IDs
+    const ids = doc.agents.map(a => a.id).filter(Boolean);
+    const dupes = ids.filter((id, i) => ids.indexOf(id) !== i);
+    if (dupes.length > 0) {
+      errors.push(`Duplicate agent IDs: ${[...new Set(dupes)].join(', ')}`);
+    }
+  } else if (required.includes('agents')) {
+    errors.push('agents must be an array');
+  }
+
+  // Sequential-specific validations
+  if (pattern === 'Sequential') {
+    if (!Array.isArray(doc.contracts) || doc.contracts.length === 0) {
+      errors.push('Sequential pattern requires at least one contract');
+    } else {
+      for (let i = 0; i < doc.contracts.length; i++) {
+        const c = doc.contracts[i];
+        if (!c.id) errors.push(`contracts[${i}]: missing required field "id"`);
+        if (!c.source_agent) errors.push(`contracts[${i}]: missing required field "source_agent"`);
+        if (!Array.isArray(c.target_agents) || c.target_agents.length === 0) {
+          errors.push(`contracts[${i}]: target_agents must be a non-empty array`);
+        }
+      }
+    }
+
+    if (!doc.integration?.contract_prefix) {
+      errors.push('Sequential pattern requires integration.contract_prefix');
+    }
+  }
+
+  // Validate integration block
+  if (doc.integration) {
+    if (typeof doc.integration !== 'object' || Array.isArray(doc.integration)) {
+      errors.push('integration must be an object');
+    } else if (!doc.integration.output_directory) {
+      errors.push('integration.output_directory is required');
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Parse a spec from a YAML string (for testing or in-memory use).
+ * Pattern is determined from the document's composition_pattern field.
+ *
+ * @param {string} yamlString - Raw YAML content
+ * @returns {Promise<{ valid: boolean, spec: TeamSpec|null, errors: string[] }>}
+ */
+async function parseSpecFromString(yamlString) {
+  const tmpDir = await fs.mkdtemp(path.join(require('os').tmpdir(), 'bmad-tf-parse-'));
+  const tmpFile = path.join(tmpDir, 'spec.yaml');
+  try {
+    await fs.writeFile(tmpFile, yamlString, 'utf8');
+    return await parseSpec(tmpFile);
+  } finally {
+    await fs.remove(tmpDir);
+  }
+}
+
+module.exports = {
+  parseSpec,
+  parseSpecFromString,
+  validateAgainstSchema,
+};