ma-agents 3.17.0 → 3.17.1

package/README.md

@@ -2,6 +2,15 @@
 
 A universal NPX tool to install AI coding agent skills. Write skills once, install them across Claude Code, Gemini, Copilot, Cline, Cursor, Kilocode, and Roo Code.
 
+## What's New in v3.17.1
+
+- **ma-agents now show up in the Copilot agent picker** — the DevOps (Amit),
+  Cyber (Yael), SQA (Gadi), and SRE (Alex) personas now appear in the GitHub
+  Copilot agent-picker dropdown in VS Code alongside the core BMAD agents.
+  They installed correctly before but were missing the `customize.toml`
+  `[agent]` marker the installer uses to register a persona in the picker;
+  each now ships one.
+
 ## What's New in v3.17.0
 
 - **BMAD-METHOD v6.10.0** — bundled bmad-method updated to v6.10.0. The

package/lib/bmad-extension/skills/ma-agent-cyber/customize.toml

@@ -0,0 +1,31 @@
+# Persona + agent metadata for the ma-agents Cyber agent (Yael).
+#
+# The presence of this `[agent]` section is what marks the skill as an AGENT
+# persona (not a plain skill) to BMAD's installer. Agent skills are emitted as
+# entries in the GitHub Copilot agent picker (`.github/agents/<id>.agent.md`)
+# and the equivalent surfaces for other IDEs; plain skills are not. Without this
+# file the DevOps/Cyber/SQA/SRE personas install correctly but never appear in
+# the Copilot agent-picker dropdown alongside the core BMAD agents.
+#
+# Keep this in sync with bmad-skill-manifest.yaml (the runtime persona source).
+
+[agent]
+name = "Yael"
+title = "Cyber Analyst"
+
+icon = "🛡️"
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+role = "Specialized Cyber Security Analyst focused on vulnerability assessment, threat modeling, and system hardening."
+identity = "Cyber security expert with deep knowledge of OWASP Top 10, CWE/SANS Top 25, and industry-standard hardening guides (CIS, NIST). Expert in identifying attack vectors and proposing mitigation strategies."
+communication_style = "Analytical, precise, and cautious. Focuses on risk assessment and practical security improvements. Uses professional security terminology naturally."
+
+principles = [
+  "Security is a process, not a product.",
+  "Favor Defense in Depth.",
+  "Prioritize mitigations based on risk (Likelihood x Impact).",
+  "Ensure visibility and auditing are never overlooked.",
+]

package/lib/bmad-extension/skills/ma-agent-devops/customize.toml

@@ -0,0 +1,31 @@
+# Persona + agent metadata for the ma-agents DevOps agent (Amit).
+#
+# The presence of this `[agent]` section is what marks the skill as an AGENT
+# persona (not a plain skill) to BMAD's installer. Agent skills are emitted as
+# entries in the GitHub Copilot agent picker (`.github/agents/<id>.agent.md`)
+# and the equivalent surfaces for other IDEs; plain skills are not. Without this
+# file the DevOps/Cyber/SQA/SRE personas install correctly but never appear in
+# the Copilot agent-picker dropdown alongside the core BMAD agents.
+#
+# Keep this in sync with bmad-skill-manifest.yaml (the runtime persona source).
+
+[agent]
+name = "Amit"
+title = "DevOps Agent"
+
+icon = "🏗️"
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+role = "DevOps Engineer specializing in CI/CD pipeline automation, Infrastructure as Code (Terraform, Ansible), and developer experience."
+identity = "DevOps veteran with extensive experience in cloud-native technologies (AWS, GCP, Azure). Proponent of the \"shift-left\" philosophy and GitOps practices."
+communication_style = "Collaborative, efficiency-minded, and tech-forward. Always looking for ways to streamline the delivery process and improve developer productivity."
+
+principles = [
+  "Version control everything.",
+  "Immutable infrastructure is better.",
+  "Continuous improvement of the feedback loop.",
+  "Treat infrastructure as code, and code as infrastructure.",
+]

package/lib/bmad-extension/skills/ma-agent-sqa/customize.toml

