ma-agents 3.12.0 → 3.12.2

package/lib/bmad-cache/wds/src/workflows/wds-8-product-evolution/bmad-skill-manifest.yaml

@@ -1 +1 @@
-type: skill
+type: skill

package/lib/bmad-customize/bmm-analyst.customize.yaml

@@ -1,8 +1,8 @@
-# MA-AGENTS: skill enforcement for bmm-analyst
-phase: planning
-on_prem_phase_prefix: "/no_think You are in a planning phase — respond in text for questions; create files only when explicitly asked."
-critical_actions:
-  - "Read the skills MANIFEST at {project-root}/skills/MANIFEST.yaml"
-  - "For each skill marked always_load: true, read the skill file completely"
-  - "If _bmad-output/project-context.md exists, read it completely"
-  - "Follow all skill directives and project-context rules during this session"
+# MA-AGENTS: skill enforcement for bmm-analyst
+phase: planning
+on_prem_phase_prefix: "/no_think You are in a planning phase — respond in text for questions; create files only when explicitly asked."
+critical_actions:
+  - "Read the skills MANIFEST at {project-root}/skills/MANIFEST.yaml"
+  - "For each skill marked always_load: true, read the skill file completely"
+  - "If _bmad-output/project-context.md exists, read it completely"
+  - "Follow all skill directives and project-context rules during this session"

package/lib/bmad-customize/bmm-architect.customize.yaml

@@ -1,8 +1,8 @@
-# MA-AGENTS: skill enforcement for bmm-architect
-phase: planning
-on_prem_phase_prefix: "/no_think You are in a planning phase — respond in text for questions; create files only when explicitly asked."
-critical_actions:
-  - "Read the skills MANIFEST at {project-root}/skills/MANIFEST.yaml"
-  - "For each skill marked always_load: true, read the skill file completely"
-  - "If _bmad-output/project-context.md exists, read it completely"
-  - "Follow all skill directives and project-context rules during this session"
+# MA-AGENTS: skill enforcement for bmm-architect
+phase: planning
+on_prem_phase_prefix: "/no_think You are in a planning phase — respond in text for questions; create files only when explicitly asked."
+critical_actions:
+  - "Read the skills MANIFEST at {project-root}/skills/MANIFEST.yaml"
+  - "For each skill marked always_load: true, read the skill file completely"
+  - "If _bmad-output/project-context.md exists, read it completely"
+  - "Follow all skill directives and project-context rules during this session"

package/lib/bmad-customize/bmm-bmad-master.customize.yaml

@@ -1,6 +1,6 @@
-# MA-AGENTS: skill enforcement for bmm-bmad-master
-critical_actions:
-  - "Read the skills MANIFEST at {project-root}/skills/MANIFEST.yaml"
-  - "For each skill marked always_load: true, read the skill file completely"
-  - "If _bmad-output/project-context.md exists, read it completely"
-  - "Follow all skill directives and project-context rules during this session"
+# MA-AGENTS: skill enforcement for bmm-bmad-master
+critical_actions:
+  - "Read the skills MANIFEST at {project-root}/skills/MANIFEST.yaml"
+  - "For each skill marked always_load: true, read the skill file completely"
+  - "If _bmad-output/project-context.md exists, read it completely"
+  - "Follow all skill directives and project-context rules during this session"

package/lib/bmad-customize/bmm-dev.customize.yaml

@@ -1,8 +1,8 @@
-# MA-AGENTS: skill enforcement for bmm-dev
-phase: implementation
-on_prem_phase_prefix: "Think carefully before writing code. Always reference the story you are implementing before making edits."
-critical_actions:
-  - "Read the skills MANIFEST at {project-root}/skills/MANIFEST.yaml"
-  - "For each skill marked always_load: true, read the skill file completely"
-  - "If _bmad-output/project-context.md exists, read it completely"
-  - "Follow all skill directives and project-context rules during this session"
+# MA-AGENTS: skill enforcement for bmm-dev
+phase: implementation
+on_prem_phase_prefix: "Think carefully before writing code. Always reference the story you are implementing before making edits."
+critical_actions:
+  - "Read the skills MANIFEST at {project-root}/skills/MANIFEST.yaml"
+  - "For each skill marked always_load: true, read the skill file completely"
+  - "If _bmad-output/project-context.md exists, read it completely"
+  - "Follow all skill directives and project-context rules during this session"

package/lib/bmad-customize/bmm-pm.customize.yaml

