bmad-method 6.11.1-next.35 → 6.11.1-next.37

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.35",
+  "version": "6.11.1-next.37",
   "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/step-04-review.md

@@ -54,7 +54,7 @@ If a layer's instruction requires subagents and none are available, for each suc
    - **intent_gap** — caused by the change; cannot be resolved from the spec because the captured intent is incomplete. Do not infer intent unless there is exactly one possible reading.
    - **bad_spec** — caused by the change, including direct deviations from spec. The spec should have been clear enough to prevent it. When in doubt between bad_spec and patch, prefer bad_spec — a spec-level fix is more likely to produce coherent code.
    - **patch** — caused by the change; its smallest fix is trivial, adds no public surface, and guards no state you did not demonstrate. Just part of the diff. A finding whose smallest fix fails any of those conditions routes to intent_gap when the spec does not settle that fix, otherwise to bad_spec.
-   - **defer** — pre-existing issue not caused by this story; or an entry whose members are all `maybe-false`; or any entry whose fix edits agent-context files (CLAUDE.md, AGENTS.md, rules, etc). For maybe-false members, record what would settle them.
+   - **defer** — pre-existing issue not caused by this story; or an entry whose members are all `maybe-false` and the claim, if true, would be `medium` or `high` — record that severity marked unverified, plus what would settle it (if it would only be `low`, reject it with the same note); or any entry whose fix edits agent-context files (CLAUDE.md, AGENTS.md, rules, etc).
 
 4. Process entries in cascading order. If intent_gap or bad_spec entries exist, they trigger a loopback — lower entries are moot since code will be re-derived. If neither exists, process patch and defer normally. Before each loopback, read `{spec_file}` frontmatter `review_loop_iteration` (missing means `0`), increment it by 1, and write it back. If it exceeds 5, HALT and escalate to the human.
    - **intent_gap** — Root cause is inside `<frozen-after-approval>`. Revert code changes. Loop back to the human to resolve. Once resolved, read fully and follow `[[bmad-snapshot:step-02-plan.md]]` to re-run steps 2–4.

package/src/bmm-skills/ship/bmad-build/step-oneshot.md

@@ -51,7 +51,7 @@ Group the survivors by shared root cause — two findings belong in one entry on
 
 - **patch** — Patch every entry caused or exposed by this change that shows a defect that actually occurs, missing coverage for a specific case, or a broken gate or convention — not a state nothing reaches — and whose smallest fix is trivial, adds no public surface, and guards no state the finding did not demonstrate. Apply that smallest fix immediately.
 - **HALT** — HALT on every entry caused or exposed by this change that shows the same evidence but whose smallest fix fails any of those conditions. Present it to the human for decision before proceeding.
-- **defer** — Defer every other entry: pre-existing issues, improvement ideas, entries whose members are all `maybe-false` (record what would settle them), and any entry whose fix edits agent-context files (CLAUDE.md, AGENTS.md, rules, specs). Append one new entry to `{{.implementation_artifacts}}/deferred-work.md` using this format. Do not modify existing entries or look for duplicates.
+- **defer** — Defer every other entry: pre-existing issues, improvement ideas, entries whose members are all `maybe-false` where the claim, if true, would be `medium` or `high` (record that severity marked unverified, plus what would settle it; if it would only be `low`, reject it with the same note), and any entry whose fix edits agent-context files (CLAUDE.md, AGENTS.md, rules, specs). Append one new entry to `{{.implementation_artifacts}}/deferred-work.md` using this format. Do not modify existing entries or look for duplicates.
   ```markdown
   - source_spec: `{spec_file}`
     summary: <one sentence>

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

@@ -54,7 +54,7 @@ Announce skipped layers first, then launch every active layer before handling an
    - **intent_gap** — caused by the change; cannot be resolved from the spec because the captured intent is incomplete. Do not infer intent unless there is exactly one possible reading.
    - **bad_spec** — caused by the change, including direct deviations from spec. The spec should have been clear enough to prevent it. When in doubt between bad_spec and patch, prefer bad_spec — a spec-level fix is more likely to produce coherent code.
    - **patch** — caused by the change; its smallest fix is trivial, adds no public surface, and guards no state you did not demonstrate. Just part of the diff. A finding whose smallest fix fails any of those conditions routes to intent_gap when the spec does not settle that fix, otherwise to bad_spec.
-   - **defer** — pre-existing issue not caused by this story; or an entry whose members are all `maybe-false`; or any entry whose fix edits agent-context files (CLAUDE.md, AGENTS.md, rules, etc). For maybe-false members, record what would settle them.
+   - **defer** — pre-existing issue not caused by this story; or an entry whose members are all `maybe-false` and the claim, if true, would be `medium` or `high` — record that severity marked unverified, plus what would settle it (if it would only be `low`, reject it with the same note); or any entry whose fix edits agent-context files (CLAUDE.md, AGENTS.md, rules, etc).
 
 4. Append a new entry to the `## Review Triage Log` section in `{spec_file}`, in this format:
    ```markdown
@@ -77,7 +77,7 @@ Announce skipped layers first, then launch every active layer before handling an
            <why this is real; for a maybe-false finding, what evidence would settle it>
          location: >- # optional — file:line or component
            src/foo.py:42
-         severity: medium # optional — high | medium | low
+         severity: medium # optional — high | medium | low; for a maybe-false entry, its if-true grade plus " (unverified)"
      ```
      After all appends, parse the complete frontmatter as YAML and verify that `deferred` is one list containing every prior item plus the new items with their intended text. Repair serialization errors before continuing.
 

package/src/bmm-skills/ship/bmad-code-review/steps/step-03-triage.md

@@ -40,7 +40,7 @@
 4. **Route** each entry into exactly one triage bucket. A group that includes verified `high`, `medium`, or `low` members routes by its highest such verdict -- not to defer just because a member is `maybe-false`.
    - **decision_needed** -- There is an ambiguous choice that requires human input. The code cannot be correctly patched without knowing the user's intent. Only possible if `{review_mode}` = `"full"`.
    - **patch** -- Code issue that is fixable without human input. The correct fix is unambiguous, adds no public surface, and guards no state you did not demonstrate; otherwise `decision_needed`.
-   - **defer** -- Pre-existing issue not caused by the current change, real but not actionable now; or an entry whose members are all `maybe-false`; or any entry whose fix edits agent-context files (CLAUDE.md, AGENTS.md, rules, other specs). For maybe-false members, record what would settle them.
+   - **defer** -- Pre-existing issue not caused by the current change, real but not actionable now; or an entry whose members are all `maybe-false` and the claim, if true, would be `medium` or `high` -- record that severity marked unverified, plus what would settle it (if it would only be `low`, reject it with the same note); or any entry whose fix edits agent-context files (CLAUDE.md, AGENTS.md, rules, other specs).
 
    If `{review_mode}` = `"no-spec"` and an entry would otherwise be `decision_needed`, reclassify it as `patch` (if the fix is unambiguous) or `defer` (if not).
 

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.