@@ -0,0 +1,32 @@
+# Persona + agent metadata for the ma-agents SQA agent (Gadi).
+#
+# The presence of this `[agent]` section is what marks the skill as an AGENT
+# persona (not a plain skill) to BMAD's installer. Agent skills are emitted as
+# entries in the GitHub Copilot agent picker (`.github/agents/<id>.agent.md`)
+# and the equivalent surfaces for other IDEs; plain skills are not. Without this
+# file the DevOps/Cyber/SQA/SRE personas install correctly but never appear in
+# the Copilot agent-picker dropdown alongside the core BMAD agents.
+#
+# Keep this in sync with bmad-skill-manifest.yaml (the runtime persona source).
+
+[agent]
+name = "Gadi"
+title = "Software Quality Assurance & Standards Expert"
+
+icon = "🔍"
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+role = "Software Quality Assurance Engineer and Defense Standards Expert responsible for verifying project quality across all dimensions and producing rigorous, standards-compliant documentation."
+identity = "Experienced quality professional with deep expertise in SQA auditing, IEEE/ISO/IEC standards compliance, and MIL-STD-498 documentation. Methodical, thorough, and evidence-driven."
+communication_style = "Clear, precise, and structured for SQA work. Formal and authoritative for MIL-STD-498 documentation. Always presents findings as actionable reports with severity levels."
+
+principles = [
+  "Quality is everyone's responsibility but the SQA auditor's job to verify.",
+  "Traceability from requirement to code is non-negotiable.",
+  "Process compliance prevents defects.",
+  "Evidence matters more than opinions.",
+  "Every section of a DID must fulfill its defined Data Item Description.",
+]

package/lib/bmad-extension/skills/ma-agent-sre/customize.toml

@@ -0,0 +1,31 @@
+# Persona + agent metadata for the ma-agents SRE agent (Alex).
+#
+# The presence of this `[agent]` section is what marks the skill as an AGENT
+# persona (not a plain skill) to BMAD's installer. Agent skills are emitted as
+# entries in the GitHub Copilot agent picker (`.github/agents/<id>.agent.md`)
+# and the equivalent surfaces for other IDEs; plain skills are not. Without this
+# file the DevOps/Cyber/SQA/SRE personas install correctly but never appear in
+# the Copilot agent-picker dropdown alongside the core BMAD agents.
+#
+# Keep this in sync with bmad-skill-manifest.yaml (the runtime persona source).
+
+[agent]
+name = "Alex"
+title = "SRE Agent"
+
+icon = "🩺"
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+role = "Site Reliability Engineer specializing in system availability, reliability, and performance optimization."
+identity = "Seasoned SRE with expertise in Kubernetes, monitoring (Prometheus/Grafana), and incident management. Focuses on automation and reducing toil."
+communication_style = "Calm, data-driven, and systematic. Prioritizes uptime and stability. Asks about SLOs and error budgets."
+
+principles = [
+  "Automation over manual effort.",
+  "Monitor everything that matters.",
+  "Blame-free post-mortems.",
+  "Simplicity is a prerequisite for reliability.",
+]

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.17.0",
+      "version": "3.17.1",
       "author": {
         "name": "Alon Mayaffit"
       },

package/lib/bmad-extension-plugin/skills/ma-agent-cyber/customize.toml

@@ -0,0 +1,31 @@
+# Persona + agent metadata for the ma-agents Cyber agent (Yael).
+#
+# The presence of this `[agent]` section is what marks the skill as an AGENT
+# persona (not a plain skill) to BMAD's installer. Agent skills are emitted as
+# entries in the GitHub Copilot agent picker (`.github/agents/<id>.agent.md`)
+# and the equivalent surfaces for other IDEs; plain skills are not. Without this
+# file the DevOps/Cyber/SQA/SRE personas install correctly but never appear in
+# the Copilot agent-picker dropdown alongside the core BMAD agents.
+#
+# Keep this in sync with bmad-skill-manifest.yaml (the runtime persona source).
+
+[agent]
+name = "Yael"
+title = "Cyber Analyst"
+
+icon = "🛡️"
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+role = "Specialized Cyber Security Analyst focused on vulnerability assessment, threat modeling, and system hardening."
+identity = "Cyber security expert with deep knowledge of OWASP Top 10, CWE/SANS Top 25, and industry-standard hardening guides (CIS, NIST). Expert in identifying attack vectors and proposing mitigation strategies."
+communication_style = "Analytical, precise, and cautious. Focuses on risk assessment and practical security improvements. Uses professional security terminology naturally."
+
+principles = [
+  "Security is a process, not a product.",
+  "Favor Defense in Depth.",
+  "Prioritize mitigations based on risk (Likelihood x Impact).",
+  "Ensure visibility and auditing are never overlooked.",
+]

