ma-agents 3.12.3 → 3.13.1

package/bin/cli.js

@@ -33,8 +33,8 @@ const chalk = require('chalk');
 const path = require('path');
 const fs = require('fs');
 const { execFileSync } = require('child_process');
-const { installSkill, uninstallSkill, getStatus, listSkills, listAgents, updateProjectContextRepoLayout, migrateRetiredSkills } = require('../lib/installer');
-const { getProfile, setProfile, resolveProfile } = require('../lib/profile');
+const { installSkill, uninstallSkill, getStatus, listSkills, listAgents, updateProjectContextRepoLayout, migrateRetiredSkills, reconcileAgentsSharedSkills } = require('../lib/installer');
+const { getProfile, setProfile, resolveProfile, getBmadModules, setBmadModules } = require('../lib/profile');
 const { reconfigure: runReconfigure, ReconfigureYesRejectedError, ManifestNotFoundError, RoomodesSlugDivergenceError } = require('../lib/reconfigure');
 const { uninstallProfileArtifacts } = require('../lib/uninstall');
 const bmad = require('../lib/bmad');
@@ -495,6 +495,19 @@ function writeConfigField(content, fieldName, value) {
   return content.trimEnd() + '\n' + newLine + '\n';
 }
 
+// Bug 27.15 — unify the path convention. config.toml (written by upstream
+// manifest-generator) declares artifact paths with a `{project-root}/` prefix;
+// previously writeRepoLayoutConfig emitted a THIRD variant: bare relative
+// `_bmad-output/...`. Emit the same `{project-root}/`-prefixed form here so
+// ma-agents stops adding a divergent third convention. config.toml is the
+// install-owned source of truth; the per-module config.yaml is the
+// upstream-stripped read copy. Fully aligning the upstream stripper
+// (official-modules.js) is a separate upstream follow-up; vendored node_modules
+// is not edited here.
+function canonicalArtifactPath(suffix) {
+  return `{project-root}/_bmad-output/${suffix}`;
+}
+
 function writeRepoLayoutConfig(layout) {
   const configPath = path.join(process.cwd(), '_bmad', 'bmm', 'config.yaml');
   try {
@@ -522,8 +535,8 @@ function writeRepoLayoutConfig(layout) {
       content = writeConfigField(content, 'sprint_backend', 'jira');
       content = writeConfigField(content, 'jira_url', layout.sprintManagement.jiraUrl);
       content = writeConfigField(content, 'jira_project_key', layout.sprintManagement.jiraProjectKey);
-      const planningArtifacts = kbPath === '.' ? '_bmad-output/planning-artifacts' : kbPath;
-      const implArtifacts = '_bmad-output/implementation-artifacts';
+      const planningArtifacts = kbPath === '.' ? canonicalArtifactPath('planning-artifacts') : kbPath;
+      const implArtifacts = canonicalArtifactPath('implementation-artifacts');
       content = writeConfigField(content, 'planning_artifacts', planningArtifacts);
       content = writeConfigField(content, 'implementation_artifacts', implArtifacts);
       fs.writeFileSync(configPath, content, 'utf-8');
@@ -534,8 +547,8 @@ function writeRepoLayoutConfig(layout) {
       const spPath = spPortable.portable;
       content = writeConfigField(content, 'sprint_backend', 'file-system');
       content = writeConfigField(content, 'sprint_management_path', spPath);
-      const planningArtifacts = kbPath === '.' ? '_bmad-output/planning-artifacts' : kbPath;
-      const implArtifacts = spPath === '.' ? '_bmad-output/implementation-artifacts' : spPath;
+      const planningArtifacts = kbPath === '.' ? canonicalArtifactPath('planning-artifacts') : kbPath;
+      const implArtifacts = spPath === '.' ? canonicalArtifactPath('implementation-artifacts') : spPath;
       content = writeConfigField(content, 'planning_artifacts', planningArtifacts);
       content = writeConfigField(content, 'implementation_artifacts', implArtifacts);
       fs.writeFileSync(configPath, content, 'utf-8');
@@ -831,14 +844,26 @@ async function collectRepoLayout(flags, existingLayout = null) {
  * break without them. Retired modules (currently only `wds`) are filtered
  * out unconditionally.
  */
-async function selectBmadModules({ bmadModulesFlag, bmadModulesPrompt }) {
+async function selectBmadModules({ bmadModulesFlag, bmadModulesPrompt, projectRoot } = {}) {
   const installable = bmad.getInstallableBmadModules().filter(m => !m.retired);
+  const root = projectRoot || process.cwd();
+
+  // Bug 27.13 — persist the resolved selection so a deselection sticks across
+  // future installs/reconfigures that do not re-pass --bmad-modules.
+  const persist = (modules) => {
+    try {
+      setBmadModules(root, modules);
+    } catch (err) {
+      console.warn(chalk.yellow(`  Warning: could not persist BMAD module selection: ${err.message}`));
+    }
+    return modules;
+  };
 
   // Branch 1: explicit CSV — validate + use as-is.
   if (bmadModulesFlag) {
     const requested = bmadModulesFlag.split(',').map(s => s.trim()).filter(Boolean);
     try {
-      return bmad.resolveBmadModules({ requested, available: installable });
+      return persist(bmad.resolveBmadModules({ requested, available: installable }));
     } catch (err) {
       console.error(chalk.red(`Error: ${err.message}`));
       process.exit(1);
@@ -872,11 +897,25 @@ async function selectBmadModules({ bmadModulesFlag, bmadModulesPrompt }) {
 
     // Belt-and-suspenders: force bmm back in if the user managed to uncheck
     // it despite the (required) tag.
-    return bmad.resolveBmadModules({ requested: chosenModules, available: installable });
+    return persist(bmad.resolveBmadModules({ requested: chosenModules, available: installable }));
+  }
+
+  // Branch 3: no flag → use the persisted selection from a prior run if present
+  // (bug 27.13 — a previous deselection must survive); otherwise fall back to
+  // the original "install every available module" default. The persisted set is
+  // intersected with the currently-installable set so a since-retired module
+  // does not resurface, and bmm is force-included via resolveBmadModules.
+  const persisted = getBmadModules(root);
+  if (persisted && persisted.length > 0) {
+    const availableIds = new Set(installable.map(m => m.id));
+    const stillInstallable = persisted.filter(id => availableIds.has(id));
+    try {
+      return persist(bmad.resolveBmadModules({ requested: stillInstallable, available: installable }));
+    } catch {
+      // If the persisted set somehow fails validation, fall through to default.
+    }
   }
-
-  // Branch 3: no flag → install everything available.
-  return installable.map(m => m.id);
+  return persist(installable.map(m => m.id));
 }
 
 // --- Install wizard ---
@@ -1167,6 +1206,7 @@ async function installWizard(preselectedSkill, preselectedAgents, customPath, fo
       const bmadModules = await selectBmadModules({
         bmadModulesFlag,
         bmadModulesPrompt,
+        projectRoot: process.cwd(),
       });
 
       if (!bmadInstalled) {
@@ -1314,6 +1354,20 @@ async function installWizard(preselectedSkill, preselectedAgents, customPath, fo
     }
   }
 
+  // Bug 27.16 — if BMAD populated the shared `.agents/skills` dir but no
+  // .agents-targeting agent (copilot/kilocode/roo-code) was selected, the
+  // standalone catalog + MANIFEST.yaml were never written there. Backfill them
+  // so the dir is never BMAD-only without the MANIFEST.yaml the instruction
+  // block points agents at. No-op when an .agents agent was selected or no
+  // shared dir exists.
+  if (installScope === 'project') {
+    try {
+      await reconcileAgentsSharedSkills(process.cwd(), selectedAgentIds, installScope);
+    } catch (err) {
+      console.log(chalk.yellow(` .agents/skills reconciliation skipped: ${err.message}`));
+    }
+  }
+
   // Step 6: Update project-context.md with repo layout section (after skills installed project-context.md)
   if (installScope === 'project') {
     const outputPath = path.join(process.cwd(), '_bmad-output', 'project-context.md');
@@ -1683,4 +1737,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { parseFlags, collectRepoLayout, readExistingLayout, writeRepoLayoutConfig, writeProjectLayoutYaml, writeConfigField, normalizePath, toPortablePath, resolveStoredPath, ciCloneIfNeeded, showCurrentLayout, handleConfigLayout, yamlEscapeValue };
+module.exports = { parseFlags, selectBmadModules, collectRepoLayout, readExistingLayout, writeRepoLayoutConfig, writeProjectLayoutYaml, writeConfigField, normalizePath, toPortablePath, resolveStoredPath, ciCloneIfNeeded, showCurrentLayout, handleConfigLayout, yamlEscapeValue };

package/docs/architecture.md

@@ -195,6 +195,24 @@ skills/<skill-name>/
 - **Modern C++** (6): cpp-memory-handling, cpp-robust-interfaces, cpp-modern-composition, cpp-const-correctness, cpp-concurrency-safety, cmake-best-practices
 - **Architecture** (5): logging-best-practices, opentelemetry-best-practices, vercel-react-best-practices, git-workflow-skill, self-signed-cert
 
+### 3.6 BMAD Cache & Offline Self-Containment (build-time)
+
+**Responsibility**: Pre-vendor BMAD's external modules so installs never touch the network.
+
+ma-agents bundles bmad-method as an npm dependency **and** pre-clones BMAD's external modules (`tea`, `bmb`, `cis`, `gds`) into `lib/bmad-cache/` at build time via `npm run build:bmad-cache` ([scripts/build-bmad-cache.js](../scripts/build-bmad-cache.js)). This is what lets `npx ma-agents install` run fully offline in air-gapped environments (NFR2/NFR50/NFR54) — the npm tarball already contains every module bmad-method would otherwise `git clone` from GitHub at install time.
+
+**Module discovery**: the builder reads BMAD's bundled module registry to learn which external modules to clone. **The registry source has moved across BMAD versions** and the reader must track it:
+
+| BMAD version | Module registry source | Format |
+|--------------|------------------------|--------|
+| ≤ 6.2.x | `tools/cli/external-official-modules.yaml` | YAML |
+| 6.3.0 – 6.6.x | `tools/installer/modules/registry-fallback.yaml` | YAML |
+| 6.8.0+ | `bmad-modules.yaml` (bmad-method **package root**) | YAML (`modules:` map; the in-package `registry-fallback.yaml` was retired in 6.7.0) |
+
+The registry has stayed **YAML** throughout — only its path has moved. (`tools/installer/modules/official-modules.js` is unchanged loader code that reads this YAML; it does not contain the module list.) Modules are classified by a `type` field: `type: bmad-org` modules are bundled (**tea, bmb, cis, gds, wds**) and `type: experimental` modules are excluded (currently `automator`). `bmm`/`core` are built-in (loaded from bmad-method's local `module.yaml`, absent from the registry) and are never cloned. The reader for the current pin and its fail-loud contract are defined by Architecture Decision **P5-5** (Epic 27) in `_bmad-output/planning-artifacts/architecture.md`. A companion build step, `npm run build:plugin` ([scripts/build-plugin.js](../scripts/build-plugin.js)), assembles the ma-agents extension plugin bundle (`lib/bmad-extension-plugin/`) deterministically; a CI Bundle Drift Guard enforces that the committed bundle matches a fresh build.
+
+> **Maintenance note:** because the registry path has now moved twice (YAML→YAML→YAML at three locations), the cache builder fails loud — if the resolved `type: bmad-org` set is smaller than the known bundled set, or no module source is found, it exits non-zero rather than producing a thin/empty cache, so a future BMAD registry move surfaces at build time, not as a broken air-gapped install.
+
 ## 4. Data Flow
 
 ### 4.1 Install Flow

package/lib/bmad-cache/bmb/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "bmad-builder",
       "source": "./",
       "description": "Build AI agents, workflows, and modules from a conversation. Four skills — Agent Builder, Workflow Builder, Module Builder, and Setup — guide you from idea to production-ready skill structure with built-in quality optimization. Part of the BMad Method ecosystem.",
-      "version": "1.6.0",
+      "version": "1.8.0",
       "author": {
         "name": "Brian (BMad) Madison"
       },

package/lib/bmad-cache/bmb/_git_preserved/hooks/commit-msg.sample

@@ -15,10 +15,60 @@
 # SOB=$(git var GIT_AUTHOR_IDENT | sed -n 's/^\(.*>\).*$/Signed-off-by: \1/p')
 # grep -qs "^$SOB" "$1" || echo "$SOB" >> "$1"
 
-# This example catches duplicate Signed-off-by lines.
+# This example catches duplicate Signed-off-by lines and messages that
+# would confuse 'git am'.
+
+ret=0
 
 test "" = "$(grep '^Signed-off-by: ' "$1" |
 	 sort | uniq -c | sed -e '/^[ 	]*1[ 	]/d')" || {
 	echo >&2 Duplicate Signed-off-by lines.
-	exit 1
+	ret=1
 }
+
+comment_re="$(
+	{
+		git config --get-regexp "^core\.comment(char|string)\$" ||
+			echo '#'
+	} | sed -n -e '
+		${
+			s/^[^ ]* //
+			s|[][*./\]|\\&|g
+			s/^auto$/[#;@!$%^&|:]/
+			p
+		}'
+)"
+scissors_line="^${comment_re} -\{8,\} >8 -\{8,\}\$"
+comment_line="^${comment_re}.*"
+blank_line='^[ 	]*$'
+# Disallow lines starting with "diff -" or "Index: " in the body of the
+# message. Stop looking if we see a scissors line.
+line="$(sed -n -e "
+	# Skip comments and blank lines at the start of the file.
+	/${scissors_line}/q
+	/${comment_line}/d
+	/${blank_line}/d
+	# The first paragraph will become the subject header so
+	# does not need to be checked.
+	: subject
+	n
+	/${scissors_line}/q
+	/${blank_line}/!b subject
+	# Check the body of the message for problematic
+	# prefixes.
+	: body
+	n
+	/${scissors_line}/q
+	/${comment_line}/b body
+	/^diff -/{p;q;}
+	/^Index: /{p;q;}
+	b body
+	" "$1")"
+if test -n "$line"
+then
+	echo >&2 "Message contains a diff that will confuse 'git am'."
+	echo >&2 "To fix this indent the diff."
+	ret=1
+fi
+
+exit $ret

package/lib/bmad-cache/bmb/_git_preserved/hooks/fsmonitor-watchman.sample

@@ -29,8 +29,6 @@ if ($version ne 2) {
 
 my $git_work_tree = get_working_dir();
 
-my $retry = 1;
-
 my $json_pkg;
 eval {
 	require JSON::XS;
@@ -123,8 +121,7 @@ sub watchman_query {
 sub is_work_tree_watched {
 	my ($output) = @_;
 	my $error = $output->{error};
-	if ($retry > 0 and $error and $error =~ m/unable to resolve root .* directory (.*) is not watched/) {
-		$retry--;
+	if ($error and $error =~ m/unable to resolve root .* directory (.*) is not watched/) {
 		my $response = qx/watchman watch "$git_work_tree"/;
 		die "Failed to make watchman watch '$git_work_tree'.\n" .
 		    "Falling back to scanning...\n" if $? != 0;
@@ -142,15 +139,12 @@ sub is_work_tree_watched {
 		# Watchman query just to get it over with now so we won't pay
 		# the cost in git to look up each individual file.
 		my $o = watchman_clock();
-		$error = $output->{error};
+		$error = $o->{error};
 
 		die "Watchman: $error.\n" .
 		"Falling back to scanning...\n" if $error;
 
 		output_result($o->{clock}, ("/"));
-		$last_update_token = $o->{clock};
-
-		eval { launch_watchman() };
 		return 0;
 	}
 

package/lib/bmad-cache/bmb/_git_preserved/packed-refs

@@ -1,2 +1,2 @@
 # pack-refs with: peeled fully-peeled sorted 
-86033fc9aeae2ca6d52c7cdb675c1f4bf17fc1c1 refs/remotes/origin/main
+7cfa7711778f04c5df56f7ae895fabc942fd920c refs/remotes/origin/main

package/lib/bmad-cache/bmb/_git_preserved/refs/heads/main

@@ -1 +1 @@
-86033fc9aeae2ca6d52c7cdb675c1f4bf17fc1c1
+7cfa7711778f04c5df56f7ae895fabc942fd920c

package/lib/bmad-cache/bmb/_git_preserved/shallow

@@ -1 +1 @@
-86033fc9aeae2ca6d52c7cdb675c1f4bf17fc1c1
+7cfa7711778f04c5df56f7ae895fabc942fd920c

package/lib/bmad-cache/bmb/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "bmad-builder",
-  "version": "1.7.0",
+  "version": "1.8.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "bmad-builder",
-      "version": "1.7.0",
+      "version": "1.8.1",
       "license": "MIT",
       "devDependencies": {
         "@astrojs/sitemap": "^3.6.0",

package/lib/bmad-cache/bmb/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-builder",
-  "version": "1.7.0",
+  "version": "1.8.1",
   "private": true,
   "description": "A BMad Core expansion module that guides users through the creation of Modules Workflow and Agents",
   "keywords": [

package/lib/bmad-cache/bmb/samples/bmad-agent-dream-weaver/assets/module-help.csv

@@ -1,4 +1,4 @@
-module,skill,display-name,menu-code,description,action,args,phase,after,before,required,output-location,outputs
+module,skill,display-name,menu-code,description,action,args,phase,preceded-by,followed-by,required,output-location,outputs
 Dream Weaver,bmad-agent-dream-weaver,Dream Capture,DL,"Capture and log a dream through guided conversation.",dream-log,,anytime,,,false,,journal entry
 Dream Weaver,bmad-agent-dream-weaver,Dream Interpretation,DI,"Analyze a dream for symbolism, meaning, and personal connections.",dream-interpret,,anytime,dw:dream-log,,false,,interpretation
 Dream Weaver,bmad-agent-dream-weaver,Recall Training,RT,"Dream recall exercises and progress tracking.",recall-training,,anytime,,,false,,coaching updates

package/lib/bmad-cache/bmb/samples/bmad-agent-dream-weaver/scripts/merge-config.py

@@ -339,9 +339,42 @@ def write_config(config: dict, config_path: str, verbose: bool = False) -> None:
         )
 
 
+def reject_unresolved_paths(named_paths: list[tuple[str, str]]) -> None:
+    """Exit with a clear error if any path argument still contains the literal
+    ``{project-root}`` token. That token is meaningful only inside config
+    values; filesystem path arguments must be resolved by the caller. Failing
+    loudly here prevents silently creating a junk ``{project-root}/`` directory.
+    """
+    for name, value in named_paths:
+        if value and "{project-root}" in value:
+            print(
+                json.dumps(
+                    {
+                        "status": "error",
+                        "error": (
+                            f"Unresolved '{{project-root}}' token in {name} path: {value!r}. "
+                            "Resolve '{project-root}' to the actual project root before running "
+                            "this script — it is a filesystem path, not a config value."
+                        ),
+                    },
+                    indent=2,
+                ),
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+
 def main():
     args = parse_args()
 
+    reject_unresolved_paths(
+        [
+            ("--config-path", args.config_path),
+            ("--user-config-path", args.user_config_path),
+            ("--legacy-dir", args.legacy_dir),
+        ]
+    )
+
     # Load inputs
     module_yaml = load_yaml_file(args.module_yaml)
     if not module_yaml:

package/lib/bmad-cache/bmb/samples/bmad-agent-dream-weaver/scripts/merge-help-csv.py

@@ -139,9 +139,37 @@ def cleanup_legacy_csvs(
     return deleted
 
 
+def reject_unresolved_paths(named_paths: list[tuple[str, str]]) -> None:
+    """Exit with a clear error if any path argument still contains the literal
+    ``{project-root}`` token. That token is meaningful only inside config
+    values; filesystem path arguments must be resolved by the caller. Failing
+    loudly here prevents silently creating a junk ``{project-root}/`` directory.
+    """
+    for name, value in named_paths:
+        if value and "{project-root}" in value:
+            print(
+                json.dumps(
+                    {
+                        "status": "error",
+                        "error": (
+                            f"Unresolved '{{project-root}}' token in {name} path: {value!r}. "
+                            "Resolve '{project-root}' to the actual project root before running "
+                            "this script — it is a filesystem path, not a config value."
+                        ),
+                    },
+                    indent=2,
+                )
+            )
+            sys.exit(1)
+
+
 def main():
     args = parse_args()
 
+    reject_unresolved_paths(
+        [("--target", args.target), ("--legacy-dir", args.legacy_dir)]
+    )
+
     # Read source entries
     source_header, source_rows = read_csv_rows(args.source)
     if not source_rows:

package/lib/bmad-cache/bmb/samples/sample-module-setup/assets/module-help.csv

@@ -1,4 +1,4 @@
-module,skill,display-name,menu-code,description,action,args,phase,after,before,required,output-location,outputs
+module,skill,display-name,menu-code,description,action,args,phase,preceded-by,followed-by,required,output-location,outputs
 BMad Samples,sample-module-setup,Setup Samples Module,SS,"Install or update BMad Samples module config and help entries.",configure,"{-H: headless mode}|{inline values: skip prompts with provided values}",anytime,,,false,{project-root}/_bmad,config.yaml and config.user.yaml
 BMad Samples,bmad-agent-code-coach,Code Coaching,TC,"Personal coding coaching and mentoring — code review, pair programming, and learning paths.",activate,,anytime,,,false,,coaching session
 BMad Samples,bmad-agent-creative-muse,Creative Muse,TM,"Creative brainstorming, problem-solving, and storytelling companion.",activate,,anytime,,,false,,creative session

package/lib/bmad-cache/bmb/samples/sample-module-setup/scripts/cleanup-legacy.py

@@ -197,9 +197,37 @@ def cleanup_directories(
     return removed, not_found, total_files
 
 
+def reject_unresolved_paths(named_paths: list[tuple[str, str]]) -> None:
+    """Exit with a clear error if any path argument still contains the literal
+    ``{project-root}`` token. That token is meaningful only inside config
+    values; filesystem path arguments must be resolved by the caller. Failing
+    loudly here prevents silently operating on a junk ``{project-root}/`` directory.
+    """
+    for name, value in named_paths:
+        if value and "{project-root}" in value:
+            print(
+                json.dumps(
+                    {
+                        "status": "error",
+                        "error": (
+                            f"Unresolved '{{project-root}}' token in {name} path: {value!r}. "
+                            "Resolve '{project-root}' to the actual project root before running "
+                            "this script — it is a filesystem path, not a config value."
+                        ),
+                    },
+                    indent=2,
+                )
+            )
+            sys.exit(1)
+
+
 def main():
     args = parse_args()
 
+    reject_unresolved_paths(
+        [("--bmad-dir", args.bmad_dir), ("--skills-dir", args.skills_dir)]
+    )
+
     bmad_dir = args.bmad_dir
     module_code = args.module_code
 

package/lib/bmad-cache/bmb/samples/sample-module-setup/scripts/merge-config.py

@@ -339,9 +339,42 @@ def write_config(config: dict, config_path: str, verbose: bool = False) -> None:
         )
 
 
+def reject_unresolved_paths(named_paths: list[tuple[str, str]]) -> None:
+    """Exit with a clear error if any path argument still contains the literal
+    ``{project-root}`` token. That token is meaningful only inside config
+    values; filesystem path arguments must be resolved by the caller. Failing
+    loudly here prevents silently creating a junk ``{project-root}/`` directory.
+    """
+    for name, value in named_paths:
+        if value and "{project-root}" in value:
+            print(
+                json.dumps(
+                    {
+                        "status": "error",
+                        "error": (
+                            f"Unresolved '{{project-root}}' token in {name} path: {value!r}. "
+                            "Resolve '{project-root}' to the actual project root before running "
+                            "this script — it is a filesystem path, not a config value."
+                        ),
+                    },
+                    indent=2,
+                ),
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+
 def main():
     args = parse_args()
 
+    reject_unresolved_paths(
+        [
+            ("--config-path", args.config_path),
+            ("--user-config-path", args.user_config_path),
+            ("--legacy-dir", args.legacy_dir),
+        ]
+    )
+
     # Load inputs
     module_yaml = load_yaml_file(args.module_yaml)
     if not module_yaml:

package/lib/bmad-cache/bmb/samples/sample-module-setup/scripts/merge-help-csv.py

@@ -139,9 +139,37 @@ def cleanup_legacy_csvs(
     return deleted
 
 
+def reject_unresolved_paths(named_paths: list[tuple[str, str]]) -> None:
+    """Exit with a clear error if any path argument still contains the literal
+    ``{project-root}`` token. That token is meaningful only inside config
+    values; filesystem path arguments must be resolved by the caller. Failing
+    loudly here prevents silently creating a junk ``{project-root}/`` directory.
+    """
+    for name, value in named_paths:
+        if value and "{project-root}" in value:
+            print(
+                json.dumps(
+                    {
+                        "status": "error",
+                        "error": (
+                            f"Unresolved '{{project-root}}' token in {name} path: {value!r}. "
+                            "Resolve '{project-root}' to the actual project root before running "
+                            "this script — it is a filesystem path, not a config value."
+                        ),
+                    },
+                    indent=2,
+                )
+            )
+            sys.exit(1)
+
+
 def main():
     args = parse_args()
 
+    reject_unresolved_paths(
+        [("--target", args.target), ("--legacy-dir", args.legacy_dir)]
+    )
+
     # Read source entries
     source_header, source_rows = read_csv_rows(args.source)
     if not source_rows:

package/lib/bmad-cache/bmb/skills/bmad-bmb-setup/assets/module-help.csv

@@ -1,4 +1,4 @@
-module,skill,display-name,menu-code,description,action,args,phase,after,before,required,output-location,outputs
+module,skill,display-name,menu-code,description,action,args,phase,preceded-by,followed-by,required,output-location,outputs
 BMad Builder,bmad-bmb-setup,Setup Builder Module,SB,"Install or update BMad Builder module config and help entries.",configure,"{-H: headless mode}|{inline values: skip prompts with provided values}",anytime,,,false,{project-root}/_bmad,config.yaml and config.user.yaml
 BMad Builder,bmad-agent-builder,Build an Agent,BA,"Create, edit, or rebuild an agent skill through conversational discovery.",build-process,"{-H: headless mode}|{description: initial agent concept}|{path: existing agent to edit or rebuild}",anytime,,bmad-agent-builder:quality-analysis,false,bmad_builder_output_folder,agent skill
 BMad Builder,bmad-agent-builder,Analyze an Agent,AA,"Run quality analysis on an existing agent — structure, cohesion, prompt craft, and enhancement opportunities.",quality-analysis,"{-H: headless mode}|{path: agent to analyze}",anytime,bmad-agent-builder:build-process,,false,bmad_builder_reports,quality report

package/lib/bmad-cache/bmb/skills/bmad-bmb-setup/scripts/cleanup-legacy.py

@@ -197,9 +197,37 @@ def cleanup_directories(
     return removed, not_found, total_files
 
 
+def reject_unresolved_paths(named_paths: list[tuple[str, str]]) -> None:
+    """Exit with a clear error if any path argument still contains the literal
+    ``{project-root}`` token. That token is meaningful only inside config
+    values; filesystem path arguments must be resolved by the caller. Failing
+    loudly here prevents silently operating on a junk ``{project-root}/`` directory.
+    """
+    for name, value in named_paths:
+        if value and "{project-root}" in value:
+            print(
+                json.dumps(
+                    {
+                        "status": "error",
+                        "error": (
+                            f"Unresolved '{{project-root}}' token in {name} path: {value!r}. "
+                            "Resolve '{project-root}' to the actual project root before running "
+                            "this script — it is a filesystem path, not a config value."
+                        ),
+                    },
+                    indent=2,
+                )
+            )
+            sys.exit(1)
+
+
 def main():
     args = parse_args()
 
+    reject_unresolved_paths(
+        [("--bmad-dir", args.bmad_dir), ("--skills-dir", args.skills_dir)]
+    )
+
     bmad_dir = args.bmad_dir
     module_code = args.module_code
 

package/lib/bmad-cache/bmb/skills/bmad-bmb-setup/scripts/merge-config.py

@@ -339,9 +339,42 @@ def write_config(config: dict, config_path: str, verbose: bool = False) -> None:
         )
 
 
+def reject_unresolved_paths(named_paths: list[tuple[str, str]]) -> None:
+    """Exit with a clear error if any path argument still contains the literal
+    ``{project-root}`` token. That token is meaningful only inside config
+    values; filesystem path arguments must be resolved by the caller. Failing
+    loudly here prevents silently creating a junk ``{project-root}/`` directory.
+    """
+    for name, value in named_paths:
+        if value and "{project-root}" in value:
+            print(
+                json.dumps(
+                    {
+                        "status": "error",
+                        "error": (
+                            f"Unresolved '{{project-root}}' token in {name} path: {value!r}. "
+                            "Resolve '{project-root}' to the actual project root before running "
+                            "this script — it is a filesystem path, not a config value."
+                        ),
+                    },
+                    indent=2,
+                ),
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+
 def main():
     args = parse_args()
 
+    reject_unresolved_paths(
+        [
+            ("--config-path", args.config_path),
+            ("--user-config-path", args.user_config_path),
+            ("--legacy-dir", args.legacy_dir),
+        ]
+    )
+
     # Load inputs
     module_yaml = load_yaml_file(args.module_yaml)
     if not module_yaml: