convoke-agents 3.1.0 → 3.2.0

package/_bmad/bme/_team-factory/lib/writers/activation-validator.js

@@ -0,0 +1,175 @@
+'use strict';
+
+const fs = require('fs-extra');
+const path = require('path');
+
+/** @typedef {import('../types/factory-types')} Types */
+
+/**
+ * Regex to extract activation XML block from agent markdown files.
+ * Matches <activation ...>...</activation> including multiline content.
+ */
+const ACTIVATION_REGEX = /<activation[^>]*>([\s\S]*?)<\/activation>/;
+
+/**
+ * Validate activation blocks in generated agent .md files.
+ * Read-only — this module NEVER writes to any file.
+ *
+ * Checks:
+ * 1. Activation block exists in the agent file
+ * 2. Config path reference points to the team's config.yaml
+ * 3. Module path reference is correct
+ *
+ * @param {string[]} agentFiles - Array of absolute paths to agent .md files
+ * @param {Object} moduleConfig - Module context for validation
+ * @param {string} moduleConfig.configPath - Expected config.yaml path
+ * @param {string} moduleConfig.modulePath - Expected module path (e.g., "bme/_team-name")
+ * @param {string} moduleConfig.moduleDir - Absolute path to module directory
+ * @returns {Promise<import('../types/factory-types').ValidationResult>}
+ */
+async function validateActivation(agentFiles, moduleConfig) {
+  const results = [];
+
+  for (const agentFile of agentFiles) {
+    const result = await validateSingleAgent(agentFile, moduleConfig);
+    results.push(result);
+  }
+
+  const valid = results.every(r => r.errors.length === 0);
+  return { valid, results };
+}
+
+/**
+ * Validate a single agent file's activation block.
+ * @param {string} agentFile - Absolute path to agent .md file
+ * @param {Object} moduleConfig - Module context
+ * @returns {Promise<import('../types/factory-types').ActivationResult>}
+ */
+async function validateSingleAgent(agentFile, moduleConfig) {
+  const checks = [];
+  const errors = [];
+
+  // Read agent file
+  let content;
+  try {
+    content = await fs.readFile(agentFile, 'utf8');
+  } catch (err) {
+    return { agentFile, checks: [], errors: [`Cannot read agent file: ${err.message}`] };
+  }
+
+  // Check 1: Activation block exists
+  const match = content.match(ACTIVATION_REGEX);
+  if (!match) {
+    checks.push({ check: 'Activation block exists', passed: false, detail: 'No <activation> block found in agent file' });
+    errors.push('No <activation> block found');
+    return { agentFile, checks, errors };
+  }
+  checks.push({ check: 'Activation block exists', passed: true });
+
+  const activationContent = match[0];
+
+  // Check 2: Config path reference
+  const configPathValid = activationContent.includes(moduleConfig.configPath);
+  checks.push({
+    check: 'Config path reference',
+    passed: configPathValid,
+    detail: configPathValid ? undefined : `Expected reference to "${moduleConfig.configPath}" not found in activation block`
+  });
+  if (!configPathValid) {
+    errors.push(`Config path "${moduleConfig.configPath}" not referenced in activation block`);
+  }
+
+  // Check 3: Config file exists on disk
+  const configAbsPath = path.resolve(moduleConfig.moduleDir, 'config.yaml');
+  const configExists = await fs.pathExists(configAbsPath);
+  checks.push({
+    check: 'Config file exists',
+    passed: configExists,
+    detail: configExists ? undefined : `Config file not found at ${configAbsPath}`
+  });
+  if (!configExists) {
+    errors.push(`Config file does not exist at ${configAbsPath}`);
+  }
+
+  // Check 4: Module path reference — strict module= attribute match only
+  const moduleAttrRegex = /module\s*=\s*"([^"]*)"/;
+  const moduleAttrMatch = activationContent.match(moduleAttrRegex);
+  const modulePathValid = moduleAttrMatch
+    ? moduleAttrMatch[1] === moduleConfig.modulePath
+    : false;
+  checks.push({
+    check: 'Module path reference',
+    passed: modulePathValid,
+    detail: modulePathValid
+      ? undefined
+      : moduleAttrMatch
+        ? `Expected module="${moduleConfig.modulePath}" but found module="${moduleAttrMatch[1]}" in activation block`
+        : `No module="..." attribute found in activation block`
+  });
+  if (!modulePathValid) {
+    errors.push(`Module path "${moduleConfig.modulePath}" not referenced correctly in activation block`);
+  }
+
+  // Check 5: Module directory exists
+  const moduleDirExists = await fs.pathExists(moduleConfig.moduleDir);
+  checks.push({
+    check: 'Module directory exists',
+    passed: moduleDirExists,
+    detail: moduleDirExists ? undefined : `Module directory not found at ${moduleConfig.moduleDir}`
+  });
+  if (!moduleDirExists) {
+    errors.push(`Module directory does not exist at ${moduleConfig.moduleDir}`);
+  }
+
+  return { agentFile, checks, errors };
+}
+
+// --- CLI entry point ---
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const agentFilesIdx = args.indexOf('--agent-files');
+  const configPathIdx = args.indexOf('--config-path');
+
+  if (agentFilesIdx === -1 || configPathIdx === -1) {
+    console.error('Usage: node activation-validator.js --agent-files <glob-or-paths> --config-path <path>');
+    process.exit(1);
+  }
+
+  const agentGlob = args[agentFilesIdx + 1];
+  const configPath = args[configPathIdx + 1];
+
+  (async () => {
+    try {
+      // Resolve agent files from glob or comma-separated list
+      let agentFiles;
+      if (agentGlob.includes('*')) {
+        // Use fs.readdir-based simple glob for *.md in a directory
+        const dir = path.dirname(agentGlob);
+        const entries = await fs.readdir(dir);
+        agentFiles = entries
+          .filter(e => e.endsWith('.md'))
+          .map(e => path.join(dir, e));
+      } else {
+        agentFiles = agentGlob.split(',').map(f => f.trim());
+      }
+
+      // Derive module context from config path
+      const moduleDir = path.dirname(configPath);
+      const modulePath = path.relative(path.resolve(moduleDir, '../../'), moduleDir);
+
+      const result = await validateActivation(agentFiles, {
+        configPath: configPath,
+        modulePath: modulePath,
+        moduleDir: moduleDir
+      });
+
+      console.log(JSON.stringify(result, null, 2));
+      process.exit(result.valid ? 0 : 1);
+    } catch (err) {
+      console.log(JSON.stringify({ valid: false, results: [], errors: [err.message] }, null, 2));
+      process.exit(1);
+    }
+  })();
+}
+
+module.exports = { validateActivation, validateSingleAgent, ACTIVATION_REGEX };