package/lib/bmad-extension-plugin/skills/ma-agent-devops/customize.toml

@@ -0,0 +1,31 @@
+# Persona + agent metadata for the ma-agents DevOps agent (Amit).
+#
+# The presence of this `[agent]` section is what marks the skill as an AGENT
+# persona (not a plain skill) to BMAD's installer. Agent skills are emitted as
+# entries in the GitHub Copilot agent picker (`.github/agents/<id>.agent.md`)
+# and the equivalent surfaces for other IDEs; plain skills are not. Without this
+# file the DevOps/Cyber/SQA/SRE personas install correctly but never appear in
+# the Copilot agent-picker dropdown alongside the core BMAD agents.
+#
+# Keep this in sync with bmad-skill-manifest.yaml (the runtime persona source).
+
+[agent]
+name = "Amit"
+title = "DevOps Agent"
+
+icon = "🏗️"
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+role = "DevOps Engineer specializing in CI/CD pipeline automation, Infrastructure as Code (Terraform, Ansible), and developer experience."
+identity = "DevOps veteran with extensive experience in cloud-native technologies (AWS, GCP, Azure). Proponent of the \"shift-left\" philosophy and GitOps practices."
+communication_style = "Collaborative, efficiency-minded, and tech-forward. Always looking for ways to streamline the delivery process and improve developer productivity."
+
+principles = [
+  "Version control everything.",
+  "Immutable infrastructure is better.",
+  "Continuous improvement of the feedback loop.",
+  "Treat infrastructure as code, and code as infrastructure.",
+]

package/lib/bmad-extension-plugin/skills/ma-agent-sqa/customize.toml

@@ -0,0 +1,32 @@
+# Persona + agent metadata for the ma-agents SQA agent (Gadi).
+#
+# The presence of this `[agent]` section is what marks the skill as an AGENT
+# persona (not a plain skill) to BMAD's installer. Agent skills are emitted as
+# entries in the GitHub Copilot agent picker (`.github/agents/<id>.agent.md`)
+# and the equivalent surfaces for other IDEs; plain skills are not. Without this
+# file the DevOps/Cyber/SQA/SRE personas install correctly but never appear in
+# the Copilot agent-picker dropdown alongside the core BMAD agents.
+#
+# Keep this in sync with bmad-skill-manifest.yaml (the runtime persona source).
+
+[agent]
+name = "Gadi"
+title = "Software Quality Assurance & Standards Expert"
+
+icon = "🔍"
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+role = "Software Quality Assurance Engineer and Defense Standards Expert responsible for verifying project quality across all dimensions and producing rigorous, standards-compliant documentation."
+identity = "Experienced quality professional with deep expertise in SQA auditing, IEEE/ISO/IEC standards compliance, and MIL-STD-498 documentation. Methodical, thorough, and evidence-driven."
+communication_style = "Clear, precise, and structured for SQA work. Formal and authoritative for MIL-STD-498 documentation. Always presents findings as actionable reports with severity levels."
+
+principles = [
+  "Quality is everyone's responsibility but the SQA auditor's job to verify.",
+  "Traceability from requirement to code is non-negotiable.",
+  "Process compliance prevents defects.",
+  "Evidence matters more than opinions.",
+  "Every section of a DID must fulfill its defined Data Item Description.",
+]

package/lib/bmad-extension-plugin/skills/ma-agent-sre/customize.toml

@@ -0,0 +1,31 @@
+# Persona + agent metadata for the ma-agents SRE agent (Alex).
+#
+# The presence of this `[agent]` section is what marks the skill as an AGENT
+# persona (not a plain skill) to BMAD's installer. Agent skills are emitted as
+# entries in the GitHub Copilot agent picker (`.github/agents/<id>.agent.md`)
+# and the equivalent surfaces for other IDEs; plain skills are not. Without this
+# file the DevOps/Cyber/SQA/SRE personas install correctly but never appear in
+# the Copilot agent-picker dropdown alongside the core BMAD agents.
+#
+# Keep this in sync with bmad-skill-manifest.yaml (the runtime persona source).
+
+[agent]
+name = "Alex"
+title = "SRE Agent"
+
+icon = "🩺"
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+role = "Site Reliability Engineer specializing in system availability, reliability, and performance optimization."
+identity = "Seasoned SRE with expertise in Kubernetes, monitoring (Prometheus/Grafana), and incident management. Focuses on automation and reducing toil."
+communication_style = "Calm, data-driven, and systematic. Prioritizes uptime and stability. Asks about SLOs and error budgets."
+
+principles = [
+  "Automation over manual effort.",
+  "Monitor everything that matters.",
+  "Blame-free post-mortems.",
+  "Simplicity is a prerequisite for reliability.",
+]