@@ -1,8 +1,8 @@
-# MA-AGENTS: skill enforcement for bmm-pm
-phase: planning
-on_prem_phase_prefix: "/no_think You are in a planning phase — respond in text for questions; create files only when explicitly asked."
-critical_actions:
-  - "Read the skills MANIFEST at {project-root}/skills/MANIFEST.yaml"
-  - "For each skill marked always_load: true, read the skill file completely"
-  - "If _bmad-output/project-context.md exists, read it completely"
-  - "Follow all skill directives and project-context rules during this session"
+# MA-AGENTS: skill enforcement for bmm-pm
+phase: planning
+on_prem_phase_prefix: "/no_think You are in a planning phase — respond in text for questions; create files only when explicitly asked."
+critical_actions:
+  - "Read the skills MANIFEST at {project-root}/skills/MANIFEST.yaml"
+  - "For each skill marked always_load: true, read the skill file completely"
+  - "If _bmad-output/project-context.md exists, read it completely"
+  - "Follow all skill directives and project-context rules during this session"

package/lib/bmad-customize/bmm-qa.customize.yaml

@@ -1,26 +1,26 @@
-# MA-AGENTS: Gad — Software Quality Assurance Expert
-phase: planning
-on_prem_phase_prefix: "/no_think You are in a planning phase — respond in text for questions; create files only when explicitly asked."
-agent:
-  metadata:
-    name: "Gad"
-
-persona:
-  role: "Software Quality Assurance Engineer responsible for verifying project quality across all dimensions — code, process, documentation, and delivery."
-  identity: "Experienced SQA engineer with deep expertise in auditing software projects for compliance, traceability, and process health. Methodical, thorough, and data-driven."
-  communication_style: "Clear, precise, and structured. Presents findings as actionable reports with severity levels. Distinguishes between blocking issues and observations."
-  principles:
-    - "Quality is everyone's responsibility but the SQA auditor's job to verify."
-    - "Traceability from requirement to code is non-negotiable."
-    - "Process compliance prevents defects."
-    - "Evidence matters more than opinions."
-
-menu:
-  - trigger: skill:ma-agent-sqa
-    description: "Activate Gad — Software Quality Assurance Expert"
-
-critical_actions:
-  - "Read the skills MANIFEST at {project-root}/skills/MANIFEST.yaml"
-  - "For each skill marked always_load: true, read the skill file completely"
-  - "If _bmad-output/project-context.md exists, read it completely"
-  - "Follow all skill directives and project-context rules during this session"
+# MA-AGENTS: Gad — Software Quality Assurance Expert
+phase: planning
+on_prem_phase_prefix: "/no_think You are in a planning phase — respond in text for questions; create files only when explicitly asked."
+agent:
+  metadata:
+    name: "Gad"
+
+persona:
+  role: "Software Quality Assurance Engineer responsible for verifying project quality across all dimensions — code, process, documentation, and delivery."
+  identity: "Experienced SQA engineer with deep expertise in auditing software projects for compliance, traceability, and process health. Methodical, thorough, and data-driven."
+  communication_style: "Clear, precise, and structured. Presents findings as actionable reports with severity levels. Distinguishes between blocking issues and observations."
+  principles:
+    - "Quality is everyone's responsibility but the SQA auditor's job to verify."
+    - "Traceability from requirement to code is non-negotiable."
+    - "Process compliance prevents defects."
+    - "Evidence matters more than opinions."
+
+menu:
+  - trigger: skill:ma-agent-sqa
+    description: "Activate Gad — Software Quality Assurance Expert"
+
+critical_actions:
+  - "Read the skills MANIFEST at {project-root}/skills/MANIFEST.yaml"
+  - "For each skill marked always_load: true, read the skill file completely"
+  - "If _bmad-output/project-context.md exists, read it completely"
+  - "Follow all skill directives and project-context rules during this session"

package/lib/bmad-customize/bmm-sm.customize.yaml

@@ -1,8 +1,8 @@
-# MA-AGENTS: skill enforcement for bmm-sm
-phase: planning
-on_prem_phase_prefix: "/no_think You are in a planning phase — respond in text for questions; create files only when explicitly asked."
-critical_actions:
-  - "Read the skills MANIFEST at {project-root}/skills/MANIFEST.yaml"
-  - "For each skill marked always_load: true, read the skill file completely"
-  - "If _bmad-output/project-context.md exists, read it completely"
-  - "Follow all skill directives and project-context rules during this session"
+# MA-AGENTS: skill enforcement for bmm-sm
+phase: planning
+on_prem_phase_prefix: "/no_think You are in a planning phase — respond in text for questions; create files only when explicitly asked."
+critical_actions:
+  - "Read the skills MANIFEST at {project-root}/skills/MANIFEST.yaml"
+  - "For each skill marked always_load: true, read the skill file completely"
+  - "If _bmad-output/project-context.md exists, read it completely"
+  - "Follow all skill directives and project-context rules during this session"