package/_bmad/bme/_team-factory/lib/writers/config-appender.js

@@ -0,0 +1,192 @@
+'use strict';
+
+const fs = require('fs-extra');
+const path = require('path');
+const yaml = require('js-yaml');
+const YAML = require('yaml'); // Comment-preserving YAML library (ag-7-1: I10). Used for the WRITE round-trip; js-yaml stays for the post-write read-back validation.
+const { checkDirtyTree } = require('./registry-writer');
+
+/** @typedef {import('../types/factory-types').CreatorResult} CreatorResult */
+
+/**
+ * Append a new agent ID to an existing team's config.yaml.
+ * Enhanced Simple safety: read → validate → write (.tmp) → verify parse → rename.
+ *
+ * @param {string} newAgentId - Agent ID to add (e.g., "gamma-guardian")
+ * @param {string} configPath - Absolute path to existing config.yaml
+ * @param {Object} [options]
+ * @param {boolean} [options.skipDirtyCheck] - Skip git dirty-tree detection (for tests)
+ * @returns {Promise<CreatorResult>}
+ */
+async function appendConfigAgent(newAgentId, configPath, options = {}) {
+  if (!newAgentId || !newAgentId.trim()) {
+    return { success: false, filePath: configPath, errors: ['newAgentId is required'] };
+  }
+
+  // --- Read existing config ---
+  if (!await fs.pathExists(configPath)) {
+    return { success: false, filePath: configPath, errors: ['config.yaml does not exist at target path'] };
+  }
+
+  // --- Dirty-tree detection (per-write) ---
+  if (!options.skipDirtyCheck) {
+    const dirtyResult = checkDirtyTree(configPath);
+    if (dirtyResult.dirty) {
+      return { success: false, filePath: configPath, errors: [], dirty: true, diff: dirtyResult.diff };
+    }
+  }
+
+  let content;
+  try {
+    content = await fs.readFile(configPath, 'utf8');
+  } catch (err) {
+    return { success: false, filePath: configPath, errors: [`Cannot read config: ${err.message}`] };
+  }
+
+  // --- Parse and validate (ag-7-1: I10 — use comment-preserving YAML.parseDocument) ---
+  // Note: YAML.parseDocument does NOT throw on syntax errors; it returns a Document
+  // with .errors populated. Check both throw AND doc.errors to match js-yaml semantics.
+  let doc;
+  let config;
+  try {
+    doc = YAML.parseDocument(content);
+    if (doc.errors && doc.errors.length > 0) {
+      return { success: false, filePath: configPath, errors: [`Cannot parse config YAML: ${doc.errors[0].message}`] };
+    }
+    config = doc.toJSON();
+  } catch (err) {
+    return { success: false, filePath: configPath, errors: [`Cannot parse config YAML: ${err.message}`] };
+  }
+
+  if (!config || !Array.isArray(config.agents)) {
+    return { success: false, filePath: configPath, errors: ['config.yaml missing agents array'] };
+  }
+
+  // --- Duplicate check (additive-only) ---
+  if (config.agents.includes(newAgentId)) {
+    return { success: true, filePath: configPath, errors: [], skipped: 'agent already in config' };
+  }
+
+  // --- Append (mutate via Document API to preserve comments) ---
+  const agentsNode = doc.get('agents');
+  if (agentsNode && typeof agentsNode.add === 'function') {
+    agentsNode.add(newAgentId);
+  } else {
+    // Fallback: create a new sequence with the appended item
+    doc.set('agents', [...config.agents, newAgentId]);
+  }
+
+  // --- Atomic write (.tmp → validate → rename) ---
+  const tmpPath = configPath + '.tmp';
+  try {
+    const newContent = doc.toString({ lineWidth: 0 });
+    await fs.writeFile(tmpPath, newContent, 'utf8');
+
+    // Verify parse of tmp file (ag-7-1 Task 5.4: read-back stays on js-yaml — checks structure only, not comments)
+    const readBack = yaml.load(await fs.readFile(tmpPath, 'utf8'));
+    if (!readBack || !Array.isArray(readBack.agents) || !readBack.agents.includes(newAgentId)) {
+      await fs.remove(tmpPath);
+      return { success: false, filePath: configPath, errors: ['Post-write verification failed: new agent not found in parsed output'] };
+    }
+
+    // Rename tmp → target
+    await fs.rename(tmpPath, configPath);
+  } catch (err) {
+    await fs.remove(tmpPath).catch(() => {});
+    return { success: false, filePath: configPath, errors: [`Write failed: ${err.message}`] };
+  }
+
+  return { success: true, filePath: configPath, errors: [] };
+}
+
+/**
+ * Append a new workflow name to an existing team's config.yaml.
+ * Enhanced Simple safety: read → validate → write (.tmp) → verify parse → rename.
+ *
+ * @param {string} newWorkflowName - Workflow name to add (kebab-case, e.g., "data-analysis")
+ * @param {string} configPath - Absolute path to existing config.yaml
+ * @param {Object} [options]
+ * @param {boolean} [options.skipDirtyCheck] - Skip git dirty-tree detection (for tests)
+ * @returns {Promise<CreatorResult>}
+ */
+async function appendConfigWorkflow(newWorkflowName, configPath, options = {}) {
+  if (!newWorkflowName || !newWorkflowName.trim()) {
+    return { success: false, filePath: configPath, errors: ['newWorkflowName is required'] };
+  }
+
+  // --- Read existing config ---
+  if (!await fs.pathExists(configPath)) {
+    return { success: false, filePath: configPath, errors: ['config.yaml does not exist at target path'] };
+  }
+
+  // --- Dirty-tree detection (per-write) ---
+  if (!options.skipDirtyCheck) {
+    const dirtyResult = checkDirtyTree(configPath);
+    if (dirtyResult.dirty) {
+      return { success: false, filePath: configPath, errors: [], dirty: true, diff: dirtyResult.diff };
+    }
+  }
+
+  let content;
+  try {
+    content = await fs.readFile(configPath, 'utf8');
+  } catch (err) {
+    return { success: false, filePath: configPath, errors: [`Cannot read config: ${err.message}`] };
+  }
+
+  // --- Parse and validate (ag-7-1: I10 — use comment-preserving YAML.parseDocument) ---
+  // Note: YAML.parseDocument does NOT throw on syntax errors; it returns a Document
+  // with .errors populated. Check both throw AND doc.errors to match js-yaml semantics.
+  let doc;
+  let config;
+  try {
+    doc = YAML.parseDocument(content);
+    if (doc.errors && doc.errors.length > 0) {
+      return { success: false, filePath: configPath, errors: [`Cannot parse config YAML: ${doc.errors[0].message}`] };
+    }
+    config = doc.toJSON();
+  } catch (err) {
+    return { success: false, filePath: configPath, errors: [`Cannot parse config YAML: ${err.message}`] };
+  }
+
+  if (!config || !Array.isArray(config.workflows)) {
+    return { success: false, filePath: configPath, errors: ['config.yaml missing workflows array'] };
+  }
+
+  // --- Duplicate check (additive-only) ---
+  if (config.workflows.includes(newWorkflowName)) {
+    return { success: true, filePath: configPath, errors: [], skipped: 'workflow already in config' };
+  }
+
+  // --- Append (mutate via Document API to preserve comments) ---
+  const workflowsNode = doc.get('workflows');
+  if (workflowsNode && typeof workflowsNode.add === 'function') {
+    workflowsNode.add(newWorkflowName);
+  } else {
+    doc.set('workflows', [...config.workflows, newWorkflowName]);
+  }
+
+  // --- Atomic write (.tmp → validate → rename) ---
+  const tmpPath = configPath + '.tmp';
+  try {
+    const newContent = doc.toString({ lineWidth: 0 });
+    await fs.writeFile(tmpPath, newContent, 'utf8');
+
+    // Verify parse of tmp file (ag-7-1 Task 5.4: read-back stays on js-yaml — checks structure only, not comments)
+    const readBack = yaml.load(await fs.readFile(tmpPath, 'utf8'));
+    if (!readBack || !Array.isArray(readBack.workflows) || !readBack.workflows.includes(newWorkflowName)) {
+      await fs.remove(tmpPath);
+      return { success: false, filePath: configPath, errors: ['Post-write verification failed: new workflow not found in parsed output'] };
+    }
+
+    // Rename tmp → target
+    await fs.rename(tmpPath, configPath);
+  } catch (err) {
+    await fs.remove(tmpPath).catch(() => {});
+    return { success: false, filePath: configPath, errors: [`Write failed: ${err.message}`] };
+  }
+
+  return { success: true, filePath: configPath, errors: [] };
+}
+
+module.exports = { appendConfigAgent, appendConfigWorkflow };

