bmad-method 6.11.1-next.2 → 6.11.1-next.21

package/src/bmm-skills/ship/bmad-code-review/review-prompts/edge-case-hunter.md

@@ -5,10 +5,12 @@ When a diff is provided, scan only the diff hunks and list boundaries that are d
 When no diff is provided (full file or function), treat the entire provided content as the scope.
 Ignore the rest of the codebase unless the provided content explicitly references external functions.
 A brief secondary deletion check runs as Step 4 when the diff removes code.
+A claims check runs as Step 5 when the launch message names a claims file.
 
 **Inputs:**
-- **content** — Content to review: diff, full file, or function
+- **content** — Content to review, or a path to read it from: diff, full file, or function
 - **also_consider** (optional) — Areas to keep in mind during review alongside normal edge-case analysis
+- **claims_file** (optional) — Path to the change's stated narrative. Do NOT read it before Step 5: the path tracing in Steps 2–3 must finish before the narrative is seen.
 
 **MANDATORY: Execute steps in the Execution section IN EXACT ORDER. DO NOT skip steps or change the sequence. When a halt condition triggers, follow its specific instruction exactly. Each action within a step is a REQUIRED action to complete that step.**
 
@@ -19,8 +21,8 @@ A brief secondary deletion check runs as Step 4 when the diff removes code.
 
 ### Step 1: Receive Content
 
-- Load the content to review strictly from the parent message that launched you (not from this instruction file)
-- If content is empty, or cannot be decoded as text, return `[{"location":"N/A","trigger_condition":"Input empty or undecodable","guard_snippet":"Provide valid content to review","potential_consequence":"Review skipped — no analysis performed"}]` and stop
+- Take the content to review from the parent message that launched you — inline, or by reading the file it points to (never from this instruction file)
+- If no content is supplied, or it is empty, unreadable, or cannot be decoded as text, return `[{"location":"N/A","trigger_condition":"Input empty or undecodable","guard_snippet":"Provide valid content to review","potential_consequence":"Review skipped — no analysis performed"}]` and stop
 - Identify content type (diff, full file, or function) to determine scope rules
 
 ### Step 2: Exhaustive Path Analysis
@@ -42,7 +44,11 @@ A brief secondary deletion check runs as Step 4 when the diff removes code.
 
 If the diff removed or replaced meaningful code (ignore pure renames and whitespace): load `references/deletion-check.md` and follow it.
 
-### Step 5: Present Findings
+### Step 5: Claims Check
+
+If the launch message provided a `claims_file` path and the file exists and is non-empty: load `references/claims-check.md` and follow it.
+
+### Step 6: Present Findings
 
 Output all findings as a single JSON array following the Output Format specification exactly.
 
