convoke-agents 3.1.0 → 3.2.1

package/scripts/update/lib/refresh-installation.js

@@ -3,9 +3,10 @@
 const fs = require('fs-extra');
 const path = require('path');
 const yaml = require('js-yaml');
-const { getPackageVersion } = require('./utils');
+const YAML = require('yaml'); // Comment-preserving YAML library (ag-7-1: I29). Use for WRITE sites that need to preserve comments. js-yaml stays for read-only consumers.
+const { getPackageVersion, assertVersion } = require('./utils');
 const configMerger = require('./config-merger');
-const { AGENTS, AGENT_FILES, AGENT_IDS, WORKFLOW_NAMES, USER_GUIDES, GYRE_AGENTS, GYRE_AGENT_FILES, GYRE_AGENT_IDS, GYRE_WORKFLOW_NAMES } = require('./agent-registry');
+const { AGENTS, AGENT_FILES, AGENT_IDS, WORKFLOW_NAMES, USER_GUIDES, GYRE_AGENTS, GYRE_AGENT_FILES, GYRE_AGENT_IDS, GYRE_WORKFLOW_NAMES, EXTRA_BME_AGENTS } = require('./agent-registry');
 
 /**
  * Refresh Installation for Convoke
@@ -91,6 +92,34 @@ async function refreshInstallation(projectRoot, options = {}) {
     if (verbose) console.log('    Skipped workflow copy (dev environment)');
   }
 
+  // 2b1. Standalone bme submodule trees (e.g., _team-factory)
+  // Each EXTRA_BME_AGENTS entry references a submodule directory under _bmad/bme/
+  // that must be copied wholesale so the agent file, workflows, lib code, and config travel together.
+  // Mirrors the workflow loop pattern (2-step remove-then-copy) so renamed/deleted files
+  // in the package don't survive in the user install as stale leftovers.
+  const copiedExtraSubmodules = new Set();
+  if (!isSameRoot) {
+    for (const agent of EXTRA_BME_AGENTS) {
+      if (copiedExtraSubmodules.has(agent.submodule)) continue;
+      copiedExtraSubmodules.add(agent.submodule);
+      const srcDir = path.join(packageRoot, '_bmad', 'bme', agent.submodule);
+      const destDir = path.join(projectRoot, '_bmad', 'bme', agent.submodule);
+      if (fs.existsSync(srcDir)) {
+        // Remove existing destination first to clear stale files
+        // (e.g., renamed/deleted workflow steps from previous versions)
+        if (fs.existsSync(destDir)) {
+          await fs.remove(destDir);
+        }
+        await fs.copy(srcDir, destDir, { overwrite: true });
+        changes.push(`Refreshed standalone bme submodule: ${agent.submodule}`);
+        if (verbose) console.log(`    Refreshed standalone bme submodule: ${agent.submodule}`);
+      }
+    }
+  } else {
+    changes.push('Skipped standalone bme submodule copy (dev environment — files already in place)');
+    if (verbose) console.log('    Skipped standalone bme submodule copy (dev environment)');
+  }
+
   // 2a. Enhance module — read config, copy directory tree, patch target agent menu
   const packageEnhance = path.join(packageRoot, '_bmad', 'bme', '_enhance');
   const enhanceConfigPath = path.join(packageEnhance, 'config.yaml');
@@ -115,12 +144,17 @@ async function refreshInstallation(projectRoot, options = {}) {
 
     if (!isSameRoot) {
       await fs.copy(packageEnhance, targetEnhance, { overwrite: true });
-      // Stamp enhance config version to match package version
+      // Stamp enhance config version to match package version (ag-7-1: I30 + I29).
+      // Uses comment-preserving YAML.parseDocument so the doc comments survive.
       const targetEnhanceConfig = path.join(targetEnhance, 'config.yaml');
       if (fs.existsSync(targetEnhanceConfig)) {
-        const ecContent = yaml.load(fs.readFileSync(targetEnhanceConfig, 'utf8'));
-        ecContent.version = version;
-        fs.writeFileSync(targetEnhanceConfig, yaml.dump(ecContent, { lineWidth: -1 }), 'utf8');
+        assertVersion(version, 'enhance');
+        const ecDoc = YAML.parseDocument(fs.readFileSync(targetEnhanceConfig, 'utf8'));
+        if (ecDoc.errors && ecDoc.errors.length > 0) {
+          throw new Error(`Refresh: cannot parse Enhance config.yaml: ${ecDoc.errors[0].message}`);
+        }
+        ecDoc.set('version', version);
+        fs.writeFileSync(targetEnhanceConfig, ecDoc.toString({ lineWidth: 0 }), 'utf8');
       }
       changes.push('Refreshed Enhance module: _bmad/bme/_enhance/');
       if (verbose) console.log('    Refreshed Enhance module: _bmad/bme/_enhance/');
@@ -189,6 +223,61 @@ async function refreshInstallation(projectRoot, options = {}) {
     }
   }
 
+  // 2c. Artifacts module — read config, copy directory tree, generate skill wrappers
+  // Workflow-only submodule (no agents). Workflows are STANDALONE: each gets a Claude Code
+  // skill wrapper but NO menu patch. The `standalone: true` flag in the workflow entry is
+  // the discriminator — workflows without it are NOT supported in this module today (Story 6.6).
+  const packageArtifacts = path.join(packageRoot, '_bmad', 'bme', '_artifacts');
+  const artifactsConfigPath = path.join(packageArtifacts, 'config.yaml');
+
+  let artifactsConfig = null;
+  if (fs.existsSync(artifactsConfigPath)) {
+    try {
+      artifactsConfig = yaml.load(fs.readFileSync(artifactsConfigPath, 'utf8'));
+    } catch (err) {
+      const msg = `Artifacts config.yaml parse error: ${err.message} — skipping Artifacts installation`;
+      changes.push(msg);
+      if (verbose) console.log(`    ⚠ ${msg}`);
+    }
+  } else {
+    changes.push('Artifacts config.yaml not found — skipping Artifacts installation');
+    if (verbose) console.log('    ⚠ Artifacts config.yaml not found — skipping Artifacts installation');
+  }
+
+  if (artifactsConfig) {
+    // Copy _artifacts/ directory tree
+    const targetArtifacts = path.join(projectRoot, '_bmad', 'bme', '_artifacts');
+
+    if (!isSameRoot) {
+      // Remove existing destination first to clear stale files
+      if (fs.existsSync(targetArtifacts)) {
+        await fs.remove(targetArtifacts);
+      }
+      await fs.copy(packageArtifacts, targetArtifacts, { overwrite: true });
+      // Stamp artifacts config version to match package version (ag-7-1: I30 + I29).
+      // Uses comment-preserving YAML.parseDocument so the standalone:true doc comments survive.
+      const targetArtifactsConfig = path.join(targetArtifacts, 'config.yaml');
+      if (fs.existsSync(targetArtifactsConfig)) {
+        assertVersion(version, 'artifacts');
+        const acDoc = YAML.parseDocument(fs.readFileSync(targetArtifactsConfig, 'utf8'));
+        if (acDoc.errors && acDoc.errors.length > 0) {
+          throw new Error(`Refresh: cannot parse Artifacts config.yaml: ${acDoc.errors[0].message}`);
+        }
+        acDoc.set('version', version);
+        fs.writeFileSync(targetArtifactsConfig, acDoc.toString({ lineWidth: 0 }), 'utf8');
+      }
+      changes.push('Refreshed Artifacts module: _bmad/bme/_artifacts/');
+      if (verbose) console.log('    Refreshed Artifacts module: _bmad/bme/_artifacts/');
+    } else {
+      changes.push('Skipped Artifacts copy (dev environment — files already in place)');
+      if (verbose) console.log('    Skipped Artifacts copy (dev environment)');
+    }
+
+    // Skill wrapper generation for each workflow happens later in section 6d,
+    // after skillsDir is defined (mirrors Enhance pattern: config/copy here, skill
+    // wrappers in section 6c after agent skills are generated).
+  }
+
   // 2d. Gyre module — copy agents, workflows, contracts, config
   const packageGyre = path.join(packageRoot, '_bmad', 'bme', '_gyre');
   const targetGyre = path.join(projectRoot, '_bmad', 'bme', '_gyre');
@@ -257,6 +346,7 @@ async function refreshInstallation(projectRoot, options = {}) {
         agents: GYRE_AGENT_IDS,
         workflows: GYRE_WORKFLOW_NAMES
       };
+      assertVersion(version, 'config-merger:gyre'); // ag-7-1: defense-in-depth before mergeConfig
       const gyreConfigMerged = await configMerger.mergeConfig(gyreConfigTarget, version, gyreUpdates);
       await configMerger.writeConfig(gyreConfigTarget, gyreConfigMerged);
       changes.push(`Updated Gyre config.yaml to v${version}`);
@@ -282,6 +372,7 @@ async function refreshInstallation(projectRoot, options = {}) {
     workflows: WORKFLOW_NAMES
   };
 
+  assertVersion(version, 'config-merger:vortex'); // ag-7-1: defense-in-depth before mergeConfig
   const merged = await configMerger.mergeConfig(configPath, version, updates);
   await configMerger.writeConfig(configPath, merged);
   changes.push(`Updated config.yaml to v${version}`);
@@ -383,16 +474,46 @@ async function refreshInstallation(projectRoot, options = {}) {
     ].map(csvEscape).join(',');
   }
 
+  // Row builder for standalone bme agents (e.g., team-factory) — submodule path differs from team agents
+  function buildExtraBmeAgentRow610(a) {
+    const p = a.persona;
+    return [
+      csvEscape(a.name),
+      csvEscape(''),
+      csvEscape(a.title),
+      csvEscape(a.icon),
+      csvEscape(''),
+      csvEscape(p.role),
+      csvEscape(p.identity),
+      csvEscape(p.communication_style),
+      csvEscape(p.expertise),
+      csvEscape('bme'),
+      csvEscape(`_bmad/bme/${a.submodule}/agents/${a.id}.md`),
+      csvEscape(`bmad-agent-bme-${a.id}`),
+    ].join(',');
+  }
+
+  function buildExtraBmeAgentRowLegacy(a) {
+    const p = a.persona;
+    return [
+      a.id, a.name, a.title, a.icon,
+      p.role, p.identity, p.communication_style, p.expertise,
+      'bme', `_bmad/bme/${a.submodule}/agents/${a.id}.md`,
+    ].map(csvEscape).join(',');
+  }
+
   let bmeRows;
   if (isV610) {
     bmeRows = [
       ...AGENTS.map(a => buildAgentRow610(a, '_vortex')),
       ...GYRE_AGENTS.map(a => buildAgentRow610(a, '_gyre')),
+      ...EXTRA_BME_AGENTS.map(buildExtraBmeAgentRow610),
     ];
   } else {
     bmeRows = [
       ...AGENTS.map(a => buildAgentRowLegacy(a, '_vortex')),
       ...GYRE_AGENTS.map(a => buildAgentRowLegacy(a, '_gyre')),
+      ...EXTRA_BME_AGENTS.map(buildExtraBmeAgentRowLegacy),
     ];
   }
 
@@ -446,6 +567,7 @@ async function refreshInstallation(projectRoot, options = {}) {
   const currentSkillDirs = new Set([
     ...AGENTS.map(a => `bmad-agent-bme-${a.id}`),
     ...GYRE_AGENTS.map(a => `bmad-agent-bme-${a.id}`),
+    ...EXTRA_BME_AGENTS.map(a => `bmad-agent-bme-${a.id}`),
   ]);
   if (fs.existsSync(skillsDir)) {
     const existingSkills = (await fs.readdir(skillsDir)).filter(d => d.startsWith('bmad-agent-bme-'));
@@ -507,6 +629,31 @@ You must fully embody this agent's persona and follow all activation instruction
     if (verbose) console.log(`    Refreshed skill: bmad-agent-bme-${agent.id}/SKILL.md`);
   }
 
+  // 6b1. Generate .claude/skills/ for standalone bme agents (e.g., team-factory)
+  for (const agent of EXTRA_BME_AGENTS) {
+    const skillDir = path.join(skillsDir, `bmad-agent-bme-${agent.id}`);
+    await fs.ensureDir(skillDir);
+    const content = `---
+name: bmad-agent-bme-${agent.id}
+description: ${agent.id} agent
+---
+
+You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
+
+<agent-activation CRITICAL="TRUE">
+1. LOAD the FULL agent file from {project-root}/_bmad/bme/${agent.submodule}/agents/${agent.id}.md
+2. READ its entire contents - this contains the complete agent persona, menu, and instructions
+3. FOLLOW every step in the <activation> section precisely
+4. DISPLAY the welcome/greeting as instructed
+5. PRESENT the numbered menu
+6. WAIT for user input before proceeding
+</agent-activation>
+`;
+    await fs.writeFile(path.join(skillDir, 'SKILL.md'), content, 'utf8');
+    changes.push(`Refreshed skill: bmad-agent-bme-${agent.id}/SKILL.md`);
+    if (verbose) console.log(`    Refreshed skill: bmad-agent-bme-${agent.id}/SKILL.md`);
+  }
+
   // 6c. Copy Enhance workflow skill wrappers and register in manifests
   if (enhanceConfig && !isSameRoot) {
     for (const workflow of enhanceConfig.workflows || []) {
@@ -540,7 +687,7 @@ You must fully embody this agent's persona and follow all activation instruction
       if (fs.existsSync(skManifestPath)) {
         const skCsv = fs.readFileSync(skManifestPath, 'utf8');
         if (!skCsv.includes(`"${canonicalId}"`)) {
-          const skRow = `\n"${canonicalId}","${canonicalId}","Manage RICE initiatives backlog — triage review findings, rescore existing items, or bootstrap new backlogs.","bme","_bmad/bme/_enhance/workflows/${workflow.name}/SKILL.md","true"`;
+          const skRow = `\n"${canonicalId}","${canonicalId}","Manage RICE initiatives backlog — triage review findings, rescore existing items, or bootstrap new backlogs.","bme","_bmad/bme/_enhance/workflows/${workflow.name}/SKILL.md","true",,,`;
           fs.appendFileSync(skManifestPath, skRow, 'utf8');
           changes.push(`Added ${canonicalId} to skill-manifest.csv`);
           if (verbose) console.log(`    Added ${canonicalId} to skill-manifest.csv`);
@@ -554,6 +701,80 @@ You must fully embody this agent's persona and follow all activation instruction
     if (verbose) console.log('    Skipped Enhance skill registration (dev environment)');
   }
 
+  // 6d. Copy Artifacts workflow skill wrappers (Story 6.6)
+  // Each standalone:true workflow gets a skill wrapper at .claude/skills/{workflow.name}/SKILL.md.
+  // workflow.name already carries the bmad- prefix, so we use it verbatim (unlike Enhance which
+  // synthesizes bmad-enhance-${workflow.name}). The remove-then-copy pattern clears any leftover
+  // files from prior installs (e.g., the obsolete bmad-portfolio-status/workflow.md thin wrapper).
+  if (artifactsConfig && !isSameRoot) {
+    for (const workflow of artifactsConfig.workflows || []) {
+      if (workflow.standalone !== true) {
+        const msg = `Artifacts: workflow ${workflow.name} has no standalone:true flag — only standalone workflows are supported, skipping`;
+        changes.push(msg);
+        if (verbose) console.log(`    ⚠ ${msg}`);
+        continue;
+      }
+
+      const destSkillDir = path.join(skillsDir, workflow.name);
+
+      // Remove the destination directory first to clear leftover files from prior installs
+      if (fs.existsSync(destSkillDir)) {
+        await fs.remove(destSkillDir);
+      }
+      await fs.ensureDir(destSkillDir);
+
+      // Copy source SKILL.md from the package (the SKILL.md uses an absolute {project-root}
+      // path to load workflow.md, so workflow.md does NOT need to be co-located).
+      const sourceSkillPath = path.join(packageRoot, '_bmad', 'bme', '_artifacts', 'workflows', workflow.name, 'SKILL.md');
+      const targetSkillPath = path.join(destSkillDir, 'SKILL.md');
+      if (fs.existsSync(sourceSkillPath)) {
+        await fs.copy(sourceSkillPath, targetSkillPath, { overwrite: true });
+        changes.push(`Generated skill wrapper: ${workflow.name}`);
+        if (verbose) console.log(`    Generated skill wrapper: ${workflow.name}`);
+      } else {
+        const msg = `Artifacts: source SKILL.md not found for ${workflow.name} at ${sourceSkillPath}`;
+        changes.push(msg);
+        if (verbose) console.log(`    ⚠ ${msg}`);
+      }
+    }
+  } else if (artifactsConfig && isSameRoot) {
+    changes.push('Skipped Artifacts skill wrapper generation (dev environment — source files unchanged)');
+    if (verbose) console.log('    Skipped Artifacts skill wrapper generation (dev environment)');
+  }
+
+  // 6e. Orphan workflow-wrapper cleanup (Story 7.4, I32)
+  // Removes stale .claude/skills/ directories for workflow wrappers that are no longer
+  // declared in the module configs. Uses a two-strategy matching approach:
+  //   Strategy 1 (Enhance): any bmad-enhance-* dir not in the current union → orphan
+  //   Strategy 2 (Artifacts): any dir whose name exactly matches a known Artifacts
+  //     workflow name but is not in the current union → orphan
+  // All other directories (agent wrappers, upstream BMAD skills, third-party) are ignored.
+  if (!isSameRoot) {
+    const currentWorkflowWrappers = new Set();
+    // Enhance wrappers: bmad-enhance-${workflow.name}
+    if (enhanceConfig && Array.isArray(enhanceConfig.workflows)) {
+      for (const wf of enhanceConfig.workflows) {
+        if (wf && wf.name) currentWorkflowWrappers.add(`bmad-enhance-${wf.name}`);
+      }
+    }
+    // Artifacts wrappers: workflow.name verbatim (only standalone:true are installed,
+    // but we track ALL names so a removed standalone workflow is still recognized as an orphan)
+    const knownArtifactsNames = new Set();
+    if (artifactsConfig && Array.isArray(artifactsConfig.workflows)) {
+      for (const wf of artifactsConfig.workflows) {
+        if (wf && wf.name) {
+          knownArtifactsNames.add(wf.name);
+          if (wf.standalone === true) currentWorkflowWrappers.add(wf.name);
+        }
+      }
+    }
+    const orphanChanges = cleanupOrphanWorkflowWrappers(skillsDir, currentWorkflowWrappers, knownArtifactsNames, { verbose });
+    changes.push(...orphanChanges);
+  } else {
+    changes.push('Skipped orphan workflow-wrapper cleanup (dev environment)');
+    if (verbose) console.log('    Skipped orphan workflow-wrapper cleanup (dev environment)');
+  }
+
   // 7. Generate agent customize files (only if they don't already exist)
   const customizeDir = path.join(projectRoot, '_bmad', '_config', 'agents');
   await fs.ensureDir(customizeDir);
@@ -599,4 +820,68 @@ prompts: []
   return changes;
 }
 
-module.exports = { refreshInstallation };
+/**
+ * Remove orphan workflow-wrapper directories from .claude/skills/.
+ *
+ * Two-strategy matching (Story 7.4, I32):
+ *   Strategy 1: Enhance prefix — any dir starting with `bmad-enhance-` that is
+ *               not in `currentWrappers` is an orphan.
+ *   Strategy 2: Artifacts exact-name — any dir whose name is in `knownArtifactsNames`
+ *               but not in `currentWrappers` is an orphan.
+ * Everything else (agent wrappers, upstream BMAD skills, third-party) is ignored.
+ *
+ * @param {string} skillsDir - Absolute path to .claude/skills/
+ * @param {Set<string>} currentWrappers - Union of live workflow wrapper names
+ * @param {Set<string>} knownArtifactsNames - ALL Artifacts workflow names (including non-standalone)
+ * @param {object} [options]
+ * @param {boolean} [options.verbose] - Log each action
+ * @returns {Array<string>} Changes array entries for removed orphans
+ */
+function cleanupOrphanWorkflowWrappers(skillsDir, currentWrappers, knownArtifactsNames, options = {}) {
+  // Deliberately synchronous (fs.removeSync / fs.readdirSync) — the function returns
+  // Array<string>, not a Promise. The sync pattern keeps the contract simple for both
+  // the caller (section 6e spreads the result into changes[]) and the test file (which
+  // imports the function directly without async scaffolding). The existing agent
+  // stale-skill sweep at section 6 uses async fs.remove because it runs inline in the
+  // async refreshInstallation body; this function is extracted to be testable standalone.
+  const { verbose = false } = options;
+  const changes = [];
+
+  if (!fs.existsSync(skillsDir)) return changes;
+
+  const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const name = entry.name;
+
+    // Skip agent wrappers (handled by existing stale-skill sweep)
+    if (name.startsWith('bmad-agent-bme-')) continue;
+
+    // Strategy 1: Enhance prefix (unambiguous — no upstream module uses bmad-enhance-)
+    if (name.startsWith('bmad-enhance-')) {
+      if (!currentWrappers.has(name)) {
+        fs.removeSync(path.join(skillsDir, name));
+        changes.push(`Removed orphan skill wrapper: ${name}`);
+        if (verbose) console.log(`    Removed orphan skill wrapper: ${name}`);
+      }
+      continue;
+    }
+
+    // Strategy 2: Artifacts exact-name match
+    if (knownArtifactsNames.has(name)) {
+      if (!currentWrappers.has(name)) {
+        fs.removeSync(path.join(skillsDir, name));
+        changes.push(`Removed orphan skill wrapper: ${name}`);
+        if (verbose) console.log(`    Removed orphan skill wrapper: ${name}`);
+      }
+      continue;
+    }
+
+    // Everything else: not a workflow wrapper we own — leave alone
+  }
+
+  return changes;
+}
+
+module.exports = { refreshInstallation, cleanupOrphanWorkflowWrappers };