package/_bmad/bme/_team-factory/lib/writers/config-creator.js

@@ -0,0 +1,215 @@
+'use strict';
+
+const fs = require('fs-extra');
+const path = require('path');
+const yaml = require('js-yaml');
+const { toKebab, deriveWorkflowName } = require('../utils/naming-utils');
+
+/** @typedef {import('../types/factory-types')} Types */
+
+/**
+ * Create a per-module config.yaml for a new team.
+ * Matches the Gyre/Vortex config.yaml schema exactly.
+ *
+ * Safety: Simple (write → verify parse). Additive-only (NFR17).
+ * Collision detection runs before writing (NFR15).
+ *
+ * @param {Object} specData - Parsed team spec file content
+ * @param {string} outputPath - Full path to write config.yaml
+ * @param {string} bmeRoot - Path to _bmad/bme/ directory for collision scanning
+ * @returns {Promise<import('../types/factory-types').CreatorResult>}
+ */
+async function createConfig(specData, outputPath, bmeRoot) {
+  const errors = [];
+
+  // --- Additive-only check (NFR17) ---
+  if (await fs.pathExists(outputPath)) {
+    return { success: false, filePath: outputPath, errors: ['config.yaml already exists at target path — additive-only, will not overwrite'], collisions: [] };
+  }
+
+  // --- Collision detection (NFR15) ---
+  const collisions = await detectCollisions(specData, bmeRoot);
+  if (collisions.length > 0) {
+    return { success: false, filePath: outputPath, errors: ['Collision(s) detected with existing modules'], collisions };
+  }
+
+  // --- Build config data ---
+  const configData = buildConfigData(specData);
+
+  // --- Write config.yaml ---
+  try {
+    await fs.ensureDir(path.dirname(outputPath));
+    const content = yaml.dump(configData, { indent: 2, lineWidth: -1, noRefs: true });
+    await fs.writeFile(outputPath, content, 'utf8');
+  } catch (err) {
+    return { success: false, filePath: outputPath, errors: [`Write failed: ${err.message}`], collisions: [] };
+  }
+
+  // --- Verify parse (Simple safety) ---
+  try {
+    const readBack = await fs.readFile(outputPath, 'utf8');
+    const parsed = yaml.load(readBack);
+    if (!parsed || !parsed.submodule_name || !parsed.agents || !parsed.workflows) {
+      errors.push('Verification failed: config.yaml missing required fields after write');
+    }
+  } catch (err) {
+    errors.push(`Verification failed: ${err.message}`);
+  }
+
+  if (errors.length > 0) {
+    return { success: false, filePath: outputPath, errors, collisions: [] };
+  }
+
+  return { success: true, filePath: outputPath, errors: [], collisions: [] };
+}
+
+/**
+ * Build config.yaml data matching Gyre/Vortex schema.
+ * @param {Object} specData - Parsed team spec file
+ * @returns {import('../types/factory-types').ConfigData}
+ */
+function buildConfigData(specData) {
+  const agents = (specData.agents || []).map(a => a.id);
+
+  // Derive workflow names from agents' capabilities (first capability kebab-case)
+  // or use workflow_names if available in spec
+  const workflows = deriveWorkflowNames(specData);
+
+  return {
+    submodule_name: `_${specData.team_name_kebab}`,
+    description: specData.description || `${specData.team_name} team module`,
+    module: 'bme',
+    output_folder: specData.integration.output_directory,
+    agents,
+    workflows,
+    version: '1.0.0',
+    user_name: '{user}',
+    communication_language: 'en',
+    party_mode_enabled: true,
+    core_module: 'bme'
+  };
+}
+
+/**
+ * Derive workflow names from spec data.
+ * Uses shared deriveWorkflowName() for per-agent logic, then deduplicates.
+ * @param {Object} specData
+ * @returns {string[]}
+ */
+function deriveWorkflowNames(specData) {
+  const names = (specData.agents || []).map(agent => deriveWorkflowName(agent, specData));
+
+  // Check for intra-spec duplicate workflow names
+  const seen = new Set();
+  for (let i = 0; i < names.length; i++) {
+    if (seen.has(names[i])) {
+      const agent = (specData.agents || [])[i];
+      // Disambiguate by appending agent id
+      names[i] = `${names[i]}-${(agent && agent.id) || i}`;
+    }
+    seen.add(names[i]);
+  }
+
+  return names;
+}
+
+/**
+ * Scan existing config.yaml files in bmeRoot for collisions (NFR15).
+ * Checks submodule_name, agent IDs, and workflow names.
+ * @param {Object} specData - New team spec
+ * @param {string} bmeRoot - Path to _bmad/bme/
+ * @returns {Promise<import('../types/factory-types').Collision[]>}
+ */
+async function detectCollisions(specData, bmeRoot) {
+  const collisions = [];
+  const newSubmodule = `_${specData.team_name_kebab}`;
+  const newAgentIds = (specData.agents || []).map(a => a.id);
+  const newWorkflows = deriveWorkflowNames(specData);
+
+  // Find all existing config.yaml files under bmeRoot
+  let entries;
+  try {
+    entries = await fs.readdir(bmeRoot);
+  } catch {
+    return collisions; // bmeRoot doesn't exist yet — no collisions possible
+  }
+
+  for (const entry of entries) {
+    // Skip the new team's own directory to avoid self-collision on re-run
+    if (entry === newSubmodule) continue;
+    const configPath = path.join(bmeRoot, entry, 'config.yaml');
+    if (!await fs.pathExists(configPath)) continue;
+
+    let existing;
+    try {
+      existing = yaml.load(await fs.readFile(configPath, 'utf8'));
+    } catch {
+      continue; // Skip unparseable configs
+    }
+    if (!existing) continue;
+
+    const moduleName = entry;
+
+    // Check submodule_name collision
+    if (existing.submodule_name === newSubmodule) {
+      collisions.push({ field: 'submodule_name', value: newSubmodule, existingModule: moduleName });
+    }
+
+    // Check agent ID collisions
+    const existingAgents = existing.agents || [];
+    for (const agentId of newAgentIds) {
+      if (existingAgents.includes(agentId)) {
+        collisions.push({ field: 'agent', value: agentId, existingModule: moduleName });
+      }
+    }
+
+    // Check workflow name collisions
+    const existingWorkflows = existing.workflows || [];
+    for (const wf of newWorkflows) {
+      if (existingWorkflows.includes(wf)) {
+        collisions.push({ field: 'workflow', value: wf, existingModule: moduleName });
+      }
+    }
+  }
+
+  return collisions;
+}
+
+// --- CLI entry point ---
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const specFileIdx = args.indexOf('--spec-file');
+  const dryRunIdx = args.indexOf('--dry-run');
+
+  if (specFileIdx === -1 || !args[specFileIdx + 1]) {
+    console.error('Usage: node config-creator.js --spec-file <path> [--dry-run]');
+    process.exit(1);
+  }
+
+  const specFilePath = args[specFileIdx + 1];
+  const dryRun = dryRunIdx !== -1;
+
+  (async () => {
+    try {
+      const specContent = await fs.readFile(specFilePath, 'utf8');
+      const specData = yaml.load(specContent);
+      const bmeRoot = path.resolve(__dirname, '../../../../');
+      const outputPath = path.join(bmeRoot, `_${specData.team_name_kebab}`, 'config.yaml');
+
+      if (dryRun) {
+        const collisions = await detectCollisions(specData, bmeRoot);
+        console.log(JSON.stringify({ dryRun: true, collisions }, null, 2));
+        process.exit(collisions.length > 0 ? 1 : 0);
+      }
+
+      const result = await createConfig(specData, outputPath, bmeRoot);
+      console.log(JSON.stringify(result, null, 2));
+      process.exit(result.success ? 0 : 1);
+    } catch (err) {
+      console.log(JSON.stringify({ success: false, errors: [err.message] }, null, 2));
+      process.exit(1);
+    }
+  })();
+}
+
+module.exports = { createConfig, buildConfigData, detectCollisions, deriveWorkflowNames, toKebab };

