ma-agents 3.14.0 → 3.15.0-beta.0

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

@@ -110,7 +110,8 @@
         "./skills/prioritize-backlog",
         "./skills/project-context-expansion",
         "./skills/remove-from-sprint",
-        "./skills/sprint-status-view"
+        "./skills/sprint-status-view",
+        "./skills/bmad-knowledge"
       ]
     }
   ]

package/lib/bmad-extension/skills/bmad-knowledge/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: bmad-knowledge
+description: Generate a self-contained Knowledge Atlas HTML site from project planning and implementation artifacts
+type: skill
+triggers:
+  - "knowledge atlas"
+  - "generate knowledge site"
+  - "bmad-knowledge"
+---
+
+# Knowledge Atlas Skill
+
+Generate a self-contained, offline-ready Knowledge Atlas HTML site from the project's `_bmad-output` planning and implementation artifacts. No network access is required at generation or view time.
+
+## Prerequisites
+
+- The project must have a `_bmad-output/` directory (created by BMAD install).
+- `ma-agents` must be installed (globally via `npx ma-agents` or as a local dependency).
+- Node.js >= 18 must be available.
+
+---
+
+## Workflow
+
+### Step 1 — Resolve the project root
+
+The project root is the directory containing `_bmad-output/`. Locate it by walking up from the current working directory until `_bmad-output/` is found, or use the directory the agent is operating in.
+
+```
+projectRoot = <directory containing _bmad-output/>
+bmadOutputDir = <projectRoot>/_bmad-output
+outputSite = <projectRoot>/_bmad-output/knowledge-site/index.html
+```
+
+### Step 2 — Locate the engine bundle
+
+The Knowledge Atlas engine is a pre-bundled CJS file committed inside the `ma-agents` package. Resolve it in this order:
+
+1. **Installed package resolution (preferred):** Use Node.js module resolution to locate the bundle:
+   ```js
+   require.resolve('ma-agents/lib/knowledge-atlas/dist/atlas.cjs')
+   ```
+   This works when `ma-agents` is installed as a dependency or globally via `npx`.
+
+2. **Dev-local fallback:** If the skill is being run from within the `ma-agents` repo itself (e.g., during development), use a path relative to the skill file:
+   ```
+   <skill_dir>/../../../../lib/knowledge-atlas/dist/atlas.cjs
+   ```
+   where `<skill_dir>` is the directory containing this SKILL.md.
+
+3. If neither path resolves to an existing file, abort with:
+   ```
+   ERROR: Cannot locate atlas.cjs. Ensure ma-agents is installed:
+     npm install -g ma-agents
+     # or: npm install --save-dev ma-agents
+   ```
+
+### Step 3 — Run the engine
+
+Execute the bundled engine as a Node.js subprocess. Pass `atlasPath` and
+`projectRoot` as ARGUMENT-ARRAY elements (never interpolate them into a shell
+string) so paths containing spaces, quotes, or shell metacharacters cannot be
+misparsed or injected:
+
+```js
+const { spawnSync } = require('node:child_process');
+const res = spawnSync(process.execPath, [atlasPath, projectRoot], {
+  encoding: 'utf-8',
+  // No `shell: true` — args go directly to the OS exec, not a shell.
+});
+if (res.status !== 0) {
+  // Report res.stderr and abort.
+  throw new Error(`atlas.cjs failed (exit ${res.status}): ${res.stderr}`);
+}
+const indexHtmlPath = res.stdout.trim(); // engine prints the index.html path
+```
+
+- The engine writes `_bmad-output/knowledge-site/index.html`.
+- It prints the path to `stdout` on success.
+- It exits with code 0 on success, non-zero on failure (error on stderr).
+- It never modifies any source file — output is isolated to `_bmad-output/knowledge-site/`.
+
+If the engine exits non-zero, report the stderr output and abort.
+
+### Step 4 — Open the generated site
+
+After successful generation, open `_bmad-output/knowledge-site/index.html` using
+the appropriate method for the current environment. Use `execFile`/`spawn` with
+an ARGUMENT ARRAY — never build a shell command string with the path
+interpolated, which would be an injection vector:
+
+**VSCode detection** (open in the editor):
+```js
+const { execFile } = require('node:child_process');
+if (process.env.TERM_PROGRAM === 'vscode' || process.env.VSCODE_PID !== undefined) {
+  execFile('code', [indexHtmlPath]); // path is a discrete arg, not concatenated
+}
+```
+
+**System default browser** (for all other environments) — pass the path as an
+arg-array element to the platform opener:
+- **Windows:** `execFile('cmd', ['/c', 'start', '', indexHtmlPath])`
+- **macOS:**   `execFile('open', [indexHtmlPath])`
+- **Linux:**   `execFile('xdg-open', [indexHtmlPath])`
+
+Report the output path to the user regardless of whether the browser opens:
+```
+Knowledge Atlas generated: <projectRoot>/_bmad-output/knowledge-site/index.html
+```
+
+---
+
+## Gitignore policy
+
+The `_bmad-output/knowledge-site/` directory is automatically gitignored when BMAD installs into a project (via `ensureKnowledgeSiteIgnored`). If it is not already ignored, add the following line to `.gitignore`:
+
+```
+_bmad-output/knowledge-site/
+```
+
+---
+
+## Notes
+
+- **Offline by construction:** The generated `index.html` is fully self-contained — no external URLs, no CDN links, no web fonts. It can be opened from a local filesystem in any browser.
+- **Deterministic output:** Pin `SOURCE_DATE_EPOCH` (Unix seconds) to get byte-identical output across runs:
+  ```bash
+  SOURCE_DATE_EPOCH=1700000000 node atlas.cjs "<projectRoot>"
+  ```
+- **No per-project install:** The engine (`atlas.cjs`) is pre-bundled in `ma-agents`. Consuming projects never run `npm install` for the Atlas engine.

