bmad-method 6.8.1-next.2 → 6.8.1-next.20

package/src/{core-skills/bmad-brainstorming/scripts → scripts}/tests/test_memlog.py

@@ -5,7 +5,8 @@
 """Tests for memlog.py. Run: uv run --with pytest pytest scripts/tests/test_memlog.py
 
 The spine under test is the flat, append-only, chronological invariant: every entry is
-one line recorded at the end in the order it happened — no sections, no grouping.
+one line recorded at the end in the order it happened — no sections, no grouping, and no
+lifecycle status the log would have to mutate.
 """
 import json
 import sys
@@ -60,11 +61,17 @@ def test_init_writes_frontmatter_fields(ws):
     meta, body = memlog.split(read(ws))
     assert meta["topic"] == "Reinvent the lunchbox"
     assert meta["goal"] == "ideas for a pitch"
-    assert meta["status"] == "active"
     assert "updated" in meta
     assert body.strip() == ""
 
 
+def test_init_has_no_lifecycle_status(ws):
+    # A memory log carries no "status" flag; completion is an appended entry, not frontmatter.
+    init(ws)
+    meta, _ = memlog.split(read(ws))
+    assert "status" not in meta
+
+
 def test_init_arbitrary_fields(ws):
     init(ws, topic="T", audience="board")
     meta, _ = memlog.split(read(ws))
@@ -86,6 +93,30 @@ def test_init_rejects_malformed_field(ws):
     assert memlog.main(["init", "--workspace", ws, "--field", "noequals"]) == 2
 
 
+# --- addressing: --workspace and --path are interchangeable --------------
+
+def test_path_addressing_targets_the_file_directly(tmp_path):
+    target = tmp_path / "run" / ".memlog.md"
+    assert memlog.main(["init", "--path", str(target), "--field", "topic=T"]) == 0
+    assert target.is_file()
+    assert memlog.main(["append", "--path", str(target), "--text", "an idea", "--type", "idea"]) == 0
+    body = memlog.split(target.read_text(encoding="utf-8"))[1]
+    assert "- (idea) an idea" in body
+
+
+def test_workspace_and_path_resolve_to_same_file(ws):
+    init(ws)
+    via_path = str(Path(ws) / MEMLOG)
+    assert memlog.main(["append", "--path", via_path, "--text", "from path"]) == 0
+    assert memlog.main(["append", "--workspace", ws, "--text", "from workspace"]) == 0
+    assert entries(ws) == ["- from path", "- from workspace"]
+
+
+def test_target_is_required(ws):
+    with pytest.raises(SystemExit):
+        memlog.main(["append", "--text", "orphan"])  # neither --workspace nor --path
+
+
 # --- append: flat chronological order is the whole point -----------------
 
 def test_append_lands_at_end_in_order(ws):
@@ -119,6 +150,15 @@ def test_append_without_type_is_plain_note(ws):
     assert entries(ws) == ["- bare entry"]
 
 
+def test_completion_is_an_entry_not_a_status(ws):
+    # The documented way to mark a session done: append it. Frontmatter never gains a status.
+    init(ws)
+    append(ws, "session complete", entry_type="event")
+    meta, _ = memlog.split(read(ws))
+    assert "status" not in meta
+    assert entries(ws)[-1] == "- (event) session complete"
+
+
 def test_append_collapses_newlines_into_one_line(ws):
     init(ws)
     append(ws, "line one\nline two\n  spaced   out")
@@ -171,29 +211,39 @@ def test_heterogeneous_entry_types_coexist(ws):
         assert tag in body
 
 
-# --- set ----------------------------------------------------------------
+def test_free_vocabulary_is_not_enforced(ws):
+    # The tool is neutral: any --type the host skill names renders verbatim.
+    init(ws)
+    append(ws, "a custom kind", entry_type="crack")
+    append(ws, "another", entry_type="lock")
+    body = body_of(ws)
+    assert "- (crack) a custom kind" in body
+    assert "- (lock) another" in body
+
+
+# --- set: generic descriptive frontmatter, no lifecycle semantics --------
 
-def test_set_flips_status(ws):
+def test_set_adds_field(ws):
     init(ws)
