bmad-method 6.11.1-next.36 → 6.11.1-next.38

package/AGENTS.md

@@ -10,3 +10,15 @@ Open source framework for structured, agent-assisted software delivery.
 
 - Skill validation rules are in `tools/skill-validator.md`.
 - Deterministic skill checks run via `npm run validate:skills` (included in `quality`).
+- Documentation conventions are in `docs/_STYLE_GUIDE.md`.
+
+## Writing prompts
+
+Skills, workflows, tasks, and agent definitions are prompt text that an agent reads in full on every run. Length and
+ambiguity are paid on every run; a corner case is paid only when it occurs. So do not add instructions for exotic
+cases — the model usually handles them from context, and the reviewing human can correct it when it does not.
+
+## Testing
+
+Automated tests assert outcomes produced by deterministic code. Do not write automated tests for LLM output or for
+static source text.

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/greptile.json

@@ -0,0 +1,52 @@
+{
+  "strictness": 2,
+  "commentTypes": ["logic", "syntax"],
+  "triggerOnUpdates": false,
+  "excludeAuthors": ["dependabot[bot]"],
+  "ignorePatterns": "greptile.json\neslint.config.mjs\n.claude/**\n.codex/**\n.agent/**\n.agentvibes/**\n.kiro/**\n.roo/**\n.github/chatmodes/**\ndist/**\nbuild/**\ncoverage/**\n.bundler-temp/**\n**/node_modules/**\n**/*.min.js\n**/*.generated.*\n**/*.bundle.md\npackage-lock.json\n**/*.png\n**/*.jpg\n**/*.svg\ntest/fixtures/**\ntools/tests/fixtures/**\ntest/template-test-generator/**\ntools/template-test-generator/test-scenarios/**\n_bmad*/**\nwebsite/public/**\nwebsite/diagrams/**\nz*/**\nsample-project/**\ntest-project-install/**\n**/validation-report-*.html\nCHANGELOG.md",
+  "instructions": "Most of this repo's source is prompt text read by agents at runtime, not executable code. Confine review of it to claims that can be checked against the repository: file paths and cross-references that do not resolve, invocation syntax that does not match the referenced skill, instructions that contradict another file, documented behavior that the code does not implement, and violations of the conventions in AGENTS.md. Do not comment on prompt wording, tone, phrasing, length, or how thorough an instruction feels \u2014 those are authoring decisions and are not yours to judge.",
+  "customContext": {
+    "files": [
+      {
+        "path": "AGENTS.md",
+        "description": "Repo conventions every change must satisfy"
+      },
+      {
+        "path": "tools/skill-validator.md",
+        "description": "Authoritative rule catalog for skills \u2014 SKILL.md metadata, workflow constraints, step file structure, path references, variable resolution, sequential execution, skill invocation syntax. Apply the whole catalog to changed skill files.",
+        "scope": ["src/bmm-skills/**", "src/core-skills/**"]
+      },
+      {
+        "path": "docs/_STYLE_GUIDE.md",
+        "description": "Documentation conventions: Google style, Diataxis structure, plus project-specific rules on headers, admonitions, and nesting",
+        "scope": ["docs/**"]
+      }
+    ],
+    "rules": [
+      {
+        "id": "docs-follow-source",
+        "rule": "Source changed. Check whether docs/ needs a matching update \u2014 new features, changed behavior, renamed concepts, altered CLI flags, or modified configuration options should all be reflected in the relevant doc pages. Flag missing or outdated docs.",
+        "scope": ["src/**"],
+        "severity": "medium"
+      },
+      {
+        "id": "agent-skill-shape",
+        "rule": "Agent skill. The persona is configured in customize.toml under [agent]: check that every {agent.*} placeholder the SKILL.md interpolates has a corresponding key there, and that menu entries name skills that exist in this repo.",
+        "scope": ["src/bmm-skills/agents/**"],
+        "severity": "high"
+      },
+      {
+        "id": "docs-links-resolve",
+        "rule": "Check that internal markdown links point at files that exist.",
+        "scope": ["docs/**/*.md"],
+        "severity": "medium"
+      },
+      {
+        "id": "tooling-exit-codes",
+        "rule": "Build and tooling script. Check error handling and that failures exit non-zero.",
+        "scope": ["tools/**", "src/scripts/**"],
+        "severity": "medium"
+      }
+    ]
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method",
-  "version": "6.11.1-next.36",
+  "version": "6.11.1-next.38",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",
@@ -50,11 +50,11 @@
     "test:renderer": "uv run --python 3.11 python -m unittest src/scripts/tests/test_config_utils.py src/scripts/tests/test_resolve_config.py src/scripts/tests/test_resolve_customization.py && node test/test-build-auto-renderer.js",
     "test:retrospective": "uv run --python 3.11 src/bmm-skills/ship/bmad-retrospective/scripts/tests/test_git_evidence.py && uv run --python 3.11 src/bmm-skills/ship/bmad-retrospective/scripts/tests/test_sprint_status.py",
     "test:site-url": "node test/test-site-url.mjs",
-    "test:skills": "node test/test-validate-skills.js",
+    "test:skills": "uv run --python 3.11 python -m unittest tools/tests/test_validate_skills.py",
     "test:sprint-planning": "uv run --python 3.11 src/bmm-skills/plan/bmad-sprint-planning/scripts/tests/test_sprint_plan.py && node test/test-template-sync.js",
     "test:urls": "node test/test-parse-source-urls.js",
     "validate:refs": "node tools/validate-file-refs.js --strict",
-    "validate:skills": "node tools/validate-skills.js --strict"
+    "validate:skills": "uv run --python 3.11 tools/validate_skills.py --strict"
   },
   "lint-staged": {
     "*.{js,cjs,mjs}": [

package/src/bmm-skills/ship/bmad-build-auto/step-01-clarify-and-route.md

@@ -2,6 +2,7 @@
 spec_file: '' # set at runtime once a route resolves it; some HALT branches exit before it is set
 spec_folder: '' # set at runtime under folder+id dispatch only
 story_id: '' # set at runtime under folder+id dispatch only
+followup_pass: '' # set at runtime when a `done` spec is re-dispatched for a follow-up review pass; empty on a first pass
 ---
 
 # Step 1: Clarify and Route
@@ -21,7 +22,7 @@ If the invocation prompt explicitly points to an existing spec file with recogni
 - `ready-for-dev` or `in-progress` → `[[bmad-snapshot:step-03-implement.md]]`
 - `in-review` → `[[bmad-snapshot:step-04-review.md]]`
 - `blocked` → HALT with status `blocked` and blocking condition `blocked spec supplied`.
-- `done` → set `review_loop_iteration` to `0` in the frontmatter, then **EARLY EXIT** to `[[bmad-snapshot:step-04-review.md]]` for a fresh review pass. (A `done` spec is a completed run, so this starts a follow-up review, not a resumption.)
+- `done` → set `review_loop_iteration` to `0` in the frontmatter and set `followup_pass` to `true`, then **EARLY EXIT** to `[[bmad-snapshot:step-04-review.md]]` for a fresh review pass. (A `done` spec is a completed run, so this starts a follow-up review, not a resumption.)
 
 If the invocation prompt instead supplies a spec folder and a story id, with no specific spec file path, this is a **folder+id dispatch**: set `spec_folder` (a `{project-root}`-relative or absolute path) and `story_id` from the prompt. Any further prompt text (e.g. `invoke_dev_with` guidance the caller appended) is additional planning context to carry into step-02 — not a competing description of what to implement.
 
@@ -31,7 +32,7 @@ Look for files matching `{spec_folder}/stories/{story_id}-*.md` (id-prefix match
 - **If more than one matches**, HALT with status `blocked` and blocking condition `ambiguous story file match`.
 - **If exactly one matches**, set `spec_file` to that path.
   - `draft` (planning was interrupted mid-flight): accumulate cross-story context before resuming — load every other file matching `{spec_folder}/stories/*.md` (every match except `{spec_file}` itself), regardless of `status`, and carry forward each one's **Code Map**, **Design Notes**, **Spec Change Log**, **Tasks & Acceptance** checklist state, and **Auto Run Result** details, where present, as additional planning context for step-02. Then **EARLY EXIT** to `[[bmad-snapshot:step-02-plan.md]]`.
-  - Any other recognized `status`: **EARLY EXIT** using the same routing as above, including the `review_loop_iteration` reset for `done`. One difference: a `blocked` story HALTs with blocking condition `story already blocked`, not `blocked spec supplied` — the caller did not supply this file; build-auto found it by id.
+  - Any other recognized `status`: **EARLY EXIT** using the same routing as above, including the `review_loop_iteration` reset and `followup_pass` for `done`. One difference: a `blocked` story HALTs with blocking condition `story already blocked`, not `blocked spec supplied` — the caller did not supply this file; build-auto found it by id.
   - `status` missing or unrecognized: HALT with status `blocked` and blocking condition `unrecognized status in existing story file`.
 - **If none matches**, this is the first dispatch for `{story_id}`. The entry's `title` and `description` are the resolved intent. If `{spec_folder}/SPEC.md` does not exist, HALT with status `blocked` and blocking condition `no epic spec found`. Otherwise load it and the files listed in its `companions:` frontmatter as planning context, then accumulate cross-story context the same way as the `draft` case above — load every file matching `{spec_folder}/stories/*.md` (none yet exists for `{story_id}` at this point, so nothing is excluded), regardless of `status`, carrying forward the same fields, where present, as additional planning context for step-02. Then continue to INSTRUCTIONS item 3 below — not `step-03-implement.md`, item 3 of the numbered list in this file (items 1 and 2 do not apply — context and intent are already resolved; item 1.A.5's previous-story continuity scan in particular never runs here, since folder+id dispatch already skips items 1 and 2 entirely — the cross-story accumulation above is its replacement for this dispatch mode).
 

package/src/bmm-skills/ship/bmad-build-auto/step-04-review.md

@@ -87,7 +87,7 @@ Write the following details to `{spec_file}` under `## Auto Run Result`:
 - Summary of implemented change
 - Files changed with one-line descriptions
 - Review findings breakdown: patches applied, items deferred, and every rejected finding with its recorded reason
-- Follow-up review recommendation: count only this pass's entries triaged `patch`, at entry verdict — never deferred or `false` ones. `true` if any patched entry was `high`, or if two or more `medium` entries were patched; otherwise `false`. Record the patched counts by verdict.
+- Follow-up review recommendation: default `false`. Count only this pass's entries triaged `patch`, at entry verdict — never deferred or `false` ones. On a first pass, `true` if any patched entry was `high`, or if two or more `medium` entries were patched. On a follow-up pass (`{followup_pass}` = `true`), `true` only if this pass patched a `high` — otherwise the work has converged; patch volume is never grounds. A `true` names the specific unverified risk under `## Auto Run Result`; if none can be named, it is `false`. Record the patched counts by verdict.
 - Verification performed, including command outcomes or manual inspection notes
 - Any residual risks
 

package/tools/installer/core/shim-policy.js

@@ -79,7 +79,7 @@ async function readInstalledSkillIds(bmadDir) {
 
 // The installed manifest carries no lifecycle column, so the description
 // prefix every shim ships with is the only record of what was a shim. This
-// is the same signal validate-skills.js uses to exempt them.
+// is the same signal validate_skills.py uses to exempt them.
 async function readInstalledShims(bmadDir) {
   const shims = [];
   for (const record of await readSkillManifest(bmadDir)) {

package/tools/skill-validator.md

@@ -7,10 +7,10 @@ An LLM-readable validation prompt for skills following the Agent Skills open sta
 Before running inference-based validation, run the deterministic validator:
 
 ```bash
-node tools/validate-skills.js --json path/to/skill-dir
+uv run --python 3.11 tools/validate_skills.py --json path/to/skill-dir
 ```
 
-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.
+This checks 10 rules deterministically: SKILL-01, SKILL-02, SKILL-03, SKILL-04, SKILL-05, SKILL-06, SKILL-07, PATH-02, 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).
 
@@ -176,14 +176,6 @@ If no findings are generated (from either pass), the skill passes validation.
 
 ---
 
-### STEP-01 — Step File Naming
-
-- **Severity:** MEDIUM
-- **Applies to:** files in `steps/` directory
-- **Rule:** Step files must be named `step-NN-description.md` where NN is a zero-padded two-digit number. An optional single-letter variant suffix is allowed for branching steps (e.g., `step-01b-continue.md`).
-- **Detection:** Regex: `^step-\d{2}[a-z]?-[a-z0-9-]+\.md$`
-- **Fix:** Rename to match the pattern.
-
 ### STEP-02 — Step Must Have a Goal Section
 
 - **Severity:** HIGH
@@ -217,22 +209,6 @@ If no findings are generated (from either pass), the skill passes validation.
 - **Detection:** Look for instructions to read multiple step files simultaneously, or unconditional references to step files with higher numbers than the current step. Exempt locations: `## NEXT` sections, navigation/dispatch sections that list valid resumption targets, and conditional routing branches.
 - **Fix:** Remove premature step loading. Ensure only the current step is active.
 
-### STEP-06 — Step File Frontmatter: No `name` or `description`
-
-- **Severity:** MEDIUM
-- **Applies to:** step files
-- **Rule:** Step files should not have `name:` or `description:` in their YAML frontmatter. These are metadata noise — the step's purpose is conveyed by its goal section and filename.
-- **Detection:** Parse step file frontmatter for `name:` or `description:` keys.
-- **Fix:** Remove `name:` and `description:` from step file frontmatter.
-
-### STEP-07 — Step Count
-
-- **Severity:** LOW
-- **Applies to:** workflow as a whole
-- **Rule:** A sharded workflow should have between 2 and 10 step files. More than 10 risks LLM context degradation.
-- **Detection:** Count files matching `step-*.md` in the `steps/` directory.
-- **Fix:** Consider consolidating steps if over 10.
-
 ---
 
 ### SEQ-01 — No Skip Instructions

package/tools/tests/fixtures/validate-skills/bmad/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: bmad
+description: 'Provides the canonical BMad entrypoint. Use when the root BMad skill needs validation.'
+---
+
+# BMad
+
+Canonical root-skill validation fixture.

package/tools/tests/fixtures/validate-skills/deprecated-shim/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: deprecated-shim
+description: 'DEPRECATED — consolidated into bmad-foo; this skill will be removed in v7 in favor of `bmad-foo`.'
+---
+
+# DEPRECATED — forwards to bmad-foo
+
+This skill was consolidated into `bmad-foo` and is retained as a thin compatibility
+shim so existing invocations keep working. New work should invoke `bmad-foo` directly.

package/tools/tests/fixtures/validate-skills/missing-trigger/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: missing-trigger
+description: 'Generates a thing and writes it to disk for the user.'
+---
+
+# Missing Trigger
+
+An active (non-deprecated) skill whose description omits a "Use when" trigger phrase.
+This fixture guards against regressions: SKILL-06 must still flag it.

package/tools/tests/fixtures/validate-skills/with-trigger/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: with-trigger
+description: 'Generates a thing and writes it to disk. Use when the user asks to scaffold a thing.'
+---
+
+# With Trigger
+
+An active skill whose description includes a "Use when" trigger phrase.