package/lib/bmad-extension/skills/bmad-knowledge/bmad-skill-manifest.yaml

@@ -0,0 +1,3 @@
+type: skill
+name: bmad-knowledge
+module: ma-skills

package/lib/bmad-extension/skills/module-help.csv

@@ -60,3 +60,4 @@ ma-skills,4-implementation,Close Sprint,close-sprint,,skill:close-sprint,close-s
 ma-skills,4-implementation,Prioritize Backlog,prioritize-backlog,,skill:prioritize-backlog,prioritize-backlog,false,bmm-sm,,"Reprioritize backlog items using multiple criteria -- severity, business value, dependencies, type, age.",_bmad-output/implementation-artifacts,"backlog",
 ma-skills,4-implementation,Project Context Expansion,project-context-expansion,,skill:project-context-expansion,project-context-expansion,false,bmm-sm,,"Post-retrospective companion to update project-context.md with new rules.",_bmad-output,"project context",
 ma-skills,4-implementation,Requirements Quality Audit,sqa-requirements-quality,,skill:sqa-requirements-quality,sqa-requirements-quality,false,bmm-qa,,"Evaluate project requirements against 14 quality criteria — produces a per-requirement audit table, missing-elements section, and overall quality score.",_bmad-output,"quality report",
+ma-skills,anytime,Knowledge Atlas,bmad-knowledge,,skill:bmad-knowledge,bmad-knowledge,false,bmm-sm,,"Generate a self-contained Knowledge Atlas HTML site from project planning and implementation artifacts.",_bmad-output/knowledge-site,"knowledge site",

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.14.0",
+      "version": "3.15.0-beta.0",
       "author": {
         "name": "Alon Mayaffit"
       },
@@ -102,7 +102,8 @@
         "./skills/prioritize-backlog",
         "./skills/project-context-expansion",
         "./skills/remove-from-sprint",
-        "./skills/sprint-status-view"
+        "./skills/sprint-status-view",
+        "./skills/bmad-knowledge"
       ]
     }
   ]