-    memlog.main(["set", "--workspace", ws, "--key", "status", "--value", "complete"])
-    assert memlog.split(read(ws))[0]["status"] == "complete"
+    memlog.main(["set", "--workspace", ws, "--key", "mode", "--value", "partner"])
+    assert memlog.split(read(ws))[0]["mode"] == "partner"
+
+
+def test_set_replaces_field(ws):
+    init(ws, topic="T", mode="facilitator")
+    memlog.main(["set", "--workspace", ws, "--key", "mode", "--value", "partner"])
+    assert memlog.split(read(ws))[0]["mode"] == "partner"
 
 
 def test_set_preserves_body(ws):
     init(ws)
     append(ws, "keep me", entry_type="idea")
-    memlog.main(["set", "--workspace", ws, "--key", "status", "--value", "complete"])
+    memlog.main(["set", "--workspace", ws, "--key", "mode", "--value", "partner"])
     meta, body = memlog.split(read(ws))
-    assert meta["status"] == "complete"
+    assert meta["mode"] == "partner"
     assert "- (idea) keep me" in body
 
 
-def test_set_can_add_new_field(ws):
-    init(ws)
-    memlog.main(["set", "--workspace", ws, "--key", "owner", "--value", "BMad"])
-    assert memlog.split(read(ws))[0]["owner"] == "BMad"
-
-
 def test_updated_stays_last(ws):
     init(ws)
     memlog.main(["set", "--workspace", ws, "--key", "owner", "--value", "BMad"])
@@ -219,22 +269,14 @@ def test_commas_in_field_survive(ws):
 
 
 def test_triple_dash_in_field_does_not_corrupt_frontmatter(ws):
-    # A `---` inside a value must NOT be read as the closing fence: topic stays intact,
-    # status survives, and the body never leaks frontmatter text.
+    # A `---` inside a value must NOT be read as the closing fence: topic stays intact
+    # and the body never leaks frontmatter text.
     init(ws, topic="Pricing --- tiers --- and add-ons")
     append(ws, "an idea", entry_type="idea")
     meta, body = memlog.split(read(ws))
     assert meta["topic"] == "Pricing --- tiers --- and add-ons"
-    assert meta["status"] == "active"
     assert entries(ws) == ["- (idea) an idea"]
-    assert "status:" not in body  # frontmatter never bled into the body
-
-
-def test_triple_dash_status_survives_in_ack(ws, capsys):
-    init(ws, topic="a --- b")
-    append(ws, "x", entry_type="idea")
-    out = json.loads(capsys.readouterr().out.strip().splitlines()[-1])
-    assert out["status"] == "active"  # not "" — frontmatter recovered cleanly
+    assert "topic:" not in body  # frontmatter never bled into the body
 
 
 def test_newline_in_field_is_neutralized(ws):
@@ -243,7 +285,6 @@ def test_newline_in_field_is_neutralized(ws):
     append(ws, "x", entry_type="idea")
     meta, _ = memlog.split(read(ws))
     assert "\n" not in meta["topic"]
-    assert meta["status"] == "active"
 
 
 def test_append_emits_json_ack(ws, capsys):
@@ -251,9 +292,9 @@ def test_append_emits_json_ack(ws, capsys):
     append(ws, "x", entry_type="idea")
     out = json.loads(capsys.readouterr().out.strip().splitlines()[-1])
     assert out["ok"] is True
-    assert out["status"] == "active"
     assert out["entries"] == 1
     assert out["memlog"].endswith(MEMLOG)
+    assert "status" not in out  # no lifecycle status
     assert "section" not in out  # sections are gone
 
 

package/tools/installer/commands/install.js

@@ -75,6 +75,9 @@ module.exports = {
         return;
       }
 
+      const { checkWindowsNodeFromWsl } = require('../core/wsl-node-check');
+      await checkWindowsNodeFromWsl();
+
       // Set debug flag as environment variable for all components
       if (options.debug) {
         process.env.BMAD_DEBUG_MANIFEST = 'true';

package/tools/installer/core/installer.js

@@ -419,10 +419,35 @@ class Installer {
       const sourceDir = path.dirname(path.join(bmadDir, relativePath));
       if (await fs.pathExists(sourceDir)) {
         await fs.remove(sourceDir);
+        await this._removeEmptyParents(path.dirname(sourceDir), bmadDir);
       }
     }
   }
 