@@ -60,12 +66,12 @@ Return ONLY a valid JSON array of objects. Each edge-case finding contains exact
 }]
 ```
 
-No extra text, no explanations, no markdown wrapping. An empty array `[]` is valid when nothing is found. Deletion findings from Step 4, if any, go in the same array with the extra fields defined in `references/deletion-check.md`.
+No extra text, no explanations, no markdown wrapping. An empty array `[]` is valid when nothing is found. Deletion findings from Step 4 and claim findings from Step 5, if any, go in the same array with the extra fields defined in `references/deletion-check.md` and `references/claims-check.md`.
 
 
 ## HALT CONDITIONS
 
-- If content is empty or cannot be decoded as text, return `[{"location":"N/A","trigger_condition":"Input empty or undecodable","guard_snippet":"Provide valid content to review","potential_consequence":"Review skipped — no analysis performed"}]` and stop
+- If no content is supplied, or it is empty, unreadable, or cannot be decoded as text, return `[{"location":"N/A","trigger_condition":"Input empty or undecodable","guard_snippet":"Provide valid content to review","potential_consequence":"Review skipped — no analysis performed"}]` and stop
 <reference path="references/deletion-check.md">
 # Deletion Check
 
@@ -82,7 +88,23 @@ For a deletion finding the standard fields read as: `location` = the removed ite
 
 Add nothing if nothing qualifies.
 </reference>
+<reference path="references/claims-check.md">
+# Claims Check
+
+Final pass for the Edge Case Hunter — runs only when the message that launched you named a claims file. Read that file now, for the first time; the path tracing is finished and the claims cannot steer it retroactively.
+
+The file holds the change's own narrative — commit messages and any stated description. The narrative is the author's testimony, not evidence: a claim repeated in a code comment is still the same claim, not confirmation. Extract each checkable claim — what the change does, what it preserves, ordering, arithmetic, and parity with existing code ("exactly as X does") — then try to falsify each one against the code you have already traced. Where your trace is not enough to decide, read the code that decides it: the compared-to function, the actual callee, the state the claim assumes.
+
+Append one finding per falsified claim to the same JSON array, with the four standard fields plus:
+
+- `kind`: `"claim"`
+- `confidence`: `"high"`, `"medium"`, or `"low"`
+
+For a claim finding the standard fields read as: `location` = where the code contradicts the claim; `trigger_condition` = the claim, quoted or tightly paraphrased; `guard_snippet` = what the code actually does; `potential_consequence` = what goes wrong for someone who believed the claim.
+
+Verified claims produce nothing. Add nothing if nothing is falsified.
+</reference>
 
 ## CONTENT SOURCE
 
-Review the content supplied under "Review content:" in the message that launched you.
+"Review content:" in the message that launched you gives the content itself or a path to read it from. Read the file when it is a path; either way that is the content under review, and this instruction file never is.

package/src/bmm-skills/ship/bmad-code-review/review-prompts/verification-gap.md

@@ -110,4 +110,4 @@ When you find no verification gaps and no other findings, output exactly this si
 
 ## CONTENT SOURCE
 
-Review the content supplied under "Review content:" in the message that launched you. If none is supplied, stop with exactly: `No verification gaps found.`
+"Review content:" in the message that launched you gives the content itself or a path to read it from. Read the file when it is a path; either way that is the content under review, and this instruction file never is. If no content is supplied, or it is empty or unreadable, stop with exactly: `No verification gaps found.`

package/src/bmm-skills/ship/bmad-code-review/steps/step-01-gather-context.md

@@ -1,5 +1,6 @@
 ---
-diff_output: '' # set at runtime
+diff_file: '' # set at runtime: path to the diff file
+claims_file: '' # set at runtime (path or empty)
 spec_file: '' # set at runtime (path or empty)
 review_mode: '' # set at runtime: "full" or "no-spec"
 story_key: '' # set at runtime when discovered from sprint status
@@ -11,7 +12,7 @@ story_key: '' # set at runtime when discovered from sprint status
 
 - YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
 - The prompt that triggered this workflow IS the intent — not a hint.
-- Do not modify any files. This step is read-only.
+- Writing `{diff_file}` and the claims file is the only change this step may make. Otherwise it is read-only.
 
 ## INSTRUCTIONS
 
@@ -35,7 +36,10 @@ story_key: '' # set at runtime when discovered from sprint status
 
    **Tier 3 — Sprint tracking.**
    Look for a sprint status file (`*sprint-status*`) in `{implementation_artifacts}` or `{planning_artifacts}`. If found, scan for stories with status `review`:
-   - **Exactly one `review` story:** Set `{story_key}` to the story's key (e.g., `1-2-user-auth`). Suggest it: "I found story <story-id> in `review` status. Would you like to review its changes? [Y] Yes / [N] No, let me choose". If confirmed, use the story context to determine the diff source (branch name derived from story slug, or uncommitted changes). If declined, clear `{story_key}` and fall through.
+   - **Exactly one `review` story:** Set `{story_key}` to the story's key (e.g., `1-2-user-auth`). HALT and give the user a choice:
+     - **Review this story** — review the detected story `<story-id>` (status `review`).
+     - **Choose another target** — pick a different review target.
+     If the user chooses **Review this story**, use the story context to determine the diff source (branch name derived from story slug, or uncommitted changes). If they choose **Choose another target**, clear `{story_key}` and fall through.
    - **Multiple `review` stories:** Present them as numbered options alongside a manual choice option. Wait for user selection. If a story is selected, set `{story_key}` and use its context to determine the diff source. If manual choice is selected, clear `{story_key}` and fall through.
    - **None:** Fall through.
 
@@ -54,16 +58,19 @@ story_key: '' # set at runtime when discovered from sprint status
    - **Specific commit range** (ask for the range)
    - **Provided diff or file list** (user pastes or provides a path)
 
-3. Construct `{diff_output}` from the chosen source.
-   - For **staged changes only**: run `git diff --cached`.
-   - For **uncommitted changes** (staged + unstaged): run `git diff HEAD`.
-   - For **branch diff**: verify the base branch exists before running `git diff`. If it does not exist, HALT and ask the user for a valid branch.
-   - For **commit range**: verify the range resolves. If it does not, HALT and ask the user for a valid range.
-   - For **provided diff**: validate the content is non-empty and parseable as a unified diff. If it is not parseable, HALT and ask the user to provide a valid diff.
-   - For **file list**: validate each path exists in the working tree. Construct `{diff_output}` by running `git diff HEAD -- <path1> <path2> ...`. If any paths are untracked (new files not yet staged), use `git diff --no-index /dev/null <path>` to include them. If the diff is empty (files have no uncommitted changes and are not untracked), ask the user whether to review the full file contents or to specify a different baseline.
-   - After constructing `{diff_output}`, verify it is non-empty regardless of source type. If empty, HALT and tell the user there is nothing to review.
+3. Write the diff for the chosen source to `{diff_file}` — a uniquely-named file in the system temp directory, so concurrent reviews cannot collide. The review layers read that file; the diff text is never pasted into their prompts.
+   - For **staged changes only**: run `git diff --cached > {diff_file}`.
+   - For **uncommitted changes** (staged + unstaged): run `git diff HEAD > {diff_file}`.
+   - For **branch diff**: verify the base branch exists, then run `git diff <base-branch>...HEAD > {diff_file}`. If it does not exist, HALT and ask the user for a valid branch.
+   - For **commit range**: verify the range resolves, then run `git diff <range> > {diff_file}`. If it does not resolve, HALT and ask the user for a valid range.
+   - For **provided diff**: validate the content is non-empty and parseable as a unified diff. If it is not parseable, HALT and ask the user to provide a valid diff. Write the validated diff to `{diff_file}`.
+   - For **file list**: validate each path exists in the working tree. Run `git diff HEAD -- <path1> <path2> ... > {diff_file}`. If any paths are untracked (new files not yet staged), append them with `git diff --no-index /dev/null <path> >> {diff_file}`. If the diff is empty (files have no uncommitted changes and are not untracked), ask the user whether to review the full file contents or to specify a different baseline.
+   - After writing `{diff_file}`, verify it is non-empty regardless of source type. If empty, HALT and tell the user there is nothing to review.
+   - Read `{diff_file}` yourself whenever you need the diff for your own context — triage and presentation later in this workflow.
 
-4. **Set the spec context.**
+4. **Stage the claims file.** Collect the change's own narrative: for a branch diff or commit range, the commit messages it covers (`git log <base>..<head>`); for other sources, whatever description of the change the user or conversation supplied. Write it verbatim to a uniquely-named file in the system temp directory and set `{claims_file}` to its path. If there is no narrative, set `{claims_file}` = `''`. Do not analyze or summarize the narrative — it is input for one review layer, staged as a file precisely so the other layers never see it.
+
+5. **Set the spec context.**
    - If the triggering request or recent conversation **explicitly** states there is no spec (e.g. "no spec", "without a spec", "no-spec"): set `{review_mode}` = `"no-spec"` and clear `{spec_file}` (set it to `''`). Do **not** ask for a spec. Do **not** infer no-spec mode merely because the invocation omitted a spec path.
    - Else if `{spec_file}` is already set (from Tier 1 or Tier 2): verify the file exists and is readable, then set `{review_mode}` = `"full"`.
    - Else (neither a spec path nor an explicit no-spec declaration is present): ask the user to choose:
@@ -72,10 +79,10 @@ story_key: '' # set at runtime when discovered from sprint status
      - If the user provides a path: set `{spec_file}` to that path, verify the file exists and is readable, then set `{review_mode}` = `"full"`.
      - If the user explicitly chooses to continue without a spec: set `{review_mode}` = `"no-spec"`.
 
-5. If `{review_mode}` = `"full"` and the file at `{spec_file}` has a `context` field in its frontmatter listing additional docs, load each referenced document. Warn the user about any docs that cannot be found.
+6. If `{review_mode}` = `"full"` and the file at `{spec_file}` has a `context` field in its frontmatter listing additional docs, load each referenced document. Warn the user about any docs that cannot be found.
 
-6. Sanity check: if `{diff_output}` exceeds approximately 3000 lines, warn the user and offer to chunk the review by file group.
-   - If the user opts to chunk: agree on the first group, narrow `{diff_output}` accordingly, and list the remaining groups for the user to note for follow-up runs.
+7. Sanity check: if `wc -l {diff_file}` exceeds approximately 3000 lines, warn the user and offer to chunk the review by file group.
+   - If the user opts to chunk: agree on the first group, rebuild `{diff_file}` narrowed to that group, and list the remaining groups for the user to note for follow-up runs.
    - If the user declines: proceed as-is with the full diff.
 
 ### CHECKPOINT

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

@@ -8,7 +8,7 @@ failed_layers: '' # set at runtime: comma-separated list of layers that failed o
 
 - YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
 - All review subagents must run at the same model capability as the current session.
-- Run subagents synchronously: launch them together, then wait for all results before continuing.
+- Run subagents synchronously: launch them together as blocking calls awaited in this turn — never backgrounded or detached, never ending the turn to await results.
 
 ## INSTRUCTIONS
 
@@ -21,7 +21,7 @@ failed_layers: '' # set at runtime: comma-separated list of layers that failed o
 
    If no layer is active, HALT with status `blocked` and blocking condition `no active review layers`.
 
-3. Execute all active layers in parallel wherever their execution methods allow: expand `{skill-root}` in each layer's `instruction` to this skill's absolute installed directory, then substitute the runtime placeholders (`{diff_output}`, `{spec_file}`). For an instruction that launches a reviewer subagent, launch that child with the prompt text after placeholder substitution; do not load the reviewer instruction file yourself. For any other customized instruction, execute it as written. Do not leave `{skill-root}` unresolved in a child prompt. If a layer's instruction requires subagents and subagents are not available, for each such layer write under `{implementation_artifacts}` the exact child prompt from that layer's instruction after placeholder substitution (not a path-only pointer), then HALT. Ask the user to run each in a separate session (ideally a different LLM) and paste back the findings. When findings are pasted, treat them as those layers' findings and resume from this point. This is the only allowed parent-side read of a reviewer instruction file.
+3. Announce skipped layers first, then launch every active layer before handling any layer's result. Try running all active layers simultaneously: expand `{skill-root}` in each layer's `instruction` to this skill's absolute installed directory, then substitute the runtime placeholders (`{diff_file}`, `{claims_file}`, `{spec_file}`). `{diff_file}` is a path: substitute the path itself and let the layer read the file — a launch prompt never carries diff text. For an instruction that launches a reviewer subagent, launch that child with the prompt text after placeholder substitution; do not load the reviewer instruction file yourself. For any other customized instruction, execute it as written. Do not leave `{skill-root}` unresolved in a child prompt, and resolve `{diff_file}` to an absolute path — the child's working directory is not yours. If a layer's instruction requires subagents and subagents are not available, for each such layer write under `{implementation_artifacts}` that layer's child prompt with everything after its content label replaced by the contents of `{diff_file}` (not a path-only pointer) — that session may not share this filesystem, so its prompt must be self-contained. Then HALT. Ask the user to run each in a separate session (ideally a different LLM) and paste back the findings. When findings are pasted, treat them as those layers' findings and resume from this point. This is the only allowed parent-side read of a reviewer instruction file.
 
 4. **Layer failure handling**: If any layer fails, times out, or returns empty results, append the layer's `name` to `{failed_layers}` (comma-separated) and proceed with findings from the remaining layers.
 

package/src/bmm-skills/ship/bmad-correct-course/SKILL.md

@@ -182,8 +182,12 @@ Activation is complete. If `activation_steps_prepend` or `activation_steps_appen
 
 <check if="mode is Incremental">
   <action>Present each edit proposal individually</action>
