ma-agents 3.5.4 → 3.5.6

package/_bmad-output/implementation-artifacts/bug-experimentalwarning-about-commonjs-loading-es-module-during-install.md

@@ -0,0 +1,57 @@
+---
+type: bug
+status: ready-for-dev
+severity: medium
+bug_type: other
+version_found: 3.5.4
+title: ExperimentalWarning about CommonJS loading ES Module during install
+---
+
+# Bug: ExperimentalWarning about CommonJS loading ES Module during install
+
+**Severity:** medium
+**Affected Component:** installer CLI (bin/cli.js + bmad-method child spawn)
+
+## Reproduction Steps
+
+1. Use a Node version that emits the experimental `require()` of ESM warning (Node 20.17+ through early 22.x; see Node release notes on `--experimental-require-module`).
+2. From a clean working directory, run `node bin/cli.js install --yes --agent claude-code` (or equivalently `npx ma-agents install`).
+3. Observe startup stderr before the BMAD banner appears.
+
+## Expected Behavior
+
+Installer starts cleanly with only intentional informational output. No `ExperimentalWarning` noise appears on any Node version supported by `engines` (`>=16.0.0`).
+
+## Actual Behavior
+
+Stderr shows a message of the form:
+
+```
+(node:XXXXX) ExperimentalWarning: CommonJS module <path> is loading ES Module <path> using require().
+Support for loading ES Module in require() is an experimental feature and might change at any time.
+```
+
+The installer still completes successfully, but the warning is noisy, alarms first-time users, and appears in CI logs.
+
+## Root Cause Hypothesis
+
+The ma-agents CLI (`bin/cli.js`, CommonJS) spawns the bmad-method CLI (`node_modules/bmad-method/tools/bmad-npx-wrapper.js`, also CommonJS). bmad-method interacts with `@clack/prompts` and `@clack/core`, both of which declare `"type": "module"` in their `package.json`. On Node runtimes that emit `ExperimentalWarning` for `require()` of an ESM package (Node 20.17+ with `--experimental-require-module` default-on), the warning surfaces during install startup. While bmad-method already uses dynamic `import()` for the `@clack/*` packages in newer paths, the warning can still be produced by a transitive CJS → ESM require chain under certain Node versions.
+
+## Affected Files
+
+- `bin/cli.js`
+- `lib/bmad.js`
+
+## Suggested Fix
+
+Install a process-level warning filter at the top of `bin/cli.js` that suppresses only `ExperimentalWarning` whose message matches the `require()`-of-ESM pattern, while re-emitting every other warning (DeprecationWarning, unhandled rejections, custom warnings) via `process.emitWarning` so they remain visible. Additionally, pass a sanitized `env` to the bmad-method child spawn in `lib/bmad.js` — set `NODE_OPTIONS` to include `--no-warnings=ExperimentalWarning` (Node 22+) or use the equivalent `NODE_NO_WARNINGS=1` as a narrow fallback — so the spawned child is equally quiet. Add `test/experimental-warning.test.js` to assert:
+
+1. The filter swallows the specific ExperimentalWarning.
+2. Unrelated warnings (e.g., a synthetic `DeprecationWarning`) are still emitted.
+3. `lib/bmad.js` spawn envs include the expected suppression flag.
+
+## Notes
+
+- Created via `create-bug-story` workflow
+- Discoverable by sprint workflows via glob: `_bmad-output/implementation-artifacts/bug-*.md`
+- To add to a sprint, run `/add-to-sprint`

package/_bmad-output/implementation-artifacts/sprint-status.yaml

@@ -27,6 +27,10 @@ tracking_system: file-system
 story_location: _bmad-output/implementation-artifacts
 
 development_status:
+  # ─── BUG FIXES (ACTIVE) ───────────────────────────────────────────────────────
+  # Bug A (2026-04-14): ExperimentalWarning on installer startup. Severity: medium.
+  bug-experimentalwarning-about-commonjs-loading-es-module-during-install: ready-for-dev
+
   # ─── IN PROGRESS ──────────────────────────────────────────────────────────────
 
   # Epic 5: Bundled BMAD Installation — stories 5.1-5.4 done (archived), 5.5-5.6 in review

package/bin/cli.js

@@ -1,5 +1,33 @@
 #!/usr/bin/env node
 
