bmad-method 6.10.1-next.20 → 6.10.1-next.21

package/package.json

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

package/src/bmm-skills/4-implementation/bmad-dev-auto/spec-template.md

@@ -48,10 +48,10 @@ warnings: [] # optional: machine-readable warnings for orchestration, e.g. overs
 
 ## Code Map
 
-<!-- Agent-populated during planning. Annotated paths prevent blind codebase searching. -->
+<!-- Agent-populated during planning: the distilled investigation map, so the spec carries what exploration found and the implementation handoff need only point here. Annotated paths prevent blind codebase searching. Entries may drill to symbol/line and carry reuse pointers ("mirror X at FILE:LINE") or read-only evidence, where they save the implementer a search. -->
 
 - `FILE` -- ROLE_OR_RELEVANCE
-- `FILE` -- ROLE_OR_RELEVANCE
+- `FILE:LINE` -- ROLE_OR_RELEVANCE; reuse pointer or READ-ONLY evidence when relevant
 
 ## Tasks & Acceptance
 

package/src/bmm-skills/4-implementation/bmad-dev-auto/step-02-plan.md

@@ -12,8 +12,8 @@ deferred_work_file: '{implementation_artifacts}/deferred-work.md'
 ## INSTRUCTIONS
 
 1. Draft resume check. If `{spec_file}` exists with `status: draft`, read it and capture the verbatim `<intent-contract>...</intent-contract>` block as `preserved_intent_contract`. Otherwise `preserved_intent_contract` is empty.
-2. Investigate codebase. _Read the code yourself for narrow, localized tasks. Isolate deep exploration in synchronous subagents: instruct them to give you distilled summaries only, and plan from those summaries._
-3. Read `./spec-template.md` fully. Fill it out based on the intent and investigation. If `{preserved_intent_contract}` is non-empty, substitute it for the `<intent-contract>` block in your filled spec before writing. Write the result to `{spec_file}`.
+2. Investigate codebase. _Read the code yourself for narrow, localized tasks. Isolate deep exploration in synchronous subagents: instruct them to give you distilled summaries only, and plan from those summaries._ 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 `./spec-template.md` fully. Fill it out based on the intent and investigation. 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_contract}` is non-empty, substitute it for the `<intent-contract>` block in your filled spec before writing. Write the result to `{spec_file}`.
 4. Self-review against READY FOR DEVELOPMENT standard.
 5. If intent gaps exist, do not fantasize and do not leave open questions. Multiple defensible readings of the intent that lead to observably different outcomes, with nothing in the intent to select between them, are an intent gap — do not resolve one by picking a reading. HALT with status `blocked`, blocking condition `intent gap`, and include the unanswered questions and evidence gathered.
 6. Warning check. If step-01 carried `multiple-goals`, add it to `{spec_file}` frontmatter `warnings`. If `{spec_file}` exceeds 1600 tokens, add `oversized` to frontmatter `warnings`. Continue either way.

package/src/bmm-skills/4-implementation/bmad-quick-dev/customize.toml

@@ -33,6 +33,29 @@ persistent_facts = [
 
 on_complete = ""
 
+# Handoff for the implementation subagent in step 03 — nailed down here the same
+# way the review layers below are, so the main session never improvises a fat
+# dispatch prompt. The spec is the subagent's sole source of truth; investigation
+# findings belong in the spec's Code Map (see step 02), not re-narrated here.
+# {spec_file} is substituted at run time. An override may replace the whole recipe
+# (e.g. drive an external coding tool via bash).
+
+implementation_handoff = """
+Launch a subagent with no prior conversation context, with this prompt:
+
+> Read {spec_file} fully and implement it. The spec is the sole source of truth for this change; its Code Map is your investigation map, and its Spec Change Log entries are binding constraints, not history.
+>
+> Guardrails:
+>
+> - Work in the current project. Before starting, load every file listed in the spec frontmatter `context:`.
+> - Do not edit the spec file itself.
+> - Do not commit or push — that happens later in the workflow.
+> - Do not revert or overwrite changes unrelated to this spec.
+> - Run the verification described in the spec, plus focused checks for the code you touched.
+>
+> When done, report: files changed with one line each, verification commands run and their outcomes, any files changed beyond the spec's tasks and why each was needed, anything you could not complete and why, and residual risks.
+"""
+
 # Review layers for the review step. `instruction` is the layer's whole
 # execution recipe — subagents by default, but an override may run anything
 # (e.g. an external reviewer via bash). {diff_output} is substituted at run

package/src/bmm-skills/4-implementation/bmad-quick-dev/spec-template.md

@@ -46,10 +46,10 @@ context: [] # optional: `{project-root}/`-prefixed paths to project-wide standar
 
 ## Code Map
 
-<!-- Agent-populated during planning. Annotated paths prevent blind codebase searching. -->
+<!-- Agent-populated during planning: the distilled investigation map, so the spec carries what exploration found and the implementation handoff need only point here. Annotated paths prevent blind codebase searching. Entries may drill to symbol/line and carry reuse pointers ("mirror X at FILE:LINE") or read-only evidence, where they save the implementer a search. -->
 
 - `FILE` -- ROLE_OR_RELEVANCE
-- `FILE` -- ROLE_OR_RELEVANCE
+- `FILE:LINE` -- ROLE_OR_RELEVANCE; reuse pointer or READ-ONLY evidence when relevant
 
 ## Tasks & Acceptance
 

package/src/bmm-skills/4-implementation/bmad-quick-dev/step-02-plan.md

@@ -8,8 +8,8 @@
 ## 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._
-3. Read `./spec-template.md` fully. Fill it out based on the intent and investigation, resolving the template's `date` field to the current system date. 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}`.
+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 `./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:

package/src/bmm-skills/4-implementation/bmad-quick-dev/step-03-implement.md

@@ -26,9 +26,13 @@ Change `{spec_file}` status to `in-progress` in the frontmatter before starting
 
 Follow `./sync-sprint-status.md` with `target_status` = `in-progress`.
 
-If `{spec_file}` has a non-empty `context:` list in its frontmatter, load those files before implementation begins. When handing to a subagent, include them in the subagent prompt so it has access to the referenced context.
+Execute the implementation handoff below: substitute the runtime placeholders (e.g. `{spec_file}`) into it, then follow it verbatim.
 
-Hand `{spec_file}` to a subagent/task and let it implement. If no subagents are available, implement directly. If the platform allows, keep the subagent available for re-engagement after it returns — step-04 may send it review fixes.
+{workflow.implementation_handoff}
+
+Do not add goal restatements, file lists, ownership boundaries, investigation detail, acceptance criteria, or CLAUDE.md/house-style rules to the dispatch — the spec is the subagent's sole source of truth, and that material already lives in it (investigation findings in its Code Map, the rest in the spec body). One line of sanctioned hedging belongs in the spec at planning time, not in the dispatch. If no subagents are available, implement directly from the spec. If the platform allows, keep the subagent available for re-engagement after it returns — step-04 may send it review fixes.
+
+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.