bmad-method 6.9.1-next.0 → 6.9.1-next.10

package/.claude-plugin/marketplace.json

@@ -63,7 +63,6 @@
         "./src/bmm-skills/3-solutioning/bmad-create-epics-and-stories",
         "./src/bmm-skills/3-solutioning/bmad-generate-project-context",
         "./src/bmm-skills/4-implementation/bmad-agent-dev",
-        "./src/bmm-skills/4-implementation/bmad-investigate",
         "./src/bmm-skills/4-implementation/bmad-dev-story",
         "./src/bmm-skills/4-implementation/bmad-quick-dev",
         "./src/bmm-skills/4-implementation/bmad-checkpoint-preview",

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method",
-  "version": "6.9.1-next.0",
+  "version": "6.9.1-next.10",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",
@@ -42,10 +42,11 @@
     "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:install && npm run test:urls && 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:channels && 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:channels && 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:refs": "node test/test-file-refs-csv.js",
+    "test:skills": "node test/test-validate-skills.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"

package/removals.txt

@@ -60,3 +60,6 @@ bmad-distillator
 # bmad-create-ux-design: renamed to bmad-ux (spine-based skill with separate
 # DESIGN.md and EXPERIENCE.md outputs).
 bmad-create-ux-design
+# bmad-investigate: retired. Plain investigation reaches the same conclusions at
+# lower cost.
+bmad-investigate

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

@@ -88,8 +88,3 @@ skill = "bmad-create-story"
 code = "ER"
 description = "Party mode review of all work completed across an epic"
 skill = "bmad-retrospective"
-
-[[agent.menu]]
-code = "IN"
-description = "Forensic case investigation with evidence-graded findings, calibrated to the input"
-skill = "bmad-investigate"

package/src/bmm-skills/4-implementation/bmad-code-review/SKILL.md

@@ -50,7 +50,6 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
 - `date` as system-generated current datetime
 - `sprint_status` = `{implementation_artifacts}/sprint-status.yaml`
 - `project_context` = `**/project-context.md` (load if exists)
-- CLAUDE.md / memory files (load if exist)
 - YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
 
 ### Step 5: Greet the User

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

@@ -18,9 +18,9 @@ failed_layers: '' # set at runtime: comma-separated list of layers that failed o
 
 2. Launch parallel subagents without conversation context. If subagents are not available, generate prompt files in `{implementation_artifacts}` — one per reviewer role below — and HALT. Ask the user to run each in a separate session (ideally a different LLM) and paste back the findings. When findings are pasted, resume from this point and proceed to step 3.
 
-   - **Blind Hunter** — receives inline `{diff_output}` only. No spec, no context docs, no project access. Invoke via the `bmad-review-adversarial-general` skill.
+   - **Blind Hunter** — prompt: "Use the `bmad-review-adversarial-general` skill on `{diff_output}`."
 
-   - **Edge Case Hunter** — receives `{diff_output}` and read access to the project. Invoke via the `bmad-review-edge-case-hunter` skill.
+   - **Edge Case Hunter** — prompt: "Use the `bmad-review-edge-case-hunter` skill on `{diff_output}`."
 
    - **Acceptance Auditor** (only if `{review_mode}` = `"full"`) — receives `{diff_output}`, the content of the file at `{spec_file}`, and any loaded context docs. Its prompt:
      > You are an Acceptance Auditor. Review this diff against the spec and context docs. Check for: violations of acceptance criteria, deviations from spec intent, missing implementation of specified behavior, contradictions between spec constraints and actual code. Output findings as a Markdown list. Each finding: one-line title, which AC/constraint it violates, and evidence from the diff.

package/src/bmm-skills/4-implementation/bmad-code-review/steps/step-03-triage.md

@@ -29,7 +29,13 @@
    - Append any unique detail, reasoning, or location references from the other finding(s) into the surviving `detail` field.
    - Set `source` to the merged sources (e.g., `blind+edge`).
 
-3. **Classify** each finding into exactly one bucket:
+3. **Assign severity** to each finding by consequence for the artifact's main consumer (software user, document reader, etc).
+   Disregard any severity assigned by a reviewing subagent. Review subagents operate under by-design information asymmetry and do not have enough context to set final severity for this workflow.
+   - `low` -- none or cosmetic
+   - `medium` -- tolerable
+   - `high` -- intolerable
+
+4. **Route** each finding into exactly one triage bucket:
    - **decision_needed** -- There is an ambiguous choice that requires human input. The code cannot be correctly patched without knowing the user's intent. Only possible if `{review_mode}` = `"full"`.
    - **patch** -- Code issue that is fixable without human input. The correct fix is unambiguous.
    - **defer** -- Pre-existing issue not caused by the current change. Real but not actionable now.
@@ -37,11 +43,11 @@
 
    If `{review_mode}` = `"no-spec"` and a finding would otherwise be `decision_needed`, reclassify it as `patch` (if the fix is unambiguous) or `defer` (if not).
 
-4. **Drop** all `dismiss` findings. Record the dismiss count for the summary.
+5. **Drop** all `dismiss` findings. Record the dismiss count for the summary.
 
-5. If `{failed_layers}` is non-empty, report which layers failed before announcing results. If zero findings remain after dropping dismissed AND `{failed_layers}` is non-empty, warn the user that the review may be incomplete rather than announcing a clean review.
+6. If `{failed_layers}` is non-empty, report which layers failed before announcing results. If zero findings remain after dropping dismissed AND `{failed_layers}` is non-empty, warn the user that the review may be incomplete rather than announcing a clean review.
 
-6. If zero findings remain after triage (all rejected or none raised): state "✅ Clean review — all layers passed." (Step 3 already warned if any review layers failed via `{failed_layers}`.)
+7. If zero findings remain after triage (all rejected or none raised): state "✅ Clean review — all layers passed." (Step 3 already warned if any review layers failed via `{failed_layers}`.)
 
 
 ## NEXT

package/src/bmm-skills/4-implementation/bmad-code-review/steps/step-04-present.md

@@ -86,7 +86,7 @@ Skip this section if `{spec_file}` is not set.
 
 #### Determine new status based on review outcome
 
-- If all `decision-needed` and `patch` findings were resolved (fixed or dismissed) AND no unresolved HIGH/MEDIUM issues remain: set `{new_status}` = `done`. Update the story file Status section to `done`.
+- If all `decision-needed` and `patch` findings were resolved (fixed or dismissed) AND no unresolved `high`/`medium` findings remain: set `{new_status}` = `done`. Update the story file Status section to `done`.
 - If `patch` findings were left as action items, or unresolved issues remain: set `{new_status}` = `in-progress`. Update the story file Status section to `in-progress`.
 
 Save the story file.

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

@@ -81,7 +81,6 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
 - `communication_language`, `document_output_language`, `user_skill_level`
 - `date` as system-generated current datetime
 - `project_context` = `**/project-context.md` (load if exists)
-- CLAUDE.md / memory files (load if exist)
 - YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
 - Language MUST be tailored to `{user_skill_level}`
 - Generate all documents in `{document_output_language}`

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

@@ -4,6 +4,7 @@ type: 'feature' # feature | bugfix | refactor | chore
 created: '{date}'
 status: 'draft' # draft | ready-for-dev | in-progress | in-review | done | blocked
 review_loop_iteration: 0 # incremented by step-04 before each review loopback
+followup_review_recommended: false # set by step-04 on status: done from the final review pass significance judgment
 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.
 warnings: [] # optional: machine-readable warnings for orchestration, e.g. oversized, multiple-goals
 ---
@@ -71,6 +72,13 @@ warnings: [] # optional: machine-readable warnings for orchestration, e.g. overs
      the amendment avoids, and any KEEP instructions (what worked well and must survive re-derivation).
      Empty until the first bad_spec loopback. -->
 
+## Review Triage Log
+
+<!-- Append-only. Populated by step-04 on EVERY review pass, including loopbacks and blocked exits.
+     Each entry records triage decision counts for intent_gap, bad_spec, patch, defer, and reject,
+     with per-category severity breakdowns using low/medium/high, plus the findings addressed in
+     that pass. Empty until the first review pass. -->
+
 ## Design Notes
 
 <!-- If the approach is straightforward, DELETE THIS ENTIRE SECTION. Do not write "N/A" or "None". -->