package/_bmad/bme/_team-factory/lib/writers/csv-appender.js

@@ -0,0 +1,118 @@
+'use strict';
+
+const fs = require('fs-extra');
+const path = require('path');
+const { CSV_HEADER, formatCsvRow, csvQuote, deriveCode, toTitleCase } = require('./csv-creator');
+const { checkDirtyTree } = require('./registry-writer');
+
+/** @typedef {import('../types/factory-types').CreatorResult} CreatorResult */
+
+/**
+ * Append a new row to an existing team's module-help.csv.
+ * Enhanced Simple safety: read → validate header → append → write (.tmp) → verify → rename.
+ *
+ * @param {Object} rowData - Data for the new CSV row
+ * @param {string} rowData.module - Module path (e.g., "bme/_gyre")
+ * @param {string} rowData.workflowName - Workflow name (kebab-case)
+ * @param {string} rowData.agentId - Agent ID
+ * @param {string} rowData.agentRole - Agent role description
+ * @param {string} rowData.teamNameKebab - Team name for command derivation
+ * @param {string} rowData.outputLocation - Output directory
+ * @param {number} [rowData.sequence] - Optional sequence number (auto-derived if omitted)
+ * @param {string} csvPath - Absolute path to existing module-help.csv
+ * @param {Object} [options]
+ * @param {boolean} [options.skipDirtyCheck] - Skip git dirty-tree detection (for tests)
+ * @returns {Promise<CreatorResult>}
+ */
+async function appendCsvRow(rowData, csvPath, options = {}) {
+  if (!rowData || !rowData.agentId) {
+    return { success: false, filePath: csvPath, rowCount: 0, errors: ['rowData with agentId is required'] };
+  }
+
+  // --- Read existing CSV ---
+  if (!await fs.pathExists(csvPath)) {
+    return { success: false, filePath: csvPath, rowCount: 0, errors: ['module-help.csv does not exist at target path'] };
+  }
+
+  // --- Dirty-tree detection (per-write) ---
+  if (!options.skipDirtyCheck) {
+    const dirtyResult = checkDirtyTree(csvPath);
+    if (dirtyResult.dirty) {
+      return { success: false, filePath: csvPath, rowCount: 0, errors: [], dirty: true, diff: dirtyResult.diff };
+    }
+  }
+
+  let content;
+  try {
+    content = await fs.readFile(csvPath, 'utf8');
+  } catch (err) {
+    return { success: false, filePath: csvPath, rowCount: 0, errors: [`Cannot read CSV: ${err.message}`] };
+  }
+
+  const lines = content.trim().split('\n');
+
+  // --- Validate header ---
+  if (lines[0] !== CSV_HEADER) {
+    return { success: false, filePath: csvPath, rowCount: 0, errors: ['CSV header mismatch — file format not recognized'] };
+  }
+
+  // --- Duplicate check ---
+  const existingRows = lines.slice(1);
+  for (const row of existingRows) {
+    const cols = row.split(',');
+    // Column 8 (index 8) is agent
+    if (cols[8] === rowData.agentId) {
+      return { success: true, filePath: csvPath, rowCount: existingRows.length, errors: [], skipped: 'agent row already exists' };
+    }
+  }
+
+  // --- Build new row ---
+  const sequence = rowData.sequence || ((existingRows.length + 1) * 10);
+  const csvRow = {
+    module: rowData.module,
+    phase: 'anytime',
+    name: toTitleCase(rowData.workflowName),
+    code: deriveCode(rowData.workflowName),
+    sequence,
+    workflow_file: `_bmad/bme/_${rowData.teamNameKebab}/workflows/${rowData.workflowName}/workflow.md`,
+    command: `bmad-${rowData.teamNameKebab}-${rowData.workflowName}`,
+    required: 'false',
+    agent: rowData.agentId,
+    options: 'Create Mode',
+    description: rowData.agentRole,
+    output_location: rowData.outputLocation,
+    outputs: rowData.workflowName,
+  };
+
+  const newLine = formatCsvRow(csvRow);
+
+  // --- Atomic write (.tmp → verify → rename) ---
+  const tmpPath = csvPath + '.tmp';
+  try {
+    const newContent = content.trimEnd() + '\n' + newLine + '\n';
+    await fs.writeFile(tmpPath, newContent, 'utf8');
+
+    // Verify header preserved
+    const readBack = await fs.readFile(tmpPath, 'utf8');
+    const readLines = readBack.trim().split('\n');
+    if (readLines[0] !== CSV_HEADER) {
+      await fs.remove(tmpPath);
+      return { success: false, filePath: csvPath, rowCount: 0, errors: ['Post-write verification failed: header mismatch'] };
+    }
+
+    // Verify row count increased
+    if (readLines.length <= lines.length) {
+      await fs.remove(tmpPath);
+      return { success: false, filePath: csvPath, rowCount: 0, errors: ['Post-write verification failed: row count did not increase'] };
+    }
+
+    await fs.rename(tmpPath, csvPath);
+  } catch (err) {
+    await fs.remove(tmpPath).catch(() => {});
+    return { success: false, filePath: csvPath, rowCount: 0, errors: [`Write failed: ${err.message}`] };
+  }
+
+  return { success: true, filePath: csvPath, rowCount: existingRows.length + 1, errors: [] };
+}
+
+module.exports = { appendCsvRow };