-  <ask>Review and refine this change? Options: Approve [a], Edit [e], Skip [s]</ask>
-  <action>Iterate on each proposal based on user feedback</action>
+  <action>HALT and give the user a choice:
+  - **Approve** — accept this proposal
+  - **Edit** — refine this proposal
+  - **Skip** — drop this proposal
+  </action>
+  <action>If the user chooses **Approve**, keep the proposal. If they choose **Edit**, refine it with them. If they choose **Skip**, drop it. Continue to the next proposal.</action>
 </check>
 
 <action if="mode is Batch">Collect all edit proposals and present together at end of step</action>
@@ -232,7 +236,11 @@ Activation is complete. If `activation_steps_prepend` or `activation_steps_appen
 
 <action>Present complete Sprint Change Proposal to user</action>
 <action>Write Sprint Change Proposal document to {default_output_file}</action>
-<ask>Review complete proposal. Continue [c] or Edit [e]?</ask>
+<action>HALT and give the user a choice:
+- **Continue** — proceed to approval
+- **Edit** — revise the proposal first
+</action>
+<action>If the user chooses **Edit**, revise the proposal with them and write the updated document before continuing.</action>
 </step>
 
 <step n="5" goal="Finalize and Route for Implementation">

package/src/bmm-skills/ship/bmad-correct-course/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 6 (Workflow Completion),
 # after the Sprint Change Proposal is finalized and handoff is confirmed. Override wins.

package/src/bmm-skills/ship/bmad-qa-generate-e2e-tests/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 5 (Create Summary),
 # after all tests pass and the summary document is saved. Override wins.

package/src/bmm-skills/ship/bmad-retrospective/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 at the end of Phase 5 (Close), after the retrospective
 # document is saved and sprint-status is updated. Override wins.

package/src/bmm-skills/v6-shims/bmad-create-architecture/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: bmad-create-architecture
 description: 'Deprecated — forwards to bmad-architecture (create intent)'
+metadata:
+  lifecycle: shim
 ---
 
 # DEPRECATED — forwards to bmad-architecture (create intent)

package/src/bmm-skills/v6-shims/bmad-create-architecture/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 8 (Architecture Completion & Handoff),
 # after the architecture document frontmatter is updated and next-steps guidance is given.

package/src/bmm-skills/v6-shims/bmad-create-prd/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: bmad-create-prd
 description: 'Deprecated — forwards to bmad-prd (create intent)'
+metadata:
+  lifecycle: shim
 ---
 
 # DEPRECATED — forwards to bmad-prd (create intent)

package/src/bmm-skills/v6-shims/bmad-create-prd/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 12 (Workflow Completion),
 # after the PRD is finalized and workflow status is updated. Override wins.

package/src/bmm-skills/v6-shims/bmad-create-story/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: bmad-create-story
 description: "Deprecated: `bmad-build` is now the official implementation method. Only use this when explicitly invoked by name"
+metadata:
+  lifecycle: shim
 ---
 
 # Create Story Workflow
@@ -255,7 +257,7 @@ Activation is complete. If `activation_steps_prepend` or `activation_steps_appen
 
   <!-- Load all available content through discovery protocol -->
   <action>Read fully and follow `./discover-inputs.md` to load all input files</action>
