ma-agents 3.13.0 → 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/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.13.0",
+      "version": "3.13.1",
       "author": {
         "name": "Alon Mayaffit"
       },

package/lib/bmad.js

@@ -278,17 +278,34 @@ function ensurePluginStageGitignoredForProject(projectRoot) {
         console.warn(chalk.yellow(`  Warning: could not load installer for gitignore policy: ${err.message}`));
         return;
     }
-    if (typeof installer.ensurePluginStageIgnored !== 'function') return;
-    try {
-        installer.ensurePluginStageIgnored(projectRoot);
-    } catch (err) {
-        // EACCES on read-only `.gitignore`, EROFS on read-only filesystem, etc.
-        // Logged so the operator can fix it manually; never fatal to the install.
-        console.warn(
-            chalk.yellow(
-                `  Warning: could not update ${path.join(projectRoot, '.gitignore')} with plugin-stage entry: ${err.message}`
-            )
-        );
+    if (typeof installer.ensurePluginStageIgnored === 'function') {
+        try {
+            installer.ensurePluginStageIgnored(projectRoot);
+        } catch (err) {
+            // EACCES on read-only `.gitignore`, EROFS on read-only filesystem, etc.
+            // Logged so the operator can fix it manually; never fatal to the install.
+            console.warn(
+                chalk.yellow(
+                    `  Warning: could not update ${path.join(projectRoot, '.gitignore')} with plugin-stage entry: ${err.message}`
+                )
+            );
+        }
+    }
+
+    // Bug 27.11 — also ensure the regenerated, installer-managed `_bmad/` tree is
+    // gitignored. Same project-root contract and same non-fatal failure policy as
+    // the plugin-stage entry above. `_bmad-output/` is intentionally left tracked
+    // (see ensureBmadOutputTracked) and is not matched by these patterns.
+    if (typeof installer.ensureBmadDirIgnored === 'function') {
+        try {
+            installer.ensureBmadDirIgnored(projectRoot);
+        } catch (err) {
+            console.warn(
+                chalk.yellow(
+                    `  Warning: could not update ${path.join(projectRoot, '.gitignore')} with _bmad/ entry: ${err.message}`
+                )
+            );
+        }
     }
 }
 