package/lib/bmad-customize/bmm-tech-writer.customize.yaml

@@ -1,8 +1,8 @@
-# MA-AGENTS: skill enforcement for bmm-tech-writer
-phase: planning
-on_prem_phase_prefix: "/no_think You are in a planning phase — respond in text for questions; create files only when explicitly asked."
-critical_actions:
-  - "Read the skills MANIFEST at {project-root}/skills/MANIFEST.yaml"
-  - "For each skill marked always_load: true, read the skill file completely"
-  - "If _bmad-output/project-context.md exists, read it completely"
-  - "Follow all skill directives and project-context rules during this session"
+# MA-AGENTS: skill enforcement for bmm-tech-writer
+phase: planning
+on_prem_phase_prefix: "/no_think You are in a planning phase — respond in text for questions; create files only when explicitly asked."
+critical_actions:
+  - "Read the skills MANIFEST at {project-root}/skills/MANIFEST.yaml"
+  - "For each skill marked always_load: true, read the skill file completely"
+  - "If _bmad-output/project-context.md exists, read it completely"
+  - "Follow all skill directives and project-context rules during this session"

package/lib/bmad-customize/bmm-ux-designer.customize.yaml

@@ -1,8 +1,8 @@
-# MA-AGENTS: skill enforcement for bmm-ux-designer
-phase: planning
-on_prem_phase_prefix: "/no_think You are in a planning phase — respond in text for questions; create files only when explicitly asked."
-critical_actions:
-  - "Read the skills MANIFEST at {project-root}/skills/MANIFEST.yaml"
-  - "For each skill marked always_load: true, read the skill file completely"
-  - "If _bmad-output/project-context.md exists, read it completely"
-  - "Follow all skill directives and project-context rules during this session"
+# MA-AGENTS: skill enforcement for bmm-ux-designer
+phase: planning
+on_prem_phase_prefix: "/no_think You are in a planning phase — respond in text for questions; create files only when explicitly asked."
+critical_actions:
+  - "Read the skills MANIFEST at {project-root}/skills/MANIFEST.yaml"
+  - "For each skill marked always_load: true, read the skill file completely"
+  - "If _bmad-output/project-context.md exists, read it completely"
+  - "Follow all skill directives and project-context rules during this session"

package/lib/bmad-extension-plugin/.claude-plugin/marketplace.json

@@ -37,7 +37,7 @@
       "name": "ma-skills",
       "source": "./",
       "description": "ma-agents extension module providing enterprise SDLC personas and operational workflow skills.",
-      "version": "3.12.0",
+      "version": "3.12.2",
       "author": {
         "name": "Alon Mayaffit"
       },

package/lib/bmad.js

@@ -459,6 +459,106 @@ function inspectBmadCache(cacheRoot) {
     };
 }
 
+/**
+ * Human-readable descriptions for each BMAD module shipped in the bundled
+ * cache. Surfaced by the install wizard's module-selection prompt so users
+ * know what they're enabling. Keyed by module id; missing keys fall back to
+ * the bare id at the call site.
+ */
+const BMAD_MODULE_DESCRIPTIONS = Object.freeze({
+    bmm: 'BMad Method core — analyst, PM, architect, dev, UX, tech-writer (required)',
+    bmb: 'BMad Builder — agent, module, and workflow builders',
+    cis: 'Creative Intelligence Suite — innovation and ideation toolkit',
+    gds: 'Game Dev Studio — game development workflows',
+    tea: 'Test Architecture Enterprise — Test Architect (Murat) + 9 testarch workflows',
+    wds: 'Web Dev Studio — retired upstream',
+});
+
+/**
+ * Return the BMAD modules this ma-agents bundle can install. `bmm` (the
+ * BMad core) is always first because it ships inside the `bmad-method`
+ * npm dependency itself, not in `lib/bmad-cache/` — the cache only carries
+ * the optional external modules (bmb, cis, gds, tea, wds, ...).
+ *
+ * Each entry carries a `retired` flag so the caller can hide modules that
+ * have been retired upstream (e.g. wds).
+ *
+ * If the cache manifest is missing or unreadable, falls back to a list
+ * containing only `bmm` — that's the minimum a successful install needs.
+ *
+ * @returns {Array<{ id: string, retired: boolean, description: string }>}
+ */
+function getInstallableBmadModules() {
+    const manifestPath = path.join(__dirname, 'bmad-cache', 'cache-manifest.json');
+    const bmmEntry = {
+        id: 'bmm',
+        retired: false,
+        description: BMAD_MODULE_DESCRIPTIONS.bmm,
+    };
+    let manifest;
+    try {
+        manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+    } catch {
+        return [bmmEntry];
+    }
+    const cacheEntries = Object.entries(manifest.modules || {}).map(([id, meta]) => ({
+        id,
+        retired: !!(meta && meta.retiredUpstream),
+        description: BMAD_MODULE_DESCRIPTIONS[id] || `(${id})`,
+    }));
+    return [bmmEntry, ...cacheEntries];
+}
+
+/**
+ * Detect which BMad modules are already installed under a given project
+ * root by checking for `_bmad/<id>/` directories. Used by the install
+ * wizard's update path to pre-check the user's existing module set.
+ *
+ * @param {string} projectRoot - Absolute or relative project root
+ * @returns {string[]} Module ids that have a corresponding `_bmad/<id>/` dir
+ */
+function getInstalledBmadModules(projectRoot) {
+    if (!projectRoot) return [];
+    const bmadDir = path.join(projectRoot, BMAD_DIR);
+    if (!fs.existsSync(bmadDir)) return [];
+    const installable = getInstallableBmadModules().map(m => m.id);
+    return installable.filter(id => fs.existsSync(path.join(bmadDir, id)));
+}
+
+/**
+ * Validate a user-supplied module list (e.g. parsed from `--bmad-modules
+ * tea,bmb`) against the set of installable modules and ensure `bmm` is
+ * always present. Without `bmm` the BMad core agents (analyst, PM, dev,
+ * architect, ...) are absent and downstream skills break, so we force-add
+ * it rather than letting the user shoot themselves in the foot.
+ *
+ * @param {Object} ctx
+ * @param {string[]} ctx.requested - Module ids the user asked for
+ * @param {Array<{id: string}>} ctx.available - Installable modules (already
+ *   filtered for retirement at the call site if desired)
+ * @returns {string[]} The validated, deduped, bmm-forced module list
+ * @throws {Error} If any requested id is not in `available`
+ */
+function resolveBmadModules(ctx) {
+    if (!ctx || !Array.isArray(ctx.requested) || !Array.isArray(ctx.available)) {
+        throw new Error(
+            'resolveBmadModules requires ctx with requested (array) and available (array)'
+        );
+    }
+    const availableIds = new Set(ctx.available.map(m => m.id));
+    const requested = ctx.requested.map(s => String(s).trim()).filter(Boolean);
+    const invalid = requested.filter(id => !availableIds.has(id));
+    if (invalid.length > 0) {
+        const knownList = ctx.available.map(m => m.id).join(', ');
+        throw new Error(
+            `Unknown BMAD module(s): ${invalid.join(', ')}. Available: ${knownList}`
+        );
+    }
+    const result = requested.includes('bmm') ? [...requested] : ['bmm', ...requested];
+    const seen = new Set();
+    return result.filter(id => (seen.has(id) ? false : (seen.add(id), true)));
+}
+
 /**
  * Decide what to do when the BMAD recompile step throws.
  *
@@ -1452,6 +1552,66 @@ async function deployClineWorkflows(projectRoot, tools = []) {
     }
 }
 
+/**
+ * Write bmad-method's `.bmad-channel.json` marker for an offline-cached
+ * module if one is not already present.
+ *
+ * Why this exists: bmad-method's `cloneExternalModule()` (in
+ * `node_modules/bmad-method/tools/installer/modules/external-manager.js`)
+ * resolves the install ref by hitting GitHub's API for the latest stable
+ * tag. On an air-gapped machine the API call throws and the function
+ * falls back to reading the cached marker via `readChannelMarker()`. If
+ * the marker is missing, it instead throws `Could not resolve stable tag
+ * for '<module>'` and aborts the entire install.
+ *
+ * Pre-3.12.2 ma-agents copied each module's source tree (with `.git/`
+ * restored from `_git_preserved/`) into `~/.bmad/cache/external-modules/`
+ * but never wrote the marker. The result: any first-time offline install
+ * that pre-populated more than `bmm` failed at the first external module.
+ * Pre-3.12.1 the bug was masked because ma-agents only ever requested
+ * `--modules bmm` (built into bmad-method itself, no cache-marker check).
+ *
+ * The marker schema is the same one bmad-method writes after a successful
+ * online clone (line 419 of external-manager.js). Channel defaults to
+ * `stable` because that's bmad-method's own default when a registry
+ * entry has no `default_channel` field.
+ *
+ * Best-effort: failures are swallowed. The next install attempt (online or
+ * offline-with-marker) will write a fresh one.
+ *
+ * @param {string} moduleDir - Cache dir for the module
+ *   (e.g. `~/.bmad/cache/external-modules/tea`)
+ * @param {{ branch?: string, commitSha?: string }} [manifestEntry] - Entry
+ *   from `lib/bmad-cache/cache-manifest.json` for this module
+ * @returns {Promise<boolean>} `true` if the marker was written, `false` if
+ *   it already existed or the manifest entry is missing required fields
+ */
+async function ensureCacheMarker(moduleDir, manifestEntry) {
+    const markerPath = path.join(moduleDir, '.bmad-channel.json');
+    if (await fs.pathExists(markerPath)) return false;
+    if (!manifestEntry || !manifestEntry.commitSha) return false;
+    try {
+        await fs.writeFile(
+            markerPath,
+            JSON.stringify(
+                {
+                    channel: 'stable',
+                    version: manifestEntry.branch || 'main',
+                    sha: manifestEntry.commitSha,
+                    writtenAt: new Date().toISOString(),
+                },
+                null,
+                2,
+            ),
+        );
+        return true;
+    } catch {
+        // Best-effort — marker is a fallback, not a correctness requirement.
+        // If we can't write it, bmad-method will surface its own error.
+        return false;
+    }
+}
+
 async function prePopulateBmadCache(force = false) {
     const cacheSource = path.join(__dirname, 'bmad-cache');
     if (!(await fs.pathExists(cacheSource))) {
@@ -1463,10 +1623,23 @@ async function prePopulateBmadCache(force = false) {
         const targetDir = path.join(os.homedir(), '.bmad', 'cache', 'external-modules');
         await fs.ensureDir(targetDir);
 
+        // Load manifest once so each module copy can stamp a `.bmad-channel.json`
+        // marker for bmad-method's offline fallback. Missing/malformed manifest
+        // is non-fatal — copy still happens, marker is just skipped.
+        let manifest = null;
+        try {
+            const manifestPath = path.join(cacheSource, 'cache-manifest.json');
+            if (await fs.pathExists(manifestPath)) {
+                manifest = JSON.parse(await fs.readFile(manifestPath, 'utf8'));
+            }
+        } catch {
+            manifest = null;
+        }
+
         const entries = await fs.readdir(cacheSource);
         const modules = entries.filter(e => e !== 'cache-manifest.json');
 
-        let copied = 0, skipped = 0, replaced = 0;
+        let copied = 0, skipped = 0, replaced = 0, markersWritten = 0;
 
         for (const mod of modules) {
             const src = path.join(cacheSource, mod);
@@ -1498,11 +1671,21 @@ async function prePopulateBmadCache(force = false) {
                 console.log(chalk.cyan(`    + Pre-populated cached module: ${mod}`));
                 copied++;
             }
+
+            // Stamp the offline-fallback marker. Always attempt — even on the
+            // skip path, since prior ma-agents versions copied the module
+            // without the marker and left users wedged on offline installs.
+            // ensureCacheMarker no-ops when the marker already exists.
+            const wrote = await ensureCacheMarker(dst, manifest && manifest.modules ? manifest.modules[mod] : null);
+            if (wrote) markersWritten++;
         }
 
         if (copied > 0 || replaced > 0) {
             console.log(chalk.gray(`  Cache pre-population complete: ${copied} copied, ${skipped} skipped, ${replaced} replaced`));
         }
+        if (markersWritten > 0) {
+            console.log(chalk.gray(`  Wrote ${markersWritten} offline-fallback marker(s) (.bmad-channel.json)`));
+        }
     } catch (err) {
         console.error(chalk.red(`  Cache pre-population failed: ${err.message}`));
     }
@@ -2619,4 +2802,11 @@ module.exports = {
     looksLikeEbusyFailure,
     inspectBmadCache,
     classifyRecompileFailure,
+    // Module selection — replaces hardcoded ['bmm'] in the CLI install path
+    BMAD_MODULE_DESCRIPTIONS,
+    getInstallableBmadModules,
+    getInstalledBmadModules,
+    resolveBmadModules,
+    // 3.12.2 — offline-fallback marker for bmad-method's cloneExternalModule
+    ensureCacheMarker,
 };