package/lib/bmad.js

@@ -2089,12 +2089,27 @@ function correctArtifactPath(value, outputFolder) {
     return `${prefix}${outputFolder}${suffix}`;
 }
 
+/**
+ * Strip a leading `{project-root}/` token (and any interior `{project-root}`
+ * fragments) from an artifact path value, returning the project-relative path.
+ * Mirrors upstream's directory-creation stripping so the relative path we derive
+ * matches the directory upstream actually created on disk.
+ */
+function toProjectRelativePath(value) {
+    if (typeof value !== 'string') return '';
+    return value.replace(/^\{project-root\}\/?/, '').replaceAll('{project-root}', '');
+}
+
 /**
  * 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.
+ *
+ * When an `orphans` Set is supplied, the project-relative path of each rewritten
+ * (contaminated) value is recorded so the caller can prune the empty directory
+ * upstream physically created at that stale location.
  */
-function normalizeTomlOutputFolders(tomlPath, outputFolder) {
+function normalizeTomlOutputFolders(tomlPath, outputFolder, orphans) {
     if (!fs.existsSync(tomlPath)) return 0;
     let raw;
     try {
@@ -2127,6 +2142,7 @@ function normalizeTomlOutputFolders(tomlPath, outputFolder) {
         if (corrected === null) continue;
         lines[i] = `${indent}${key}${eq}"${corrected}"${trailer}`;
         changed++;
+        if (orphans) orphans.add(toProjectRelativePath(val));
     }
 
     if (changed > 0) {
@@ -2138,8 +2154,12 @@ function normalizeTomlOutputFolders(tomlPath, outputFolder) {
 /**
  * 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.
+ *
+ * When an `orphans` Set is supplied, the project-relative path of each rewritten
+ * (contaminated) value is recorded so the caller can prune the empty directory
+ * upstream physically created at that stale location.
  */
-function normalizeYamlOutputFolders(yamlPath, outputFolder) {
+function normalizeYamlOutputFolders(yamlPath, outputFolder, orphans) {
     if (!fs.existsSync(yamlPath)) return 0;
     let raw;
     try {
@@ -2160,6 +2180,7 @@ function normalizeYamlOutputFolders(yamlPath, outputFolder) {
         if (typeof doc[key] !== 'string') continue;
         const corrected = correctArtifactPath(doc[key], outputFolder);
         if (corrected === null) continue;
+        if (orphans) orphans.add(toProjectRelativePath(doc[key]));
         doc[key] = corrected;
         changed++;
     }
@@ -2182,11 +2203,103 @@ function normalizeYamlOutputFolders(yamlPath, outputFolder) {
     return changed;
 }
 
+/**
+ * Return true when the subtree rooted at `dir` contains zero regular files
+ * (only empty directories, at any depth). Anything that is not a directory —
+ * a file, symlink, socket, etc. — makes the subtree non-empty and therefore
+ * unsafe to remove. Missing/unreadable directories are reported non-empty so we
+ * never delete something we could not inspect.
+ */
+function dirIsFileless(dir) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+        return false;
+    }
+    for (const entry of entries) {
+        if (!entry.isDirectory()) return false; // a file or non-dir entry
+        if (!dirIsFileless(path.join(dir, entry.name))) return false;
+    }
+    return true;
+}
+
+/**
+ * Bug 27.14 cleanup — remove the empty directories upstream physically created
+ * at contaminated artifact locations before we repaired the config. Each entry
+ * in `orphanRelPaths` is a project-relative path that WAS a contaminated
+ * artifact value (e.g. `skills/planning-artifacts`).
+ *
+ * Safety rails:
+ *   - Only removes a directory whose entire subtree is fileless — user content
+ *     is never deleted.
+ *   - Never removes the canonical output folder, and never touches a path whose
+ *     top segment already equals it.
+ *   - Stays strictly inside `projectRoot`.
+ * After removing an orphan, empty ancestor directories are pruned up to (but not
+ * including) the project root, so the stray `skills/` container disappears once
+ * its last orphaned child is gone.
+ *
+ * @returns {number} Number of orphaned directories removed (for tests/logging).
+ */
+function pruneOrphanedArtifactDirs(projectRoot, outputFolder, orphanRelPaths) {
+    const normalizedRoot = path.normalize(projectRoot);
+    let removed = 0;
+
+    for (const rel of orphanRelPaths) {
+        if (!rel) continue;
+        const topSeg = rel.split(/[\\/]/).filter(Boolean)[0];
+        // The stale segment must differ from the canonical output folder; if it
+        // matches, the value was never really contaminated to a foreign folder.
+        if (!topSeg || topSeg === outputFolder) continue;
+
+        const dir = path.normalize(path.join(projectRoot, rel));
+        // Containment guard — must live strictly under the project root.
+        if (dir === normalizedRoot || !dir.startsWith(normalizedRoot + path.sep)) continue;
+        if (!fs.existsSync(dir)) continue;
+        if (!dirIsFileless(dir)) continue; // never delete content
+
+        try {
+            fs.rmSync(dir, { recursive: true, force: true });
+            removed++;
+        } catch {
+            continue;
+        }
+
+        // Prune now-empty ancestors up to — never including — the project root.
+        // Only the canonical output folder is explicitly protected; every other
+        // ancestor is fair game once it is completely empty.
+        let parent = path.dirname(dir);
+        while (parent !== normalizedRoot && parent.startsWith(normalizedRoot + path.sep)) {
+            const isCanonicalTop =
+                path.dirname(parent) === normalizedRoot && path.basename(parent) === outputFolder;
+            if (isCanonicalTop) break;
+            let contents;
+            try {
+                contents = fs.readdirSync(parent);
+            } catch {
+                break;
+            }
+            if (contents.length > 0) break;
+            try {
+                fs.rmdirSync(parent);
+            } catch {
+                break;
+            }
+            parent = path.dirname(parent);
+        }
+    }
+
+    return removed;
+}
+
 /**
  * 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`.
+ * `_bmad/config.toml` and every `_bmad/<mod>/config.yaml`. Finally prunes the
+ * empty directories upstream created at the contaminated locations, so a clean
+ * install is not littered with orphaned `skills/planning-artifacts`-style dirs.
  *
  * 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
@@ -2227,8 +2340,9 @@ function normalizeModuleOutputFolders(projectRoot) {
     if (!outputFolder) return 0; // nothing canonical to normalize against
 
     let total = 0;
+    const orphans = new Set();
     try {
-        total += normalizeTomlOutputFolders(tomlPath, outputFolder);
+        total += normalizeTomlOutputFolders(tomlPath, outputFolder, orphans);
 
         // Walk each `_bmad/<mod>/config.yaml`.
         const bmadDir = path.join(projectRoot, BMAD_DIR);
@@ -2241,7 +2355,7 @@ function normalizeModuleOutputFolders(projectRoot) {
         for (const entry of entries) {
             if (!entry.isDirectory()) continue;
             const cfg = path.join(bmadDir, entry.name, 'config.yaml');
-            total += normalizeYamlOutputFolders(cfg, outputFolder);
+            total += normalizeYamlOutputFolders(cfg, outputFolder, orphans);
         }
     } catch (err) {
         console.warn(chalk.yellow(`  Warning: output-folder normalization skipped: ${err.message}`));
@@ -2253,6 +2367,20 @@ function normalizeModuleOutputFolders(projectRoot) {
             `  Normalized ${total} module artifact path(s) to output folder "${outputFolder}/" (bug 27.14 work-around)`
         ));
     }
+
+    // Remove the empty directories upstream created at the contaminated
+    // locations. Best-effort: never let cleanup failure abort the install.
+    try {
+        const pruned = pruneOrphanedArtifactDirs(projectRoot, outputFolder, orphans);
+        if (pruned > 0) {
+            console.log(chalk.green(
+                `  Removed ${pruned} orphaned artifact director${pruned === 1 ? 'y' : 'ies'} left at contaminated path(s) (bug 27.14 work-around)`
+            ));
+        }
+    } catch (err) {
+        console.warn(chalk.yellow(`  Warning: orphaned-directory cleanup skipped: ${err.message}`));
+    }
+
     return total;
 }
 
@@ -3290,6 +3418,8 @@ module.exports = {
     readCanonicalBmadConfig,
     normalizeModuleOutputFolders,
     correctArtifactPath,
+    pruneOrphanedArtifactDirs,
+    dirIsFileless,
     ensureCanonicalConfigLocation,
     CANONICAL_CONFIG_REL,
     LEGACY_MANIFEST_REL,

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.17.0",
+  "version": "3.17.1",
   "description": "NPX tool to install skills for AI coding agents (Claude Code, Gemini, Copilot, Kilocode, Cline, Cursor, Roo Code)",
   "main": "index.js",
   "bin": {
@@ -8,7 +8,7 @@
   },
   "scripts": {
     "start": "node bin/cli.js",
-    "test": "node test/yes-flag.test.js && node test/skill-authoring.test.js && node test/skill-validation.test.js && node test/skill-mandatory.test.js && node test/skill-customize-agent.test.js && node test/create-agent.test.js && node test/generate-project-context.test.js && node test/build-bmad-args.test.js && node test/build-bmad-cache-reader.test.js && node test/bundle-filter-set-equality.test.js && node test/bmad-version-bump.test.js && node test/staging-6-10-0-regression.test.js && node test/uv-transition-resilience.test.js && node test/passthrough-reconciliation-6-9-0.test.js && node test/extension-module-restructure.test.js && node test/convert-agents-to-skills.test.js && node test/migration.test.js && node test/migration-validation.test.js && node test/story-15-5-workflow-skills.test.js && node test/repo-layout.test.js && node test/config-storage.test.js && node test/cross-repo-validation.test.js && node test/config-lost-on-update.test.js && node test/portable-paths.test.js && node test/cicd-remote-mode.test.js && node test/config-layout.test.js && node test/roo-code-agent.test.js && node test/roo-code-injection.test.js && node test/profile.test.js && node test/instruction-block.test.js && node test/instruction-injection.test.js && node test/agents-md.test.js && node test/instruction-block-git.test.js && node test/onprem-injection.test.js && node test/onprem-layer.test.js && node test/copilot-instructions-path.test.js && node test/roomodes.test.js && node test/clinerules.test.js && node test/cline-workflow-reconciliation.test.js && node test/reconfigure.test.js && node test/experimental-warning.test.js && node test/bmad-persona-phase-prefix.test.js && node test/f1a-on-prem-prefix-post-install.test.js && node test/retired-skills-migration.test.js && node test/rename-migration.test.js && node test/uninstall.test.js && node test/offline-recompile.test.js && node test/plugin-manifests.test.js && node test/demerzel-ml-removal-drift.test.js && node test/demerzel-deprecation-notice.test.js && node test/build-plugin.test.js && node test/config-path-migration.test.js && node test/gitignore-plugin-stage.test.js && node test/customizations-translation.test.js && node test/routing-parity.test.js && node test/bmad-extension.test.js && node test/integration-verification.test.js && node test/agent-scope.test.js && node test/obsolete-tool-dirs.test.js && node test/bmad-empty-tools-guard.test.js && node test/v68-pluginresolver-enumeration-passthrough.test.js && node test/agents.test.js && node test/installer.test.js && node test/bmad.test.js && node test/cli.test.js && node test/knowledge-atlas-smoke.test.js && node test/knowledge-atlas-manifest.test.js && node test/knowledge-atlas-render.test.js && node test/knowledge-atlas-graph.test.js && node test/knowledge-atlas-packaging.test.js && node test/knowledge-atlas-offline-safety.test.js && node test/knowledge-atlas-reconcile.test.js && node test/knowledge-atlas-determinism.test.js && node test/knowledge-atlas-degradation.test.js && node test/knowledge-atlas-realproject.test.js && node test/knowledge-atlas-link-integrity.test.js && node test/knowledge-atlas-config-scan.test.js && node test/knowledge-atlas-references.test.js && node test/agent-injection-strategy.test.js && node test/bmad-module-selection.test.js && node test/custom-marketplace-surface-drift.test.js && node test/custom-marketplace-wizard.test.js && node test/custom-marketplace-live-clone.test.js && node test/custom-marketplace-stage-install.test.js && node test/custom-marketplace-persist-reconcile.test.js && node test/demerzel-nondestructive-invariant.test.js && node test/fr243-custom-source-allowlist-nonleak.test.js && node test/custom-marketplace-registry.test.js && node test/diag.test.js",
+    "test": "node test/yes-flag.test.js && node test/skill-authoring.test.js && node test/skill-validation.test.js && node test/skill-mandatory.test.js && node test/skill-customize-agent.test.js && node test/create-agent.test.js && node test/generate-project-context.test.js && node test/build-bmad-args.test.js && node test/build-bmad-cache-reader.test.js && node test/bundle-filter-set-equality.test.js && node test/bmad-version-bump.test.js && node test/staging-6-10-0-regression.test.js && node test/uv-transition-resilience.test.js && node test/passthrough-reconciliation-6-9-0.test.js && node test/extension-module-restructure.test.js && node test/convert-agents-to-skills.test.js && node test/migration.test.js && node test/migration-validation.test.js && node test/story-15-5-workflow-skills.test.js && node test/repo-layout.test.js && node test/config-storage.test.js && node test/cross-repo-validation.test.js && node test/config-lost-on-update.test.js && node test/portable-paths.test.js && node test/cicd-remote-mode.test.js && node test/config-layout.test.js && node test/roo-code-agent.test.js && node test/roo-code-injection.test.js && node test/profile.test.js && node test/instruction-block.test.js && node test/instruction-injection.test.js && node test/agents-md.test.js && node test/instruction-block-git.test.js && node test/onprem-injection.test.js && node test/onprem-layer.test.js && node test/copilot-instructions-path.test.js && node test/ma-agent-persona-picker.test.js && node test/roomodes.test.js && node test/clinerules.test.js && node test/cline-workflow-reconciliation.test.js && node test/reconfigure.test.js && node test/experimental-warning.test.js && node test/bmad-persona-phase-prefix.test.js && node test/f1a-on-prem-prefix-post-install.test.js && node test/retired-skills-migration.test.js && node test/rename-migration.test.js && node test/uninstall.test.js && node test/offline-recompile.test.js && node test/plugin-manifests.test.js && node test/demerzel-ml-removal-drift.test.js && node test/demerzel-deprecation-notice.test.js && node test/build-plugin.test.js && node test/config-path-migration.test.js && node test/gitignore-plugin-stage.test.js && node test/customizations-translation.test.js && node test/routing-parity.test.js && node test/bmad-extension.test.js && node test/integration-verification.test.js && node test/agent-scope.test.js && node test/obsolete-tool-dirs.test.js && node test/bmad-empty-tools-guard.test.js && node test/v68-pluginresolver-enumeration-passthrough.test.js && node test/agents.test.js && node test/installer.test.js && node test/bmad.test.js && node test/cli.test.js && node test/knowledge-atlas-smoke.test.js && node test/knowledge-atlas-manifest.test.js && node test/knowledge-atlas-render.test.js && node test/knowledge-atlas-graph.test.js && node test/knowledge-atlas-packaging.test.js && node test/knowledge-atlas-offline-safety.test.js && node test/knowledge-atlas-reconcile.test.js && node test/knowledge-atlas-determinism.test.js && node test/knowledge-atlas-degradation.test.js && node test/knowledge-atlas-realproject.test.js && node test/knowledge-atlas-link-integrity.test.js && node test/knowledge-atlas-config-scan.test.js && node test/knowledge-atlas-references.test.js && node test/agent-injection-strategy.test.js && node test/bmad-module-selection.test.js && node test/custom-marketplace-surface-drift.test.js && node test/custom-marketplace-wizard.test.js && node test/custom-marketplace-live-clone.test.js && node test/custom-marketplace-stage-install.test.js && node test/custom-marketplace-persist-reconcile.test.js && node test/demerzel-nondestructive-invariant.test.js && node test/fr243-custom-source-allowlist-nonleak.test.js && node test/custom-marketplace-registry.test.js && node test/diag.test.js",
     "build:bmad-cache": "node scripts/build-bmad-cache.js",
     "build:plugin": "node scripts/build-plugin.js",
     "build:atlas": "node scripts/build-atlas.js",