@@ -847,6 +864,11 @@ async function installBmad(modules = ['bmm', 'bmb'], tools = [], projectRoot = p
     try {
         runCommand(command, { cwd: projectRoot, env: buildChildSpawnEnv() });
         bmadInvokeSucceeded = true;
+        // Bug 27.14 — repair any module artifact path that upstream's
+        // suffix-match output-folder resolution contaminated (e.g. gds paths
+        // pinned to bmb's "skills" instead of the chosen output folder). Runs
+        // after bmad-method writes the config and before downstream consumers.
+        normalizeModuleOutputFolders(projectRoot);
         // F1a — on-prem persona phase-prefix pass. Runs BEFORE
         // deployMethodology so a methodology-deploy failure doesn't prevent
         // the prefix from being applied (they are independent concerns).
@@ -953,6 +975,10 @@ async function runMigration(modules, tools, projectRoot, force, { userName, comm
         return false;
     }
 
+    // Bug 27.14 — repair contaminated module artifact paths on the migration
+    // path too (same upstream suffix-match resolution applies to updates).
+    normalizeModuleOutputFolders(projectRoot);
+
     // Step 3: Merge user customizations
     if (backedUpFiles.length > 0) {
         console.log(chalk.cyan('  Step 3/4: Merging user customizations...'));
@@ -1808,6 +1834,237 @@ function readCanonicalBmadConfig(projectRoot) {
     }
 }
 
+// ── Bug 27.14 — output-folder propagation normalization ──────────────────────
+//
+// Upstream bmad-method's resolveConfigValue (official-modules.js) resolves the
+// `{output_folder}` token via a `endsWith('_output_folder')` suffix match over
+// all collected answers. When bmb (answer key `bmb_..._output_folder` = "skills")
+// and gds are co-installed, gds's `{output_folder}` resolves alphabetically to
+// bmb's "skills" value, so gds artifact paths become `{project-root}/skills/...`
+// instead of `{project-root}/_bmad-output/...`.
+//
+// ma-agents owns no part of that resolution (it lives in vendored node_modules),
+// so this is a post-install WORK-AROUND: after bmad-method writes the config,
+// re-read `[core] output_folder` and rewrite any contaminated module artifact
+// path back onto the canonical output folder. We deliberately scope the rewrite
+// to the well-known core artifact keys so we never touch a module's INTENTIONAL
+// own-folder values (e.g. bmb's `bmad_builder_output_folder = ".../skills"` or
+// wds's `design_artifacts = ".../design-artifacts"`).
+//
+// Upstream follow-up (do NOT edit node_modules here): patch resolveConfigValue
+// to require an exact `output_folder` / `core_output_folder` key instead of the
+// `endsWith` suffix match. Tracked as an upstream follow-up.
+
+// Artifact keys that must always live under `[core] output_folder`. These are
+// the canonical bmm/gds planning+implementation+architecture artifact keys plus
+// tea's test_artifacts. Module-specific own-folder keys (bmb_*_output_folder,
+// design_artifacts, project_knowledge, *_output sub-paths) are intentionally
+// excluded.
+const OUTPUT_FOLDER_ARTIFACT_KEYS = [
+    'planning_artifacts',
+    'architecture_artifacts',
+    'implementation_artifacts',
+    'test_artifacts',
+];
+
+/**
+ * Given an artifact path value and the canonical output folder, return a
+ * corrected value if the path's output-folder segment differs from the
+ * canonical one, or `null` if no change is needed.
+ *
+ * Handles both conventions:
+ *   - `{project-root}/<seg>/<suffix...>`  (config.toml style)
+ *   - `<seg>/<suffix...>`                 (config.yaml stripped style)
+ *
+ * The leading `<seg>` (the first path segment after an optional `{project-root}/`
+ * prefix) is the resolved output folder; if it !== `outputFolder` it is rewritten.
+ * Only single-segment output folders are handled (the bmad default), which covers
+ * the observed `skills` vs `_bmad-output` contamination.
+ */
+function correctArtifactPath(value, outputFolder) {
+    if (typeof value !== 'string' || !value) return null;
+    const ROOT = '{project-root}/';
+    let prefix = '';
+    let rest = value;
+    if (rest.startsWith(ROOT)) {
+        prefix = ROOT;
+        rest = rest.slice(ROOT.length);
+    }
+    const slash = rest.indexOf('/');
+    if (slash === -1) return null; // no segment/suffix split — leave as-is
+    const seg = rest.slice(0, slash);
+    const suffix = rest.slice(slash); // includes leading '/'
+    if (seg === outputFolder) return null; // already canonical
+    return `${prefix}${outputFolder}${suffix}`;
+}
+
+/**
+ * Rewrite contaminated artifact paths inside `_bmad/config.toml`. Returns the
+ * number of lines changed. Uses line-based editing (no TOML dependency) so we
+ * preserve comments, ordering, and formatting exactly.
+ */
+function normalizeTomlOutputFolders(tomlPath, outputFolder) {
+    if (!fs.existsSync(tomlPath)) return 0;
+    let raw;
+    try {
+        raw = fs.readFileSync(tomlPath, 'utf-8');
+    } catch {
+        return 0;
+    }
+    const usesCrlf = /\r\n/.test(raw);
+    const eol = usesCrlf ? '\r\n' : '\n';
+    const lines = raw.split(/\r?\n/);
+    let changed = 0;
+    let inModuleSection = false;
+
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const sectionMatch = line.match(/^\s*\[([^\]]+)\]\s*$/);
+        if (sectionMatch) {
+            const section = sectionMatch[1].trim();
+            inModuleSection = section.startsWith('modules.');
+            continue;
+        }
+        if (!inModuleSection) continue;
+
+        // key = "value"  (only quoted string values are artifact paths)
+        const kvMatch = line.match(/^(\s*)([A-Za-z0-9_]+)(\s*=\s*)"([^"]*)"(\s*(?:#.*)?)$/);
+        if (!kvMatch) continue;
+        const [, indent, key, eq, val, trailer] = kvMatch;
+        if (!OUTPUT_FOLDER_ARTIFACT_KEYS.includes(key)) continue;
+        const corrected = correctArtifactPath(val, outputFolder);
+        if (corrected === null) continue;
+        lines[i] = `${indent}${key}${eq}"${corrected}"${trailer}`;
+        changed++;
+    }
+
+    if (changed > 0) {
+        fs.writeFileSync(tomlPath, lines.join(eol), 'utf-8');
+    }
+    return changed;
+}
+
+/**
+ * Rewrite contaminated artifact paths inside a per-module `_bmad/<mod>/config.yaml`.
+ * Returns the number of keys changed. Uses js-yaml so we keep schema fidelity.
+ */
+function normalizeYamlOutputFolders(yamlPath, outputFolder) {
+    if (!fs.existsSync(yamlPath)) return 0;
+    let raw;
+    try {
+        raw = fs.readFileSync(yamlPath, 'utf-8');
+    } catch {
+        return 0;
+    }
+    let doc;
+    try {
+        doc = yaml.parse(raw);
+    } catch {
+        return 0;
+    }
+    if (!doc || typeof doc !== 'object') return 0;
+
+    let changed = 0;
+    for (const key of OUTPUT_FOLDER_ARTIFACT_KEYS) {
+        if (typeof doc[key] !== 'string') continue;
+        const corrected = correctArtifactPath(doc[key], outputFolder);
+        if (corrected === null) continue;
+        doc[key] = corrected;
+        changed++;
+    }
+
+    if (changed > 0) {
+        // Preserve the leading comment header (everything up to the first
+        // non-comment, non-blank line) so the "Generated by BMAD installer"
+        // banner survives the rewrite.
+        const headerLines = [];
+        for (const l of raw.split(/\r?\n/)) {
+            if (l.trim() === '' || l.trimStart().startsWith('#')) {
+                headerLines.push(l);
+            } else {
+                break;
+            }
+        }
+        const header = headerLines.length > 0 ? headerLines.join('\n') + '\n' : '';
+        fs.writeFileSync(yamlPath, header + yaml.stringify(doc), 'utf-8');
+    }
+    return changed;
+}
+
+/**
+ * Bug 27.14 — post-install pass that re-points any contaminated module artifact
+ * path at the canonical `[core] output_folder`. Reads the output folder from
+ * `_bmad/config.toml` (the install-owned source of truth), then normalizes both
+ * `_bmad/config.toml` and every `_bmad/<mod>/config.yaml`.
+ *
+ * Idempotent and non-fatal: a second run finds nothing to change, and any I/O
+ * error is logged and swallowed (config normalization must never abort an
+ * otherwise-green install).
+ *
+ * @param {string} projectRoot - Absolute path to the project root.
+ * @returns {number} Total number of artifact paths rewritten (for tests/logging).
+ */
+function normalizeModuleOutputFolders(projectRoot) {
+    if (typeof projectRoot !== 'string' || !projectRoot) return 0;
+    const tomlPath = path.join(projectRoot, BMAD_DIR, 'config.toml');
+    if (!fs.existsSync(tomlPath)) return 0;
+
+    let tomlRaw;
+    try {
+        tomlRaw = fs.readFileSync(tomlPath, 'utf-8');
+    } catch {
+        return 0;
+    }
+
+    // Extract `[core] output_folder = "..."`. Only the value inside the [core]
+    // section counts; module sections may carry their own output_folder-like keys.
+    let outputFolder = null;
+    let inCore = false;
+    for (const line of tomlRaw.split(/\r?\n/)) {
+        const section = line.match(/^\s*\[([^\]]+)\]\s*$/);
+        if (section) {
+            inCore = section[1].trim() === 'core';
+            continue;
+        }
+        if (!inCore) continue;
+        const kv = line.match(/^\s*output_folder\s*=\s*"([^"]*)"/);
+        if (kv) {
+            outputFolder = kv[1].trim();
+            break;
+        }
+    }
+    if (!outputFolder) return 0; // nothing canonical to normalize against
+
+    let total = 0;
+    try {
+        total += normalizeTomlOutputFolders(tomlPath, outputFolder);
+
+        // Walk each `_bmad/<mod>/config.yaml`.
+        const bmadDir = path.join(projectRoot, BMAD_DIR);
+        let entries = [];
+        try {
+            entries = fs.readdirSync(bmadDir, { withFileTypes: true });
+        } catch {
+            entries = [];
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory()) continue;
+            const cfg = path.join(bmadDir, entry.name, 'config.yaml');
+            total += normalizeYamlOutputFolders(cfg, outputFolder);
+        }
+    } catch (err) {
+        console.warn(chalk.yellow(`  Warning: output-folder normalization skipped: ${err.message}`));
+        return total;
+    }
+
+    if (total > 0) {
+        console.log(chalk.green(
+            `  Normalized ${total} module artifact path(s) to output folder "${outputFolder}/" (bug 27.14 work-around)`
+        ));
+    }
+    return total;
+}
+
 /**
  * Migration shim: normalize the project layout so that canonical config lives
  * at `_bmad/bmm/config.yaml` (v6.3.0) instead of `_bmad/_config/manifest.yaml`
@@ -2840,6 +3097,8 @@ module.exports = {
     isGeneratedClineWrapper,
     // Story 22.7 — canonical config (_bmad/bmm/config.yaml) helpers
     readCanonicalBmadConfig,
+    normalizeModuleOutputFolders,
+    correctArtifactPath,
     ensureCanonicalConfigLocation,
     CANONICAL_CONFIG_REL,
     LEGACY_MANIFEST_REL,

package/lib/installer.js

@@ -166,7 +166,12 @@ function composeInstructionBlock({ profile, projectRoot } = {}) {
     composed += '\n\n' + onprem.replace(/\s+$/, '');
   }
 
-  return composed + '\n';
+  // Bug 27.10 — the source templates are authored with CRLF line endings, but the
+  // segment seams and terminator above are hand-written LF. That mix yields a block
+  // whose body lines are CRLF while the joins are LF. Normalize to pure LF once here
+  // so the composed block is EOL-consistent regardless of how templates were checked
+  // out on Windows, and so downstream marker-merge (which assumes LF) stays stable.
+  return composed.replace(/\r\n/g, '\n') + '\n';
 }
 
 /**
@@ -245,6 +250,17 @@ function resolveBmadOutputDirs(projectRoot) {
 const CLAUDE_CODE_HOOK_ID = 'ma-agents-verify-manifest';
 const CLAUDE_CODE_SETTINGS_FILE = '.claude/settings.json';
 
+// Bug 27.8 — the SessionStart hook must point at a path that exists in a real
+// (npx/node_modules) install, not at the package's own `lib/` which is never
+// copied into the target. The dependency-free hook script is copied into the
+// target's `.claude/hooks/` and the command resolves it via $CLAUDE_PROJECT_DIR
+// (the target project root). The legacy `lib/hooks/...` command string is kept
+// here only so existing installs get it removed/migrated on the next run.
+const CLAUDE_CODE_HOOK_SOURCE = path.join(__dirname, 'hooks', 'claude-code', 'verify-manifest.js');
+const CLAUDE_CODE_HOOK_TARGET_REL = '.claude/hooks/verify-manifest.js';
+const CLAUDE_CODE_HOOK_COMMAND = `node "$CLAUDE_PROJECT_DIR/${CLAUDE_CODE_HOOK_TARGET_REL}"`;
+const CLAUDE_CODE_HOOK_LEGACY_COMMAND = `node "$CLAUDE_PROJECT_DIR/lib/hooks/claude-code/verify-manifest.js"`;
+
 function getPackageVersion() {
   const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf-8'));
   return pkg.version;
@@ -397,13 +413,91 @@ function ensurePluginStageIgnored(projectRoot) {
   );
 }
 
+// Bug 27.11 — the installer writes the `_bmad/` module tree which is
+// "Installer-managed. Regenerated on every install — treat as read-only."
+// Leaving it tracked guarantees churn and merge conflicts on every reinstall.
+// This sister-policy to PLUGIN_STAGE_PATTERNS ensures `_bmad/` is gitignored.
+//
+// IMPORTANT: this targets ONLY the regenerated `_bmad/` tree. The
+// `_bmad-output/` directory holds tracked project knowledge and is
+// deliberately kept OUT of .gitignore (see ensureBmadOutputTracked) — the
+// patterns below never match it because git treats `_bmad/` (trailing-slash
+// anchored) and `_bmad-output` as distinct entries.
+const BMAD_DIR_NAME = '_bmad';
+const BMAD_DIR_PATTERNS = [
+  BMAD_DIR_NAME,            // _bmad
+  `${BMAD_DIR_NAME}/`,      // _bmad/
+  `/${BMAD_DIR_NAME}`,      // /_bmad
+  `/${BMAD_DIR_NAME}/`,     // /_bmad/
+];
+const BMAD_DIR_CANONICAL_ENTRY = `${BMAD_DIR_NAME}/`;
+
+/**
+ * Ensure `_bmad/` is present in the target project's `.gitignore`. Mirrors the
+ * append-only, idempotent, EOL-preserving contract of `ensurePluginStageIgnored`.
+ *
+ *  - If `.gitignore` is absent, create it with the single canonical entry.
+ *  - If any active (non-comment) line already matches any BMAD_DIR_PATTERNS
+ *    variant, do nothing.
+ *  - Otherwise, append `BMAD_DIR_CANONICAL_ENTRY` preserving existing EOL style.
+ *
+ * Defensive: no-op on falsy/non-string projectRoot, matching the sister helper.
+ *
+ * @param {string} projectRoot - Absolute path to the target project root.
+ */
+function ensureBmadDirIgnored(projectRoot) {
+  if (typeof projectRoot !== 'string' || projectRoot.length === 0) {
+    return;
+  }
+
+  const gitignorePath = path.join(projectRoot, '.gitignore');
+
+  let content = '';
+  let fileExists = true;
+  try {
+    content = fs.readFileSync(gitignorePath, 'utf-8');
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+    fileExists = false;
+  }
+
+  if (fileExists) {
+    const alreadyPresent = content.split(/\r?\n/).some(rawLine => {
+      const line = rawLine.trim();
+      if (!line || line.startsWith('#')) return false; // skip blanks & comments
+      return BMAD_DIR_PATTERNS.includes(line);
+    });
+    if (alreadyPresent) return; // idempotent no-op
+  }
+
+  const usesCrlf = fileExists && /\r\n/.test(content);
+  const eol = usesCrlf ? '\r\n' : '\n';
+
+  let next = content;
+  if (next && !next.endsWith('\n') && !next.endsWith('\r\n')) {
+    next += eol; // ensure the append lands on its own line
+  }
+  next += BMAD_DIR_CANONICAL_ENTRY + eol;
+
+  fs.writeFileSync(gitignorePath, next, 'utf-8');
+  console.log(
+    chalk.green(
+      `${BMAD_DIR_CANONICAL_ENTRY} added to .gitignore (installer-managed BMAD tree — regenerated on every install)`
+    )
+  );
+}
+
 function ensureManifest(installPath, agentId, scope) {
   let manifest = readManifest(installPath);
   if (!manifest) {
+    // Bug 27.9 — when bootstrapped before any agent is known (e.g. profile
+    // bootstrap via setProfile → ensureManifest(root, null, 'project')), agentId
+    // is null. Mirror the migrate-branch guard so we never write the malformed
+    // `agent: null` / `agents: [null]` shape; an empty agents array is valid.
     manifest = {
       manifestVersion: MANIFEST_VERSION,
-      agent: agentId,
-      agents: [agentId],
+      agent: agentId || null,
+      agents: agentId ? [agentId] : [],
       scope: scope,
       skills: {}
     };
@@ -1265,6 +1359,116 @@ async function performInstall(skillId, skill, agent, installPath) {
   return true;
 }
 
+// --- Bug 27.16 — .agents/skills pipeline-consistency reconciliation ----------
+//
+// Two pipelines write skills: ma-agents' own standalone loop (installSkill →
+// performInstall + generateSkillsManifest — the ONLY writer of MANIFEST.yaml),
+// and bmad-method's PluginResolver (via --custom-source) which routes
+// copilot/roo/kilo to the shared `.agents/skills/` dir. The standalone loop only
+// targets `.agents/skills` when a copilot/kilocode/roo-code agent is selected.
+//
+// When the user selects only claude-code/cline/opencode, BMAD still writes the
+// BMAD-family skills into `.agents/skills` (175 of them in the Workshop repro)
+// but the standalone catalog and MANIFEST.yaml are never written there — leaving
+// a dir that looks installed but is silently partial AND missing the
+// MANIFEST.yaml the stamped instruction block points agents at.
+//
+// This pass makes `.agents/skills` pipeline-consistent: if BMAD populated it but
+// no `.agents`-targeting agent was selected (so the standalone loop skipped it),
+// install the full standalone catalog there and generate MANIFEST.yaml. The set
+// of `.agents`-targeting agent ids is derived from agents whose project skills
+// dir resolves to `.agents/skills`.
+
+const AGENTS_SHARED_SKILLS_DIRNAME = '.agents';
+
+/**
+ * Return the list of agent ids whose project-level skills dir is the shared
+ * `.agents/skills/` directory (copilot, kilocode, roo-code). Derived from the
+ * agent registry's `skillsDir` so a future registry change surfaces here.
+ */
+function getAgentsSharedSkillAgentIds() {
+  return listAgents()
+    .filter(a => a.skillsDir === path.join(AGENTS_SHARED_SKILLS_DIRNAME, 'skills') ||
+                 a.skillsDir === `${AGENTS_SHARED_SKILLS_DIRNAME}/skills`)
+    .map(a => a.id);
+}
+
+/**
+ * Bug 27.16 — reconcile a BMAD-populated `.agents/skills` directory that the
+ * standalone loop never targeted. No-op unless ALL of:
+ *   - scope === 'project'
+ *   - `<projectRoot>/.agents/skills` exists on disk (BMAD created it)
+ *   - no `.agents`-targeting agent was among the selected agents
+ *   - the dir has no MANIFEST.yaml (the standalone-loop signature)
+ *
+ * When triggered, installs the full standalone catalog into `.agents/skills`
+ * (using a representative `.agents`-targeting agent for template resolution),
+ * records the skills into that dir's `.ma-agents.json`, and generates
+ * MANIFEST.yaml — so the dir is never BMAD-only without a manifest.
+ *
+ * Idempotent: once MANIFEST.yaml exists the early-return fires.
+ *
+ * @param {string} projectRoot
+ * @param {string[]} selectedAgentIds - agent ids the user selected this run
+ * @param {string} scope - 'project' | 'global'
+ * @returns {Promise<{reconciled: boolean, installed: number}>}
+ */
+async function reconcileAgentsSharedSkills(projectRoot, selectedAgentIds = [], scope = 'project') {
+  const result = { reconciled: false, installed: 0 };
+  if (scope !== 'project') return result;
+  if (typeof projectRoot !== 'string' || !projectRoot) return result;
+
+  const sharedDir = path.join(projectRoot, AGENTS_SHARED_SKILLS_DIRNAME, 'skills');
+  if (!fs.existsSync(sharedDir)) return result; // BMAD never populated it
+
+  const sharedAgentIds = getAgentsSharedSkillAgentIds();
+  const selectedSet = new Set(selectedAgentIds || []);
+  const anySharedSelected = sharedAgentIds.some(id => selectedSet.has(id));
+  if (anySharedSelected) return result; // standalone loop already targeted it
+
+  // If a MANIFEST.yaml already exists, the dir is not standalone-orphaned.
+  if (fs.existsSync(path.join(sharedDir, 'MANIFEST.yaml'))) return result;
+
+  // Pick a representative `.agents`-targeting agent for template resolution.
+  const repAgent = sharedAgentIds.map(id => getAgent(id)).find(Boolean);
+  if (!repAgent) return result; // registry has no such agent — nothing to do
+
+  console.log(chalk.yellow(
+    `  Note: ${sharedDir} was populated by BMAD but carries no MANIFEST.yaml ` +
+    `(no .agents-targeting agent selected) — backfilling the standalone catalog (bug 27.16).`
+  ));
+
+  const skills = listSkills();
+  const manifest = ensureManifest(sharedDir, repAgent.id, scope);
+  const now = new Date().toISOString();
+
+  for (const skill of skills) {
+    try {
+      const ok = await performInstall(skill.id, skill, repAgent, sharedDir);
+      if (!ok) continue;
+      const existing = manifest.skills[skill.id];
+      manifest.skills[skill.id] = {
+        version: skill.version,
+        installedAt: existing ? existing.installedAt : now,
+        updatedAt: now,
+        installerVersion: getPackageVersion(),
+        agentVersion: repAgent.version
+      };
+      result.installed++;
+    } catch (err) {
+      console.log(chalk.yellow(`    x ${skill.id} skipped in .agents/skills backfill: ${err.message}`));
+    }
+  }
+
+  writeManifest(sharedDir, manifest);
+  await generateSkillsManifest(sharedDir);
+  result.reconciled = true;
+  console.log(chalk.green(
+    `  Backfilled ${result.installed} standalone skill(s) + MANIFEST.yaml into ${sharedDir}`
+  ));
+  return result;
+}
+
 // --- Install with upgrade detection ---
 
 async function installSkill(skillId, agentIds, customPath = '', scope = 'project', options = {}) {
@@ -1882,7 +2086,12 @@ function getStatus(agentIds, customPath = '', scope = 'project') {
 
     for (const { path: checkPath, scope: checkScope } of pathsToCheck) {
       const manifest = readManifest(checkPath);
-      if (!manifest || !manifest.skills || Object.keys(manifest.skills).length === 0) {
+      // Bug 27.12 — never treat the PROFILE-ONLY project-root manifest as a
+      // skill inventory. The per-agent skills manifests are authoritative; a
+      // manifest carrying the `project-root` scope discriminator is a
+      // profile/settings store and must be skipped here.
+      if (!manifest || manifest.scope === 'project-root' ||
+          !manifest.skills || Object.keys(manifest.skills).length === 0) {
         continue;
       }
 
@@ -1924,27 +2133,49 @@ async function deployClaudeCodeHook(projectRoot) {
     settings.hooks.SessionStart = [];
   }
 
-  // Check if our hook is already present
-  const hookCommand = `node "$CLAUDE_PROJECT_DIR/lib/hooks/claude-code/verify-manifest.js"`;
+  // Bug 27.8 — copy the self-contained hook into the target so the command
+  // resolves in any install (npx/node_modules/dev-repo). The legacy command
+  // string (which pointed at the never-copied package `lib/`) is migrated to
+  // the new command on every run.
+  const hookTargetPath = path.join(projectRoot, CLAUDE_CODE_HOOK_TARGET_REL);
+  await fs.ensureDir(path.dirname(hookTargetPath));
+  await fs.copy(CLAUDE_CODE_HOOK_SOURCE, hookTargetPath, { overwrite: true });
+
+  const hookCommand = CLAUDE_CODE_HOOK_COMMAND;
+  let migrated = false;
+  for (const group of settings.hooks.SessionStart) {
+    if (!group.hooks) continue;
+    for (const h of group.hooks) {
+      if (h.command === CLAUDE_CODE_HOOK_LEGACY_COMMAND || h._id === CLAUDE_CODE_HOOK_ID) {
+        h.command = hookCommand;
+        h._id = CLAUDE_CODE_HOOK_ID;
+        migrated = true;
+      }
+    }
+  }
+
   const alreadyInstalled = settings.hooks.SessionStart.some(group =>
     group.hooks && group.hooks.some(h => h.command === hookCommand)
   );
 
-  if (alreadyInstalled) {
-    return; // Already deployed
+  if (!alreadyInstalled) {
+    settings.hooks.SessionStart.push({
+      matcher: 'startup',
+      hooks: [
+        {
+          type: 'command',
+          command: hookCommand,
+          _id: CLAUDE_CODE_HOOK_ID
+        }
+      ]
+    });
+  } else if (!migrated) {
+    // Hook entry already current and file copied — still ensure settings exist.
+    await fs.ensureDir(path.dirname(settingsPath));
+    await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+    return;
   }
 
-  settings.hooks.SessionStart.push({
-    matcher: 'startup',
-    hooks: [
-      {
-        type: 'command',
-        command: hookCommand,
-        _id: CLAUDE_CODE_HOOK_ID
-      }
-    ]
-  });
-
   await fs.ensureDir(path.dirname(settingsPath));
   await fs.writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
   console.log(chalk.cyan('    + Deployed Claude Code verify-manifest hook'));
@@ -1956,6 +2187,15 @@ async function deployClaudeCodeHook(projectRoot) {
 async function removeClaudeCodeHook(projectRoot) {
   const settingsPath = path.join(projectRoot, CLAUDE_CODE_SETTINGS_FILE);
 
+  // Bug 27.8 — remove the copied hook file first, before any settings.json
+  // early-return, so a missing/corrupt settings.json never orphans the file.
+  const hookTargetPath = path.join(projectRoot, CLAUDE_CODE_HOOK_TARGET_REL);
+  try {
+    await fs.remove(hookTargetPath);
+  } catch {
+    // best-effort cleanup — never fail uninstall over a missing file
+  }
+
   if (!fs.existsSync(settingsPath)) return;
 
   let settings;
@@ -1967,10 +2207,15 @@ async function removeClaudeCodeHook(projectRoot) {
 
   if (!settings.hooks || !settings.hooks.SessionStart) return;
 
-  const hookCommand = `node "$CLAUDE_PROJECT_DIR/lib/hooks/claude-code/verify-manifest.js"`;
+  // Match both the current command and the legacy package-relative command so
+  // older installs get cleaned up too.
   settings.hooks.SessionStart = settings.hooks.SessionStart.filter(group => {
     if (!group.hooks) return true;
-    group.hooks = group.hooks.filter(h => h.command !== hookCommand && h._id !== CLAUDE_CODE_HOOK_ID);
+    group.hooks = group.hooks.filter(h =>
+      h.command !== CLAUDE_CODE_HOOK_COMMAND &&
+      h.command !== CLAUDE_CODE_HOOK_LEGACY_COMMAND &&
+      h._id !== CLAUDE_CODE_HOOK_ID
+    );
     return group.hooks.length > 0;
   });
 
@@ -2009,6 +2254,9 @@ module.exports = {
   removeClaudeCodeHook,
   ensureBmadOutputTracked,
   ensurePluginStageIgnored,
+  ensureBmadDirIgnored,
+  reconcileAgentsSharedSkills,
+  getAgentsSharedSkillAgentIds,
   generateSkillsManifest,
   generateProjectContext,
   generateRepoLayoutSection,

package/lib/profile.js

@@ -23,6 +23,29 @@ const path = require('path');
 const MANIFEST_FILE = '.ma-agents.json';
 const VALID_PROFILES = ['on-prem', 'standard'];
 
+// Bug 27.12 — the project-root .ma-agents.json is a PROFILE/settings store, not
+// a skill inventory. Per-agent skills dirs (e.g. .claude/skills/.ma-agents.json)
+// own the installed-skill inventory and remain the authoritative source read by
+// getStatus/uninstall/reconcile. The root bootstrap therefore emits ONLY the
+// fields it owns (manifestVersion + a scope discriminator) and NOT a `skills`/
+// `agents` shape it would never back-fill — so the root file can no longer
+// masquerade as an empty skill inventory (`skills: {}`).
+const ROOT_MANIFEST_VERSION = '1.2.0';
+const ROOT_SCOPE = 'project-root';
+
+/**
+ * Bootstrap a fresh PROFILE-ONLY root manifest object (not persisted here).
+ * Intentionally omits `skills` and `agents`: those belong to per-agent skills
+ * manifests. The `scope: 'project-root'` discriminator makes the file's role
+ * explicit for any reader.
+ */
+function bootstrapRootManifest() {
+  return {
+    manifestVersion: ROOT_MANIFEST_VERSION,
+    scope: ROOT_SCOPE,
+  };
+}
+
 /**
  * Reads the persisted profile from .ma-agents.json at the given project root.
  * Returns undefined if the file does not exist, is malformed, or the "profile"
@@ -73,10 +96,12 @@ function setProfile(projectRoot, value) {
   }
 
   if (!manifest || typeof manifest !== 'object') {
-    // Bootstrap via the standard schema (mirrors lib/installer.js ensureManifest shape).
-    // Require lazily to avoid potential circular-import pitfalls at module load.
-    const { ensureManifest } = require('./installer');
-    manifest = ensureManifest(projectRoot, null, 'project');
+    // Bug 27.12 — bootstrap a PROFILE-ONLY root manifest. Previously this used
+    // ensureManifest(root, null, 'project'), which stamped an empty `skills: {}`
+    // / `agents: []` shape the root file never owns or back-fills, making it
+    // look like an (empty) skill inventory. The per-agent skills manifests are
+    // the authoritative inventory; the root file stores profile/settings only.
+    manifest = bootstrapRootManifest();
   }
 
   // Migrate 1.1.0 (or missing version) → 1.2.0, since the "profile" field is 1.2.0-only.
@@ -127,4 +152,70 @@ function clearProfile(projectRoot) {
   fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
 }
 
-module.exports = { getProfile, setProfile, resolveProfile, clearProfile };
+/**
+ * Bug 27.13 — durable BMAD-module selection.
+ *
+ * Reads the persisted BMAD module set from .ma-agents.json (the `bmadModules`
+ * field). Returns undefined when the file is absent/malformed or the field is
+ * missing, so callers can distinguish "never persisted" (→ install default set)
+ * from an explicit empty selection. A persisted value is always returned as an
+ * array of strings.
+ */
+function getBmadModules(projectRoot) {
+  const manifestPath = path.join(projectRoot, MANIFEST_FILE);
+  if (!fs.existsSync(manifestPath)) return undefined;
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+  } catch {
+    return undefined;
+  }
+  if (!manifest || typeof manifest !== 'object') return undefined;
+  if (!Object.prototype.hasOwnProperty.call(manifest, 'bmadModules')) return undefined;
+  const value = manifest.bmadModules;
+  if (!Array.isArray(value)) return undefined;
+  // Normalize to a clean, de-duplicated array of non-empty strings.
+  return [...new Set(value.filter(m => typeof m === 'string' && m.length > 0))];
+}
+
+/**
+ * Bug 27.13 — persists the selected BMAD module set into .ma-agents.json,
+ * preserving all other fields. Creates the file via the standard ensureManifest
+ * bootstrap path if absent (mirroring setProfile). The choice then survives
+ * subsequent installs/reconfigures that do not re-pass --bmad-modules.
+ *
+ * @param {string} projectRoot
+ * @param {string[]} modules - module ids to persist (e.g. ['bmm','tea','bmb'])
+ */
+function setBmadModules(projectRoot, modules) {
+  if (!Array.isArray(modules)) {
+    throw new Error(`setBmadModules expects an array of module ids (got ${JSON.stringify(modules)})`);
+  }
+  const cleaned = [...new Set(modules.filter(m => typeof m === 'string' && m.length > 0))];
+
+  const manifestPath = path.join(projectRoot, MANIFEST_FILE);
+  let manifest;
+  if (fs.existsSync(manifestPath)) {
+    try {
+      manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+    } catch {
+      manifest = null;
+    }
+  }
+  if (!manifest || typeof manifest !== 'object') {
+    // Bug 27.12 — profile-only root bootstrap (see setProfile / bootstrapRootManifest).
+    manifest = bootstrapRootManifest();
+  }
+
+  manifest.bmadModules = cleaned;
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
+}
+
+module.exports = {
+  getProfile,
+  setProfile,
+  resolveProfile,
+  clearProfile,
+  getBmadModules,
+  setBmadModules,
+};

package/lib/templates/instruction-block-git.template.md

@@ -1,25 +1,25 @@
-## Git Workflow (ALL file-changing tasks)
-
-These rules apply to EVERY task that modifies a tracked file. There is no
-"small fix exemption" — a one-line edit follows the same workflow as a feature.
-
-- **Worktree first.** Before changing any file, create a fresh isolated worktree
-  on a new feature branch: `git worktree add ../<project>-<branch> -b <branch>`.
-  The scripted form is `skills/git-workflow-skill/scripts/start-feature.sh`. All
-  file-writing happens inside that worktree — never in the main working tree.
-- **Never commit directly to the trunk.** Do NOT commit to `main`, `dev`,
-  `master`, or whatever the trunk branch is. Commits land only on your feature
-  branch inside the worktree.
-- **Conventional Commits.** Every commit message uses a Conventional Commits
-  prefix. The allowed prefixes are: `feat`, `fix`, `chore`, `docs`, `refactor`,
-  `test`, `ci`.
-- **PR is the only path into the trunk.** Integrate exclusively by opening a pull
-  request with `gh pr create`. Never merge directly and never auto-merge a PR
-  without explicit human approval.
-- **Self-review before opening the PR.** Run the `code-review` skill on your own
-  changes and address its findings before you open the PR.
-- **Clean up after merge.** Once the PR is merged, remove the worktree with
-  `git worktree remove` and delete the feature branch.
-
-Full procedure: see `skills/git-workflow-skill/SKILL.md`, and the helper scripts
-`scripts/start-feature.sh` / `scripts/finish-feature.sh`.
+## Git Workflow (ALL file-changing tasks)
+
+These rules apply to EVERY task that modifies a tracked file. There is no
+"small fix exemption" — a one-line edit follows the same workflow as a feature.
+
+- **Worktree first.** Before changing any file, create a fresh isolated worktree
+  on a new feature branch: `git worktree add ../<project>-<branch> -b <branch>`.
+  The scripted form is `skills/git-workflow-skill/scripts/start-feature.sh`. All
+  file-writing happens inside that worktree — never in the main working tree.
+- **Never commit directly to the trunk.** Do NOT commit to `main`, `dev`,
+  `master`, or whatever the trunk branch is. Commits land only on your feature
+  branch inside the worktree.
+- **Conventional Commits.** Every commit message uses a Conventional Commits
+  prefix. The allowed prefixes are: `feat`, `fix`, `chore`, `docs`, `refactor`,
+  `test`, `ci`.
+- **PR is the only path into the trunk.** Integrate exclusively by opening a pull
+  request with `gh pr create`. Never merge directly and never auto-merge a PR
+  without explicit human approval.
+- **Self-review before opening the PR.** Run the `code-review` skill on your own
+  changes and address its findings before you open the PR.
+- **Clean up after merge.** Once the PR is merged, remove the worktree with
+  `git worktree remove` and delete the feature branch.
+
+Full procedure: see `skills/git-workflow-skill/SKILL.md`, and the helper scripts
+`scripts/start-feature.sh` / `scripts/finish-feature.sh`.

package/lib/templates/instruction-block-onprem.template.md

@@ -1,86 +1,86 @@
-## On-Prem / Local-LLM Guardrails
-
-These rules apply ONLY when this project is installed with `profile: on-prem`.
-They are appended to the universal block by the composer in `lib/installer.js`.
-Local LLMs (Nemotron, Qwen, DeepSeek, Llama-3, etc. served via vLLM, Ollama, or
-TGI) fail in patterns cloud LLMs rarely exhibit — the rules below pin those
-failure modes down explicitly. Keep these rules verbatim in every response
-context where tool use is possible.
-
-### Reasoning mode: `/no_think` on planning-phase prompts
-
-Local reasoning-capable models (Nemotron-variants and similar) default to
-chain-of-thought reasoning that bloats planning-phase prompts with internal
-deliberation the operator does not need to read. Prepend the literal token
-`/no_think` as the first line of any planning-phase system prompt or user turn
-you compose. The token is consumed by the serving layer and suppresses the
-model's reasoning trace on that turn.
-
-- Planning-phase turns (PM, Architect, Tech Lead): begin the turn with
-  `/no_think` on its own line. Reasoning-mode OFF.
-- Implementation-phase turns (Dev): omit `/no_think`. Reasoning-mode ON is
-  desirable for stepwise code synthesis and debugging.
-- Review / QA turns: omit `/no_think` when the review benefits from explicit
-  reasoning (root-cause analysis). Include `/no_think` for mechanical checks
-  (lint, style, formatting).
-
-If the downstream serving layer does not recognize `/no_think`, it is a no-op
-text token — safe to include unconditionally on planning turns.
-
-### No writes to `~/.claude/` or any user home directory
-
-Local LLMs frequently hallucinate paths under `~/.claude/`, `~/.cache/`,
-`~/Library/`, or `%APPDATA%` — imitating patterns learned from Claude Code and
-Cursor training data. These paths are OUTSIDE the project and cross-contaminate
-other projects on the same machine.
-
-- NEVER create, write, or modify files under `~/.claude/`, `~/.cache/`,
-  `~/Library/`, `~/AppData/`, `%APPDATA%`, or any path that resolves outside
-  the current project directory.
-- All project artifacts — code, configuration, logs, scratch notes, and agent
-  state — MUST land under the current working directory (the project root) or
-  an explicitly-named subdirectory thereof.
-- When a tool call appears to target a home-directory path, refuse the write
-  and respond in text explaining the violation. Ask the user for an explicit
-  in-project path before proceeding.
-
-### No `str_replace_editor` or Claude Code-specific tools
-
-Local LLMs hallucinate Anthropic-proprietary tools — most commonly
-`str_replace_editor`, `text_editor_20241022`, and `computer_use_preview` — that
-do NOT exist outside the Anthropic API. Calling them against a local-LLM
-serving layer produces a tool-not-found error or, worse, a silent no-op.
-
-- Do NOT emit tool calls named `str_replace_editor`, `text_editor_*`,
-  `computer_use_*`, or any other tool whose name includes `str_replace_editor`
-  or matches Anthropic-specific tool schemas.
-- Use only tools enumerated in the active tool manifest (`MANIFEST.yaml`) or
-  the IDE's native tool surface (Roo Code, Cline, OpenCode native tools).
-- When you want to edit a file, use the native file-write tool of the active
-  agent — not `str_replace_editor`. If unsure what tool is available, list
-  available tools or ask the user before emitting a tool call.
-
-### Per-phase reasoning and sampling guidance
-
-Local LLMs require tighter sampling control than cloud LLMs. Use these defaults
-unless the serving layer overrides them.
-
-- **Planning phase (PM, Architect, Tech Lead):**
-  - Reasoning: OFF (`/no_think` prepended).
-  - Temperature: low (0.0 – 0.3). Planning artifacts should be deterministic
-    and reproducible.
-  - Top-p: 0.9 or unset. Top-k: unset.
-  - Max tokens: generous (8k+) — planning documents are long.
-- **Implementation phase (Dev):**
-  - Reasoning: ON (omit `/no_think`).
-  - Temperature: moderate (0.3 – 0.6). Code synthesis benefits from controlled
-    exploration but not creative rewriting.
-  - Top-p: 0.95 or unset. Top-k: unset.
-  - Max tokens: generous (8k+) — full-file rewrites are common.
-- **Review / QA phase:**
-  - Reasoning: ON for root-cause analysis; OFF for mechanical checks.
-  - Temperature: low (0.0 – 0.2). Reviews should be deterministic.
-
-If the serving layer applies its own sampler defaults, the per-phase guidance
-above is advisory — but the phase boundary and `/no_think` placement are
-load-bearing and MUST be honored on every turn.
+## On-Prem / Local-LLM Guardrails
+
+These rules apply ONLY when this project is installed with `profile: on-prem`.
+They are appended to the universal block by the composer in `lib/installer.js`.
+Local LLMs (Nemotron, Qwen, DeepSeek, Llama-3, etc. served via vLLM, Ollama, or
+TGI) fail in patterns cloud LLMs rarely exhibit — the rules below pin those
+failure modes down explicitly. Keep these rules verbatim in every response
+context where tool use is possible.
+
+### Reasoning mode: `/no_think` on planning-phase prompts
+
+Local reasoning-capable models (Nemotron-variants and similar) default to
+chain-of-thought reasoning that bloats planning-phase prompts with internal
+deliberation the operator does not need to read. Prepend the literal token
+`/no_think` as the first line of any planning-phase system prompt or user turn
+you compose. The token is consumed by the serving layer and suppresses the
+model's reasoning trace on that turn.
+
+- Planning-phase turns (PM, Architect, Tech Lead): begin the turn with
+  `/no_think` on its own line. Reasoning-mode OFF.
+- Implementation-phase turns (Dev): omit `/no_think`. Reasoning-mode ON is
+  desirable for stepwise code synthesis and debugging.
+- Review / QA turns: omit `/no_think` when the review benefits from explicit
+  reasoning (root-cause analysis). Include `/no_think` for mechanical checks
+  (lint, style, formatting).
+
+If the downstream serving layer does not recognize `/no_think`, it is a no-op
+text token — safe to include unconditionally on planning turns.
+
+### No writes to `~/.claude/` or any user home directory
+
+Local LLMs frequently hallucinate paths under `~/.claude/`, `~/.cache/`,
+`~/Library/`, or `%APPDATA%` — imitating patterns learned from Claude Code and
+Cursor training data. These paths are OUTSIDE the project and cross-contaminate
+other projects on the same machine.
+
+- NEVER create, write, or modify files under `~/.claude/`, `~/.cache/`,
+  `~/Library/`, `~/AppData/`, `%APPDATA%`, or any path that resolves outside
+  the current project directory.
+- All project artifacts — code, configuration, logs, scratch notes, and agent
+  state — MUST land under the current working directory (the project root) or
+  an explicitly-named subdirectory thereof.
+- When a tool call appears to target a home-directory path, refuse the write
+  and respond in text explaining the violation. Ask the user for an explicit
+  in-project path before proceeding.
+
+### No `str_replace_editor` or Claude Code-specific tools
+
+Local LLMs hallucinate Anthropic-proprietary tools — most commonly
+`str_replace_editor`, `text_editor_20241022`, and `computer_use_preview` — that
+do NOT exist outside the Anthropic API. Calling them against a local-LLM
+serving layer produces a tool-not-found error or, worse, a silent no-op.
+
+- Do NOT emit tool calls named `str_replace_editor`, `text_editor_*`,
+  `computer_use_*`, or any other tool whose name includes `str_replace_editor`
+  or matches Anthropic-specific tool schemas.
+- Use only tools enumerated in the active tool manifest (`MANIFEST.yaml`) or
+  the IDE's native tool surface (Roo Code, Cline, OpenCode native tools).
+- When you want to edit a file, use the native file-write tool of the active
+  agent — not `str_replace_editor`. If unsure what tool is available, list
+  available tools or ask the user before emitting a tool call.
+
+### Per-phase reasoning and sampling guidance
+
+Local LLMs require tighter sampling control than cloud LLMs. Use these defaults
+unless the serving layer overrides them.
+
+- **Planning phase (PM, Architect, Tech Lead):**
+  - Reasoning: OFF (`/no_think` prepended).
+  - Temperature: low (0.0 – 0.3). Planning artifacts should be deterministic
+    and reproducible.
+  - Top-p: 0.9 or unset. Top-k: unset.
+  - Max tokens: generous (8k+) — planning documents are long.
+- **Implementation phase (Dev):**
+  - Reasoning: ON (omit `/no_think`).
+  - Temperature: moderate (0.3 – 0.6). Code synthesis benefits from controlled
+    exploration but not creative rewriting.
+  - Top-p: 0.95 or unset. Top-k: unset.
+  - Max tokens: generous (8k+) — full-file rewrites are common.
+- **Review / QA phase:**
+  - Reasoning: ON for root-cause analysis; OFF for mechanical checks.
+  - Temperature: low (0.0 – 0.2). Reviews should be deterministic.
+
+If the serving layer applies its own sampler defaults, the per-phase guidance
+above is advisory — but the phase boundary and `/no_think` placement are
+load-bearing and MUST be honored on every turn.

package/lib/templates/instruction-block-universal.template.md

@@ -1,29 +1,29 @@
-# AI Agent Skills - Planning Instruction
-
-You have access to a library of skills in your skills directory. Before starting any task:
-
-1. Read the skill manifest at {{MANIFEST_PATH}}
-2. Based on the task description, select which skills are relevant
-3. Read only the selected skill files
-4. Then proceed with the task
-
-Always load skills marked with always_load: true.
-Do not load skills that are not relevant to the current task.
-
-## Respond in TEXT vs. create FILES
-
-Choose your response medium deliberately. Defaulting to file creation when the user asked a question is a common failure mode — especially for coding agents running in web UIs.
-
-- **Create or modify FILES when the user's request contains file-action keywords:** `create`, `write`, `generate`, `build`, `implement` (and obvious synonyms such as `add`, `produce`, `refactor`, `fix`, `update <file>`). These signal a concrete artifact is expected.
-- **Respond in TEXT when the request contains text-response keywords:** `what do you think`, `how should we`, `discuss`, `opinion` (and obvious synonyms such as `explain`, `why`, `should I`, `compare`, `recommend`). These signal that a conversation is expected, not a deliverable.
-- **If unsure, respond in TEXT.** A text answer can always be followed by file creation on confirmation; an unwanted file cannot be cleanly undone.
-- **Never create `response.md`, `output.md`, or any similarly named scratch file as a reply.** A reply belongs in the chat transcript, not on disk.
-- **Confirm file paths before writing.** When you are about to create or modify a file whose path the user has not explicitly named, state the intended path in text and wait for confirmation, unless the path is unambiguous from the task context.
-
-## BMAD phase discipline
-
-BMAD-METHOD organizes work into declared phases (analysis, planning, architecture, story-creation, implementation, review). Respect the currently declared phase.
-
-- **Do not skip ahead to implementation during planning.** If the project is in a planning phase — or the user has asked for requirements, architecture, or a story — produce planning artifacts, not code.
-- **Do not retroactively plan after you have already coded.** If implementation has already started, flag the gap instead of fabricating back-dated planning documents.
-- The declared phase is established by the active skill, the story status, or an explicit statement from the user. When none of these is available, ask before assuming.
+# AI Agent Skills - Planning Instruction
+
+You have access to a library of skills in your skills directory. Before starting any task:
+
+1. Read the skill manifest at {{MANIFEST_PATH}}
+2. Based on the task description, select which skills are relevant
+3. Read only the selected skill files
+4. Then proceed with the task
+
+Always load skills marked with always_load: true.
+Do not load skills that are not relevant to the current task.
+
+## Respond in TEXT vs. create FILES
+
+Choose your response medium deliberately. Defaulting to file creation when the user asked a question is a common failure mode — especially for coding agents running in web UIs.
+
+- **Create or modify FILES when the user's request contains file-action keywords:** `create`, `write`, `generate`, `build`, `implement` (and obvious synonyms such as `add`, `produce`, `refactor`, `fix`, `update <file>`). These signal a concrete artifact is expected.
+- **Respond in TEXT when the request contains text-response keywords:** `what do you think`, `how should we`, `discuss`, `opinion` (and obvious synonyms such as `explain`, `why`, `should I`, `compare`, `recommend`). These signal that a conversation is expected, not a deliverable.
+- **If unsure, respond in TEXT.** A text answer can always be followed by file creation on confirmation; an unwanted file cannot be cleanly undone.
+- **Never create `response.md`, `output.md`, or any similarly named scratch file as a reply.** A reply belongs in the chat transcript, not on disk.
+- **Confirm file paths before writing.** When you are about to create or modify a file whose path the user has not explicitly named, state the intended path in text and wait for confirmation, unless the path is unambiguous from the task context.
+
+## BMAD phase discipline
+
+BMAD-METHOD organizes work into declared phases (analysis, planning, architecture, story-creation, implementation, review). Respect the currently declared phase.
+
+- **Do not skip ahead to implementation during planning.** If the project is in a planning phase — or the user has asked for requirements, architecture, or a story — produce planning artifacts, not code.
+- **Do not retroactively plan after you have already coded.** If implementation has already started, flag the gap instead of fabricating back-dated planning documents.
+- The declared phase is established by the active skill, the story status, or an explicit statement from the user. When none of these is available, ask before assuming.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ma-agents",
-  "version": "3.13.0",
+  "version": "3.13.1",
   "description": "NPX tool to install skills for AI coding agents (Claude Code, Gemini, Copilot, Kilocode, Cline, Cursor, Roo Code)",
   "main": "index.js",
   "bin": {

package/skills/git-workflow-skill/skill.json

@@ -1,21 +1,21 @@
-{
-  "name": "Git Workflow",
-  "description": "MANDATORY worktree-based workflow for ALL file-changing activities. Enforces isolated feature branches, conventional commits, and PR-based merging.",
-  "version": "2.1.0",
-  "author": "AI Agent Skills",
-  "tags": [
-    "git",
-    "worktrees",
-    "workflow",
-    "branching",
-    "conventional-commits",
-    "pull-requests",
-    "multi-agent"
-  ],
-  "applies_when": [
-    "committing changes",
-    "creating branches or PRs",
-    "any code writing or modification task"
-  ],
-  "always_load": true
-}
+{
+  "name": "Git Workflow",
+  "description": "MANDATORY worktree-based workflow for ALL file-changing activities. Enforces isolated feature branches, conventional commits, and PR-based merging.",
+  "version": "2.1.0",
+  "author": "AI Agent Skills",
+  "tags": [
+    "git",
+    "worktrees",
+    "workflow",
+    "branching",
+    "conventional-commits",
+    "pull-requests",
+    "multi-agent"
+  ],
+  "applies_when": [
+    "committing changes",
+    "creating branches or PRs",
+    "any code writing or modification task"
+  ],
+  "always_load": true
+}