bmad-method 6.10.1-next.2 → 6.10.1-next.21

package/src/core-skills/bmad-review/scripts/word_metrics.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.10"
+# ///
+"""Exact word counts for a document, as JSON.
+
+Emits the document's total word count and a per-heading-section breakdown so
+an editorial review can ground word-impact estimates and reduction
+percentages in real numbers instead of guessing. Sections are delimited by
+markdown headings (# through ######); heading markers inside fenced code
+blocks are ignored (fences pair CommonMark-style: a fence closes only on a
+run of the same character at least as long, so ```` fences may embed ```
+examples). A word is any whitespace-separated token, plus one word per CJK
+character since those scripts do not space-delimit words. For non-markdown
+input the result is a single section holding the full text.
+"""
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+HEADING = re.compile(r"^(#{1,6})\s+(\S.*)$")
+FENCE = re.compile(r"^ {0,3}(`{3,}|~{3,})")
+CJK = re.compile(r"[぀-ヿ㐀-䶿一-鿿豈-﫿가-힯ｦ-ﾟ]")
+
+
+def word_count(text: str) -> int:
+    cjk = len(CJK.findall(text))
+    return cjk + len(CJK.sub(" ", text).split())
+
+
+def section_metrics(text: str) -> list[dict]:
+    sections = []
+    current = {"heading": "(preamble)", "level": 0, "body": []}
+    open_fence = None  # (char, length) while inside a fenced block
+    for line in text.splitlines():
+        fence = FENCE.match(line)
+        if fence:
+            marker = fence.group(1)
+            if open_fence is None:
+                open_fence = (marker[0], len(marker))
+            elif marker[0] == open_fence[0] and len(marker) >= open_fence[1] and line.strip() == marker:
+                open_fence = None
+            current["body"].append(line)
+            continue
+        match = None if open_fence else HEADING.match(line)
+        if match:
+            sections.append(current)
+            current = {
+                "heading": match.group(2).strip(),
+                "level": len(match.group(1)),
+                "body": [],
+            }
+        else:
+            current["body"].append(line)
+    sections.append(current)
+
+    out = []
+    for section in sections:
+        words = word_count("\n".join(section["body"]))
+        if section["heading"] == "(preamble)" and words == 0:
+            continue
+        out.append(
+            {"heading": section["heading"], "level": section["level"], "words": words}
+        )
+    return out
+
+
+def metrics(path: Path) -> dict:
+    text = path.read_text(encoding="utf-8", errors="replace")
+    return {
+        "file": str(path),
+        "total_words": word_count(text),
+        "sections": section_metrics(text),
+    }
+
+
+def main() -> int:
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8")  # JSON is UTF-8 regardless of locale code page
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("path", help="document to measure")
+    parser.add_argument("-o", "--output", help="write JSON here (default: stdout)")
+    args = parser.parse_args()
+
+    path = Path(args.path)
+    if not path.is_file():
+        print(f"error: not a readable file: {path}", file=sys.stderr)
+        return 2
+
+    result = json.dumps(metrics(path), indent=2, ensure_ascii=False)
+    if args.output:
+        Path(args.output).write_text(result + "\n", encoding="utf-8")
+    else:
+        print(result)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/src/core-skills/module-help.csv

@@ -3,12 +3,8 @@ Core,_meta,,,,,,,,,false,https://docs.bmad-method.org/llms.txt,
 Core,bmad-brainstorming,Brainstorming,BSP,Use early in ideation or when stuck generating ideas.,,,anytime,,,false,{output_folder}/brainstorming,brainstorming session
 Core,bmad-party-mode,Party Mode,PM,Orchestrate multi-agent discussions when you need multiple perspectives or want agents to collaborate.,,,anytime,,,false,,
 Core,bmad-help,BMad Help,BH,,,,anytime,,,false,,