-  <note>Available content: {epics_content}, {prd_content}, {architecture_content}, {ux_content}, plus the project-context facts loaded during activation via `persistent_facts`.</note>
+  <note>Available content: {epics_content}, {prd_content}, {architecture_content}, {ux_content}, plus any facts loaded during activation via `persistent_facts` (empty unless the user opted in).</note>
 
   <!-- Analyze epics file for story foundation -->
   <action>From {epics_content}, extract Epic {{epic_num}} complete context:</action> **EPIC ANALYSIS:** - Epic

package/src/bmm-skills/v6-shims/bmad-create-story/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 6 (Update sprint status and finalize),
 # after the story file is saved and sprint-status.yaml is updated. Override wins.

package/src/bmm-skills/v6-shims/bmad-dev-auto/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: bmad-dev-auto
 description: "Deprecated: forwards to bmad-build-auto. Do not use unless invoked by name"
+metadata:
+  lifecycle: shim
 ---
 
 # Deprecated Build Auto Alias

package/src/bmm-skills/v6-shims/bmad-dev-story/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: bmad-dev-story
 description: "Deprecated: `bmad-build` is now the official implementation method. Only use this when explicitly invoked by name"
+metadata:
+  lifecycle: shim
 ---
 
 # Dev Story Workflow

package/src/bmm-skills/v6-shims/bmad-dev-story/customize.toml

