ma-agents 2.20.3 → 2.22.0

package/lib/bmad.js

@@ -22,24 +22,78 @@ function isBmadInstalled(projectRoot = process.cwd()) {
     return fs.existsSync(path.join(projectRoot, BMAD_DIR));
 }
 
-async function installBmad(modules = ['bmm', 'bmb'], tools = [], projectRoot = process.cwd(), force = false) {
-    let command = getBmadCommand(`install --yes --directory "${projectRoot}"`);
+/**
+ * Build a complete bmad-method CLI command from an install context object.
+ * Replaces ad-hoc string concatenation with a single authoritative builder.
+ * Architecture Decision P2-6.
+ *
+ * @param {Object} ctx - Install context
+ * @param {string} ctx.projectRoot - Project root directory
+ * @param {string[]} ctx.modules - Module IDs (e.g. ['bmm', 'bmb'])
+ * @param {string[]} ctx.tools - Tool/IDE IDs (e.g. ['claude-code', 'cursor'])
+ * @param {string} ctx.action - 'install' (default) or 'update'
+ * @param {string} [ctx.userName] - User name for agents
+ * @param {string} [ctx.commLang] - Communication language
+ * @param {string} [ctx.docLang] - Document output language
+ * @param {string} [ctx.outputFolder] - Output folder relative to project root
+ * @returns {string} Complete command string ready for execSync
+ */
+function buildBmadArgs(ctx) {
+    if (!ctx || !ctx.projectRoot || !Array.isArray(ctx.modules)) {
+        throw new Error('buildBmadArgs requires ctx with projectRoot (string) and modules (array)');
+    }
+    const parts = ['install'];
+
+    parts.push('--directory', `"${ctx.projectRoot}"`);
+    parts.push('--modules', ctx.modules.join(','));
+    parts.push('--tools', ctx.tools && ctx.tools.length > 0 ? ctx.tools.join(',') : 'none');
+    parts.push('--yes');
+
+    // Optional params — only include if provided (let bmad-method default otherwise)
+    if (ctx.userName) {
+        parts.push('--user-name', `"${ctx.userName}"`);
+    }
+    if (ctx.commLang) {
+        parts.push('--communication-language', `"${ctx.commLang}"`);
+    }
+    if (ctx.docLang) {
+        parts.push('--document-output-language', `"${ctx.docLang}"`);
+    }
+    if (ctx.outputFolder) {
+        parts.push('--output-folder', `"${ctx.outputFolder}"`);
+    }
 
-    if (modules && modules.length > 0) {
-        command += ` --modules ${modules.join(',')}`;
+    // Extension module — only if directory exists
+    const extensionPath = path.join(__dirname, 'bmad-extension');
+    if (fs.existsSync(extensionPath)) {
+        parts.push('--custom-content', `"${extensionPath}"`);
     }
 
-    if (tools && tools.length > 0) {
-        command += ` --tools ${tools.join(',')}`;
-    } else {
-        command += ' --tools none';
+    if (ctx.action === 'update') {
+        parts.push('--action', 'update');
     }
 
+    return getBmadCommand(parts.join(' '));
+}
+
+async function installBmad(modules = ['bmm', 'bmb'], tools = [], projectRoot = process.cwd(), force = false, { userName = '', commLang = '', docLang = '', outputFolder = '' } = {}) {
+    const command = buildBmadArgs({
+        projectRoot,
+        modules,
+        tools,
+        action: 'install',
+        userName,
+        commLang,
+        docLang,
+        outputFolder,
+    });
+
     await prePopulateBmadCache(force);
 
     console.log(chalk.gray(`  Running: ${command}`));
     try {
         execSync(command, { stdio: 'inherit', cwd: projectRoot, env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } });
+        await deployMethodology(projectRoot, force);
         return true;
     } catch (error) {
         console.error(chalk.red(`  BMAD installation failed: ${error.message}`));
@@ -47,24 +101,24 @@ async function installBmad(modules = ['bmm', 'bmb'], tools = [], projectRoot = p
     }
 }
 
-async function updateBmad(modules = ['bmm', 'bmb'], tools = [], projectRoot = process.cwd(), force = false) {
-    let command = getBmadCommand(`install --action update --yes --directory "${projectRoot}"`);
-
-    if (modules && modules.length > 0) {
-        command += ` --modules ${modules.join(',')}`;
-    }
-
-    if (tools && tools.length > 0) {
-        command += ` --tools ${tools.join(',')}`;
-    } else {
-        command += ' --tools none';
-    }
+async function updateBmad(modules = ['bmm', 'bmb'], tools = [], projectRoot = process.cwd(), force = false, { userName = '', commLang = '', docLang = '', outputFolder = '' } = {}) {
+    const command = buildBmadArgs({
+        projectRoot,
+        modules,
+        tools,
+        action: 'update',
+        userName,
+        commLang,
+        docLang,
+        outputFolder,
+    });
 
     await prePopulateBmadCache(force);
 
     console.log(chalk.gray(`  Running: ${command}`));
     try {
         execSync(command, { stdio: 'inherit', cwd: projectRoot, env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } });
+        await deployMethodology(projectRoot, force);
         return true;
     } catch (error) {
         console.error(chalk.red(`  BMAD update failed: ${error.message}`));
@@ -72,7 +126,7 @@ async function updateBmad(modules = ['bmm', 'bmb'], tools = [], projectRoot = pr
     }
 }
 
-async function applyCustomizations(projectRoot = process.cwd(), modules = ['bmm', 'bmb'], tools = [], selectedAgentIds = [], force = false) {
+async function applyCustomizations(projectRoot = process.cwd(), modules = ['bmm', 'bmb'], tools = [], selectedAgentIds = [], force = false, { userName = '', commLang = '', docLang = '', outputFolder = '' } = {}) {
     const sourceDir = path.join(__dirname, 'bmad-customizations');
     const workflowSourceDir = path.join(__dirname, 'bmad-workflows');
     const configTargetDir = path.join(projectRoot, CONFIG_DIR);
@@ -122,18 +176,19 @@ async function applyCustomizations(projectRoot = process.cwd(), modules = ['bmm'
         }
     }
 
-    // Recompile agents to apply YAML customizations
+    // STAGE:RECOMPILE — Recompile agents to apply YAML customizations
     // IMPORTANT: Steps 3-5 must run AFTER recompile because the recompile regenerates
     // the _bmad/bmm/ tree and would wipe any files placed there beforehand.
-    let command = getBmadCommand(`install --yes --directory "${projectRoot}"`);
-    if (modules && modules.length > 0) {
-        command += ` --modules ${modules.join(',')}`;
-    }
-    if (tools && tools.length > 0) {
-        command += ` --tools ${tools.join(',')}`;
-    } else {
-        command += ' --tools none';
-    }
+    const command = buildBmadArgs({
+        projectRoot,
+        modules,
+        tools,
+        action: 'install',
+        userName,
+        commLang,
+        docLang,
+        outputFolder,
+    });
     await prePopulateBmadCache(force);
 
     console.log(chalk.gray(`  Running: ${command}`));
@@ -143,21 +198,37 @@ async function applyCustomizations(projectRoot = process.cwd(), modules = ['bmm'
         console.error(chalk.red(`  BMAD recompile failed: ${error.message}`));
     }
 
-    // 3. Apply workflows (AFTER recompile so they persist)
+    // STAGE:EXTENSION — Deploy BMAD extension module (AFTER recompile — extensions/ survives recompile)
+    // NOTE: Stage 1 deploys persona/menu customize.yaml to _bmad/_config/agents/ (consumed
+    // by BMAD's agent compilation). This stage deploys the extension module to
+    // _bmad/extensions/ma-agents-skills/ which adds critical_actions for skill loading.
+    // These are complementary paths: _config/agents/ drives agent recompilation (persona/menu),
+    // while extensions/ adds runtime behavior (critical_actions). BMAD does NOT merge them —
+    // they are consumed by different mechanisms. The 4 custom agents have persona/menu in both
+    // locations; this is intentional for backward compatibility during transition (Story 8.3).
+    const extensionSource = path.join(__dirname, 'bmad-extension');
+    const extensionTarget = path.join(projectRoot, BMAD_DIR, 'extensions', 'ma-agents-skills');
+    if (fs.existsSync(extensionSource)) {
+        await fs.ensureDir(extensionTarget);
+        await fs.copy(extensionSource, extensionTarget);
+        console.log(chalk.cyan('    + Deployed BMAD extension module: ma-agents-skills'));
+    }
+
+    // STAGE:WORKFLOWS — Apply workflows (AFTER recompile so they persist)
     if (fs.existsSync(workflowSourceDir)) {
         await fs.ensureDir(workflowTargetDir);
         await fs.copy(workflowSourceDir, workflowTargetDir);
         console.log(chalk.cyan(`    + Applied BMAD workflows`));
     }
 
-    // 4. Apply MIL-STD-498 templates (AFTER recompile so they persist)
+    // 5. Apply MIL-STD-498 templates (AFTER recompile so they persist)
     if (fs.existsSync(templateSourceDir)) {
         await fs.ensureDir(templateTargetDir);
         await fs.copy(templateSourceDir, templateTargetDir);
         console.log(chalk.cyan(`    + Applied MIL-STD-498 templates`));
     }
 
-    // 5. Copy agent templates to compiled location (AFTER recompile)
+    // 6. Copy agent templates to compiled location (AFTER recompile)
     // BMAD recompile doesn't generate custom agents (mil498, cyber) in _bmad/bmm/agents/.
     // Without this, updateAgentInstructions() creates the file with only the MA-AGENTS block.
     if (fs.existsSync(sourceDir)) {
@@ -175,7 +246,7 @@ async function applyCustomizations(projectRoot = process.cwd(), modules = ['bmm'
         }
     }
 
-    // 6. Register custom workflows in BMAD CSV registries (after recompile)
+    // 7. Register custom workflows in BMAD CSV registries (after recompile)
     if (selectedAgentIds.length === 0 || selectedAgentIds.includes('bmm-mil498')) {
         await registerMilWorkflows(projectRoot);
     }
@@ -260,6 +331,65 @@ async function registerMilWorkflows(projectRoot) {
     }
 }
 
+/**
+ * Deploy the methodology presentation to the target project's _bmad-output/methodology/ directory.
+ * Version-aware: skips if target is same or newer; overwrites only with --force.
+ * AC: #1, #2, #3, #5 (Story 6.1)
+ */
+async function deployMethodology(projectRoot = process.cwd(), force = false) {
+    const methodologySource = path.join(__dirname, 'methodology');
+    if (!(await fs.pathExists(methodologySource))) {
+        console.log(chalk.gray('  No methodology content found — skipping'));
+        return;
+    }
+
+    const methodologyTarget = path.join(projectRoot, '_bmad-output', 'methodology');
+    await fs.ensureDir(methodologyTarget);
+
+    // Version comparison
+    const sourceVersionFile = path.join(methodologySource, 'version.json');
+    const targetVersionFile = path.join(methodologyTarget, 'version.json');
+
+    let sourceVersion = '0.0.0';
+    let targetVersion = null;
+
+    if (await fs.pathExists(sourceVersionFile)) {
+        try {
+            const v = JSON.parse(await fs.readFile(sourceVersionFile, 'utf-8'));
+            sourceVersion = v.version || '0.0.0';
+        } catch { /* ignore */ }
+    }
+
+    if (await fs.pathExists(targetVersionFile)) {
+        try {
+            const v = JSON.parse(await fs.readFile(targetVersionFile, 'utf-8'));
+            targetVersion = v.version || null;
+        } catch { /* ignore */ }
+    }
+
+    if (targetVersion !== null && !force) {
+        // Simple semver comparison: skip if target is same or newer
+        const semverGte = (a, b) => {
+            const pa = a.split('.').map(Number);
+            const pb = b.split('.').map(Number);
+            for (let i = 0; i < 3; i++) {
+                if ((pa[i] || 0) > (pb[i] || 0)) return true;
+                if ((pa[i] || 0) < (pb[i] || 0)) return false;
+            }
+            return true;
+        };
+        if (semverGte(targetVersion, sourceVersion)) {
+            console.log(chalk.gray(`  ✓ Methodology presentation is up to date (v${targetVersion})`));
+            return;
+        }
+    }
+
+    await fs.copy(methodologySource, methodologyTarget, { overwrite: true });
+    console.log(chalk.green('  ✓ Methodology presentation installed to _bmad-output/methodology/'));
+    console.log(chalk.gray('  Hint: Share this with your team for BMAD-METHOD onboarding'));
+    console.log(chalk.gray('  Tip: Use /open-presentation to open the slides (install via npx ma-agents install open-presentation)'));
+}
+
 async function prePopulateBmadCache(force = false) {
     const cacheSource = path.join(__dirname, 'bmad-cache');
     if (!(await fs.pathExists(cacheSource))) {
@@ -342,8 +472,10 @@ function restoreGitDir(moduleDir) {
 
 module.exports = {
     isBmadInstalled,
+    buildBmadArgs,
     installBmad,
     updateBmad,
     applyCustomizations,
-    prePopulateBmadCache
+    prePopulateBmadCache,
+    deployMethodology,
 };

package/lib/hooks/claude-code/verify-manifest.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+
+/**
+ * Claude Code SessionStart Hook — MANIFEST.yaml Skill Enforcement
+ *
+ * Injects a context reminder at session startup to reinforce skill loading
+ * from the project's MANIFEST.yaml. Runs as a standalone Node.js script
+ * with no external dependencies.
+ *
+ * Hook event: SessionStart (matcher: "startup")
+ * Exit 0 + stdout text → injected into Claude's session context
+ *
+ * Installed by: ma-agents installer (lib/installer.js)
+ * Removed by: ma-agents uninstaller when all skills are removed
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+// Read hook input from stdin (JSON)
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', (chunk) => { input += chunk; });
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    const projectDir = data.cwd || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
+    // Look for skills MANIFEST.yaml in the project
+    const manifestPath = path.join(projectDir, '.claude', 'skills', 'MANIFEST.yaml');
+
+    if (!fs.existsSync(manifestPath)) {
+      // No manifest — this project doesn't use ma-agents skills. Exit silently.
+      process.exit(0);
+    }
+
+    // MANIFEST exists — inject context reminder into session
+    const reminder = [
+      'SKILL ENFORCEMENT ACTIVE: This project uses ma-agents skills.',
+      `Read the skill manifest at ${manifestPath} before starting any task.`,
+      'Load all skills marked always_load: true, then select relevant skills for the current task.',
+    ].join(' ');
+
+    process.stdout.write(reminder);
+    process.exit(0);
+  } catch (err) {
+    // On any error, allow session to proceed (don't block startup)
+    process.stderr.write(`verify-manifest hook warning: ${err.message}\n`);
+    process.exit(0);
+  }
+});
+
+// Handle stdin close without data (defensive)
+process.stdin.on('error', () => { process.exit(0); });