-Core,bmad-index-docs,Index Docs,ID,Use when LLM needs to understand available docs without loading everything.,,,anytime,,,false,,
-Core,bmad-shard-doc,Shard Document,SD,Use when doc becomes too large (>500 lines) to manage effectively.,,[path],anytime,,,false,,
-Core,bmad-editorial-review-prose,Editorial Review - Prose,EP,Use after drafting to polish written content.,,[path],anytime,,,false,report located with target document,three-column markdown table with suggested fixes
-Core,bmad-editorial-review-structure,Editorial Review - Structure,ES,Use when doc produced from multiple subprocesses or needs structural improvement.,,[path],anytime,,,false,report located with target document,
-Core,bmad-review-adversarial-general,Adversarial Review,AR,"Use for quality assurance or before finalizing deliverables. Code Review in other modules runs this automatically, but also useful for document reviews.",,[path],anytime,,,false,,
-Core,bmad-review-edge-case-hunter,Edge Case Hunter Review,ECH,Use alongside adversarial review for orthogonal coverage — method-driven not attitude-driven.,,[path],anytime,,,false,,
-Core,bmad-spec,Spec,SP,"Use to distill any intent input (brief, PRD, transcript, brain dump, design folder, mixed multi-source) into a succinct, no-fluff SPEC.md contract + companions that downstream work derives from. Locks the WHAT before the HOW. Works for software, game design, research, editorial, policy, business, anything intent-bearing. Validation mode also available.",,[path],anytime,,,false,{output_folder}/specs/spec-{slug},SPEC.md + companion files
 Core,bmad-customize,BMad Customize,BC,"Use when you want to change how an agent or workflow behaves — add persistent facts, swap templates, insert activation hooks, or customize menus. Scans what's customizable, picks the right scope (agent vs workflow), writes the override to _bmad/custom/, and verifies the merge. No TOML hand-authoring required.",,,anytime,,,false,{project-root}/_bmad/custom,TOML override files
+Core,bmad-advanced-elicitation,Advanced Elicitation,AE,"Use at any checkpoint to push a just-produced draft, section, or plan past its first version — pick from a menu of elicitation methods (pre-mortem, first principles, red team, socratic) and apply the improvements.",,,anytime,,,false,,
+Core,bmad-review,Review,RV,"Use to review anything before it ships — a diff, branch, or uncommitted changes; a PRD, spec, story, or architecture doc; any prose document. Runs whichever installed lenses fit the content and reports findings in one shape: shipped lenses cover adversarial critique, edge cases, verification gaps, document structure (cuts, merges, moves), and prose copy-edit, and installs may add more. Reach for it to tighten a bloated or LLM-slop draft, pressure-test a plan before building, or check a change is adequately tested. Run every applicable lens or name the ones you want. Code Review in other modules calls it automatically.",,[path],anytime,,,false,,findings JSON array + markdown report
 Core,bmad-forge-idea,Forge Idea,FI,"Use to pressure-test and harden an idea — software, business, creative, research, or life — until it proves out, hardens into something buildable, or dies cheaply. Persona-driven interrogation; optional handoff to bmad-spec or bmad-quick-dev.",,,anytime,,,false,{output_folder}/forge,refined-idea brief (optional)
+Core,bmad-deep-recon,Deep Recon,RS,Decision-grade research three ways: draft a deep-research prompt for your own AI tool then process the returned report into a downstream-ready cited summary — or run the research directly via web fan-out. Types: market domain technical competitive user-voice academic-lit plus a select shape for choose-between decisions; claim verification and refresh lifecycle. Custom types via overrides.,,[type],anytime,,,false,{planning_artifacts}/research,research report/summary + optional html briefing

package/src/core-skills/module.yaml

@@ -31,3 +31,8 @@ output_folder:
   prompt: "Where should output files be saved?"
   default: "_bmad-output"
   result: "{project-root}/{value}"
+
+# The one directory created at install time. Everything else (module artifact
+# folders, project knowledge) is created lazily by the first skill that writes there.
+directories:
+  - "{output_folder}"