+// Bug A fix — suppress the cosmetic Node.js ExperimentalWarning about
+// CommonJS require() of an ES Module. Must be installed BEFORE any
+// other require() so the filter catches warnings fired by the very
+// first dependency-loading call below. See lib/warning-filter.js.
+//
+// Re-exec gating:
+//   - Only when this file is launched as the CLI (require.main === module).
+//     When imported by the test suite or another script, skip the re-exec
+//     path — otherwise the importing process would silently fork itself.
+//   - Only for commands that can trigger the CJS-require-ESM warning,
+//     i.e. those that spawn bmad-method or otherwise load the heavy
+//     transitive dependency graph. Informational commands (--help,
+//     --version, status, list, agents) stay single-process for fast
+//     cold start. The listener-only fallback is still attached so
+//     in-process warnings still route through our filter.
+const { installExperimentalWarningFilter } = require('../lib/warning-filter');
+const _reexecCommands = new Set([
+  'install', 'uninstall', 'remove',
+  'create-skill', 'validate-skill', 'set-mandatory',
+  'customize-agent', 'create-agent',
+  'config',
+  undefined, // bare `ma-agents` → interactive wizard
+]);
+const _firstArg = process.argv[2];
+installExperimentalWarningFilter({
+  reexec: require.main === module && _reexecCommands.has(_firstArg),
+});
+
 const prompts = require('prompts');
 const chalk = require('chalk');
 const path = require('path');

package/lib/bmad.js

@@ -4,6 +4,27 @@ const os = require('os');
 const { execSync } = require('child_process');
 const chalk = require('chalk');
 const yaml = require('yaml');
+const { withExperimentalWarningSuppressed } = require('./warning-filter');
+
+/**
+ * Build the env object passed to the bmad-method child spawn.
+ * Extends parent env with GIT_TERMINAL_PROMPT=0 and a NODE_OPTIONS
+ * value that silences the ExperimentalWarning about CJS require() of
+ * an ES Module (Bug A). Callers that need a different NODE_OPTIONS
+ * can merge after this call.
+ *
+ * @param {NodeJS.ProcessEnv} [parentEnv=process.env]
+ * @returns {NodeJS.ProcessEnv}
+ */
+function buildChildSpawnEnv(parentEnv = process.env) {
+    return {
+        ...parentEnv,
+        GIT_TERMINAL_PROMPT: '0',
+        // Bug A — keep the bmad-method child as quiet about CJS-require-ESM
+        // as the parent. Preserves any NODE_OPTIONS the user already set.
+        NODE_OPTIONS: withExperimentalWarningSuppressed(parentEnv.NODE_OPTIONS),
+    };
+}
 
 const BMAD_DIR = '_bmad';
 const CONFIG_DIR = path.join(BMAD_DIR, '_config', 'agents');
