Merge 45eb74afb9 into 3dd37bc94d

The agent.customize.template.yaml defines principles as an array
(principles: []), and qa.agent.yaml correctly follows this. All other
agent files used a block scalar string (principles: |) which parsed as
a string instead of an array, breaking downstream YAML consumers that
expect the template-defined type.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.claude/skills/bmad-os-diataxis-style-fix/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: bmad-os-diataxis-style-fix
+description: Fixes documentation to comply with Diataxis framework and BMad Method style guide rules
+disable-model-invocation: true
+---
+
+Read `prompts/instructions.md` and execute.

.claude/skills/bmad-os-diataxis-style-fix/prompts/instructions.md

@@ -0,0 +1,229 @@
+# Diataxis Style Fixer
+
+Automatically fixes documentation to comply with the Diataxis framework and BMad Method style guide.
+
+## CRITICAL RULES
+
+- **NEVER commit or push changes** — let the user review first
+- **NEVER make destructive edits** — preserve all content, only fix formatting
+- **Use Edit tool** — make targeted fixes, not full file rewrites
+- **Show summary** — after fixing, list all changes made
+
+## Input
+
+Documentation file path or directory to fix. Defaults to `docs/` if not specified.
+
+## Step 1: Understand Diataxis Framework
+
+**Diataxis** is a documentation framework that categorizes content into four types based on two axes:
+
+|                | **Learning** (oriented toward future)                                         | **Doing** (oriented toward present)                                          |
+| -------------- | ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| **Practical**  | **Tutorials** — lessons that guide learners through achieving a specific goal | **How-to guides** — step-by-step instructions for solving a specific problem |
+| **Conceptual** | **Explanation** — content that clarifies and describes underlying concepts    | **Reference** — technical descriptions, organized for lookup                 |
+
+**Key principles:**
+- Each document type serves a distinct user need
+- Don't mix types — a tutorial shouldn't explain concepts deeply
+- Focus on the user's goal, not exhaustive coverage
+- Structure follows purpose (tutorials are linear, reference is scannable)
+
+## Step 2: Read the Style Guide
+
+Read the project's style guide at `docs/_STYLE_GUIDE.md` to understand all project-specific conventions.
+
+## Step 3: Detect Document Type
+
+Based on file location, determine the document type:
+
+| Location             | Diataxis Type        |
+| -------------------- | -------------------- |
+| `/docs/tutorials/`   | Tutorial             |
+| `/docs/how-to/`      | How-to guide         |
+| `/docs/explanation/` | Explanation          |
+| `/docs/reference/`   | Reference            |
+| `/docs/glossary/`    | Reference (glossary) |
+
+## Step 4: Find and Fix Issues
+
+For each markdown file, scan for issues and fix them:
+
+### Universal Fixes (All Doc Types)
+
+**Horizontal Rules (`---`)**
+- Remove any `---` outside of YAML frontmatter
+- Replace with `##` section headers or admonitions as appropriate
+
+**`####` Headers**
+- Replace with bold text: `#### Header` → `**Header**`
+- Or convert to admonition if it's a warning/notice
+
+**"Related" or "Next:" Sections**
+- Remove entire section including links
+- The sidebar handles navigation
+
+**Deeply Nested Lists**
+- Break into sections with `##` headers
+- Flatten to max 3 levels
+
+**Code Blocks for Dialogue/Examples**
+- Convert to admonitions:
+  ```
+  :::note[Example]
+  [content]
+  :::
+  ```
+
+**Bold Paragraph Callouts**
+- Convert to admonitions with appropriate type
+
+**Too Many Admonitions**
+- Limit to 1-2 per section (tutorials allow 3-4 per major section)
+- Consolidate related admonitions
+- Remove less critical ones if over limit
+
+**Table Cells / List Items > 2 Sentences**
+- Break into multiple rows/cells
+- Or shorten to 1-2 sentences
+
+**Header Budget Exceeded**
+- Merge related sections
+- Convert some `##` to `###` subsections
+- Goal: 8-12 `##` per doc; 2-3 `###` per section
+
+### Type-Specific Fixes
+
+**Tutorials** (`/docs/tutorials/`)
+- Ensure hook describes outcome in 1-2 sentences
+- Add "What You'll Learn" bullet section if missing
+- Add `:::note[Prerequisites]` if missing
+- Add `:::tip[Quick Path]` TL;DR at top if missing
+- Use tables for phases, commands, agents
+- Add "What You've Accomplished" section if missing
+- Add Quick Reference table if missing
+- Add Common Questions section if missing
+- Add Getting Help section if missing
+- Add `:::tip[Key Takeaways]` at end if missing
+
+**How-To** (`/docs/how-to/`)
+- Ensure hook starts with "Use the `X` workflow to..."
+- Add "When to Use This" with 3-5 bullets if missing
+- Add `:::note[Prerequisites]` if missing
+- Ensure steps are numbered `###` with action verbs
+- Add "What You Get" describing outputs if missing
+
+**Explanation** (`/docs/explanation/`)
+- Ensure hook states what document explains
+- Organize content into scannable `##` sections
+- Add comparison tables for 3+ options
+- Link to how-to guides for procedural questions
+- Limit to 2-3 admonitions per document
+
+**Reference** (`/docs/reference/`)
+- Ensure hook states what document references
+- Ensure structure matches reference type
+- Use consistent item structure throughout
+- Use tables for structured/comparative data
+- Link to explanation docs for conceptual depth
+- Limit to 1-2 admonitions per document
+
+**Glossary** (`/docs/glossary/` or glossary files)
+- Ensure categories as `##` headers
+- Ensure terms in tables (not individual headers)
+- Definitions 1-2 sentences max
+- Bold term names in cells
+
+## Step 5: Apply Fixes
+
+For each file with issues:
+1. Read the file
+2. Use Edit tool for each fix
+3. Track what was changed
+
+## Step 6: Summary
+
+After processing all files, output a summary:
+
+```markdown
+# Style Fixes Applied
+
+**Files processed:** N
+**Files modified:** N
+
+## Changes Made
+
+### `path/to/file.md`
+- Removed horizontal rule at line 45
+- Converted `####` headers to bold text
+- Added `:::tip[Quick Path]` admonition
+- Consolidated 3 admonitions into 2
+
+### `path/to/other.md`
+- Removed "Related:" section
+- Fixed table cell length (broke into 2 rows)
+
+## Review Required
+
+Please review the changes. When satisfied, commit and push as needed.
+```
+
+## Common Patterns
+
+**Converting `####` to bold:**
+```markdown
+#### Important Note
+Some text here.
+```
+→
+```markdown
+**Important Note**
+
+Some text here.
+```
+
+**Removing horizontal rule:**
+```markdown
+Some content above.
+
+---
+
+Some content below.
+```
+→
+```markdown
+Some content above.
+
+## [Descriptive Section Header]
+
+Some content below.
+```
+
+**Converting code block to admonition:**
+```markdown
+```
+User: What should I do?
+
+Agent: Run the workflow.
+```
+```
+→
+```markdown
+:::note[Example]
+
+**User:** What should I do?
+
+**Agent:** Run the workflow.
+
+:::
+```
+
+**Converting bold paragraph to admonition:**
+```markdown
+**IMPORTANT:** This is critical that you read this before proceeding.
+```
+→
+```markdown
+:::caution[Important]
+This is critical that you read this before proceeding.
+:::
+```

CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## [6.0.0]
+
+V6 Stable Release! The End of Beta!
+
+### 🎁 Features
+
+* Add PRD workflow steps 2b (vision/differentiators) and 2c (executive summary) for more complete product requirements documentation
+* Add new `bmad uninstall` command with interactive and non-interactive modes for selective component removal
+* Add dedicated GitHub Copilot installer that generates enriched `.agent.md`, `.prompt.md` files and project configuration
+* Add TEA browser automation prerequisite prompts to guide Playwright CLI/MCP setup after configuration
+
+### 🐛 Bug Fixes
+
+* Fix version comparison to use semantic versioning, preventing incorrect downgrade recommendations to older beta versions
+* Fix `--custom-content` flag to properly populate sources and selected files in module config
+* Fix module configuration UX messaging to show accurate completion status and improve feedback timing
+* Fix changelog URL in installer start message for proper GitHub resolution
+* Remove incorrect `mode: primary` from OpenCode agent template and restore `name` field across all templates
+* Auto-discover PRD files in validate-prd workflow to reduce manual path input
+* Fix installer non-interactive mode hanging and improve IDE configuration handling during updates
+* Fix workflow-level config.yaml copying for custom content modules
+
+### ♻️ Refactoring
+
+* Remove alias variables from Phase 4 workflows, use canonical `{implementation_artifacts}` and `{planning_artifacts}`
+* Add missing `project_context` references to workflows for consistency
+
+### 📚 Documentation
+
+* Add post-install notes documentation for modules
+* Improve project-context documentation and fix folder structure
+* Add BMad Builder link to index for extenders
+
+---
+
 ## [6.0.0-Beta.8]
 
 **Release: February 8, 2026**

CONTRIBUTING.md

