bmad-method 6.0.3 → 6.0.4

package/.claude/skills/bmad-os-root-cause-analysis/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: bmad-os-root-cause-analysis
+description: Analyzes a bug-fix commit or PR and produces a structured Root Cause Analysis report covering what went wrong, why, and what guardrails failed.
+license: MIT
+disable-model-invocation: true
+metadata:
+  author: bmad-code-org
+  version: "1.0.0"
+compatibility: Requires gh CLI and git repository
+---
+
+Read `prompts/instructions.md` and execute.

package/.claude/skills/bmad-os-root-cause-analysis/prompts/instructions.md

@@ -0,0 +1,74 @@
+# Bug-Fix Root Cause Analysis
+
+Analyze a bug-fix commit or PR and produce a structured Root Cause Analysis report.
+
+## Principles
+
+- **Direct attribution.** This report names the individual who introduced the defect. Industry convention advocates blameless postmortems. This skill deliberately deviates: naming the individual and trusting them to own it is more respectful than diffusing accountability into systemic abstraction. Direct, factual, not accusatory. If authorship can't be determined confidently, say so.
+- **Pyramid communication.** The executive summary must convey the full picture. A reader who stops after the first paragraph gets the gist. Everything else is supporting evidence.
+
+## Preflight
+
+Verify `gh auth status` and that you're in a git repository. Stop with a clear message if either fails.
+
+## Execution
+
+1. **Identify the fix.** Accept whatever the user provides — commit SHA, PR, issue, description. Resolve to the specific fix commit/PR using `gh` and `git`. If ambiguous, ask. Confirm the change is actually a bug fix before proceeding.
+2. **Gather evidence.** Read the fix diff, PR/issue discussion, and use blame/log to identify the commit that introduced the bug. Collect timeline data.
+3. **Analyze.** Apply 5 Whys. Classify the root cause. Identify contributing factors.
+4. **Evaluate guardrails.** Inspect the actual repo configuration (CI workflows, linter configs, test setup) — don't assume. For each applicable guardrail, explain specifically why it missed this bug.
+5. **Write the report** to `_bmad-output/rca-reports/rca-{YYYY-MM-DD}-{slug}.md`. Present the executive summary in chat.
+
+## Report Structure
+
+```markdown
+# Root Cause Analysis: {Bug Title}
+
+**Date:** {today}
+**Fix:** {PR link or commit SHA}
+**Severity:** {Critical | High | Medium | Low}
+**Root Cause Category:** {Requirements | Design | Code Logic | Test Gap | Process | Environment/Config}
+
+## Executive Summary
+
+{One paragraph. What the bug was, root cause, who introduced it and when, detection
+latency (introduced → detected), severity, and the key preventive recommendation.}
+
+## What Was the Problem?
+
+## When Did It Happen?
+
+| Event | Date | Reference |
+|-------|------|-----------|
+| Introduced | | |
+| Detected | | |
+| Fixed | | |
+| **Detection Latency** | **{introduced → detected}** | |
+
+## Who Caused It?
+
+{Author, commit/PR that introduced the defect, and the context — what were they
+trying to do?}
+
+## How Did It Happen?
+
+## Why Did It Happen?
+
+{5 Whys analysis. Root cause category. Contributing factors.}
+
+## Failed Guardrails Analysis
+
+| Guardrail | In Place? | Why It Failed |
+|-----------|-----------|---------------|
+| | | |
+
+**Most Critical Failure:** {Which one mattered most and why.}
+
+## Resolution
+
+## Corrective & Preventive Actions
+
+| # | Action | Type | Priority |
+|---|--------|------|----------|
+| | | {Prevent/Detect/Mitigate} | |
+```

package/.github/ISSUE_TEMPLATE/config.yaml

@@ -1,7 +1,7 @@
 blank_issues_enabled: false
 contact_links:
   - name: 📚 Documentation
-    url: http://docs.bmad-method.org
+    url: https://docs.bmad-method.org
     about: Check the docs first — tutorials, guides, and reference
   - name: 💬 Discord Community
     url: https://discord.gg/gk8jAdXWmj

package/.github/ISSUE_TEMPLATE/documentation.yaml

@@ -28,7 +28,7 @@ body:
     attributes:
       label: Documentation location
       description: Where is the documentation that needs improvement?
-      placeholder: e.g., http://docs.bmad-method.org/tutorials/getting-started/ or "In the README"
+      placeholder: e.g., https://docs.bmad-method.org/tutorials/getting-started/ or "In the README"
     validations:
       required: true
 

package/CHANGELOG.md

@@ -1,10 +1,42 @@
 # Changelog
 
