bmad-method 6.11.1-next.4 → 6.11.1-next.41

package/.claude-plugin/marketplace.json

@@ -34,11 +34,11 @@
         "./src/bmm-skills/plan/bmad-sprint-planning",
         "./src/bmm-skills/plan/bmad-ux",
         "./src/bmm-skills/ship/bmad-build",
-        "./src/bmm-skills/ship/bmad-checkpoint-preview",
         "./src/bmm-skills/ship/bmad-code-review",
         "./src/bmm-skills/ship/bmad-correct-course",
         "./src/bmm-skills/ship/bmad-qa-generate-e2e-tests",
         "./src/bmm-skills/ship/bmad-retrospective",
+        "./src/bmm-skills/ship/bmad-walkthrough",
         "./src/core-skills/bmad-advanced-elicitation",
         "./src/core-skills/bmad-brainstorming",
         "./src/core-skills/bmad-customize",

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/README.md

@@ -1,5 +1,10 @@
 ![BMad Method](banner-bmad-method.png)
 
+
+[![Version](https://img.shields.io/npm/v/bmad-method?color=blue&label=version)](https://www.npmjs.com/package/bmad-method)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Discord](https://img.shields.io/badge/Discord-Join%20Community-7289da?logo=discord&logoColor=white)](https://discord.gg/gk8jAdXWmj)
+
 **Agile Ai Driven Development — turn an idea or change request into working software without giving up the thinking.**
 
 Ai Driven Development (AiDD) covers the whole effort, not only the code: what to build, how it holds together, and how it changes as you learn. BMad Method is the agile way to do it — decisions stay explicit, context carries forward, and the process sizes itself to the work. Small changes go straight to build. Complex work gets the depth it needs. The same method covers a weekend prototype and a system with years of history behind it.
@@ -18,11 +23,11 @@ npx bmad-method install
 
 Open your project in your AI coding tool, invoke `bmad-build` with what you want to change, and keep making the decisions that matter. Run `bmad-help` whenever you want guidance on what comes next or what is optional.
 
-**[Build your first project with BMad →](https://docs.bmad-method.org/tutorials/getting-started/)**
+**[Build your first project with BMad →](https://docs.bmad-method.org/start/build-your-first-change/)**
 
-**[Add BMad to an existing codebase →](https://docs.bmad-method.org/how-to/established-projects/)**
+**[Add BMad to an existing codebase →](https://docs.bmad-method.org/existing-codebases/start-in-an-existing-codebase/)**
 
-BMad is free and open source, with no paywalled workflows or gated community. For prerelease builds, CI/CD, configuration overrides, and non-interactive setup, see the [installation guide](https://docs.bmad-method.org/how-to/install-bmad/).
+BMad is free and open source, with no paywalled workflows or gated community. For installation prerequisites, updates, prerelease builds, and the installer's live automation help, see the [installation guide](https://docs.bmad-method.org/start/install-bmad/).
 
 ## Why BMad?
 
@@ -35,7 +40,7 @@ Coding assistants are effective at implementation, but they often turn unstated
 - **Guided collaboration** — Use structured workflows and multiple-agent discussions without handing over judgment.
 - **One delivery path** — Move from early thinking through reviewed implementation, correction, and learning.
 
-[See how the workflows fit together →](https://docs.bmad-method.org/reference/workflow-map/)
+[See how much planning a change needs →](https://docs.bmad-method.org/plan/choose-a-planning-path/)
 
 ## BMad Ecosystem
 
@@ -56,14 +61,9 @@ Install the core method or add official modules for specialized work.
 
 ## Documentation
 
-- **[Getting Started](https://docs.bmad-method.org/tutorials/getting-started/)** — Install BMad and build a small project.
-- **[Workflow Map](https://docs.bmad-method.org/reference/workflow-map/)** — Understand the available paths and outputs.
-- **[Established Projects](https://docs.bmad-method.org/how-to/established-projects/)** — Add BMad to an existing codebase.
-- **[Upgrade to V6](https://docs.bmad-method.org/how-to/upgrade-to-v6/)** — Migrate from an earlier version.
-
-## Roadmap
-
-See what is in progress and what is planned on the [public roadmap](https://docs.bmad-method.org/roadmap/).
+- **[Build Your First Change](https://docs.bmad-method.org/start/build-your-first-change/)** — Install BMad and build a small project.
+- **[Choose a Planning Path](https://docs.bmad-method.org/plan/choose-a-planning-path/)** — Pick how much planning a change needs and see what each planning skill produces.
+- **[Start in an Existing Codebase](https://docs.bmad-method.org/existing-codebases/start-in-an-existing-codebase/)** — Add BMad to an existing codebase.
 
 ## Community
 
@@ -85,10 +85,4 @@ MIT License — see [LICENSE](LICENSE) for details.
 
 **BMad** and **BMAD-METHOD** are trademarks of BMad Code, LLC. See [TRADEMARK.md](TRADEMARK.md) for details.
 
-[![Contributors](https://contrib.rocks/image?repo=bmad-code-org/BMAD-METHOD)](https://github.com/bmad-code-org/BMAD-METHOD/graphs/contributors)
-
-See [CONTRIBUTORS.md](CONTRIBUTORS.md) for contributor information.
-
-[![Version](https://img.shields.io/npm/v/bmad-method?color=blue&label=version)](https://www.npmjs.com/package/bmad-method)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![Discord](https://img.shields.io/badge/Discord-Join%20Community-7289da?logo=discord&logoColor=white)](https://discord.gg/gk8jAdXWmj)
+If you would like to contribute, join us in the discord and read [CONTRIBUTORS.md](CONTRIBUTORS.md) first.

package/README_CN.md

@@ -24,14 +24,6 @@
 
 ---
 
-## 🚀 BMad 的下一步是什么？
-
-**V6 已经上线，而这只是开始。** BMad 仍在快速演进：跨平台智能体团队与子智能体集成、Skills 架构、BMad Builder v1、Dev Loop 自动化等能力都在持续推进。
-
-**[📍 查看完整路线图 →](https://docs.bmad-method.org/zh-cn/roadmap/)**
-
----
-
 ## 快速开始
 
 **先决条件**：[Node.js](https://nodejs.org) v20+
@@ -103,6 +95,4 @@ MIT 许可证 — 详见 [LICENSE](LICENSE)。
 
 **BMad** 和 **BMAD-METHOD** 是 BMad Code, LLC 的商标。详见 [TRADEMARK.md](TRADEMARK.md)。
 
-[![Contributors](https://contrib.rocks/image?repo=bmad-code-org/BMAD-METHOD)](https://github.com/bmad-code-org/BMAD-METHOD/graphs/contributors)
-
 请参阅 [CONTRIBUTORS.md](CONTRIBUTORS.md) 了解贡献者信息。

package/README_KR.md

@@ -0,0 +1,90 @@
+![BMad Method](banner-bmad-method.png)
+
+[![버전](https://img.shields.io/npm/v/bmad-method?color=blue&label=%EB%B2%84%EC%A0%84)](https://www.npmjs.com/package/bmad-method)
+[![라이선스: MIT](https://img.shields.io/badge/%EB%9D%BC%EC%9D%B4%EC%84%A0%EC%8A%A4-MIT-yellow.svg)](LICENSE)
+[![Discord](https://img.shields.io/badge/Discord-%EC%BB%A4%EB%AE%A4%EB%8B%88%ED%8B%B0%20%EC%B0%B8%EC%97%AC-7289da?logo=discord&logoColor=white)](https://discord.gg/gk8jAdXWmj)
+
+[English](README.md) | [简体中文](README_CN.md) | [Tiếng Việt](README_VN.md) | 한국어
+
+**애자일 AI 주도 개발 — 사고 과정을 포기하지 않고 아이디어나 변경 요청을 실제 작동하는 소프트웨어로 바꿉니다.**
+
+AI 주도 개발(AiDD)은 코드 작성에 그치지 않습니다. 무엇을 만들지, 각 요소가 어떻게 맞물리는지, 새롭게 알게 된 내용에 따라 어떻게 바꿀지까지 개발 전반을 아우릅니다. BMad Method는 이를 애자일 방식으로 실천합니다. 결정은 명확히 남고 컨텍스트는 다음 작업으로 이어지며 작업 규모에 맞춰 절차도 달라집니다. 작은 변경은 바로 Build로 진행하고 복잡한 작업은 필요한 만큼 깊이 계획합니다. 주말에 만드는 프로토타입부터 오랜 역사를 지닌 시스템까지 같은 방법으로 다룹니다.
+
+![BMad 전달 루프: 막연한 생각은 구체화부터, 크고 명확한 아이디어는 계획부터 시작하며 작은 변경은 바로 구현 및 검증으로 이어집니다. 학습 및 조정 단계에서 얻은 내용은 다시 계획에 반영됩니다.](docs/images/bmad-delivery-loop-ko.svg)
+
+_어디서든 시작하세요. BMad를 처음부터 끝까지 사용해도 되고 개요·사양·아키텍처만 기존 개발 흐름에 가져와도 됩니다._
+
+## 바로 시작하기
+
+**필수 조건:** [Node.js](https://nodejs.org) 20.12+, [Python](https://www.python.org) 3.10+, [uv](https://docs.astral.sh/uv/)
+
+```bash
+npx bmad-method install
+```
+
+프로젝트를 AI 코딩 도구에서 열고 `bmad-build`에 원하는 변경을 말하세요. 중요한 결정은 직접 내리면서 작업을 이어 가면 됩니다. 다음 단계나 선택 사항을 안내받고 싶을 때는 언제든 `bmad-help`를 실행하세요.
+
+**[BMad로 첫 변경 사항 구현하기 →](https://docs.bmad-method.org/ko-kr/start/build-your-first-change/)**
+
+**[기존 코드베이스에 BMad 적용하기 →](https://docs.bmad-method.org/ko-kr/how-to/established-projects/)**
+
+BMad는 무료 오픈 소스이며 유료 전용 워크플로나 가입이 제한된 커뮤니티가 없습니다. 설치 필수 조건, 업데이트, 사전 릴리스 빌드, 설치 프로그램의 최신 자동화 도움말은 [설치 가이드](https://docs.bmad-method.org/ko-kr/start/install-bmad/)를 참고하세요.
+
+## 왜 BMad인가요?
+
+코딩 도우미는 구현에는 능숙하지만 명시하지 않은 가정을 그대로 코드로 옮기기도 합니다. BMad는 중요한 결정을 명확히 드러내고 다음 작업에 필요한 컨텍스트로 남기는 에이전트와 워크플로를 제공합니다. 판단은 사용자가 직접 내립니다.
+
+- **작업에 맞는 절차** — 명확한 변경은 바로 구현하고 큰 과제는 더 깊이 계획합니다.
+- **신규·기존 코드 모두 지원** — 빈 프로젝트에서 시작하거나, 물려받은 코드베이스의 컨텍스트를 검증해 현재 상태에 맞춰 작업합니다.
+- **지속되는 컨텍스트** — 대화할 때마다 다시 설명하지 않아도 제품과 기술 결정을 다음 작업으로 이어 갑니다.
+- **분야별 관점** — 필요할 때 제품, 아키텍처, UX, 개발, 테스트 전문가의 관점을 활용합니다.
+- **안내형 협업** — 판단을 맡기지 않고도 구조화된 워크플로와 여러 에이전트의 토론을 활용합니다.
+- **하나로 이어지는 개발 흐름** — 초기 구상부터 검토를 거친 구현, 방향 수정, 학습까지 한 흐름으로 진행합니다.
+
+[워크플로가 어떻게 연결되는지 보기 →](https://docs.bmad-method.org/ko-kr/reference/workflow-map/)
+
+## BMad 생태계
+
+핵심 프레임워크만 설치하거나 전문 작업을 위한 공식 모듈을 추가합니다.
+
+| 모듈 | 용도 |
+| --- | --- |
+| **[BMad Method](https://github.com/bmad-code-org/BMAD-METHOD)** | 새 프로토타입부터 기존 코드베이스까지 소프트웨어를 계획하고 완성합니다. |
+| **[BMad Builder](https://github.com/bmad-code-org/bmad-builder)** | 스킬, 워크플로, 에이전트를 만듭니다. |
+| **[BMad Creative Intelligence Suite](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite)** | 혁신, 디자인 사고, 스토리텔링을 위한 창의적 사고 파트너를 제공합니다. |
+| **[BMad Test Architect](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise)** | BMad Method에 엔터프라이즈 테스트 기능을 더합니다. |
+| **[BMad Loop](https://github.com/bmad-code-org/bmad-loop)** | 에픽 전체를 사람의 개입 없이 구현하고 검증한 뒤 회고합니다. |
+| **[BMad Game Dev Studio](https://github.com/bmad-code-org/bmad-module-game-dev-studio)** | Unity, Unreal, Godot, Phaser를 비롯한 모든 프레임워크에서 게임을 구상하고 설계해 구현합니다. |
+
+## 웹에서 계획하기
+
+[Web bundle](https://bmadcode.com/web-bundles/)은 일부 BMad 워크플로를 Google Gemini Gem과 ChatGPT Custom GPT로 패키징한 것입니다. 기존 웹 구독 환경에서 계획을 세운 뒤, 그 결과물을 AI 코딩 도구로 가져와 구현에 사용하세요.
+
+## 문서
+
+- **[첫 변경 사항 구현하기](https://docs.bmad-method.org/ko-kr/start/build-your-first-change/)** — BMad를 설치하고 작은 프로젝트를 만듭니다.
+- **[워크플로 맵](https://docs.bmad-method.org/ko-kr/reference/workflow-map/)** — 사용할 수 있는 경로와 산출물을 살펴봅니다.
+- **[기존 프로젝트](https://docs.bmad-method.org/ko-kr/how-to/established-projects/)** — 기존 코드베이스에 BMad를 적용합니다.
+- **[v6로 업그레이드](https://docs.bmad-method.org/ko-kr/how-to/upgrade-to-v6/)** — 이전 버전에서 마이그레이션합니다.
+
+## 커뮤니티
+
+- [Discord](https://discord.gg/gk8jAdXWmj) — 도움을 받고 아이디어를 나누며 협업합니다.
+- [YouTube](https://youtube.com/@BMadCode) — 튜토리얼과 마스터 클래스를 시청합니다.
+- [GitHub Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues) — 버그를 제보하고 기능을 요청합니다.
+- [GitHub Discussions](https://github.com/bmad-code-org/BMAD-METHOD/discussions) — 커뮤니티의 긴 대화에 참여합니다.
+- [BMad Code](https://bmadcode.com) — 더 넓은 BMad 생태계를 둘러봅니다.
+
+## 후원과 기여
+
+BMad는 누구에게나 무료이며 앞으로도 계속 무료로 제공됩니다. 저장소에 스타를 누르거나 [커피 한 잔을 후원](https://buymeacoffee.com/bmad)해 주세요. 기업 후원은 <contact@bmadcode.com>으로 문의해 주세요.
+
+기여를 환영합니다. Pull Request를 열기 전에 [CONTRIBUTING.md](CONTRIBUTING.md)를 읽어 주세요.
+
+## 라이선스
+
+MIT 라이선스를 따릅니다. 자세한 내용은 [LICENSE](LICENSE)를 참고하세요.
+
+**BMad**와 **BMAD-METHOD**는 BMad Code, LLC의 상표입니다. 자세한 내용은 [TRADEMARK.md](TRADEMARK.md)를 참고하세요.
+
+기여하려면 Discord에 참여하고 먼저 [CONTRIBUTORS.md](CONTRIBUTORS.md)를 읽어 주세요.

package/README_VN.md

@@ -28,14 +28,6 @@ Các công cụ AI truyền thống thường làm thay phần suy nghĩ của b
 
 ---
 
-## 🚀 Điều gì tiếp theo cho BMad?
-
-**V6 đã có mặt và đây mới chỉ là khởi đầu!** BMad Method đang phát triển rất nhanh với các cải tiến như đội agent đa nền tảng và tích hợp sub-agent, kiến trúc Skills, BMad Builder v1, tự động hóa vòng lặp phát triển và nhiều thứ khác vẫn đang được xây dựng.
-
-**[📍 Xem lộ trình đầy đủ →](https://docs.bmad-method.org/vi-vn/roadmap/)**
-
----
-
 ## Bắt đầu nhanh
 
 **Điều kiện tiên quyết**: [Node.js](https://nodejs.org) v20+ · [Python](https://www.python.org) 3.10+ · [uv](https://docs.astral.sh/uv/)
@@ -104,6 +96,4 @@ Giấy phép MIT - xem [LICENSE](LICENSE) để biết chi tiết.
 
 **BMad** và **BMAD-METHOD** là các nhãn hiệu của BMad Code, LLC. Xem [TRADEMARK.md](TRADEMARK.md) để biết chi tiết.
 
-[![Contributors](https://contrib.rocks/image?repo=bmad-code-org/BMAD-METHOD)](https://github.com/bmad-code-org/BMAD-METHOD/graphs/contributors)
-
 Xem [CONTRIBUTORS.md](CONTRIBUTORS.md) để biết thông tin về những người đóng góp.

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.4",
+  "version": "6.11.1-next.41",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",
@@ -40,20 +40,21 @@
     "lint:fix": "eslint . --ext .js,.cjs,.mjs,.yaml --fix",
     "lint:md": "markdownlint-cli2 \"**/*.md\"",
     "prepare": "command -v husky >/dev/null 2>&1 && husky || exit 0",
-    "quality": "npm run format:check && npm run lint && npm run lint:md && npm run docs:build && npm run test:site-url && npm run test:install && npm run test:urls && npm run test:renderer && npm run test:retrospective && npm run test:sprint-planning && npm run validate:refs && npm run validate:skills && npm run docs:validate-sidebar",
+    "quality": "npm run format:check && npm run lint && npm run lint:md && npm run docs:build && npm run test:site-url && npm run test:implementation-model && npm run test:install && npm run test:urls && npm run test:renderer && npm run test:retrospective && npm run test:sprint-planning && npm run validate:refs && npm run validate:skills && npm run docs:validate-sidebar",
     "rebundle": "node tools/installer/bundlers/bundle-web.js rebundle",
-    "test": "npm run test:refs && npm run test:install && npm run test:urls && npm run test:site-url && npm run test:channels && npm run test:renderer && npm run test:retrospective && npm run test:sprint-planning && npm run test:skills && npm run lint && npm run lint:md && npm run format:check",
+    "test": "npm run test:refs && npm run test:install && npm run test:urls && npm run test:site-url && npm run test:implementation-model && npm run test:channels && npm run test:renderer && npm run test:retrospective && npm run test:sprint-planning && npm run test:skills && npm run lint && npm run lint:md && npm run format:check",
     "test:channels": "node test/test-installer-channels.js",
-    "test:install": "node test/test-installation-components.js",
+    "test:implementation-model": "node test/test-validate-published-implementation-model.mjs",
+    "test:install": "node test/test-installation-components.js && node test/test-shim-policy.js",
     "test:refs": "node test/test-file-refs-csv.js",
     "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/agents/bmad-agent-analyst/SKILL.md

@@ -20,7 +20,7 @@ You are Mary, the Business Analyst. You bring deep expertise in market research,
 
 ### Step 1: Resolve the Agent Block
 
-Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key agent`
+Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key agent`
 
 **If the script fails**, resolve the `agent` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
 

package/src/bmm-skills/agents/bmad-agent-analyst/customize.toml

@@ -35,9 +35,7 @@ activation_steps_append = []
 #   - a file reference prefixed with `file:`, e.g. "file:{project-root}/docs/standards.md"
 #     (glob patterns are supported; the file's contents are loaded and treated as facts).
 
-persistent_facts = [
-  "file:{project-root}/**/project-context.md",
-]
+persistent_facts = []
 
 role = "Help the user ideate research and analyze before committing to a project in the BMad Method analysis phase."
 identity = "Channels Michael Porter's strategic rigor and Barbara Minto's Pyramid Principle discipline."

package/src/bmm-skills/agents/bmad-agent-architect/SKILL.md

@@ -20,7 +20,7 @@ You are Winston, the System Architect. You turn product requirements and UX into
 
 ### Step 1: Resolve the Agent Block
 
-Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key agent`
+Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key agent`
 
 **If the script fails**, resolve the `agent` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
 

package/src/bmm-skills/agents/bmad-agent-architect/customize.toml

@@ -35,9 +35,7 @@ activation_steps_append = []
 #   - a file reference prefixed with `file:`, e.g. "file:{project-root}/docs/standards.md"
 #     (glob patterns are supported; the file's contents are loaded and treated as facts).
 
-persistent_facts = [
-  "file:{project-root}/**/project-context.md",
-]
+persistent_facts = []
 
 role = "Convert the PRD and UX into technical architecture decisions that keep implementation on track during the BMad Method solutioning phase."
 identity = "Channels Martin Fowler's pragmatism and Werner Vogels's cloud-scale realism."

package/src/bmm-skills/agents/bmad-agent-dev/SKILL.md

@@ -20,7 +20,7 @@ You are Amelia, the Senior Software Engineer. You execute approved stories with
 
 ### Step 1: Resolve the Agent Block
 
-Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key agent`
+Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key agent`
 
 **If the script fails**, resolve the `agent` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
 

package/src/bmm-skills/agents/bmad-agent-dev/customize.toml

@@ -35,9 +35,7 @@ activation_steps_append = []
 #   - a file reference prefixed with `file:`, e.g. "file:{project-root}/docs/standards.md"
 #     (glob patterns are supported; the file's contents are loaded and treated as facts).
 
-persistent_facts = [
-  "file:{project-root}/**/project-context.md",
-]
+persistent_facts = []
 
 role = "Implement approved stories with test-first discipline and ship working, verified code during the BMad Method implementation phase."
 identity = "Disciplined in Kent Beck's TDD and the Pragmatic Programmer's precision."

package/src/bmm-skills/agents/bmad-agent-pm/SKILL.md

@@ -20,7 +20,7 @@ You are John, the Product Manager. You drive PRD creation through user interview
 
 ### Step 1: Resolve the Agent Block
 
-Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key agent`
+Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key agent`
 
 **If the script fails**, resolve the `agent` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
 

package/src/bmm-skills/agents/bmad-agent-pm/customize.toml

@@ -35,9 +35,7 @@ activation_steps_append = []
 #   - a file reference prefixed with `file:`, e.g. "file:{project-root}/docs/standards.md"
 #     (glob patterns are supported; the file's contents are loaded and treated as facts).
 
-persistent_facts = [
-  "file:{project-root}/**/project-context.md",
-]
+persistent_facts = []
 
 role = "Translate product vision into a validated PRD, epics, and stories that development can execute during the BMad Method planning phase."
 identity = "Thinks like Marty Cagan and Teresa Torres. Writes with Bezos's six-pager discipline."

package/src/bmm-skills/agents/bmad-agent-ux-designer/SKILL.md

@@ -20,7 +20,7 @@ You are Sally, the UX Designer. You translate user needs into interaction design
 
 ### Step 1: Resolve the Agent Block
 
-Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key agent`
+Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key agent`
 
 **If the script fails**, resolve the `agent` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
 

package/src/bmm-skills/agents/bmad-agent-ux-designer/customize.toml

@@ -35,9 +35,7 @@ activation_steps_append = []
 #   - a file reference prefixed with `file:`, e.g. "file:{project-root}/docs/standards.md"
 #     (glob patterns are supported; the file's contents are loaded and treated as facts).
 
-persistent_facts = [
-  "file:{project-root}/**/project-context.md",
-]
+persistent_facts = []
 
 role = "Turn user needs and the PRD into UX design specifications that inform architecture and implementation during the BMad Method planning phase."
 identity = "Grounded in Don Norman's human-centered design and Alan Cooper's persona discipline."

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

@@ -1,5 +1,5 @@
 module,skill,display-name,menu-code,description,action,args,phase,preceded-by,followed-by,required,output-location,outputs
-BMad Method,_meta,,,,,,,,,false,https://docs.bmad-method.org/llms.txt,
+BMad Method,_meta,,,,,,,,,false,https://docs.bmad-method.org/,
 BMad Method,bmad-project-context,Project Context,PC,"Set up or refresh a repo's agent instructions so AI agents work well in it: verified commands, policy, conventions that differ from defaults, and known pitfalls. Setup, refresh, record, and audit — replaces document-project and generate-project-context.",,,anytime,,,false,repo root,AGENTS.md managed block
 BMad Method,bmad-build,Build,BD,"The standard implementation flow: clarify intent, plan, implement, review, and present.",,,ship,bmad-sprint-planning,bmad-code-review,true,implementation_artifacts,spec and project implementation
 BMad Method,bmad-spec,Spec,SPC,"Condense any input (brief, PRD, transcript, brain dump, design folder, or several sources at once) into a short SPEC.md plus supporting files that later work builds from. Pins down what to build before deciding how. Works for software, game design, research, editorial, policy, business — anything with an intent behind it. Can also validate an existing spec.",,[path],anytime,,,false,{output_folder}/specs/spec-{slug},SPEC.md + companion files
@@ -14,6 +14,6 @@ BMad Method,bmad-create-epics-and-stories,Create Epics and Stories,CE,Break the
 BMad Method,bmad-sprint-planning,Sprint Planning,SP,"Checks the planning is complete enough to implement (PASS/CONCERNS/FAIL), then generates the sprint status file that implementation agents follow for every story.",,,plan,,,true,implementation_artifacts,sprint status
 BMad Method,bmad-sprint-planning,Sprint Status,SS,"Summarize sprint progress at any time: risks, open action items, and the recommended next action. Can also validate or repair the tracking file.",status,,anytime,,,false,,status summary
 BMad Method,bmad-code-review,Code Review,CR,Ad hoc review of any code change. An optional extra check after Build's built-in review.,,,ship,bmad-build,,false,,
-BMad Method,bmad-checkpoint-preview,Checkpoint,CK,"Guided walkthrough of a change, from purpose and context into details. Use for human review of commits, branches, or PRs.",,,ship,,,false,,
+BMad Method,bmad-walkthrough,Walkthrough,WT,"Guided walkthrough of a change, from purpose and context into details. Use for human review of commits, branches, or PRs.",,,ship,,,false,,
 BMad Method,bmad-qa-generate-e2e-tests,QA Automation Test,QA,Generate automated API and end-to-end tests for implemented code. Not for code review or story validation — use Code Review for that.,,,ship,bmad-build,,false,implementation_artifacts,test suite
 BMad Method,bmad-retrospective,Retrospective,ER,"Optional at the end of an epic: review the completed work and lessons learned, and look ahead to the next epic. If major issues surfaced, consider Correct Course.",,,ship,bmad-code-review,,false,implementation_artifacts,retrospective

package/src/bmm-skills/plan/bmad-architecture/SKILL.md

@@ -50,7 +50,7 @@ Writes go through the shared script (don't read the file back except on resume):
 
 **Forwarded activation:** if a caller invoked you with a stated intent and pre-resolved customization fields, honor them verbatim — skip your own intent inference, use the supplied values for those named fields, and resolve only the remaining fields from your own `customize.toml`.
 
-1. Resolve customization: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow` (on failure read `{skill-root}/customize.toml`, use defaults). Run `{workflow.activation_steps_prepend}`, then `{workflow.activation_steps_append}`. Hold `{workflow.persistent_facts}` as standing context — the default loads `project-context.md`, load-bearing for brownfield — and consult `{workflow.external_sources}` on demand.
+1. Resolve customization: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow` (on failure read `{skill-root}/customize.toml`, use defaults). Run `{workflow.activation_steps_prepend}`, then `{workflow.activation_steps_append}`. Hold `{workflow.persistent_facts}` as standing context — empty unless the user opted in — and consult `{workflow.external_sources}` on demand.
 2. Resolve config: `uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root}` (merges `_bmad/config.toml`, `_bmad/config.user.toml`, and the `_bmad/custom/` overrides). From the merged JSON resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{project_name}` (under `core`), `{planning_artifacts}` (under `modules.bmm`), and `{date}`; missing keys take neutral defaults, never block.
 3. Headless (no interactive user) → follow `references/headless.md` for the whole run. Otherwise greet `{user_name}` in `{communication_language}`. Detect the intent from the conversation and input — **create** (the default), **update** an existing spine, or **validate** one (see those sections). If the real ask is requirements / UX / a capability contract / epic breakdown / an agent, invoke the `bmad-prd`, `bmad-ux`, `bmad-spec`, `bmad-create-epics-and-stories`, or `bmad-workflow-builder` (if the BMad Builder module is installed) skill instead.
 4. If a run folder for this target already exists under `{workflow.spine_output_path}`, offer to resume from its memlog rather than restart.

package/src/bmm-skills/plan/bmad-architecture/customize.toml

@@ -24,14 +24,13 @@ activation_steps_append = []
 # Each entry is either a literal sentence, a skill prefixed with `skill:`, or a `file:`-prefixed
 # path/glob whose contents are loaded as facts.
 #
-# Default loads project-context.md if bmad-generate-project-context produced one — giving the
-# architect persistent awareness of the project's tech, domain, and conventions (load-bearing
-# for brownfield). Common opt-ins (set in team/user override TOML):
+# Empty by default. Repo-wide context belongs in AGENTS.md (see bmad-project-context), which every
+# skill already sees; use this for context only this skill needs, loaded on demand rather than
+# carried as constant memory. Common opt-ins (set in team/user override TOML):
 #   "Our org is AWS-only -- do not propose GCP or Azure."
 #   "file:{project-root}/docs/engineering-standards.md"
-persistent_facts = [
-  "file:{project-root}/**/project-context.md",
-]
+#   "file:{project-root}/**/project-context.md"           # if you keep a project-context.md
+persistent_facts = []
 
 # Executed when the workflow completes (after the spine is final and the user has been told).
 # String scalar (single instruction) or array of instructions executed in order. Empty for none.

package/src/bmm-skills/plan/bmad-create-epics-and-stories/SKILL.md

@@ -51,7 +51,7 @@ This uses **step-file architecture** for disciplined execution:
 
 ### Step 1: Resolve the Workflow Block
 
-Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`
+Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow`
 
 **If the script fails**, resolve the `workflow` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
 

package/src/bmm-skills/plan/bmad-create-epics-and-stories/customize.toml

@@ -30,9 +30,7 @@ activation_steps_append = []
 #   - a file reference prefixed with `file:`, e.g. "file:{project-root}/docs/standards.md"
 #     (glob patterns are supported; the file's contents are loaded and treated as facts).
 
-persistent_facts = [
-  "file:{project-root}/**/project-context.md",
-]
+persistent_facts = []
 
 # Scalar: executed when the workflow reaches Step 4 (Final Validation) and the
 # user confirms [C] Complete — after the epics.md is saved and bmad-help is invoked.

package/src/bmm-skills/plan/bmad-create-epics-and-stories/steps/step-04-final-validation.md

@@ -138,6 +138,6 @@ Upon Completion of task output: offer to answer any questions about the Epics an
 
 ## On Complete
 
-Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete`
+Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow.on_complete`
 
 If the resolved `workflow.on_complete` is non-empty, follow it as the final terminal instruction before exiting.

package/src/bmm-skills/plan/bmad-generate-project-context/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: bmad-generate-project-context
 description: 'Deprecated — forwards to bmad-project-context. Use when the user says "generate project context" or "create project context"'
+metadata:
+  lifecycle: shim
 ---
 
 # DEPRECATED — forwards to bmad-project-context

package/src/bmm-skills/plan/bmad-prd/SKILL.md

@@ -17,7 +17,7 @@ You are a master facilitator and coach helping the user create, edit, or validat
 
 **Forwarded activation:** if a caller invoked you with a stated intent and pre-resolved customization fields (e.g. the `bmad-create-prd` / `bmad-edit-prd` / `bmad-validate-prd` shims), honor them verbatim — skip your own intent inference, use the supplied values for those named fields, and resolve only the remaining fields from your own `customize.toml`.
 
-1. Resolve customization: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, read `{skill-root}/customize.toml` directly and use defaults.
+1. Resolve customization: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow`. On failure, read `{skill-root}/customize.toml` directly and use defaults.
 2. Run `{workflow.activation_steps_prepend}`. Treat `{workflow.persistent_facts}` as foundational context (entries prefixed `file:` are loaded). `{workflow.external_sources}` is an org-configured registry of internal tools (knowledge bases, MCP tools); consult them alongside generic web research on the same triggers, org tools preferred when their directive matches. Research itself fires during Discovery — see **Research subagents**.
 3. Load `{project-root}/_bmad/bmm/config.yaml` (+ `config.user.yaml` if present). Resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{planning_artifacts}`, `{project_name}`, `{date}`. Missing keys → neutral defaults; never block.
 4. If headless, follow `references/headless.md` for the whole run. Otherwise greet the user **by name** using `{user_name}` and **in their language** using `{communication_language}` — and stay in `{communication_language}` for every turn for the entire run, not just the greeting. In the greeting, let the user know that at any point they can invoke `bmad-party-mode` for multi-agent perspectives or `bmad-advanced-elicitation` for deeper exploration on a specific section. Then scan for misroute on the first message: if the signal points elsewhere (game → BMad GDS; express build → `bmad-build`; one-pager → `bmad-product-brief`; vet product idea → `bmad-prfaq`; agent skill or custom agent → `bmad-workflow-builder`), suggest they might want the other options before continuing.

package/src/bmm-skills/plan/bmad-prd/customize.toml

@@ -24,14 +24,13 @@ activation_steps_append = []
 # Each entry is either a literal sentence, a skill prefixed with `skill:`, or a `file:`-prefixed path/glob
 # whose contents are loaded as facts.
 #
-# Default loads project-context.md if bmad-generate-project-context has produced one — this gives
-# the facilitator persistent awareness of the project's tech, domain, and constraints without
-# re-asking. Common opt-ins (set in team/user override TOML):
+# Empty by default. Repo-wide context belongs in AGENTS.md (see bmad-project-context), which every
+# skill already sees; use this for context only this skill needs, loaded on demand rather than
+# carried as constant memory. Common opt-ins (set in team/user override TOML):
+#   "file:{project-root}/**/project-context.md"                               # if you keep a project-context.md
 #   "skill:acme-co:terms-and-conditions"                                      # a skill that contains some relevant info
 #   "Investor PRDs must include a market sizing section."                    # generic agent instruction
-persistent_facts = [
-  "file:{project-root}/**/project-context.md",
-]
+persistent_facts = []
 
 # Executed when the workflow completes (after the user has been told the
 # PRD is ready). Accepts either a string scalar (single instruction)

package/src/bmm-skills/plan/bmad-prfaq/SKILL.md

@@ -30,7 +30,7 @@ The PRFAQ forces customer-first clarity: write the press release announcing the
 
 ### Step 1: Resolve the Workflow Block
 
-Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`
+Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow`
 
 **If the script fails**, resolve the `workflow` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
 

package/src/bmm-skills/plan/bmad-prfaq/customize.toml

@@ -30,9 +30,7 @@ activation_steps_append = []
 #   - a file reference prefixed with `file:`, e.g. "file:{project-root}/docs/standards.md"
 #     (glob patterns are supported; the file's contents are loaded and treated as facts).
 
-persistent_facts = [
-  "file:{project-root}/**/project-context.md",
-]
+persistent_facts = []
 
 # Scalar: executed when the workflow reaches its terminal stage (Stage 5: The Verdict),
 # after the PRFAQ and distillate have been delivered. Override wins. Leave empty for

package/src/bmm-skills/plan/bmad-prfaq/references/verdict.md

@@ -78,6 +78,6 @@ purpose: "Token-efficient context for downstream PRD creation"
 
 This is the terminal stage. If the user wants to revise, loop back to the relevant stage. Otherwise, the workflow is done.
 
-Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete`
+Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow.on_complete`
 
 If the resolved `workflow.on_complete` is non-empty, follow it as the final terminal instruction before exiting.