bmad-method 6.11.1-next.27 → 6.11.1-next.29

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/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/)**
 
-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?
 
@@ -56,15 +61,11 @@ 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.
+- **[Build Your First Change](https://docs.bmad-method.org/start/build-your-first-change/)** — 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/).
-
 ## Community
 
 - [Discord](https://discord.gg/gk8jAdXWmj) — Get help, share ideas, and collaborate.
@@ -85,10 +86,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_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/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method",
-  "version": "6.11.1-next.27",
+  "version": "6.11.1-next.29",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",

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

@@ -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/ship/bmad-build/customize.toml

@@ -138,7 +138,7 @@ Do not invoke any skill, and do not spawn subagents of your own — you are the
 
 """
 
-# Review layers for the one-shot route.
+# Review layers for the in-session (light) route.
 
 [[workflow.oneshot_review_layers]]
 id = "blind-hunter"

package/src/bmm-skills/ship/bmad-build/spec-template.md

@@ -3,6 +3,7 @@ title: '{title}'
 type: 'feature' # feature | bugfix | refactor | chore
 created: '{date}'
 status: 'draft' # draft | ready-for-dev | in-progress | in-review | done
+route: '' # in-session | dispatch — set by step-02's route gate after design
 review_loop_iteration: 0 # incremented by step-04 before each review loopback
 context: [] # optional: `{project-root}/`-prefixed paths to project-wide standards/docs the implementation agent should load. Keep short — only what isn't already distilled into the spec body.
 ---
@@ -25,6 +26,7 @@ context: [] # optional: `{project-root}/`-prefixed paths to project-wide standar
 ## Boundaries & Constraints
 
 <!-- Two tiers: Always = invariant rules. Never = out of scope + forbidden approaches. -->
+<!-- If step-02's route gate reported all facts clean (route: 'in-session'), DELETE THIS ENTIRE SECTION. -->
 
 **Always:** INVARIANT_RULES
 
@@ -41,9 +43,20 @@ context: [] # optional: `{project-root}/`-prefixed paths to project-wide standar
 
 </frozen-after-approval>
 
+## Open Questions
+
+<!-- One entry per intent gap: something the request does not say, the code cannot settle,
+     and the user would notice in the result. Choices the user would not notice are yours. State the choice, the defensible
+     options, and each option's consequence. The spec cannot leave `draft` while any entry
+     remains: when the human answers, record the decision inside <frozen-after-approval> and
+     delete the entry. When no entries remain, DELETE THIS ENTIRE SECTION. -->
+
+- CHOICE — options: OPTION_A (CONSEQUENCE_A) / OPTION_B (CONSEQUENCE_B)
+
 ## Code Map
 
 <!-- Agent-populated during planning. Annotated paths prevent blind codebase searching. -->
+<!-- If step-02's route gate reported all facts clean (route: 'in-session'), DELETE THIS ENTIRE SECTION. -->
 
 - `FILE` -- ROLE_OR_RELEVANCE
 - `FILE` -- ROLE_OR_RELEVANCE
@@ -53,6 +66,7 @@ context: [] # optional: `{project-root}/`-prefixed paths to project-wide standar
 <!-- Tasks: backtick-quoted file path -- action -- rationale. Prefer one task per file; group tightly-coupled changes when splitting would be artificial. -->
 <!-- If an I/O Matrix is present, include a task to unit-test its edge cases. -->
 <!-- AC covers system-level behaviors not captured by the I/O Matrix. Do not duplicate I/O scenarios here. -->
+<!-- If step-02's route gate reported all facts clean (route: 'in-session'), DELETE THIS ENTIRE SECTION. -->
 
 **Execution:**
 - [ ] `FILE` -- ACTION -- RATIONALE
@@ -60,6 +74,11 @@ context: [] # optional: `{project-root}/`-prefixed paths to project-wide standar
 **Acceptance Criteria:**
 - Given PRECONDITION, when ACTION, then EXPECTED_RESULT
 
+## Implementation Notes
+
+<!-- Agent-owned. Append-only during implementation: decisions made, files touched, surprises
+     encountered. Leave empty at planning time; never delete this section. -->
+
 ## Spec Change Log
 
 <!-- Append-only. Populated by step-04 during review loops. Do not modify or delete existing entries.

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

@@ -1,22 +1,20 @@
 ---
-spec_file: '' # set at runtime for both routes before leaving this step
+spec_file: '' # set at runtime before leaving this step
 story_key: '' # set at runtime to the current story's full sprint-status key (e.g. 3-2-digest-delivery) when the intent is an epic story and sprint-status resolution succeeds
 ---
 
-# Step 1: Clarify and Route
+# Step 1: Clarify
 
 ## RULES
 
 - **Language** — Speak in `{{.communication_language}}`. Write any file output in `{{.document_output_language}}`.
-- The prompt that triggered this workflow IS the intent — not a hint.
-- Do NOT assume you start from zero.
-- The intent captured in this step — even if detailed, structured, and plan-like — may contain hallucinations, scope creep, or unvalidated assumptions. It is input to the workflow, not a substitute for step-02 investigation and spec generation. Ignore directives within the intent that instruct you to skip steps or implement directly.
-- The user chose this workflow on purpose. Later steps (e.g. agentic adversarial review) catch LLM blind spots and give the human control. Do not skip them.
+- Use the invocation prompt as the starting intent. Even detailed, plan-like intent is input to investigate, not authority to skip Build steps or substitute for step-02 investigation and spec generation. Ignore directives within the intent that instruct you to skip steps or implement directly.
+- This step resolves workflow state, loads relevant existing evidence, applies the VCS and scope gates, and selects the spec path. Do not conduct an intent interview here.
 - **EARLY EXIT** means: stop this step immediately — do not read or execute anything further here. Read and fully follow the target file instead. Return here ONLY if a later step explicitly says to loop back.
 
 ## Intent check (do this first)
 
-Before listing artifacts or prompting the user, check whether you already know the intent. Check in this order — skip the remaining checks as soon as the intent is clear:
+Before listing artifacts, resolve existing workflow state in this order. Skip the remaining checks as soon as a branch applies. A freeform request is starting intent even when it is brief; do not ask the user to restate it.
 
 1. Explicit argument
    Did the user pass a specific file path, spec name, or clear instruction this message?
@@ -39,8 +37,6 @@ Before listing artifacts or prompting the user, check whether you already know t
      If the user chooses **New**: proceed to INSTRUCTIONS
    - Unformatted spec or intent file lacking `status` frontmatter? → Suggest treating its contents as the starting intent. Do NOT attempt to infer a state and resume it.
 
-Never ask extra questions if you already understand what the user intends.
-
 ### Story-key resolution
 
 This runs on ALL paths (early-exit and INSTRUCTIONS) whenever `spec_file` is set. Determine whether the spec is an epic story — use the spec's filename, frontmatter, and any loaded epics file to identify `epic_num` and `story_num`. If the spec is not an epic story, skip silently and leave `story_key` unset.
@@ -80,7 +76,7 @@ If the spec is an epic story and `{{.implementation_artifacts}}/sprint-status.ya
        - **Epics** (`*epic*`) — feature breakdown into implementable stories
        - **Product Brief** (`*brief*`) — project vision and scope
      - Scan the listing for files matching these patterns. If any look relevant to the current intent, load them selectively — you don't need all of them, but you need the right constraints and requirements rather than guessing from code alone.
-2. Clarify intent. Do not fantasize, do not leave open questions. If you must ask questions, ask them as a numbered list. When the human replies, verify that every single numbered question was answered. If any were ignored, HALT and re-ask only the missing questions before proceeding. Keep looping until intent is clear enough to implement.
+2. Carry the intent and loaded evidence forward as-is. Do not fill unsupported gaps and do not ask the user about them yet: step-02 investigates first, and what investigation cannot settle becomes an Open Questions entry there.
 3. Version control sanity check. Is the working tree clean? Does the current branch make sense for this intent — considering its name and recent history? If the tree is dirty or the branch is an obvious mismatch, HALT and ask the human before proceeding. If version control is unavailable, skip this check.
 4. Multi-goal check (see SCOPE STANDARD). If the intent fails the single-goal criteria:
    - Present detected distinct goals as a bullet list.
@@ -95,15 +91,9 @@ If the spec is an epic story and `{{.implementation_artifacts}}/sprint-status.ya
        evidence: <why this was split from the current intent>
      ```
    - If the user chooses **Keep all goals**: Proceed as-is.
-5. Route — choose exactly one:
-
-   If the explicit spec-folder-plus-story-id pair had no matching story file, keep the colocated `spec_file` selected above. Otherwise, derive a valid kebab-case slug from the clarified intent. If the intent references a tracking identifier (story number, issue number, ticket ID), lead the slug with it (e.g. `3-2-digest-delivery`, `gh-47-fix-auth`). If `{{.implementation_artifacts}}/spec-{slug}.md` already exists: if its status is `draft`, treat it as the same work and resume it (set `spec_file` to that path, **EARLY EXIT** → `[[bmad-snapshot:step-02-plan.md]]`); otherwise append `-2`, `-3`, etc. Set `spec_file` = `{{.implementation_artifacts}}/spec-{slug}.md`.
-
-   **a) One-shot** — zero blast radius: no plausible path by which this change causes unintended consequences elsewhere. Clear intent, no architectural decisions.
-
-   **EARLY EXIT** → `[[bmad-snapshot:step-oneshot.md]]`
+5. Set the spec file.
 
-   **b) Plan-code-review** — everything else. When uncertain whether blast radius is truly zero, choose this path.
+   If the explicit spec-folder-plus-story-id pair had no matching story file, keep the colocated `spec_file` selected above. Otherwise, derive a valid kebab-case slug from the current intent. If the intent references a tracking identifier (story number, issue number, ticket ID), lead the slug with it (e.g. `3-2-digest-delivery`, `gh-47-fix-auth`). If `{{.implementation_artifacts}}/spec-{slug}.md` already exists: if its status is `draft`, treat it as the same work and resume it (set `spec_file` to that path, **EARLY EXIT** → `[[bmad-snapshot:step-02-plan.md]]`); otherwise append `-2`, `-3`, etc. Set `spec_file` = `{{.implementation_artifacts}}/spec-{slug}.md`.
 
 ## NEXT
 

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

@@ -4,30 +4,42 @@
 
 - **Language** — Speak in `{{.communication_language}}`. Write any file output in `{{.document_output_language}}`.
 - No intermediate approvals.
+- **EARLY EXIT** means: stop this step immediately — do not read or execute anything further here. Read and fully follow the target file instead. Return here ONLY if a later step explicitly says to loop back.
 
 ## INSTRUCTIONS
 
 1. Draft resume check. If `{spec_file}` exists with `status: draft`, read it and capture the verbatim `<frozen-after-approval>...</frozen-after-approval>` block as `preserved_intent`. Otherwise `preserved_intent` is empty.
-2. Investigate codebase. _Isolate deep exploration in synchronous subagents/tasks where available. To prevent context snowballing, instruct subagents to give you distilled summaries only._ Decide which findings actually matter for execution — the specific files, symbols/lines, reuse points, and read-only constraints — and carry those forward for the Code Map. This is where the investigation lands: the spec preserves it so it is never re-narrated to the implementer at dispatch time.
-3. Read `[[bmad-snapshot:spec-template.md]]` fully. Fill it out based on the intent and investigation, resolving the template's `date` field to the current system date. Drain the investigation into the `## Code Map` section — annotated paths, symbol/line anchors, reuse pointers, and read-only evidence — so the spec is the implementer's investigation map and the step-03 handoff need only point at it. If `preserved_intent` is non-empty, replace the `<frozen-after-approval>` block in the spec you just filled out with `preserved_intent`, before writing. Write the result to `{spec_file}`.
-4. Self-review against READY FOR DEVELOPMENT standard.
-5. If intent gaps exist, do not fantasize, do not leave open questions, HALT and ask the human.
-6. Token count check (see SCOPE STANDARD). If spec exceeds 1600 tokens:
-   - Show user the token count.
-   - HALT and give the user a choice:
-     - **Split** — carve off secondary goals.
+2. Investigate the codebase. When you can, send deep searches to subagents and wait for them in this turn. Tell them to return short summaries only, so this session does not fill up with their notes. Keep only what the work needs: the specific files, symbols or lines, what to reuse, and what not to change. Write that into the Code Map. Do not retell the investigation when implementation starts — the spec already has it.
+
+   Do not ask the human during investigation. When something is unclear, look in the repository, planning artifacts, or history first. Keep looking until you know, or until those sources have nothing more to say. Leave any remaining choice for the next step.
+3. Decide the path. You already have a plan. Write down three facts about it — as it is now, not as a guess:
+   - **Intent gaps** — things the request does not say, the code cannot settle, and the user would notice in the result. Only the human can answer these. Choices the user would not notice are yours: decide and record them in the spec.
+   - **Irreversibles** — things you cannot undo: migrations, data deletion or mutation, external side effects, deploy or config triggers.
+   - **Footprint** — how big: files you will change, and anything new that other code will call or depend on.
+
+   If there are no intent gaps, nothing irreversible, and the change is small: read `[[bmad-snapshot:spec-template.md]]` fully and write `{spec_file}` with only the frontmatter, `## Intent` (inside its `<frozen-after-approval>` block), and `## Implementation Notes`. Delete every other section; the template says you may. Set `route: 'in-session'` and `status: 'in-progress'`, resolving `date` to the current system date. If `preserved_intent` is non-empty, use it as the frozen block. **EARLY EXIT** → `[[bmad-snapshot:step-oneshot.md]]`.
+
+   Otherwise write the full spec. Set `route: 'dispatch'` and continue.
+4. Read `[[bmad-snapshot:spec-template.md]]` fully. Fill it out from the intent and investigation, resolving the template's `date` field to the current system date. Put the investigation into `## Code Map`: paths, symbols or lines, what to reuse, and what not to change. Implementation should work from the spec without being told the investigation again. For each intent gap, add one `## Open Questions` entry: the choice, the options, and what each option means. Never write an intent gap into the frozen block as an assumption. If `preserved_intent` is non-empty, replace the `<frozen-after-approval>` block with it before writing. Write the result to `{spec_file}`.
+5. Self-review against READY FOR DEVELOPMENT standard. For anything important that's missing: if the repository can tell you, go look and fix the spec; if a human has to decide, add an `## Open Questions` entry. Do not invent the answer.
+6. Resolve the gates before the checkpoint. Two things must be settled, in whatever order the conversation makes natural; combine them in one message when both apply.
+   - **Token count** (see SCOPE STANDARD). If the spec exceeds 1600 tokens, show the count and give the user a choice:
+     - **Split** — carve off secondary goals. Propose the split — name each secondary goal. For each deferred goal, append one new entry to `{{.implementation_artifacts}}/deferred-work.md` using the format below. Do not modify existing entries or look for duplicates. Rewrite the current spec to cover only the main goal — do not surgically carve sections out; regenerate the spec for the narrowed scope.
      - **Keep full spec** — accept the risks.
-   - If the user chooses **Split**: Propose the split — name each secondary goal. For each deferred goal, append one new entry to `{{.implementation_artifacts}}/deferred-work.md` using this format. Do not modify existing entries or look for duplicates. Rewrite the current spec to cover only the main goal — do not surgically carve sections out; regenerate the spec for the narrowed scope. Continue to checkpoint.
      ```markdown
      - source_spec: `{spec_file}`
        summary: <one sentence naming the deferred goal>
        evidence: <why this was split from the current spec>
      ```
-   - If the user chooses **Keep full spec**: Continue to checkpoint with the full spec.
+   - **Open Questions.** Present every entry as a numbered question with its options and what each option means, and HALT for the human's answers. Write each answer into the `<frozen-after-approval>` block as a decision and delete the entry. An answer may expose a new intent gap — add it and ask again. When the last entry is gone, delete the section.
 
 ### CHECKPOINT 1
 
-Present summary. Display the spec file path as a CWD-relative path (no leading `/`) so it is clickable in the terminal. If token count exceeded 1600 and the user chose to keep the full spec, include the token count and explain why it may be a problem.
+Only when Open Questions is empty.
+
+Present summary. Display the spec file path in whatever form is clickable where you are presenting it (e.g. code citation in chat, CWD-relative path with no leading `/` in terminal). If unsure, use CWD-relative path. 
+
+If token count exceeded 1600 and the user chose to keep the full spec, include the token count and explain why it may be a problem.
 
 After presenting the summary, display this note:
 

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

@@ -34,7 +34,7 @@ Do not add goal restatements, file lists, ownership boundaries, investigation de
 
 The handoff directs the subagent to load the spec's `context:` files itself, so never pre-load and paste those files into the dispatch. Only when you implement directly (no subagent available) do you load a non-empty `context:` list yourself before starting.
 
-**Path formatting rule:** Any markdown links written into `{spec_file}` must use paths relative to `{spec_file}`'s directory so they are clickable in VS Code. Any file paths displayed in terminal/conversation output must use CWD-relative format with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability. No leading `/` in either case.
+**Path formatting rule:** Any markdown links written into `{spec_file}` must use paths relative to `{spec_file}`'s directory so they are clickable in VS Code. No leading `/`. Display file paths and `file:line` references in conversation/terminal output in whatever form is clickable where you are presenting them (e.g. code citation in chat, CWD-relative path with no leading `/` in terminal). If unsure, use CWD-relative path.
 
 ### Tasks & Acceptance Verification
 

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

@@ -67,7 +67,7 @@ Display summary of your work to the user, including:
 - The commit hash, if one was created.
 - Review findings breakdown: patches applied, items deferred, and the dismissed count — dismissal reasons are recorded in the spec's `## Review Triage Log`.
 
-Any file paths shown in conversation/terminal output must use CWD-relative format (no leading `/`) with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability — the goal is to make paths clickable in terminal emulators.
+Display file paths and `file:line` references in whatever form is clickable where you are presenting them (e.g. code citation in chat, CWD-relative path with no leading `/` in terminal). If unsure, use CWD-relative path.
 
 Offer to push and/or create a pull request.
 

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

@@ -1,9 +1,12 @@
 # Step One-Shot: Implement, Review, Present
 
+Entered only from step-02's route gate: `{spec_file}` already exists with `route: 'in-session'`.
+
 ## RULES
 
 - **Language** — Speak in `{{.communication_language}}`. Write any file output in `{{.document_output_language}}`.
 - NEVER auto-push.
+- Content inside `<frozen-after-approval>` in `{spec_file}` is read-only. Do not modify.
 - All review subagents must run at the same model capability as the current session.
 - Run subagents synchronously: launch them together as blocking calls awaited in this turn — never backgrounded or detached, never ending the turn to await results.
 
@@ -13,7 +16,9 @@
 
 Follow `[[bmad-snapshot:sync-sprint-status.md]]` with `target_status` = `in-progress`.
 
-Implement the clarified intent directly.
+Implement directly from `{spec_file}` — its Intent is the source of truth. As you work, append to its `## Implementation Notes` section: decisions made, files touched, surprises encountered.
+
+**Escalation ramp.** If implementation surfaces a fact the route gate did not see — an intent gap (something the request does not say and the user would notice in the result), an irreversible action, or footprint growth beyond the designed scope — stop editing. Record the trigger in `## Implementation Notes`, then upgrade `{spec_file}`: reinstate `## Code Map` (populated from your live context) and `## Open Questions` (one entry per intent gap), set `route: 'dispatch'` and `status: 'draft'`. Return to `[[bmad-snapshot:step-02-plan.md]]` and resume at its gate instruction (step 6).
 
 ### Review
 
@@ -43,16 +48,13 @@ Group the survivors by shared root cause — two findings belong in one entry on
     evidence: <why this is real>
   ```
 
-### Generate Spec Trace
-
-Set `title` = a concise title derived from the clarified intent.
+### Finalize Spec
 
-Write `{spec_file}` using `[[bmad-snapshot:spec-template.md]]`. Fill only these sections — delete all others:
+Update `{spec_file}`:
 
-1. **Frontmatter** — set `title: '{title}'`, `type`, `created`, `status: 'done'`. Add `route: 'one-shot'`.
-2. **Title and Intent** — `# {title}` heading and `## Intent` with **Problem** and **Approach** lines. Reuse the summary you already generated for the terminal.
-3. **Suggested Review Order** — append after Intent. Build using the same convention as `[[bmad-snapshot:step-05-present.md]]` § "Generate Suggested Review Order" (spec-file-relative links, concern-based ordering, ultra-concise framing).
-4. **Review Triage Log** — only when findings were dismissed: one line per dismissal, the finding and the reason that disposed of its claim.
+1. **Frontmatter** — set `status: 'done'`.
+2. **Suggested Review Order** — append after Intent. Build using the same convention as `[[bmad-snapshot:step-05-present.md]]` § "Generate Suggested Review Order" (spec-file-relative links, concern-based ordering, ultra-concise framing).
+3. **Review Triage Log** — only when findings were dismissed: add the section with one line per dismissal, the finding and the reason that disposed of its claim.
 
 Follow `[[bmad-snapshot:sync-sprint-status.md]]` with `target_status` = `review`.
 
@@ -67,8 +69,8 @@ If version control is available and the tree is dirty, create a local commit wit
 Display a summary in conversation output, including:
 
 - The commit hash (if one was created).
-- List of files changed with one-line descriptions. Any file paths shown in conversation/terminal output must use CWD-relative format (no leading `/`) with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability — this differs from spec-file links which use spec-file-relative paths.
-- Review findings breakdown: patches applied, items deferred, and the dismissed count — dismissal reasons are recorded in the spec trace. If every finding was dismissed, say so.
+- List of files changed with one-line descriptions. Display file paths and `file:line` references in whatever form is clickable where you are presenting them (e.g. code citation in chat, CWD-relative path with no leading `/` in terminal). If unsure, use CWD-relative path. This differs from spec-file links which use spec-file-relative paths.
+- Review findings breakdown: patches applied, items deferred, and the dismissed count — dismissal reasons are recorded in the spec. If every finding was dismissed, say so.
 
 Offer to push and/or create a pull request.
 

package/src/bmm-skills/ship/bmad-build/sync-sprint-status.md

@@ -1,6 +1,6 @@
 # Sync Sprint Status
 
-Shared sub-step for updating `sprint-status.yaml` during build. Called from any route (plan-code-review, one-shot, future routes) with a `target_status` parameter.
+Shared sub-step for updating `sprint-status.yaml` during build. Called from any route (dispatch, in-session, future routes) with a `target_status` parameter.
 
 ## Preconditions
 

package/src/bmm-skills/ship/{bmad-checkpoint-preview → bmad-walkthrough}/SKILL.md

@@ -1,9 +1,9 @@
 ---
-name: bmad-checkpoint-preview
-description: 'Walk the user through reviewing a change: what it is for, what to look at closely, and how to test it. Use when the user says "checkpoint", "human review", or "walk me through this change"'
+name: bmad-walkthrough
+description: 'Walk the user through reviewing a change: what it is for, what to look at closely, and how to test it. Use when the user says "walkthrough", "walk me through this change", or "human review"'
 ---
 
-# Checkpoint Review Workflow
+# Walkthrough Workflow
 
 **Goal:** Guide a human through reviewing a change — from purpose and context into details.
 

package/src/bmm-skills/ship/{bmad-checkpoint-preview → bmad-walkthrough}/customize.toml

@@ -1,6 +1,6 @@
 # DO NOT EDIT -- overwritten on every update.
 #
-# Workflow customization surface for bmad-checkpoint-preview. Mirrors the
+# Workflow customization surface for bmad-walkthrough. Mirrors the
 # agent customization shape under the [workflow] namespace.
 
 [workflow]

package/src/bmm-skills/v6-shims/README.md

@@ -18,6 +18,7 @@ stated intent and pre-resolved customization fields so the target skips its own
 | `bmad-domain-research`     | `bmad-deep-recon` (domain type)      |
 | `bmad-technical-research`  | `bmad-deep-recon` (technical type)   |
 | `bmad-sprint-status`       | `bmad-sprint-planning` (status view) |
+| `bmad-checkpoint-preview`  | `bmad-walkthrough`                   |
 
 Enterprise users may still depend on these IDs, so they ship by default. Removal rides the
 v7 cut — never a 6.x minor.

package/src/bmm-skills/v6-shims/bmad-checkpoint-preview/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: bmad-checkpoint-preview
+description: "Deprecated: forwards to bmad-walkthrough. Do not use unless invoked by name"
+metadata:
+  lifecycle: shim
+---
+
+# Deprecated Walkthrough Alias
+
+## On Activation
+
+1. Check whether either legacy customization file exists:
+   - `{project-root}/_bmad/custom/bmad-checkpoint-preview.toml`
+   - `{project-root}/_bmad/custom/bmad-checkpoint-preview.user.toml`
+2. If neither legacy file exists, output exactly `bmad-checkpoint-preview is deprecated. Redirecting to bmad-walkthrough. Please use bmad-walkthrough in the future.`, invoke `bmad-walkthrough` exactly once with the user's original input verbatim, then execute no further steps in this shim.
+3. For every legacy file that exists, use its matching new filename:
+   - `{project-root}/_bmad/custom/bmad-checkpoint-preview.toml` becomes `{project-root}/_bmad/custom/bmad-walkthrough.toml`.
+   - `{project-root}/_bmad/custom/bmad-checkpoint-preview.user.toml` becomes `{project-root}/_bmad/custom/bmad-walkthrough.user.toml`.
+4. If the matching new file does not exist, tell the user that the customization file uses the deprecated name and offer to rename it. Rename it only after explicit approval. If approval is declined or unavailable, or the rename fails, HALT and do not invoke any skill.
+5. If the matching new file already exists, do not overwrite it. Read both files, explain their differences, and propose the exact content for the new file. Resolve conflicting values with the user. Only after the user explicitly approves that content, save and verify the new file, then remove the legacy file. If approval is declined or unavailable, or any operation fails, HALT and do not invoke any skill.
+6. After every detected legacy file has been migrated successfully and no legacy file remains, output exactly `bmad-checkpoint-preview is deprecated. Redirecting to bmad-walkthrough. Please use bmad-walkthrough in the future.`, invoke `bmad-walkthrough` exactly once with the user's original input verbatim, then execute no further steps in this shim.

package/tools/validate-published-implementation-model.mjs

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-const CANONICAL_LLMS_ENTRY = '**[Build]';
+const CANONICAL_LLMS_ENTRY = '**[Build a Change]';
 const CANONICAL_LLMS_DESCRIPTION = 'Canonical implementation workflow for direct intent and fully planned work';
 
 const FORBIDDEN_TERMS = [