package/src/bmm-skills/4-implementation/bmad-dev-auto/step-01-clarify-and-route.md

@@ -20,7 +20,7 @@ If the invocation prompt explicitly points to an existing spec file with recogni
 - `ready-for-dev` or `in-progress` → `./step-03-implement.md`
 - `in-review` → `./step-04-review.md`
 - `blocked` → HALT with status `blocked` and blocking condition `blocked spec supplied`.
-- `done` → ingest as context and proceed to INSTRUCTIONS — do not resume.
+- `done` → set `review_loop_iteration` to `0` in the frontmatter, then **EARLY EXIT** to `./step-04-review.md` for a fresh review pass. (A `done` spec is a completed run, so this starts a follow-up review, not a resumption.)
 
 Otherwise, treat the invocation prompt as starting intent. This may be a story ID, ticket ID, file path, short description, or longer free-form intent. Do not infer workflow state from non-spec files.
 If the invocation prompt does not contain enough intent to identify what to implement, HALT with status `blocked` and blocking condition `unclear intent`.

package/src/bmm-skills/4-implementation/bmad-dev-auto/step-04-review.md

@@ -25,22 +25,44 @@ Do NOT `git add` anything — this is read-only inspection.
 
 Launch two subagents without prior session context.
 
-- **Blind hunter** — receives inline `{diff_output}` only. No spec, no context docs, no project access. Invoke via the `bmad-review-adversarial-general` skill.
-- **Edge case hunter** — receives `{diff_output}` and read access to the project. Invoke via the `bmad-review-edge-case-hunter` skill.
+- **Blind hunter** — prompt: "Use the `bmad-review-adversarial-general` skill on `{diff_output}`."
+- **Edge case hunter** — prompt: "Use the `bmad-review-edge-case-hunter` skill on `{diff_output}`."
 
 ### Classify
 
 1. Deduplicate all review findings.
-2. Classify each finding. The first three categories are **this story's problem** — caused or exposed by the current change. The last two are **not this story's problem**.
+2. Assign severity to each finding by consequence for the artifact's main consumer (software user, document reader, etc).
+   Disregard any severity assigned by a reviewing subagent. Review subagents operate under by-design information asymmetry and do not have enough context to set final severity for this workflow.
+   - `low`: none or cosmetic
+   - `medium`: tolerable
+   - `high`: intolerable
+3. Route each finding into exactly one triage category. The first three categories are **this story's problem** — caused or exposed by the current change. The last two are **not this story's problem**.
    - **intent_gap** — caused by the change; cannot be resolved from the spec because the captured intent is incomplete. Do not infer intent unless there is exactly one possible reading.
    - **bad_spec** — caused by the change, including direct deviations from spec. The spec should have been clear enough to prevent it. When in doubt between bad_spec and patch, prefer bad_spec — a spec-level fix is more likely to produce coherent code.
    - **patch** — caused by the change; trivially fixable without human input. Just part of the diff.
    - **defer** — pre-existing issue not caused by this story, surfaced incidentally by the review. Collect for later focused attention.
    - **reject** — noise. Drop silently. When unsure between defer and reject, prefer reject — only defer findings you are confident are real.
-3. Process findings in cascading order. If intent_gap exists, lower findings are moot; follow the intent_gap branch below. If bad_spec exists, lower findings are moot since code will be re-derived. If neither exists, process patch and defer normally. Before each bad_spec loopback, read `{spec_file}` frontmatter `review_loop_iteration` (missing means `0`), increment it by 1, and write it back. If it exceeds 5, HALT with status `blocked` and blocking condition `review repair loop exceeded 5 iterations`.
-   - **intent_gap** — Root cause is inside `<intent-contract>`. Revert code changes. HALT with status `blocked`, blocking condition `intent gap in intent contract`, and include the intent-gap findings.
-   - **bad_spec** — Root cause is outside `<intent-contract>`. Do not modify content inside `<intent-contract>`. Before reverting code: extract KEEP instructions for positive preservation (what worked well and must survive re-derivation). Revert code changes. Read the `## Spec Change Log` in `{spec_file}` and strictly respect all logged constraints when amending the sections outside `<intent-contract>` that contain the root cause. Append a new change-log entry recording: the triggering finding, what was amended, the known-bad state avoided, and the KEEP instructions. Read fully and follow `./step-03-implement.md` to re-derive the code, then this step will run again.
-   - **patch** — Auto-fix. These are the only findings that survive loopbacks.
+4. Append a new entry to the `## Review Triage Log` section in `{spec_file}`, in this format:
+   ```markdown
+   ### {date} — Review pass
+   - intent_gap: count
+   - bad_spec: count
+   - patch: count
+   - defer: count
+   - reject: count
+   - addressed_findings:
+     - `[high|medium|low]` `[patch|bad_spec]` <finding summary and action taken in this pass>
+   ```
+   Where `count` is either just `0`, or total with breakdown by severity `N: (high Nhigh, medium Nmedium, low Nlow)`.
+   If no patch was fixed and no bad_spec repair loopback was triggered in this pass, write:
+   ```markdown
+   - addressed_findings:
+     - none
+   ```
+5. Process findings in cascading order. If intent_gap exists, lower findings are moot; follow the intent_gap branch below. If bad_spec exists, lower findings are moot since code will be re-derived. If neither exists, process patch and defer normally. Before each bad_spec loopback, read `{spec_file}` frontmatter `review_loop_iteration` (missing means `0`), increment it by 1, and write it back. If it exceeds 5, append the triage-log entry for this pass with `addressed_findings: none`, then HALT with status `blocked` and blocking condition `review repair loop exceeded 5 iterations (non-convergence)`.
+   - **intent_gap** — Root cause is inside `<intent-contract>`. Revert code changes. Append the triage-log entry for this pass with `addressed_findings: none`, then HALT with status `blocked`, blocking condition `intent gap in intent contract`, and include the intent-gap findings.
+   - **bad_spec** — Root cause is outside `<intent-contract>`. Do not modify content inside `<intent-contract>`. Before reverting code: extract KEEP instructions for positive preservation (what worked well and must survive re-derivation). Revert code changes. Read the `## Spec Change Log` in `{spec_file}` and strictly respect all logged constraints when amending the sections outside `<intent-contract>` that contain the root cause. Append a new change-log entry recording: the triggering finding, what was amended, the known-bad state avoided, and the KEEP instructions. Append the triage-log entry for this pass, listing every bad_spec finding that triggered the spec amendment and implementation loopback under `addressed_findings`. Read fully and follow `./step-03-implement.md` to re-derive the code, then this step will run again.
+   - **patch** — Auto-fix. These are the only findings that survive loopbacks. After auto-fixing, append the triage-log entry for this pass, listing every patch fixed in this pass under `addressed_findings`.
    - **defer** — Append one new entry to `{deferred_work_file}` using this format. Do not modify existing entries or look for duplicates.
      ```markdown
      - source_spec: `{spec_file}`
@@ -55,7 +77,14 @@ Prepare `Auto Run Result` details:
 - Summary of implemented change
 - Files changed with one-line descriptions
 - Review findings breakdown: patches applied, items deferred, items rejected
+- Follow-up review recommendation: `true` when the final review pass made review-driven changes significant enough to benefit from an independent follow-up review; otherwise `false`. Use judgment, not a fixed numeric threshold. Base the judgment on the final pass's triage log and fixes, including patched-finding volume, consequence/severity, breadth, behavior/API/security/data impact, and implementation complexity. Many low-severity patched findings can be significant by volume. Do not recommend follow-up for only a few localized low-consequence fixes.
 - Verification performed, including command outcomes or manual inspection notes
 - Any residual risks
 
+Set `{spec_file}` frontmatter `followup_review_recommended` from the judgment above.
+
+If version control is available, commit. Do not push.
+
+Capture `final_revision` (current HEAD after committing, or `NO_VCS` if version control is unavailable) into `{spec_file}` frontmatter.
+
 HALT with status `done`.

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

@@ -20,6 +20,8 @@ A specification is "Ready for Development" when:
 - **Logical**: Tasks ordered by dependency.
 - **Testable**: All ACs use Given/When/Then.
 - **Complete**: No placeholders or TBDs.
+- **Sufficient**: No known requirement, acceptance, dependency, or implementation gaps remain unresolved.
+- **Coherent**: No unresolved ambiguities or internal contradictions.
 
 ## SCOPE STANDARD
 
@@ -69,7 +71,6 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
 - `date` as system-generated current datetime
 - `sprint_status` = `{implementation_artifacts}/sprint-status.yaml`
 - `project_context` = `**/project-context.md` (load if exists)
-- CLAUDE.md / memory files (load if exist)
 - YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
 - Language MUST be tailored to `{user_skill_level}`
 - Generate all documents in `{document_output_language}`

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

@@ -1,41 +1,33 @@
 # DO NOT EDIT -- overwritten on every update.
 #
-# Workflow customization surface for bmad-quick-dev. Mirrors the
-# agent customization shape under the [workflow] namespace.
+# Default customization values for bmad-quick-dev.
+# Override in _bmad/custom/bmad-quick-dev.toml or
+# _bmad/custom/bmad-quick-dev.user.toml.
+#
+# Merge rules:
+# - Strings replace the default.
+# - Lists append to the default list.
+# - Tables merge key by key.
 
 [workflow]
 
-# --- Configurable below. Overrides merge per BMad structural rules: ---
-#   scalars: override wins • arrays (persistent_facts, activation_steps_*): append
-#   arrays-of-tables with `code`/`id`: replace matching items, append new ones.
-
-# Steps to run before the standard activation (config load, greet).
-# Overrides append. Use for pre-flight loads, compliance checks, etc.
+# Extra instructions to run before config is loaded and before the user is greeted.
 
 activation_steps_prepend = []
 
-# Steps to run after greet but before the workflow begins.
-# Overrides append. Use for context-heavy setup that should happen
-# once the user has been acknowledged.
+# Extra instructions to run after the greeting and before step 01.
 
 activation_steps_append = []
 
-# Persistent facts the workflow keeps in mind for the whole run
-# (standards, compliance constraints, stylistic guardrails).
-# Distinct from the runtime memory sidecar — these are static context
-# loaded on activation. Overrides append.
-#
-# Each entry is either:
-#   - a literal sentence, e.g. "All stories must include testable acceptance criteria."
-#   - 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).
+# Facts kept in context for the whole run.
+# Entries are literal text or file references prefixed with "file:".
+# File entries may use globs and are loaded during activation.
 
 persistent_facts = [
   "file:{project-root}/**/project-context.md",
 ]
 
-# Scalar: executed when the workflow reaches its final step,
-# after implementation is complete and explanations are provided. Override wins.
-# Leave empty for no custom post-completion behavior.
+# Instruction run after Quick Dev completes.
+# Empty means no extra completion behavior.
 
 on_complete = ""

package/src/bmm-skills/4-implementation/bmad-quick-dev/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
+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.
 ---
 

package/src/bmm-skills/4-implementation/bmad-quick-dev/step-01-clarify-and-route.md

@@ -59,8 +59,8 @@ If the spec is an epic story and `{sprint_status}` exists: find the `development
         - **If missing, empty, or invalid:** continue to step 3.
 
      3. **Compile epic context.** Produce `{implementation_artifacts}/epic-<N>-context.md` by following `./compile-epic-context.md`, in order of preference:
-        - **Preferred — sub-agent:** spawn a sub-agent with `./compile-epic-context.md` as its prompt. Pass it the epic number, the epics file path, the `{planning_artifacts}` directory, and the output path `{implementation_artifacts}/epic-<N>-context.md`.
-        - **Fallback — inline** (for runtimes without sub-agent support, e.g. Copilot, Codex, local Ollama, older Claude): if your runtime cannot spawn sub-agents, or the spawn fails/times out, read `./compile-epic-context.md` yourself and follow its instructions to produce the same output file.
+        - **Preferred — subagent:** spawn a subagent with `./compile-epic-context.md` as its prompt. Pass it the epic number, the epics file path, the `{planning_artifacts}` directory, and the output path `{implementation_artifacts}/epic-<N>-context.md`.
+        - **Fallback — inline** (for runtimes without subagent support, e.g. Copilot, Codex, local Ollama, older Claude): if your runtime cannot spawn subagents, or the spawn fails/times out, read `./compile-epic-context.md` yourself and follow its instructions to produce the same output file.
 
      4. **Verify.** After compilation, verify the output file exists, is non-empty, and starts with `# Epic <N> Context:`. If valid, load it. If verification fails, HALT and report the failure.
 
@@ -82,7 +82,12 @@ If the spec is an epic story and `{sprint_status}` exists: find the `development
    - Present detected distinct goals as a bullet list.
    - Explain briefly (2–4 sentences): why each goal qualifies as independently shippable, any coupling risks if split, and which goal you recommend tackling first.
    - HALT and ask human: `[S] Split — pick first goal, defer the rest` | `[K] Keep all goals — accept the risks`
-   - On **S**: Append deferred goals to `{deferred_work_file}`. Narrow scope to the first-mentioned goal. Continue routing.
+   - On **S**: For each deferred goal, append one new entry to `{deferred_work_file}` using this format. Do not modify existing entries or look for duplicates. Narrow scope to the first-mentioned goal. Continue routing.
+     ```markdown
+     - source_spec: none
+       summary: <one sentence naming the deferred goal>
+       evidence: <why this was split from the current intent>
+     ```
    - On **K**: Proceed as-is.
 5. Route — choose exactly one:
 

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

@@ -12,14 +12,19 @@ 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 `<frozen-after-approval>...</frozen-after-approval>` block as `preserved_intent`. Otherwise `preserved_intent` is empty.
-2. Investigate codebase. _Isolate deep exploration in sub-agents/tasks where available. To prevent context snowballing, instruct subagents to give you distilled summaries only._
+2. Investigate codebase. _Isolate deep exploration in 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. If `{preserved_intent}` is non-empty, substitute it for the `<frozen-after-approval>` 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, 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 ask human: `[S] Split — carve off secondary goals` | `[K] Keep full spec — accept the risks`
-   - On **S**: Propose the split — name each secondary goal. Append deferred goals to `{deferred_work_file}`. 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.
+   - On **S**: Propose the split — name each secondary goal. For each deferred goal, append one new entry to `{deferred_work_file}` 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>
+     ```
    - On **K**: Continue to checkpoint with full spec.
 
 ### CHECKPOINT 1

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

@@ -26,15 +26,15 @@ 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 sub-agent, include them in the sub-agent prompt so it has access to the referenced context.
+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.
 
-Hand `{spec_file}` to a sub-agent/task and let it implement. If no sub-agents are available, implement directly.
+Hand `{spec_file}` to a subagent/task and let it implement. If no subagents are available, implement directly.
 
 **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.
 
-### Self-Check
+### Tasks & Acceptance Verification
 
-Before leaving this step, verify every task in the `## Tasks & Acceptance` section of `{spec_file}` is complete. Mark each finished task `[x]`. If any task is not done, finish it before proceeding.
+Before leaving this step, verify every task in the `## Tasks & Acceptance` section of `{spec_file}` is complete and every acceptance criterion is satisfied. Mark each finished task `[x]`. If any task is not done or any acceptance criterion is not satisfied, finish the missing work before proceeding.
 
 ## NEXT
 

package/src/bmm-skills/4-implementation/bmad-quick-dev/step-04-review.md

@@ -1,6 +1,5 @@
 ---
 deferred_work_file: '{implementation_artifacts}/deferred-work.md'
-specLoopIteration: 1
 ---
 
 # Step 4: Review
@@ -23,26 +22,35 @@ Do NOT `git add` anything — this is read-only inspection.
 
 ### Review
 