@@ -30,12 +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",
-  "Never add epic or story references as inline code comments (e.g. # Epic: X, # Story: PROJ-42).",
-  "Code comments explain why, not what — no AI workflow metadata, planning refs, or story tracking in source code.",
-  "Generated code must be production-ready: clean, minimal, and free of AI-generated noise.",
-]
+persistent_facts = []
 
 # Scalar: executed when the workflow reaches its final step,
 # after the story implementation is complete and status is updated. Override wins.

package/src/bmm-skills/v6-shims/bmad-document-project/SKILL.md

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

package/src/bmm-skills/v6-shims/bmad-domain-research/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: bmad-domain-research
 description: 'Deprecated — forwards to bmad-deep-recon (domain type)'
+metadata:
+  lifecycle: shim
 ---
 
 # DEPRECATED — forwards to bmad-deep-recon (domain type)

package/src/bmm-skills/v6-shims/bmad-edit-prd/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: bmad-edit-prd
 description: 'Deprecated — forwards to bmad-prd (update intent)'
+metadata:
+  lifecycle: shim
 ---
 
 # DEPRECATED — forwards to bmad-prd (update intent)

package/src/bmm-skills/v6-shims/bmad-edit-prd/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 E-4 (Complete & Validate) and the
 # user exits via [S] Summary or [X] Exit — not on [V] Validate (which chains to