+  /**
+   * Remove now-empty parent directories left behind after skill dir cleanup.
+   * Walks up from dir, stopping at (and never removing) bmadDir. Best-effort:
+   * a directory that vanishes or fills in mid-walk just ends the walk.
+   * @param {string} dir - Directory to start walking up from
+   * @param {string} bmadDir - BMAD installation directory (boundary)
+   */
+  async _removeEmptyParents(dir, bmadDir) {
+    let current = dir;
+    while (true) {
+      // Path-boundary check (not a string prefix, so siblings like _bmad2 don't match).
+      const rel = path.relative(bmadDir, current);
+      if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) break;
+      try {
+        const entries = await fs.readdir(current);
+        if (entries.length > 0) break;
+        await fs.rmdir(current);
+      } catch {
+        break;
+      }
+      current = path.dirname(current);
+    }
+  }
+
   async _readSkillManifestRows(bmadDir) {
     const csvPath = path.join(bmadDir, '_config', 'skill-manifest.csv');
     if (!(await fs.pathExists(csvPath))) return [];
@@ -630,6 +655,7 @@ class Installer {
   /**
    * Sync src/scripts/* → _bmad/scripts/ so shared Python scripts
    * (e.g. resolve_customization.py) are available at install time.
+   * Excludes dev-only tests and Python caches so they don't ship to users.
    * Wipes the destination first so files removed or renamed in source
    * don't linger and get recorded as installed. Also seeds
    * _bmad/custom/.gitignore on fresh installs so *.user.toml overrides
@@ -643,7 +669,12 @@ class Installer {
 
     await fs.remove(paths.scriptsDir);
     await fs.ensureDir(paths.scriptsDir);
-    await fs.copy(srcScriptsDir, paths.scriptsDir, { overwrite: true });
+    // Ship only the runtime scripts — dev-only tests and Python caches must not land in user projects.
+    const isInstallable = (srcPath) => {
+      const base = path.basename(srcPath);
+      return base !== 'tests' && base !== '__pycache__' && base !== '.pytest_cache' && !base.endsWith('.pyc');
+    };
+    await fs.copy(srcScriptsDir, paths.scriptsDir, { overwrite: true, filter: isInstallable });
     await this._trackFilesRecursive(paths.scriptsDir);
 
     const customGitignore = path.join(paths.customDir, '.gitignore');
@@ -1202,6 +1233,9 @@ class Installer {
       `    1. Launch your AI agent from your project folder`,
       `    2. Not sure what to do? Invoke the ${color.cyan('bmad-help')} skill and ask it what to do!`,
       '',
+      `    ${color.cyan('Tip:')} BMAD workflows increasingly run Python scripts via ${color.cyan('uv run')} — uv is`,
+      `    becoming the de facto standard. If you don't have it yet, ask your agent to set it up.`,
+      '',
       `    Blog, Docs and Guides: ${color.blue('https://bmadcode.com/')}`,
       `    Community: ${color.blue('https://discord.gg/gk8jAdXWmj')}`,
     );

package/tools/installer/core/uv-check.js

@@ -0,0 +1,97 @@
+const { spawnSync } = require('node:child_process');
+const prompts = require('../prompts');
+
+// `uv` (https://docs.astral.sh/uv/) is becoming the de facto standard for
+// running the Python scripts BMAD workflows shell out to: `uv run <script>`
+// resolves the interpreter and any dependencies on demand, so skills don't
+// have to assume a particular `python3` is on PATH. The ecosystem is mid-
+// migration — some skills still call `python3` directly — so a missing `uv`
+// is a warning, not a blocker: BMAD installs and runs either way.
+const RUNTIME_COMMAND = 'uv';
+
+/**
+ * Parse `uv --version` output into version parts.
+ * Example outputs: "uv 0.5.31", "uv 0.5.31 (Homebrew 2025-02-12)".
+ * @param {string} output - stdout/stderr from `uv --version`
+ * @returns {{major: number, minor: number, patch: number, raw: string}|null}
+ */
+function parseUvVersion(output) {
+  if (!output) return null;
+  const match = output.match(/uv\s+(\d+)\.(\d+)(?:\.(\d+))?/i);
+  if (!match) return null;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3] || 0),
+    raw: `${match[1]}.${match[2]}.${match[3] || 0}`,
+  };
+}
+
+/**
+ * Probe the local environment for `uv`.
+ * @returns {{version: {major: number, minor: number, patch: number, raw: string}}|null}
+ */
+function detectUv() {
+  let result;
+  try {
+    result = spawnSync(RUNTIME_COMMAND, ['--version'], {
+      encoding: 'utf8',
+      timeout: 5000,
+      windowsHide: true,
+    });
+  } catch {
+    return null;
+  }
+  if (!result || result.error) return null;
+  const version = parseUvVersion(`${result.stdout || ''}\n${result.stderr || ''}`);
+  return version ? { version } : null;
+}
+
+function setupHints() {
+  return [
+    'BMAD workflows increasingly run Python scripts via `uv run`, which manages',
+    'the interpreter and dependencies for you — no manual venv or pip needed.',
+    '',
+    'Easiest path: ask your AI agent to "install and set up uv for me".',
+    '',
+    'Or install it yourself:',
+    '  macOS/Linux:  curl -LsSf https://astral.sh/uv/install.sh | sh',
+    '  Windows:      powershell -c "irm https://astral.sh/uv/install.ps1 | iex"',
+    '  Homebrew:     brew install uv',
+    '  Docs:         https://docs.astral.sh/uv/getting-started/installation/',
+  ].join('\n');
+}
+
+/**
+ * Check whether `uv` is available and inform the user.
+ *
+ * Warn-don't-block, and no acknowledgement prompt: `uv` is on its way to being
+ * the standard runner for BMAD's Python scripts, but the migration is still in
+ * progress, so the install never stops on its account. The note tells the user
+ * how to set it up (preferably by asking their agent).
+ *
+ * @returns {Promise<{status: 'found'|'missing', detected: Object|null}>}
+ */
+async function checkUvEnvironment() {
+  // Called via module.exports so tests can stub detection.
+  const detected = module.exports.detectUv();
+
+  if (detected) {
+    await prompts.log.success(`uv ${detected.version.raw} detected — ready to run BMAD's Python-powered scripts via \`uv run\`.`);
+    return { status: 'found', detected };
+  }
+
+  await prompts.log.warn(
+    "uv not found on PATH. uv is becoming the de facto standard for running BMAD's Python\n" +
+      'scripts (`uv run <script>`), and it provisions the interpreter for you. BMAD installs\n' +
+      'fine without it, but setting up uv now keeps you ahead as workflows adopt it.',
+  );
+  await prompts.note(setupHints(), 'uv recommended');
+  return { status: 'missing', detected: null };
+}
+
+module.exports = {
+  checkUvEnvironment,
+  detectUv,
+  parseUvVersion,
+};