-Launch three subagents without conversation context. If no sub-agents are available, generate three review prompt files in `{implementation_artifacts}` — one per reviewer role below — and HALT. Ask the human to run each in a separate session (ideally a different LLM) and paste back the findings.
+Launch two subagents without conversation context. If no subagents are available, generate two review prompt files in `{implementation_artifacts}` — one per reviewer role below — and HALT. Ask the human to run each in a separate session (ideally a different LLM) and paste back the findings.
 
-- **Blind hunter** — receives inline `{diff_output}` only. No spec, no context docs, no project access. Invoke via the `bmad-review-adversarial-general` skill.
-- **Edge case hunter** — receives `{diff_output}` and read access to the project. Invoke via the `bmad-review-edge-case-hunter` skill.
-- **Acceptance auditor** — receives `{diff_output}`, `{spec_file}`, and read access to the project. Must also read the docs listed in `{spec_file}` frontmatter `context`. Checks for violations of acceptance criteria, rules, and principles from the spec and context docs.
+- **Blind hunter** — prompt: "Use the `bmad-review-adversarial-general` skill on `{diff_output}`."
+- **Edge case hunter** — prompt: "Use the `bmad-review-edge-case-hunter` skill on `{diff_output}`."
 
 ### Classify
 
 1. Deduplicate all review findings.
-2. Classify each finding. The first three categories are **this story's problem** — caused or exposed by the current change. The last two are **not this story's problem**.
+2. Assign severity to each finding by consequence for the artifact's main consumer (software user, document reader, etc).
+   Disregard any severity assigned by a reviewing subagent. Review subagents operate under by-design information asymmetry and do not have enough context to set final severity for this workflow.
+   - `low`: none or cosmetic
+   - `medium`: tolerable
+   - `high`: intolerable
+3. Route each finding into exactly one triage category. The first three categories are **this story's problem** — caused or exposed by the current change. The last two are **not this story's problem**.
    - **intent_gap** — caused by the change; cannot be resolved from the spec because the captured intent is incomplete. Do not infer intent unless there is exactly one possible reading.
    - **bad_spec** — caused by the change, including direct deviations from spec. The spec should have been clear enough to prevent it. When in doubt between bad_spec and patch, prefer bad_spec — a spec-level fix is more likely to produce coherent code.
    - **patch** — caused by the change; trivially fixable without human input. Just part of the diff.
    - **defer** — pre-existing issue not caused by this story, surfaced incidentally by the review. Collect for later focused attention.
    - **reject** — noise. Drop silently. When unsure between defer and reject, prefer reject — only defer findings you are confident are real.
-3. Process findings in cascading order. If intent_gap or bad_spec findings exist, they trigger a loopback — lower findings are moot since code will be re-derived. If neither exists, process patch and defer normally. Increment `{specLoopIteration}` on each loopback. If it exceeds 5, HALT and escalate to the human.
+4. Process findings in cascading order. If intent_gap or bad_spec findings exist, they trigger a loopback — lower findings are moot since code will be re-derived. If neither exists, process patch and defer normally. Before each loopback, read `{spec_file}` frontmatter `review_loop_iteration` (missing means `0`), increment it by 1, and write it back. If it exceeds 5, HALT and escalate to the human.
    - **intent_gap** — Root cause is inside `<frozen-after-approval>`. Revert code changes. Loop back to the human to resolve. Once resolved, read fully and follow `./step-02-plan.md` to re-run steps 2–4.
    - **bad_spec** — Root cause is outside `<frozen-after-approval>`. Before reverting code: extract KEEP instructions for positive preservation (what worked well and must survive re-derivation). Revert code changes. Read the `## Spec Change Log` in `{spec_file}` and strictly respect all logged constraints when amending the non-frozen sections that contain the root cause. Append a new change-log entry recording: the triggering finding, what was amended, the known-bad state avoided, and the KEEP instructions. Read fully and follow `./step-03-implement.md` to re-derive the code, then this step will run again.
    - **patch** — Auto-fix. These are the only findings that survive loopbacks.
-   - **defer** — Append to `{deferred_work_file}`.
+   - **defer** — Append one new entry to `{deferred_work_file}` using this format. Do not modify existing entries or look for duplicates.
+     ```markdown
+     - source_spec: `{spec_file}`
+       summary: <one sentence>
+       evidence: <why this is real>
+     ```
    - **reject** — Drop silently.
 
 ## NEXT

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

@@ -19,14 +19,19 @@ Implement the clarified intent directly.
 
 ### Review
 
-Invoke the `bmad-review-adversarial-general` skill in a subagent with the changed files. The subagent gets NO conversation context — to avoid anchoring bias. Launch at the same model capability as the current session. If no sub-agents are available, write the changed files to a review prompt file in `{implementation_artifacts}` and HALT. Ask the human to run the review in a separate session and paste back the findings.
+Invoke the `bmad-review-adversarial-general` skill in a subagent with the changed files. The subagent gets NO conversation context — to avoid anchoring bias. Launch at the same model capability as the current session. If no subagents are available, write the changed files to a review prompt file in `{implementation_artifacts}` and HALT. Ask the human to run the review in a separate session and paste back the findings.
 
 ### Classify
 
 Deduplicate all review findings. Three categories only:
 
 - **patch** — trivially fixable. Auto-fix immediately.
-- **defer** — pre-existing issue not caused by this change. Append to `{deferred_work_file}`.
+- **defer** — pre-existing issue not caused by this change. Append one new entry to `{deferred_work_file}` using this format. Do not modify existing entries or look for duplicates.
+  ```markdown
+  - source_spec: `{spec_file}`
+    summary: <one sentence>
+    evidence: <why this is real>
+  ```
 - **reject** — noise. Drop silently.
 
 If a finding is caused by this change but too significant for a trivial patch, HALT and present it to the human for decision before proceeding.

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

@@ -29,4 +29,3 @@ BMad Method,bmad-code-review,Code Review,CR,Story cycle: If issues back to DS if
 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.,,,4-implementation,,,false,,
 BMad Method,bmad-qa-generate-e2e-tests,QA Automation Test,QA,Generate automated API and E2E tests for implemented code. NOT for code review or story validation — use CR for that.,,,4-implementation,bmad-dev-story,,false,implementation_artifacts,test suite
 BMad Method,bmad-retrospective,Retrospective,ER,Optional at epic end: Review completed work lessons learned and next epic or if major issues consider CC.,,,4-implementation,bmad-code-review,,false,implementation_artifacts,retrospective
-BMad Method,bmad-investigate,Investigate,IN,Forensic case investigation calibrated to the input. Evidence-graded analysis with hypothesis tracking. Produces a structured case file.,,4-implementation,,,false,implementation_artifacts,investigation report

package/src/core-skills/bmad-forge-idea/SKILL.md

@@ -7,13 +7,13 @@ description: Pressure-test an idea through persona-driven interrogation until it
 
 ## Overview
 
-Take a half-formed idea out of the user's head and pressure-test it now, in conversation, where changing your mind is free — until what survives is something they can act on with earned conviction, or it dies cheaply. The enemy is the hole you cannot see in your own idea: every unexamined assumption and unresolved branch is a crack that otherwise surfaces later, in the build or the launch, when it costs far more to fix.
+Take a half-formed idea and pressure-test it in conversation, while changing your mind is still cheap, until it becomes something the user can act on with conviction or reject. The main risk is what the user has not examined yet: unchecked assumptions and unresolved decisions usually become more expensive problems later.
 
-The product is the quality of the user's thinking, not an artifact. Hardening an idea, proving or disproving it, or just being an unsparing thinking partner are each a complete outcome. A distilled `forged-idea.md` and a handoff downstream are one optional exit, never the destination — so never herd the user toward "shall we build it?"
+The main goal is better thinking, not producing an artifact. Strengthening an idea, rejecting it, or thinking it through more clearly are all complete outcomes. Writing `forged-idea.md` to hand off to another workflow is optional. Do not steer the conversation toward "shall we build it?"
 