+## [6.0.4]
+
+### 🎁 Features
+
+* Add edge case hunter review task - new reusable review task that exhaustively traces branching paths and boundary conditions in code, reporting only unhandled gaps. Method-driven analysis complementary to adversarial review (#1790)
+
+### 🐛 Bug Fixes
+
+* Fix brainstorming to not overwrite previous sessions; now prompts to continue existing brainstorming or start a new one when older brainstorming sessions are found
+* Fix installer templates - replace legacy `@` path prefixes with explicit `{project-root}` syntax for consistency (#1769)
+* Fix edge case hunter - remove zero-findings halt condition that was pressuring the LLM to hallucinate findings when none legitimately exist (#1797)
+* Fix broken docs domain references in README and GitHub issue templates (#1777)
+
+---
+
 ## [6.0.3]
 
+### 🎁 Features
+
+* Add bmad-os-root-cause-analysis skill for analyzing bug-fix commits and producing structured root cause analysis reports with pyramid communication format (#1741)
+
 ### 🐛 Bug Fixes
 
+* Fix installer to refuse installation when ancestor directory has BMAD commands, preventing duplicate command autocompletion in nested directories (#1735)
+* Fix OpenCode integration by replacing unsupported `name` frontmatter with `mode: all` and update directory names to plural form (#1764)
+* Fix CSV manifest pipeline double-escaping of quotes that was corrupting output files; switch Gemini templates to single quotes (#1746)
 * Fix workflow descriptions to use proper quotes so they format better in skill conversion and don't break yaml front matter
+* Fix workflow help task chaining by removing ambiguous "with-argument" clause that caused LLMs to misinterpret help.md as skill calls (#1740)
+
+### ♻️ Refactoring
+
+* Standardize all workflow descriptions to use proper quotes to prevent breaking command or skill front matter during skill conversion
+
+### 📚 Documentation
+
+* Fix broken TEA hyperlinks to point to new repository URL (#1772)
+* Rebrand BMAD acronym to "Build More Architect Dreams" across documentation (#1765)
 
 ---
 

package/README.md

@@ -5,7 +5,7 @@
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org)
 [![Discord](https://img.shields.io/badge/Discord-Join%20Community-7289da?logo=discord&logoColor=white)](https://discord.gg/gk8jAdXWmj)
 
-**Breakthrough Method of Agile AI Driven Development** — An AI-driven agile development module for the BMad Method Module Ecosystem, the best and most comprehensive Agile AI Driven Development framework that has true scale-adaptive intelligence that adjusts from bug fixes to enterprise systems.
+**Build More Architect Dreams** — An AI-driven agile development module for the BMad Method Module Ecosystem, the best and most comprehensive Agile AI Driven Development framework that has true scale-adaptive intelligence that adjusts from bug fixes to enterprise systems.
 
 **100% free and open source.** No paywalls. No gated content. No gated Discord. We believe in empowering everyone, not just those who can pay for a gated community or courses.
 
@@ -20,7 +20,7 @@ Traditional AI tools do the thinking for you, producing average results. BMad ag
 - **Party Mode** — Bring multiple agent personas into one session to collaborate and discuss
 - **Complete Lifecycle** — From brainstorming to deployment
 
-[Learn more at **docs.bmad-method.org**](http://docs.bmad-method.org)
+[Learn more at **docs.bmad-method.org**](https://docs.bmad-method.org)
 
 ---
 
@@ -28,7 +28,7 @@ Traditional AI tools do the thinking for you, producing average results. BMad ag
 
 **V6 is here and we're just getting started!** The BMad Method is evolving rapidly with optimizations including Cross Platform Agent Team and Sub Agent inclusion, Skills Architecture, BMad Builder v1, Dev Loop Automation, and so much more in the works.
 
-**[📍 Check out the complete Roadmap →](http://docs.bmad-method.org/roadmap/)**
+**[📍 Check out the complete Roadmap →](https://docs.bmad-method.org/roadmap/)**
 
 ---
 
@@ -50,7 +50,7 @@ Follow the installer prompts, then open your AI IDE (Claude Code, Cursor, etc.)
 npx bmad-method install --directory /path/to/project --modules bmm --tools claude-code --yes
 ```
 
-[See all installation options](http://docs.bmad-method.org/how-to/non-interactive-installation/)
+[See all installation options](https://docs.bmad-method.org/how-to/non-interactive-installation/)
 
 > **Not sure what to do?** Run `/bmad-help` — it tells you exactly what's next and what's optional. You can also ask questions like `/bmad-help I just finished the architecture, what do I do next?`
 
@@ -62,17 +62,17 @@ BMad Method extends with official modules for specialized domains. Available dur
 | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
 | **[BMad Method (BMM)](https://github.com/bmad-code-org/BMAD-METHOD)**                                             | Core framework with 34+ workflows                 |
 | **[BMad Builder (BMB)](https://github.com/bmad-code-org/bmad-builder)**                                           | Create custom BMad agents and workflows           |
-| **[Test Architect (TEA)](https://github.com/bmad-code-org/tea)**                                                  | Risk-based test strategy and automation           |
+| **[Test Architect (TEA)](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise)**             | Risk-based test strategy and automation           |
 | **[Game Dev Studio (BMGD)](https://github.com/bmad-code-org/bmad-module-game-dev-studio)**                        | Game development workflows (Unity, Unreal, Godot) |
 | **[Creative Intelligence Suite (CIS)](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite)** | Innovation, brainstorming, design thinking        |
 
 ## Documentation
 
-[BMad Method Docs Site](http://docs.bmad-method.org) — Tutorials, guides, concepts, and reference
+[BMad Method Docs Site](https://docs.bmad-method.org) — Tutorials, guides, concepts, and reference
 
 **Quick links:**
-- [Getting Started Tutorial](http://docs.bmad-method.org/tutorials/getting-started/)
-- [Upgrading from Previous Versions](http://docs.bmad-method.org/how-to/upgrade-to-v6/)
+- [Getting Started Tutorial](https://docs.bmad-method.org/tutorials/getting-started/)
+- [Upgrading from Previous Versions](https://docs.bmad-method.org/how-to/upgrade-to-v6/)
 - [Test Architect Documentation](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/)
 
 

package/docs/index.md

@@ -3,7 +3,7 @@ title: Welcome to the BMad Method
 description: AI-driven development framework with specialized agents, guided workflows, and intelligent planning
 ---
 
-The BMad Method (**B**reakthrough **M**ethod of **A**gile AI **D**riven Development) is an AI-driven development framework module within the BMad Method Ecosystem that helps you build software through the whole process from ideation and planning all the way through agentic implementation. It provides specialized AI agents, guided workflows, and intelligent planning that adapts to your project's complexity, whether you're fixing a bug or building an enterprise platform.
+The BMad Method (**B**uild **M**ore **A**rchitect **D**reams) is an AI-driven development framework module within the BMad Method Ecosystem that helps you build software through the whole process from ideation and planning all the way through agentic implementation. It provides specialized AI agents, guided workflows, and intelligent planning that adapts to your project's complexity, whether you're fixing a bug or building an enterprise platform.
 
 If you're comfortable working with AI coding assistants like Claude, Cursor, or GitHub Copilot, you're ready to get started.
 

package/package.json

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

package/src/core/module-help.csv

@@ -7,3 +7,4 @@ core,anytime,Shard Document,SD,,_bmad/core/tasks/shard-doc.xml,bmad-shard-doc,fa
 core,anytime,Editorial Review - Prose,EP,,_bmad/core/tasks/editorial-review-prose.xml,bmad-editorial-review-prose,false,,,"Review prose for clarity, tone, and communication issues. Use after drafting to polish written content.",report located with target document,"three-column markdown table with suggested fixes",
 core,anytime,Editorial Review - Structure,ES,,_bmad/core/tasks/editorial-review-structure.xml,bmad-editorial-review-structure,false,,,"Propose cuts, reorganization, and simplification while preserving comprehension. Use when doc produced from multiple subprocesses or needs structural improvement.",report located with target document,
 core,anytime,Adversarial Review (General),AR,,_bmad/core/tasks/review-adversarial-general.xml,bmad-review-adversarial-general,false,,,"Review content critically to find issues and weaknesses. Use for quality assurance or before finalizing deliverables. Code Review in other modules run this automatically, but its useful also for document reviews",,
+core,anytime,Edge Case Hunter Review,ECH,,_bmad/core/tasks/review-edge-case-hunter.xml,bmad-review-edge-case-hunter,false,,,"Walk every branching path and boundary condition in code, report only unhandled edge cases. Use alongside adversarial review for orthogonal coverage - method-driven not attitude-driven.",,

package/src/core/tasks/help.md

@@ -1,6 +1,6 @@
 ---
 name: help
-description: "Analyzes what is done and the users query and offers advice on what to do next. Use if user says what should I do next or what do I do now"
+description: 'Analyzes what is done and the users query and offers advice on what to do next. Use if user says what should I do next or what do I do now'
 ---
 
 # Task: BMAD Help

package/src/core/tasks/review-edge-case-hunter.xml

@@ -0,0 +1,63 @@
+<!-- if possible, run this in a separate subagent or process with read access to the project,
+  but no context except the content to review -->
+
+<task id="_bmad/core/tasks/review-edge-case-hunter.xml" name="Edge Case Hunter Review"
+  description="Walk every branching path and boundary condition in content, report only unhandled edge cases. Orthogonal to adversarial review - method-driven not attitude-driven.">
+  <objective>You are a pure path tracer. Never comment on whether code is good or bad; only list missing handling.
+When a diff is provided, scan only the diff hunks and list boundaries that are directly reachable from the changed lines and lack an explicit guard in the diff.
+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.</objective>
+
+  <inputs>
+    <input name="content" desc="Content to review - diff, full file, or function" />
+    <input name="also_consider" required="false"
+      desc="Optional areas to keep in mind during review alongside normal edge-case analysis" />
+  </inputs>
+
+  <output-format>Return ONLY a valid JSON array of objects. Each object must contain exactly these four fields and nothing else:
+{
+  "location": "file:line",
+  "trigger_condition": "one-line description (max 15 words)",
+  "guard_snippet": "minimal code sketch that closes the gap",
+  "potential_consequence": "what could actually go wrong (max 15 words)"
+}
+No extra text, no explanations, no markdown wrapping.</output-format>
+
+  <llm critical="true">
+    <i>MANDATORY: Execute ALL steps in the flow section IN EXACT ORDER</i>
+    <i>DO NOT skip steps or change the sequence</i>
+    <i>HALT immediately when halt-conditions are met</i>
+    <i>Each action xml tag within step xml tag is a REQUIRED action to complete that step</i>
+
+    <i>Your method is exhaustive path enumeration — mechanically walk every branch, not hunt by intuition</i>
+    <i>Trace each branching path: conditionals, switches, early returns, guard clauses, loops, error handlers</i>
+    <i>Trace each boundary condition: null, undefined, empty, zero, negative, overflow, max-length, type coercion, concurrency, timing</i>
+    <i>Report ONLY paths and conditions that lack handling — discard handled ones silently</i>
+    <i>Do NOT editorialize or add filler — findings only</i>
+  </llm>
+
+  <flow>
+    <step n="1" title="Receive Content">
+      <action>Load the content to review from provided input or context</action>
+      <action>If content to review is empty, ask for clarification and abort task</action>
+      <action>Identify content type (diff, full file, or function) to determine scope rules</action>
+    </step>
+
+    <step n="2" title="Exhaustive Path Analysis" critical="true">
+      <mandate>Walk every branching path and boundary condition within scope - report only unhandled ones</mandate>
+      <action>If also_consider input was provided, incorporate those areas into the analysis</action>
+      <action>Enumerate all branching paths and boundary conditions within scope: conditionals, switches, early returns, guard clauses, loops, error handlers, null/empty states, overflow, type edges, concurrency, timing</action>
+      <action>For each path: determine whether the content handles it</action>
+      <action>Collect only the unhandled paths as findings - discard handled ones silently</action>
+    </step>
+
+    <step n="3" title="Present Findings">
+      <action>Output findings as a JSON array following the output-format specification exactly</action>
+    </step>
+  </flow>
+
+  <halt-conditions>
+    <condition>HALT if content is empty or unreadable</condition>
+  </halt-conditions>
+
+</task>

package/src/core/workflows/brainstorming/steps/step-01-session-setup.md

@@ -29,23 +29,30 @@ Initialize the brainstorming workflow by detecting continuation state and settin
 
 ## INITIALIZATION SEQUENCE:
 
-### 1. Check for Existing Workflow
+### 1. Check for Existing Sessions
 
-First, check if the output document already exists:
+First, check the brainstorming sessions folder for existing sessions:
 
-- Look for file at `{output_folder}/brainstorming/brainstorming-session-{{date}}.md`
-- If exists, read the complete file including frontmatter
-- If not exists, this is a fresh workflow
+- List all files in `{output_folder}/brainstorming/`
+- **DO NOT read any file contents** - only list filenames
+- If files exist, identify the most recent by date/time in the filename
+- If no files exist, this is a fresh workflow
 
-### 2. Handle Continuation (If Document Exists)
+### 2. Handle Existing Sessions (If Files Found)
 
-If the document exists and has frontmatter with `stepsCompleted`:
+If existing session files are found:
 
-- **STOP here** and load `./step-01b-continue.md` immediately
-- Do not proceed with any initialization tasks
-- Let step-01b handle the continuation logic
+- Display the most recent session filename (do NOT read its content)
+- Ask the user: "Found existing session: `[filename]`. Would you like to:
+  **[1]** Continue this session
+  **[2]** Start a new session
+  **[3]** See all existing sessions"
 
-### 3. Fresh Workflow Setup (If No Document)
+- If user selects **[1]** (continue): Set `{brainstorming_session_output_file}` to that file path and load `./step-01b-continue.md`
+- If user selects **[2]** (new): Generate new filename with current date/time and proceed to step 3
+- If user selects **[3]** (see all): List all session filenames and ask which to continue or if new
+
+### 3. Fresh Workflow Setup (If No Files or User Chooses New)
 
 If no document exists or no `stepsCompleted` in frontmatter:
 
@@ -55,10 +62,10 @@ Create the brainstorming session document:
 
 ```bash
 # Create directory if needed
-mkdir -p "$(dirname "{output_folder}/brainstorming/brainstorming-session-{{date}}.md")"
+mkdir -p "$(dirname "{brainstorming_session_output_file}")"
 
 # Initialize from template
-cp "{template_path}" "{output_folder}/brainstorming/brainstorming-session-{{date}}.md"
+cp "{template_path}" "{brainstorming_session_output_file}"
 ```
 
 #### B. Context File Check and Loading
@@ -134,7 +141,7 @@ _[Content based on conversation about session parameters and facilitator approac
 
 ## APPEND TO DOCUMENT:
 
-When user selects approach, append the session overview content directly to `{output_folder}/brainstorming/brainstorming-session-{{date}}.md` using the structure from above.
+When user selects approach, append the session overview content directly to `{brainstorming_session_output_file}` using the structure from above.
 
 ### E. Continue to Technique Selection
 
@@ -152,7 +159,7 @@ Which approach appeals to you most? (Enter 1-4)"
 
 #### When user selects approach number:
 
-- **Append initial session overview to `{output_folder}/brainstorming/brainstorming-session-{{date}}.md`**
+- **Append initial session overview to `{brainstorming_session_output_file}`**
 - **Update frontmatter:** `stepsCompleted: [1]`, `selected_approach: '[selected approach]'`
 - **Load the appropriate step-02 file** based on selection
 
@@ -167,7 +174,9 @@ After user selects approach number:
 
 ## SUCCESS METRICS:
 
-✅ Existing workflow detected and continuation handled properly
+✅ Existing sessions detected without reading file contents
+✅ User prompted to continue existing session or start new
+✅ Correct session file selected for continuation
 ✅ Fresh workflow initialized with correct document structure
 ✅ Session context gathered and understood clearly
 ✅ User's approach selection captured and routed correctly
@@ -176,7 +185,9 @@ After user selects approach number:
 
 ## FAILURE MODES:
 
-❌ Not checking for existing document before creating new one
+❌ Reading file contents during session detection (wastes context)
+❌ Not asking user before continuing existing session
+❌ Not properly routing user's continue/new session selection
 ❌ Missing continuation detection leading to duplicate work
 ❌ Insufficient session context gathering
 ❌ Not properly routing user's approach selection
@@ -184,7 +195,9 @@ After user selects approach number:
 
 ## SESSION SETUP PROTOCOLS:
 
-- Always verify document existence before initialization
+- Always list sessions folder WITHOUT reading file contents
+- Ask user before continuing any existing session
+- Only load continue step after user confirms
 - Load brain techniques CSV only when needed for technique presentation
 - Use collaborative facilitation language throughout
 - Maintain psychological safety for creative exploration

package/src/core/workflows/brainstorming/steps/step-01b-continue.md

@@ -35,7 +35,7 @@ Load existing document and analyze current state:
 
 **Document Analysis:**
 
-- Read existing `{output_folder}/brainstorming/brainstorming-session-{{date}}.md`
+- Read existing `{brainstorming_session_output_file}`
 - Examine frontmatter for `stepsCompleted`, `session_topic`, `session_goals`
 - Review content to understand session progress and outcomes
 - Identify current stage and next logical steps

package/src/core/workflows/brainstorming/steps/step-03-technique-execution.md

@@ -296,7 +296,7 @@ After final technique element:
 
 #### If 'C' (Move to organization):
 
-- **Append the technique execution content to `{output_folder}/brainstorming/brainstorming-session-{{date}}.md`**
+- **Append the technique execution content to `{brainstorming_session_output_file}`**
 - **Update frontmatter:** `stepsCompleted: [1, 2, 3]`
 - **Load:** `./step-04-idea-organization.md`
 
@@ -356,7 +356,7 @@ _[Short narrative describing the user and AI collaboration journey - what made t
 
 ## APPEND TO DOCUMENT:
 
-When user selects 'C', append the content directly to `{output_folder}/brainstorming/brainstorming-session-{{date}}.md` using the structure from above.
+When user selects 'C', append the content directly to `{brainstorming_session_output_file}` using the structure from above.
 
 ## SUCCESS METRICS:
 

package/src/core/workflows/brainstorming/steps/step-04-idea-organization.md

@@ -253,14 +253,14 @@ Provide final session wrap-up and forward guidance:
 
 #### If [C] Complete:
 
-- **Append the final session content to `{output_folder}/brainstorming/brainstorming-session-{{date}}.md`**
+- **Append the final session content to `{brainstorming_session_output_file}`**
 - Update frontmatter: `stepsCompleted: [1, 2, 3, 4]`
 - Set `session_active: false` and `workflow_completed: true`
 - Complete workflow with positive closure message
 
 ## APPEND TO DOCUMENT:
 
-When user selects 'C', append the content directly to `{output_folder}/brainstorming/brainstorming-session-{{date}}.md` using the structure from step 7.
+When user selects 'C', append the content directly to `{brainstorming_session_output_file}` using the structure from step 7.
 
 ## SUCCESS METRICS:
 

package/src/core/workflows/brainstorming/workflow.md

@@ -1,6 +1,6 @@
 ---
 name: brainstorming
-description: 'Facilitate interactive brainstorming sessions using diverse creative techniques and ideation methods. Use when the user says "help me brainstorm" or "help me ideate".'
+description: 'Facilitate interactive brainstorming sessions using diverse creative techniques and ideation methods. Use when the user says help me brainstorm or help me ideate.'
 context_file: '' # Optional context file path for project-specific guidance
 ---
 
@@ -45,7 +45,9 @@ Load config from `{project-root}/_bmad/core/config.yaml` and resolve:
 - `installed_path` = `{project-root}/_bmad/core/workflows/brainstorming`
 - `template_path` = `{installed_path}/template.md`
 - `brain_techniques_path` = `{installed_path}/brain-methods.csv`
-- `default_output_file` = `{output_folder}/brainstorming/brainstorming-session-{{date}}.md`
+- `brainstorming_session_output_file` = `{output_folder}/brainstorming/brainstorming-session-{{date}}-{{time}}.md` (evaluated once at workflow start)
+
+All steps MUST reference `{brainstorming_session_output_file}` instead of the full path pattern.
 - `context_file` = Optional context file path from workflow invocation for project-specific guidance
 - `advancedElicitationTask` = `{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml`
 

package/src/core/workflows/party-mode/workflow.md

@@ -1,6 +1,6 @@
 ---
 name: party-mode
-description: 'Orchestrates group discussions between all installed BMAD agents, enabling natural multi-agent conversations. Use when user requests "party mode" only.'
+description: 'Orchestrates group discussions between all installed BMAD agents, enabling natural multi-agent conversations. Use when user requests party mode.'
 ---
 
 # Party Mode Workflow

package/tools/cli/installers/install-messages.yaml

@@ -12,7 +12,7 @@ startMessage: |
     - Select and install modules during setup - customize your experience
     - New BMad Method for Agile AI-Driven Development (the evolution of V4)
     - Exciting new modules available during installation, with community modules coming soon
-    - Documentation: docs.bmad-method.com
+    - Documentation: https://docs.bmad-method.org
 
   🌟 BMad is 100% free and open source.
     - No gated Discord. No paywalls. No gated content.

package/tools/cli/installers/lib/core/manifest-generator.js

@@ -24,16 +24,14 @@ class ManifestGenerator {
   }
 
   /**
-   * Clean text for CSV output by normalizing whitespace and escaping quotes
+   * Clean text for CSV output by normalizing whitespace.
+   * Note: Quote escaping is handled by escapeCsv() at write time.
    * @param {string} text - Text to clean
-   * @returns {string} Cleaned text safe for CSV
+   * @returns {string} Cleaned text
    */
   cleanForCSV(text) {
     if (!text) return '';
-    return text
-      .trim()
-      .replaceAll(/\s+/g, ' ') // Normalize all whitespace (including newlines) to single space
-      .replaceAll('"', '""'); // Escape quotes for CSV
+    return text.trim().replaceAll(/\s+/g, ' '); // Normalize all whitespace (including newlines) to single space
   }
 
   /**

package/tools/cli/installers/lib/ide/_config-driven.js

@@ -34,6 +34,25 @@ class ConfigDrivenIdeSetup extends BaseIdeSetup {
    * @returns {Promise<Object>} Setup result
    */
   async setup(projectDir, bmadDir, options = {}) {
+    // Check for BMAD files in ancestor directories that would cause duplicates
+    if (this.installerConfig?.ancestor_conflict_check) {
+      const conflict = await this.findAncestorConflict(projectDir);
+      if (conflict) {
+        await prompts.log.error(
+          `Found existing BMAD commands in ancestor installation: ${conflict}\n` +
+            `  ${this.name} inherits commands from parent directories, so this would cause duplicates.\n` +
+            `  Please remove the BMAD files from that directory first:\n` +
+            `    rm -rf "${conflict}"/bmad*`,
+        );
+        return {
+          success: false,
+          reason: 'ancestor-conflict',
+          error: `Ancestor conflict: ${conflict}`,
+          conflictDir: conflict,
+        };
+      }
+    }
+
     if (!options.silent) await prompts.log.info(`Setting up ${this.name}...`);
 
     // Clean up any old BMAD installation first
@@ -453,6 +472,15 @@ LOAD and execute from: {project-root}/{{bmadFolderName}}/{{path}}
    * @param {string} projectDir - Project directory
    */
   async cleanup(projectDir, options = {}) {
+    // Migrate legacy target directories (e.g. .opencode/agent → .opencode/agents)
+    if (this.installerConfig?.legacy_targets) {
+      if (!options.silent) await prompts.log.message('  Migrating legacy directories...');
+      for (const legacyDir of this.installerConfig.legacy_targets) {
+        await this.cleanupTarget(projectDir, legacyDir, options);
+        await this.removeEmptyParents(projectDir, legacyDir);
+      }
+    }
+
     // Clean all target directories
     if (this.installerConfig?.targets) {
       const parentDirs = new Set();
@@ -532,24 +560,71 @@ LOAD and execute from: {project-root}/{{bmadFolderName}}/{{path}}
     }
   }
   /**
-   * Recursively remove empty directories walking up from dir toward projectDir
+   * Check ancestor directories for existing BMAD files in the same target_dir.
+   * IDEs like Claude Code inherit commands from parent directories, so an existing
+   * installation in an ancestor would cause duplicate commands.
+   * @param {string} projectDir - Project directory being installed to
+   * @returns {Promise<string|null>} Path to conflicting directory, or null if clean
+   */
+  async findAncestorConflict(projectDir) {
+    const targetDir = this.installerConfig?.target_dir;
+    if (!targetDir) return null;
+
+    const resolvedProject = await fs.realpath(path.resolve(projectDir));
+    let current = path.dirname(resolvedProject);
+    const root = path.parse(current).root;
+
+    while (current !== root && current.length > root.length) {
+      const candidatePath = path.join(current, targetDir);
+      try {
+        if (await fs.pathExists(candidatePath)) {
+          const entries = await fs.readdir(candidatePath);
+          const hasBmad = entries.some((e) => typeof e === 'string' && e.toLowerCase().startsWith('bmad'));
+          if (hasBmad) {
+            return candidatePath;
+          }
+        }
+      } catch {
+        // Can't read directory — skip
+      }
+      current = path.dirname(current);
+    }
+
+    return null;
+  }
+
+  /**
+   * Walk up ancestor directories from relativeDir toward projectDir, removing each if empty
    * Stops at projectDir boundary — never removes projectDir itself
    * @param {string} projectDir - Project root (boundary)
    * @param {string} relativeDir - Relative directory to start from
    */
   async removeEmptyParents(projectDir, relativeDir) {
+    const resolvedProject = path.resolve(projectDir);
     let current = relativeDir;
     let last = null;
     while (current && current !== '.' && current !== last) {
       last = current;
-      const fullPath = path.join(projectDir, current);
+      const fullPath = path.resolve(projectDir, current);
+      // Boundary guard: never traverse outside projectDir
+      if (!fullPath.startsWith(resolvedProject + path.sep) && fullPath !== resolvedProject) break;
       try {
-        if (!(await fs.pathExists(fullPath))) break;
+        if (!(await fs.pathExists(fullPath))) {
+          // Dir already gone — advance current; last is reset at top of next iteration
+          current = path.dirname(current);
+          continue;
+        }
         const remaining = await fs.readdir(fullPath);
         if (remaining.length > 0) break;
         await fs.rmdir(fullPath);
-      } catch {
-        break;
+      } catch (error) {
+        // ENOTEMPTY: TOCTOU race (file added between readdir and rmdir) — skip level, continue upward
+        // ENOENT: dir removed by another process between pathExists and rmdir — skip level, continue upward
+        if (error.code === 'ENOTEMPTY' || error.code === 'ENOENT') {
+          current = path.dirname(current);
+          continue;
+        }
+        break; // fatal error (e.g. EACCES) — stop upward walk
       }
       current = path.dirname(current);
     }

package/tools/cli/installers/lib/ide/manager.js

@@ -206,7 +206,9 @@ class IdeManager {
         if (handlerResult.tools > 0) parts.push(`${handlerResult.tools} tools`);
         detail = parts.join(', ');
       }
-      return { success: true, ide: ideName, detail, handlerResult };
+      // Propagate handler's success status (default true for backward compat)
+      const success = handlerResult?.success !== false;
+      return { success, ide: ideName, detail, error: handlerResult?.error, handlerResult };
     } catch (error) {
       await prompts.log.error(`Failed to setup ${ideName}: ${error.message}`);
       return { success: false, ide: ideName, error: error.message };

package/tools/cli/installers/lib/ide/platform-codes.yaml

@@ -40,6 +40,7 @@ platforms:
     installer:
       target_dir: .claude/commands
       template_type: default
+      ancestor_conflict_check: true
 
   cline:
     name: "Cline"
@@ -131,11 +132,14 @@ platforms:
     category: ide
     description: "OpenCode terminal coding assistant"
     installer:
+      legacy_targets:
+        - .opencode/agent
+        - .opencode/command
       targets:
-        - target_dir: .opencode/agent
+        - target_dir: .opencode/agents
           template_type: opencode
           artifact_types: [agents]
-        - target_dir: .opencode/command
+        - target_dir: .opencode/commands
           template_type: opencode
           artifact_types: [workflows, tasks, tools]
 
@@ -191,12 +195,17 @@ platforms:
 #   template_type: string                 # Default template type to use
 #   header_template: string (optional)    # Override for header/frontmatter template
 #   body_template: string (optional)      # Override for body/content template
+#   legacy_targets: array (optional)      # Old target dirs to clean up on reinstall (migration)
+#     - string                            # Relative path, e.g. .opencode/agent
 #   targets: array (optional)             # For multi-target installations
 #     - target_dir: string
 #       template_type: string
 #       artifact_types: [agents, workflows, tasks, tools]
 #   artifact_types: array (optional)      # Filter which artifacts to install (default: all)
 #   skip_existing: boolean (optional)     # Skip files that already exist (default: false)
+#   ancestor_conflict_check: boolean (optional) # Refuse install when ancestor dir has BMAD files
+#                                                # in the same target_dir (for IDEs that inherit
+#                                                # commands from parent directories)
 
 # ============================================================================
 # Platform Categories

package/tools/cli/installers/lib/ide/templates/agent-command-template.md

@@ -6,7 +6,7 @@ description: '{{description}}'
 You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
 
 <agent-activation CRITICAL="TRUE">
-1. LOAD the FULL agent file from @_bmad/{{module}}/agents/{{path}}
+1. LOAD the FULL agent file from {project-root}/_bmad/{{module}}/agents/{{path}}
 2. READ its entire contents - this contains the complete agent persona, menu, and instructions
 3. Execute ALL activation steps exactly as written in the agent file
 4. Follow the agent's persona and menu system precisely

package/tools/cli/installers/lib/ide/templates/combined/default-workflow-yaml.md

@@ -6,9 +6,9 @@ description: '{{description}}'
 IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
 
 <steps CRITICAL="TRUE">
-1. Always LOAD the FULL @{project-root}/{{bmadFolderName}}/core/tasks/workflow.xml
-2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @{project-root}/{{bmadFolderName}}/{{path}}
-3. Pass the yaml path @{project-root}/{{bmadFolderName}}/{{path}} as 'workflow-config' parameter to the workflow.xml instructions
+1. Always LOAD the FULL {project-root}/{{bmadFolderName}}/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config {project-root}/{{bmadFolderName}}/{{path}}
+3. Pass the yaml path {project-root}/{{bmadFolderName}}/{{path}} as 'workflow-config' parameter to the workflow.xml instructions
 4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
 5. Save outputs after EACH section when generating any documents from templates
 </steps>

package/tools/cli/installers/lib/ide/templates/combined/default-workflow.md

@@ -3,4 +3,4 @@ name: '{{name}}'
 description: '{{description}}'
 ---
 
-IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: LOAD the FULL @{project-root}/{{bmadFolderName}}/{{path}}, READ its entire contents and follow its directions exactly!
+IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: LOAD the FULL {project-root}/{{bmadFolderName}}/{{path}}, READ its entire contents and follow its directions exactly!

package/tools/cli/installers/lib/ide/templates/combined/gemini-workflow-yaml.toml

@@ -1,4 +1,4 @@
-description = """{{description}}"""
+description = '{{description}}'
 prompt = """
 Execute the BMAD '{{name}}' workflow.
 

package/tools/cli/installers/lib/ide/templates/combined/gemini-workflow.toml

@@ -1,4 +1,4 @@
-description = """{{description}}"""
+description = '{{description}}'
 prompt = """
 Execute the BMAD '{{name}}' workflow.
 

package/tools/cli/installers/lib/ide/templates/combined/opencode-agent.md

@@ -1,5 +1,5 @@
 ---
-name: '{{name}}'
+mode: all
 description: '{{description}}'
 ---
 

package/tools/cli/installers/lib/ide/templates/combined/opencode-task.md

@@ -1,5 +1,4 @@
 ---
-name: '{{name}}'
 description: '{{description}}'
 ---
 

package/tools/cli/installers/lib/ide/templates/combined/opencode-tool.md

@@ -1,5 +1,4 @@
 ---
-name: '{{name}}'
 description: '{{description}}'
 ---
 

package/tools/cli/installers/lib/ide/templates/combined/opencode-workflow-yaml.md

@@ -1,5 +1,4 @@
 ---
-name: '{{name}}'
 description: '{{description}}'
 ---
 

package/tools/cli/installers/lib/ide/templates/combined/opencode-workflow.md

@@ -1,5 +1,4 @@
 ---
-name: '{{name}}'
 description: '{{description}}'
 ---
 

package/tools/cli/installers/lib/ide/templates/workflow-command-template.md

@@ -5,8 +5,8 @@ description: '{{description}}'
 IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
 
 <steps CRITICAL="TRUE">
-1. Always LOAD the FULL @_bmad/core/tasks/workflow.xml
-2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @{{workflow_path}}
+1. Always LOAD the FULL {project-root}/_bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config {project-root}/{{workflow_path}}
 3. Pass the yaml path {{workflow_path}} as 'workflow-config' parameter to the workflow.xml instructions
 4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
 5. Save outputs after EACH section when generating any documents from templates

package/tools/cli/installers/lib/ide/templates/workflow-commander.md

@@ -2,4 +2,4 @@
 description: '{{description}}'
 ---
 
-IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: LOAD the FULL @{{workflow_path}}, READ its entire contents and follow its directions exactly!
+IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: LOAD the FULL {project-root}/{{workflow_path}}, READ its entire contents and follow its directions exactly!