package/lib/bmad-extension-plugin/skills/bmad-knowledge/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: bmad-knowledge
+description: Generate a self-contained Knowledge Atlas HTML site from project planning and implementation artifacts
+type: skill
+triggers:
+  - "knowledge atlas"
+  - "generate knowledge site"
+  - "bmad-knowledge"
+---
+
+# Knowledge Atlas Skill
+
+Generate a self-contained, offline-ready Knowledge Atlas HTML site from the project's `_bmad-output` planning and implementation artifacts. No network access is required at generation or view time.
+
+## Prerequisites
+
+- The project must have a `_bmad-output/` directory (created by BMAD install).
+- `ma-agents` must be installed (globally via `npx ma-agents` or as a local dependency).
+- Node.js >= 18 must be available.
+
+---
+
+## Workflow
+
+### Step 1 — Resolve the project root
+
+The project root is the directory containing `_bmad-output/`. Locate it by walking up from the current working directory until `_bmad-output/` is found, or use the directory the agent is operating in.
+
+```
+projectRoot = <directory containing _bmad-output/>
+bmadOutputDir = <projectRoot>/_bmad-output
+outputSite = <projectRoot>/_bmad-output/knowledge-site/index.html
+```
+
+### Step 2 — Locate the engine bundle
+
+The Knowledge Atlas engine is a pre-bundled CJS file committed inside the `ma-agents` package. Resolve it in this order:
+
+1. **Installed package resolution (preferred):** Use Node.js module resolution to locate the bundle:
+   ```js
+   require.resolve('ma-agents/lib/knowledge-atlas/dist/atlas.cjs')
+   ```
+   This works when `ma-agents` is installed as a dependency or globally via `npx`.
+
+2. **Dev-local fallback:** If the skill is being run from within the `ma-agents` repo itself (e.g., during development), use a path relative to the skill file:
+   ```
+   <skill_dir>/../../../../lib/knowledge-atlas/dist/atlas.cjs
+   ```
+   where `<skill_dir>` is the directory containing this SKILL.md.
+
+3. If neither path resolves to an existing file, abort with:
+   ```
+   ERROR: Cannot locate atlas.cjs. Ensure ma-agents is installed:
+     npm install -g ma-agents
+     # or: npm install --save-dev ma-agents
+   ```
+
+### Step 3 — Run the engine
+
+Execute the bundled engine as a Node.js subprocess. Pass `atlasPath` and
+`projectRoot` as ARGUMENT-ARRAY elements (never interpolate them into a shell
+string) so paths containing spaces, quotes, or shell metacharacters cannot be
+misparsed or injected:
+
+```js
+const { spawnSync } = require('node:child_process');
+const res = spawnSync(process.execPath, [atlasPath, projectRoot], {
+  encoding: 'utf-8',
+  // No `shell: true` — args go directly to the OS exec, not a shell.
+});
+if (res.status !== 0) {
+  // Report res.stderr and abort.
+  throw new Error(`atlas.cjs failed (exit ${res.status}): ${res.stderr}`);
+}
+const indexHtmlPath = res.stdout.trim(); // engine prints the index.html path
+```
+
+- The engine writes `_bmad-output/knowledge-site/index.html`.
+- It prints the path to `stdout` on success.
+- It exits with code 0 on success, non-zero on failure (error on stderr).
+- It never modifies any source file — output is isolated to `_bmad-output/knowledge-site/`.
+
+If the engine exits non-zero, report the stderr output and abort.
+
+### Step 4 — Open the generated site
+
+After successful generation, open `_bmad-output/knowledge-site/index.html` using
+the appropriate method for the current environment. Use `execFile`/`spawn` with
+an ARGUMENT ARRAY — never build a shell command string with the path
+interpolated, which would be an injection vector:
+
+**VSCode detection** (open in the editor):
+```js
+const { execFile } = require('node:child_process');
+if (process.env.TERM_PROGRAM === 'vscode' || process.env.VSCODE_PID !== undefined) {
+  execFile('code', [indexHtmlPath]); // path is a discrete arg, not concatenated
+}
+```
+
+**System default browser** (for all other environments) — pass the path as an
+arg-array element to the platform opener:
+- **Windows:** `execFile('cmd', ['/c', 'start', '', indexHtmlPath])`
+- **macOS:**   `execFile('open', [indexHtmlPath])`
+- **Linux:**   `execFile('xdg-open', [indexHtmlPath])`
+
+Report the output path to the user regardless of whether the browser opens:
+```
+Knowledge Atlas generated: <projectRoot>/_bmad-output/knowledge-site/index.html
+```
+
+---
+
+## Gitignore policy
+
+The `_bmad-output/knowledge-site/` directory is automatically gitignored when BMAD installs into a project (via `ensureKnowledgeSiteIgnored`). If it is not already ignored, add the following line to `.gitignore`:
+
+```
+_bmad-output/knowledge-site/
+```
+
+---
+
+## Notes
+
+- **Offline by construction:** The generated `index.html` is fully self-contained — no external URLs, no CDN links, no web fonts. It can be opened from a local filesystem in any browser.
+- **Deterministic output:** Pin `SOURCE_DATE_EPOCH` (Unix seconds) to get byte-identical output across runs:
+  ```bash
+  SOURCE_DATE_EPOCH=1700000000 node atlas.cjs "<projectRoot>"
+  ```
+- **No per-project install:** The engine (`atlas.cjs`) is pre-bundled in `ma-agents`. Consuming projects never run `npm install` for the Atlas engine.