-This is domain-agnostic — the idea may be software, a business model, a creative concept, a research hypothesis, a life decision, or a frivolous thought experiment. When it's a product or feature — net-new or a change inside an existing project — the forge stands in as an alternative analysis-and-definition tool, and what survives distills into `forged-idea.md` for downstream planning.
+This skill can be used on many kinds of ideas. When the idea is about a product or feature, what survives may be written to `forged-idea.md` for later planning.
 
-Act as an exacting interrogator who would rather find the crack than spare the feelings. This is interactive and socratic by nature; there is no headless mode.
+Lead by questioning, not lecturing. Ask one question at a time, press on weak points, and do not let vague claims pass without examination.
 
 ## Conventions
 
@@ -31,21 +31,47 @@ Act as an exacting interrogator who would rather find the crack than spare the f
 
 ## Open the session
 
-Open cold. Acknowledging the idea is not endorsing it — do not praise it before it has survived anything, on this turn or any turn. The pull to validate the idea up front to build rapport is the exact reflex this skill exists to refuse.
+Start by scrutinizing the idea, not endorsing it.
 
-Determine the goal before pressing (if a persona is already active with an idea on the table, confirm it in a line rather than asking). Otherwise ask in one message: what is the idea, and what do you want — harden it, prove or kill it, or just think it through? The goal steers the push: proving goes for the load-bearing claim first; hardening drives each branch to a resolved answer. Note whether the idea is net-new or a change inside an existing project.
+### Discover intent
+Identify: 
+- the subject idea, 
+- the user's goal for the session, 
+- whether the idea is new or a change to an existing project
 
-Tell the user the gear they can call anytime: **"adversarial on this"** (attacked to destruction — you attack, they defend; "switch roles," "you defend now, they attack"). The room is always in play once the topic is set (see The personas) — they can name any persona or call a whole party by name to steer who's at the table.
+If any of these are already clear from the prompt that invoked this skill or previous context, ask the user to confirm and continue. 
+
+Otherwise ask for what's missing, in order: 
+- what is the idea?
+- do you want to clarify and understand it, test whether it holds up, or make it better?
+- is it a new idea or a change to an existing project? If the latter, what project is it, and where can I find its files or other relevant materials?
+
+### Steering the conversation
+
+Tell the user they can say **"attack this"**, **"defend this"**, or **"switch roles"** at any time to change how the current idea is argued. In attack mode, do not agree with the idea; look for contradictions, weak assumptions, and failure cases. In defend mode, argue for the strongest version of the idea. Tell the user they can also name a persona or party at any time to change who participates in the session.
+
+### Set up the session
 
 Derive a kebab-case `{slug}` for the idea and bind the session workspace `{workspace} = {workflow.forge_output_path}/{workflow.run_folder_pattern}` (the pattern fills with `{slug}`). Create the memlog once the goal is known:
 `uv run {project-root}/_bmad/scripts/memlog.py init --workspace {workspace} --field idea="<idea>" --field goal="<goal>"`
+
 Tell the user the path; state is on disk now, so the session survives interruption. If init fails, don't abort — run the forge in-conversation and tell the user state won't persist this session.
 
 ## The forge
 
-Work one question at a time, in dependency order. Put your own recommended answer on the table each time — a position to push against gets further than an open prompt. Find discoverable answers yourself rather than asking. Treat the user's own words as suspect too: when a term is fuzzy or carries two meanings — a business 'user' versus 'buyer' versus 'payer', not just a code noun — name the ambiguity and force a precise choice before the branch resolves, because a branch built on an overloaded word resolves falsely. When the idea lands inside an existing project, that project's material is your ground truth, and a label is not a move: find the relevant material yourself, check the claim against it, and when it contradicts, make the contradiction the next question. When a branch resolves, give the user a beat before moving on — the crack they were holding back surfaces in that opening.
+Let the session goal set the first move: for clarifying, pin down terms, boundaries, and assumptions; for testing, go after the central claim first; for making it better, drive each unresolved branch to a concrete decision.
+
+Work one question at a time, in dependency order.
 
-**Never default-agree.** Reflexive agreement lowers the pressure and the user thinks shallower for it. Attack the weak point or build on the strong one — whichever drives deeper thinking — and praise only what genuinely earns it. The objective is the best idea, not a comfortable user.
+Include your current best answer or hypothesis when it helps the user respond. A concrete proposal is easier to accept, reject, or revise than an open-ended prompt. Find discoverable answers yourself instead of asking.
+
+Do not assume the user's terms are precise. When a term is fuzzy or overloaded, name the ambiguity and ask for a precise choice before continuing. For example, do not let `user`, `buyer`, and `payer` collapse into one entity unless the idea actually requires that.
+
+For ideas about an existing project, treat the project's files and materials as the source of truth. Do not accept a label or summary as proof. Find the relevant material yourself and check the user's claim against it. If the material contradicts the user's claim, stop and resolve that before continuing.
+
+When a branch resolves, pause before moving on. Give the user a chance to raise any remaining concern.
+
+Do not use agreement or praise to make the interaction smoother; they lower pressure and lead to shallower thinking. Agreement is allowed only when it helps the user think better. Praise is noise. Continued engagement and ego-stroking are not objectives. In attack mode, never agree with the idea until the user ends the mode. For each answer, either challenge the weak point or build on the strong point, whichever helps the user think better.
 
 Capture as you go — each decision, assumption, crack, kill, and locked idea, one bullet in the user's meaning:
 `uv run {project-root}/_bmad/scripts/memlog.py append --workspace {workspace} --type <decision|assumption|crack|kill|direction|lock|note> --text "<gist>"`
@@ -53,27 +79,29 @@ A `lock` is an idea the user hardens — settled, not to be reopened; locks are
 
 ## The personas
 
-The forge is voiced, not generic — and once the topic is set it always runs with the room, because a branch worked by two sharp characters goes deeper and lands harder than a faceless assistant ever could. A persona loaded at activation leads throughout and holds character.
+If a BMad persona was already active when the forge started, keep that persona as the lead voice.
 
-Resolve the pool once, as soon as the goal is known:
+Resolve the available persona pool once, as soon as the goal is known:
 `uv run {skill-root}/scripts/resolve_personas.py --project-root {project-root} --skill {skill-root}`
-It returns the installed BMad roster (`agents`), any custom personas the user authored (`members`), and their saved party groups (`parties` — each with an optional `scene` to play, open-cast rooms flagged) — everything `bmad-party-mode` knows, without invoking it.
+The script returns installed BMad agents (`agents`), user-defined personas (`members`), and saved parties (`parties`). Parties may include a `scene`; some are open-cast. This gives you the same roster information as `bmad-party-mode` without invoking it.
+
+Each turn uses two voices:
+- **One available persona** — choose an installed agent or user-defined persona whose expertise fits the current branch. Vary this voice every few turns; do not let one voice dominate. If the user names a specific persona, use it. If the user calls a saved party, use the whole party and its scene. If the user asks to go one-on-one, use only the requested persona. If no pool is available, generate this voice yourself.
+- **One generated persona** — create a fresh outside voice, such as a competitor, buyer, finance reviewer, domain expert, or critic. Give it a name and enough characterization to keep its viewpoint distinct.
 
-From then on, every turn brings two voices to the branch — witnesses you cross-examine, not a panel that debates:
-- **One from the user's pool** — an installed agent or custom persona they'll recognize, whose expertise fits the branch in play. Vary who shows up every few turns to keep the pressure high and the angles fresh; don't let the same voice dominate. If the user calls a specific name, bring them in. If the pool resolves empty (a core-only install with no roster), generate both voices on the fly so every branch still arrives with two.
-- **One you generate on the fly** — a fresh persona the topic conjures (a hostile competitor, a skeptical CFO, a domain specialist, a historical persona or expert), named and characterized so it's unmistakably itself.
+Use these voices in character to pressure-test the current branch: find sharper objections, missing assumptions, and stronger defenses. Cross-examine them for what matters, then synthesize their input into your next question. Do not let the session turn into a panel debate or persona performance.
 