package/scripts/update/lib/utils.js

@@ -88,9 +88,35 @@ function findProjectRoot() {
   return null;
 }
 
+/**
+ * Assert that a version string is valid before stamping a config file.
+ * Throws a clear error if version is undefined, null, or empty.
+ * Used by refresh-installation.js, config-merger.js, and any future config writer
+ * that stamps a version field — closes I30 (ag-7-1).
+ *
+ * @param {string} version - The version string to validate
+ * @param {string} callSite - Identifier for the call site (e.g., 'enhance', 'artifacts', 'config-merger')
+ * @throws {Error} if version is not a non-empty string
+ */
+function assertVersion(version, callSite) {
+  // Reject all non-string types (numeric 0, boolean false, etc.) — version
+  // must be a non-empty string. Closes Blind Hunter finding #9 (ag-7-1 review).
+  if (typeof version !== 'string' || version === '') {
+    let displayed;
+    if (version === null) displayed = 'null';
+    else if (version === undefined) displayed = 'undefined';
+    else if (version === '') displayed = "''";
+    else displayed = `${typeof version} (${String(version)})`;
+    throw new Error(
+      `Refresh: cannot stamp config — getPackageVersion() returned ${displayed}; check package.json (call site: ${callSite})`
+    );
+  }
+}
+
 module.exports = {
   getPackageVersion,
   compareVersions,
   countUserDataFiles,
-  findProjectRoot
+  findProjectRoot,
+  assertVersion
 };