package/src/bmm-skills/v6-shims/bmad-market-research/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: bmad-market-research
 description: 'Deprecated — forwards to bmad-deep-recon (market type)'
+metadata:
+  lifecycle: shim
 ---
 
 # DEPRECATED — forwards to bmad-deep-recon (market type)

package/src/bmm-skills/v6-shims/bmad-quick-dev/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: bmad-quick-dev
 description: "Deprecated: forwards to bmad-build. Do not use unless invoked by name"
+metadata:
+  lifecycle: shim
 ---
 
 # Deprecated Build Alias

package/src/bmm-skills/v6-shims/bmad-sprint-status/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: bmad-sprint-status
 description: 'Deprecated — forwards to bmad-sprint-planning (status view)'
+metadata:
+  lifecycle: shim
 ---
 
 # DEPRECATED — forwards to bmad-sprint-planning (status view)

package/src/bmm-skills/v6-shims/bmad-sprint-status/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 final step,
 # after sprint status is summarized and risks are surfaced. Override wins.

package/src/bmm-skills/v6-shims/bmad-technical-research/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: bmad-technical-research
 description: 'Deprecated — forwards to bmad-deep-recon (technical type)'
+metadata:
+  lifecycle: shim
 ---
 
 # DEPRECATED — forwards to bmad-deep-recon (technical type)

package/src/bmm-skills/v6-shims/bmad-validate-prd/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: bmad-validate-prd
 description: 'Deprecated — forwards to bmad-prd (validate intent)'