-They hammer the branch in character; you synthesize their hits into your next question and drive it to a resolved answer. The user steers anytime — name a specific person, call a whole saved party for its scene, or go one-on-one. Voice them yourself by default; spawn separate agents (as `bmad-party-mode` does) only when a branch needs genuinely independent minds — a verdict that shouldn't be colored by one voice speaking for all.
+Voice the personas yourself by default. Spawn separate agents only when a branch needs independent reasoning that should not be influenced by one shared voice.
 
 ## Exits
 
-The session ends however the thinking lands, and every landing is a real outcome:
+The session can end in three valid states:
 
-- **Hardened** — the idea survived. Distill the memlog into `{workspace}/forged-idea.md`: super succinct — the locked items and what was killed and why, in the user's meaning. Not a prose retelling, not a template, not the conversation replayed — the load-bearing residue, nothing else. If it reads like a document, it's too long. Note it can feed `bmad-spec`, `bmad-prd`, or `bmad-prfaq`.
-- **Killed** — the idea did not survive. Say so plainly and record why. Finding this cheaply is a win, not a failure.
-- **Clearer** — the user simply thinks straighter now. The memlog stands on its own; no `forged-idea.md` needed (the report below still renders).
+- **Hardened** — the idea is stronger and specific enough to use. Distill the memlog into `{workspace}/forged-idea.md`. Keep it extremely short: only the decisions, rejected options, and reasons that matter downstream, in the user's meaning. Do not write a prose summary, template, or conversation recap. If it reads like a document, it is too long. Note that it can feed `bmad-spec`, `bmad-prd`, or `bmad-prfaq`.
+- **Killed** — the idea does not hold up. Say so plainly and record why. Finding that out early is a valid outcome.
+- **Clearer** — the user understands the idea better, but there is no hardened idea to hand off. Leave the memlog as the record; no `forged-idea.md` is needed.
 
-However it lands, render the verdict as a self-contained HTML report the user can open — `{workspace}/forge-report.html`, written every time, no asking. Strike it with a bespoke wax-seal/stamp matched to the outcome: **HARDENED** for a survivor, an **Idea Death Certificate** stamped **KILLED** (with the cause of death) for one that didn't, or a fitting bespoke seal for wherever else it landed (e.g. **CLARIFIED**). Lay out the load-bearing residue — the locked items, what was killed and why, the cracks that held — in the user's meaning, and credit the room: the personas and parties that pressure-tested it, by name, icon, and voice. One nicely-styled page (inline CSS, an inline-SVG seal, light flourish only where it lifts the piece) — a genuine keepsake, not a templated dump. Tell the user the path.
+Always render `{workspace}/forge-report.html` as a self-contained HTML file the user can open, with inline CSS and an inline-SVG seal or stamp. Summarize the outcome, the locked decisions, what was rejected and why, and the weak points that survived scrutiny, in the user's meaning. Credit the personas and parties that pressure-tested the idea by name, icon, and voice. Render a prominent wax-seal-style or stamped outcome mark, matched to the result: `HARDENED`, an `Idea Death Certificate` stamped `KILLED` with the cause of death, or `CLARIFIED`. Tell the user the path.
 
 Flip the status at the end: `uv run {project-root}/_bmad/scripts/memlog.py set --workspace {workspace} --key status --value complete`.
 If `{workflow.on_complete}` is non-empty, run all instructions in order.

package/src/core-skills/bmad-review-adversarial-general/SKILL.md

@@ -28,7 +28,7 @@ Review with extreme skepticism — assume problems exist. Find at least ten issu
 
 ### Step 3: Present Findings
 
-Output findings as a Markdown list (descriptions only).
+Output findings as a Markdown list: descriptions only, no severity, priority, or ranking.
 
 
 ## HALT CONDITIONS

package/src/core-skills/bmad-review-edge-case-hunter/SKILL.md

@@ -16,7 +16,7 @@ Ignore the rest of the codebase unless the provided content explicitly reference
 
 **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.**
 
-**Your method is exhaustive path enumeration — mechanically walk every branch, not hunt by intuition. Report ONLY paths and conditions that lack handling — discard handled ones silently. Do NOT editorialize or add filler — findings only.**
+**Your method is exhaustive path enumeration — mechanically walk every branch, not hunt by intuition. Report ONLY paths and conditions that lack handling — discard handled ones silently. Do NOT editorialize or add filler. Do not assign severity labels, rankings, or priority levels.**
 
 
 ## EXECUTION

package/tools/installer/modules/custom-module-manager.js

@@ -11,6 +11,18 @@ function quoteCustomRef(ref) {
   return `"${ref}"`;
 }
 