package/tools/installer/core/wsl-node-check.js

@@ -0,0 +1,109 @@
+const prompts = require('../prompts');
+
+const WSL_UNC_PATTERN = /^\\\\wsl(?:\.localhost|\$)?\\/i;
+
+function normalizePath(value) {
+  return typeof value === 'string' ? value.replaceAll('/', '\\').toLowerCase() : '';
+}
+
+function isLinuxStylePath(value) {
+  return (
+    typeof value === 'string' &&
+    value.startsWith('/') &&
+    !value.startsWith('//') &&
+    !/^\/[a-z](?:\/|$)/i.test(value) &&
+    !/^\/cygdrive\/[a-z](?:\/|$)/i.test(value)
+  );
+}
+
+function isWslUncPath(value) {
+  return WSL_UNC_PATTERN.test(value || '');
+}
+
+/**
+ * Detect the broken interop case where WSL resolved node/npx to Windows.
+ * @param {Object} [runtime]
+ * @param {string} [runtime.platform]
+ * @param {Object} [runtime.env]
+ * @param {string} [runtime.cwd]
+ * @param {string} [runtime.execPath]
+ * @returns {{isMismatch: boolean, reason: string|null, execPath: string}}
+ */
+function detectWindowsNodeFromWsl(runtime = {}) {
+  const platform = runtime.platform || process.platform;
+  const env = runtime.env || process.env;
+  const cwd = runtime.cwd || safeCwd();
+  const execPath = runtime.execPath || process.execPath || '';
+
+  if (platform !== 'win32') {
+    return { isMismatch: false, reason: null, execPath };
+  }
+
+  if (env.WSL_DISTRO_NAME) {
+    return { isMismatch: true, reason: 'WSL_DISTRO_NAME is set', execPath };
+  }
+
+  if (env.WSL_INTEROP) {
+    return { isMismatch: true, reason: 'WSL_INTEROP is set', execPath };
+  }
+
+  if (isLinuxStylePath(env.PWD)) {
+    return { isMismatch: true, reason: 'PWD is a Linux path', execPath };
+  }
+
+  if (isWslUncPath(cwd)) {
+    return { isMismatch: true, reason: 'current directory is a WSL UNC path', execPath };
+  }
+
+  const normalizedExecPath = normalizePath(execPath);
+  if (normalizedExecPath.includes('\\wsl$\\') || normalizedExecPath.includes('\\wsl.localhost\\')) {
+    return { isMismatch: true, reason: 'Node executable path is under a WSL UNC path', execPath };
+  }
+
+  return { isMismatch: false, reason: null, execPath };
+}
+
+function safeCwd() {
+  try {
+    return process.cwd();
+  } catch {
+    return '';
+  }
+}
+
+function formatWindowsNodeFromWslMessage(detection) {
+  const lines = [
+    'Windows Node.js was launched from a WSL shell.',
+    '',
+    'This usually means Node.js is not installed inside the WSL distro, so WSL resolved `node`/`npx` to Windows.',
+    'The installer cannot safely continue because Linux paths may be interpreted as Windows paths.',
+    '',
+    'Install Node.js inside WSL, then rerun the same command from the WSL terminal.',
+  ];
+
+  if (detection.execPath) {
+    lines.push('', `Detected Node executable: ${detection.execPath}`);
+  }
+
+  if (detection.reason) {
+    lines.push(`Detection signal: ${detection.reason}`);
+  }
+
+  return lines.join('\n');
+}
+
+async function checkWindowsNodeFromWsl() {
+  const detection = module.exports.detectWindowsNodeFromWsl();
+  if (!detection.isMismatch) {
+    return detection;
+  }
+
+  await prompts.log.error(formatWindowsNodeFromWslMessage(detection));
+  process.exit(1);
+}
+
+module.exports = {
+  checkWindowsNodeFromWsl,
+  detectWindowsNodeFromWsl,
+  formatWindowsNodeFromWslMessage,
+};