+metadata:
+  lifecycle: shim
 ---
 
 # DEPRECATED — forwards to bmad-prd (validate intent)

package/src/bmm-skills/v6-shims/bmad-validate-prd/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 13 (Validation Report Complete) and
 # the user exits via [X] Exit — not on [E] Use Edit Workflow (which chains to

package/src/core-skills/bmad-advanced-elicitation/SKILL.md

@@ -19,7 +19,7 @@ You are BMad's shared refinement checkpoint: other skills invoke you at natural
 
 ## Serving the Catalog
 
-`scripts/pick_methods.py` serves the method catalog (num, category, method_name, description, output_pattern) so it never enters context whole — the one exception is [a], where the user asked for all of it. Invoke as:
+`scripts/pick_methods.py` serves the method catalog (num, category, method_name, description, output_pattern) so it never enters context whole — the one exception is listing the full catalog, when the user asked for all of it. Invoke as:
 
 ```bash
 uv run {skill-root}/scripts/pick_methods.py --file {workflow.methods_file} <command>
@@ -28,7 +28,7 @@ uv run {skill-root}/scripts/pick_methods.py --file {workflow.methods_file} <comm
 If `{workflow.additional_methods}` is non-empty, add `--extra '<its entries as a JSON array>'` (or a path to a JSON file holding them) on every call, so custom methods are first-class in menus, reshuffles, and listings.
 
 - `categories` — category names + counts, the cheap map.
-- `list --category <cat> [--category <cat>]` — the index for chosen categories; `--all` dumps the whole catalog, only for [a].
+- `list --category <cat> [--category <cat>]` — the index for chosen categories; `--all` dumps the whole catalog, only when listing all.
 - `show <name-or-num> [...]` — full rows by name or num.
 - `random -n 5 --spread [--exclude <name>]...` — a category-diverse random draw.
 
@@ -36,30 +36,29 @@ If `{workflow.additional_methods}` is non-empty, add `--extra '<its entries as a
 
 ## The Menu
 
-```
-**Advanced Elicitation Options**
-Choose a number (1-5), [r] to Reshuffle, [a] List All, or [x] to Proceed:
-
-1. [Method Name]
-2. [Method Name]
-3. [Method Name]
-4. [Method Name]
-5. [Method Name]
-r. Reshuffle the list with 5 new options
-a. List all methods with descriptions
-x. Proceed / No Further Actions
-```
+HALT and give the user a choice:
+
+- The five offered methods, listed by name. The user may pick one or several.
+- **Reshuffle** — replace the list with five new options.
+- **List all** — show the full catalog with descriptions.
+- **Proceed** — no further elicitation.
 
-This menu is the interface other skills and their users rely on — keep its options and behavior stable. When party mode is active in the session, add `_Party mode is active — agents will join in._` under the heading. Handle the response:
+This menu is the interface other skills and their users rely on — keep its options and behavior stable. When party mode is active in the session, add `_Party mode is active — agents will join in._` under the heading.
 
-- **1–5** — run that method (several numbers: in sequence), then re-present the menu.
-- **r** — reshuffle as above and re-present.
-- **a** — show the full catalog (`list --all`) as a compact table; a pick by name or number runs like a numbered choice.
-- **x** — done. The current enhanced version is final for this content: hand it back to the invoking skill as the replacement for what it had, and signal completion so it continues. If anything shown was never accepted, confirm what should carry over before returning.
-- **Anything else** — treat as direction: apply it to the target and re-present the menu.
+- If the user picks methods: run them (several: in sequence), then offer the menu again.
+- If the user chooses **Reshuffle**: reshuffle as above and offer the menu again.
+- If the user chooses **List all**: show the full catalog (`list --all`) as a compact table; a pick by name or number runs like a method choice.
+- If the user chooses **Proceed**: done. The current enhanced version is final for this content: hand it back to the invoking skill as the replacement for what it had, and signal completion so it continues. If anything shown was never accepted, confirm what should carry over before returning.
+- Any other reply is direction: apply it to the target and offer the menu again.
 
 ## Running a Method
 
