Merge 1ee10ddcab into 5ad35d68bd

Add all changes since v6.0.2 including new root-cause-analysis skill,
installer fixes, workflow fixes, and documentation updates.

Also standardize quotes in remaining task/workflow files.

.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.

.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} | |
+```

CHANGELOG.md

@@ -2,9 +2,26 @@
 
 ## [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)
 
 ---
 

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.
 
@@ -62,7 +62,7 @@ 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        |
 

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-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "bmad-method",
-  "version": "6.0.2",
+  "version": "6.0.3",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "bmad-method",
-      "version": "6.0.2",
+      "version": "6.0.3",
       "license": "MIT",
       "dependencies": {
         "@clack/core": "^1.0.0",

package.json

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

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

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
 ---
 

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

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 {
+      } catch (error) {
-        break;
+        // 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);
     }

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 };

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

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

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

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

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

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

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

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

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

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

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