bmad-method 6.10.1-next.8 → 6.11.0

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-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-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-build.",,,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/src/scripts/config_utils.py

@@ -0,0 +1,119 @@
+"""Shared strict TOML loading and structural merge support."""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+from typing import Any, Iterable
+
+
+class ConfigError(ValueError):
+    """Raised when a present configuration layer cannot be used safely."""
+
+
+_KEYED_MERGE_FIELDS = ("code", "id")
+
+
+def load_toml(path: Path, *, required: bool = False) -> dict[str, Any]:
+    """Load a TOML table, allowing absence only for optional layers."""
+    if not path.exists():
+        if required:
+            raise ConfigError(f"required TOML file not found: {path}")
+        return {}
+    if not path.is_file():
+        raise ConfigError(f"TOML layer is not a file: {path}")
+    try:
+        with path.open("rb") as stream:
+            parsed = tomllib.load(stream)
+    except tomllib.TOMLDecodeError as error:
+        raise ConfigError(f"failed to parse {path}: {error}") from error
+    except OSError as error:
+        raise ConfigError(f"failed to read {path}: {error}") from error
+    if not isinstance(parsed, dict):
+        raise ConfigError(f"TOML layer did not parse to a table: {path}")
+    return parsed
+
+
+def _detect_keyed_merge_field(items: list[Any]) -> str | None:
+    if not items or not all(isinstance(item, dict) for item in items):
+        return None
+    for candidate in _KEYED_MERGE_FIELDS:
+        if all(candidate in item for item in items):
+            for item in items:
+                value = item[candidate]
+                if not isinstance(value, str):
+                    raise ConfigError(
+                        f"keyed array identifier `{candidate}` must be a string, "
+                        f"got {type(value).__name__}"
+                    )
+                if not value:
+                    raise ConfigError(
+                        f"keyed array identifier `{candidate}` must not be empty"
+                    )
+            return candidate
+    return None
+
+
+def _merge_arrays(base: list[Any], override: list[Any]) -> list[Any]:
+    keyed_field = _detect_keyed_merge_field(base + override)
+    if keyed_field is None:
+        return list(base) + list(override)
+
+    result: list[Any] = []
+    index_by_key: dict[str, int] = {}
+    for item in base:
+        copied = dict(item)
+        index_by_key[copied[keyed_field]] = len(result)
+        result.append(copied)
+    for item in override:
+        copied = dict(item)
+        key = copied[keyed_field]
+        if key in index_by_key:
+            result[index_by_key[key]] = copied
+        else:
+            index_by_key[key] = len(result)
+            result.append(copied)
+    return result
+
+
+def structural_merge(base: Any, override: Any) -> Any:
+    """Merge tables recursively, keyed table arrays by identity, and append other arrays."""
+    if isinstance(base, dict) and isinstance(override, dict):
+        result = dict(base)
+        for key, value in override.items():
+            result[key] = structural_merge(result[key], value) if key in result else value
+        return result
+    if isinstance(base, list) and isinstance(override, list):
+        return _merge_arrays(base, override)
+    return override
+
+
+def merge_layers(layers: Iterable[dict[str, Any]]) -> dict[str, Any]:
+    merged: dict[str, Any] = {}
+    for layer in layers:
+        merged = structural_merge(merged, layer)
+    return merged
+
+
+def load_central_config(project_root: Path) -> dict[str, Any]:
+    bmad_dir = project_root / "_bmad"
+    return merge_layers(
+        (
+            load_toml(bmad_dir / "config.toml", required=True),
+            load_toml(bmad_dir / "config.user.toml"),
+            load_toml(bmad_dir / "custom" / "config.toml"),
+            load_toml(bmad_dir / "custom" / "config.user.toml"),
+        )
+    )
+
+
+def load_customization(project_root: Path | None, skill_dir: Path) -> dict[str, Any]:
+    skill_name = skill_dir.name
+    custom_dir = project_root / "_bmad" / "custom" if project_root else None
+    return merge_layers(
+        (
+            load_toml(skill_dir / "customize.toml", required=True),
+            load_toml(custom_dir / f"{skill_name}.toml") if custom_dir else {},
+            load_toml(custom_dir / f"{skill_name}.user.toml") if custom_dir else {},
+        )
+    )