package/src/core-skills/v6-shims/README.md

@@ -0,0 +1,25 @@
+# v6 Deprecation Shims
+
+Skills in this folder are forwarders kept for backward compatibility with v6 skill IDs.
+Each one holds no logic of its own — it forwards to the skill that replaced it, pinning
+the legacy output contract so existing callers keep working.
+
+| Shim                              | Forwards to                              |
+| --------------------------------- | ---------------------------------------- |
+| `bmad-editorial-review`           | `bmad-review` (structure + prose lenses) |
+| `bmad-editorial-review-prose`     | `bmad-review` (prose lens)               |
+| `bmad-editorial-review-structure` | `bmad-review` (structure lens)           |
+| `bmad-review-adversarial-general` | `bmad-review` (adversarial lens)         |
+| `bmad-review-edge-case-hunter`    | `bmad-review` (edge-case lens)           |
+| `bmad-review-verification-gap`    | `bmad-review` (verification-gap lens)    |
+
+`bmad-editorial-review` keeps its `customize.toml` so existing team and user
+overrides still resolve; the shim forwards those resolved values to `bmad-review`.
+
+External module repos (gds, loop, tea, bmb, os-utils) still invoke these IDs, so they
+ship by default. Removal rides the v7 cut — never a 6.x minor.
+
+The folder is grouping only: the installer discovers skills recursively and installs each
+one under its own `name`, so nesting here does not change any installed path or skill ID.
+A future install option will let users include or exclude this folder before it is removed
+outright.

package/src/core-skills/v6-shims/bmad-editorial-review/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: bmad-editorial-review
+description: 'Deprecated — forwards to bmad-review.'
+---
+
+Merged into `bmad-review`. Invoke the `bmad-review` skill on the same content with the `structure` and `prose` lenses — both, structure first, so prose runs on top of the structure findings — unless the caller asked for a structure-only or prose-only review, in which case pass only that lens. Pass through any `also_consider` areas, and forward this skill's resolved `[workflow]` fields as pre-resolved values — but only those that resolved to something, since an empty value here means no legacy override exists and bmad-review's own default should stand: `reader_type`, `style_guide`, `review_guidance`, `output_preferences`, `persistent_facts`, `activation_steps_prepend`, `activation_steps_append`, `on_complete`, and `review_output_path` as the report path. Present the findings in the legacy shape: the two-pass findings table `| Pass | Original Text | Revised Text | Changes |` with the purpose/audience read above it and, when the structure pass ran, the reduction summary below it — and no other lens's output.

package/src/core-skills/v6-shims/bmad-editorial-review/customize.toml

@@ -0,0 +1,31 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Legacy override surface for bmad-editorial-review, which is deprecated and
+# forwards to bmad-review's `structure` and `prose` lenses. These keys exist
+# only so overrides written against the old skill keep resolving: the shim
+# resolves them here and passes them to bmad-review as pre-resolved values,
+# which bmad-review honors verbatim over its own.
+#
+# Every field is documented in bmad-review's customize.toml, which is where
+# new customization belongs. Defaults are empty here so the shim contributes
+# nothing of its own — an unset key falls through to bmad-review's default.
+#
+# Override files (not edited here):
+#   {project-root}/_bmad/custom/bmad-editorial-review.toml         (team)
+#   {project-root}/_bmad/custom/bmad-editorial-review.user.toml    (personal)
+#
+# Overrides merge per BMad structural rules: scalars win, arrays append.
+
+[workflow]
+
+activation_steps_prepend = []
+activation_steps_append = []
+persistent_facts = []
+review_guidance = []
+on_complete = ""
+output_preferences = ""
+reader_type = ""
+style_guide = ""
+
+# Where the findings table lands; forwarded as bmad-review's report path.
+review_output_path = ""