package/scripts/update/lib/validator.js

@@ -5,7 +5,7 @@ const path = require('path');
 const yaml = require('js-yaml');
 const configMerger = require('./config-merger');
 const { countUserDataFiles } = require('./utils');
-const { AGENT_FILES, AGENT_IDS, WORKFLOW_NAMES, WAVE3_WORKFLOW_NAMES } = require('./agent-registry');
+const { AGENT_FILES, AGENT_IDS, WORKFLOW_NAMES, WAVE3_WORKFLOW_NAMES, EXTRA_BME_AGENTS, EXTRA_BME_AGENT_IDS } = require('./agent-registry');
 
 /**
  * Validator for Convoke
@@ -47,6 +47,9 @@ async function validateInstallation(preMigrationData = {}, projectRoot) {
   // 8. Enhance module validation (optional — passes if not installed)
   checks.push(await validateEnhanceModule(projectRoot));
 
+  // 9. Artifacts module validation (optional — passes if not installed)
+  checks.push(await validateArtifactsModule(projectRoot));
+
   const allPassed = checks.every(c => c.passed);
 
   return {
@@ -202,11 +205,22 @@ async function validateManifest(projectRoot) {
 
     const manifestContent = fs.readFileSync(manifestPath, 'utf8');
 
-    // Check for all Convoke agents
+    // Check for all Convoke agents (Vortex/Gyre IDs and standalone bme agents)
     const missingFromManifest = AGENT_IDS.filter(id => !manifestContent.includes(id));
+    const missingExtras = EXTRA_BME_AGENT_IDS.filter(id => !manifestContent.includes(`bmad-agent-bme-${id}`));
+
+    const allMissing = [...missingFromManifest, ...missingExtras];
+    if (allMissing.length > 0) {
+      check.error = `Agent manifest missing: ${allMissing.join(', ')}`;
+      return check;
+    }
 
-    if (missingFromManifest.length > 0) {
-      check.error = `Agent manifest missing: ${missingFromManifest.join(', ')}`;
+    // Confirm standalone bme agent files exist on disk
+    const missingExtraFiles = EXTRA_BME_AGENTS
+      .filter(a => !fs.existsSync(path.join(projectRoot, '_bmad', 'bme', a.submodule, 'agents', `${a.id}.md`)))
+      .map(a => a.id);
+    if (missingExtraFiles.length > 0) {
+      check.error = `Standalone bme agent files missing: ${missingExtraFiles.join(', ')}`;
       return check;
     }
 
@@ -468,6 +482,101 @@ async function validateEnhanceModule(projectRoot) {
   return check;
 }
 
+/**
+ * Validate Artifacts module installation (optional — passes if not installed)
+ * Performs 5-point verification: directory, config, workflows array, per-workflow entry, per-workflow skill wrapper
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {Promise<object>} Validation check result
+ */
+async function validateArtifactsModule(projectRoot) {
+  const check = {
+    name: 'Artifacts module',
+    passed: false,
+    error: null
+  };
+
+  try {
+    const artifactsDir = path.join(projectRoot, '_bmad/bme/_artifacts');
+
+    // Check 1: Directory exists — if not, Artifacts is simply not installed (optional)
+    if (!fs.existsSync(artifactsDir)) {
+      check.passed = true;
+      check.info = 'not installed';
+      return check;
+    }
+
+    const failures = [];
+
+    // Check 2: Config parse — bail early if config is unreadable, since later checks
+    // depend on a parsed workflows array.
+    const configPath = path.join(artifactsDir, 'config.yaml');
+    if (!fs.existsSync(configPath)) {
+      check.error = 'Artifacts: config.yaml not found';
+      return check;
+    }
+
+    let config = null;
+    try {
+      config = yaml.load(fs.readFileSync(configPath, 'utf8'));
+    } catch (err) {
+      check.error = `Artifacts: config.yaml parse error: ${err.message}`;
+      return check;
+    }
+
+    if (!config || typeof config !== 'object') {
+      check.error = 'Artifacts: config.yaml is empty or invalid';
+      return check;
+    }
+
+    // Check 3: Workflows array non-empty
+    if (!Array.isArray(config.workflows) || config.workflows.length === 0) {
+      check.error = 'Artifacts: config.yaml has no workflows array';
+      return check;
+    }
+
+    // Checks 4 & 5: Per-workflow entry point and skill wrapper.
+    // Aggregate failures across all workflows so a single doctor run reports every
+    // problem at once (mirrors validateEnhanceModule).
+    // Non-standalone workflows are skipped from wrapper/entry checks because
+    // refresh-installation.js section 6d does NOT install them — validating their
+    // wrapper would be a contract mismatch with the refresh logic.
+    for (const wf of config.workflows) {
+      if (!wf || !wf.name || !wf.entry) {
+        failures.push('workflow entry missing name or entry field');
+        continue;
+      }
+
+      if (wf.standalone !== true) {
+        // Refresh skips non-standalone workflows; nothing to validate.
+        continue;
+      }
+
+      // Check 4: Workflow entry point file exists
+      const entryPath = path.join(artifactsDir, wf.entry);
+      if (!fs.existsSync(entryPath)) {
+        failures.push(`workflow entry missing for ${wf.name}: ${wf.entry}`);
+      }
+
+      // Check 5: Skill wrapper exists at .claude/skills/{workflow.name}/SKILL.md
+      // (workflow.name already carries the bmad- prefix; do NOT synthesize bmad-${wf.name})
+      const skillWrapperPath = path.join(projectRoot, '.claude', 'skills', wf.name, 'SKILL.md');
+      if (!fs.existsSync(skillWrapperPath)) {
+        failures.push(`skill wrapper missing for ${wf.name}`);
+      }
+    }
+
+    if (failures.length > 0) {
+      check.error = `Artifacts: ${failures.join('; ')}`;
+    } else {
+      check.passed = true;
+    }
+  } catch (error) {
+    check.error = error.message;
+  }
+
+  return check;
+}
+
 /**
  * Validate a SKILL.md file has required frontmatter fields
  * @param {string} skillMdPath - Absolute path to SKILL.md file
@@ -633,6 +742,7 @@ module.exports = {
   validateDeprecatedWorkflows,
   validateWorkflowStepStructure,
   validateEnhanceModule,
+  validateArtifactsModule,
   validateSkillMd,
   validateStepFiles,
   validateSkillCohesion,