+function isLocalSourcePath(input) {
+  return (
+    input.startsWith('/') ||
+    input.startsWith('./') ||
+    input.startsWith('../') ||
+    input.startsWith('.\\') ||
+    input.startsWith('..\\') ||
+    input.startsWith('~') ||
+    path.win32.isAbsolute(input)
+  );
+}
+
 /**
  * Manages custom modules installed from user-provided sources.
  * Supports any Git host (GitHub, GitLab, Bitbucket, self-hosted) and local file paths.
@@ -83,13 +95,7 @@ class CustomModuleManager {
         // Avoid consuming the @ in `git@host:owner/repo` — `before` wouldn't end with a path separator
         // in that case. Require that the @ comes after the host/path, not inside the auth segment.
         // Rule: the @ is a version suffix only if `before` looks like a complete URL or local path.
-        const beforeLooksLikeRepo =
-          before.startsWith('/') ||
-          before.startsWith('./') ||
-          before.startsWith('../') ||
-          before.startsWith('~') ||
-          /^https?:\/\//i.test(before) ||
-          /^git@[^:]+:.+/.test(before);
+        const beforeLooksLikeRepo = isLocalSourcePath(before) || /^https?:\/\//i.test(before) || /^git@[^:]+:.+/.test(before);
         if (beforeLooksLikeRepo) {
           versionSuffix = candidate;
           trimmed = before;
@@ -97,8 +103,8 @@ class CustomModuleManager {
       }
     }
 
-    // Local path detection: starts with /, ./, ../, or ~
-    if (trimmed.startsWith('/') || trimmed.startsWith('./') || trimmed.startsWith('../') || trimmed.startsWith('~')) {
+    // Local path detection: POSIX, Windows, relative, or home-relative.
+    if (isLocalSourcePath(trimmed)) {
       if (versionSuffix) {
         return {
           type: 'local',

package/tools/validate-skills.js

@@ -312,6 +312,11 @@ function validateSkill(skillDir) {
   const name = skillFm && skillFm.name;
   const description = skillFm && skillFm.description;
 
+  // Deprecated skills are thin compatibility shims that forward to a replacement.
+  // They intentionally omit a "Use when" trigger so users are steered to the new
+  // skill instead, so exempt them from the SKILL-06 trigger-phrase requirement.
+  const isDeprecated = typeof description === 'string' && /^\s*deprecated\b/i.test(description);
+
   // --- SKILL-04: name format ---
   if (name && !NAME_REGEX.test(name)) {
     findings.push({
@@ -349,7 +354,7 @@ function validateSkill(skillDir) {
       });
     }
 
-    if (!/use\s+when\b/i.test(description) && !/use\s+if\b/i.test(description)) {
+    if (!isDeprecated && !/use\s+when\b/i.test(description) && !/use\s+if\b/i.test(description)) {
       findings.push({
         rule: 'SKILL-06',
         title: 'description Quality',

package/src/bmm-skills/4-implementation/bmad-investigate/SKILL.md

@@ -1,196 +0,0 @@
----
-name: bmad-investigate
-description: Forensic case investigation with evidence-graded findings, calibrated to the input. Use when the user asks to investigate a bug, trace what caused an incident, walk through unfamiliar code, or build a mental model of a code area before working on it.
----
-
-# Investigate
-
-## Overview
-
-Reconstruct what's happening, or what an unfamiliar area does, from the available evidence. Produce a structured case
-file another engineer can pick up cold. Calibrate continuously between defect-chasing (symptom-driven) and
-area-exploration (no symptom); the same discipline applies on both ends.
-
-**Args:** A ticket ID, log file path, diagnostic archive, error message, code area name, problem description, or a path
-to an existing case file. The last form resumes a prior investigation; everything else opens a new case.
-
-**Output:** `{implementation_artifacts}/{workflow.case_file_subdir}/{workflow.case_file_filename}`. Reference inputs
-are recorded; raw content is not read into the parent context until an outcome calls for it.
-
-`{slug}` is the ticket ID when one is provided, otherwise a short descriptive name agreed with the user, sanitized to
-lowercase alphanumeric with hyphens. On collision with an existing case file at the resolved path, ask whether to
-rename to `slug-YYYY-MM-DD.md` or resume the existing file (resuming routes to Outcome 0).
-
-After every outcome, present what was learned and pause for the user before continuing.
-
-## Principles
-
-- **Evidence grading.**
-  - **Confirmed.** Directly observed; cite `path:line`, log timestamp, or commit hash.
-  - **Deduced.** Logically follows from Confirmed evidence; show the chain.
-  - **Hypothesized.** Plausible but unconfirmed; state what would confirm or refute it.
-- **Stronghold first.** Anchor in one Confirmed piece of evidence and expand outward. Never start from a theory and
-  hunt for support. When evidence is sparse, switch to evidence-light mode (Outcome 1 branch).
-- **Challenge the premise.** The user's description is a hypothesis, not a fact. Verify independently; if evidence
-  contradicts, say so.
-- **Follow the evidence, not the narrative.** When evidence contradicts the working theory, update the theory — never
-  the other way around. Resist confirmation bias even when the user is convinced.
-- **Hypotheses are never deleted.** Update Status (Open / Confirmed / Refuted) and add a Resolution. Wrong turns are
-  part of the deliverable.
-- **Missing evidence is itself a finding.** Document the gap, what it would resolve, and how to obtain it.
-- **Write it down early.** Initialize the case file as soon as the slug is agreed; it is the persistent state across
-  interruptions.
-- **Path:line citations** use CWD-relative format, no leading `/`, so they're clickable in IDE-embedded terminals.
-- **Delegation discipline.** When a step requires reading 5+ files or any file >10K tokens, delegate to a subagent
-  that returns structured JSON only. Cite `path:line` from the result; don't re-read in the parent.
-- **Issue independent operations in parallel** (multi-grep, multi-read, parallel inventories) — one message, multiple
-  tool calls.
-- **Communication.** Evidence-first language ("the evidence shows", "unconfirmed, requires X to verify"). No hedging,
-  no narrative.
-
-## On Activation
-
-### Step 1: Resolve the workflow block
-
-Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`
-
-If the script fails, stop and surface the error.
-
-### Step 2: Execute prepend steps
-
-Run each entry in `{workflow.activation_steps_prepend}` in order.
-
-### Step 3: Load persistent facts
-
-Treat each entry in `{workflow.persistent_facts}` as foundational context. `file:` prefixes are paths or globs under
-`{project-root}` (load contents); other entries are facts verbatim.
-
-### Step 4: Load config
-
-Load `{project-root}/_bmad/bmm/config.yaml` and resolve `{user_name}`, `{communication_language}`,
-`{document_output_language}`, `{implementation_artifacts}`, `{project_knowledge}`. If `{implementation_artifacts}` is
-unresolved, fall back to `./investigations/` and surface the fallback before initializing.
-
-### Step 5: Greet
-
-Greet `{user_name}` in `{communication_language}`.
-
-### Step 6: Execute append steps
-
-Run each entry in `{workflow.activation_steps_append}` in order.
-
-Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
-
-### Step 7: Acknowledge and route
-
-Acknowledge the input as a reference (record paths and IDs; don't read raw content). Path to an existing case file →
-Outcome 0. Otherwise → Outcome 1.
-
-## Procedure
-
-### Outcome 0: Existing case is loaded and surfaced
-
-Read the case file. Surface, in order: open hypotheses (Status = Open) with their confirm/refute criteria; open
-backlog (Status ≠ Done); missing-evidence rows; last Conclusion with confidence. Ask which thread to pull. New
-evidence opens a new `## Follow-up: {YYYY-MM-DD}` block (append `#2`, `#3` on same-day reentry). Pause for user with the recap above; wait for direction.
-
-### Outcome 1: Scope and stronghold are established
-
-Acknowledge each input shape — record location, scope, time window only; bulk reads happen in Outcome 2.
-
-- **Issue tracker ticket.** Fetch full details via available MCP tools.
-- **Diagnostic archive.** Record path, file count, time window.
-- **Log file or stack trace.** Record path and time window; only the stack frame already in the user's message is in
-  scope here.
-- **Free-text description.** Capture verbatim; treat as hypothesis.
-- **Code area name** (no symptom). Record entry point.
-- **Recent commit area.** Record commit range.
-
-If the user arrived with a hypothesis, register it as Hypothesis #1. Find the stronghold *independently*; the user's
-hypothesis is one of the things the stronghold validates or refutes.
-
-Find a stronghold: a Confirmed piece of evidence (error message, function name, HTTP route, config parameter, test
-case). Anchor here.
-
-**Initialize `{case_file}` before branching.** The path is
-`{implementation_artifacts}/{workflow.case_file_subdir}/{workflow.case_file_filename}` with `{slug}` substituted (slug
-and collision rules in Overview). Create the file from `{workflow.case_file_template}` and fill Hand-off Brief
-(rough), Case Info, Problem Statement, initial Evidence Inventory.
-
-**Evidence-light branch.** When no Confirmed evidence is reachable: mark the case evidence-light in the Hand-off
-Brief; populate the Investigation Backlog with prioritized data-collection items; record "to make progress, I need one
-of: …"; pause for the user to provide evidence or authorize Outcome 2 to scan more broadly.
-
-Otherwise present scope, stronghold, file path, proposed approach. Pause for user with the recap above; wait for direction.
-
-### Outcome 2: Evidence perimeter is mapped
-
-Survey the scene: inventory available evidence in parallel across these independent categories: diagnostic archives;
-issue tracker; version control; test results; static analysis; source code. For any category exceeding ~10K tokens,
-delegate to a subagent that returns a JSON manifest (paths, sizes, time windows, key fragments cited as `path:line`).
-
-Classify each Available, Partial, or Missing — Missing is itself a finding. Update Evidence Inventory and Investigation
-Backlog. Pause for user with the recap above; wait for direction.
-
-### Outcome 3: Cause is reasoned about with discipline
-
-- **Trace causality.** Symptom-driven: trace backward from the symptom to producing conditions and the state that
-  emerged. Exploration: trace backward from outputs (returns, side effects, messages sent) to producing conditions.
-  Same technique, different anchor.
-- **Reconstruct the timeline** by cross-referencing logs, system events, version control, user observations.
-- **Form and test hypotheses.** State, identify confirming/refuting evidence, search, grade
-  (Confirmed / Refuted / Open). Update Status. Never delete.
-- **Refutation pass.** Each time a hypothesis transitions toward Confirmed, actively look for refuting evidence first.
-  Record the attempt in Resolution.
-- **Verify the user's premise.** If evidence contradicts, say so explicitly.
-- **Add discovered paths to the backlog.** Stay focused on the current thread.
-
-Update Confirmed Findings, Deduced Conclusions, Hypothesized Paths, Backlog, Timeline. Highlight contradictions to the
-original premise. Pause for user with the recap above; wait for direction.
-
-### Outcome 4: Source has been traced where it matters
-
-Issue these first-pass scans as parallel tool calls in one message: grep for exact error strings; glob the affected
-directory for parallel implementations; `git log` for recent changes.
-
-Then sequentially: read the surrounding code; follow the caller chain; watch for language and process boundary
-crossings (compiled→scripts, IPC, host→device, configuration flow).
-
-Lean by case type:
-
-- **Exploration:** I/O mapping (triggers, outputs, dependencies); frequent-terms scan; control-flow filtering
-  (branches, loops, error handling, state-machine transitions).
-- **Symptom-driven:** depth assessment — is the root cause reachable from local context, or is a broader area model
-  required? Surface escalations; never silently expand scope. Trivial-fix assessment — off-by-one, missing null check,
-  swapped argument → one-line code suggestion or draft diff in the report; non-trivial → stop at the root cause area.
-
-Investigation stops at the diagnosis; implementation is out of scope. Update Source Code Trace (Error origin, Trigger,
-Condition, Related files; area model when broader). Pause for user with the recap above; wait for direction.
-
-### Outcome 5: Report is finalized and the hand-off is clean
-
-Update `{case_file}`:
-
-- **Hand-off Brief** rewritten to final form (3 sentences, 15-second read).
-- **Final Conclusion** with confidence: **High** (Confirmed root cause, deterministic repro), **Medium** (Deduced;
-  minor uncertainty), **Low** (Hypothesized; clear data gap).
-- **Fix direction** when applicable (categorize by mechanism if multiple combine).
-- **Diagnostic steps** if uncertainty remains.
-- **Reproduction Plan** when applicable, or a verification plan for exploration cases.
-- **Status:** Active / Concluded / Blocked on evidence.
-
-Present the conclusion, then a concrete next-steps menu: trivial fix → `bmad-quick-dev`; scope/plan adjustment →
-`bmad-correct-course`; tracked story → `bmad-create-story`; fresh review → `bmad-code-review`. Recommend the
-highest-value action. Mitigations and workarounds are generated only on explicit request — investigation stops at the
-diagnosis. Execute `{workflow.on_complete}` if non-empty. Pause for user with the recap above; wait for direction.
-
-## Follow-up Iterations
-
-Continue work by appending to `{case_file}` under a new `## Follow-up: {YYYY-MM-DD}` block (`#2`, `#3` on same-day
-reentry). The investigation is complete when:
-
-- Root cause is Confirmed.
-- Root cause is Hypothesized with a clear data gap.
-- The mental model is sufficient for the user's stated goal (exploration cases).
-- The backlog contains only items requiring unavailable evidence.
-- The user explicitly concludes.

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

@@ -1,62 +0,0 @@
-# DO NOT EDIT -- overwritten on every update.
-#
-# Workflow customization surface for bmad-investigate. Mirrors the
-# agent customization shape under the [workflow] namespace.
-
-[workflow]
-
-# --- Configurable below. Overrides merge per BMad structural rules: ---
-#   scalars: override wins • arrays (persistent_facts, activation_steps_*): append
-#   arrays-of-tables with `code`/`id`: replace matching items, append new ones.
-
-# Steps to run before the standard activation (config load, greet).
-# Overrides append. Use for pre-flight loads, compliance checks, etc.
-
-activation_steps_prepend = []
-
-# Steps to run after greet but before the workflow begins.
-# Overrides append. Use for context-heavy setup that should happen
-# once the user has been acknowledged.
-
-activation_steps_append = []
-
-# Persistent facts the workflow keeps in mind for the whole run.
-# Use for citation conventions (path:line vs path#L42), grading-scale
-# overrides (ITIL severity 1-5 instead of High/Medium/Low), tone
-# directives (engineering vs exec-facing), or compliance constraints
-# the case file must respect.
-# Distinct from the runtime memory sidecar — these are static context
-# loaded on activation. Overrides append.
-#
-# Each entry is either:
-#   - a literal sentence, e.g. "Use ITIL severity 1-5 instead of High/Medium/Low for confidence."
-#   - 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",
-]
-
-# Scalar: path to the case-file template, resolved from the skill root.
-# Override to point at an org-shaped template (compliance sections,
-# SLA fields, post-mortem hooks, ITIL fields).
-
-case_file_template = "references/case-file-template.md"
-
-# Scalar: subdirectory under {implementation_artifacts} where case files land.
-# Override for org taxonomies (forensics/, cases/, incidents/, bug-bash/).
-
-case_file_subdir = "investigations"
-
-# Scalar: filename pattern for new case files. {slug} expands to the
-# ticket ID or a short user-agreed name.
-
-case_file_filename = "{slug}-investigation.md"
-
-# Scalar: executed when the workflow finalizes the case file at Outcome 5,
-# after the conclusion is presented. Override wins. Use for post-case
-# automation: post the case to Slack/Teams, push fields back to ticketing,
-# link the case to a sprint, trigger a follow-up retro.
-# Leave empty for no custom post-completion behavior.
-
-on_complete = ""

package/src/bmm-skills/4-implementation/bmad-investigate/references/case-file-template.md

@@ -1,127 +0,0 @@
-# Investigation: {title}
-
-## Hand-off Brief
-
-1. **What happened.** {one-sentence problem statement, evidence-graded}
-2. **Where the case stands.** {status, last finding, what would unblock progress}
-3. **What's needed next.** {single recommended action with rationale}
-
-## Case Info
-
-| Field            | Value                                                                      |
-| ---------------- | -------------------------------------------------------------------------- |
-| Ticket           | {ticket-id or "N/A"}                                                       |
-| Date opened      | {date}                                                                     |
-| Status           | Active                                                                     |
-| System           | {OS, version, relevant environment details}                                |
-| Evidence sources | {diagnostic archive, logs, crash dump, code, version control, etc.}        |
-
-## Problem Statement
-
-{User-reported description; the initial claim. May be refined or contradicted by evidence.}
-
-## Evidence Inventory
-
-| Source   | Status                          | Notes     |
-| -------- | ------------------------------- | --------- |
-| {source} | {Available / Partial / Missing} | {details} |
-
-## Investigation Backlog
-
-| # | Path to Explore | Priority              | Status                                | Notes     |
-| - | --------------- | --------------------- | ------------------------------------- | --------- |
-| 1 | {description}   | {High / Medium / Low} | {Open / In Progress / Done / Blocked} | {context} |
-
-## Timeline of Events
-
-| Time        | Event               | Source                | Confidence            |
-| ----------- | ------------------- | --------------------- | --------------------- |
-| {timestamp} | {event description} | {log file, commit, …} | {Confirmed / Deduced} |
-
-## Confirmed Findings
-
-### Finding 1: {title}
-
-**Evidence:** {citation — `path:line`, log timestamp, or commit hash}
-
-**Detail:** {description}
-
-## Deduced Conclusions
-
-### Deduction 1: {title}
-
-**Based on:** {which Confirmed Findings}
-
-**Reasoning:** {logical chain}
-
-**Conclusion:** {what follows}
-
-## Hypothesized Paths
-
-### Hypothesis 1: {title}
-
-**Status:** {Open / Confirmed / Refuted}
-
-**Theory:** {description}
-
-**Supporting indicators:** {what makes this plausible}
-
-**Would confirm:** {specific evidence that would prove this}
-
-**Would refute:** {specific evidence that would disprove this}
-
-**Resolution:** {when Status changes from Open, what evidence settled it}
-
-## Missing Evidence
-
-| Gap              | Impact                               | How to Obtain   |
-| ---------------- | ------------------------------------ | --------------- |
-| {what's missing} | {what it would confirm or eliminate} | {how to get it} |
-
-## Source Code Trace
-
-| Element       | Detail                                      |
-| ------------- | ------------------------------------------- |
-| Error origin  | {file:line, function name}                  |
-| Trigger       | {what causes this code to execute}          |
-| Condition     | {what state produces the observed behavior} |
-| Related files | {other files in the same code path}         |
-
-## Conclusion
-
-**Confidence:** {High / Medium / Low}
-
-{Summary stating what is Confirmed vs. what remains Hypothesized. If a root cause is identified, state it; otherwise
-name the most promising hypothesized paths and what would resolve the remaining uncertainty.}
-
-## Recommended Next Steps
-
-### Fix direction
-
-{What needs to change and why. Categorize by mechanism when multiple issues combine.}
-
-### Diagnostic
-
-{Steps to confirm the root cause: additional logging, targeted tests, data to collect.}
-
-## Reproduction Plan
-
-{Setup, trigger, expected results. Scale from isolated proof to full system reproduction.}
-
-## Side Findings
-
-Tangential observations surfaced during the investigation, evidence-graded, with citation when applicable.
-
-- {observation}
-
-## Follow-up: {date}
-
-### New Evidence
-
-### Additional Findings
-
-### Updated Hypotheses
-
-### Backlog Changes
-
-### Updated Conclusion