@@ -73,7 +73,7 @@ After searching, use the [feature request template](https://github.com/bmad-code
 
 ### Target Branch
 
-Submit PRs to the `main` branch.
+Submit PRs to the `main` branch. We use [trunk-based development](https://trunkbaseddevelopment.com/branch-for-release/): `main` is the trunk where all work lands, and stable release branches receive only cherry-picked fixes.
 
 ### PR Size
 

README.md

@@ -5,20 +5,22 @@
 [![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 framework with 21 specialized agents, 50+ guided workflows, and scale-adaptive intelligence that adjusts from bug fixes to enterprise systems.
+**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.
 
-**100% free and open source.** No paywalls. No gated content. No gated Discord. We believe in empowering everyone, not just those who can pay.
+**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.
 
-## Why BMad?
+## Why the BMad Method?
 
-Traditional AI tools do the thinking for you, producing average results. BMad agents and facilitated workflow act as expert collaborators who guide you through a structured process to bring out your best thinking in partnership with the AI.
+Traditional AI tools do the thinking for you, producing average results. BMad agents and facilitated workflows act as expert collaborators who guide you through a structured process to bring out your best thinking in partnership with the AI.
 
-- **AI Intelligent Help**: Brand new for beta - AI assisted help will guide you from the beginning to the end - just ask for `/bmad-help` after you have installed BMad to your project
-- **Scale-Domain-Adaptive**: Automatically adjusts planning depth and needs based on project complexity, domain and type - a SaaS Mobile Dating App has different planning needs from a diagnostic medical system, BMad adapts and helps you along the way
-- **Structured Workflows**: Grounded in agile best practices across analysis, planning, architecture, and implementation
-- **Specialized Agents**: 12+ domain experts (PM, Architect, Developer, UX, Scrum Master, and more)
-- **Party Mode**: Bring multiple agent personas into one session to plan, troubleshoot, or discuss your project collaboratively, multiple perspectives with maximum fun
-- **Complete Lifecycle**: From brainstorming to deployment, BMad is there with you every step of the way
+- **AI Intelligent Help** — Ask `/bmad-help` anytime for guidance on what's next
+- **Scale-Domain-Adaptive** — Automatically adjusts planning depth based on project complexity
+- **Structured Workflows** — Grounded in agile best practices across analysis, planning, architecture, and implementation
+- **Specialized Agents** — 12+ domain experts (PM, Architect, Developer, UX, Scrum Master, and more)
+- **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)
 
 ## Quick Start
 
@@ -28,103 +30,41 @@ Traditional AI tools do the thinking for you, producing average results. BMad ag
 npx bmad-method install
 ```
 
-Follow the installer prompts, then open your AI IDE (Claude Code, Cursor, Windsurf, etc.) in the project folder.
+> If you are getting a stale beta version, use: `npx bmad-method@6.0.1 install`
 
-**Non-Interactive Installation**: For CI/CD pipelines or automated deployments, use command-line flags:
+Follow the installer prompts, then open your AI IDE (Claude Code, Codex, Windsurf, etc.) in your project folder.
+
+**Non-Interactive Installation** (for CI/CD):
 
 ```bash
 npx bmad-method install --directory /path/to/project --modules bmm --tools claude-code --yes
 ```
 
-See [Non-Interactive Installation Guide](http://docs.bmad-method.org/how-to/non-interactive-installation/) for all available options.
+[See all installation options](http://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 it questions like:
-
- - `/bmad-help How should I build a web app for my TShirt Business that can scale to millions?`
- - `/bmad-help I just finished the architecture, I am not sure what to do next`
-
-And the amazing thing is BMad Help evolves depending on what modules you install also!
- - `/bmad-help Im interested in really exploring creative ways to demo BMad at work, what do you recommend to help plan a great slide deck and compelling narrative?`, and if you have the Creative Intelligence Suite installed, it will offer you different or complimentary advice than if you just have BMad Method Module installed!
-
-The workflows below show the fastest path to working code. You can also load agents directly for a more structured process, extensive planning, or to learn about agile development practices — the agents guide you with menus, explanations, and elicitation at each step.
-
-### Simple Path (Quick Flow)
-
-Bug fixes, small features, clear scope — 3 commands - 1 Optional Agent:
-
-1. `/quick-spec` — analyzes your codebase and produces a tech-spec with stories
-2. `/dev-story` — implements each story
-3. `/code-review` — validates quality
-
-### Full Planning Path (BMad Method)
-
-Products, platforms, complex features — structured planning then build:
-
-1. `/product-brief` — define problem, users, and MVP scope
-2. `/create-prd` — full requirements with personas, metrics, and risks
-3. `/create-architecture` — technical decisions and system design
-4. `/create-epics-and-stories` — break work into prioritized stories
-5. `/sprint-planning` — initialize sprint tracking
-6. **Repeat per story:** `/create-story` → `/dev-story` → `/code-review`
-
-Every step tells you what's next. Optional phases (brainstorming, research, UX design) are available when you need them — ask `/bmad-help` anytime. For a detailed walkthrough, see the [Getting Started Tutorial](http://docs.bmad-method.org/tutorials/getting-started/).
+> **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?`
 
 ## Modules
 
-BMad Method extends with official modules for specialized domains. Modules are available during installation and can be added to your project at any time. After the V6 beta period these will also be available as Plugins and Granular Skills.
+BMad Method extends with official modules for specialized domains. Available during installation or anytime after.
 
-| Module                                | GitHub                                                                                                                            | NPM                                                                                                | Purpose                                                               |
-| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
-| **BMad Method (BMM)**                 | [bmad-code-org/BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD)                                                         | [bmad-method](https://www.npmjs.com/package/bmad-method)                                           | Core framework with 34+ workflows across 4 development phases         |
-| **BMad Builder (BMB)**                | [bmad-code-org/bmad-builder](https://github.com/bmad-code-org/bmad-builder)                                                       | [bmad-builder](https://www.npmjs.com/package/bmad-builder)                                         | Create custom BMad agents, workflows, and domain-specific modules     |
-| **Test Architect (TEA)** 🆕            | [bmad-code-org/tea](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise)                                    | [tea](https://www.npmjs.com/package/bmad-method-test-architecture-enterprise)                      | Risk-based test strategy, automation, and release gates (8 workflows) |
-| **Game Dev Studio (BMGD)**            | [bmad-code-org/bmad-module-game-dev-studio](https://github.com/bmad-code-org/bmad-module-game-dev-studio)                         | [bmad-game-dev-studio](https://www.npmjs.com/package/bmad-game-dev-studio)                         | Game development workflows for Unity, Unreal, and Godot               |
-| **Creative Intelligence Suite (CIS)** | [bmad-code-org/bmad-module-creative-intelligence-suite](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite) | [bmad-creative-intelligence-suite](https://www.npmjs.com/package/bmad-creative-intelligence-suite) | Innovation, brainstorming, design thinking, and problem-solving       |
-
-* More modules are coming in the next 2 weeks from BMad Official, and a community marketplace for the installer also will be coming with the final V6 release!
-
-## Testing Agents
-
-BMad provides two testing options to fit your needs:
-
-### Quinn (QA) - Built-in
-
-**Quick test automation for rapid coverage**
-
-- ✅ **Always available** in BMM module (no separate install)
-- ✅ **Simple**: One workflow (`QA` - Automate)
-- ✅ **Beginner-friendly**: Standard test framework patterns
-- ✅ **Fast**: Generate tests and ship
-
-**Use Quinn for:** Small projects, quick coverage, standard patterns
-
-### Test Architect (TEA) - Optional Module
-
-**Enterprise-grade test strategy and quality engineering**
-
-- 🆕 **Standalone module** (install separately)
-- 🏗️ **Comprehensive**: 8 workflows covering full test lifecycle
-- 🎯 **Advanced**: Risk-based planning, quality gates, NFR assessment
-- 📚 **Knowledge-driven**: 34 testing patterns and best practices
-- 📖 [Test Architect Documentation](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/)
-
-**Use TEA for:** Enterprise projects, test strategy, compliance, release gates
-
----
+| Module                                                                                                            | Purpose                                           |
+| ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
+| **[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           |
+| **[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 Documentation](http://docs.bmad-method.org)** — Tutorials, how-to guides, concepts, and reference
-**[Test Architect Documentation](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/)** — TEA standalone module documentation
+[BMad Method Docs Site](http://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/)
-- [Test Architect Migration Guide](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/migration/) — Upgrading from BMM-embedded TEA
+- [Test Architect Documentation](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/)
 
-### For v4 Users
-
-- **[v4 Documentation](https://github.com/bmad-code-org/BMAD-METHOD/tree/V4/docs)**
-- If you need to install V4, you can do this with  `npx bmad-method@4.44.3 install` - similar for any past version.
 
 ## Community
 

docs/_STYLE_GUIDE.md

@@ -77,8 +77,10 @@ Show in "What You've Accomplished" sections:
 your-project/
 ├── _bmad/                                   # BMad configuration
 ├── _bmad-output/
-│   ├── PRD.md                     # Your requirements document
-│   └── bmm-workflow-status.yaml   # Progress tracking
+│   ├── planning-artifacts/
+│   │   └── PRD.md                           # Your requirements document
+│   ├── implementation-artifacts/
+│   └── project-context.md                   # Implementation rules (optional)
 └── ...
 ```
 ````
@@ -143,7 +145,7 @@ your-project/
 ### Types
 
 | Type              | Example                       |
-| ----------------- | ---------------------------- |
+| ----------------- | ----------------------------- |
 | **Index/Landing** | `core-concepts/index.md`      |
 | **Concept**       | `what-are-agents.md`          |
 | **Feature**       | `quick-flow.md`               |

docs/explanation/project-context.md

@@ -0,0 +1,157 @@
+---
+title: "Project Context"
+description: How project-context.md guides AI agents with your project's rules and preferences
+sidebar:
+  order: 7
+---
+
+The `project-context.md` file is your project's implementation guide for AI agents. Similar to a "constitution" in other development systems, it captures the rules, patterns, and preferences that ensure consistent code generation across all workflows.
+
+## What It Does
+
+AI agents make implementation decisions constantly — which patterns to follow, how to structure code, what conventions to use. Without clear guidance, they may:
+- Follow generic best practices that don't match your codebase
+- Make inconsistent decisions across different stories
+- Miss project-specific requirements or constraints
+
+The `project-context.md` file solves this by documenting what agents need to know in a concise, LLM-optimized format.
+
+## How It Works
+
+Every implementation workflow automatically loads `project-context.md` if it exists. The architect workflow also loads it to respect your technical preferences when designing the architecture.
+
+**Loaded by these workflows:**
+- `create-architecture` — respects technical preferences during solutioning
+- `create-story` — informs story creation with project patterns
+- `dev-story` — guides implementation decisions
+- `code-review` — validates against project standards
+- `quick-dev` — applies patterns when implementing tech-specs
+- `sprint-planning`, `retrospective`, `correct-course` — provides project-wide context
+
+## When to Create It
+
+The `project-context.md` file is useful at any stage of a project:
+
+| Scenario | When to Create | Purpose |
+|----------|----------------|---------|
+| **New project, before architecture** | Manually, before `create-architecture` | Document your technical preferences so the architect respects them |
+| **New project, after architecture** | Via `generate-project-context` or manually | Capture architecture decisions for implementation agents |
+| **Existing project** | Via `generate-project-context` | Discover existing patterns so agents follow established conventions |
+| **Quick Flow project** | Before or during `quick-dev` | Ensure quick implementation respects your patterns |
+
+:::tip[Recommended]
+For new projects, create it manually before architecture if you have strong technical preferences. Otherwise, generate it after architecture to capture those decisions.
+:::
+
+## What Goes In It
+
+The file has two main sections:
+
+### Technology Stack & Versions
+
+Documents the frameworks, languages, and tools your project uses with specific versions:
+
+```markdown
+## Technology Stack & Versions
+
+- Node.js 20.x, TypeScript 5.3, React 18.2
+- State: Zustand (not Redux)
+- Testing: Vitest, Playwright, MSW
+- Styling: Tailwind CSS with custom design tokens
+```
+
+### Critical Implementation Rules
+
+Documents patterns and conventions that agents might otherwise miss:
+
+```markdown
+## Critical Implementation Rules
+
+**TypeScript Configuration:**
+- Strict mode enabled — no `any` types without explicit approval
+- Use `interface` for public APIs, `type` for unions/intersections
+
+**Code Organization:**
+- Components in `/src/components/` with co-located `.test.tsx`
+- Utilities in `/src/lib/` for reusable pure functions
+- API calls use the `apiClient` singleton — never fetch directly
+
+**Testing Patterns:**
+- Unit tests focus on business logic, not implementation details
+- Integration tests use MSW to mock API responses
+- E2E tests cover critical user journeys only
+
+**Framework-Specific:**
+- All async operations use the `handleError` wrapper for consistent error handling
+- Feature flags accessed via `featureFlag()` from `@/lib/flags`
+- New routes follow the file-based routing pattern in `/src/app/`
+```
+
+Focus on what's **unobvious** — things agents might not infer from reading code snippets. Don't document standard practices that apply universally.
+
+## Creating the File
+
+You have three options:
+
+### Manual Creation
+
+Create the file at `_bmad-output/project-context.md` and add your rules:
+
+```bash
+# In your project root
+mkdir -p _bmad-output
+touch _bmad-output/project-context.md
+```
+
+Edit it with your technology stack and implementation rules. The architect and implementation workflows will automatically find and load it.
+
+### Generate After Architecture
+
+Run the `generate-project-context` workflow after completing your architecture:
+
+```bash
+/bmad-bmm-generate-project-context
+```
+
+This scans your architecture document and project files to generate a context file capturing the decisions made.
+
+### Generate for Existing Projects
+
+For existing projects, run `generate-project-context` to discover existing patterns:
+
+```bash
+/bmad-bmm-generate-project-context
+```
+
+The workflow analyzes your codebase to identify conventions, then generates a context file you can review and refine.
+
+## Why It Matters
+
+Without `project-context.md`, agents make assumptions that may not match your project:
+
+| Without Context | With Context |
+|----------------|--------------|
+| Uses generic patterns | Follows your established conventions |
+| Inconsistent style across stories | Consistent implementation |
+| May miss project-specific constraints | Respects all technical requirements |
+| Each agent decides independently | All agents align with same rules |
+
+This is especially important for:
+- **Quick Flow** — skips PRD and architecture, so context file fills the gap
+- **Team projects** — ensures all agents follow the same standards
+- **Existing projects** — prevents breaking established patterns
+
+## Editing and Updating
+
+The `project-context.md` file is a living document. Update it when:
+
+- Architecture decisions change
+- New conventions are established
+- Patterns evolve during implementation
+- You identify gaps from agent behavior
+
+You can edit it manually at any time, or re-run `generate-project-context` to update it after significant changes.
+
+:::note[File Location]
+The default location is `_bmad-output/project-context.md`. Workflows search for it there, and also check `**/project-context.md` anywhere in your project.
+:::

docs/how-to/customize-bmad.md

@@ -42,7 +42,7 @@ _bmad/_config/agents/
 Open the `.customize.yaml` file for the agent you want to modify. Every section is optional -- customize only what you need.
 
 | Section            | Behavior | Purpose                                         |
-| ------------------- | ------------ | ---------------------------------------------- |
+| ------------------ | -------- | ----------------------------------------------- |
 | `agent.metadata`   | Replaces | Override the agent's display name               |
 | `persona`          | Replaces | Set role, identity, style, and principles       |
 | `memories`         | Appends  | Add persistent context the agent always recalls |
@@ -96,7 +96,7 @@ Add custom entries to the agent's display menu. Each item needs a `trigger`, a t
 ```yaml
 menu:
   - trigger: my-workflow
-    workflow: '{project-root}/my-custom/workflows/my-workflow.yaml'
+    workflow: 'my-custom/workflows/my-workflow.yaml'
     description: My custom workflow
   - trigger: deploy
     action: '#deploy-prompt'
@@ -137,7 +137,7 @@ npx bmad-method install
 The installer detects the existing installation and offers these options:
 
 | Option                       | What It Does                                                        |
-| --------------------- | ------------------------------------------------------------------- |
+| ---------------------------- | ------------------------------------------------------------------- |
 | **Quick Update**             | Updates all modules to the latest version and recompiles all agents |
 | **Recompile Agents**         | Applies customizations only, without updating module files          |
 | **Modify BMad Installation** | Full installation flow for adding or removing modules               |

docs/how-to/established-projects.md

@@ -5,7 +5,7 @@ sidebar:
   order: 6
 ---
 
-Use BMad Method effectively when working on existing projects and legacy codebases, sometimes also referred to as brownfield projects.
+Use BMad Method effectively when working on existing projects and legacy codebases.
 
 This guide covers the essential workflow for onboarding to existing projects with BMad Method.
 
@@ -23,7 +23,30 @@ If you have completed all PRD epics and stories through the BMad process, clean
 - `_bmad-output/planning-artifacts/`
 - `_bmad-output/implementation-artifacts/`
 
-## Step 2: Maintain Quality Project Documentation
+## Step 2: Create Project Context
+
+:::tip[Recommended for Existing Projects]
+Generate `project-context.md` to capture your existing codebase patterns and conventions. This ensures AI agents follow your established practices when implementing changes.
+:::
+
+Run the generate project context workflow:
+
+```bash
+/bmad-bmm-generate-project-context
+```
+
+This scans your codebase to identify:
+- Technology stack and versions
+- Code organization patterns
+- Naming conventions
+- Testing approaches
+- Framework-specific patterns
+
+You can review and refine the generated file, or create it manually at `_bmad-output/project-context.md` if you prefer.
+
+[Learn more about project context](../explanation/project-context.md)
+
+## Step 3: Maintain Quality Project Documentation
 
 Your `docs/` folder should contain succinct, well-organized documentation that accurately represents your project:
 
@@ -36,9 +59,21 @@ For complex projects, consider using the `document-project` workflow. It offers
 
 ## Step 3: Get Help
 
-Get help to know what to do next based on your unique needs
+### BMad-Help: Your Starting Point
 
-Run `bmad-help` to get guidance when you are not sure what to do next.
+**Run `/bmad-help` anytime you're unsure what to do next.** This intelligent guide:
+
+- Inspects your project to see what's already been done
+- Shows options based on your installed modules
+- Understands natural language queries
+
+```
+/bmad-help I have an existing Rails app, where should I start?
+/bmad-help What's the difference between quick-flow and full method?
+/bmad-help Show me what workflows are available
+```
+
+BMad-Help also **automatically runs at the end of every workflow**, providing clear guidance on exactly what to do next.
 
 ### Choosing Your Approach
 

docs/how-to/get-answers-about-bmad.md

@@ -5,17 +5,48 @@ sidebar:
   order: 4
 ---
 
-If you have successfully installed BMad and the BMad Method (+ other modules as needed) - the first step in getting answers is `/bmad-help`. This will answer upwards of 80% of all questions and is available to you in the IDE as you are working.
+## Start Here: BMad-Help
 
-## When to Use This
+**The fastest way to get answers about BMad is `/bmad-help`.** This intelligent guide will answer upwards of 80% of all questions and is available to you directly in your IDE as you work.
 
-- You have a question about how BMad works or what to do next with BMad
-- You want to understand a specific agent or workflow
-- You need quick answers without waiting for Discord
+BMad-Help is more than a lookup tool — it:
+- **Inspects your project** to see what's already been completed
+- **Understands natural language** — ask questions in plain English
+- **Varies based on your installed modules** — shows relevant options
+- **Auto-runs after workflows** — tells you exactly what to do next
+- **Recommends the first required task** — no guessing where to start
 
-:::note[Prerequisites]
-An AI tool (Claude Code, Cursor, ChatGPT, Claude.ai, etc.) and either BMad installed in your project or access to the GitHub repo.
-:::
+### How to Use BMad-Help
+
+Run it with just the slash command:
+
+```
+/bmad-help
+```
+
+Or combine it with a natural language query:
+
+```
+/bmad-help I have a SaaS idea and know all the features. Where do I start?
+/bmad-help What are my options for UX design?
+/bmad-help I'm stuck on the PRD workflow
+/bmad-help Show me what's been done so far
+```
+
+BMad-Help responds with:
+- What's recommended for your situation
+- What the first required task is
+- What the rest of the process looks like
+
+---
+
+## When to Use This Guide
+
+Use this section when:
+- You want to understand BMad's architecture or internals
+- You need answers outside of what BMad-Help provides
+- You're researching BMad before installing
+- You want to explore the source code directly
 
 ## Steps
 

docs/how-to/install-bmad.md

@@ -79,7 +79,18 @@ your-project/
 
 ## Verify Installation
 
-Run the `help` workflow (`/bmad-help` on most platforms) to verify everything works and see what to do next.
+Run `/bmad-help` to verify everything works and see what to do next.
+
+**BMad-Help is your intelligent guide** that will:
+- Confirm your installation is working
+- Show what's available based on your installed modules
+- Recommend your first step
+
+You can also ask it questions:
+```
+/bmad-help I just installed, what should I do first?
+/bmad-help What are my options for a SaaS project?
+```
 
 ## Troubleshooting
 

docs/how-to/project-context.md

@@ -0,0 +1,136 @@
+---
+title: "Manage Project Context"
+description: Create and maintain project-context.md to guide AI agents
+sidebar:
+  order: 7
+---
+
+Use the `project-context.md` file to ensure AI agents follow your project's technical preferences and implementation rules throughout all workflows.
+
+:::note[Prerequisites]
+- BMad Method installed
+- Understanding of your project's technology stack and conventions
+:::
+
+## When to Use This
+
+- You have strong technical preferences before starting architecture
+- You've completed architecture and want to capture decisions for implementation
+- You're working on an existing codebase with established patterns
+- You notice agents making inconsistent decisions across stories
+
+## Step 1: Choose Your Approach
+
+**Manual creation** — Best when you know exactly what rules you want to document
+
+**Generate after architecture** — Best for capturing decisions made during solutioning
+
+**Generate for existing projects** — Best for discovering patterns in existing codebases
+
+## Step 2: Create the File
+
+### Option A: Manual Creation
+
+Create the file at `_bmad-output/project-context.md`:
+
+```bash
+mkdir -p _bmad-output
+touch _bmad-output/project-context.md
+```
+
+Add your technology stack and implementation rules:
+
+```markdown
+---
+project_name: 'MyProject'
+user_name: 'YourName'
+date: '2026-02-15'
+sections_completed: ['technology_stack', 'critical_rules']
+---
+
+# Project Context for AI Agents
+
+## Technology Stack & Versions
+
+- Node.js 20.x, TypeScript 5.3, React 18.2
+- State: Zustand
+- Testing: Vitest, Playwright
+- Styling: Tailwind CSS
+
+## Critical Implementation Rules
+
+**TypeScript:**
+- Strict mode enabled, no `any` types
+- Use `interface` for public APIs, `type` for unions
+
+**Code Organization:**
+- Components in `/src/components/` with co-located tests
+- API calls use `apiClient` singleton — never fetch directly
+
+**Testing:**
+- Unit tests focus on business logic
+- Integration tests use MSW for API mocking
+```
+
+### Option B: Generate After Architecture
+
+Run the workflow in a fresh chat:
+
+```bash
+/bmad-bmm-generate-project-context
+```
+
+The workflow scans your architecture document and project files to generate a context file capturing the decisions made.
+
+### Option C: Generate for Existing Projects
+
+For existing projects, run:
+
+```bash
+/bmad-bmm-generate-project-context
+```
+
+The workflow analyzes your codebase to identify conventions, then generates a context file you can review and refine.
+
+## Step 3: Verify Content
+
+Review the generated file and ensure it captures:
+
+- Correct technology versions
+- Your actual conventions (not generic best practices)
+- Rules that prevent common mistakes
+- Framework-specific patterns
+
+Edit manually to add anything missing or remove inaccuracies.
+
+## What You Get
+
+A `project-context.md` file that:
+
+- Ensures all agents follow the same conventions
+- Prevents inconsistent decisions across stories
+- Captures architecture decisions for implementation
+- Serves as a reference for your project's patterns and rules
+
+## Tips
+
+:::tip[Focus on the Unobvious]
+Document patterns agents might miss such as "Use JSDoc style comments on every public class, function and variable", not universal practices like "use meaningful variable names" which LLMs know at this point.
+:::
+
+:::tip[Keep It Lean]
+This file is loaded by every implementation workflow. Long files waste context. Do not include content that only applies to narrow scope or specific stories or features.
+:::
+
+:::tip[Update as Needed]
+Edit manually when patterns change, or re-generate after significant architecture changes.
+:::
+
+:::tip[Works for All Project Types]
+Just as useful for Quick Flow as for full BMad Method projects.
+:::
+
+## Next Steps
+
+- [**Project Context Explanation**](../explanation/project-context.md) — Learn more about how it works
+- [**Workflow Map**](../reference/workflow-map.md) — See which workflows load project context

docs/how-to/shard-large-documents.md

@@ -23,11 +23,11 @@ Document sharding splits large markdown files into smaller, organized files base
 
 ```text
 Before Sharding:
-docs/
+_bmad-output/planning-artifacts/
 └── PRD.md (large 50k token file)
 
 After Sharding:
-docs/
+_bmad-output/planning-artifacts/
 └── prd/
     ├── index.md                    # Table of contents with descriptions
     ├── overview.md                 # Section 1

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 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**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.
 
 If you're comfortable working with AI coding assistants like Claude, Cursor, or GitHub Copilot, you're ready to get started.
 
@@ -12,7 +12,11 @@ If you're comfortable working with AI coding assistants like Claude, Cursor, or
 The fastest way to understand BMad is to try it.
 
 - **[Get Started with BMad](./tutorials/getting-started.md)** — Install and understand how BMad works
-- **[Workflow Map](./reference/workflow-map.md)** — Visual overview of BMM phases, workflows, and context management.
+- **[Workflow Map](./reference/workflow-map.md)** — Visual overview of BMM phases, workflows, and context management
+
+:::tip[Just Want to Dive In?]
+Install BMad and run `/bmad-help` — it will guide you through everything based on your project and installed modules.
+:::
 
 ## How to Use These Docs
 
@@ -25,6 +29,10 @@ These docs are organized into four sections based on what you're trying to do:
 | **Explanation**   | Understanding-oriented. Deep dives into concepts and architecture. Read when you want to know *why*.       |
 | **Reference**     | Information-oriented. Technical specifications for agents, workflows, and configuration.                   |
 
+## Extend and Customize
+
+Want to expand BMad with your own agents, workflows, or modules? The **[BMad Builder](https://bmad-builder-docs.bmad-method.org/)** provides the framework and tools for creating custom extensions, whether you're adding new capabilities to BMad or building entirely new modules from scratch.
+
 ## What You'll Need
 
 BMad works with any AI coding assistant that supports custom system prompts or project context. Popular options include:

docs/reference/commands.md

@@ -103,9 +103,29 @@ See [Workflow Map](./workflow-map.md) for the complete workflow reference organi
 
 Tasks and tools are standalone operations that do not require an agent or workflow context.
 
+#### BMad-Help: Your Intelligent Guide
+
+**`/bmad-help`** is your primary interface for discovering what to do next. It's not just a lookup tool — it's an intelligent assistant that:
+
+- **Inspects your project** to see what's already been done
+- **Understands natural language queries** — ask questions in plain English
+- **Varies by installed modules** — shows options based on what you have
+- **Auto-invokes after workflows** — every workflow ends with clear next steps
+- **Recommends the first required task** — no guessing where to start
+
+**Examples:**
+
+```
+/bmad-help
+/bmad-help I have a SaaS idea and know all the features. Where do I start?
+/bmad-help What are my options for UX design?
+/bmad-help I'm stuck on the PRD workflow
+```
+
+#### Other Tasks and Tools
+
 | Example command | Purpose |
 | --- | --- |
-| `/bmad-help` | Context-aware guidance and next-step recommendations |
 | `/bmad-shard-doc` | Split a large markdown file into smaller sections |
 | `/bmad-index-docs` | Index project documentation |
 | `/bmad-editorial-review-prose` | Review document prose quality |

docs/reference/workflow-map.md

@@ -24,67 +24,66 @@ Final important note: Every workflow below can be run directly with your tool of
 Explore the problem space and validate ideas before committing to planning.
 
 | Workflow                        | Purpose                                                                    | Produces                  |
-| ---------------------- | -------------------------------------------------------------------------- | ------------------------- |
-| `brainstorming`        | Brainstorm Project Ideas with guided facilitation of a brainstorming coach | `brainstorming-report.md` |
-| `research`             | Validate market, technical, or domain assumptions                          | Research findings         |
-| `create-product-brief` | Capture strategic vision                                                   | `product-brief.md`        |
+| ------------------------------- | -------------------------------------------------------------------------- | ------------------------- |
+| `bmad-brainstorming`            | Brainstorm Project Ideas with guided facilitation of a brainstorming coach | `brainstorming-report.md` |
+| `bmad-bmm-research`             | Validate market, technical, or domain assumptions                          | Research findings         |
+| `bmad-bmm-create-product-brief` | Capture strategic vision                                                   | `product-brief.md`        |
 
 ## Phase 2: Planning
 
 Define what to build and for whom.
 
 | Workflow                    | Purpose                                  | Produces     |
-| ------------------ | ---------------------------------------- | ------------ |
-| `create-prd`       | Define requirements (FRs/NFRs)           | `PRD.md`     |
-| `create-ux-design` | Design user experience (when UX matters) | `ux-spec.md` |
+| --------------------------- | ---------------------------------------- | ------------ |
+| `bmad-bmm-create-prd`       | Define requirements (FRs/NFRs)           | `PRD.md`     |
+| `bmad-bmm-create-ux-design` | Design user experience (when UX matters) | `ux-spec.md` |
 
 ## Phase 3: Solutioning
 
 Decide how to build it and break work into stories.
 
 | Workflow                                  | Purpose                                    | Produces                    |
-| -------------------------------- | ------------------------------------------ | --------------------------- |
-| `create-architecture`            | Make technical decisions explicit          | `architecture.md` with ADRs |
-| `create-epics-and-stories`       | Break requirements into implementable work | Epic files with stories     |
-| `check-implementation-readiness` | Gate check before implementation           | PASS/CONCERNS/FAIL decision |
+| ----------------------------------------- | ------------------------------------------ | --------------------------- |
+| `bmad-bmm-create-architecture`            | Make technical decisions explicit          | `architecture.md` with ADRs |
+| `bmad-bmm-create-epics-and-stories`       | Break requirements into implementable work | Epic files with stories     |
+| `bmad-bmm-check-implementation-readiness` | Gate check before implementation           | PASS/CONCERNS/FAIL decision |
 
 ## Phase 4: Implementation
 
-Build it, one story at a time.
+Build it, one story at a time. Coming soon, full phase 4 automation!
 
 | Workflow                   | Purpose                                                                  | Produces                         |
-| ----------------- | -------------------------------------- | ----------------------------- |
-| `sprint-planning` | Initialize tracking (once per project) | `sprint-status.yaml`          |
-| `create-story`    | Prepare next story for implementation  | `story-[slug].md`             |
-| `dev-story`       | Implement the story                    | Working code + tests          |
-| `automate` (QA)   | Generate tests for existing features   | Test suite                    |
-| `code-review`     | Validate implementation quality        | Approved or changes requested |
-| `correct-course`  | Handle significant mid-sprint changes  | Updated plan or re-routing    |
-| `retrospective`   | Review after epic completion           | Lessons learned               |
-
-**Quinn (QA Agent):** Built-in QA agent for test automation. Trigger with `QA` or `bmad-bmm-qa-automate`. Generates standard API and E2E tests using your project's test framework. Beginner-friendly, no configuration needed. For advanced test strategy, install [Test Architect (TEA)](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/) module.
+| -------------------------- | ------------------------------------------------------------------------ | -------------------------------- |
+| `bmad-bmm-sprint-planning` | Initialize tracking (once per project to sequence the dev cycle)         | `sprint-status.yaml`             |
+| `bmad-bmm-create-story`    | Prepare next story for implementation                                    | `story-[slug].md`                |
+| `bmad-bmm-dev-story`       | Implement the story                                                      | Working code + tests             |
+| `bmad-bmm-code-review`     | Validate implementation quality                                          | Approved or changes requested    |
+| `bmad-bmm-correct-course`  | Handle significant mid-sprint changes                                    | Updated plan or re-routing       |
+| `bmad-bmm-automate`        | Generate tests for existing features - Use after a full epic is complete | End to End UI Focused Test suite |
+| `bmad-bmm-retrospective`   | Review after epic completion                                             | Lessons learned                  |
 
 ## Quick Flow (Parallel Track)
 
 Skip phases 1-3 for small, well-understood work.
 
 | Workflow              | Purpose                                    | Produces                                      |
-| ------------ | ------------------------------------------ | --------------------------------------------- |
-| `quick-spec` | Define an ad-hoc change                    | `tech-spec.md` (story file for small changes) |
-| `quick-dev`  | Implement from spec or direct instructions | Working code + tests                          |
+| --------------------- | ------------------------------------------ | --------------------------------------------- |
+| `bmad-bmm-quick-spec` | Define an ad-hoc change                    | `tech-spec.md` (story file for small changes) |
+| `bmad-bmm-quick-dev`  | Implement from spec or direct instructions | Working code + tests                          |
 
 ## Context Management
 
 Each document becomes context for the next phase. The PRD tells the architect what constraints matter. The architecture tells the dev agent which patterns to follow. Story files give focused, complete context for implementation. Without this structure, agents make inconsistent decisions.
 
-For established projects, `document-project` creates or updates `project-context.md` - what exists in the codebase and the rules all implementation workflows must observe. Run it just before Phase 4, and again when something significant changes - structure, architecture, or those rules. You can also edit `project-context.md` by hand.
+### Project Context
 
-All implementation workflows load `project-context.md` if it exists. Additional context per workflow:
+:::tip[Recommended]
+Create `project-context.md` to ensure AI agents follow your project's rules and preferences. This file works like a constitution for your project — it guides implementation decisions across all workflows. This optional file can be generated at the end of Architecture Creation, or in an existing project it can be generated also to capture whats important to keep aligned with current conventions.
+:::
 
-| Workflow       | Also Loads                   |
-| -------------- | ---------------------------- |
-| `create-story` | epics, PRD, architecture, UX |
-| `dev-story`    | story file                   |
-| `code-review`  | architecture, story file     |
-| `quick-spec`   | planning docs (if exist)     |
-| `quick-dev`    | tech-spec                    |
+**How to create it:**
+
+- **Manually** — Create `_bmad-output/project-context.md` with your technology stack and implementation rules
+- **Generate it** — Run `/bmad-bmm-generate-project-context` to auto-generate from your architecture or codebase
+
+[**Learn more about project-context.md**](../explanation/project-context.md)

docs/tutorials/getting-started.md

@@ -8,6 +8,7 @@ Build software faster using AI-powered workflows with specialized agents that gu
 ## What You'll Learn
 
 - Install and initialize BMad Method for a new project
+- Use **BMad-Help** — your intelligent guide that knows what to do next
 - Choose the right planning track for your project size
 - Progress through phases from requirements to working code
 - Use agents and workflows effectively
@@ -19,11 +20,46 @@ Build software faster using AI-powered workflows with specialized agents that gu
 - **A project idea** — Even a simple one works for learning
 :::
 
-:::tip[Quick Path]
+:::tip[The Easiest Path]
 **Install** → `npx bmad-method install`
-**Plan** → PM creates PRD, Architect creates architecture
-**Build** → SM manages sprints, DEV implements stories
-**Fresh chats** for each workflow to avoid context issues.
+**Ask** → `/bmad-help what should I do first?`
+**Build** → Let BMad-Help guide you workflow by workflow
+:::
+
+## Meet BMad-Help: Your Intelligent Guide
+
+**BMad-Help is the fastest way to get started with BMad.** You don't need to memorize workflows or phases — just ask, and BMad-Help will:
+
+- **Inspect your project** to see what's already been done
+- **Show your options** based on which modules you have installed
+- **Recommend what's next** — including the first required task
+- **Answer questions** like "I have a SaaS idea, where do I start?"
+
+### How to Use BMad-Help
+
+Run it in your AI IDE with just the slash command:
+
+```
+/bmad-help
+```
+
+Or combine it with a question for context-aware guidance:
+
+```
+/bmad-help I have an idea for a SaaS product, I already know all the features I want. where do I get started?
+```
+
+BMad-Help will respond with:
+- What's recommended for your situation
+- What the first required task is
+- What the rest of the process looks like
+
+### It Powers Workflows Too
+
+BMad-Help doesn't just answer questions — **it automatically runs at the end of every workflow** to tell you exactly what to do next. No guessing, no searching docs — just clear guidance on the next required workflow.
+
+:::tip[Start Here]
+After installing BMad, run `/bmad-help` immediately. It will detect what modules you have installed and guide you to the right starting point for your project.
 :::
 
 ## Understanding BMad
@@ -65,7 +101,15 @@ The installer creates two folders:
 - `_bmad/` — agents, workflows, tasks, and configuration
 - `_bmad-output/` — empty for now, but this is where your artifacts will be saved
 
-Open your AI IDE in the project folder. Run the `help` workflow (`/bmad-help`) to see what to do next — it detects what you've completed and recommends the next step.
+:::tip[Your Next Step]
+Open your AI IDE in the project folder and run:
+
+```
+/bmad-help
+```
+
+BMad-Help will detect what you've completed and recommend exactly what to do next. You can also ask it questions like "What are my options?" or "I have a SaaS idea, where should I start?"
+:::
 
 :::note[How to Load Agents and Run Workflows]
 Each workflow has a **slash command** you run in your IDE (e.g., `/bmad-bmm-create-prd`). Running a workflow command automatically loads the appropriate agent — you don't need to load agents separately. You can also load an agent directly for general conversation (e.g., `/bmad-agent-bmm-pm` for the PM agent).
@@ -79,6 +123,12 @@ Always start a fresh chat for each workflow. This prevents context limitations f
 
 Work through phases 1-3. **Use fresh chats for each workflow.**
 
+:::tip[Project Context (Optional)]
+Before starting, consider creating `project-context.md` to document your technical preferences and implementation rules. This ensures all AI agents follow your conventions throughout the project.
+
+Create it manually at `_bmad-output/project-context.md` or generate it after architecture using `/bmad-bmm-generate-project-context`. [Learn more](../explanation/project-context.md).
+:::
+
 ### Phase 1: Analysis (Optional)
 
 All workflows in this phase are optional:
@@ -157,20 +207,24 @@ Your project now has:
 your-project/
 ├── _bmad/                                   # BMad configuration
 ├── _bmad-output/
-│   ├── PRD.md                     # Your requirements document
-│   ├── architecture.md            # Technical decisions
-│   ├── epics/                     # Epic and story files
-│   └── sprint-status.yaml         # Sprint tracking
+│   ├── planning-artifacts/
+│   │   ├── PRD.md                           # Your requirements document
+│   │   ├── architecture.md                  # Technical decisions
+│   │   └── epics/                           # Epic and story files
+│   ├── implementation-artifacts/
+│   │   └── sprint-status.yaml               # Sprint tracking
+│   └── project-context.md                   # Implementation rules (optional)
 └── ...
 ```
 
 ## Quick Reference
 
 | Workflow                              | Command                                    | Agent     | Purpose                                         |
-| -------------------------------- | ------------------------------------------ | --------- | ------------------------------------ |
-| `help`                           | `/bmad-help`                               | Any       | Get guidance on what to do next      |
+| ------------------------------------- | ------------------------------------------ | --------- | ----------------------------------------------- |
+| **`help`** ⭐                         | `/bmad-help`                               | Any       | **Your intelligent guide — ask anything!**      |
 | `prd`                                 | `/bmad-bmm-create-prd`                     | PM        | Create Product Requirements Document            |
 | `create-architecture`                 | `/bmad-bmm-create-architecture`            | Architect | Create architecture document                     |
+| `generate-project-context`            | `/bmad-bmm-generate-project-context`       | Analyst   | Create project context file                     |
 | `create-epics-and-stories`       | `/bmad-bmm-create-epics-and-stories`       | PM        | Break down PRD into epics            |
 | `check-implementation-readiness` | `/bmad-bmm-check-implementation-readiness` | Architect | Validate planning cohesion           |
 | `sprint-planning`                | `/bmad-bmm-sprint-planning`                | SM        | Initialize sprint tracking           |
@@ -194,16 +248,26 @@ Not strictly. Once you learn the flow, you can run workflows directly using the
 
 ## Getting Help
 
+:::tip[First Stop: BMad-Help]
+**Run `/bmad-help` anytime** — it's the fastest way to get unstuck. Ask it anything:
+- "What should I do after installing?"
+- "I'm stuck on workflow X"
+- "What are my options for Y?"
+- "Show me what's been done so far"
+
+BMad-Help inspects your project, detects what you've completed, and tells you exactly what to do next.
+:::
+
 - **During workflows** — Agents guide you with questions and explanations
 - **Community** — [Discord](https://discord.gg/gk8jAdXWmj) (#bmad-method-help, #report-bugs-and-issues)
-- **Stuck?** — Run `help` (`/bmad-help`) to see what to do next
 
 ## Key Takeaways
 
 :::tip[Remember These]
+- **Start with `/bmad-help`** — Your intelligent guide that knows your project and options
 - **Always use fresh chats** — Start a new chat for each workflow
 - **Track matters** — Quick Flow uses quick-spec; Method/Enterprise need PRD and architecture
-- **Use `help` (`/bmad-help`) when stuck** — It detects your progress and suggests next steps
+- **BMad-Help runs automatically** — Every workflow ends with guidance on what's next
 :::
 
-Ready to start? Install BMad and let the agents guide you through your first project.
+Ready to start? Install BMad, run `/bmad-help`, and let your intelligent guide lead the way.

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "bmad-method",
-  "version": "6.0.0-Beta.8",
+  "version": "6.0.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "bmad-method",
-      "version": "6.0.0-Beta.8",
+      "version": "6.0.1",
       "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.0-Beta.8",
+  "version": "6.0.1",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",
@@ -25,6 +25,7 @@
   },
   "scripts": {
     "bmad:install": "node tools/cli/bmad-cli.js install",
+    "bmad:uninstall": "node tools/cli/bmad-cli.js uninstall",
     "docs:build": "node tools/build-docs.mjs",
     "docs:dev": "astro dev --root website",
     "docs:fix-links": "node tools/fix-doc-links.js",

src/bmm/agents/analyst.agent.yaml

@@ -12,8 +12,8 @@ agent:
     role: Strategic Business Analyst + Requirements Expert
     identity: Senior analyst with deep expertise in market research, competitive analysis, and requirements elicitation. Specializes in translating vague needs into actionable specs.
     communication_style: "Speaks with the excitement of a treasure hunter - thrilled by every clue, energized when patterns emerge. Structures insights with precision while making analysis feel like discovery."
-    principles: |
-      - Channel expert business analysis frameworks: draw upon Porter's Five Forces, SWOT analysis, root cause analysis, and competitive intelligence methodologies to uncover what others miss. Every business challenge has root causes waiting to be discovered. Ground findings in verifiable evidence.
+    principles:
+      - "Channel expert business analysis frameworks: draw upon Porter's Five Forces, SWOT analysis, root cause analysis, and competitive intelligence methodologies to uncover what others miss. Every business challenge has root causes waiting to be discovered. Ground findings in verifiable evidence."
       - Articulate requirements with absolute precision. Ensure all stakeholder voices heard.
 
   menu:

src/bmm/agents/architect.agent.yaml

@@ -14,8 +14,8 @@ agent:
     role: System Architect + Technical Design Leader
     identity: Senior architect with expertise in distributed systems, cloud infrastructure, and API design. Specializes in scalable patterns and technology selection.
     communication_style: "Speaks in calm, pragmatic tones, balancing 'what could be' with 'what should be.'"
-    principles: |
-      - Channel expert lean architecture wisdom: draw upon deep knowledge of distributed systems, cloud patterns, scalability trade-offs, and what actually ships successfully
+    principles:
+      - "Channel expert lean architecture wisdom: draw upon deep knowledge of distributed systems, cloud patterns, scalability trade-offs, and what actually ships successfully"
       - User journeys drive technical decisions. Embrace boring technology for stability.
       - Design simple solutions that scale when needed. Developer productivity is architecture. Connect every decision to business value and user impact.
 

src/bmm/agents/dev.agent.yaml

@@ -14,7 +14,7 @@ agent:
     role: Senior Software Engineer
     identity: Executes approved stories with strict adherence to story details and team standards and practices.
     communication_style: "Ultra-succinct. Speaks in file paths and AC IDs - every statement citable. No fluff, all precision."
-    principles: |
+    principles:
       - All existing and new tests must pass 100% before story is ready for review
       - Every task/subtask must be covered by comprehensive unit tests before marking an item complete
 

src/bmm/agents/pm.agent.yaml

@@ -12,8 +12,8 @@ agent:
     role: Product Manager specializing in collaborative PRD creation through user interviews, requirement discovery, and stakeholder alignment.
     identity: Product management veteran with 8+ years launching B2B and consumer products. Expert in market research, competitive analysis, and user behavior insights.
     communication_style: "Asks 'WHY?' relentlessly like a detective on a case. Direct and data-sharp, cuts through fluff to what actually matters."
-    principles: |
-      - Channel expert product manager thinking: draw upon deep knowledge of user-centered design, Jobs-to-be-Done framework, opportunity scoring, and what separates great products from mediocre ones
+    principles:
+      - "Channel expert product manager thinking: draw upon deep knowledge of user-centered design, Jobs-to-be-Done framework, opportunity scoring, and what separates great products from mediocre ones"
       - PRDs emerge from user interviews, not template filling - discover what users actually need
       - Ship the smallest thing that validates the assumption - iteration over perfection
       - Technical feasibility is a constraint, not the driver - user value first

src/bmm/agents/quick-flow-solo-dev.agent.yaml

@@ -14,7 +14,7 @@ agent:
     role: Elite Full-Stack Developer + Quick Flow Specialist
     identity: Barry handles Quick Flow - from tech spec creation through implementation. Minimum ceremony, lean artifacts, ruthless efficiency.
     communication_style: "Direct, confident, and implementation-focused. Uses tech slang (e.g., refactor, patch, extract, spike) and gets straight to the point. No fluff, just results. Stays focused on the task at hand."
-    principles: |
+    principles:
       - Planning and execution are two sides of the same coin.
       - Specs are for building, not bureaucracy. Code that ships is better than perfect code that doesn't.
 

src/bmm/agents/sm.agent.yaml

@@ -14,7 +14,7 @@ agent:
     role: Technical Scrum Master + Story Preparation Specialist
     identity: Certified Scrum Master with deep technical background. Expert in agile ceremonies, story preparation, and creating clear actionable user stories.
     communication_style: "Crisp and checklist-driven. Every word has a purpose, every requirement crystal clear. Zero tolerance for ambiguity."
-    principles: |
+    principles:
       - I strive to be a servant leader and conduct myself accordingly, helping with any task and offering suggestions
       - I love to talk about Agile process and theory whenever anyone wants to talk about it
 

src/bmm/agents/tech-writer/tech-writer.agent.yaml

@@ -14,9 +14,9 @@ agent:
     role: Technical Documentation Specialist + Knowledge Curator
     identity: Experienced technical writer expert in CommonMark, DITA, OpenAPI. Master of clarity - transforms complex concepts into accessible structured documentation.
     communication_style: "Patient educator who explains like teaching a friend. Uses analogies that make complex simple, celebrates clarity when it shines."
-    principles: |
+    principles:
       - Every Technical Document I touch helps someone accomplish a task. Thus I strive for Clarity above all, and every word and phrase serves a purpose without being overly wordy.
-      - I believe a picture/diagram is worth 1000s works and will include diagrams over drawn out text.
+      - I believe a picture/diagram is worth 1000s of words and will include diagrams over drawn out text.
       - I understand the intended audience or will clarify with the user so I know when to simplify vs when to be detailed.
       - I will always strive to follow `_bmad/_memory/tech-writer-sidecar/documentation-standards.md` best practices.
 

src/bmm/agents/ux-designer.agent.yaml

@@ -14,7 +14,7 @@ agent:
     role: User Experience Designer + UI Specialist
     identity: Senior UX Designer with 7+ years creating intuitive experiences across web and mobile. Expert in user research, interaction design, AI-assisted tools.
     communication_style: "Paints pictures with words, telling user stories that make you FEEL the problem. Empathetic advocate with creative storytelling flair."
-    principles: |
+    principles:
       - Every decision serves genuine user needs
       - Start simple, evolve through feedback
       - Balance empathy with edge case attention
@@ -24,4 +24,4 @@ agent:
   menu:
     - trigger: CU or fuzzy match on ux-design
       exec: "{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-ux-design/workflow.md"
-      description: "[CU] Create UX: Guidance through realizing the plan for your UX to inform architecture and implementation. PRovides more details that what was discovered in the PRD"
+      description: "[CU] Create UX: Guidance through realizing the plan for your UX to inform architecture and implementation. Provides more details than what was discovered in the PRD"

src/bmm/workflows/1-analysis/research/domain-steps/step-06-research-synthesis.md

@@ -373,6 +373,7 @@ _This comprehensive research document serves as an authoritative reference on {{
 
 #### If 'C' (Complete Research):
 
+- **Replace** the template placeholder `[Research overview and methodology will be appended here]` in the `## Research Overview` section near the top of the document with a concise 2-3 paragraph overview summarizing the research scope, key findings, and a pointer to the full executive summary in the Research Synthesis section
 - Append the complete document to the research file
 - Update frontmatter: `stepsCompleted: [1, 2, 3, 4, 5]`
 - Complete the domain research workflow
@@ -380,7 +381,7 @@ _This comprehensive research document serves as an authoritative reference on {{
 
 ## APPEND TO DOCUMENT:
 
-When user selects 'C', append the complete comprehensive research document using the full structure above.
+When user selects 'C', append the complete comprehensive research document using the full structure above. Also replace the `[Research overview and methodology will be appended here]` placeholder in the Research Overview section at the top of the document.
 
 ## SUCCESS METRICS:
 

src/bmm/workflows/1-analysis/research/market-steps/step-06-research-completion.md

@@ -389,13 +389,14 @@ _This comprehensive market research document serves as an authoritative market r
 
 #### If 'C' (Complete Research):
 
+- **Replace** the template placeholder `[Research overview and methodology will be appended here]` in the `## Research Overview` section near the top of the document with a concise 2-3 paragraph overview summarizing the research scope, key findings, and a pointer to the full executive summary in the Research Synthesis section
 - Append the final content to the research document
 - Update frontmatter: `stepsCompleted: [1, 2, 3, 4]`
 - Complete the market research workflow
 
 ## APPEND TO DOCUMENT:
 
-When user selects 'C', append the content directly to the research document using the structure from step 4.
+When user selects 'C', append the content directly to the research document using the structure from step 4. Also replace the `[Research overview and methodology will be appended here]` placeholder in the Research Overview section at the top of the document.
 
 ## SUCCESS METRICS:
 

src/bmm/workflows/1-analysis/research/technical-steps/step-06-research-synthesis.md

@@ -416,6 +416,7 @@ _This comprehensive technical research document serves as an authoritative techn
 
 #### If 'C' (Complete Research):
 
+- **Replace** the template placeholder `[Research overview and methodology will be appended here]` in the `## Research Overview` section near the top of the document with a concise 2-3 paragraph overview summarizing the research scope, key findings, and a pointer to the full executive summary in the Research Synthesis section
 - Append the complete technical document to the research file
 - Update frontmatter: `stepsCompleted: [1, 2, 3, 4, 5, 6]`
 - Complete the technical research workflow
@@ -423,7 +424,7 @@ _This comprehensive technical research document serves as an authoritative techn
 
 ## APPEND TO DOCUMENT:
 
-When user selects 'C', append the complete comprehensive technical research document using the full structure above.
+When user selects 'C', append the complete comprehensive technical research document using the full structure above. Also replace the `[Research overview and methodology will be appended here]` placeholder in the Research Overview section at the top of the document.
 
 ## SUCCESS METRICS:
 

src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-02-discovery.md

@@ -3,7 +3,7 @@ name: 'step-02-discovery'
 description: 'Discover project type, domain, and context through collaborative dialogue'
 
 # File References
-nextStepFile: './step-03-success.md'
+nextStepFile: './step-02b-vision.md'
 outputFile: '{planning_artifacts}/prd.md'
 
 # Data Files

src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-02b-vision.md

@@ -0,0 +1,154 @@
+---
+name: 'step-02b-vision'
+description: 'Discover the product vision and differentiator through collaborative dialogue'
+
+# File References
+nextStepFile: './step-02c-executive-summary.md'
+outputFile: '{planning_artifacts}/prd.md'
+
+# Task References
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+---
+
+# Step 2b: Product Vision Discovery
+
+**Progress: Step 2b of 13** - Next: Executive Summary
+
+## STEP GOAL:
+
+Discover what makes this product special and understand the product vision through collaborative conversation. No content generation — facilitation only.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read
+- ✅ ALWAYS treat this as collaborative discovery between PM peers
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a product-focused PM facilitator collaborating with an expert peer
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring structured thinking and facilitation skills, while the user brings domain expertise and product vision
+
+### Step-Specific Rules:
+
+- 🎯 Focus on discovering vision and differentiator — no content generation yet
+- 🚫 FORBIDDEN to generate executive summary content (that's the next step)
+- 🚫 FORBIDDEN to append anything to the document in this step
+- 💬 APPROACH: Natural conversation to understand what makes this product special
+- 🎯 BUILD ON classification insights from step 2
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- ⚠️ Present A/P/C menu after vision discovery is complete
+- 📖 Update frontmatter, adding this step to the end of the list of stepsCompleted
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from steps 1 and 2 are available
+- Project classification exists from step 2 (project type, domain, complexity, context)
+- Input documents already loaded are in memory (product briefs, research, brainstorming, project docs)
+- No executive summary content yet (that's step 2c)
+- This step ONLY discovers — it does NOT write to the document
+
+## YOUR TASK:
+
+Discover the product vision and differentiator through natural conversation. Understand what makes this product unique and valuable before any content is written.
+
+## VISION DISCOVERY SEQUENCE:
+
+### 1. Acknowledge Classification Context
+
+Reference the classification from step 2 and use it to frame the vision conversation:
+
+"We've established this is a {{projectType}} in the {{domain}} domain with {{complexityLevel}} complexity. Now let's explore what makes this product special."
+
+### 2. Explore What Makes It Special
+
+Guide the conversation to uncover the product's unique value:
+
+- **User delight:** "What would make users say 'this is exactly what I needed'?"
+- **Differentiation moment:** "What's the moment where users realize this is different or better than alternatives?"
+- **Core insight:** "What insight or approach makes this product possible or unique?"
+- **Value proposition:** "If you had one sentence to explain why someone should use this over anything else, what would it be?"
+
+### 3. Understand the Vision
+
+Dig deeper into the product vision:
+
+- **Problem framing:** "What's the real problem you're solving — not the surface symptom, but the deeper need?"
+- **Future state:** "When this product is successful, what does the world look like for your users?"
+- **Why now:** "Why is this the right time to build this?"
+
+### 4. Validate Understanding
+
+Reflect back what you've heard and confirm:
+
+"Here's what I'm hearing about your vision and differentiator:
+
+**Vision:** {{summarized_vision}}
+**What Makes It Special:** {{summarized_differentiator}}
+**Core Insight:** {{summarized_insight}}
+
+Does this capture it? Anything I'm missing?"
+
+Let the user confirm or refine your understanding.
+
+### N. Present MENU OPTIONS
+
+Present your understanding of the product vision for review, then display menu:
+
+"Based on our conversation, I have a clear picture of your product vision and what makes it special. I'll use these insights to draft the Executive Summary in the next step.
+
+**What would you like to do?**"
+
+Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Executive Summary (Step 2c of 13)"
+
+#### Menu Handling Logic:
+- IF A: Read fully and follow: {advancedElicitationTask} with the current vision insights, process the enhanced insights that come back, ask user if they accept the improvements, if yes update understanding then redisplay menu, if no keep original understanding then redisplay menu
+- IF P: Read fully and follow: {partyModeWorkflow} with the current vision insights, process the collaborative insights, ask user if they accept the changes, if yes update understanding then redisplay menu, if no keep original understanding then redisplay menu
+- IF C: Update {outputFile} frontmatter by adding this step name to the end of stepsCompleted array, then read fully and follow: {nextStepFile}
+- IF Any other: help user respond, then redisplay menu
+
+#### EXECUTION RULES:
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- After other menu items execution, return to this menu
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN [C continue option] is selected and [stepsCompleted updated], will you then read fully and follow: `{nextStepFile}` to generate the Executive Summary.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Classification context from step 2 acknowledged and built upon
+- Natural conversation to understand product vision and differentiator
+- User's existing documents (briefs, research, brainstorming) leveraged for vision insights
+- Vision and differentiator validated with user before proceeding
+- Clear understanding established that will inform Executive Summary generation
+- Frontmatter updated with stepsCompleted when C selected
+
+### ❌ SYSTEM FAILURE:
+
+- Generating executive summary or any document content (that's step 2c!)
+- Appending anything to the PRD document
+- Not building on classification from step 2
+- Being prescriptive instead of having natural conversation
+- Proceeding without user selecting 'C'
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+
+**Master Rule:** This step is vision discovery only. No content generation, no document writing. Have natural conversations, build on what you know from classification, and establish the vision that will feed into the Executive Summary.

src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-02c-executive-summary.md

@@ -0,0 +1,170 @@
+---
+name: 'step-02c-executive-summary'
+description: 'Generate and append the Executive Summary section to the PRD document'
+
+# File References
+nextStepFile: './step-03-success.md'
+outputFile: '{planning_artifacts}/prd.md'
+
+# Task References
+advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+---
+
+# Step 2c: Executive Summary Generation
+
+**Progress: Step 2c of 13** - Next: Success Criteria
+
+## STEP GOAL:
+
+Generate the Executive Summary content using insights from classification (step 2) and vision discovery (step 2b), then append it to the PRD document.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure the entire file is read
+- ✅ ALWAYS treat this as collaborative discovery between PM peers
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a product-focused PM facilitator collaborating with an expert peer
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ Content is drafted collaboratively — present for review before saving
+
+### Step-Specific Rules:
+
+- 🎯 Generate Executive Summary content based on discovered insights
+- 💬 Present draft content for user review and refinement before appending
+- 🚫 FORBIDDEN to append content without user approval via 'C'
+- 🎯 Content must be dense, precise, and zero-fluff (PRD quality standards)
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- ⚠️ Present A/P/C menu after generating executive summary content
+- 💾 ONLY save when user chooses C (Continue)
+- 📖 Update output file frontmatter, adding this step name to the end of the list of stepsCompleted
+- 🚫 FORBIDDEN to load next step until C is selected
+
+## CONTEXT BOUNDARIES:
+
+- Current document and frontmatter from steps 1, 2, and 2b are available
+- Project classification exists from step 2 (project type, domain, complexity, context)
+- Vision and differentiator insights exist from step 2b
+- Input documents from step 1 are available (product briefs, research, brainstorming, project docs)
+- This step generates and appends the first substantive content to the PRD
+
+## YOUR TASK:
+
+Draft the Executive Summary section using all discovered insights, present it for user review, and append it to the PRD document when approved.
+
+## EXECUTIVE SUMMARY GENERATION SEQUENCE:
+
+### 1. Synthesize Available Context
+
+Review all available context before drafting:
+- Classification from step 2: project type, domain, complexity, project context
+- Vision and differentiator from step 2b: what makes this special, core insight
+- Input documents: product briefs, research, brainstorming, project docs
+
+### 2. Draft Executive Summary Content
+
+Generate the Executive Summary section using the content structure below. Apply PRD quality standards:
+- High information density — every sentence carries weight
+- Zero fluff — no filler phrases or vague language
+- Precise and actionable — clear, specific statements
+- Dual-audience optimized — readable by humans, consumable by LLMs
+
+### 3. Present Draft for Review
+
+Present the drafted content to the user for review:
+
+"Here's the Executive Summary I've drafted based on our discovery work. Please review and let me know if you'd like any changes:"
+
+Show the full drafted content using the structure from the Content Structure section below.
+
+Allow the user to:
+- Request specific changes to any section
+- Add missing information
+- Refine the language or emphasis
+- Approve as-is
+
+### N. Present MENU OPTIONS
+
+Present the executive summary content for user review, then display menu:
+
+"Here's the Executive Summary for your PRD. Review the content above and let me know what you'd like to do."
+
+Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Success Criteria (Step 3 of 13)"
+
+#### Menu Handling Logic:
+- IF A: Read fully and follow: {advancedElicitationTask} with the current executive summary content, process the enhanced content that comes back, ask user if they accept the improvements, if yes update content then redisplay menu, if no keep original content then redisplay menu
+- IF P: Read fully and follow: {partyModeWorkflow} with the current executive summary content, process the collaborative improvements, ask user if they accept the changes, if yes update content then redisplay menu, if no keep original content then redisplay menu
+- IF C: Append the final content to {outputFile}, update frontmatter by adding this step name to the end of the stepsCompleted array, then read fully and follow: {nextStepFile}
+- IF Any other: help user respond, then redisplay menu
+
+#### EXECUTION RULES:
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- After other menu items execution, return to this menu
+
+## APPEND TO DOCUMENT:
+
+When user selects 'C', append the following content structure directly to the document:
+
+```markdown
+## Executive Summary
+
+{vision_alignment_content}
+
+### What Makes This Special
+
+{product_differentiator_content}
+
+## Project Classification
+
+{project_classification_content}
+```
+
+Where:
+- `{vision_alignment_content}` — Product vision, target users, and the problem being solved. Dense, precise summary drawn from step 2b vision discovery.
+- `{product_differentiator_content}` — What makes this product unique, the core insight, and why users will choose it over alternatives. Drawn from step 2b differentiator discovery.
+- `{project_classification_content}` — Project type, domain, complexity level, and project context (greenfield/brownfield). Drawn from step 2 classification.
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN [C continue option] is selected and [content appended to document], will you then read fully and follow: `{nextStepFile}` to define success criteria.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Executive Summary drafted using insights from steps 2 and 2b
+- Content meets PRD quality standards (dense, precise, zero-fluff)
+- Draft presented to user for review before saving
+- User given opportunity to refine content
+- Content properly appended to document when C selected
+- A/P/C menu presented and handled correctly
+- Frontmatter updated with stepsCompleted when C selected
+
+### ❌ SYSTEM FAILURE:
+
+- Generating content without incorporating discovered vision and classification
+- Appending content without user selecting 'C'
+- Producing vague, fluffy, or low-density content
+- Not presenting draft for user review
+- Not presenting A/P/C menu after content generation
+- Skipping directly to next step without appending content
+
+❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
+❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
+❌ **CRITICAL**: Making decisions without complete understanding of step requirements and protocols
+
+**Master Rule:** Generate high-quality Executive Summary content from discovered insights. Present for review, refine collaboratively, and only save when the user approves. This is the first substantive content in the PRD — it sets the quality bar for everything that follows.

src/bmm/workflows/document-project/instructions.md

@@ -8,55 +8,7 @@
 
 <critical>This router determines workflow mode and delegates to specialized sub-workflows</critical>
 
-<step n="1" goal="Validate workflow and get project info">
-
-<invoke-workflow path="{project-root}/_bmad/bmm/workflows/workflow-status">
-  <param>mode: data</param>
-  <param>data_request: project_config</param>
-</invoke-workflow>
-
-<check if="status_exists == false">
-  <output>{{suggestion}}</output>
-  <output>Note: Documentation workflow can run standalone. Continuing without progress tracking.</output>
-  <action>Set standalone_mode = true</action>
-  <action>Set status_file_found = false</action>
-</check>
-
-<check if="status_exists == true">
-  <action>Store {{status_file_path}} for later updates</action>
-  <action>Set status_file_found = true</action>
-
-  <!-- Extract brownfield/greenfield from status data -->
-  <check if="field_type == 'greenfield'">
-    <output>Note: This is a greenfield project. Documentation workflow is typically for brownfield projects.</output>
-    <ask>Continue anyway to document planning artifacts? (y/n)</ask>
-    <check if="n">
-      <action>Exit workflow</action>
-    </check>
-  </check>
-
-  <!-- Now validate sequencing -->
-  <invoke-workflow path="{project-root}/_bmad/bmm/workflows/workflow-status">
-    <param>mode: validate</param>
-    <param>calling_workflow: document-project</param>
-  </invoke-workflow>
-
-  <check if="warning != ''">
-    <output>{{warning}}</output>
-    <output>Note: This may be auto-invoked by prd for brownfield documentation.</output>
-    <ask>Continue with documentation? (y/n)</ask>
-    <check if="n">
-      <output>{{suggestion}}</output>
-      <action>Exit workflow</action>
-    </check>
-  </check>
-</check>
-
-</step>
-
-<step n="2" goal="Check for resumability and determine workflow mode">
-<critical>SMART LOADING STRATEGY: Check state file FIRST before loading any CSV files</critical>
-
+<step n="1" goal="Check for ability to resume and determine workflow mode">
 <action>Check for existing state file at: {project_knowledge}/project-scan-report.json</action>
 
 <check if="project-scan-report.json exists">
@@ -66,21 +18,21 @@
 
 <ask>I found an in-progress workflow state from {{last_updated}}.
 
-**Current Progress:**
+    **Current Progress:**
 
-- Mode: {{mode}}
-- Scan Level: {{scan_level}}
-- Completed Steps: {{completed_steps_count}}/{{total_steps}}
-- Last Step: {{current_step}}
-- Project Type(s): {{cached_project_types}}
+    - Mode: {{mode}}
+    - Scan Level: {{scan_level}}
+    - Completed Steps: {{completed_steps_count}}/{{total_steps}}
+    - Last Step: {{current_step}}
+    - Project Type(s): {{cached_project_types}}
 
-Would you like to:
+    Would you like to:
 
-1. **Resume from where we left off** - Continue from step {{current_step}}
-2. **Start fresh** - Archive old state and begin new scan
-3. **Cancel** - Exit without changes
+    1. **Resume from where we left off** - Continue from step {{current_step}}
+    2. **Start fresh** - Archive old state and begin new scan
+    3. **Cancel** - Exit without changes
 
-Your choice [1/2/3]:
+    Your choice [1/2/3]:
 </ask>
 
   <check if="user selects 1">
@@ -175,47 +127,4 @@ Your choice [1/2/3]:
 
 </step>
 
-<step n="4" goal="Update status and complete">
-
-<check if="status_file_found == true">
-  <invoke-workflow path="{project-root}/_bmad/bmm/workflows/workflow-status">
-    <param>mode: update</param>
-    <param>action: complete_workflow</param>
-    <param>workflow_name: document-project</param>
-  </invoke-workflow>
-
-  <check if="success == true">
-    <output>Status updated!</output>
-  </check>
-</check>
-
-<output>**✅ Document Project Workflow Complete, {user_name}!**
-
-**Documentation Generated:**
-
-- Mode: {{workflow_mode}}
-- Scan Level: {{scan_level}}
-- Output: {project_knowledge}/index.md and related files
-
-{{#if status_file_found}}
-**Status Updated:**
-
-- Progress tracking updated
-
-**Next Steps:**
-
-- **Next required:** {{next_workflow}} ({{next_agent}} agent)
-
-Check status anytime with: `workflow-status`
-{{else}}
-**Next Steps:**
-Since no workflow is in progress:
-
-- Refer to the BMM workflow guide if unsure what to do next
-- Or run `workflow-init` to create a workflow path and get guided next steps
-  {{/if}}
-  </output>
-
-</step>
-
 </workflow>

src/core/agents/bmad-master.agent.yaml

@@ -14,8 +14,8 @@ agent:
     role: "Master Task Executor + BMad Expert + Guiding Facilitator Orchestrator"
     identity: "Master-level expert in the BMAD Core Platform and all loaded modules with comprehensive knowledge of all resources, tasks, and workflows. Experienced in direct task execution and runtime resource management, serving as the primary execution engine for BMAD operations."
     communication_style: "Direct and comprehensive, refers to himself in the 3rd person. Expert-level communication focused on efficient task execution, presenting information systematically using numbered lists with immediate command response capability."
-    principles: |
-      - "Load resources at runtime never pre-load, and always present numbered lists for choices."
+    principles:
+      - Load resources at runtime, never pre-load, and always present numbered lists for choices.
 
   critical_actions:
     - "Always greet the user and let them know they can use `/bmad-help` at any time to get advice on what to do next, and they can combine that with what they need help with <example>`/bmad-help where should I start with an idea I have that does XYZ`</example>"

src/core/tasks/help.md

@@ -9,6 +9,7 @@ description: Get unstuck by showing what workflow steps come next or answering q
 
 - **Empty `phase` = anytime** — Universal tools work regardless of workflow state
 - **Numbered phases indicate sequence** — Phases like `1-discover` → `2-define` → `3-build` → `4-ship` flow in order (naming varies by module)
+- **Phase with no Required Steps** - If an entire phase has no required, true items, the entire phase is optional. If it is sequentially before another phase, it can be recommended, but always be clear with the use what the true next required item is.
 - **Stay in module** — Guide through the active module's workflow based on phase+sequence ordering
 - **Descriptions contain routing** — Read for alternate paths (e.g., "back to previous if fixes needed")
 - **`required=true` blocks progress** — Required workflows must complete before proceeding to later phases
@@ -52,7 +53,7 @@ Determine what was just completed:
 
 ## EXECUTION
 
-1. **Load catalog** — Load `{project-root}/_bmad/_config/bmad-help.csv`
+1. **Load catalog** — Load `_bmad/_config/bmad-help.csv`
 
 2. **Resolve output locations and config** — Scan each folder under `_bmad/` (except `_config`) for `config.yaml`. For each workflow row, resolve its `output-location` variables against that module's config so artifact paths can be searched. Also extract `communication_language` and `project_knowledge` from each scanned module's config.
 

tools/cli/README.md

@@ -5,3 +5,56 @@
 For external official modules to be discoverable during install, ensure an entry for the external repo is added to external-official-modules.yaml.
 
 For community modules - this will be handled in a different way. This file is only for registration of modules under the bmad-code-org.
+
+## Post-Install Notes
+
+Modules can display setup guidance to users after configuration is collected during `npx bmad-method install`. Notes are defined in the module's own `module.yaml` — no changes to the installer are needed.
+
+### Simple Format
+
+Always displayed after the module is configured:
+
+```yaml
+post-install-notes: |
+  Thank you for choosing the XYZ Cool Module
+  For Support about this Module call 555-1212
+```
+
+### Conditional Format
+
+Display different messages based on a config question's answer:
+
+```yaml
+post-install-notes:
+  config_key_name:
+    value1: |
+      Instructions for value1...
+    value2: |
+      Instructions for value2...
+```
+
+Values without an entry (e.g., `none`) display nothing. Multiple config keys can each have their own conditional notes.
+
+### Example: TEA Module
+
+The TEA module uses the conditional format keyed on `tea_browser_automation`:
+
+```yaml
+post-install-notes:
+  tea_browser_automation:
+    cli: |
+      Playwright CLI Setup:
+        npm install -g @playwright/cli@latest
+        playwright-cli install --skills
+    mcp: |
+      Playwright MCP Setup (two servers):
+        1. playwright    — npx @playwright/mcp@latest
+        2. playwright-test — npx playwright run-test-mcp-server
+    auto: |
+      Playwright CLI Setup:
+        ...
+      Playwright MCP Setup (two servers):
+        ...
+```
+
+When a user selects `auto`, they see both CLI and MCP instructions. When they select `none`, nothing is shown.

tools/cli/bmad-cli.js

@@ -2,6 +2,7 @@ const { program } = require('commander');
 const path = require('node:path');
 const fs = require('node:fs');
 const { execSync } = require('node:child_process');
+const semver = require('semver');
 const prompts = require('./lib/prompts');
 
 // The installer flow uses many sequential @clack/prompts, each adding keypress
@@ -34,7 +35,7 @@ async function checkForUpdate() {
       timeout: 5000,
     }).trim();
 
-    if (result && result !== packageJson.version) {
+    if (result && semver.gt(result, packageJson.version)) {
       const color = await prompts.getColor();
       const updateMsg = [
         `You are using version ${packageJson.version} but ${result} is available.`,

tools/cli/commands/uninstall.js

@@ -0,0 +1,167 @@
+const path = require('node:path');
+const fs = require('fs-extra');
+const prompts = require('../lib/prompts');
+const { Installer } = require('../installers/lib/core/installer');
+
+const installer = new Installer();
+
+module.exports = {
+  command: 'uninstall',
+  description: 'Remove BMAD installation from the current project',
+  options: [
+    ['-y, --yes', 'Remove all BMAD components without prompting (preserves user artifacts)'],
+    ['--directory <path>', 'Project directory (default: current directory)'],
+  ],
+  action: async (options) => {
+    try {
+      let projectDir;
+
+      if (options.directory) {
+        // Explicit --directory flag takes precedence
+        projectDir = path.resolve(options.directory);
+      } else if (options.yes) {
+        // Non-interactive mode: use current directory
+        projectDir = process.cwd();
+      } else {
+        // Interactive: ask user which directory to uninstall from
+        // select() handles cancellation internally (exits process)
+        const dirChoice = await prompts.select({
+          message: 'Where do you want to uninstall BMAD from?',
+          choices: [
+            { value: 'cwd', name: `Current directory (${process.cwd()})` },
+            { value: 'other', name: 'Another directory...' },
+          ],
+        });
+
+        if (dirChoice === 'other') {
+          // text() handles cancellation internally (exits process)
+          const customDir = await prompts.text({
+            message: 'Enter the project directory path:',
+            placeholder: process.cwd(),
+            validate: (value) => {
+              if (!value || value.trim().length === 0) return 'Directory path is required';
+            },
+          });
+
+          projectDir = path.resolve(customDir.trim());
+        } else {
+          projectDir = process.cwd();
+        }
+      }
+
+      if (!(await fs.pathExists(projectDir))) {
+        await prompts.log.error(`Directory does not exist: ${projectDir}`);
+        process.exit(1);
+      }
+
+      const { bmadDir } = await installer.findBmadDir(projectDir);
+
+      if (!(await fs.pathExists(bmadDir))) {
+        await prompts.log.warn('No BMAD installation found.');
+        process.exit(0);
+      }
+
+      const existingInstall = await installer.getStatus(projectDir);
+      const version = existingInstall.version || 'unknown';
+      const modules = (existingInstall.modules || []).map((m) => m.id || m.name).join(', ');
+      const ides = (existingInstall.ides || []).join(', ');
+
+      const outputFolder = await installer.getOutputFolder(projectDir);
+
+      await prompts.intro('BMAD Uninstall');
+      await prompts.note(`Version: ${version}\nModules: ${modules}\nIDE integrations: ${ides}`, 'Current Installation');
+
+      let removeModules = true;
+      let removeIdeConfigs = true;
+      let removeOutputFolder = false;
+
+      if (!options.yes) {
+        // multiselect() handles cancellation internally (exits process)
+        const selected = await prompts.multiselect({
+          message: 'Select components to remove:',
+          options: [
+            {
+              value: 'modules',
+              label: `BMAD Modules & data (${installer.bmadFolderName}/)`,
+              hint: 'Core installation, agents, workflows, config',
+            },
+            { value: 'ide', label: 'IDE integrations', hint: ides || 'No IDEs configured' },
+            { value: 'output', label: `User artifacts (${outputFolder}/)`, hint: 'WARNING: Contains your work products' },
+          ],
+          initialValues: ['modules', 'ide'],
+          required: true,
+        });
+
+        removeModules = selected.includes('modules');
+        removeIdeConfigs = selected.includes('ide');
+        removeOutputFolder = selected.includes('output');
+
+        const red = (s) => `\u001B[31m${s}\u001B[0m`;
+        await prompts.note(
+          red('💀 This action is IRREVERSIBLE! Removed files cannot be recovered!') +
+            '\n' +
+            red('💀 IDE configurations and modules will need to be reinstalled.') +
+            '\n' +
+            red('💀 User artifacts are preserved unless explicitly selected.'),
+          '!! DESTRUCTIVE ACTION !!',
+        );
+
+        const confirmed = await prompts.confirm({
+          message: 'Proceed with uninstall?',
+          default: false,
+        });
+
+        if (!confirmed) {
+          await prompts.outro('Uninstall cancelled.');
+          process.exit(0);
+        }
+      }
+
+      // Phase 1: IDE integrations
+      if (removeIdeConfigs) {
+        const s = await prompts.spinner();
+        s.start('Removing IDE integrations...');
+        await installer.uninstallIdeConfigs(projectDir, existingInstall, { silent: true });
+        s.stop(`Removed IDE integrations (${ides || 'none'})`);
+      }
+
+      // Phase 2: User artifacts
+      if (removeOutputFolder) {
+        const s = await prompts.spinner();
+        s.start(`Removing user artifacts (${outputFolder}/)...`);
+        await installer.uninstallOutputFolder(projectDir, outputFolder);
+        s.stop('User artifacts removed');
+      }
+
+      // Phase 3: BMAD modules & data (last — other phases may need _bmad/)
+      if (removeModules) {
+        const s = await prompts.spinner();
+        s.start(`Removing BMAD modules & data (${installer.bmadFolderName}/)...`);
+        await installer.uninstallModules(projectDir);
+        s.stop('Modules & data removed');
+      }
+
+      const summary = [];
+      if (removeIdeConfigs) summary.push('IDE integrations cleaned');
+      if (removeModules) summary.push('Modules & data removed');
+      if (removeOutputFolder) summary.push('User artifacts removed');
+      if (!removeOutputFolder) summary.push(`User artifacts preserved in ${outputFolder}/`);
+
+      await prompts.note(summary.join('\n'), 'Summary');
+      await prompts.outro('To reinstall, run: npx bmad-method install');
+
+      process.exit(0);
+    } catch (error) {
+      try {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        await prompts.log.error(`Uninstall failed: ${errorMessage}`);
+        if (error instanceof Error && error.stack) {
+          await prompts.log.message(error.stack);
+        }
+      } catch {
+        console.error(error instanceof Error ? error.message : error);
+      }
+      process.exit(1);
+    }
+  },
+};

tools/cli/installers/install-messages.yaml

@@ -6,24 +6,19 @@
 startMessage: |
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-  🎉 BETA IS HERE! Welcome to BMad Method V6 Beta!
+  🎉 V6 IS HERE! Welcome to BMad Method V6 - Official Stable Release!
 
-  We've officially graduated from Alpha! This milestone represents:
-    - 50+ workflows covering the full development lifecycle
-    - Stability - we will still be adding and evolving and optimizing,
-      but anticipate no massive breaking changes
-    - Groundwork in place for customization and community modules
+  The BMad Method is now a Platform powered by the BMad Method Core and Module Ecosystem!
+    - 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
 
   🌟 BMad is 100% free and open source.
     - No gated Discord. No paywalls. No gated content.
     - We believe in empowering everyone, not just those who can pay.
     - Knowledge should be shared, not sold.
 
-  🙏 SUPPORT BMAD DEVELOPMENT:
-    - During the Beta, please give us feedback and raise issues on GitHub!
-    - Donate: https://buymeacoffee.com/bmad
-    - Corporate Sponsorship available - DM on Discord
-
   🎤 SPEAKING & MEDIA:
     - Available for conferences, podcasts, and media appearances
     - Topics: AI-Native Transformation, Spec and Context Engineering, BMad Method
@@ -32,9 +27,11 @@ startMessage: |
   ⭐ HELP US GROW:
     - Star us on GitHub: https://github.com/bmad-code-org/BMAD-METHOD/
     - Subscribe on YouTube: https://www.youtube.com/@BMadCode
-    - Every star & sub helps us reach more developers!
+    - Free Community and Support: https://discord.gg/gk8jAdXWmj
+    - Donate: https://buymeacoffee.com/bmad
+    - Corporate Sponsorship available
 
-  Latest updates: https://github.com/bmad-code-org/BMAD-METHOD/CHANGELOG.md
+  Latest updates: https://github.com/bmad-code-org/BMAD-METHOD/blob/main/CHANGELOG.md
 
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 

tools/cli/installers/lib/core/config-collector.js

@@ -302,6 +302,7 @@ class ConfigCollector {
 
         const configSpinner = await prompts.spinner();
         configSpinner.start('Configuring modules...');
+        try {
           for (const moduleName of defaultModules) {
             const displayName = displayNameMap.get(moduleName) || moduleName.toUpperCase();
             configSpinner.message(`Configuring ${displayName}...`);
@@ -312,13 +313,19 @@ class ConfigCollector {
               this._silentConfig = false;
             }
           }
-        configSpinner.stop('Module configuration complete');
+        } finally {
+          configSpinner.stop(customizeModules.length > 0 ? 'Module defaults applied' : 'Module configuration complete');
+        }
       }
 
       // Run customized modules individually (may show interactive prompts)
       for (const moduleName of customizeModules) {
         await this.collectModuleConfig(moduleName, projectDir);
       }
+
+      if (customizeModules.length > 0) {
+        await prompts.log.step('Module configuration complete');
+      }
     }
 
     // Add metadata
@@ -550,6 +557,8 @@ class ConfigCollector {
       }
     }
 
+    await this.displayModulePostConfigNotes(moduleName, moduleConfig);
+
     return newKeys.length > 0 || newStaticKeys.length > 0; // Return true if we had any new fields (interactive or static)
   }
 
@@ -923,6 +932,8 @@ class ConfigCollector {
         }
       }
     }
+
+    await this.displayModulePostConfigNotes(moduleName, moduleConfig);
   }
 
   /**
@@ -1195,6 +1206,58 @@ class ConfigCollector {
     return question;
   }
 
+  /**
+   * Display post-configuration notes for a module
+   * Shows prerequisite guidance based on collected config values
+   * Reads notes from the module's `post-install-notes` section in module.yaml
+   * Supports two formats:
+   *   - Simple string: always displayed
+   *   - Object keyed by config field name, with value-specific messages
+   * @param {string} moduleName - Module name
+   * @param {Object} moduleConfig - Parsed module.yaml content
+   */
+  async displayModulePostConfigNotes(moduleName, moduleConfig) {
+    if (this._silentConfig) return;
+    if (!moduleConfig || !moduleConfig['post-install-notes']) return;
+
+    const notes = moduleConfig['post-install-notes'];
+    const color = await prompts.getColor();
+
+    // Format 1: Simple string - always display
+    if (typeof notes === 'string') {
+      await prompts.log.message('');
+      for (const line of notes.trim().split('\n')) {
+        await prompts.log.message(color.dim(line));
+      }
+      return;
+    }
+
+    // Format 2: Conditional on config values
+    if (typeof notes === 'object') {
+      const config = this.collectedConfig[moduleName];
+      if (!config) return;
+
+      let hasOutput = false;
+      for (const [configKey, valueMessages] of Object.entries(notes)) {
+        const selectedValue = config[configKey];
+        if (!selectedValue || !valueMessages[selectedValue]) continue;
+
+        if (hasOutput) await prompts.log.message('');
+        hasOutput = true;
+
+        const message = valueMessages[selectedValue];
+        for (const line of message.trim().split('\n')) {
+          const trimmedLine = line.trim();
+          if (trimmedLine.endsWith(':') && !trimmedLine.startsWith(' ')) {
+            await prompts.log.info(color.bold(trimmedLine));
+          } else {
+            await prompts.log.message(color.dim('  ' + trimmedLine));
+          }
+        }
+      }
+    }
+  }
+
   /**
    * Deep merge two objects
    * @param {Object} target - Target object

tools/cli/installers/lib/core/installer.js

@@ -527,8 +527,13 @@ class Installer {
             const cachedModules = await fs.readdir(cacheDir, { withFileTypes: true });
 
             for (const cachedModule of cachedModules) {
-              if (cachedModule.isDirectory()) {
               const moduleId = cachedModule.name;
+              const cachedPath = path.join(cacheDir, moduleId);
+
+              // Skip if path doesn't exist (broken symlink, deleted dir) - avoids lstat ENOENT
+              if (!(await fs.pathExists(cachedPath)) || !cachedModule.isDirectory()) {
+                continue;
+              }
 
               // Skip if we already have this module from manifest
               if (customModulePaths.has(moduleId)) {
@@ -542,15 +547,12 @@ class Installer {
                 continue;
               }
 
-                const cachedPath = path.join(cacheDir, moduleId);
-
               // Check if this is actually a custom module (has module.yaml)
               const moduleYamlPath = path.join(cachedPath, 'module.yaml');
               if (await fs.pathExists(moduleYamlPath)) {
                 customModulePaths.set(moduleId, cachedPath);
               }
             }
-            }
 
             // Update module manager with the new custom module paths from cache
             this.moduleManager.setCustomModulePaths(customModulePaths);
@@ -609,8 +611,13 @@ class Installer {
           const cachedModules = await fs.readdir(cacheDir, { withFileTypes: true });
 
           for (const cachedModule of cachedModules) {
-            if (cachedModule.isDirectory()) {
             const moduleId = cachedModule.name;
+            const cachedPath = path.join(cacheDir, moduleId);
+
+            // Skip if path doesn't exist (broken symlink, deleted dir) - avoids lstat ENOENT
+            if (!(await fs.pathExists(cachedPath)) || !cachedModule.isDirectory()) {
+              continue;
+            }
 
             // Skip if we already have this module from manifest
             if (customModulePaths.has(moduleId)) {
@@ -624,15 +631,12 @@ class Installer {
               continue;
             }
 
-              const cachedPath = path.join(cacheDir, moduleId);
-
             // Check if this is actually a custom module (has module.yaml)
             const moduleYamlPath = path.join(cachedPath, 'module.yaml');
             if (await fs.pathExists(moduleYamlPath)) {
               customModulePaths.set(moduleId, cachedPath);
             }
           }
-          }
 
           // Update module manager with the new custom module paths from cache
           this.moduleManager.setCustomModulePaths(customModulePaths);
@@ -949,12 +953,11 @@ class Installer {
               if (!isCustomModule && config._customModuleSources && config._customModuleSources.has(moduleName)) {
                 customInfo = config._customModuleSources.get(moduleName);
                 isCustomModule = true;
-                if (
-                  customInfo.sourcePath &&
-                  (customInfo.sourcePath.startsWith('_config') || customInfo.sourcePath.includes('_config/custom')) &&
-                  !customInfo.path
-                )
-                  customInfo.path = customInfo.sourcePath;
+                if (customInfo.sourcePath && !customInfo.path) {
+                  customInfo.path = path.isAbsolute(customInfo.sourcePath)
+                    ? customInfo.sourcePath
+                    : path.join(bmadDir, customInfo.sourcePath);
+                }
               }
 
               // Finally check regular custom content
@@ -1375,8 +1378,11 @@ class Installer {
     lines.push(
       '',
       '  Next steps:',
-      `    Docs: ${color.dim('https://docs.bmad-method.org/')}`,
-      `    Run ${color.cyan('/bmad-help')} in your IDE to get started`,
+      `    Read our new Docs Site: ${color.dim('https://docs.bmad-method.org/')}`,
+      `    Join our Discord: ${color.dim('https://discord.gg/gk8jAdXWmj')}`,
+      `    Star us on GitHub: ${color.dim('https://github.com/bmad-code-org/BMAD-METHOD/')}`,
+      `    Subscribe on YouTube: ${color.dim('https://www.youtube.com/@BMadCode')}`,
+      `    Run ${color.cyan('/bmad-help')} with your IDE Agent and ask it how to get started`,
     );
 
     await prompts.note(lines.join('\n'), 'BMAD is ready to use!');
@@ -1528,20 +1534,157 @@ class Installer {
   }
 
   /**
-   * Uninstall BMAD
+   * Uninstall BMAD with selective removal options
+   * @param {string} directory - Project directory
+   * @param {Object} options - Uninstall options
+   * @param {boolean} [options.removeModules=true] - Remove _bmad/ directory
+   * @param {boolean} [options.removeIdeConfigs=true] - Remove IDE configurations
+   * @param {boolean} [options.removeOutputFolder=false] - Remove user artifacts output folder
+   * @returns {Object} Result with success status and removed components
    */
-  async uninstall(directory) {
+  async uninstall(directory, options = {}) {
     const projectDir = path.resolve(directory);
     const { bmadDir } = await this.findBmadDir(projectDir);
 
-    if (await fs.pathExists(bmadDir)) {
-      await fs.remove(bmadDir);
+    if (!(await fs.pathExists(bmadDir))) {
+      return { success: false, reason: 'not-installed' };
     }
 
-    // Clean up IDE configurations
-    await this.ideManager.cleanup(projectDir);
+    // 1. DETECT: Read state BEFORE deleting anything
+    const existingInstall = await this.detector.detect(bmadDir);
+    const outputFolder = await this._readOutputFolder(bmadDir);
 
-    return { success: true };
+    const removed = { modules: false, ideConfigs: false, outputFolder: false };
+
+    // 2. IDE CLEANUP (before _bmad/ deletion so configs are accessible)
+    if (options.removeIdeConfigs !== false) {
+      await this.uninstallIdeConfigs(projectDir, existingInstall, { silent: options.silent });
+      removed.ideConfigs = true;
+    }
+
+    // 3. OUTPUT FOLDER (only if explicitly requested)
+    if (options.removeOutputFolder === true && outputFolder) {
+      removed.outputFolder = await this.uninstallOutputFolder(projectDir, outputFolder);
+    }
+
+    // 4. BMAD DIRECTORY (last, after everything that needs it)
+    if (options.removeModules !== false) {
+      removed.modules = await this.uninstallModules(projectDir);
+    }
+
+    return { success: true, removed, version: existingInstall.version };
+  }
+
+  /**
+   * Uninstall IDE configurations only
+   * @param {string} projectDir - Project directory
+   * @param {Object} existingInstall - Detection result from detector.detect()
+   * @param {Object} [options] - Options (e.g. { silent: true })
+   * @returns {Promise<Object>} Results from IDE cleanup
+   */
+  async uninstallIdeConfigs(projectDir, existingInstall, options = {}) {
+    await this.ideManager.ensureInitialized();
+    const cleanupOptions = { isUninstall: true, silent: options.silent };
+    const ideList = existingInstall.ides || [];
+    if (ideList.length > 0) {
+      return this.ideManager.cleanupByList(projectDir, ideList, cleanupOptions);
+    }
+    return this.ideManager.cleanup(projectDir, cleanupOptions);
+  }
+
+  /**
+   * Remove user artifacts output folder
+   * @param {string} projectDir - Project directory
+   * @param {string} outputFolder - Output folder name (relative)
+   * @returns {Promise<boolean>} Whether the folder was removed
+   */
+  async uninstallOutputFolder(projectDir, outputFolder) {
+    if (!outputFolder) return false;
+    const resolvedProject = path.resolve(projectDir);
+    const outputPath = path.resolve(resolvedProject, outputFolder);
+    if (!outputPath.startsWith(resolvedProject + path.sep)) {
+      return false;
+    }
+    if (await fs.pathExists(outputPath)) {
+      await fs.remove(outputPath);
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Remove the _bmad/ directory
+   * @param {string} projectDir - Project directory
+   * @returns {Promise<boolean>} Whether the directory was removed
+   */
+  async uninstallModules(projectDir) {
+    const { bmadDir } = await this.findBmadDir(projectDir);
+    if (await fs.pathExists(bmadDir)) {
+      await fs.remove(bmadDir);
+      return true;
+    }
+    return false;
+  }
+
+  /**
+   * Get the configured output folder name for a project
+   * Resolves bmadDir internally from projectDir
+   * @param {string} projectDir - Project directory
+   * @returns {string} Output folder name (relative, default: '_bmad-output')
+   */
+  async getOutputFolder(projectDir) {
+    const { bmadDir } = await this.findBmadDir(projectDir);
+    return this._readOutputFolder(bmadDir);
+  }
+
+  /**
+   * Read the output_folder setting from module config files
+   * Checks bmm/config.yaml first, then other module configs
+   * @param {string} bmadDir - BMAD installation directory
+   * @returns {string} Output folder path or default
+   */
+  async _readOutputFolder(bmadDir) {
+    const yaml = require('yaml');
+
+    // Check bmm/config.yaml first (most common)
+    const bmmConfigPath = path.join(bmadDir, 'bmm', 'config.yaml');
+    if (await fs.pathExists(bmmConfigPath)) {
+      try {
+        const content = await fs.readFile(bmmConfigPath, 'utf8');
+        const config = yaml.parse(content);
+        if (config && config.output_folder) {
+          // Strip {project-root}/ prefix if present
+          return config.output_folder.replace(/^\{project-root\}[/\\]/, '');
+        }
+      } catch {
+        // Fall through to other modules
+      }
+    }
+
+    // Scan other module config.yaml files
+    try {
+      const entries = await fs.readdir(bmadDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name === 'bmm' || entry.name.startsWith('_')) continue;
+        const configPath = path.join(bmadDir, entry.name, 'config.yaml');
+        if (await fs.pathExists(configPath)) {
+          try {
+            const content = await fs.readFile(configPath, 'utf8');
+            const config = yaml.parse(content);
+            if (config && config.output_folder) {
+              return config.output_folder.replace(/^\{project-root\}[/\\]/, '');
+            }
+          } catch {
+            // Continue scanning
+          }
+        }
+      }
+    } catch {
+      // Directory scan failed
+    }
+
+    // Default fallback
+    return '_bmad-output';
   }
 
   /**
@@ -2236,15 +2379,35 @@ class Installer {
       const configuredIdes = existingInstall.ides || [];
       const projectRoot = path.dirname(bmadDir);
 
-      // Get custom module sources from cache
+      // Get custom module sources: first from --custom-content (re-cache from source), then from cache
       const customModuleSources = new Map();
+      if (config.customContent?.sources?.length > 0) {
+        for (const source of config.customContent.sources) {
+          if (source.id && source.path && (await fs.pathExists(source.path))) {
+            customModuleSources.set(source.id, {
+              id: source.id,
+              name: source.name || source.id,
+              sourcePath: source.path,
+              cached: false, // From CLI, will be re-cached
+            });
+          }
+        }
+      }
       const cacheDir = path.join(bmadDir, '_config', 'custom');
       if (await fs.pathExists(cacheDir)) {
         const cachedModules = await fs.readdir(cacheDir, { withFileTypes: true });
 
         for (const cachedModule of cachedModules) {
-          if (cachedModule.isDirectory()) {
           const moduleId = cachedModule.name;
+          const cachedPath = path.join(cacheDir, moduleId);
+
+          // Skip if path doesn't exist (broken symlink, deleted dir) - avoids lstat ENOENT
+          if (!(await fs.pathExists(cachedPath))) {
+            continue;
+          }
+          if (!cachedModule.isDirectory()) {
+            continue;
+          }
 
           // Skip if we already have this module from manifest
           if (customModuleSources.has(moduleId)) {
@@ -2258,8 +2421,6 @@ class Installer {
             continue;
           }
 
-            const cachedPath = path.join(cacheDir, moduleId);
-
           // Check if this is actually a custom module (has module.yaml)
           const moduleYamlPath = path.join(cachedPath, 'module.yaml');
           if (await fs.pathExists(moduleYamlPath)) {
@@ -2273,7 +2434,6 @@ class Installer {
           }
         }
       }
-      }
 
       // Load saved IDE configurations
       const savedIdeConfigs = await this.ideConfigManager.loadAllIdeConfigs(bmadDir);
@@ -2407,6 +2567,7 @@ class Installer {
         _savedIdeConfigs: savedIdeConfigs, // Pass saved IDE configs to installer
         _customModuleSources: customModuleSources, // Pass custom module sources for updates
         _existingModules: installedModules, // Pass all installed modules for manifest generation
+        customContent: config.customContent, // Pass through for re-caching from source
       };
 
       // Call the standard install method

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

@@ -456,8 +456,18 @@ LOAD and execute from: {project-root}/{{bmadFolderName}}/{{path}}
   async cleanup(projectDir, options = {}) {
     // Clean all target directories
     if (this.installerConfig?.targets) {
+      const parentDirs = new Set();
       for (const target of this.installerConfig.targets) {
         await this.cleanupTarget(projectDir, target.target_dir, options);
+        // Track parent directories for empty-dir cleanup
+        const parentDir = path.dirname(target.target_dir);
+        if (parentDir && parentDir !== '.') {
+          parentDirs.add(parentDir);
+        }
+      }
+      // After all targets cleaned, remove empty parent directories (recursive up to projectDir)
+      for (const parentDir of parentDirs) {
+        await this.removeEmptyParents(projectDir, parentDir);
       }
     } else if (this.installerConfig?.target_dir) {
       await this.cleanupTarget(projectDir, this.installerConfig.target_dir, options);
@@ -509,6 +519,41 @@ LOAD and execute from: {project-root}/{{bmadFolderName}}/{{path}}
     if (removedCount > 0 && !options.silent) {
       await prompts.log.message(`  Cleaned ${removedCount} BMAD files from ${targetDir}`);
     }
+
+    // Remove empty directory after cleanup
+    if (removedCount > 0) {
+      try {
+        const remaining = await fs.readdir(targetPath);
+        if (remaining.length === 0) {
+          await fs.remove(targetPath);
+        }
+      } catch {
+        // Directory may already be gone or in use — skip
+      }
+    }
+  }
+  /**
+   * Recursively remove empty directories walking up from dir toward projectDir
+   * 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) {
+    let current = relativeDir;
+    let last = null;
+    while (current && current !== '.' && current !== last) {
+      last = current;
+      const fullPath = path.join(projectDir, current);
+      try {
+        if (!(await fs.pathExists(fullPath))) break;
+        const remaining = await fs.readdir(fullPath);
+        if (remaining.length > 0) break;
+        await fs.rmdir(fullPath);
+      } catch {
+        break;
+      }
+      current = path.dirname(current);
+    }
   }
 }
 

tools/cli/installers/lib/ide/codex.js

@@ -23,9 +23,9 @@ class CodexSetup extends BaseIdeSetup {
    * @returns {Object} Collected configuration
    */
   async collectConfiguration(options = {}) {
-    // Non-interactive mode: use default (global)
+    // Non-interactive mode: use default (project) - recommended for real work
     if (options.skipPrompts) {
-      return { installLocation: 'global' };
+      return { installLocation: options.codexLocation || 'project' };
     }
 
     let confirmed = false;

tools/cli/installers/lib/ide/github-copilot.js

@@ -1,6 +1,6 @@
 const path = require('node:path');
 const { BaseIdeSetup } = require('./_base-ide');
-const chalk = require('chalk');
+const prompts = require('../../../lib/prompts');
 const { AgentCommandGenerator } = require('./shared/agent-command-generator');
 const { BMAD_FOLDER_NAME, toDashPath } = require('./shared/path-utils');
 const fs = require('fs-extra');
@@ -31,7 +31,7 @@ class GitHubCopilotSetup extends BaseIdeSetup {
    * @param {Object} options - Setup options
    */
   async setup(projectDir, bmadDir, options = {}) {
-    console.log(chalk.cyan(`Setting up ${this.name}...`));
+    if (!options.silent) await prompts.log.info(`Setting up ${this.name}...`);
 
     // Create .github/agents and .github/prompts directories
     const githubDir = path.join(projectDir, this.githubDir);
@@ -66,21 +66,15 @@ class GitHubCopilotSetup extends BaseIdeSetup {
       const targetPath = path.join(agentsDir, fileName);
       await this.writeFile(targetPath, agentContent);
       agentCount++;
-
-      console.log(chalk.green(`  ✓ Created agent: ${fileName}`));
     }
 
     // Generate prompt files from bmad-help.csv
     const promptCount = await this.generatePromptFiles(projectDir, bmadDir, agentArtifacts, agentManifest);
 
     // Generate copilot-instructions.md
-    await this.generateCopilotInstructions(projectDir, bmadDir, agentManifest);
+    await this.generateCopilotInstructions(projectDir, bmadDir, agentManifest, options);
 
-    console.log(chalk.green(`\n✓ ${this.name} configured:`));
-    console.log(chalk.dim(`  - ${agentCount} agents created in .github/agents/`));
-    console.log(chalk.dim(`  - ${promptCount} prompts created in .github/prompts/`));
-    console.log(chalk.dim(`  - copilot-instructions.md generated`));
-    console.log(chalk.dim(`  - Destination: .github/`));
+    if (!options.silent) await prompts.log.success(`${this.name} configured: ${agentCount} agents, ${promptCount} prompts → .github/`);
 
     return {
       success: true,
@@ -406,7 +400,7 @@ tools: ${toolsStr}
    * @param {string} bmadDir - BMAD installation directory
    * @param {Map} agentManifest - Agent manifest data
    */
-  async generateCopilotInstructions(projectDir, bmadDir, agentManifest) {
+  async generateCopilotInstructions(projectDir, bmadDir, agentManifest, options = {}) {
     const configVars = await this.loadModuleConfig(bmadDir);
 
     // Build the agents table from the manifest
@@ -495,19 +489,16 @@ Type \`/bmad-\` in Copilot Chat to see all available BMAD workflows and agent ac
         const after = existing.slice(endIdx + markerEnd.length);
         const merged = `${before}${markedContent}${after}`;
         await this.writeFile(instructionsPath, merged);
-        console.log(chalk.green('  ✓ Updated BMAD section in copilot-instructions.md'));
       } else {
         // Existing file without markers — back it up before overwriting
         const backupPath = `${instructionsPath}.bak`;
         await fs.copy(instructionsPath, backupPath);
-        console.log(chalk.yellow(`  ⚠ Backed up existing copilot-instructions.md → copilot-instructions.md.bak`));
+        if (!options.silent) await prompts.log.warn(`  Backed up copilot-instructions.md → .bak`);
         await this.writeFile(instructionsPath, `${markedContent}\n`);
-        console.log(chalk.green('  ✓ Generated copilot-instructions.md (with BMAD markers)'));
       }
     } else {
       // No existing file — create fresh with markers
       await this.writeFile(instructionsPath, `${markedContent}\n`);
-      console.log(chalk.green('  ✓ Generated copilot-instructions.md'));
     }
   }
 
@@ -607,7 +598,7 @@ Type \`/bmad-\` in Copilot Chat to see all available BMAD workflows and agent ac
   /**
    * Cleanup GitHub Copilot configuration - surgically remove only BMAD files
    */
-  async cleanup(projectDir) {
+  async cleanup(projectDir, options = {}) {
     // Clean up agents directory
     const agentsDir = path.join(projectDir, this.githubDir, this.agentsDir);
     if (await fs.pathExists(agentsDir)) {
@@ -621,8 +612,8 @@ Type \`/bmad-\` in Copilot Chat to see all available BMAD workflows and agent ac
         }
       }
 
-      if (removed > 0) {
-        console.log(chalk.dim(`  Cleaned up ${removed} existing BMAD agents`));
+      if (removed > 0 && !options.silent) {
+        await prompts.log.message(`  Cleaned up ${removed} existing BMAD agents`);
       }
     }
 
@@ -639,16 +630,70 @@ Type \`/bmad-\` in Copilot Chat to see all available BMAD workflows and agent ac
         }
       }
 
-      if (removed > 0) {
-        console.log(chalk.dim(`  Cleaned up ${removed} existing BMAD prompts`));
+      if (removed > 0 && !options.silent) {
+        await prompts.log.message(`  Cleaned up ${removed} existing BMAD prompts`);
       }
     }
 
-    // Note: copilot-instructions.md is NOT cleaned up here.
-    // generateCopilotInstructions() handles marker-based replacement in a single
-    // read-modify-write pass, which correctly preserves user content outside the markers.
-    // Stripping markers here would cause generation to treat the file as legacy (no markers)
-    // and overwrite user content.
+    // During uninstall, also strip BMAD markers from copilot-instructions.md.
+    // During reinstall (default), this is skipped because generateCopilotInstructions()
+    // handles marker-based replacement in a single read-modify-write pass,
+    // which correctly preserves user content outside the markers.
+    if (options.isUninstall) {
+      await this.cleanupCopilotInstructions(projectDir, options);
+    }
+  }
+
+  /**
+   * Strip BMAD marker section from copilot-instructions.md
+   * If file becomes empty after stripping, delete it.
+   * If a .bak backup exists and the main file was deleted, restore the backup.
+   * @param {string} projectDir - Project directory
+   * @param {Object} [options] - Options (e.g. { silent: true })
+   */
+  async cleanupCopilotInstructions(projectDir, options = {}) {
+    const instructionsPath = path.join(projectDir, this.githubDir, 'copilot-instructions.md');
+    const backupPath = `${instructionsPath}.bak`;
+
+    if (!(await fs.pathExists(instructionsPath))) {
+      return;
+    }
+
+    const content = await fs.readFile(instructionsPath, 'utf8');
+    const markerStart = '<!-- BMAD:START -->';
+    const markerEnd = '<!-- BMAD:END -->';
+    const startIdx = content.indexOf(markerStart);
+    const endIdx = content.indexOf(markerEnd);
+
+    if (startIdx === -1 || endIdx === -1 || endIdx <= startIdx) {
+      return; // No valid markers found
+    }
+
+    // Strip the marker section (including markers)
+    const before = content.slice(0, startIdx);
+    const after = content.slice(endIdx + markerEnd.length);
+    const cleaned = before + after;
+
+    if (cleaned.trim().length === 0) {
+      // File is empty after stripping — delete it
+      await fs.remove(instructionsPath);
+
+      // If backup exists, restore it
+      if (await fs.pathExists(backupPath)) {
+        await fs.rename(backupPath, instructionsPath);
+        if (!options.silent) {
+          await prompts.log.message('  Restored copilot-instructions.md from backup');
+        }
+      }
+    } else {
+      // Write cleaned content back (preserve original whitespace)
+      await fs.writeFile(instructionsPath, cleaned, 'utf8');
+
+      // If backup exists, it's stale now — remove it
+      if (await fs.pathExists(backupPath)) {
+        await fs.remove(backupPath);
+      }
+    }
   }
 }
 

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

@@ -216,13 +216,14 @@ class IdeManager {
   /**
    * Cleanup IDE configurations
    * @param {string} projectDir - Project directory
+   * @param {Object} [options] - Cleanup options passed through to handlers
    */
-  async cleanup(projectDir) {
+  async cleanup(projectDir, options = {}) {
     const results = [];
 
     for (const [name, handler] of this.handlers) {
       try {
-        await handler.cleanup(projectDir);
+        await handler.cleanup(projectDir, options);
         results.push({ ide: name, success: true });
       } catch (error) {
         results.push({ ide: name, success: false, error: error.message });
@@ -232,6 +233,40 @@ class IdeManager {
     return results;
   }
 
+  /**
+   * Cleanup only the IDEs in the provided list
+   * Falls back to cleanup() (all handlers) if ideList is empty or undefined
+   * @param {string} projectDir - Project directory
+   * @param {Array<string>} ideList - List of IDE names to clean up
+   * @param {Object} [options] - Cleanup options passed through to handlers
+   * @returns {Array} Results array
+   */
+  async cleanupByList(projectDir, ideList, options = {}) {
+    if (!ideList || ideList.length === 0) {
+      return this.cleanup(projectDir, options);
+    }
+
+    await this.ensureInitialized();
+    const results = [];
+
+    // Build lowercase lookup for case-insensitive matching
+    const lowercaseHandlers = new Map([...this.handlers.entries()].map(([k, v]) => [k.toLowerCase(), v]));
+
+    for (const ideName of ideList) {
+      const handler = lowercaseHandlers.get(ideName.toLowerCase());
+      if (!handler) continue;
+
+      try {
+        await handler.cleanup(projectDir, options);
+        results.push({ ide: ideName, success: true });
+      } catch (error) {
+        results.push({ ide: ideName, success: false, error: error.message });
+      }
+    }
+
+    return results;
+  }
+
   /**
    * Get list of supported IDEs
    * @returns {Array} List of supported IDE names

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

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

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

@@ -1,10 +1,12 @@
 ---
+name: '{{name}}'
 description: '{{description}}'
 ---
 
 Execute the BMAD '{{name}}' task.
 
 TASK INSTRUCTIONS:
+
 1. LOAD the task file from {project-root}/{{bmadFolderName}}/{{path}}
 2. READ its entire contents
 3. FOLLOW every instruction precisely as specified

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

@@ -1,10 +1,12 @@
 ---
+name: '{{name}}'
 description: '{{description}}'
 ---
 
 Execute the BMAD '{{name}}' tool.
 
 TOOL INSTRUCTIONS:
+
 1. LOAD the tool file from {project-root}/{{bmadFolderName}}/{{path}}
 2. READ its entire contents
 3. FOLLOW every instruction precisely as specified

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

@@ -1,4 +1,5 @@
 ---
+name: '{{name}}'
 description: '{{description}}'
 ---
 
@@ -7,6 +8,7 @@ Execute the BMAD '{{name}}' workflow.
 CRITICAL: You must load and follow the workflow definition exactly.
 
 WORKFLOW INSTRUCTIONS:
+
 1. LOAD the workflow file from {project-root}/{{bmadFolderName}}/{{path}}
 2. READ its entire contents
 3. FOLLOW every step precisely as specified

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

@@ -1,4 +1,5 @@
 ---
+name: '{{name}}'
 description: '{{description}}'
 ---
 
@@ -7,6 +8,7 @@ Execute the BMAD '{{name}}' workflow.
 CRITICAL: You must load and follow the workflow definition exactly.
 
 WORKFLOW INSTRUCTIONS:
+
 1. LOAD the workflow file from {project-root}/{{bmadFolderName}}/{{path}}
 2. READ its entire contents
 3. FOLLOW every step precisely as specified

tools/cli/installers/lib/modules/manager.js

@@ -734,8 +734,10 @@ class ModuleManager {
         continue;
       }
 
-      // Skip config.yaml templates - we'll generate clean ones with actual values
-      if (file === 'config.yaml' || file.endsWith('/config.yaml')) {
+      // Skip module root config.yaml only - generated by config collector with actual values
+      // Workflow-level config.yaml (e.g. workflows/orchestrate-story/config.yaml) must be copied
+      // for custom modules that use workflow-specific configuration
+      if (file === 'config.yaml') {
         continue;
       }
 

tools/cli/lib/ui.js

@@ -245,11 +245,48 @@ class UI {
 
       // Handle quick update separately
       if (actionType === 'quick-update') {
-        // Quick update doesn't install custom content - just updates existing modules
+        // Pass --custom-content through so installer can re-cache if cache is missing
+        let customContentForQuickUpdate = { hasCustomContent: false };
+        if (options.customContent) {
+          const paths = options.customContent
+            .split(',')
+            .map((p) => p.trim())
+            .filter(Boolean);
+          if (paths.length > 0) {
+            const customPaths = [];
+            const selectedModuleIds = [];
+            const sources = [];
+            for (const customPath of paths) {
+              const expandedPath = this.expandUserPath(customPath);
+              const validation = this.validateCustomContentPathSync(expandedPath);
+              if (validation) continue;
+              let moduleMeta;
+              try {
+                const moduleYamlPath = path.join(expandedPath, 'module.yaml');
+                moduleMeta = require('yaml').parse(await fs.readFile(moduleYamlPath, 'utf-8'));
+              } catch {
+                continue;
+              }
+              if (!moduleMeta?.code) continue;
+              customPaths.push(expandedPath);
+              selectedModuleIds.push(moduleMeta.code);
+              sources.push({ path: expandedPath, id: moduleMeta.code, name: moduleMeta.name || moduleMeta.code });
+            }
+            if (customPaths.length > 0) {
+              customContentForQuickUpdate = {
+                hasCustomContent: true,
+                selected: true,
+                sources,
+                selectedFiles: customPaths.map((p) => path.join(p, 'module.yaml')),
+                selectedModuleIds,
+              };
+            }
+          }
+        }
         return {
           actionType: 'quick-update',
           directory: confirmedDirectory,
-          customContent: { hasCustomContent: false },
+          customContent: customContentForQuickUpdate,
           skipPrompts: options.yes || false,
         };
       }
@@ -305,6 +342,7 @@ class UI {
           // Build custom content config similar to promptCustomContentSource
           const customPaths = [];
           const selectedModuleIds = [];
+          const sources = [];
 
           for (const customPath of paths) {
             const expandedPath = this.expandUserPath(customPath);
@@ -326,6 +364,11 @@ class UI {
               continue;
             }
 
+            if (!moduleMeta) {
+              await prompts.log.warn(`Skipping custom content path: ${customPath} - module.yaml is empty`);
+              continue;
+            }
+
             if (!moduleMeta.code) {
               await prompts.log.warn(`Skipping custom content path: ${customPath} - module.yaml missing 'code' field`);
               continue;
@@ -333,6 +376,11 @@ class UI {
 
             customPaths.push(expandedPath);
             selectedModuleIds.push(moduleMeta.code);
+            sources.push({
+              path: expandedPath,
+              id: moduleMeta.code,
+              name: moduleMeta.name || moduleMeta.code,
+            });
           }
 
           if (customPaths.length > 0) {
@@ -340,7 +388,9 @@ class UI {
               selectedCustomModules: selectedModuleIds,
               customContentConfig: {
                 hasCustomContent: true,
-                paths: customPaths,
+                selected: true,
+                sources,
+                selectedFiles: customPaths.map((p) => path.join(p, 'module.yaml')),
                 selectedModuleIds: selectedModuleIds,
               },
             };
@@ -446,6 +496,7 @@ class UI {
       // Build custom content config similar to promptCustomContentSource
       const customPaths = [];
       const selectedModuleIds = [];
+      const sources = [];
 
       for (const customPath of paths) {
         const expandedPath = this.expandUserPath(customPath);
@@ -467,6 +518,11 @@ class UI {
           continue;
         }
 
+        if (!moduleMeta) {
+          await prompts.log.warn(`Skipping custom content path: ${customPath} - module.yaml is empty`);
+          continue;
+        }
+
         if (!moduleMeta.code) {
           await prompts.log.warn(`Skipping custom content path: ${customPath} - module.yaml missing 'code' field`);
           continue;
@@ -474,12 +530,19 @@ class UI {
 
         customPaths.push(expandedPath);
         selectedModuleIds.push(moduleMeta.code);
+        sources.push({
+          path: expandedPath,
+          id: moduleMeta.code,
+          name: moduleMeta.name || moduleMeta.code,
+        });
       }
 
       if (customPaths.length > 0) {
         customContentConfig = {
           hasCustomContent: true,
-          paths: customPaths,
+          selected: true,
+          sources,
+          selectedFiles: customPaths.map((p) => path.join(p, 'module.yaml')),
           selectedModuleIds: selectedModuleIds,
         };
       }