package/src/core-skills/v6-shims/bmad-editorial-review-prose/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: bmad-editorial-review-prose
+description: 'Deprecated — forwards to bmad-review.'
+---
+
+Merged into `bmad-review`. Invoke the `bmad-review` skill on the same content with only the `prose` lens, passing through the same inputs and any `also_consider` areas. Present the findings in the legacy shape: a three-column markdown table `| Original Text | Revised Text | Changes |` — no Pass column, no preamble above the table. If no issues are found, output exactly: `No editorial issues identified`.

package/src/core-skills/v6-shims/bmad-editorial-review-structure/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: bmad-editorial-review-structure
+description: 'Deprecated — forwards to bmad-review.'
+---
+
+Merged into `bmad-review`. Invoke the `bmad-review` skill on the same content with only the `structure` lens, passing through the same inputs and any `also_consider` areas. Present the findings in the legacy report shape: a `## Document Summary` block (purpose, audience, reader type, structure model, current length), a `## Recommendations` list of numbered `[CUT/MERGE/MOVE/CONDENSE/QUESTION/PRESERVE]` entries each with rationale and word impact, and a closing `## Summary` (total recommendations, estimated reduction) — not the findings table. If no structural issues are found, output exactly: `No substantive changes recommended`.

package/src/core-skills/v6-shims/bmad-review-adversarial-general/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: bmad-review-adversarial-general
+description: 'Deprecated — forwards to bmad-review.'
+---
+
+Merged into `bmad-review`. Invoke the `bmad-review` skill on the same content with only the `adversarial` lens, passing through any `also_consider` areas. Present the findings as a Markdown list — descriptions only, no severity, priority, or ranking; no JSON block.

package/src/core-skills/v6-shims/bmad-review-edge-case-hunter/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: bmad-review-edge-case-hunter
+description: 'Deprecated — forwards to bmad-review.'
+---
+
+Merged into `bmad-review`. Invoke the `bmad-review` skill on the same content with only the `edge-case-hunter` lens, passing through any `also_consider` areas. Output ONLY the raw findings JSON array in the legacy shape: the four standard fields (plus `kind`/`confidence` on deletion findings), no `lens` field, no markdown wrapping, no extra text. `[]` is valid when nothing is found.

package/src/core-skills/v6-shims/bmad-review-verification-gap/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: bmad-review-verification-gap
+description: 'Deprecated — forwards to bmad-review.'
+---
+
+Merged into `bmad-review`. Invoke the `bmad-review` skill on the same content with only the `verification-gap` lens. Present the markdown rendering only (no JSON block), listing any `gap_shape: "other"` findings under an `## Other findings` heading. When there are no findings at all, output exactly this single line: `No verification gaps found.`

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

@@ -35,6 +35,13 @@ platforms:
       target_dir: .agent/skills
       global_target_dir: ~/.gemini/antigravity/skills
 
+  antigravity-cli:
+    name: "Antigravity CLI (AGY)"
+    preferred: false
+    installer:
+      target_dir: .agents/skills
+      global_target_dir: ~/.gemini/antigravity-cli/skills
+
   auggie:
     name: "Auggie"
     preferred: false

package/tools/installer/modules/custom-module-manager.js

@@ -3,6 +3,7 @@ const os = require('node:os');
 const path = require('node:path');
 const { execSync } = require('node:child_process');
 const prompts = require('../prompts');