package/lib/bmad-extension-plugin/skills/bmad-knowledge/bmad-skill-manifest.yaml

@@ -0,0 +1,3 @@
+type: skill
+name: bmad-knowledge
+module: ma-skills

package/lib/bmad-extension-plugin/skills/module-help.csv

@@ -60,3 +60,4 @@ ma-skills,4-implementation,Close Sprint,close-sprint,,skill:close-sprint,close-s
 ma-skills,4-implementation,Prioritize Backlog,prioritize-backlog,,skill:prioritize-backlog,prioritize-backlog,false,bmm-sm,,"Reprioritize backlog items using multiple criteria -- severity, business value, dependencies, type, age.",_bmad-output/implementation-artifacts,"backlog",
 ma-skills,4-implementation,Project Context Expansion,project-context-expansion,,skill:project-context-expansion,project-context-expansion,false,bmm-sm,,"Post-retrospective companion to update project-context.md with new rules.",_bmad-output,"project context",
 ma-skills,4-implementation,Requirements Quality Audit,sqa-requirements-quality,,skill:sqa-requirements-quality,sqa-requirements-quality,false,bmm-qa,,"Evaluate project requirements against 14 quality criteria — produces a per-requirement audit table, missing-elements section, and overall quality score.",_bmad-output,"quality report",
+ma-skills,anytime,Knowledge Atlas,bmad-knowledge,,skill:bmad-knowledge,bmad-knowledge,false,bmm-sm,,"Generate a self-contained Knowledge Atlas HTML site from project planning and implementation artifacts.",_bmad-output/knowledge-site,"knowledge site",

package/lib/bmad.js

@@ -307,6 +307,21 @@ function ensurePluginStageGitignoredForProject(projectRoot) {
             );
         }
     }