@@ -122,7 +143,7 @@ async function installBmad(modules = ['bmm', 'bmb'], tools = [], projectRoot = p
 
     console.log(chalk.gray(`  Running: ${command}`));
     try {
-        runCommand(command, { cwd: projectRoot, env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } });
+        runCommand(command, { cwd: projectRoot, env: buildChildSpawnEnv() });
         await deployMethodology(projectRoot, force);
         return true;
     } catch (error) {
@@ -157,7 +178,7 @@ async function runMigration(modules, tools, projectRoot, force, { userName, comm
 
     console.log(chalk.gray(`  Running: ${command}`));
     try {
-        runCommand(command, { cwd: projectRoot, env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } });
+        runCommand(command, { cwd: projectRoot, env: buildChildSpawnEnv() });
     } catch (error) {
         // Rollback on failure
         console.error(chalk.red(`  BMAD update failed: ${error.message}`));
@@ -284,7 +305,7 @@ async function updateBmad(modules = ['bmm', 'bmb'], tools = [], projectRoot = pr
 
     console.log(chalk.gray(`  Running: ${command}`));
     try {
-        runCommand(command, { cwd: projectRoot, env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } });
+        runCommand(command, { cwd: projectRoot, env: buildChildSpawnEnv() });
         await deployMethodology(projectRoot, force);
         return true;
     } catch (error) {
@@ -361,7 +382,7 @@ async function applyCustomizations(projectRoot = process.cwd(), modules = ['bmm'
 
     console.log(chalk.gray(`  Running: ${command}`));
     try {
-        runCommand(command, { cwd: projectRoot, env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } });
+        runCommand(command, { cwd: projectRoot, env: buildChildSpawnEnv() });
     } catch (error) {
         console.error(chalk.red(`  BMAD recompile failed: ${error.message}`));
     }

package/lib/methodology/version.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "BMAD-METHOD AI Development Training Presentation",
   "files": [
     "BMAD_AI_Development_Training.pptx"

package/lib/warning-filter.js

@@ -0,0 +1,245 @@
+/**
+ * lib/warning-filter.js
+ *
+ * Suppresses the Node.js `ExperimentalWarning` that fires when a CommonJS
+ * module loads an ES Module via `require()`.
+ *
+ * Why this exists
+ * ---------------
+ * The ma-agents CLI (`bin/cli.js`) is CommonJS. It transitively loads
+ * code paths from `bmad-method`, which itself interacts with
+ * `@clack/prompts` / `@clack/core` (both `"type": "module"`).
+ * On Node runtimes where `require()` of ESM is permitted but still
+ * emits `ExperimentalWarning` (notably Node 20.17+ through early 22.x),
+ * every installer run prints a noisy warning before the banner.
+ *
+ * The warning is cosmetic — the installer completes successfully — but
+ * it frightens first-time users and pollutes CI logs.
+ *
+ * Why a `process.on('warning', ...)` listener alone is NOT enough
+ * ----------------------------------------------------------------
+ * In Node.js 20+, `ExperimentalWarning` is printed through an internal
+ * path that does not honor user-land `'warning'` listeners for
+ * suppression purposes — the listener is invoked, but Node ALSO prints
+ * the default formatted message to stderr. The only reliable way to
+ * silence it is a CLI flag at process start:
+ *   NODE_OPTIONS="--no-warnings=ExperimentalWarning"  (Node 16+)
+ *
+ * Strategy
+ * --------
+ * On first entry, we check whether the current process was started with
+ * the suppression flag. If not, we re-exec ourselves in a child
+ * process with `NODE_OPTIONS` augmented to include the flag, inherit
+ * its stdio, and exit with the child's status. A sentinel env var
+ * `MA_AGENTS_WARNINGS_FILTERED=1` prevents infinite re-spawn loops.
+ *
+ * We additionally attach a `process.on('warning')` listener that
+ * silently swallows the specific CJS-require-ESM ExperimentalWarning
+ * (if it somehow reaches user-land despite the flag) while re-emitting
+ * every other warning. This is belt-and-braces for Node versions where
+ * listener semantics differ.
+ *
+ * For the bmad-method child process spawn (separate Node invocation),
+ * `lib/bmad.js` extends `NODE_OPTIONS` with the same flag via
+ * `withExperimentalWarningSuppressed()` so the child is equally quiet.
+ *
+ * This module MUST stay CommonJS and MUST NOT import any ESM package.
+ *
+ * @module lib/warning-filter
+ */
+
+'use strict';
+
+const SENTINEL_ENV = 'MA_AGENTS_WARNINGS_FILTERED';
+const SUPPRESS_FLAG = '--no-warnings=ExperimentalWarning';
+
+/**
+ * Default Node.js warning formatter (mirrors the built-in output
+ * used when no `warning` listener is registered). Kept in sync with
+ * Node's internal `process/warning.js` formatting circa Node 20–22.
+ *
+ * @param {Error} warning
+ * @returns {string}
+ */
+function formatWarning(warning) {
+    const name = warning && warning.name ? warning.name : 'Warning';
+    const code = warning && warning.code ? ` [${warning.code}]` : '';
+    const message = warning && warning.message ? warning.message : String(warning);
+    const detail = warning && warning.detail ? `\n${warning.detail}` : '';
+    const stack = warning && warning.stack ? warning.stack.split('\n').slice(1).join('\n') : '';
+    const header = `(node:${process.pid}) ${name}${code}: ${message}`;
+    const body = stack ? `${header}\n${stack}` : header;
+    return detail ? `${body}${detail}\n` : `${body}\n`;
+}
+
+/**
+ * Classify a warning as the specific "CommonJS require() loading an ES Module"
+ * ExperimentalWarning we want to suppress.
+ *
+ * Matches two Node phrasings observed in v20.17+ / v22.x:
+ *   1. "CommonJS module <X> is loading ES Module <Y> using require()"
+ *   2. "Support for loading ES Module in require() is an experimental feature"
+ *
+ * Only matches when `warning.name === 'ExperimentalWarning'` — never
+ * silences a DeprecationWarning, custom warning, or anything else.
+ *
+ * @param {Error|{name?: string, message?: string}} warning
+ * @returns {boolean}
+ */
+function isRequireEsmWarning(warning) {
+    if (!warning || warning.name !== 'ExperimentalWarning') {
+        return false;
+    }
+    const msg = String(warning.message || '');
+    if (/CommonJS module\b.*\bloading ES Module\b.*\brequire\(\)/i.test(msg)) {
+        return true;
+    }
+    if (/Support for loading ES Module in require\(\)/i.test(msg)) {
+        return true;
+    }
+    return false;
+}
+
+/**
+ * Build the NODE_OPTIONS value that should be passed to a child Node
+ * process (such as bmad-method) to silence the ExperimentalWarning.
+ * Preserves any existing NODE_OPTIONS the caller already set.
+ *
+ * @param {string|undefined} currentNodeOptions - value of NODE_OPTIONS in the parent env
+ * @returns {string} new NODE_OPTIONS value (may equal input if flag already present)
+ */
+function withExperimentalWarningSuppressed(currentNodeOptions) {
+    const current = (currentNodeOptions || '').trim();
+    if (!current) {
+        return SUPPRESS_FLAG;
+    }
+    // If any form of --no-warnings is already present, keep as-is.
+    if (/(^|\s)--no-warnings(\s|=|$)/.test(current)) {
+        return current;
+    }
+    return `${current} ${SUPPRESS_FLAG}`;
+}
+
+/**
+ * Returns true if the current Node process was started with a command-line
+ * option that already suppresses the target warning. Inspects
+ * `process.execArgv` (flags passed directly to node) and the environment's
+ * `NODE_OPTIONS` (flags Node consumed from env at startup).
+ *
+ * @returns {boolean}
+ */
+function isWarningAlreadySuppressed() {
+    const execArgv = process.execArgv || [];
+    for (const a of execArgv) {
+        if (a === '--no-warnings' || a.startsWith('--no-warnings=')) return true;
+        if (a.startsWith('--disable-warning=')) return true;
+    }
+    const opts = (process.env.NODE_OPTIONS || '').trim();
+    if (/(^|\s)--no-warnings(\s|=|$)/.test(opts)) return true;
+    if (/(^|\s)--disable-warning=/.test(opts)) return true;
+    return false;
+}
+
+/**
+ * Attach the user-land warning listener (belt-and-braces). Idempotent —
+ * tags its listener with `__maAgentsFilter` so repeated calls only
+ * register one.
+ *
+ * @returns {boolean} true if newly attached, false if already attached.
+ */
+function attachListener() {
+    const existing = process.listeners('warning').find(fn => fn.__maAgentsFilter === true);
+    if (existing) return false;
+
+    function filter(warning) {
+        if (isRequireEsmWarning(warning)) {
+            return; // swallow — cosmetic warning we fix
+        }
+        try {
+            process.stderr.write(formatWarning(warning));
+        } catch {
+            // never throw from a warning listener
+        }
+    }
+    filter.__maAgentsFilter = true;
+    process.on('warning', filter);
+    return true;
+}
+
+/**
+ * Install the warning filter. On first call from a non-suppressed
+ * process, re-execs the current script with
+ * `NODE_OPTIONS="--no-warnings=ExperimentalWarning"` and a sentinel env
+ * var to prevent re-spawn loops, then exits with the child's status.
+ *
+ * On subsequent calls — or when the process is already suppressed —
+ * it simply attaches the user-land listener and returns.
+ *
+ * Safe to call multiple times (idempotent).
+ *
+ * @param {Object} [opts]
+ * @param {boolean} [opts.reexec=true] - set to false to skip re-exec
+ *   (used by tests that want to verify listener behaviour only).
+ * @returns {boolean} true if the filter was newly installed, false if
+ *   a previous install was already active.
+ */
+function installExperimentalWarningFilter(opts = {}) {
+    const reexec = opts.reexec !== false;
+
+    // If already re-execed, or already suppressed via flags, just attach
+    // the listener and move on.
+    if (process.env[SENTINEL_ENV] === '1' || isWarningAlreadySuppressed()) {
+        return attachListener();
+    }
+
+    if (!reexec) {
+        return attachListener();
+    }
+
+    // Re-exec self with the suppression flag in NODE_OPTIONS.
+    // We use spawnSync to wait for the child synchronously and then
+    // propagate its exit code.
+    const { spawnSync } = require('child_process');
+    const newEnv = {
+        ...process.env,
+        [SENTINEL_ENV]: '1',
+        NODE_OPTIONS: withExperimentalWarningSuppressed(process.env.NODE_OPTIONS),
+    };
+    // Forward most execArgv flags to the child, but drop any --inspect*
+    // variants — the parent has already bound the debugger port, so the
+    // child would fail with EADDRINUSE. The debugger is attached to the
+    // parent only; since the parent exits immediately after the child,
+    // this is acceptable.
+    const forwardedExecArgv = (process.execArgv || []).filter(a =>
+        !/^--inspect(-brk|-port)?(=|$)/.test(a)
+    );
+    const args = [...forwardedExecArgv, ...(process.argv.slice(1) || [])];
+    const child = spawnSync(process.execPath, args, {
+        stdio: 'inherit',
+        env: newEnv,
+    });
+    // If spawn failed (e.g., EACCES), fall back to listener-only mode.
+    if (child.error) {
+        return attachListener();
+    }
+    // Propagate signal or exit code. Node's process.exit is the last
+    // thing we do on this path.
+    if (child.signal) {
+        process.kill(process.pid, child.signal);
+        // In case the signal was ignored:
+        process.exit(1);
+    }
+    process.exit(typeof child.status === 'number' ? child.status : 0);
+}
+
+module.exports = {
+    installExperimentalWarningFilter,
+    isRequireEsmWarning,
+    withExperimentalWarningSuppressed,
+    isWarningAlreadySuppressed,
+    // exposed for tests only
+    _formatWarning: formatWarning,
+    _attachListener: attachListener,
+    _SENTINEL_ENV: SENTINEL_ENV,
+    _SUPPRESS_FLAG: SUPPRESS_FLAG,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ma-agents",
-  "version": "3.5.4",
+  "version": "3.5.6",
   "description": "NPX tool to install skills for AI coding agents (Claude Code, Gemini, Copilot, Kilocode, Cline, Cursor, Roo Code)",
   "main": "index.js",
   "bin": {
@@ -8,7 +8,7 @@
   },
   "scripts": {
     "start": "node bin/cli.js",
-    "test": "node test/yes-flag.test.js && node test/skill-authoring.test.js && node test/skill-validation.test.js && node test/skill-mandatory.test.js && node test/skill-customize-agent.test.js && node test/create-agent.test.js && node test/generate-project-context.test.js && node test/build-bmad-args.test.js && node test/bmad-version-bump.test.js && node test/extension-module-restructure.test.js && node test/convert-agents-to-skills.test.js && node test/migration.test.js && node test/migration-validation.test.js && node test/story-15-5-workflow-skills.test.js && node test/repo-layout.test.js && node test/config-storage.test.js && node test/cross-repo-validation.test.js && node test/config-lost-on-update.test.js && node test/portable-paths.test.js && node test/cicd-remote-mode.test.js && node test/config-layout.test.js && node test/roo-code-agent.test.js && node test/roo-code-injection.test.js && node test/profile.test.js && node test/onprem-injection.test.js",
+    "test": "node test/yes-flag.test.js && node test/skill-authoring.test.js && node test/skill-validation.test.js && node test/skill-mandatory.test.js && node test/skill-customize-agent.test.js && node test/create-agent.test.js && node test/generate-project-context.test.js && node test/build-bmad-args.test.js && node test/bmad-version-bump.test.js && node test/extension-module-restructure.test.js && node test/convert-agents-to-skills.test.js && node test/migration.test.js && node test/migration-validation.test.js && node test/story-15-5-workflow-skills.test.js && node test/repo-layout.test.js && node test/config-storage.test.js && node test/cross-repo-validation.test.js && node test/config-lost-on-update.test.js && node test/portable-paths.test.js && node test/cicd-remote-mode.test.js && node test/config-layout.test.js && node test/roo-code-agent.test.js && node test/roo-code-injection.test.js && node test/profile.test.js && node test/onprem-injection.test.js && node test/experimental-warning.test.js",
     "build:bmad-cache": "node scripts/build-bmad-cache.js"
   },
   "keywords": [

package/test/experimental-warning.test.js

@@ -0,0 +1,314 @@
+#!/usr/bin/env node
+/**
+ * Tests for Bug A: ExperimentalWarning about CommonJS loading ES Module
+ * during installer startup.
+ *
+ * Contract:
+ *   lib/warning-filter.js exports installExperimentalWarningFilter().
+ *   When installed, the process-level 'warning' listener swallows
+ *   ExperimentalWarning messages that describe CJS require() of an
+ *   ES Module, but lets every other warning through unchanged.
+ *
+ * Additionally, bin/cli.js must install the filter at startup, and
+ * lib/bmad.js must pass NODE_OPTIONS="--no-warnings=ExperimentalWarning"
+ * (or equivalent) to the bmad-method child spawn env.
+ */
+'use strict';
+
+const assert = require('assert');
+const { spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const REPO_ROOT = path.join(__dirname, '..');
+const FILTER_PATH = path.join(REPO_ROOT, 'lib', 'warning-filter.js');
+const CLI_PATH = path.join(REPO_ROOT, 'bin', 'cli.js');
+const BMAD_PATH = path.join(REPO_ROOT, 'lib', 'bmad.js');
+
+let passed = 0;
+let failed = 0;
+
+function test(name, fn) {
+  try {
+    fn();
+    console.log(`  ✓ ${name}`);
+    passed++;
+  } catch (err) {
+    console.error(`  ✗ ${name}: ${err.message}`);
+    if (err.stack) console.error(err.stack.split('\n').slice(1, 4).join('\n'));
+    failed++;
+  }
+}
+
+console.log('\n── Bug A: ExperimentalWarning filter tests ──────────────────────\n');
+
+// ─── Test 1: filter module exists and exports the expected API ────────────────
+test('lib/warning-filter.js exists', () => {
+  assert.ok(fs.existsSync(FILTER_PATH), 'expected lib/warning-filter.js to exist');
+});
+
+test('filter module exports installExperimentalWarningFilter()', () => {
+  const mod = require(FILTER_PATH);
+  assert.strictEqual(typeof mod.installExperimentalWarningFilter, 'function');
+});
+
+test('filter module exports isRequireEsmWarning() predicate', () => {
+  const mod = require(FILTER_PATH);
+  assert.strictEqual(typeof mod.isRequireEsmWarning, 'function');
+});
+
+// ─── Test 2: isRequireEsmWarning() correctly classifies warnings ──────────────
+test('isRequireEsmWarning matches CJS-loading-ESM ExperimentalWarning', () => {
+  const { isRequireEsmWarning } = require(FILTER_PATH);
+  const w = new Error(
+    'CommonJS module /a/b.js is loading ES Module /c/d.js using require(). ' +
+    'Support for loading ES Module in require() is an experimental feature ' +
+    'and might change at any time.'
+  );
+  w.name = 'ExperimentalWarning';
+  assert.strictEqual(isRequireEsmWarning(w), true);
+});
+
+test('isRequireEsmWarning matches require(ESM) variant phrasing', () => {
+  const { isRequireEsmWarning } = require(FILTER_PATH);
+  const w = new Error('Support for loading ES Module in require() is an experimental feature.');
+  w.name = 'ExperimentalWarning';
+  assert.strictEqual(isRequireEsmWarning(w), true);
+});
+
+test('isRequireEsmWarning ignores unrelated ExperimentalWarning', () => {
+  const { isRequireEsmWarning } = require(FILTER_PATH);
+  const w = new Error('Fetch API is an experimental feature.');
+  w.name = 'ExperimentalWarning';
+  assert.strictEqual(isRequireEsmWarning(w), false);
+});
+
+test('isRequireEsmWarning ignores DeprecationWarning with require() text', () => {
+  const { isRequireEsmWarning } = require(FILTER_PATH);
+  const w = new Error('Some deprecated require() usage in ES Module.');
+  w.name = 'DeprecationWarning';
+  assert.strictEqual(isRequireEsmWarning(w), false);
+});
+
+// ─── Test 3: end-to-end — re-exec flow silences ExperimentalWarning ──────────
+test('installed filter (with re-exec) silences CJS-require-ESM ExperimentalWarning', () => {
+  // Drive the full re-exec path: parent re-execs with NODE_OPTIONS set,
+  // child emits the warning, expects ZERO bytes of ExperimentalWarning.
+  const child = spawnSync(process.execPath, [
+    '-e',
+    `const { installExperimentalWarningFilter } = require(${JSON.stringify(FILTER_PATH)});
+     installExperimentalWarningFilter();
+     // After re-exec we land here in the child:
+     process.emitWarning('CommonJS module /a.js is loading ES Module /b.mjs using require().', 'ExperimentalWarning');`,
+  ], { encoding: 'utf8' });
+  assert.strictEqual(child.status, 0, `child exited non-zero: ${child.stderr}`);
+  assert.ok(
+    !/ExperimentalWarning/.test(child.stderr),
+    `expected no ExperimentalWarning in stderr, got:\n${child.stderr}`
+  );
+});
+
+// ─── Test 3b: NODE_OPTIONS-only test bypasses re-exec ─────────────────────────
+test('listener-only mode swallows the matched warning at user-land', () => {
+  // reexec:false means we only attach the listener; target warning still
+  // hits Node's internal printer in some Node versions, but our listener
+  // returns silently so the listener path itself never re-emits it.
+  const child = spawnSync(process.execPath, [
+    '-e',
+    `const { installExperimentalWarningFilter, _attachListener } = require(${JSON.stringify(FILTER_PATH)});
+     installExperimentalWarningFilter({ reexec: false });
+     // Emit a custom-named warning identical in shape so we don't depend
+     // on Node's internal experimental-warning path:
+     const w = new Error('CommonJS module /a.js is loading ES Module /b.mjs using require().');
+     w.name = 'ExperimentalWarning';
+     // Drive the listener directly to assert it returns without writing.
+     const listener = process.listeners('warning').find(fn => fn.__maAgentsFilter);
+     if (!listener) { console.error('no filter listener'); process.exit(2); }
+     // capture stderr writes
+     let captured = '';
+     const orig = process.stderr.write.bind(process.stderr);
+     process.stderr.write = (c) => { captured += String(c); return true; };
+     listener(w);
+     process.stderr.write = orig;
+     if (captured.length !== 0) { console.error('LEAKED:', captured); process.exit(3); }
+     process.exit(0);`,
+  ], { encoding: 'utf8', env: { ...process.env, [require(FILTER_PATH)._SENTINEL_ENV]: '1' } });
+  assert.strictEqual(child.status, 0, `child exited ${child.status}: ${child.stderr}`);
+});
+
+// ─── Test 4: filter preserves unrelated warnings ──────────────────────────────
+test('installed filter preserves DeprecationWarning', () => {
+  // Drive the listener directly to verify it re-emits non-matching warnings.
+  const child = spawnSync(process.execPath, [
+    '-e',
+    `const { installExperimentalWarningFilter } = require(${JSON.stringify(FILTER_PATH)});
+     installExperimentalWarningFilter({ reexec: false });
+     const listener = process.listeners('warning').find(fn => fn.__maAgentsFilter);
+     const w = new Error('legacy api — do not use');
+     w.name = 'DeprecationWarning';
+     let captured = '';
+     const orig = process.stderr.write.bind(process.stderr);
+     process.stderr.write = (c) => { captured += String(c); return true; };
+     listener(w);
+     process.stderr.write = orig;
+     process.stdout.write(captured);`,
+  ], { encoding: 'utf8' });
+  assert.strictEqual(child.status, 0);
+  assert.ok(
+    /DeprecationWarning/.test(child.stdout),
+    `expected DeprecationWarning to be preserved, stdout=\n${child.stdout}\nstderr=\n${child.stderr}`
+  );
+});
+
+test('installed filter preserves unrelated ExperimentalWarning', () => {
+  const child = spawnSync(process.execPath, [
+    '-e',
+    `const { installExperimentalWarningFilter } = require(${JSON.stringify(FILTER_PATH)});
+     installExperimentalWarningFilter({ reexec: false });
+     const listener = process.listeners('warning').find(fn => fn.__maAgentsFilter);
+     const w = new Error('Fetch API is an experimental feature.');
+     w.name = 'ExperimentalWarning';
+     let captured = '';
+     const orig = process.stderr.write.bind(process.stderr);
+     process.stderr.write = (c) => { captured += String(c); return true; };
+     listener(w);
+     process.stderr.write = orig;
+     process.stdout.write(captured);`,
+  ], { encoding: 'utf8' });
+  assert.strictEqual(child.status, 0);
+  assert.ok(
+    /Fetch API/.test(child.stdout),
+    `expected unrelated ExperimentalWarning preserved, stdout=\n${child.stdout}`
+  );
+});
+
+// ─── Test 5: idempotent — installing twice doesn't double-suppress or leak ────
+test('installExperimentalWarningFilter is idempotent', () => {
+  const child = spawnSync(process.execPath, [
+    '-e',
+    `const { installExperimentalWarningFilter } = require(${JSON.stringify(FILTER_PATH)});
+     installExperimentalWarningFilter({ reexec: false });
+     installExperimentalWarningFilter({ reexec: false });
+     const listeners = process.listeners('warning').filter(fn => fn.__maAgentsFilter === true);
+     if (listeners.length !== 1) {
+       console.error('EXPECTED 1 filter listener, got', listeners.length);
+       process.exit(2);
+     }
+     process.exit(0);`,
+  ], { encoding: 'utf8' });
+  assert.strictEqual(child.status, 0, `child exited ${child.status}: ${child.stderr}`);
+});
+
+// ─── Test 6: bin/cli.js wires the filter at startup ───────────────────────────
+test('bin/cli.js requires warning-filter and installs it', () => {
+  const src = fs.readFileSync(CLI_PATH, 'utf8');
+  assert.ok(
+    /require\(['"]\.\.\/lib\/warning-filter['"]\)/.test(src) ||
+    /require\(['"]\.\.\/lib\/warning-filter\.js['"]\)/.test(src),
+    'expected bin/cli.js to require ../lib/warning-filter'
+  );
+  assert.ok(
+    /installExperimentalWarningFilter\s*\(/.test(src),
+    'expected bin/cli.js to call installExperimentalWarningFilter(...)'
+  );
+});
+
+// ─── Test 7: lib/bmad.js propagates suppression to child spawn via NODE_OPTIONS
+test('lib/bmad.js builds child env that suppresses ExperimentalWarning', () => {
+  const src = fs.readFileSync(BMAD_PATH, 'utf8');
+  // Either calls the helper directly or inlines the flag.
+  const usesHelper = /withExperimentalWarningSuppressed/.test(src) &&
+                     /require\(['"]\.\/warning-filter['"]\)/.test(src);
+  const inlinesFlag = /--no-warnings=ExperimentalWarning/.test(src);
+  assert.ok(
+    usesHelper || inlinesFlag,
+    'expected lib/bmad.js to either import withExperimentalWarningSuppressed ' +
+    'from ./warning-filter, or inline --no-warnings=ExperimentalWarning'
+  );
+  assert.ok(
+    /NODE_OPTIONS/.test(src),
+    'expected lib/bmad.js to set NODE_OPTIONS for the child spawn'
+  );
+});
+
+// ─── Test 8: integration — running bin/cli.js --help is silent on stderr ──────
+test('bin/cli.js --help produces no ExperimentalWarning on stderr', () => {
+  const child = spawnSync(process.execPath, [CLI_PATH, '--help'], {
+    encoding: 'utf8',
+    env: { ...process.env, [require(FILTER_PATH)._SENTINEL_ENV]: '' },
+  });
+  assert.strictEqual(child.status, 0, `cli --help exited non-zero: ${child.stderr}`);
+  assert.ok(
+    !/ExperimentalWarning/.test(child.stderr),
+    `expected no ExperimentalWarning from cli --help, got:\n${child.stderr}`
+  );
+});
+
+// ─── Test 9: withExperimentalWarningSuppressed helper is well-behaved ─────────
+test('withExperimentalWarningSuppressed adds flag when none present', () => {
+  const { withExperimentalWarningSuppressed } = require(FILTER_PATH);
+  assert.strictEqual(withExperimentalWarningSuppressed(undefined), '--no-warnings=ExperimentalWarning');
+  assert.strictEqual(withExperimentalWarningSuppressed(''), '--no-warnings=ExperimentalWarning');
+});
+
+test('withExperimentalWarningSuppressed preserves existing --no-warnings', () => {
+  const { withExperimentalWarningSuppressed } = require(FILTER_PATH);
+  assert.strictEqual(withExperimentalWarningSuppressed('--no-warnings'), '--no-warnings');
+  assert.strictEqual(
+    withExperimentalWarningSuppressed('--no-warnings=DeprecationWarning'),
+    '--no-warnings=DeprecationWarning'
+  );
+});
+
+test('withExperimentalWarningSuppressed appends flag to other NODE_OPTIONS', () => {
+  const { withExperimentalWarningSuppressed } = require(FILTER_PATH);
+  assert.strictEqual(
+    withExperimentalWarningSuppressed('--max-old-space-size=4096'),
+    '--max-old-space-size=4096 --no-warnings=ExperimentalWarning'
+  );
+});
+
+// ─── Test 10: regression — require('bin/cli.js') must NOT re-exec ───────────
+test('require("bin/cli.js") from another process does not re-exec', () => {
+  // If the CLI silently re-execs on require, the "before pid" line
+  // would print twice in the stderr/stdout stream.
+  const child = spawnSync(process.execPath, [
+    '-e',
+    `const before = process.pid;
+     console.log('MARK_BEFORE', before);
+     require(${JSON.stringify(CLI_PATH)});
+     console.log('MARK_AFTER', process.pid, 'same:', process.pid === before);`,
+  ], { encoding: 'utf8' });
+  assert.strictEqual(child.status, 0, `child exited non-zero: ${child.stderr}`);
+  const beforeCount = (child.stdout.match(/MARK_BEFORE/g) || []).length;
+  assert.strictEqual(beforeCount, 1, `expected exactly one MARK_BEFORE, got ${beforeCount}\n${child.stdout}`);
+  assert.ok(/same: true/.test(child.stdout), 'expected PID to be unchanged after require');
+});
+
+// ─── Test 11: regression — fast commands must NOT re-exec ────────────────────
+test('bin/cli.js --version runs in a single process (no re-exec)', () => {
+  // Spawn cli.js --version and assert PID stability via NODE_OPTIONS check.
+  // We approximate by running it with the sentinel unset and checking it
+  // still completes without looping. A process-tree check is overkill;
+  // we just verify exit code and output shape.
+  const child = spawnSync(process.execPath, [CLI_PATH, '--version'], {
+    encoding: 'utf8',
+    env: { ...process.env, [require(FILTER_PATH)._SENTINEL_ENV]: '' },
+  });
+  assert.strictEqual(child.status, 0);
+  assert.ok(/ma-agents v/.test(child.stdout), `expected version banner, got: ${child.stdout}`);
+  assert.ok(!/ExperimentalWarning/.test(child.stderr));
+});
+
+// ─── Test 12: --inspect is not forwarded to the re-exec child ────────────────
+test('installExperimentalWarningFilter drops --inspect* from forwarded execArgv', () => {
+  const src = fs.readFileSync(FILTER_PATH, 'utf8');
+  assert.ok(
+    /--inspect/.test(src) && /filter/.test(src),
+    'expected warning-filter.js to filter --inspect out of forwarded execArgv'
+  );
+});
+
+// ─── Summary ──────────────────────────────────────────────────────────────────
+console.log(`\n  ${passed} passed, ${failed} failed\n`);
+if (failed > 0) process.exit(1);

package/.ma-agents.json

@@ -1,10 +0,0 @@
-{
-  "manifestVersion": "1.2.0",
-  "agent": null,
-  "agents": [
-    null
-  ],
-  "scope": "project",
-  "skills": {},
-  "profile": "standard"
-}

package/MANIFEST.yaml

@@ -1,3 +0,0 @@
-# MANIFEST.yaml
-
-skills:

package/_bmad-output/methodology/version.json

@@ -1,7 +0,0 @@
-{
-  "version": "1.0.0",
-  "description": "BMAD-METHOD AI Development Training Presentation",
-  "files": [
-    "BMAD_AI_Development_Training.pptx"
-  ]
-}