bmad-method 6.11.1-next.36 → 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.36",
+  "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/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.