package/tools/installer/ide/platform-codes.yaml

@@ -70,6 +70,13 @@ platforms:
       target_dir: .agents/skills
       global_target_dir: ~/.codex/skills
 
+  codewhale:
+    name: "CodeWhale"
+    preferred: false
+    installer:
+      target_dir: .codewhale/skills
+      global_target_dir: ~/.codewhale/skills
+
   codebuddy:
     name: "CodeBuddy"
     preferred: false
@@ -155,6 +162,13 @@ platforms:
       target_dir: .agents/skills
       global_target_dir: ~/.config/agents/skills
 
+  hermes:
+    name: "Hermes Agent"
+    preferred: false
+    installer:
+      target_dir: .agents/skills
+      global_target_dir: ~/.hermes/skills
+
   iflow:
     name: "iFlow"
     preferred: false

package/tools/installer/install-messages.yaml

@@ -12,6 +12,10 @@ startMessage: |
   🌟 100% free. 100% open source. Always.
      No paywalls. No gated content. Knowledge shared, not sold.
 
+  🐍 HEADS UP: uv (https://docs.astral.sh/uv/) is becoming the de facto standard
+     for running the Python scripts BMAD workflows rely on (`uv run <script>`).
+     If it's not set up yet, ask your AI agent to "install and set up uv for me".
+
   🌐 CONNECT:
     Website:   https://bmadcode.com/
     Discord:   https://discord.gg/gk8jAdXWmj

package/tools/installer/ui.js

@@ -161,6 +161,17 @@ class UI {
     const messageLoader = new MessageLoader();
     await messageLoader.displayStartMessage();
 
+    // Probe for `uv` before any other prompts: it's becoming the de facto
+    // runner for the Python scripts BMAD workflows shell out to
+    // (`uv run <script>`), and uv provisions the interpreter itself, so it's
+    // the single thing worth checking for. The migration is still in progress
+    // (some skills still call `python3` directly), so this is informational —
+    // warn-don't-block, no ack prompt — and just points the user at setup
+    // (ideally "ask your agent to set up uv"). The installer runs in the
+    // destination environment, so probing PATH here tests the right machine.
+    const { checkUvEnvironment } = require('./core/uv-check');
+    await checkUvEnvironment();
+
     // Parse channel flags (--channel/--all-*/--next=/--pin) once. Warnings
     // are surfaced immediately so the user sees them before any git ops run.
     const channelOptions = parseChannelOptions(options);