+const { gitEnv } = require('./git-env');
 
 function quoteCustomRef(ref) {
   if (typeof ref !== 'string' || !/^[\w.\-+/]+$/.test(ref)) {
@@ -418,7 +419,7 @@ class CustomModuleManager {
         execSync('git fetch origin --depth 1', {
           cwd: repoCacheDir,
           stdio: ['ignore', 'pipe', 'pipe'],
-          env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+          env: gitEnv({ GIT_TERMINAL_PROMPT: '0' }),
         });
         if (effectiveVersion) {
           // Fetch the ref as either a tag or a branch — `origin <ref>` works
@@ -427,11 +428,12 @@ class CustomModuleManager {
           execSync(`git fetch --depth 1 origin ${quoteCustomRef(effectiveVersion)} --no-tags`, {
             cwd: repoCacheDir,
             stdio: ['ignore', 'pipe', 'pipe'],
-            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+            env: gitEnv({ GIT_TERMINAL_PROMPT: '0' }),
           });
           execSync(`git checkout --quiet FETCH_HEAD`, {
             cwd: repoCacheDir,
             stdio: ['ignore', 'pipe', 'pipe'],
+            env: gitEnv(),
           });
         } else {
           // Resolve the default branch (origin/HEAD) and fetch it explicitly.
@@ -442,6 +444,7 @@ class CustomModuleManager {
             defaultBranch = execSync('git symbolic-ref refs/remotes/origin/HEAD --short', {
               cwd: repoCacheDir,
               stdio: 'pipe',
+              env: gitEnv(),
             })
               .toString()
               .trim()
@@ -452,11 +455,12 @@ class CustomModuleManager {
           execSync(`git fetch --depth 1 origin ${quoteCustomRef(defaultBranch)}`, {
             cwd: repoCacheDir,
             stdio: ['ignore', 'pipe', 'pipe'],
-            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+            env: gitEnv({ GIT_TERMINAL_PROMPT: '0' }),
           });
           execSync(`git reset --hard origin/${quoteCustomRef(defaultBranch)}`, {
             cwd: repoCacheDir,
             stdio: ['ignore', 'pipe', 'pipe'],
+            env: gitEnv(),
           });
         }
         fetchSpinner.stop(`Updated ${displayName}`);
@@ -477,12 +481,12 @@ class CustomModuleManager {
         if (effectiveVersion) {
           execSync(`git clone --depth 1 --branch ${quoteCustomRef(effectiveVersion)} "${parsed.cloneUrl}" "${repoCacheDir}"`, {
             stdio: ['ignore', 'pipe', 'pipe'],
-            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+            env: gitEnv({ GIT_TERMINAL_PROMPT: '0' }),
           });
         } else {
           execSync(`git clone --depth 1 "${parsed.cloneUrl}" "${repoCacheDir}"`, {
             stdio: ['ignore', 'pipe', 'pipe'],
-            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+            env: gitEnv({ GIT_TERMINAL_PROMPT: '0' }),
           });
         }
         fetchSpinner.stop(`Cloned ${displayName}`);
@@ -496,7 +500,7 @@ class CustomModuleManager {
     // Record the resolved SHA for the manifest writer.
     let resolvedSha = null;
     try {
-      resolvedSha = execSync('git rev-parse HEAD', { cwd: repoCacheDir, stdio: 'pipe' }).toString().trim();
+      resolvedSha = execSync('git rev-parse HEAD', { cwd: repoCacheDir, stdio: 'pipe', env: gitEnv() }).toString().trim();
     } catch {
       // swallow — a non-git repo (local path) wouldn't reach here anyway
     }
@@ -508,6 +512,7 @@ class CustomModuleManager {
         const symbolic = execSync('git symbolic-ref --short refs/remotes/origin/HEAD', {
           cwd: repoCacheDir,
           stdio: 'pipe',
+          env: gitEnv(),
         })
           .toString()
           .trim();
@@ -558,6 +563,7 @@ class CustomModuleManager {
           cwd: repoCacheDir,
           stdio: ['ignore', 'pipe', 'pipe'],
           timeout: 120_000,
+          env: gitEnv(), // npm shells out to git for git-URL deps; keep hook GIT_* vars away from it
         });
         installSpinner.stop(`Installed dependencies for ${displayName}`);
       } catch (error_) {

package/tools/installer/modules/external-manager.js

@@ -5,6 +5,7 @@ const { execSync } = require('node:child_process');
 const yaml = require('yaml');
 const prompts = require('../prompts');
 const { resolveChannel, tagExists, parseGitHubRepo } = require('./channel-resolver');
+const { gitEnv } = require('./git-env');
 const { decideChannelForModule } = require('./channel-plan');
 const { getProjectRoot } = require('../project-root');
 
@@ -370,33 +371,34 @@ class ExternalModuleManager {
       const fetchSpinner = await createSpinner();
       fetchSpinner.start(`Fetching ${moduleInfo.name}...`);
       try {
-        const currentSha = execSync('git rev-parse HEAD', { cwd: moduleCacheDir, stdio: 'pipe' }).toString().trim();
+        const currentSha = execSync('git rev-parse HEAD', { cwd: moduleCacheDir, stdio: 'pipe', env: gitEnv() }).toString().trim();
 
         if (resolved.channel === 'next') {
           execSync('git fetch origin --depth 1', {
             cwd: moduleCacheDir,
             stdio: ['ignore', 'pipe', 'pipe'],
-            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+            env: gitEnv({ GIT_TERMINAL_PROMPT: '0' }),
           });
           execSync('git reset --hard origin/HEAD', {
             cwd: moduleCacheDir,
             stdio: ['ignore', 'pipe', 'pipe'],
-            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+            env: gitEnv({ GIT_TERMINAL_PROMPT: '0' }),
           });
         } else {
           // stable or pinned — fetch the specific tag and check it out.
           execSync(`git fetch --depth 1 origin tag ${quoteShell(resolved.ref)} --no-tags`, {
             cwd: moduleCacheDir,
             stdio: ['ignore', 'pipe', 'pipe'],
-            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+            env: gitEnv({ GIT_TERMINAL_PROMPT: '0' }),
           });
           execSync(`git checkout --quiet FETCH_HEAD`, {
             cwd: moduleCacheDir,
             stdio: ['ignore', 'pipe', 'pipe'],
+            env: gitEnv(),
           });
         }
 
-        const newSha = execSync('git rev-parse HEAD', { cwd: moduleCacheDir, stdio: 'pipe' }).toString().trim();
+        const newSha = execSync('git rev-parse HEAD', { cwd: moduleCacheDir, stdio: 'pipe', env: gitEnv() }).toString().trim();
         fetchSpinner.stop(`Fetched ${moduleInfo.name}`);
         if (currentSha !== newSha) needsDependencyInstall = true;
       } catch {
@@ -415,12 +417,12 @@ class ExternalModuleManager {
         if (resolved.channel === 'next') {
           execSync(`git clone --depth 1 "${moduleInfo.url}" "${moduleCacheDir}"`, {
             stdio: ['ignore', 'pipe', 'pipe'],
-            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+            env: gitEnv({ GIT_TERMINAL_PROMPT: '0' }),
           });
         } else {
           execSync(`git clone --depth 1 --branch ${quoteShell(resolved.ref)} "${moduleInfo.url}" "${moduleCacheDir}"`, {
             stdio: ['ignore', 'pipe', 'pipe'],
-            env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+            env: gitEnv({ GIT_TERMINAL_PROMPT: '0' }),
           });
         }
         fetchSpinner.stop(`Fetched ${moduleInfo.name}`);
@@ -431,7 +433,7 @@ class ExternalModuleManager {
     }
 
     // Record resolution (channel + tag + SHA) for the manifest writer to pick up.
-    const sha = execSync('git rev-parse HEAD', { cwd: moduleCacheDir, stdio: 'pipe' }).toString().trim();
+    const sha = execSync('git rev-parse HEAD', { cwd: moduleCacheDir, stdio: 'pipe', env: gitEnv() }).toString().trim();
     ExternalModuleManager._resolutions.set(moduleCode, {
       channel: resolved.channel,
       version: resolved.version,
@@ -459,6 +461,7 @@ class ExternalModuleManager {
             cwd: moduleCacheDir,
             stdio: ['ignore', 'pipe', 'pipe'],
             timeout: 120_000, // 2 minute timeout
+            env: gitEnv(), // npm shells out to git for git-URL deps; keep hook GIT_* vars away from it
           });
           installSpinner.stop(`Installed dependencies for ${moduleInfo.name}`);
         } catch (error) {
@@ -485,6 +488,7 @@ class ExternalModuleManager {
               cwd: moduleCacheDir,
               stdio: ['ignore', 'pipe', 'pipe'],
               timeout: 120_000, // 2 minute timeout
+              env: gitEnv(), // npm shells out to git for git-URL deps; keep hook GIT_* vars away from it
             });
             installSpinner.stop(`Installed dependencies for ${moduleInfo.name}`);
           } catch (error) {

package/tools/installer/modules/git-env.js

@@ -0,0 +1,47 @@
+/**
+ * Sanitized environment for spawning git subprocesses.
+ *
+ * When the installer runs inside a git hook (e.g. `npm test` from a
+ * pre-commit hook), git exports repo-targeting variables — GIT_DIR,
+ * GIT_INDEX_FILE, GIT_WORK_TREE, etc. — into the hook's environment. A
+ * spawned `git` inherits them and silently operates on the hook's repository
+ * instead of the cwd passed to execSync (GIT_DIR overrides directory
+ * discovery, and the cwd then becomes its work tree). In a worktree checkout
+ * this let a cache refresh shallow-fetch and hard-reset the developer's own
+ * repo. Strip these variables so cache-directory git commands can only ever
+ * act on the repository at their cwd.
+ */
+
+const REPO_TARGETING_VARS = [
+  'GIT_DIR',
+  'GIT_WORK_TREE',
+  'GIT_INDEX_FILE',
+  'GIT_COMMON_DIR',
+  'GIT_OBJECT_DIRECTORY',
+  'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+  'GIT_PREFIX',
+  'GIT_NAMESPACE',
+  // `git -c key=val` exports its overrides to hook subprocesses through these;
+  // a core.worktree override can retarget the work tree just like GIT_WORK_TREE.
+  'GIT_CONFIG_PARAMETERS',
+  'GIT_CONFIG_COUNT',
+];
+
+// GIT_CONFIG_KEY_0 / GIT_CONFIG_VALUE_0 ... — the enumerated form of the same mechanism.
+const CONFIG_PAIR_VAR = /^GIT_CONFIG_(KEY|VALUE)_\d+$/;
+
+/**
+ * Build the environment for a git child process.
+ * @param {Object} [extra] - Additional variables to set (e.g. GIT_TERMINAL_PROMPT)
+ * @returns {Object} process.env minus repo-targeting GIT_* vars, plus extras
+ */
+function gitEnv(extra = {}) {
+  const env = { ...process.env, ...extra };
+  for (const name of REPO_TARGETING_VARS) delete env[name];
+  for (const name of Object.keys(env)) {
+    if (CONFIG_PAIR_VAR.test(name)) delete env[name];
+  }
+  return env;
+}
+
+module.exports = { gitEnv };

package/tools/skill-validator.md

@@ -10,7 +10,7 @@ Before running inference-based validation, run the deterministic validator:
 node tools/validate-skills.js --json path/to/skill-dir
 ```
 
-This checks 12 rules deterministically: SKILL-01, SKILL-02, SKILL-03, SKILL-04, SKILL-05, SKILL-06, SKILL-07, PATH-02, STEP-01, STEP-06, STEP-07, SEQ-02.
+This checks 13 rules deterministically: SKILL-01, SKILL-02, SKILL-03, SKILL-04, SKILL-05, SKILL-06, SKILL-07, PATH-02, STEP-01, STEP-06, STEP-07, SEQ-02, TPL-01.
 
 Review its JSON output. For any rule that produced **zero findings** in the first pass, **skip it** during inference-based validation below — it has already been verified. If a rule produced any findings, the inference validator should still review that rule (some rules like SKILL-04 and SKILL-06 have sub-checks that benefit from judgment). Focus your inference effort on the remaining rules that require judgment (PATH-01, PATH-03, PATH-04, PATH-05, WF-03, STEP-02, STEP-03, STEP-04, STEP-05, SEQ-01, REF-01, REF-02, REF-03).
 
@@ -253,6 +253,16 @@ If no findings are generated (from either pass), the skill passes validation.
 
 ---
 
+### TPL-01 — Template Files Must Not Contain Compile-Time Substitutions
+
+- **Severity:** HIGH
+- **Applies to:** `.md` files whose name contains `template` (case-insensitive)
+- **Rule:** Template files seed durable, version-controlled artifacts (e.g. spec files) that execute on other machines. A `{{.var}}` compile-time substitution would be baked at render time and freeze a machine-local value into every artifact produced from the template.
+- **Detection:** Regex `\{\{\.\w+\}\}` match anywhere in a file whose basename matches `/template/i`.
+- **Fix:** Remove the `{{.var}}` reference. Use single-curly `{var}` if the value should be resolved at LLM runtime by the consumer of the generated artifact.
+
+---
+
 ### REF-01 — Variable References Must Be Defined
 
 - **Severity:** HIGH

package/tools/validate-skills.js

@@ -17,6 +17,7 @@
  * - STEP-06: step frontmatter has no name/description
  * - STEP-07: step count 2-10
  * - SEQ-02: no time estimates
+ * - TPL-01: template files must not contain compile-time {{.var}} substitutions
  *
  * Usage:
  *   node tools/validate-skills.js                    # All skills, human-readable
@@ -43,6 +44,8 @@ const positionalArgs = args.filter((a) => !a.startsWith('--'));
 const NAME_REGEX = /^bmad-[a-z0-9]+(-[a-z0-9]+)*$/;
 const STEP_FILENAME_REGEX = /^step-\d{2}[a-z]?-[a-z0-9-]+\.md$/;
 const TIME_ESTIMATE_PATTERNS = [/takes?\s+\d+\s*min/i, /~\s*\d+\s*min/i, /estimated\s+time/i, /\bETA\b/];
+const TEMPLATE_FILENAME_REGEX = /template/i;
+const COMPILE_TIME_SUB_REGEX = /\{\{\.\w+\}\}/;
 
 const SEVERITY_ORDER = { CRITICAL: 0, HIGH: 1, MEDIUM: 2, LOW: 3 };
 
@@ -535,6 +538,36 @@ function validateSkill(skillDir) {
     }
   }
 
+  // --- TPL-01: template files must not contain compile-time {{.var}} substitutions ---
+  // Template files seed durable, version-controlled artifacts (spec files) that
+  // execute on other machines. Baking a {{.var}} at render time would freeze a
+  // machine-local value into every downstream artifact.
+  for (const filePath of allFiles) {
+    if (path.extname(filePath) !== '.md') continue;
+    const base = path.basename(filePath);
+    if (!TEMPLATE_FILENAME_REGEX.test(base)) continue;
+
+    const relFile = path.relative(skillDir, filePath);
+    const content = safeReadFile(filePath, findings, relFile);
+    if (content === null) continue;
+
+    const lines = content.split('\n');
+    for (const [i, line] of lines.entries()) {
+      const match = line.match(COMPILE_TIME_SUB_REGEX);
+      if (match) {
+        findings.push({
+          rule: 'TPL-01',
+          title: 'Template files must not contain compile-time substitutions',
+          severity: 'HIGH',
+          file: relFile,
+          line: i + 1,
+          detail: `Template file contains compile-time substitution \`${match[0]}\` — this would be baked at render time and leak a machine-local value into every spec produced from the template.`,
+          fix: 'Remove the `{{.var}}` reference. Use single-curly `{var}` if the value should be resolved at LLM runtime by the consumer of the generated spec.',
+        });
+      }
+    }
+  }
+
   return findings;
 }