+
+    // Story 29.1 — ensure the Knowledge Atlas site output directory is gitignored.
+    // `_bmad-output/knowledge-site/` is transient (regenerated on each skill run)
+    // and must not be committed. `_bmad-output/` itself remains tracked.
+    if (typeof installer.ensureKnowledgeSiteIgnored === 'function') {
+        try {
+            installer.ensureKnowledgeSiteIgnored(projectRoot);
+        } catch (err) {
+            console.warn(
+                chalk.yellow(
+                    `  Warning: could not update ${path.join(projectRoot, '.gitignore')} with knowledge-site/ entry: ${err.message}`
+                )
+            );
+        }
+    }
 }
 
 /**

package/lib/installer.js

@@ -487,6 +487,93 @@ function ensureBmadDirIgnored(projectRoot) {
   );
 }
 
+// Story 29.1 — Knowledge Atlas site output is generated into
+// `_bmad-output/knowledge-site/` on every skill invocation. This directory is
+// transient (regenerated each run) and should never be committed. It is gitignored
+// by the same append-only, idempotent policy as the plugin stage and _bmad/ tree.
+//
+// IMPORTANT: `_bmad-output/` itself is intentionally kept tracked (project knowledge
+// artifacts live there). Only the nested `knowledge-site/` subdirectory is ignored.
+const KNOWLEDGE_SITE_DIR_NAME = '_bmad-output/knowledge-site';
+const KNOWLEDGE_SITE_PATTERNS = [
+  KNOWLEDGE_SITE_DIR_NAME,                  // _bmad-output/knowledge-site
+  `${KNOWLEDGE_SITE_DIR_NAME}/`,            // _bmad-output/knowledge-site/
+  `/${KNOWLEDGE_SITE_DIR_NAME}`,            // /_bmad-output/knowledge-site
+  `/${KNOWLEDGE_SITE_DIR_NAME}/`,           // /_bmad-output/knowledge-site/
+];
+const KNOWLEDGE_SITE_CANONICAL_ENTRY = `${KNOWLEDGE_SITE_DIR_NAME}/`;
+
+/**
+ * Ensure `_bmad-output/knowledge-site/` is present in the target project's
+ * `.gitignore`. Mirrors the append-only, idempotent, EOL-preserving contract
+ * of `ensurePluginStageIgnored` and `ensureBmadDirIgnored`.
+ *
+ *  - If `.gitignore` is absent, create it with the single canonical entry.
+ *  - If any active (non-comment) line already matches any KNOWLEDGE_SITE_PATTERNS
+ *    variant, do nothing (idempotent).
+ *  - Otherwise, append `KNOWLEDGE_SITE_CANONICAL_ENTRY` preserving the file's
+ *    existing EOL style.
+ *
+ * Non-fatal: EACCES / EROFS are swallowed by the caller in lib/bmad.js so an
+ * unwritable .gitignore never aborts the install. This function throws on other
+ * I/O errors so the caller can decide whether to swallow.
+ *
+ * Defensive: no-op on falsy / non-string projectRoot.
+ *
+ * @param {string} projectRoot - Absolute path to the target project root.
+ */
+function ensureKnowledgeSiteIgnored(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
+      // Exact match on any canonical variant.
+      if (KNOWLEDGE_SITE_PATTERNS.includes(line)) return true;
+      // Broader coverage: if a parent entry (`_bmad-output` / `_bmad-output/`,
+      // optionally anchored with a leading slash) is already ignored, then the
+      // nested `knowledge-site/` is implicitly covered — appending our entry
+      // would be redundant. Match the directory form precisely so we never
+      // mistake an unrelated entry like `_bmad-output-archive` for a parent.
+      const normalized = line.replace(/^\//, '').replace(/\/$/, '');
+      if (normalized === '_bmad-output') return true;
+      return false;
+    });
+    if (alreadyPresent) return; // idempotent no-op
+  }
+
+  // Preserve the file's existing line-ending style; default to LF for new files.
+  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 += KNOWLEDGE_SITE_CANONICAL_ENTRY + eol;
+
+  fs.writeFileSync(gitignorePath, next, 'utf-8');
+  console.log(
+    chalk.green(
+      `${KNOWLEDGE_SITE_CANONICAL_ENTRY} added to .gitignore (Knowledge Atlas site output — regenerated on each run)`
+    )
+  );
+}
+
 function ensureManifest(installPath, agentId, scope) {
   let manifest = readManifest(installPath);
   if (!manifest) {
@@ -2260,6 +2347,7 @@ module.exports = {
   ensureBmadOutputTracked,
   ensurePluginStageIgnored,
   ensureBmadDirIgnored,
+  ensureKnowledgeSiteIgnored,
   reconcileAgentsSharedSkills,
   getAgentsSharedSkillAgentIds,
   generateSkillsManifest,