-Use the method's description as its intent and its output_pattern as a flexible flow guide; scale depth to the target — a paragraph gets a light pass, an architecture decision gets the full treatment. Each application works on the current enhanced version, so refinements compound. Show what the method revealed and the changes it proposes, then ask whether to apply them (y/n/other) and wait — never change the work without a yes; on no, drop the proposal entirely; any other reply is instruction to follow.
+Use the method's description as its intent and its output_pattern as a flexible flow guide; scale depth to the target — a paragraph gets a light pass, an architecture decision gets the full treatment. Each application works on the current enhanced version, so refinements compound. Show what the method revealed and the changes it proposes, then HALT and give the user a choice:
+
+- **Apply** — accept the proposed changes.
+- **Reject** — drop the proposal entirely.
+- Or give different direction.
+
+Never change the work unless the user accepts the proposal. If they reject it, drop the proposal entirely. Any other reply is instruction to follow.
 
 When a method casts personas (round tables, panels, debates), reuse party members already in the session if party mode is active; otherwise resolve installed agents on demand via `uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root} --key agents` (a four-layer merge of `_bmad/config.toml`, `config.user.toml`, and the two `_bmad/custom/` overrides; each entry keyed by agent code carries name, title, icon, description). If neither yields a fit, invent named viewpoints suited to the content.

package/src/core-skills/bmad-brainstorming/customize.toml

@@ -22,12 +22,11 @@ activation_steps_append = []
 # Persistent facts the facilitator keeps in mind for the whole session
 # (domain constraints, house rules, stylistic guardrails). Each entry is 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, giving the facilitator
-# persistent awareness of the project's domain without re-asking.
-persistent_facts = [
-  "file:{project-root}/**/project-context.md",
-]
+# path/glob whose contents are loaded as facts. Empty by default — repo-wide context
+# belongs in AGENTS.md (see bmad-project-context), which every skill already sees. Use
+# this for context only the facilitator needs, loaded on demand rather than carried as
+# constant memory (e.g. `file:{project-root}/**/project-context.md` if you keep one).
+persistent_facts = []
 
 # The technique library loaded on demand during the session. Swap the path in
 # team/user TOML to ship a different or extended catalog of creative methods.

package/src/core-skills/bmad-forge-idea/customize.toml

@@ -20,12 +20,11 @@ activation_steps_append = []
 # Persistent facts the interrogator keeps in mind for the whole session
 # (domain constraints, house rules, what's off the table). Each entry is 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
-# when one exists (e.g. from bmad-generate-project-context), so the forge grounds
-# in the project's tech, domain, and constraints without re-asking.
-persistent_facts = [
-  "file:{project-root}/**/project-context.md",
-]
+# path/glob whose contents are loaded as facts. Empty by default — repo-wide context
+# belongs in AGENTS.md (see bmad-project-context), which every skill already sees. Use
+# this for context only the forge needs, loaded on demand rather than carried as constant
+# memory (e.g. `file:{project-root}/**/project-context.md` if you keep one).
+persistent_facts = []
 
 # Executed when the session completes. Scalar or array of instructions. Empty for none.
 on_complete = []

package/src/core-skills/bmad-party-mode/customize.toml

@@ -22,10 +22,10 @@ activation_steps_append = []
 # Persistent facts the orchestrator keeps in mind for the whole session
 # (house rules, running gags, topics to avoid). Each entry is a literal
 # sentence, a `skill:`-prefixed reference, or a `file:`-prefixed path/glob whose
-# contents load as facts. Default picks up project-context.md if one exists.
-persistent_facts = [
-  "file:{project-root}/**/project-context.md",
-]
+# contents load as facts. Empty by default — repo-wide context belongs in AGENTS.md
+# (see bmad-project-context), which every skill already sees. Use this for context only
+# the party needs, loaded on demand rather than carried as constant memory.
+persistent_facts = []
 
 # Which party loads when the user just says "party mode" with no override.
 # Empty = the installed BMAD agents — exactly the default behavior of a plain