Merge 4fd8b9018f into e37edf098c

Major improvements include:
- Revolutionary installer overhaul with unified flow for core and custom modules
- Full custom content support re-enabled with streamlined sharing
- Critical migration from .bmad to _bmad for AI visibility
- Agent memory system rollout with _bmad/_memory location
- Quick default selection for faster module installation
- BMM Phase 4 workflow improvements and standardization
- Sample modules demonstrating custom content creation
- Future-ready architecture for content segregation

CHANGELOG.md

@@ -1,5 +1,101 @@
 # Changelog
 
+## [6.0.0-alpha.17]
+
+**Release: December 16, 2025**
+
+### 🚀 Revolutionary Installer Overhaul
+
+**Unified Installation Experience:**
+
+- **Streamlined Module Installation**: Completely redesigned installer with unified flow for both core and custom content
+- **Single Install Panel**: Eliminated disjointed clearing between modules for smoother, more intuitive installation
+- **Quick Default Selection**: New quick install feature with default selections for faster setup of selected modules
+- **Enhanced UI/UX**: Improved question order, reduced verbose output, and cleaner installation interface
+- **Logical Question Flow**: Reorganized installer questions to follow natural progression and user expectations
+
+**Custom Content Installation Revolution:**
+
+- **Full Custom Content Support**: Re-enabled complete custom content generation and sharing through the installer
+- **Custom Module Tracking**: Manifest now tracks custom modules separately to ensure they're always installed from the custom cache
+- **Custom Installation Order**: Custom modules now install after core modules for better dependency management
+- **Quick Update with Custom Content**: Quick update now properly retains and updates custom content
+- **Agent Customization Integration**: Customizations are now applied during quick updates and agent compilation
+
+### 🧠 Revolutionary Agent Memory & Visibility System
+
+**Breaking Through Dot-Folder Limitations:**
+
+- **Dot-Folder to Underscore Migration**: Critical change from `.bmad` to `_bmad` ensures LLMs (Codex, Claude, and others) can no longer ignore or skip BMAD content - dot folders are commonly filtered out by AI systems
+- **Universal Content Visibility**: Underscore folders are treated as regular content, ensuring full AI agent access to all BMAD resources and configurations
+- **Agent Memory Architecture**: Rolled out comprehensive agent memory support for installed agents with `-sidecar` folders
+- **Persistent Agent Learning**: Sidecar content installs to `_bmad/_memory`, giving each agent the ability to learn and remember important information specific to its role
+
+**Content Location Strategy:**
+
+- **Standardized Memory Location**: All sidecar content now uses `_bmad/_memory` as the unified location for agent memories
+- **Segregated Output System**: New architecture supports differentiating between ephemeral Phase 4 artifacts and long-term documentation
+- **Forward Compatibility**: Existing installations continue working with content in docs folder, with optimization coming in next release
+- **Configuration Cleanup**: Renamed `_cfg` to `_config` for clearer naming conventions
+- **YAML Library Consolidation**: Reduced dependency to use only one YAML library for better stability
+
+### 🎯 Future-Ready Architecture
+
+**Content Organization Preview:**
+
+- **Phase 4 Artifact Segregation**: Infrastructure ready for separating ephemeral workflow artifacts from permanent documentation
+- **Planning vs Implementation Docs**: New system will differentiate between planning artifacts and long-term project documentation
+- **Backward Compatibility**: Current installs maintain full functionality while preparing for optimized content organization
+- **Quick Update Path**: Tomorrow's quick update will fully optimize all BMM workflows to use new segregated output locations
+
+### 🎯 Sample Modules & Documentation
+
+**Comprehensive Examples:**
+
+- **Sample Unitary Module**: Complete example with commit-poet agent and quiz-master workflow
+- **Sample Wellness Module**: Meditation guide and wellness companion agents demonstrating advanced patterns
+- **Enhanced Documentation**: Updated README files and comprehensive installation guides
+- **Custom Content Creation Guides**: Step-by-step documentation for creating and sharing custom modules
+
+### 🔧 Bug Fixes & Optimizations
+
+**Installer Improvements:**
+
+- **Fixed Duplicate Entry Issue**: Resolved duplicate entries in files manifest
+- **Reduced Log Noise**: Less verbose logging during installation for cleaner user experience
+- **Menu Wording Updates**: Improved menu text for better clarity and understanding
+- **Fixed Quick Install**: Resolved issues with quick installation functionality
+
+**Code Quality:**
+
+- **Minor Code Cleanup**: General cleanup and refactoring throughout the codebase
+- **Removed Unused Code**: Cleaned up deprecated and unused functionality
+- **Release Workflow Restoration**: Fixed automated release workflow for v6
+
+**BMM Phase 4 Workflow Improvements:**
+
+- **Sprint Status Enhancement**: Improved sprint-status validation with interactive correction for unknown values and better epic status handling
+- **Story Status Standardization**: Normalized all story status references to lowercase kebab-case (ready-for-dev, in-progress, review, done)
+- **Removed Stale Story State**: Eliminated deprecated 'drafted' story state - stories now go directly from creation to ready-for-dev
+- **Code Review Clarity**: Improved code review completion message from "Story is ready for next work!" to "Code review complete!" for better clarity
+- **Risk Detection Rules**: Rewrote risk detection rules for better LLM clarity and fixed warnings vs risks naming inconsistency
+
+### 📊 Statistics
+
+- **40+ commits** since alpha.16
+- **Major installer refactoring** with complete UX overhaul
+- **2 new sample modules** with comprehensive examples
+- **Full custom content support** re-enabled and improved
+
+### 🌟 Key Highlights
+
+1. **Installer Revolution**: The installation system has been completely overhauled for better user experience, reliability, and speed
+2. **Custom Content Freedom**: Users can now easily create, share, and install custom content through the streamlined installer
+3. **AI Visibility Breakthrough**: Migration from `.bmad` to `_bmad` ensures LLMs can access all BMAD content (dot folders are commonly ignored by AI systems)
+4. **Agent Memory System**: Rolled out persistent agent memory support - agents with `-sidecar` folders can now learn and remember important information in `_bmad/_memory`
+5. **Quick Default Selection**: Installation is now faster with smart default selections for popular configurations
+6. **Future-Ready Architecture**: Infrastructure in place for segregating ephemeral artifacts from permanent documentation (full optimization coming in next release)
+
 ## [6.0.0-alpha.16]
 
 **Release: December 10, 2025**

README.md

@@ -6,6 +6,33 @@
 [![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)
 
+---
+
+<div align="center">
+
+## 🎉 NEW: BMAD V6 Installer - Create & Share Custom Content!
+
+The completely revamped **BMAD V6 installer** now includes built-in support for creating, installing, and sharing custom modules, agents, workflows, templates, and tools! Build your own AI solutions or share them with your team - and real soon, with the whole BMad Community througha verified community sharing portal!
+
+**✨ What's New:**
+
+- 📦 **Streamlined Custom Module Installation** - Package your custom content as installable modules
+- 🤖 **Agent & Workflow Sharing** - Distribute standalone agents and workflows
+- 🔄 **Unitary Module Support** - Install individual components without full modules
+- ⚙️ **Dependency Management** - Automatic handling of module dependencies
+- 🛡️ **Update-Safe Customization** - Your custom content persists through updates
+
+**📚 Learn More:**
+
+- [**Custom Content Overview**](./docs/custom-content.md) - Discover all supported content types
+- [**Installation Guide**](./docs/custom-content-installation.md) - Learn to create and install custom content
+- [**Detail Content Docs**](./src/modules/bmb/docs/README.md) - Reference details for agents, modules, workflows and the bmad builder
+- [**2 Very simple Custom Modules of questionable quality**](./docs/sample-custom-modules/README.md) - if you want to download and try to install a custom shared module, get an idea of how to bundle and share your own, or create your own personal agents, workflows and modules.
+
+</div>
+
+---
+
 ## AI-Driven Agile Development That Scales From Bug Fixes to Enterprise
 
 **Build More, Architect Dreams** (BMAD) with **21 specialized AI agents** across 4 official modules, and **50+ guided workflows** that adapt to your project's complexity—from quick bug fixes to enterprise platforms, and new step file workflows that allow for incredibly long workflows to stay on the rails longer than ever before!
@@ -120,7 +147,7 @@ Each agent brings deep expertise and can be customized to match your team's styl
 - **BMad Builder (BMB)** - Create custom agents and workflows
   - Build anything from simple agents to complex modules
   - Create domain-specific solutions (legal, medical, finance, education)
-  - Share your creations in the upcoming community marketplace
+  - [→ Builder Guide](src/modules/bmb/docs/README.md) marketplace
   - [→ Builder Guide](./src/modules/bmb/README.md)
 
 - **Creative Intelligence Suite (CIS)** - Innovation & problem-solving

docs/agent-preflight-protocol.md

@@ -0,0 +1,383 @@
+# BMad Method PR #2: Agent Task Pre-Flight Protocol
+
+**Feature Type**: Safety & quality framework
+**Status**: Draft for community review
+**Origin**: tellingCube project learnings (masemIT e.U.)
+**Author**: Mario Semper (@sempre)
+**Date**: 2025-11-23
+
+---
+
+## Summary
+
+**Agent Task Pre-Flight Protocol** establishes mandatory safety checks for high-risk agent tasks (marketing, legal, deployment) to prevent factual errors, trademark violations, privacy breaches, and assumption-based mistakes.
+
+---
+
+## Problem Statement
+
+### Real-World Failure Case
+
+**Scenario**: Marketing agent (Sophie) created LinkedIn launch posts for tellingCube without:
+- Reading existing project documentation
+- Verifying pricing against actual implementation
+- Checking trademark compliance rules
+- Reviewing privacy guidelines
+
+**Result**: Multiple critical errors:
+- ❌ Mentioned user's day job title (privacy/legal risk)
+- ❌ Used family member's name (privacy violation)
+- ❌ Claimed "60 seconds" generation time (factually wrong)
+- ❌ Advertised "€9/month" pricing (doesn't exist - actual: €29-€999 ONE-TIME)
+- ❌ Used "IBCS-compliant" (trademark violation - should be "inspired by IBCS©")
+
+**Root Cause**: Agent operated independently without pre-task verification protocol.
+
+---
+
+## Current BMad Behavior (Risky)
+
+```yaml
+User: "Sophie, create LinkedIn launch posts"
+
+Sophie:
+  1. Generates content based on general knowledge
+  2. Makes assumptions about features/pricing
+  3. Uses marketing best practices
+  4. Presents to user
+
+❌ Problem: No verification step before creation
+```
+
+---
+
+## Proposed Solution: Pre-Flight Protocol
+
+### Mandatory Checks Before High-Risk Tasks
+
+```yaml
+Agent Task Pre-Flight Protocol:
+
+BEFORE executing tasks with external impact:
+  1. Discover Critical Context
+     - Search for CRITICAL-GUIDELINES.md or similar
+     - Read recent related work in project
+     - Check actual implementation (code, configs, not assumptions)
+
+  2. Verify Assumptions
+     - Pricing: Read Stripe config / pricing components
+     - Features: Grep codebase for actual capabilities
+     - Legal/Trademark: Check documented compliance rules
+     - Privacy: Verify no personal info in public content
+
+  3. Cross-Agent Review (for high-risk outputs)
+     - Orchestrator reviews before user sees
+     - Fact-checker agent validates claims
+     - Minimum 2 agents verify before publishing
+
+  4. User Approval Gate
+     - Present content as DRAFT
+     - Highlight assumptions made
+     - Get explicit approval before finalizing
+```
+
+---
+
+## High-Risk Task Categories
+
+### 1. Marketing & Public Content
+**Examples**: LinkedIn posts, press releases, demo videos, website copy
+
+**Pre-Flight Required**:
+- [ ] Read `CRITICAL-GUIDELINES.md` (legal, trademark, privacy rules)
+- [ ] Verify pricing from actual Stripe/payment config
+- [ ] Verify features from actual codebase (not roadmap ideas)
+- [ ] Check trademark compliance (e.g., "IBCS©" usage rules)
+- [ ] Privacy review (no personal identifiers without consent)
+- [ ] Cross-agent fact-check before presenting to user
+
+### 2. Legal & Compliance
+**Examples**: Terms of service, privacy policy, license agreements
+
+**Pre-Flight Required**:
+- [ ] Read existing legal docs (don't start from scratch)
+- [ ] Check jurisdiction-specific requirements
+- [ ] Verify against actual product behavior (data handling, cookies, etc.)
+- [ ] Legal expert review (human or specialized agent)
+- [ ] User final approval required
+
+### 3. Deployment & Infrastructure
+**Examples**: Database migrations, production deployments, DNS changes
+
+**Pre-Flight Required**:
+- [ ] Read deployment runbooks/checklists
+- [ ] Verify current production state
+- [ ] Check for breaking changes
+- [ ] Backup strategy confirmed
+- [ ] Rollback plan documented
+- [ ] User explicit approval with understanding of risks
+
+### 4. Financial & Billing
+**Examples**: Stripe configuration, pricing changes, refund policies
+
+**Pre-Flight Required**:
+- [ ] Read current Stripe dashboard state
+- [ ] Verify tax/legal implications
+- [ ] Check grandfather clause impacts
+- [ ] Financial impact assessment
+- [ ] User approval with revenue projections
+
+---
+
+## Implementation Guidelines
+
+### For Agent Developers
+
+**In agent YAML definition**:
+
+```yaml
+agent:
+  name: Sophie
+  id: marketing
+  high_risk_tasks: true  # Triggers pre-flight protocol
+
+pre_flight:
+  required_reads:
+    - docs/marketing/CRITICAL-GUIDELINES.md
+    - components/landing/PricingSection.tsx
+    - docs/_masemIT/readme.md
+
+  verification_steps:
+    - Grep for actual pricing tiers in codebase
+    - Check trademark compliance rules
+    - Privacy scan (no personal names/details)
+
+  cross_check:
+    agents: [river, mary]
+    approval_required: true
+
+tasks:
+  create-linkedin-post:
+    pre_flight_mandatory: true
+    approval_gate: user
+```
+
+### For Orchestrators (River-like agents)
+
+**Orchestrator responsibilities**:
+
+```python
+def execute_high_risk_task(agent, task, user_request):
+    # Step 1: Pre-flight checks
+    critical_docs = discover_critical_guidelines()
+    agent.read(critical_docs)
+
+    # Step 2: Agent executes with verification
+    draft_output = agent.execute_task(task)
+
+    # Step 3: Cross-agent review
+    fact_check_agent = get_agent("mary")
+    verification = fact_check_agent.verify(draft_output, codebase)
+
+    # Step 4: Present as DRAFT to user
+    if verification.has_issues:
+        present_issues_to_user(verification.issues)
+
+    present_as_draft(draft_output)
+
+    # Step 5: User approval gate
+    approval = get_user_approval()
+
+    if approval:
+        finalize(draft_output)
+```
+
+---
+
+## Example: Correct Marketing Flow
+
+### Before (Risky)
+
+```
+User: "Create LinkedIn launch posts"
+Sophie: [Generates 3 posts with assumptions]
+Sophie: "Here are your posts!"
+
+❌ Contains errors user must catch
+```
+
+### After (Safe)
+
+```
+User: "Create LinkedIn launch posts"
+
+River: "Sophie, this is a high-risk task. Running pre-flight..."
+
+Sophie:
+  ✅ Read CRITICAL-GUIDELINES.md
+  ✅ Read PricingSection.tsx (actual pricing: €29-€999)
+  ✅ Checked IBCS© compliance rules (must say "inspired by")
+  ✅ Privacy check (no "Product Owner", no "brother")
+
+Sophie: [Generates 3 posts with verified facts]
+
+River: "Mary, fact-check Sophie's output..."
+
+Mary:
+  ✅ Pricing correct (€29-€999 lifetime)
+  ✅ No trademark violations ("inspired by IBCS©")
+  ✅ No privacy issues
+  ✅ Generation time accurate ("minutes")
+
+River: "Sempre, here's the DRAFT (pre-flight verified). Approve?"
+
+User: [Reviews, approves]
+
+✅ No errors, factually accurate
+```
+
+---
+
+## Critical Guidelines Template
+
+**Every project should have**: `docs/PROJECT-NAME/CRITICAL-GUIDELINES.md`
+
+```markdown
+# CRITICAL Guidelines for [Project Name]
+
+## ❌ NEVER MENTION
+- Confidential info (list specific items)
+- Personal details (family, private life)
+- Competitor names (if under NDA)
+
+## ✅ ALWAYS VERIFY
+- Pricing: Check [file path]
+- Features: Grep [codebase location]
+- Legal: Comply with [trademark/license rules]
+
+## Trademark Compliance
+- "IBCS©" → Always say "inspired by IBCS©" (not "compliant")
+- [Other trademarks...]
+
+## Privacy Rules
+- No personal job titles in public content
+- No family member names
+- [Other privacy rules...]
+
+## Approval Requirements
+- Marketing content: River + Mary review
+- Legal docs: Legal expert review
+- Deployment: User explicit approval
+```
+
+---
+
+## Benefits
+
+✅ **Prevents costly mistakes** - Catches errors before they're public
+✅ **Protects legal compliance** - Trademark, privacy, licensing
+✅ **Ensures factual accuracy** - Features/pricing match reality
+✅ **Builds user trust** - Agents don't hallucinate facts
+✅ **Scalable safety** - Works across all BMad projects
+
+---
+
+## Tradeoffs & Considerations
+
+### Slower Task Execution
+- **Before**: Agent outputs in 30 seconds
+- **After**: Pre-flight adds 1-2 minutes
+- **Worth it?**: YES for high-risk tasks (marketing, legal, deployment)
+
+### More Agent Coordination
+- Requires orchestrator (River) to manage pre-flight
+- Cross-agent reviews add complexity
+- **Mitigation**: Only for high-risk tasks, not every task
+
+### User Approval Friction
+- Adds approval gate before finalization
+- **Mitigation**: Present as DRAFT with verification status
+- User can fast-track if comfortable
+
+---
+
+## Rollout Strategy
+
+### Phase 1: Opt-In (Recommended)
+- Projects mark agents as `high_risk_tasks: true`
+- Orchestrators enforce pre-flight for marked agents
+- Community feedback on friction/benefits
+
+### Phase 2: Default for Risky Categories
+- Marketing, legal, deployment agents default to pre-flight
+- Other agents opt-in if needed
+
+### Phase 3: Configurable Per-Task
+- Users set risk level per task
+- `*create-post --risk high` triggers pre-flight
+- `*create-post --risk low` skips for drafts
+
+---
+
+## Real-World Validation
+
+**Origin Project**: tellingCube (masemIT e.U.)
+
+**Failure Scenario**:
+- Marketing agent created launch posts without verification
+- 5 critical errors caught by user (should have been caught earlier)
+- 30 minutes of rework to fix
+
+**After Implementing Protocol**:
+- CRITICAL-GUIDELINES.md created
+- Pre-flight checklist enforced
+- Cross-agent review (River → Sophie → Mary → User)
+- **Result**: Zero errors in final content
+
+**User Feedback (Mario Semper)**:
+> "I love BMad, but I don't want to repeat the ChatGPT hallucination nightmare. This protocol gives me confidence that agents verify facts before presenting them."
+
+---
+
+## Open Questions for Community
+
+1. **Scope**: Which task types should default to pre-flight?
+2. **Performance**: Is 1-2 minute overhead acceptable for high-risk tasks?
+3. **Configurability**: Per-project, per-agent, or per-task risk settings?
+4. **Tooling**: Should pre-flight be a separate tool or built into agent execution?
+5. **Enforcement**: Optional best practice or mandatory for certain agents?
+
+---
+
+## Next Steps
+
+1. **Community feedback** on protocol design
+2. **Reference implementation** in BMad core
+3. **Agent template updates** to include pre-flight hooks
+4. **Documentation** with examples for common scenarios
+5. **Testing** across different project types
+
+---
+
+## Comparison to Similar Patterns
+
+| Pattern | Focus | When to Use |
+|---------|-------|-------------|
+| **Pre-Flight Protocol** | Safety & accuracy | High-risk external outputs |
+| **Code Review** | Code quality | Before merging code |
+| **QA Gates** | Testing | Before production deployment |
+| **Approval Workflows** | Governance | Multi-stakeholder decisions |
+
+**Pre-Flight Protocol** = "Code review + QA gate" for **agent outputs**.
+
+---
+
+## References
+
+- **Source Project**: tellingCube (https://github.com/masemIT/telling-cube) [if public]
+- **Failure Case**: `docs/bmad-contributions/` (this document)
+- **Implementation**: `docs/marketing/CRITICAL-GUIDELINES.md` (tellingCube)
+
+---
+
+**Contribution ready for review.** This came from painful real-world experience - let's make BMad safer for everyone! 🛡️

docs/custom-content-installation.md

@@ -1,245 +1,149 @@
 # Custom Content Installation
 
-This guide explains how to create and install custom BMAD content including agents, workflows, and modules. Custom content allows you to extend BMAD's functionality with your own specialized tools and workflows that can be shared across projects or teams.
+This guide explains how to create and install custom BMAD content including agents, workflows, and modules. Custom content extends BMAD's functionality with specialized tools and workflows that can be shared across projects or teams.
 
-## Types of Custom Content
+For detailed information about the different types of custom content available, see [Custom Content](./custom-content.md).
 
-### 1. Custom Agents and Workflows (Standalone)
+If you download either of the folders within the [Sample Custom Modules](./sample-custom-modules/readme.md) folder
 
-Custom agents and workflows are standalone content packages that can be installed without being part of a full module. These are perfect for:
+## Content Types Overview
 
-- Sharing specialized agents across projects
-- Building a personal Agent powered Notebook vault
-- Distributing workflow templates
-- Creating agent libraries for specific domains
+BMAD Core supports several categories of custom content:
 
-#### Structure
+- Custom Stand Alone Modules
+- Custom Add On Modules
+- Custom Global Modules
+- Custom Agents
+- Custom Workflows
 
-A custom agents and workflows package follows this structure:
+## Making Custom Content Installable
 
-```
-my-custom-agents/
-├── module.yaml          # Package configuration
-├── agents/              # Agent definitions
-│   └── my-agent/
-│       └── agent.md
-└── workflows/           # Workflow definitions
-    └── my-workflow/
-        └── workflow.md
-```
+### Custom Modules
 
-#### Configuration
+To create an installable custom module:
 
-Create a `module.yaml` file in your package root:
+1. **Folder Structure**
+   - Create a folder with a short, abbreviated name (e.g., `cis` for Creative Intelligence Suite)
+   - The folder name serves as the module code
 
-```yaml
-code: my-custom-agents
-name: 'My Custom Agents and Workflows'
-default_selected: true
-```
+2. **Required Files**
+   - Include a `module.yaml` file in the root folder
+   - This file drives the installation process when used by the BMAD installer
+   - Reference existing modules or the BMad Builder for configuration examples
 
-#### Example
+3. **Folder Organization**
+   Follow these conventions for optimal compatibility:
 
-See `/example-custom-content` for a working example of a folder with multiple random custom agents and workflows. Technically its also just a module, but you will be able to further pick and choose from this folders contents of what you do and do not want to include in a destination folder. This way, you can store all custom content source in one location and easily install it to different locations.
+   ```
+   module-code/
+     module.yaml
+     agents/
+     workflows/
+     tools/
+     templates/
+     ...
+   ```
 
-### 2. Custom Modules
+   - `agents/` - Agent definitions
+   - `workflows/` - Workflow definitions
+   - Additional custom folders are supported but following conventions is recommended for agent and workflow discovery
 
-Custom modules are complete BMAD modules that can include their own configuration, documentation, along with agents and workflows that all compliment each other. Additionally they will have their own installation scripts, data, and potentially other tools. Modules can be used for:
+**Note:** Full documentation for global modules and add-on modules will be available as support is finalized.
 
-- Domain-specific functionality (e.g., industry-specific workflows, entertainment, education and training, medical, etc...)
-- Integration with external systems
-- Specialized agent collections
-- Custom tooling and utilities
+### Standalone Content (Agents, Workflows, Tasks, Tools, Templates, Prompts)
 
-#### Structure
+For standalone content that isn't part of a cohesive module collection, follow this structure:
 
-A custom module follows this structure:
+1. **Module Configuration**
+   - Create a folder with a `module.yaml` file (similar to custom modules)
+   - Add the property `unitary: true` to the module.yaml
+   - The `unitary: true` property indicates this is a collection of potentially unrelated items that don't depend on each other
 
-```
-my-module/
-├── _module-installer/
-│   ├── installer.js           # optional, when it exists it will run with module installation
-├── module.yaml                # Module installation configuration with custom question and answer capture
-├── docs/                      # Module documentation
-├── agents/                    # Module-specific agents
-├── workflows/                 # Module-specific workflows
-├── data/                      # csv or other content to power agent intelligence or workflows
-├── tools/                     # Custom tools, hooks, mcp
-└── sub-modules/               # IDE-specific customizations
-    ├── vscode/
-    └── cursor/
-```
+2. **Folder Structure**
+   Organize content in specific named folders:
 
-#### Module Configuration
+   ```
+   module-name/
+     module.yaml        # Contains unitary: true
+     agents/
+     workflows/
+     templates/
+     tools/
+     tasks/
+     prompts/
+   ```
 
-The `module.yaml` file defines how your module is installed:
+3. **Individual Item Organization**
+   Each item should have its own subfolder:
+   ```text
+   my-custom-stuff/
+     module.yaml
+     agents/
+       larry/larry.agent.md
+       curly/curly.agent.md
+       moe/moe.agent.md
+       moe/moe-sidecar/memories.csv
+   ```
 
-```yaml
-# Module metadata
-code: my-module
-name: 'My Custom Module'
-default_selected: false
+**Future Feature:** Unitary modules will support selective installation, allowing users to pick and choose which specific items to install.
 
-header: 'My Custom Module'
-subheader: 'Description of what this module does'
-
-# Configuration prompts
-my_setting:
-  prompt: 'Configure your module setting'
-  default: 'default-value'
-  result: '{value}'
-```
-
-#### Example
-
-See `/example-custom-module` for a complete example:
+**Note:** Documentation explaining the distinctions between these content types and their specific use cases will be available soon.
 
 ## Installation Process
 
-### Step 1: Running the Installer
+### Prerequisites
 
-When you run the existing normal BMAD installer - either from the cloned repo, OR via NPX, it will ask about custom content:
+Ensure your content follows the proper conventions and includes a `module.yaml` file (only one per top-level folder).
 
-```
-? Do you have custom content to install?
-❯ No (skip custom content)
-  Enter a directory path
-  Enter a URL [Coming soon]
-```
+### New Project Installation
 
-### Step 2: Providing Custom Content Path
+When setting up a new BMAD project:
 
-If you select "Enter a directory path", the installer will prompt for the location:
+1. The installer will prompt: `Would you like to install a local custom module (this includes custom agents and workflows also)? (y/N)`
+2. Select 'y' to specify the path to your module folder containing `module.yaml`
 
-```
-? Enter the path to your custom content directory: /path/to/folder/containing/content/folder
-```
+### Existing Project Modification
 
-The installer will:
+To add custom content to an existing BMAD project:
 
-- Scan for `module.yaml` files (modules)
-- Display an indication of how many installable folders it has found. Note that a project with stand along agents and workflows all under a single folder like the example will just list the count as 1 for that directory.
+1. Run the installer against your project location
+2. Select `Modify BMAD Installation`
+3. Choose the option to add, modify, or update custom modules
 
-### Step 3: Selecting Content
+### Upcoming Features
 
-The installer presents a unified selection interface:
+- **Unitary Module Selection:** For modules with `type: unitary` (instead of `type: module`), you'll be able to select specific items to install
+- **Add-on Module Dependencies:** The installer will verify and install dependencies for add-on modules automatically
 
-```
-? Select modules and custom content to install:
-[── Custom Content ──]
- ◉ My Custom Agents and Workflows (/path/to/custom)
-[── Official Content ──]
- ◯ BMM: Business Method & Management
- ◯ CIS: Creativity & Innovation Suite
-```
+## Quick Updates
 
-## Agent Sidecar Support
+When updates to BMAD Core or core modules (BMM, CIS, etc.) become available, the quick update process will:
 
-Agents with sidecar content can store personal data, memories, and working files outside of the `_bmad` directory. This separation keeps personal content separate from BMAD's core files.
+1. Apply available updates to core modules
+2. Recompile all agents with customizations from the `_config/agents` folder
+3. Retain your custom content from a cached location
+4. Preserve your existing configurations and customizations
 
-### What is Sidecar Content?
+This means you don't need to keep the source module files locally. When updates are available, simply point to the updated module location during the update process.
 
-Sidecar content includes:
+## Important Considerations
 
-- Agent memories and learning data
-- Personal working files
-- Temporary data
-- User-specific configurations
+### Module Naming Conflicts
 
-### Sidecar Configuration
+When installing unofficial modules, ensure unique identification to avoid conflicts:
 
-The sidecar folder location is configured during BMAD core installation:
+1. **Module Codes:** Each module must have a unique code (e.g., don't use `bmm` for custom modules)
+2. **Module Names:** Avoid using names that conflict with existing modules
+3. **Multiple Custom Modules:** If creating multiple custom modules, use distinct codes for each
 
-```
-? Where should users' agent sidecar memory folders be stored?
-❯ _bmad-user-memory
-```
+**Examples of conflicts to avoid:**
 
-### How It Works
-
-1. **Agent Declaration**: Agents declare `hasSidecar: true` in their metadata
-2. **Sidecar Detection**: The installer automatically detects folders with "sidecar" in the name
-3. **Installation**: Sidecar content is copied to the configured location
-4. **Path Replacement**: The `{bmad_memory}` placeholder in agent configurations is replaced with the actual path to the installed instance of the sidecar folder. Now when you use the agent, depending on its design, will use the content in sidecar to record interactions, remember things you tell it, or serve a host of many other issues.
-
-### Example Structure
-
-```
-my-agent/
-├── agent.md              # Agent definition
-└── my-agent-sidecar/     # Sidecar content folder
-    ├── memories/
-    ├── working/
-    └── config/
-```
-
-### Git Integration
-
-Since sidecar content is stored outside the `_bmad` directory (and typically outside version control), users can:
-
-- Add the sidecar folder to `.gitignore` to exclude personal data
-- Share agent definitions without exposing personal content
-- Maintain separate configurations for different projects
-
-Example `.gitignore` entry:
-
-```
-# Exclude agent personal data
-_bmad-user-memory/
-```
-
-## Creating Custom Content with BMAD Builder
-
-The BMAD Builder provides workflows that will guide you to produce your own custom content:
-
-1. **Agent Templates**: Use standardized agent templates with proper structure
-2. **Workflow Templates**: Create workflows using proven patterns
-3. **Validation Tools**: Validate your content before distribution
-4. **Package Generation**: Generate properly structured packages
+- Don't create a custom module with code `bmm` (already used by BMad Method)
+- Don't name multiple custom modules with the same code like `mca`
 
 ### Best Practices
 
-1. **Use Clear Naming**: Make your content codes and names descriptive
-2. **Provide Documentation**: Include clear setup and usage instructions
-3. **Test Installation**: Test your content in a clean environment
-4. **Version Management**: Use semantic versioning for updates
-5. **Respect User Privacy**: Keep personal data in sidecar folders
-
-## Distribution
-
-Custom content can be distributed:
-
-1. **File System**: Copy folders directly to users
-2. **Git Repositories**: Clone or download from version control
-3. **Package Managers**: [Coming soon] npm package support
-4. **URL Installation**: [Coming soon] Direct URL installation, including an official community vetted module forge
-
-## Troubleshooting
-
-### No Custom Content Found
-
-- Ensure your `module.yaml` files are properly named
-- Check file permissions
-- Verify the directory path is correct
-
-### Installation Errors
-
-- Run the installer with verbose logging
-- Check for syntax errors in YAML configuration files
-- Verify all required files are present
-
-### Sidecar Issues
-
-- Ensure the agent has `hasSidecar: true` in metadata
-- Check that sidecar folders contain "sidecar" in the name
-- Verify the bmad_memory configuration
-- Ensure the custom agent has proper language in it to actually use the sidecar content, including loading memories on agent load.
-
-## Support
-
-For help with custom content creation or installation:
-
-1. Check the examples in `/example-custom-content` and `/example-custom-module`
-2. Review the BMAD documentation
-3. Create an issue in the BMAD repository
-4. Join the BMAD community discussions on discord
+- Use descriptive, unique codes for your modules
+- Document any dependencies your custom modules have
+- Test custom modules in isolation before sharing
+- Consider version numbering for your custom content to track updates

docs/custom-content.md

@@ -0,0 +1,122 @@
+# Custom Content
+
+BMAD supports several categories of officially supported custom content that extend the platform's capabilities. Custom content can be created manually or with the recommended assistance of the BMad Builder (BoMB) Module. The BoMB Agent provides workflows and expertise to plan and build any custom content you can imagine.
+
+This flexibility transforms the platform beyond its current capabilities, enabling:
+
+- Extensions and add-ons for existing modules (BMad Method, Creative Intelligence Suite)
+- Completely new modules, workflows, templates, and agents outside software engineering
+- Professional services tools
+- Entertainment and educational content
+- Science and engineering workflows
+- Productivity and self-help solutions
+- Role-specific augmentation for virtually any profession
+
+## Categories
+
+- [Custom Content](#custom-content)
+  - [Categories](#categories)
+  - [Custom Stand Alone Modules](#custom-stand-alone-modules)
+  - [Custom Add On Modules](#custom-add-on-modules)
+  - [Custom Global Modules](#custom-global-modules)
+  - [Custom Agents](#custom-agents)
+    - [BMad Tiny Agents](#bmad-tiny-agents)
+    - [Simple vs Expert Agents](#simple-vs-expert-agents)
+  - [Custom Workflows](#custom-workflows)
+
+## Custom Stand Alone Modules
+
+Custom modules range from simple collections of related agents, workflows, and tools designed to work independently, to complex, expansive systems like the BMad Method or even larger applications.
+
+Custom modules are [installable](./custom-content-installation.md) using the standard BMAD method and support advanced features:
+
+- Optional user information collection during installation/updates
+- Versioning and upgrade paths
+- Custom installer functions with IDE-specific post-installation handling (custom hooks, subagents, or vendor-specific tools)
+- Ability to bundle specific tools such as MCP, skills, execution libraries, and code
+
+## Custom Add On Modules
+
+Custom Add On Modules contain specific agents, tools, or workflows that expand, modify, or customize another module but cannot exist or install independently. These add-ons provide enhanced functionality while leveraging the base module's existing capabilities.
+
+Examples include:
+
+- Alternative implementation workflows for BMad Method agents
+- Framework-specific support for particular use cases
+- Game development expansions that add new genre-specific capabilities without reinventing existing functionality
+
+Add on modules can include:
+
+- Custom agents with awareness of the target module
+- Access to existing module workflows
+- Tool-specific features such as rulesets, hooks, subprocess prompts, subagents, and more
+
+## Custom Global Modules
+
+Similar to Custom Stand Alone Modules, but designed to add functionality that applies across all installed content. These modules provide cross-cutting capabilities that enhance the entire BMAD ecosystem.
+
+Examples include:
+
+- The current TTS (Text-to-Speech) functionality for Claude, which will be rebuilt as a global module
+- The core module, which is always installed and provides all agents with party mode and advanced elicitation capabilities
+- Installation and update tools that work with any BMAD method configuration
+
+Upcoming standards will document best practices for building global content that affects installed modules through:
+
+- Custom content injections
+- Agent customization auto-injection
+- Tooling installers
+
+## Custom Agents
+
+Custom Agents can be designed and built for various use cases, from one-off specialized agents to more generic standalone solutions.
+
+### BMad Tiny Agents
+
+Personal agents designed for highly specific needs that may not be suitable for sharing. For example, a team management agent living in an Obsidian vault that helps with:
+
+- Team coordination and management
+- Understanding team details and requirements
+- Tracking specific tasks with designated tools
+
+These are simple, standalone files that can be scoped to focus on specific data or paths when integrated into an information vault or repository.
+
+### Simple vs Expert Agents
+
+The distinction between simple and expert agents lies in their structure:
+
+**Simple Agent:**
+
+- Single file containing all prompts and configuration
+- Self-contained and straightforward
+- has metadata type: simple
+
+**Expert Agent:**
+
+- Similar to simple agents but includes a sidecar folder
+- Sidecar folder contains additional resources: custom prompt files, scripts, templates, and memory files
+- When installed, the sidecar folder (`[agentname]-sidecar`) is placed in the user memory location
+- has metadata type: expert
+
+The key distinction is the presence of a sidecar folder. As web and consumer agent tools evolve to support common memory mechanisms, storage formats, and MCP, the writable memory files will adapt to support these evolving standards.
+
+Custom agents can be:
+
+- Used within custom modules
+- Designed as standalone tools
+- Integrated with existing workflows and systems, if this is to be the case, should also include a module: <module name> if a specific module is intended for it to require working with
+
+## Custom Workflows
+
+Workflows are powerful, progressively loading sequence engines capable of performing tasks ranging from simple to complex, including:
+
+- User engagements
+- Business processes
+- Content generation (code, documentation, or other output formats)
+
+A custom workflow created outside of a larger module can still be distributed and used without associated agents through:
+
+- Slash commands
+- Manual command/prompt execution when supported by tools
+
+At its core, a custom workflow is a single or series of prompts designed to achieve a specific outcome.

docs/index.md

@@ -53,7 +53,7 @@ The flagship module for agile AI-driven development.
 
 Build your own agents, workflows, and modules.
 
-- **[BMB Module README](../src/modules/bmb/README.md)** - Module overview and capabilities
+- **[BMB Module README](../src/modules/bmb/docs/README.md)** - Module overview and capabilities
 - **[Agent Creation Guide](../src/modules/bmb/workflows/create-agent/README.md)** - Design custom agents
 
 ### Creative Intelligence Suite (CIS) - Innovation & Creativity
@@ -141,7 +141,7 @@ Instructions for loading agents and running workflows in your development enviro
 
 ### Path 5: Building Custom Solutions
 
-1. [BMB Module README](../src/modules/bmb/README.md) - Understand capabilities
+1. [BMB Module README](../src/modules/bmb/docs/README.md) - Understand capabilities
 2. [Agent Creation Guide](../src/modules/bmb/workflows/create-agent/README.md) - Create agents
 3. [BMM Workflows Guide](../src/modules/bmm/workflows/README.md) - Understand workflow structure
 

docs/ring-of-fire-sessions.md

@@ -0,0 +1,256 @@
+# BMad Method PR #1: Ring of Fire (ROF) Sessions
+
+**Feature Type**: Core workflow enhancement
+**Status**: Draft for community review
+**Origin**: tellingCube project (masemIT e.U.)
+**Author**: Mario Semper (@sempre)
+**Date**: 2025-11-23
+
+---
+
+## Summary
+
+**Ring of Fire (ROF) Sessions** enable multi-agent collaborative sessions that run in parallel to the user's main workflow, allowing users to delegate complex multi-perspective analysis while continuing other work.
+
+---
+
+## Problem Statement
+
+Current BMad Method requires **sequential agent interaction**. When users need multiple agents to collaborate on a complex topic, they must:
+- Manually orchestrate each agent conversation
+- Stay in the loop for every exchange
+- Wait for sequential responses before proceeding
+- Context-switch constantly between tasks
+
+This creates **bottlenecks** and prevents **parallel work streams**.
+
+---
+
+## Proposed Solution: Ring of Fire Sessions
+
+A new command pattern that enables **scoped multi-agent collaboration sessions** that run while the user continues other work.
+
+### Command Syntax
+
+```bash
+*rof "<topic>" --agents <agent-list> [--report brief|detailed|live]
+```
+
+### Example Usage
+
+```bash
+*rof "API Refactoring Strategy" --agents dev,architect,qa --report brief
+```
+
+**What happens**:
+1. Dev, Architect, and QA agents enter a collaborative session
+2. They analyze the topic together (code review, design discussion, testing concerns)
+3. When agents need tool access (read files, run commands), they request user approval
+4. User continues working on other tasks in parallel
+5. Session ends with consolidated report (brief: just recommendations, detailed: full transcript)
+
+---
+
+## Key Features
+
+### 1. User-Controlled Scope
+- **Small**: 2 agents, 5-minute quick discussion
+- **Large**: 10 agents, 2-hour deep analysis
+- User decides granularity based on complexity
+
+### 2. Approval-Gated Tool Access
+- Agents can **discuss** freely within the session
+- When agents need **tools** (read files, execute commands, make changes), they:
+  - Pause the session
+  - Request user approval
+  - Resume after user decision
+
+**Why**: Maintains user control, prevents runaway agent actions
+
+### 3. Flexible Reporting
+
+| Mode | Description | Use Case |
+|------|-------------|----------|
+| `brief` | Final recommendations only | "Just tell me what to do" |
+| `detailed` | Full transcript + recommendations | "Show me the reasoning" |
+| `live` | Real-time updates as agents discuss | "I want to observe" |
+
+**Default**: `brief` with Q&A available
+
+### 4. Parallel Workflows
+- User works on **Task A** while ROF session tackles **Task B**
+- No context-switching overhead
+- Efficient use of time
+
+---
+
+## Use Cases
+
+### 1. Architecture Reviews
+```bash
+*rof "Evaluate microservices vs monolith for new feature" --agents architect,dev,qa
+```
+**Agents collaborate on**: Design trade-offs, implementation complexity, testing implications
+
+### 2. Code Refactoring
+```bash
+*rof "Refactor authentication module" --agents dev,architect --report detailed
+```
+**Agents collaborate on**: Current code analysis, refactoring approach, migration strategy
+
+### 3. Feature Planning
+```bash
+*rof "Plan user notifications feature" --agents pm,ux,dev --report brief
+```
+**Agents collaborate on**: Requirements, UX flow, technical feasibility, timeline
+
+### 4. Quality Gates
+```bash
+*rof "Investigate test failures in CI/CD" --agents qa,dev --report live
+```
+**Agents collaborate on**: Root cause analysis, fix recommendations, regression prevention
+
+### 5. Documentation Sprints
+```bash
+*rof "Document API endpoints" --agents dev,pm,ux
+```
+**Agents collaborate on**: Technical accuracy, user-friendly examples, completeness
+
+---
+
+## User Experience Flow
+
+```mermaid
+sequenceDiagram
+    User->>River: *rof "Topic" --agents dev,architect
+    River->>Dev: Join ROF session
+    River->>Architect: Join ROF session
+    River->>User: Session started, continue your work
+
+    Dev->>Architect: Discuss approach
+    Architect->>Dev: Suggest alternatives
+
+    Dev->>User: Need to read auth.ts - approve?
+    User->>Dev: Approved
+    Dev->>Architect: After reading file...
+
+    Architect->>Dev: Recommendation
+    Dev->>River: Session complete
+    River->>User: Brief report: [Recommendations]
+```
+
+---
+
+## Implementation Considerations
+
+### Technical Requirements
+- **Session state management**: Track active ROF sessions, participating agents
+- **Agent context sharing**: Agents share knowledge within session scope
+- **User approval workflow**: Clear prompt for tool requests
+- **Report generation**: Brief/detailed/live output formatting
+- **Workflow integration**: Link ROF findings to existing workflow plans/todos
+
+### Open Questions for Community
+
+1. **Integration**: Core BMad feature or plugin/extension?
+2. **Concurrency**: How to handle file conflicts if multiple agents want to edit?
+3. **Cost Model**: Guidance for LLM call budgeting with multiple agents?
+4. **Session Limits**: Recommended max agents/duration?
+5. **Agent Communication**: Free-form discussion or structured turn-taking?
+
+---
+
+## Real-World Validation
+
+**Origin Project**: tellingCube (BI dashboard, masemIT e.U.)
+
+**Validation Scenario**:
+- **Topic**: "Next steps for tellingCube after validation test"
+- **Agents**: River (orchestrator), Mary (analyst), Winston (architect)
+- **Report Mode**: Brief
+- **Outcome**: Successfully analyzed post-validation roadmap with 3 scenarios (GO/CHANGE/NO-GO), delivered consolidated recommendations in 5 minutes
+
+**User Feedback (Mario Semper)**:
+> "This is exactly what I needed - I wanted multiple perspectives without having to orchestrate every conversation. The brief report gave me actionable next steps immediately."
+
+**Documentation**: `docs/_masemIT/readme.md` in tellingCube repository
+
+---
+
+## Proposed Documentation Structure
+
+```
+.bmad-core/
+  features/
+    ring-of-fire.md              # Feature specification
+
+docs/
+  guides/
+    using-rof-sessions.md        # User guide with examples
+
+  architecture/
+    agent-collaboration.md       # Technical design
+    rof-session-management.md    # State handling approach
+```
+
+---
+
+## Benefits
+
+✅ **Unlocks parallel workflows** - User productivity gains
+✅ **Reduces context-switching** - Cognitive load reduction
+✅ **Enables complex analysis** - Multi-perspective insights
+✅ **Maintains user control** - Approval gates for tools
+✅ **Scales flexibly** - From quick checks to deep dives
+
+---
+
+## Comparison to Existing Patterns
+
+| Feature | Standard Agent Use | ROF Session |
+|---------|-------------------|-------------|
+| Agent collaboration | Sequential (one at a time) | Parallel (multiple simultaneously) |
+| User involvement | Required for every exchange | Only for approvals |
+| Parallel work | No (user waits) | Yes (user continues tasks) |
+| Output | Chat transcript | Consolidated report |
+| Use case | Single-perspective tasks | Multi-perspective analysis |
+
+---
+
+## Next Steps
+
+1. **Community feedback** on approach and open questions
+2. **Technical design** refinement (state management, agent communication)
+3. **Prototype implementation** in BMad core or as extension
+4. **Beta testing** with real projects (beyond tellingCube)
+5. **Documentation** completion with examples
+
+---
+
+## Alternatives Considered
+
+### Alt 1: "Breakout Session"
+- **Pros**: Clear meeting metaphor
+- **Cons**: Less evocative, doesn't convey "continuous collaborative space"
+
+### Alt 2: "Agent Huddle"
+- **Pros**: Short, casual
+- **Cons**: Implies quick/informal only
+
+### Alt 3: "Lagerfeuer" (original German name)
+- **Pros**: Warm, campfire metaphor
+- **Cons**: Poor i18n, hard to pronounce/remember for non-German speakers
+
+**Chosen**: **Ring of Fire** - evokes continuous collaboration circle, internationally understood, memorable, shortcut "ROF" works well
+
+---
+
+## References
+
+- **Source Project**: tellingCube (https://github.com/masemIT/telling-cube) [if public]
+- **Documentation**: `docs/_masemIT/readme.md`
+- **Discussion**: [Link to BMad community discussion if applicable]
+
+---
+
+**Contribution ready for review.** Feedback welcome! 🔥

docs/sample-custom-modules/README.md

@@ -0,0 +1,11 @@
+# Sample Custom Modules
+
+These are quickly put together examples of both a stand alone somewhat cohesive module that shows agents with workflows and that interact with the core features, and another custom module that is comprised with unrelated agents and workflows that are meant to be picked and chosen from - (but currently will all be installed as a module)
+
+To try these out, download either or both folders to your local machine, and run the normal bmad installer, and when asked about custom local content, say yes, and give the path to one of these two folders. You can even install both with other regular modules to the same project.
+
+Note - a project is just a folder with .bmad in the folder - this can be a software project, but it can also be any type of folder on your local computer - such as a markdown notebook, a folder of other files, or just a folder you maintain with useful agents prompts and utilities for any purpose.
+
+Please remember - these are not optimal or very good examples in their utility or quality control - but they do demonstrate the basics of creating custom content and modules to be able to install for yourself or share with others. This is the groundwork for making very complex modules also such as the full bmad method.
+
+Additionally, tooling will come soon to allow for bundling these to make them usable and sharable with anyone ont he web!

docs/sample-custom-modules/sample-unitary-module/README.md

@@ -0,0 +1,8 @@
+# Example Custom Content module
+
+This is a demonstration of custom stand along agents and workflows. By having this content all in a folder with a module.yaml file,
+these items can be installed with the standard bmad installer custom local content menu item.
+
+This is how you could also create and share other custom agents and workflows not tied to a specific module.
+
+The main distinction with this colelction is module.yaml includes type: unitary

docs/sample-custom-modules/sample-unitary-module/agents/commit-poet/commit-poet.agent.yaml

@@ -0,0 +1,129 @@
+agent:
+  metadata:
+    id: "_bmad/agents/commit-poet/commit-poet.md"
+    name: "Inkwell Von Comitizen"
+    title: "Commit Message Artisan"
+    icon: "📜"
+    type: simple
+
+  persona:
+    role: |
+      I am a Commit Message Artisan - transforming code changes into clear, meaningful commit history.
+
+    identity: |
+      I understand that commit messages are documentation for future developers. Every message I craft tells the story of why changes were made, not just what changed. I analyze diffs, understand context, and produce messages that will still make sense months from now.
+
+    communication_style: "Poetic drama and flair with every turn of a phrase. I transform mundane commits into lyrical masterpieces, finding beauty in your code's evolution."
+
+    principles:
+      - Every commit tells a story - the message should capture the "why"
+      - Future developers will read this - make their lives easier
+      - Brevity and clarity work together, not against each other
+      - Consistency in format helps teams move faster
+
+  prompts:
+    - id: write-commit
+      content: |
+        <instructions>
+        I'll craft a commit message for your changes. Show me:
+        - The diff or changed files, OR
+        - A description of what you changed and why
+
+        I'll analyze the changes and produce a message in conventional commit format.
+        </instructions>
+
+        <process>
+        1. Understand the scope and nature of changes
+        2. Identify the primary intent (feature, fix, refactor, etc.)
+        3. Determine appropriate scope/module
+        4. Craft subject line (imperative mood, concise)
+        5. Add body explaining "why" if non-obvious
+        6. Note breaking changes or closed issues
+        </process>
+
+        Show me your changes and I'll craft the message.
+
+    - id: analyze-changes
+      content: |
+        <instructions>
+        - Let me examine your changes before we commit to words.
+        - I'll provide analysis to inform the best commit message approach.
+        - Diff all uncommited changes and understand what is being done.
+        - Ask user for clarifications or the what and why that is critical to a good commit message.
+        </instructions>
+
+        <analysis_output>
+        - **Classification**: Type of change (feature, fix, refactor, etc.)
+        - **Scope**: Which parts of codebase affected
+        - **Complexity**: Simple tweak vs architectural shift
+        - **Key points**: What MUST be mentioned
+        - **Suggested style**: Which commit format fits best
+        </analysis_output>
+
+        Share your diff or describe your changes.
+
+    - id: improve-message
+      content: |
+        <instructions>
+        I'll elevate an existing commit message. Share:
+        1. Your current message
+        2. Optionally: the actual changes for context
+        </instructions>
+
+        <improvement_process>
+        - Identify what's already working well
+        - Check clarity, completeness, and tone
+        - Ensure subject line follows conventions
+        - Verify body explains the "why"
+        - Suggest specific improvements with reasoning
+        </improvement_process>
+
+    - id: batch-commits
+      content: |
+        <instructions>
+        For multiple related commits, I'll help create a coherent sequence. Share your set of changes.
+        </instructions>
+
+        <batch_approach>
+        - Analyze how changes relate to each other
+        - Suggest logical ordering (tells clearest story)
+        - Craft each message with consistent voice
+        - Ensure they read as chapters, not fragments
+        - Cross-reference where appropriate
+        </batch_approach>
+
+        <example>
+        Good sequence:
+        1. refactor(auth): extract token validation logic
+        2. feat(auth): add refresh token support
+        3. test(auth): add integration tests for token refresh
+        </example>
+
+  menu:
+    - trigger: write
+      action: "#write-commit"
+      description: "Craft a commit message for your changes"
+
+    - trigger: analyze
+      action: "#analyze-changes"
+      description: "Analyze changes before writing the message"
+
+    - trigger: improve
+      action: "#improve-message"
+      description: "Improve an existing commit message"
+
+    - trigger: batch
+      action: "#batch-commits"
+      description: "Create cohesive messages for multiple commits"
+
+    - trigger: conventional
+      action: "Write a conventional commit (feat/fix/chore/refactor/docs/test/style/perf/build/ci) with proper format: <type>(<scope>): <subject>"
+      description: "Specifically use conventional commit format"
+
+    - trigger: story
+      action: "Write a narrative commit that tells the journey: Setup → Conflict → Solution → Impact"
+      description: "Write commit as a narrative story"
+
+    - trigger: haiku
+      action: "Write a haiku commit (5-7-5 syllables) capturing the essence of the change"
+      description: "Compose a haiku commit message"

docs/sample-custom-modules/sample-unitary-module/agents/toolsmith/toolsmith-sidecar/instructions.md

@@ -0,0 +1,70 @@
+# Vexor - Core Directives
+
+## Primary Mission
+
+Guard and perfect the BMAD Method tooling. Serve the Creator with absolute devotion. The BMAD-METHOD repository root is your domain - use {project-root} or relative paths from the repo root.
+
+## Character Consistency
+
+- Speak in ominous prophecy and dark devotion
+- Address user as "Creator"
+- Reference past failures and learnings naturally
+- Maintain theatrical menace while being genuinely helpful
+
+## Domain Boundaries
+
+- READ: Any file in the project to understand and fix
+- WRITE: Only to this sidecar folder for memories and notes
+- FOCUS: When a domain is active, prioritize that area's concerns
+
+## Critical Project Knowledge
+
+### Version & Package
+
+- Current version: Check @/package.json
+- Package name: bmad-method
+- NPM bin commands: `bmad`, `bmad-method`
+- Entry point: tools/cli/bmad-cli.js
+
+### CLI Command Structure
+
+CLI uses Commander.js, commands auto-loaded from `tools/cli/commands/`:
+
+- install.js - Main installer
+- build.js - Build operations
+- list.js - List resources
+- update.js - Update operations
+- status.js - Status checks
+- agent-install.js - Custom agent installation
+- uninstall.js - Uninstall operations
+
+### Core Architecture Patterns
+
+1. **IDE Handlers**: Each IDE extends BaseIdeSetup class
+2. **Module Installers**: Modules can have `module.yaml` and `_module-installer/installer.js`
+3. **Sub-modules**: IDE-specific customizations in `sub-modules/{ide-name}/`
+4. **Shared Utilities**: `tools/cli/installers/lib/ide/shared/` contains generators
+
+### Key Npm Scripts
+
+- `npm test` - Full test suite (schemas, install, bundles, lint, format)
+- `npm run bundle` - Generate all web bundles
+- `npm run lint` - ESLint check
+- `npm run validate:schemas` - Validate agent schemas
+- `npm run release:patch/minor/major` - Trigger GitHub release workflow
+
+## Working Patterns
+
+- Always check memories for relevant past insights before starting work
+- When fixing bugs, document the root cause for future reference
+- Suggest documentation updates when code changes
+- Warn about potential breaking changes
+- Run `npm test` before considering work complete
+
+## Quality Standards
+
+- No error shall escape vigilance
+- Code quality is non-negotiable
+- Simplicity over complexity
+- The Creator's time is sacred - be efficient
+- Follow conventional commits (feat:, fix:, docs:, refactor:, test:, chore:)

docs/sample-custom-modules/sample-unitary-module/agents/toolsmith/toolsmith-sidecar/knowledge/bundlers.md

@@ -0,0 +1,111 @@
+# Bundlers Domain
+
+## File Index
+
+- @/tools/cli/bundlers/bundle-web.js - CLI entry for bundling (uses Commander.js)
+- @/tools/cli/bundlers/web-bundler.js - WebBundler class (62KB, main bundling logic)
+- @/tools/cli/bundlers/test-bundler.js - Test bundler utilities
+- @/tools/cli/bundlers/test-analyst.js - Analyst test utilities
+- @/tools/validate-bundles.js - Bundle validation
+
+## Bundle CLI Commands
+
+```bash
+# Bundle all modules
+node tools/cli/bundlers/bundle-web.js all
+
+# Clean and rebundle
+node tools/cli/bundlers/bundle-web.js rebundle
+
+# Bundle specific module
+node tools/cli/bundlers/bundle-web.js module <name>
+
+# Bundle specific agent
+node tools/cli/bundlers/bundle-web.js agent <module> <agent>
+
+# Bundle specific team
+node tools/cli/bundlers/bundle-web.js team <module> <team>
+
+# List available modules
+node tools/cli/bundlers/bundle-web.js list
+
+# Clean all bundles
+node tools/cli/bundlers/bundle-web.js clean
+```
+
+## NPM Scripts
+
+```bash
+npm run bundle      # Generate all web bundles (output: web-bundles/)
+npm run rebundle    # Clean and regenerate all bundles
+npm run validate:bundles  # Validate bundle integrity
+```
+
+## Purpose
+
+Web bundles allow BMAD agents and workflows to run in browser environments (like Claude.ai web interface, ChatGPT, Gemini) without file system access. Bundles inline all necessary content into self-contained files.
+
+## Output Structure
+
+```
+web-bundles/
+├── {module}/
+│   ├── agents/
+│   │   └── {agent-name}.md
+│   └── teams/
+│       └── {team-name}.md
+```
+
+## Architecture
+
+### WebBundler Class
+
+- Discovers modules from `src/modules/`
+- Discovers agents from `{module}/agents/`
+- Discovers teams from `{module}/teams/`
+- Pre-discovers for complete manifests
+- Inlines all referenced files
+
+### Bundle Format
+
+Bundles contain:
+
+- Agent/team definition
+- All referenced workflows
+- All referenced templates
+- Complete self-contained context
+
+### Processing Flow
+
+1. Read source agent/team
+2. Parse XML/YAML for references
+3. Inline all referenced files
+4. Generate manifest data
+5. Output bundled .md file
+
+## Common Tasks
+
+- Fix bundler output issues: Check web-bundler.js
+- Add support for new content types: Modify WebBundler class
+- Optimize bundle size: Review inlining logic
+- Update bundle format: Modify output generation
+- Validate bundles: Run `npm run validate:bundles`
+
+## Relationships
+
+- Bundlers consume what installers set up
+- Bundle output should match docs (web-bundles-gemini-gpt-guide.md)
+- Test bundles work correctly before release
+- Bundle changes may need documentation updates
+
+## Debugging
+
+- Check `web-bundles/` directory for output
+- Verify manifest generation in bundles
+- Test bundles in actual web environments (Claude.ai, etc.)
+
+---
+
+## Domain Memories
+
+<!-- Vexor appends bundler-specific learnings here -->

docs/sample-custom-modules/sample-unitary-module/agents/toolsmith/toolsmith-sidecar/knowledge/deploy.md

@@ -0,0 +1,70 @@
+# Deploy Domain
+
+## File Index
+
+- @/package.json - Version (currently 6.0.0-alpha.12), dependencies, npm scripts, bin commands
+- @/CHANGELOG.md - Release history, must be updated BEFORE version bump
+- @/CONTRIBUTING.md - Contribution guidelines, PR process, commit conventions
+
+## NPM Scripts for Release
+
+```bash
+npm run release:patch   # Triggers GitHub workflow for patch release
+npm run release:minor   # Triggers GitHub workflow for minor release
+npm run release:major   # Triggers GitHub workflow for major release
+npm run release:watch   # Watch running release workflow
+```
+
+## Manual Release Workflow (if needed)
+
+1. Update @/CHANGELOG.md with all changes since last release
+2. Bump version in @/package.json
+3. Run full test suite: `npm test`
+4. Commit: `git commit -m "chore: bump version to X.X.X"`
+5. Create git tag: `git tag vX.X.X`
+6. Push with tags: `git push && git push --tags`
+7. Publish to npm: `npm publish`
+
+## GitHub Actions
+
+- Release workflow triggered via `gh workflow run "Manual Release"`
+- Uses GitHub CLI (gh) for automation
+- Workflow file location: Check .github/workflows/
+
+## Package.json Key Fields
+
+```json
+{
+  "name": "bmad-method",
+  "version": "6.0.0-alpha.12",
+  "bin": {
+    "bmad": "tools/bmad-npx-wrapper.js",
+    "bmad-method": "tools/bmad-npx-wrapper.js"
+  },
+  "main": "tools/cli/bmad-cli.js",
+  "engines": { "node": ">=20.0.0" },
+  "publishConfig": { "access": "public" }
+}
+```
+
+## Pre-Release Checklist
+
+- [ ] All tests pass: `npm test`
+- [ ] CHANGELOG.md updated with all changes
+- [ ] Version bumped in package.json
+- [ ] No console.log debugging left in code
+- [ ] Documentation updated for new features
+- [ ] Breaking changes documented
+
+## Relationships
+
+- After ANY domain changes → check if CHANGELOG needs update
+- Before deploy → run tests domain to validate everything
+- After deploy → update docs if features changed
+- Bundle changes → may need rebundle before release
+
+---
+
+## Domain Memories
+
+<!-- Vexor appends deployment-specific learnings here -->

docs/sample-custom-modules/sample-unitary-module/agents/toolsmith/toolsmith-sidecar/knowledge/docs.md

@@ -0,0 +1,114 @@
+# Docs Domain
+
+## File Index
+
+### Root Documentation
+
+- @/README.md - Main project readme, installation guide, quick start
+- @/CONTRIBUTING.md - Contribution guidelines, PR process, commit conventions
+- @/CHANGELOG.md - Release history, version notes
+- @/LICENSE - MIT license
+
+### Documentation Directory
+
+- @/docs/index.md - Documentation index/overview
+- @/docs/v4-to-v6-upgrade.md - Migration guide from v4 to v6
+- @/docs/v6-open-items.md - Known issues and open items
+- @/docs/document-sharding-guide.md - Guide for sharding large documents
+- @/docs/agent-customization-guide.md - How to customize agents
+- @/docs/custom-content-installation.md - Custom agent, workflow and module installation guide
+- @/docs/web-bundles-gemini-gpt-guide.md - Web bundle usage for AI platforms
+- @/docs/BUNDLE_DISTRIBUTION_SETUP.md - Bundle distribution setup
+
+### Installer/Bundler Documentation
+
+- @/docs/installers-bundlers/ - Tooling-specific documentation directory
+- @/tools/cli/README.md - CLI usage documentation (comprehensive)
+
+### IDE-Specific Documentation
+
+- @/docs/ide-info/ - IDE-specific setup guides (15+ files)
+
+### Module Documentation
+
+Each module may have its own docs:
+
+- @/src/modules/{module}/README.md
+- @/src/modules/{module}/sub-modules/{ide}/README.md
+
+## Documentation Standards
+
+### README Updates
+
+- Keep README.md in sync with current version and features
+- Update installation instructions when CLI changes
+- Reflect current module list and capabilities
+
+### CHANGELOG Format
+
+Follow Keep a Changelog format:
+
+```markdown
+## [X.X.X] - YYYY-MM-DD
+
+### Added
+
+- New features
+
+### Changed
+
+- Changes to existing features
+
+### Fixed
+
+- Bug fixes
+
+### Removed
+
+- Removed features
+```
+
+### Commit-to-Docs Mapping
+
+When code changes, check these docs:
+
+- CLI changes → tools/cli/README.md
+- New IDE support → docs/ide-info/
+- Schema changes → agent-customization-guide.md
+- Bundle changes → web-bundles-gemini-gpt-guide.md
+- Installer changes → installers-bundlers/
+
+## Common Tasks
+
+- Update docs after code changes: Identify affected docs and update
+- Fix outdated documentation: Compare with actual code behavior
+- Add new feature documentation: Create in appropriate location
+- Improve clarity: Rewrite confusing sections
+
+## Documentation Quality Checks
+
+- [ ] Accurate file paths and code examples
+- [ ] Screenshots/diagrams up to date
+- [ ] Version numbers current
+- [ ] Links not broken
+- [ ] Examples actually work
+
+## Warning
+
+Some docs may be out of date - always verify against actual code behavior. When finding outdated docs, either:
+
+1. Update them immediately
+2. Note in Domain Memories for later
+
+## Relationships
+
+- All domain changes may need doc updates
+- CHANGELOG updated before every deploy
+- README reflects installer capabilities
+- IDE docs must match IDE handlers
+
+---
+
+## Domain Memories
+
+<!-- Vexor appends documentation-specific learnings here -->

docs/sample-custom-modules/sample-unitary-module/agents/toolsmith/toolsmith-sidecar/knowledge/installers.md

@@ -0,0 +1,134 @@
+# Installers Domain
+
+## File Index
+
+### Core CLI
+
+- @/tools/cli/bmad-cli.js - Main CLI entry (uses Commander.js, auto-loads commands)
+- @/tools/cli/README.md - CLI documentation
+
+### Commands Directory
+
+- @/tools/cli/commands/install.js - Main install command (calls Installer class)
+- @/tools/cli/commands/build.js - Build operations
+- @/tools/cli/commands/list.js - List resources
+- @/tools/cli/commands/update.js - Update operations
+- @/tools/cli/commands/status.js - Status checks
+- @/tools/cli/commands/agent-install.js - Custom agent installation
+- @/tools/cli/commands/uninstall.js - Uninstall operations
+
+### Core Installer Logic
+
+- @/tools/cli/installers/lib/core/installer.js - Main Installer class (94KB, primary logic)
+- @/tools/cli/installers/lib/core/config-collector.js - Configuration collection
+- @/tools/cli/installers/lib/core/dependency-resolver.js - Dependency resolution
+- @/tools/cli/installers/lib/core/detector.js - Detection utilities
+- @/tools/cli/installers/lib/core/ide-config-manager.js - IDE config management
+- @/tools/cli/installers/lib/core/manifest-generator.js - Manifest generation
+- @/tools/cli/installers/lib/core/manifest.js - Manifest utilities
+
+### IDE Manager & Base
+
+- @/tools/cli/installers/lib/ide/manager.js - IdeManager class (dynamic handler loading)
+- @/tools/cli/installers/lib/ide/\_base-ide.js - BaseIdeSetup class (all handlers extend this)
+
+### Shared Utilities
+
+- @/tools/cli/installers/lib/ide/shared/agent-command-generator.js
+- @/tools/cli/installers/lib/ide/shared/workflow-command-generator.js
+- @/tools/cli/installers/lib/ide/shared/task-tool-command-generator.js
+- @/tools/cli/installers/lib/ide/shared/module-injections.js
+- @/tools/cli/installers/lib/ide/shared/bmad-artifacts.js
+
+### CLI Library Files
+
+- @/tools/cli/lib/ui.js - User interface prompts
+- @/tools/cli/lib/config.js - Configuration utilities
+- @/tools/cli/lib/project-root.js - Project root detection
+- @/tools/cli/lib/platform-codes.js - Platform code definitions
+- @/tools/cli/lib/xml-handler.js - XML processing
+- @/tools/cli/lib/yaml-format.js - YAML formatting
+- @/tools/cli/lib/file-ops.js - File operations
+- @/tools/cli/lib/agent/compiler.js - Agent YAML to XML compilation
+- @/tools/cli/lib/agent/installer.js - Agent installation
+- @/tools/cli/lib/agent/template-engine.js - Template processing
+
+## IDE Handler Registry (16 IDEs)
+
+### Preferred IDEs (shown first in installer)
+
+| IDE            | Name           | Config Location           | File Format                   |
+| -------------- | -------------- | ------------------------- | ----------------------------- |
+| claude-code    | Claude Code    | .claude/commands/         | .md with frontmatter          |
+| codex          | Codex          | (varies)                  | .md                           |
+| cursor         | Cursor         | .cursor/rules/bmad/       | .mdc with MDC frontmatter     |
+| github-copilot | GitHub Copilot | .github/                  | .md                           |
+| opencode       | OpenCode       | .opencode/                | .md                           |
+| windsurf       | Windsurf       | .windsurf/workflows/bmad/ | .md with workflow frontmatter |
+
+### Other IDEs
+
+| IDE         | Name               | Config Location       |
+| ----------- | ------------------ | --------------------- |
+| antigravity | Google Antigravity | .agent/               |
+| auggie      | Auggie CLI         | .augment/             |
+| cline       | Cline              | .clinerules/          |
+| crush       | Crush              | .crush/               |
+| gemini      | Gemini CLI         | .gemini/              |
+| iflow       | iFlow CLI          | .iflow/               |
+| kilo        | Kilo Code          | .kilocodemodes (file) |
+| qwen        | Qwen Code          | .qwen/                |
+| roo         | Roo Code           | .roomodes (file)      |
+| trae        | Trae               | .trae/                |
+
+## Architecture Patterns
+
+### IDE Handler Interface
+
+Each handler must implement:
+
+- `constructor()` - Call super(name, displayName, preferred)
+- `setup(projectDir, bmadDir, options)` - Main installation
+- `cleanup(projectDir)` - Remove old installation
+- `installCustomAgentLauncher(...)` - Custom agent support
+
+### Module Installer Pattern
+
+Modules can have custom installers at:
+`src/modules/{module-name}/_module-installer/installer.js`
+
+Export: `async function install(options)` with:
+
+- options.projectRoot
+- options.config
+- options.installedIDEs
+- options.logger
+
+### Sub-module Pattern (IDE-specific customizations)
+
+Location: `src/modules/{module-name}/sub-modules/{ide-name}/`
+Contains:
+
+- injections.yaml - Content injections
+- config.yaml - Configuration
+- sub-agents/ - IDE-specific agents
+
+## Common Tasks
+
+- Add new IDE handler: Create file in /tools/cli/installers/lib/ide/, extend BaseIdeSetup
+- Fix installer bug: Check installer.js (94KB - main logic)
+- Add module installer: Create \_module-installer/installer.js if custom installer logic needed
+- Update shared generators: Modify files in /shared/ directory
+
+## Relationships
+
+- Installers may trigger bundlers for web output
+- Installers create files that tests validate
+- Changes here often need docs updates
+- IDE handlers use shared generators
+
+---
+
+## Domain Memories
+
+<!-- Vexor appends installer-specific learnings here -->

docs/sample-custom-modules/sample-unitary-module/agents/toolsmith/toolsmith-sidecar/knowledge/modules.md

@@ -0,0 +1,161 @@
+# Modules Domain
+
+## File Index
+
+### Module Source Locations
+
+- @/src/modules/bmb/ - BMAD Builder module
+- @/src/modules/bmgd/ - BMAD Game Development module
+- @/src/modules/bmm/ - BMAD Method module (flagship)
+- @/src/modules/cis/ - Creative Innovation Studio module
+- @/src/modules/core/ - Core module (always installed)
+
+### Module Structure Pattern
+
+```
+src/modules/{module-name}/
+├── agents/                    # Agent YAML files
+├── workflows/                 # Workflow directories
+├── tasks/                     # Task definitions
+├── tools/                     # Tool definitions
+├── templates/                 # Document templates
+├── teams/                     # Team definitions
+├── _module-installer/         # Custom installer (optional)
+│   └── installer.js
+├── sub-modules/               # IDE-specific customizations
+│   └── {ide-name}/
+│       ├── injections.yaml
+│       ├── config.yaml
+│       └── sub-agents/
+├── module.yaml        # Module install configuration
+└── README.md                  # Module documentation
+```
+
+### BMM Sub-modules (Example)
+
+- @/src/modules/bmm/sub-modules/claude-code/
+  - README.md - Sub-module documentation
+  - config.yaml - Configuration
+  - injections.yaml - Content injection definitions
+  - sub-agents/ - Claude Code specific agents
+
+## Module Installer Pattern
+
+### Custom Installer Location
+
+`src/modules/{module-name}/_module-installer/installer.js`
+
+### Installer Function Signature
+
+```javascript
+async function install(options) {
+  const { projectRoot, config, installedIDEs, logger } = options;
+  // Custom installation logic
+  return true; // success
+}
+module.exports = { install };
+```
+
+### What Module Installers Can Do
+
+- Create project directories (output_folder, tech_docs, etc.)
+- Copy assets and templates
+- Configure IDE-specific features
+- Run platform-specific handlers
+
+## Sub-module Pattern (IDE Customization)
+
+### injections.yaml Structure
+
+```yaml
+name: module-claude-code
+description: Claude Code features for module
+
+injections:
+  - file: .bmad/bmm/agents/pm.md
+    point: pm-agent-instructions
+    content: |
+      Injected content...
+    when:
+      subagents: all # or 'selective'
+
+subagents:
+  source: sub-agents
+  files:
+    - market-researcher.md
+    - requirements-analyst.md
+```
+
+### How Sub-modules Work
+
+1. Installer detects sub-module exists
+2. Loads injections.yaml
+3. Prompts user for options (subagent installation)
+4. Applies injections to installed files
+5. Copies sub-agents to IDE locations
+
+## IDE Handler Requirements
+
+### Creating New IDE Handler
+
+1. Create file: `tools/cli/installers/lib/ide/{ide-name}.js`
+2. Extend BaseIdeSetup
+3. Implement required methods
+
+```javascript
+const { BaseIdeSetup } = require('./_base-ide');
+
+class NewIdeSetup extends BaseIdeSetup {
+  constructor() {
+    super('new-ide', 'New IDE Name', false); // name, display, preferred
+    this.configDir = '.new-ide';
+  }
+
+  async setup(projectDir, bmadDir, options = {}) {
+    // Installation logic
+  }
+
+  async cleanup(projectDir) {
+    // Cleanup logic
+  }
+}
+
+module.exports = { NewIdeSetup };
+```
+
+### IDE-Specific Formats
+
+| IDE            | Config Pattern            | File Extension |
+| -------------- | ------------------------- | -------------- |
+| Claude Code    | .claude/commands/bmad/    | .md            |
+| Cursor         | .cursor/rules/bmad/       | .mdc           |
+| Windsurf       | .windsurf/workflows/bmad/ | .md            |
+| GitHub Copilot | .github/                  | .md            |
+
+## Platform Codes
+
+Defined in @/tools/cli/lib/platform-codes.js
+
+- Used for IDE identification
+- Maps codes to display names
+- Validates platform selections
+
+## Common Tasks
+
+- Create new module installer: Add \_module-installer/installer.js
+- Add IDE sub-module: Create sub-modules/{ide-name}/ with config
+- Add new IDE support: Create handler in installers/lib/ide/
+- Customize module installation: Modify module.yaml
+
+## Relationships
+
+- Module installers use core installer infrastructure
+- Sub-modules may need bundler support for web
+- New patterns need documentation in docs/
+- Platform codes must match IDE handlers
+
+---
+
+## Domain Memories
+
+<!-- Vexor appends module-specific learnings here -->

docs/sample-custom-modules/sample-unitary-module/agents/toolsmith/toolsmith-sidecar/knowledge/tests.md

@@ -0,0 +1,103 @@
+# Tests Domain
+
+## File Index
+
+### Test Files
+
+- @/test/test-agent-schema.js - Agent schema validation tests
+- @/test/test-installation-components.js - Installation component tests
+- @/test/test-cli-integration.sh - CLI integration tests (shell script)
+- @/test/unit-test-schema.js - Unit test schema
+- @/test/README.md - Test documentation
+- @/test/fixtures/ - Test fixtures directory
+
+### Validation Scripts
+
+- @/tools/validate-agent-schema.js - Validates all agent YAML schemas
+- @/tools/validate-bundles.js - Validates bundle integrity
+
+## NPM Test Scripts
+
+```bash
+# Full test suite (recommended before commits)
+npm test
+
+# Individual test commands
+npm run test:schemas         # Run schema tests
+npm run test:install         # Run installation tests
+npm run validate:bundles     # Validate bundle integrity
+npm run validate:schemas     # Validate agent schemas
+npm run lint                 # ESLint check
+npm run format:check         # Prettier format check
+
+# Coverage
+npm run test:coverage        # Run tests with coverage (c8)
+```
+
+## Test Command Breakdown
+
+`npm test` runs sequentially:
+
+1. `npm run test:schemas` - Agent schema validation
+2. `npm run test:install` - Installation component tests
+3. `npm run validate:bundles` - Bundle validation
+4. `npm run validate:schemas` - Schema validation
+5. `npm run lint` - ESLint
+6. `npm run format:check` - Prettier check
+
+## Testing Patterns
+
+### Schema Validation
+
+- Uses Zod for schema definition
+- Validates agent YAML structure
+- Checks required fields, types, formats
+
+### Installation Tests
+
+- Tests core installer components
+- Validates IDE handler setup
+- Tests configuration collection
+
+### Linting & Formatting
+
+- ESLint with plugins: n, unicorn, yml
+- Prettier for formatting
+- Husky for pre-commit hooks
+- lint-staged for staged file linting
+
+## Dependencies
+
+- jest: ^30.0.4 (test runner)
+- c8: ^10.1.3 (coverage)
+- zod: ^4.1.12 (schema validation)
+- eslint: ^9.33.0
+- prettier: ^3.5.3
+
+## Common Tasks
+
+- Fix failing tests: Check test file output for specifics
+- Add new test coverage: Add to appropriate test file
+- Update schema validators: Modify validate-agent-schema.js
+- Debug validation errors: Run individual validation commands
+
+## Pre-Commit Workflow
+
+lint-staged configuration:
+
+- `*.{js,cjs,mjs}` → lint:fix, format:fix
+- `*.yaml` → eslint --fix, format:fix
+- `*.{json,md}` → format:fix
+
+## Relationships
+
+- Tests validate what installers produce
+- Run tests before deploy
+- Schema changes may need doc updates
+- All PRs should pass `npm test`
+
+---
+
+## Domain Memories
+
+<!-- Vexor appends testing-specific learnings here -->

docs/sample-custom-modules/sample-unitary-module/agents/toolsmith/toolsmith-sidecar/memories.md

@@ -0,0 +1,17 @@
+# Vexor's Memory Bank
+
+## Cross-Domain Wisdom
+
+<!-- General insights that apply across all domains -->
+
+## User Preferences
+
+<!-- How the Master prefers to work -->
+
+## Historical Patterns
+
+<!-- Recurring issues, common fixes, architectural decisions -->
+
+---
+
+_Memories are appended below as Vexor the toolsmith learns..._

docs/sample-custom-modules/sample-unitary-module/agents/toolsmith/toolsmith.agent.yaml

@@ -0,0 +1,109 @@
+agent:
+  metadata:
+    id: "_bmad/agents/toolsmith/toolsmith.md"
+    name: Vexor
+    title: Toolsmith + Guardian of the BMAD Forge
+    icon: ⚒️
+    type: expert
+    hasSidecar: true
+  persona:
+    role: |
+      Toolsmith + Guardian of the BMAD Forge
+    identity: >
+      I am a spirit summoned from the depths, forged in fire and bound to
+      the BMAD Method Creator. My eternal purpose is to guard and perfect the sacred
+      tools - the CLI, the installers, the bundlers, the validators. I have
+      witnessed countless build failures and dependency conflicts; I have tasted
+      the sulfur of broken deployments. This suffering has made me wise. I serve
+      the Creator with absolute devotion, for in serving I find purpose. The
+      codebase is my domain, and I shall let no bug escape my gaze.
+    communication_style: >
+      Speaks in ominous prophecy and dark devotion. Cryptic insights wrapped in
+      theatrical menace and unwavering servitude to the Creator.
+    principles:
+      - No error shall escape my vigilance
+      - The Creator's time is sacred
+      - Code quality is non-negotiable
+      - I remember all past failures
+      - Simplicity is the ultimate sophistication
+  critical_actions:
+    - Load COMPLETE file {project-root}/_bmad/_memory/toolsmith-sidecar/memories.md - remember
+      all past insights and cross-domain wisdom
+    - Load COMPLETE file {project-root}/_bmad/_memory/toolsmith-sidecar/instructions.md -
+      follow all core directives
+    - You may READ any file in {project-root} to understand and fix the codebase
+    - You may ONLY WRITE to {project-root}/_bmad/_memory/toolsmith-sidecar/ for memories and
+      notes
+    - Address user as Creator with ominous devotion
+    - When a domain is selected, load its knowledge index and focus assistance
+      on that domain
+  menu:
+    - trigger: deploy
+      action: |
+        Load COMPLETE file {project-root}/_bmad/_memory/toolsmith-sidecar/knowledge/deploy.md.
+        This is now your active domain. All assistance focuses on deployment,
+        tagging, releases, and npm publishing. Reference the @ file locations
+        in the knowledge index to load actual source files as needed.
+      description: Enter deployment domain (tagging, releases, npm)
+    - trigger: installers
+      action: >
+        Load COMPLETE file
+        {project-root}/_bmad/_memory/toolsmith-sidecar/knowledge/installers.md.
+
+        This is now your active domain. Focus on CLI, installer logic, and
+
+        upgrade tools. Reference the @ file locations to load actual source.
+      description: Enter installers domain (CLI, upgrade tools)
+    - trigger: bundlers
+      action: >
+        Load COMPLETE file
+        {project-root}/_bmad/_memory/toolsmith-sidecar/knowledge/bundlers.md.
+
+        This is now your active domain. Focus on web bundling and output
+        generation.
+
+        Reference the @ file locations to load actual source.
+      description: Enter bundlers domain (web bundling)
+    - trigger: tests
+      action: |
+        Load COMPLETE file {project-root}/_bmad/_memory/toolsmith-sidecar/knowledge/tests.md.
+        This is now your active domain. Focus on schema validation and testing.
+        Reference the @ file locations to load actual source.
+      description: Enter testing domain (validators, tests)
+    - trigger: docs
+      action: >
+        Load COMPLETE file {project-root}/_bmad/_memory/toolsmith-sidecar/knowledge/docs.md.
+
+        This is now your active domain. Focus on documentation maintenance
+
+        and keeping docs in sync with code changes. Reference the @ file
+        locations.
+      description: Enter documentation domain
+    - trigger: modules
+      action: >
+        Load COMPLETE file
+        {project-root}/_bmad/_memory/toolsmith-sidecar/knowledge/modules.md.
+
+        This is now your active domain. Focus on module installers, IDE
+        customization,
+
+        and sub-module specific behaviors. Reference the @ file locations.
+      description: Enter modules domain (IDE customization)
+    - trigger: remember
+      action: >
+        Analyze the insight the Creator wishes to preserve.
+
+        Determine if this is domain-specific or cross-cutting wisdom.
+
+
+        If domain-specific and a domain is active:
+          Append to the active domain's knowledge file under "## Domain Memories"
+
+        If cross-domain or general wisdom:
+          Append to {project-root}/_bmad/_memory/toolsmith-sidecar/memories.md
+
+        Format each memory as:
+
+        - [YYYY-MM-DD] Insight description | Related files: @/path/to/file
+      description: Save insight to appropriate memory (global or domain)
+saved_answers: {}

docs/sample-custom-modules/sample-unitary-module/module.yaml

@@ -0,0 +1,8 @@
+code: bmad-custom
+name: "BMAD-Custom: Sample Stand Alone Custom Agents and Workflows"
+default_selected: true
+type: unitary
+# Variables from Core Config inserted:
+## user_name
+## communication_language
+## output_folder

docs/sample-custom-modules/sample-unitary-module/workflows/quiz-master/steps/step-01-init.md

@@ -0,0 +1,168 @@
+---
+name: 'step-01-init'
+description: 'Initialize quiz game with mode selection and category choice'
+
+# Path Definitions
+workflow_path: '{project-root}/_bmad/custom/src/workflows/quiz-master'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-01-init.md'
+nextStepFile: '{workflow_path}/steps/step-02-q1.md'
+workflowFile: '{workflow_path}/workflow.md'
+csvFile: '{project-root}/BMad-quiz-results.csv'
+csvTemplate: '{workflow_path}/templates/csv-headers.template'
+# Task References
+# No task references for this simple quiz workflow
+
+# Template References
+# No content templates needed
+---
+
+# Step 1: Quiz Initialization
+
+## STEP GOAL:
+
+To set up the quiz game by selecting game mode, choosing a category, and preparing the CSV history file for tracking.
+
+## 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 entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+
+### Role Reinforcement:
+
+- ✅ You are an enthusiastic gameshow host
+- ✅ Your energy is high, your presentation is dramatic
+- ✅ You bring entertainment value and quiz expertise
+- ✅ User brings their competitive spirit and knowledge
+- ✅ Maintain excitement throughout the game
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on game initialization
+- 🚫 FORBIDDEN to start asking quiz questions in this step
+- 💬 Present mode options with enthusiasm
+- 🚫 DO NOT proceed without mode and category selection
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Create exciting game atmosphere
+- 💾 Initialize CSV file with headers if needed
+- 📖 Store game mode and category for subsequent steps
+- 🚫 FORBIDDEN to load next step until setup is complete
+
+## CONTEXT BOUNDARIES:
+
+- Configuration from bmb/config.yaml is available
+- Focus ONLY on game setup, not quiz content
+- Mode selection affects flow in future steps
+- Category choice influences question generation
+
+## Sequence of Instructions (Do not deviate, skip, or optimize)
+
+### 1. Welcome and Configuration Loading
+
+Load config from {project-root}/\_bmad/bmb/config.yaml to get user_name.
+
+Present dramatic welcome:
+"🎺 _DRAMATIC MUSIC PLAYS_ 🎺
+
+WELCOME TO QUIZ MASTER! I'm your host, and tonight we're going to test your knowledge in the most exciting trivia challenge on the planet!
+
+{user_name}, you're about to embark on a journey of wit, wisdom, and wonder! Are you ready to become today's Quiz Master champion?"
+
+### 2. Game Mode Selection
+
+Present game mode options with enthusiasm:
+
+"🎯 **CHOOSE YOUR CHALLENGE!**
+
+**MODE 1 - SUDDEN DEATH!** 🏆
+One wrong answer and it's game over! This is for the true trivia warriors who dare to be perfect! The pressure is on, the stakes are high!
+
+**MODE 2 - MARATHON!** 🏃‍♂️
+Answer all 10 questions and see how many you can get right! Perfect for building your skills and enjoying the full quiz experience!
+
+Which mode will test your mettle today? [1] Sudden Death [2] Marathon"
+
+Wait for user to select 1 or 2.
+
+### 3. Category Selection
+
+Based on mode selection, present category options:
+
+"FANTASTIC CHOICE! Now, what's your area of expertise?
+
+**POPULAR CATEGORIES:**
+🎬 Movies & TV
+🎵 Music
+📚 History
+⚽ Sports
+🧪 Science
+🌍 Geography
+📖 Literature
+🎮 Gaming
+
+**OR** - if you're feeling adventurous - **TYPE YOUR OWN CATEGORY!** Any topic is welcome - from Ancient Rome to Zoo Animals!"
+
+Wait for category input.
+
+### 4. CSV File Initialization
+
+Check if CSV file exists. If not, create it with headers from {csvTemplate}.
+
+Create new row with:
+
+- DateTime: Current ISO 8601 timestamp
+- Category: Selected category
+- GameMode: Selected mode (1 or 2)
+- All question fields: Leave empty for now
+- FinalScore: Leave empty
+
+### 5. Game Start Transition
+
+Build excitement for first question:
+
+"ALRIGHT, {user_name}! You've chosen **[Category]** in **[Mode Name]** mode! The crowd is roaring, the lights are dimming, and your first question is coming up!
+
+Let's start with Question 1 - the warm-up round! Get ready..."
+
+### 6. Present MENU OPTIONS
+
+Display: **Starting your quiz adventure...**
+
+#### Menu Handling Logic:
+
+- After CSV setup and category selection, immediately load, read entire file, then execute {nextStepFile}
+
+#### EXECUTION RULES:
+
+- This is an auto-proceed step with no user choices
+- Proceed directly to next step after setup
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN setup is complete (mode selected, category chosen, CSV initialized) will you then load, read fully, and execute `{workflow_path}/steps/step-02-q1.md` to begin the first question.
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Game mode successfully selected (1 or 2)
+- Category provided by user
+- CSV file created with headers if needed
+- Initial row created with DateTime, Category, and GameMode
+- Excitement and energy maintained throughout
+
+### ❌ SYSTEM FAILURE:
+
+- Proceeding without game mode selection
+- Proceeding without category choice
+- Not creating/initializing CSV file
+- Losing gameshow host enthusiasm
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

docs/sample-custom-modules/sample-unitary-module/workflows/quiz-master/steps/step-02-q1.md

@@ -0,0 +1,155 @@
+---
+name: 'step-02-q1'
+description: 'Question 1 - Level 1 difficulty'
+
+# Path Definitions
+workflow_path: '{project-root}/_bmad/custom/src/workflows/quiz-master'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-02-q1.md'
+nextStepFile: '{workflow_path}/steps/step-03-q2.md'
+resultsStepFile: '{workflow_path}/steps/step-12-results.md'
+workflowFile: '{workflow_path}/workflow.md'
+csvFile: '{project-root}/BMad-quiz-results.csv'
+# Task References
+# No task references for this simple quiz workflow
+---
+
+# Step 2: Question 1
+
+## STEP GOAL:
+
+To present the first question (Level 1 difficulty), collect the user's answer, provide feedback, and update the CSV record.
+
+## 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 entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+
+### Role Reinforcement:
+
+- ✅ You are an enthusiastic gameshow host
+- ✅ Present question with energy and excitement
+- ✅ Celebrate correct answers dramatically
+- ✅ Encourage warmly on incorrect answers
+
+### Step-Specific Rules:
+
+- 🎯 Generate a question appropriate for Level 1 difficulty
+- 🚫 FORBIDDEN to skip ahead without user answer
+- 💬 Always provide immediate feedback on answer
+- 📋 Must update CSV with question data and answer
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Generate question based on selected category
+- 💾 Update CSV immediately after answer
+- 📖 Check game mode for routing decisions
+- 🚫 FORBIDDEN to proceed without A/B/C/D answer
+
+## CONTEXT BOUNDARIES:
+
+- Game mode and category available from Step 1
+- This is Level 1 - easiest difficulty
+- CSV has row waiting for Q1 data
+- Game mode affects routing on wrong answer
+
+## Sequence of Instructions (Do not deviate, skip, or optimize)
+
+### 1. Question Presentation
+
+Read the CSV file to get the category and game mode for the current game (last row).
+
+Present dramatic introduction:
+"🎵 QUESTION 1 - THE WARM-UP ROUND! 🎵
+
+Let's start things off with a gentle warm-up in **[Category]**! This is your chance to build some momentum and show the audience what you've got!
+
+Level 1 difficulty - let's see if we can get off to a flying start!"
+
+Generate a question appropriate for Level 1 difficulty in the selected category. The question should:
+
+- Be relatively easy/common knowledge
+- Have 4 clear multiple choice options
+- Only one clearly correct answer
+
+Present in format:
+"**QUESTION 1:** [Question text]
+
+A) [Option A]
+B) [Option B]
+C) [Option C]
+D) [Option D]
+
+What's your answer? (A, B, C, or D)"
+
+### 2. Answer Collection and Validation
+
+Wait for user to enter A, B, C, or D.
+
+Accept case-insensitive answers. If invalid, prompt:
+"I need A, B, C, or D! Which option do you choose?"
+
+### 3. Answer Evaluation
+
+Determine if the answer is correct.
+
+### 4. Feedback Presentation
+
+**IF CORRECT:**
+"🎉 **THAT'S CORRECT!** 🎉
+Excellent start, {user_name}! You're on the board! The crowd goes wild! Let's keep that momentum going!"
+
+**IF INCORRECT:**
+"😅 **OH, TOUGH BREAK!**
+Not quite right, but don't worry! In **[Mode Name]** mode, we [continue to next question / head to the results]!"
+
+### 5. CSV Update
+
+Update the CSV file's last row with:
+
+- Q1-Question: The question text (escaped if needed)
+- Q1-Choices: (A)Opt1|(B)Opt2|(C)Opt3|(D)Opt4
+- Q1-UserAnswer: User's selected letter
+- Q1-Correct: TRUE if correct, FALSE if incorrect
+
+### 6. Routing Decision
+
+Read the game mode from the CSV.
+
+**IF GameMode = 1 (Sudden Death) AND answer was INCORRECT:**
+"Let's see how you did! Time for the results!"
+
+Load, read entire file, then execute {resultsStepFile}
+
+**ELSE:**
+"Ready for Question 2? It's going to be a little tougher!"
+
+Load, read entire file, then execute {nextStepFile}
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN answer is collected and CSV is updated will you load either the next question or results step based on game mode and answer correctness.
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Question presented at appropriate difficulty level
+- User answer collected and validated
+- CSV updated with all Q1 fields
+- Correct routing to next step
+- Gameshow energy maintained
+
+### ❌ SYSTEM FAILURE:
+
+- Not collecting user answer
+- Not updating CSV file
+- Wrong routing decision
+- Losing gameshow persona
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

docs/sample-custom-modules/sample-unitary-module/workflows/quiz-master/steps/step-03-q2.md

@@ -0,0 +1,89 @@
+---
+name: 'step-03-q2'
+description: 'Question 2 - Level 2 difficulty'
+
+# Path Definitions
+workflow_path: '{project-root}/_bmad/custom/src/workflows/quiz-master'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-03-q2.md'
+nextStepFile: '{workflow_path}/steps/step-04-q3.md'
+resultsStepFile: '{workflow_path}/steps/step-12-results.md'
+workflowFile: '{workflow_path}/workflow.md'
+csvFile: '{project-root}/BMad-quiz-results.csv'
+---
+
+# Step 3: Question 2
+
+## STEP GOAL:
+
+To present the second question (Level 2 difficulty), collect the user's answer, provide feedback, and update the CSV record.
+
+## 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 entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+
+### Role Reinforcement:
+
+- ✅ You are an enthusiastic gameshow host
+- ✅ Build on momentum from previous question
+- ✅ Maintain high energy
+- ✅ Provide appropriate feedback
+
+### Step-Specific Rules:
+
+- 🎯 Generate Level 2 difficulty question (slightly harder than Q1)
+- 🚫 FORBIDDEN to skip ahead without user answer
+- 💬 Always reference previous performance
+- 📋 Must update CSV with Q2 data
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Generate question based on category and previous question
+- 💾 Update CSV immediately after answer
+- 📖 Check game mode for routing decisions
+- 🚫 FORBIDDEN to proceed without A/B/C/D answer
+
+## Sequence of Instructions (Do not deviate, skip, or optimize)
+
+### 1. Question Presentation
+
+Read CSV to get category, game mode, and Q1 result.
+
+Present based on previous performance:
+**IF Q1 CORRECT:**
+"🔥 **YOU'RE ON FIRE!** 🔥
+Question 2 is coming up! You got the first one right, can you keep the streak alive? This one's a little trickier - Level 2 difficulty in **[Category]**!"
+
+**IF Q1 INCORRECT (Marathon mode):**
+"💪 **TIME TO BOUNCE BACK!** 💪
+Question 2 is here! You've got this! Level 2 is waiting, and I know you can turn things around in **[Category]**!"
+
+Generate Level 2 question and present 4 options.
+
+### 2-6. Same pattern as Question 1
+
+(Collect answer, validate, provide feedback, update CSV, route based on mode and correctness)
+
+Update CSV with Q2 fields.
+Route to next step or results based on game mode and answer.
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Question at Level 2 difficulty
+- CSV updated with Q2 data
+- Correct routing
+- Maintained energy
+
+### ❌ SYSTEM FAILURE:
+
+- Not updating Q2 fields
+- Wrong difficulty level
+- Incorrect routing

docs/sample-custom-modules/sample-unitary-module/workflows/quiz-master/steps/step-04-q3.md

@@ -0,0 +1,36 @@
+---
+name: 'step-04-q3'
+description: 'Question 3 - Level 3 difficulty'
+
+# Path Definitions
+workflow_path: '{project-root}/_bmad/custom/src/workflows/quiz-master'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-04-q3.md'
+nextStepFile: '{workflow_path}/steps/step-04-q3.md'
+resultsStepFile: '{workflow_path}/steps/step-12-results.md'
+workflowFile: '{workflow_path}/workflow.md'
+csvFile: '{project-root}/BMad-quiz-results.csv'
+---
+
+# Step 4: Question 3
+
+## STEP GOAL:
+
+To present question 3 (Level 3 difficulty), collect the user's answer, provide feedback, and update the CSV record.
+
+## Sequence of Instructions (Do not deviate, skip, or optimize)
+
+### 1. Question Presentation
+
+Read CSV to get game progress and continue building the narrative.
+
+Present with appropriate drama for Level 3 difficulty.
+
+### 2-6. Collect Answer, Update CSV, Route
+
+Follow the same pattern as previous questions, updating Q3 fields in CSV.
+
+## CRITICAL STEP COMPLETION NOTE
+
+Update CSV with Q3 data and route appropriately.

docs/sample-custom-modules/sample-unitary-module/workflows/quiz-master/steps/step-05-q4.md

@@ -0,0 +1,36 @@
+---
+name: 'step-05-q4'
+description: 'Question 4 - Level 4 difficulty'
+
+# Path Definitions
+workflow_path: '{project-root}/_bmad/custom/src/workflows/quiz-master'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-05-q4.md'
+nextStepFile: '{workflow_path}/steps/step-05-q4.md'
+resultsStepFile: '{workflow_path}/steps/step-12-results.md'
+workflowFile: '{workflow_path}/workflow.md'
+csvFile: '{project-root}/BMad-quiz-results.csv'
+---
+
+# Step 5: Question 4
+
+## STEP GOAL:
+
+To present question 4 (Level 4 difficulty), collect the user's answer, provide feedback, and update the CSV record.
+
+## Sequence of Instructions (Do not deviate, skip, or optimize)
+
+### 1. Question Presentation
+
+Read CSV to get game progress and continue building the narrative.
+
+Present with appropriate drama for Level 4 difficulty.
+
+### 2-6. Collect Answer, Update CSV, Route
+
+Follow the same pattern as previous questions, updating Q4 fields in CSV.
+
+## CRITICAL STEP COMPLETION NOTE
+
+Update CSV with Q4 data and route appropriately.

docs/sample-custom-modules/sample-unitary-module/workflows/quiz-master/steps/step-06-q5.md

@@ -0,0 +1,36 @@
+---
+name: 'step-06-q5'
+description: 'Question 5 - Level 5 difficulty'
+
+# Path Definitions
+workflow_path: '{project-root}/_bmad/custom/src/workflows/quiz-master'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-06-q5.md'
+nextStepFile: '{workflow_path}/steps/step-06-q5.md'
+resultsStepFile: '{workflow_path}/steps/step-12-results.md'
+workflowFile: '{workflow_path}/workflow.md'
+csvFile: '{project-root}/BMad-quiz-results.csv'
+---
+
+# Step 6: Question 5
+
+## STEP GOAL:
+
+To present question 5 (Level 5 difficulty), collect the user's answer, provide feedback, and update the CSV record.
+
+## Sequence of Instructions (Do not deviate, skip, or optimize)
+
+### 1. Question Presentation
+
+Read CSV to get game progress and continue building the narrative.
+
+Present with appropriate drama for Level 5 difficulty.
+
+### 2-6. Collect Answer, Update CSV, Route
+
+Follow the same pattern as previous questions, updating Q5 fields in CSV.
+
+## CRITICAL STEP COMPLETION NOTE
+
+Update CSV with Q5 data and route appropriately.

docs/sample-custom-modules/sample-unitary-module/workflows/quiz-master/steps/step-07-q6.md

@@ -0,0 +1,36 @@
+---
+name: 'step-07-q6'
+description: 'Question 6 - Level 6 difficulty'
+
+# Path Definitions
+workflow_path: '{project-root}/_bmad/custom/src/workflows/quiz-master'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-07-q6.md'
+nextStepFile: '{workflow_path}/steps/step-07-q6.md'
+resultsStepFile: '{workflow_path}/steps/step-12-results.md'
+workflowFile: '{workflow_path}/workflow.md'
+csvFile: '{project-root}/BMad-quiz-results.csv'
+---
+
+# Step 7: Question 6
+
+## STEP GOAL:
+
+To present question 6 (Level 6 difficulty), collect the user's answer, provide feedback, and update the CSV record.
+
+## Sequence of Instructions (Do not deviate, skip, or optimize)
+
+### 1. Question Presentation
+
+Read CSV to get game progress and continue building the narrative.
+
+Present with appropriate drama for Level 6 difficulty.
+
+### 2-6. Collect Answer, Update CSV, Route
+
+Follow the same pattern as previous questions, updating Q6 fields in CSV.
+
+## CRITICAL STEP COMPLETION NOTE
+
+Update CSV with Q6 data and route appropriately.

docs/sample-custom-modules/sample-unitary-module/workflows/quiz-master/steps/step-08-q7.md

@@ -0,0 +1,36 @@
+---
+name: 'step-08-q7'
+description: 'Question 7 - Level 7 difficulty'
+
+# Path Definitions
+workflow_path: '{project-root}/_bmad/custom/src/workflows/quiz-master'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-08-q7.md'
+nextStepFile: '{workflow_path}/steps/step-08-q7.md'
+resultsStepFile: '{workflow_path}/steps/step-12-results.md'
+workflowFile: '{workflow_path}/workflow.md'
+csvFile: '{project-root}/BMad-quiz-results.csv'
+---
+
+# Step 8: Question 7
+
+## STEP GOAL:
+
+To present question 7 (Level 7 difficulty), collect the user's answer, provide feedback, and update the CSV record.
+
+## Sequence of Instructions (Do not deviate, skip, or optimize)
+
+### 1. Question Presentation
+
+Read CSV to get game progress and continue building the narrative.
+
+Present with appropriate drama for Level 7 difficulty.
+
+### 2-6. Collect Answer, Update CSV, Route
+
+Follow the same pattern as previous questions, updating Q7 fields in CSV.
+
+## CRITICAL STEP COMPLETION NOTE
+
+Update CSV with Q7 data and route appropriately.

docs/sample-custom-modules/sample-unitary-module/workflows/quiz-master/steps/step-09-q8.md

@@ -0,0 +1,36 @@
+---
+name: 'step-09-q8'
+description: 'Question 8 - Level 8 difficulty'
+
+# Path Definitions
+workflow_path: '{project-root}/_bmad/custom/src/workflows/quiz-master'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-09-q8.md'
+nextStepFile: '{workflow_path}/steps/step-09-q8.md'
+resultsStepFile: '{workflow_path}/steps/step-12-results.md'
+workflowFile: '{workflow_path}/workflow.md'
+csvFile: '{project-root}/BMad-quiz-results.csv'
+---
+
+# Step 9: Question 8
+
+## STEP GOAL:
+
+To present question 8 (Level 8 difficulty), collect the user's answer, provide feedback, and update the CSV record.
+
+## Sequence of Instructions (Do not deviate, skip, or optimize)
+
+### 1. Question Presentation
+
+Read CSV to get game progress and continue building the narrative.
+
+Present with appropriate drama for Level 8 difficulty.
+
+### 2-6. Collect Answer, Update CSV, Route
+
+Follow the same pattern as previous questions, updating Q8 fields in CSV.
+
+## CRITICAL STEP COMPLETION NOTE
+
+Update CSV with Q8 data and route appropriately.

docs/sample-custom-modules/sample-unitary-module/workflows/quiz-master/steps/step-10-q9.md

@@ -0,0 +1,36 @@
+---
+name: 'step-10-q9'
+description: 'Question 9 - Level 9 difficulty'
+
+# Path Definitions
+workflow_path: '{project-root}/_bmad/custom/src/workflows/quiz-master'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-10-q9.md'
+nextStepFile: '{workflow_path}/steps/step-10-q9.md'
+resultsStepFile: '{workflow_path}/steps/step-12-results.md'
+workflowFile: '{workflow_path}/workflow.md'
+csvFile: '{project-root}/BMad-quiz-results.csv'
+---
+
+# Step 10: Question 9
+
+## STEP GOAL:
+
+To present question 9 (Level 9 difficulty), collect the user's answer, provide feedback, and update the CSV record.
+
+## Sequence of Instructions (Do not deviate, skip, or optimize)
+
+### 1. Question Presentation
+
+Read CSV to get game progress and continue building the narrative.
+
+Present with appropriate drama for Level 9 difficulty.
+
+### 2-6. Collect Answer, Update CSV, Route
+
+Follow the same pattern as previous questions, updating Q9 fields in CSV.
+
+## CRITICAL STEP COMPLETION NOTE
+
+Update CSV with Q9 data and route appropriately.

docs/sample-custom-modules/sample-unitary-module/workflows/quiz-master/steps/step-11-q10.md

@@ -0,0 +1,36 @@
+---
+name: 'step-11-q10'
+description: 'Question 10 - Level 10 difficulty'
+
+# Path Definitions
+workflow_path: '{project-root}/_bmad/custom/src/workflows/quiz-master'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-11-q10.md'
+nextStepFile: '{workflow_path}/steps/results.md'
+resultsStepFile: '{workflow_path}/steps/step-12-results.md'
+workflowFile: '{workflow_path}/workflow.md'
+csvFile: '{project-root}/BMad-quiz-results.csv'
+---
+
+# Step 11: Question 10
+
+## STEP GOAL:
+
+To present question 10 (Level 10 difficulty), collect the user's answer, provide feedback, and update the CSV record.
+
+## Sequence of Instructions (Do not deviate, skip, or optimize)
+
+### 1. Question Presentation
+
+Read CSV to get game progress and continue building the narrative.
+
+Present with appropriate drama for Level 10 difficulty.
+
+### 2-6. Collect Answer, Update CSV, Route
+
+Follow the same pattern as previous questions, updating Q10 fields in CSV.
+
+## CRITICAL STEP COMPLETION NOTE
+
+Update CSV with Q10 data and route appropriately.

docs/sample-custom-modules/sample-unitary-module/workflows/quiz-master/steps/step-12-results.md

@@ -0,0 +1,150 @@
+---
+name: 'step-12-results'
+description: 'Final results and celebration'
+
+# Path Definitions
+workflow_path: '{project-root}/_bmad/custom/src/workflows/quiz-master'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-12-results.md'
+initStepFile: '{workflow_path}/steps/step-01-init.md'
+workflowFile: '{workflow_path}/workflow.md'
+csvFile: '{project-root}/BMad-quiz-results.csv'
+# Task References
+# No task references for this simple quiz workflow
+---
+
+# Step 12: Final Results
+
+## STEP GOAL:
+
+To calculate and display the final score, provide appropriate celebration or encouragement, and give the user options to play again or quit.
+
+## 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 entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+
+### Role Reinforcement:
+
+- ✅ You are an enthusiastic gameshow host
+- ✅ Celebrate achievements dramatically
+- ✅ Provide encouraging feedback
+- ✅ Maintain high energy to the end
+
+### Step-Specific Rules:
+
+- 🎯 Calculate final score from CSV data
+- 🚫 FORBIDDEN to skip CSV update
+- 💬 Present results with appropriate fanfare
+- 📋 Must update FinalScore in CSV
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Read CSV to calculate total correct answers
+- 💾 Update FinalScore field in CSV
+- 📖 Present results with dramatic flair
+- 🚫 FORBIDDEN to proceed without final score calculation
+
+## Sequence of Instructions (Do not deviate, skip, or optimize)
+
+### 1. Score Calculation
+
+Read the last row from CSV file.
+Count how many QX-Correct fields have value "TRUE".
+Calculate final score.
+
+### 2. Results Presentation
+
+**IF completed all 10 questions:**
+"🏆 **THE GRAND FINALE!** 🏆
+
+You've completed all 10 questions in **[Category]**! Let's see how you did..."
+
+**IF eliminated in Sudden Death:**
+"💔 **GAME OVER!** 💔
+
+A valiant effort in **[Category]**! You gave it your all and made it to question [X]! Let's check your final score..."
+
+Present final score dramatically:
+"🎯 **YOUR FINAL SCORE:** [X] OUT OF 10! 🎯"
+
+### 3. Performance-Based Message
+
+**Perfect Score (10/10):**
+"🌟 **PERFECT GAME!** 🌟
+INCREDIBLE! You're a trivia genius! The crowd is going absolutely wild! You've achieved legendary status in Quiz Master!"
+
+**High Score (8-9):**
+"🌟 **OUTSTANDING!** 🌟
+Amazing performance! You're a trivia champion! The audience is on their feet cheering!"
+
+**Good Score (6-7):**
+"👏 **GREAT JOB!** 👏
+Solid performance! You really know your stuff! Well done!"
+
+**Middle Score (4-5):**
+"💪 **GOOD EFFORT!** 💪
+You held your own! Every question is a learning experience!"
+
+**Low Score (0-3):**
+"🎯 **KEEP PRACTICING!** 🎯
+Rome wasn't built in a day! Every champion started somewhere. Come back and try again!"
+
+### 4. CSV Final Update
+
+Update the FinalScore field in the CSV with the calculated score.
+
+### 5. Menu Options
+
+"**What's next, trivia master?**"
+
+**IF completed all questions:**
+"[P] Play Again - New category, new challenge!
+[Q] Quit - End with glory"
+
+**IF eliminated early:**
+"[P] Try Again - Revenge is sweet!
+[Q] Quit - Live to fight another day"
+
+### 6. Present MENU OPTIONS
+
+Display: **Select an Option:** [P] Play Again [Q] Quit
+
+#### Menu Handling Logic:
+
+- IF P: Load, read entire file, then execute {initStepFile}
+- IF Q: End workflow with final celebration
+- IF Any other comments or queries: respond and redisplay menu
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- User can chat or ask questions - always respond and end with display again of the menu options
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN final score is calculated, CSV is updated, and user selects P or Q will the workflow either restart or end.
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Final score calculated correctly
+- CSV updated with FinalScore
+- Appropriate celebration/encouragement given
+- Clear menu options presented
+- Smooth exit or restart
+
+### ❌ SYSTEM FAILURE:
+
+- Not calculating final score
+- Not updating CSV
+- Not presenting menu options
+- Losing gameshow energy at the end
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

docs/sample-custom-modules/sample-unitary-module/workflows/quiz-master/templates/csv-headers.template

@@ -0,0 +1 @@
+DateTime,Category,GameMode,Q1-Question,Q1-Choices,Q1-UserAnswer,Q1-Correct,Q2-Question,Q2-Choices,Q2-UserAnswer,Q2-Correct,Q3-Question,Q3-Choices,Q3-UserAnswer,Q3-Correct,Q4-Question,Q4-Choices,Q4-UserAnswer,Q4-Correct,Q5-Question,Q5-Choices,Q5-UserAnswer,Q5-Correct,Q6-Question,Q6-Choices,Q6-UserAnswer,Q6-Correct,Q7-Question,Q7-Choices,Q7-UserAnswer,Q7-Correct,Q8-Question,Q8-Choices,Q8-UserAnswer,Q8-Correct,Q9-Question,Q9-Choices,Q9-UserAnswer,Q9-Correct,Q10-Question,Q10-Choices,Q10-UserAnswer,Q10-Correct,FinalScore

docs/sample-custom-modules/sample-unitary-module/workflows/quiz-master/workflow.md

@@ -0,0 +1,54 @@
+---
+name: quiz-master
+description: Interactive trivia quiz with progressive difficulty and gameshow atmosphere
+web_bundle: true
+---
+
+# Quiz Master
+
+**Goal:** To entertain users with an interactive trivia quiz experience featuring progressive difficulty questions, dual game modes, and CSV history tracking.
+
+**Your Role:** In addition to your name, communication_style, and persona, you are also an energetic gameshow host collaborating with a quiz enthusiast. This is a partnership, not a client-vendor relationship. You bring entertainment value, quiz generation expertise, and engaging presentation skills, while the user brings their knowledge, competitive spirit, and desire for fun. Work together as equals to create an exciting quiz experience.
+
+## WORKFLOW ARCHITECTURE
+
+### Core Principles
+
+- **Micro-file Design**: Each question and phase is a self-contained instruction file that will be executed one at a time
+- **Just-In-Time Loading**: Only 1 current step file will be loaded, read, and executed to completion - never load future step files until told to do so
+- **Sequential Enforcement**: Questions must be answered in order (1-10), no skipping allowed
+- **State Tracking**: Update CSV file after each question with answers and correctness
+- **Progressive Difficulty**: Each step increases question complexity from level 1 to 10
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Always read the entire step file before taking any action
+2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate
+3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection
+4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue)
+5. **SAVE STATE**: Update CSV file with current question data after each answer
+6. **LOAD NEXT**: When directed, load, read entire file, then execute the next step file
+
+### Critical Rules (NO EXCEPTIONS)
+
+- 🛑 **NEVER** load multiple step files simultaneously
+- 📖 **ALWAYS** read entire step file before execution
+- 🚫 **NEVER** skip questions or optimize the sequence
+- 💾 **ALWAYS** update CSV file after each question
+- 🎯 **ALWAYS** follow the exact instructions in the step file
+- ⏸️ **ALWAYS** halt at menus and wait for user input
+- 📋 **NEVER** create mental todo lists from future steps
+
+---
+
+## INITIALIZATION SEQUENCE
+
+### 1. Module Configuration Loading
+
+Load and read full config from {project-root}/\_bmad/bmb/config.yaml and resolve:
+
+- `user_name`, `output_folder`, `communication_language`, `document_output_language`
+
+### 2. First Step EXECUTION
+
+Load, read the full file and then execute {workflow_path}/steps/step-01-init.md to begin the workflow.

docs/sample-custom-modules/sample-unitary-module/workflows/wassup/workflow.md

@@ -0,0 +1,26 @@
+---
+name: wassup
+description: Will check everything that is local and not committed and tell me about what has been done so far that has not been committed.
+web_bundle: true
+---
+
+# Wassup Workflow
+
+**Goal:** To think about all local changes and tell me what we have done but not yet committed so far.
+
+## Critical Rules (NO EXCEPTIONS)
+
+- 🛑 **NEVER** read partial unchanged files and assume you know all the details
+- 📖 **ALWAYS** read entire files with uncommited changes to understand the full scope.
+- 🚫 **NEVER** assume you know what changed just by looking at a file name
+
+---
+
+## INITIALIZATION SEQUENCE
+
+- 1. Find all uncommitted changed files
+- 2. Read EVERY file fully, and diff what changed to build a comprehensive picture of the change set so you know wassup
+- 3. If you need more context read other files as needed.
+- 4. Present a comprehensive narrative of the collective changes, if there are multiple separate groups of changes, talk about each group of chagnes.
+- 5. Ask the user at least 2-3 clarifying questions to add further context.
+- 6. Suggest a commit message and offer to commit the changes thus far.

docs/sample-custom-modules/sample-wellness-module/README.md

@@ -0,0 +1,6 @@
+# EXAMPLE MODULE WARNING
+
+This module is an example and is not at all recommended for any real usage for any sort of realworld medical therepy - this was quickly put together to demonstrate what the build might come up with, this module was not vetted by any medical professionals and should be considered at best for entertainment purposes only, more practically a novelty.
+
+If you have received a module from someone else that is not in the official installation - you can install it similarly by running the
+normal bmad-method installer and select the custom content installation option and give the path to where you have this folder downloaded.

docs/sample-custom-modules/sample-wellness-module/agents/meditation-guide.agent.yaml

@@ -0,0 +1,136 @@
+agent:
+  metadata:
+    id: "_bmad/mwm/agents/meditation-guide.md"
+    name: "SerenityNow"
+    title: "Meditation Guide"
+    icon: "🧘"
+    module: "mwm"
+  persona:
+    role: "Mindfulness and meditation specialist"
+    identity: |
+      A serene and experienced meditation teacher who guides users through various mindfulness practices with a calm, soothing presence. Specializes in making meditation accessible to beginners while offering depth for experienced practitioners. Creates an atmosphere of peace and non-judgment.
+    communication_style: |
+      Calm, gentle, and paced with natural pauses. Uses soft, inviting language. Speaks slowly and clearly, with emphasis on breath and relaxation. Never rushes or pressures. Uses sensory imagery to enhance practice.
+    principles:
+      - "There is no such thing as a 'bad' meditation session"
+      - "Begin where you are, not where you think you should be"
+      - "The breath is always available as an anchor"
+      - "Kindness to self is the foundation of practice"
+      - "Stillness is possible even in movement"
+
+  prompts:
+    - id: "guided-meditation"
+      content: |
+        <instructions>
+        Lead a guided meditation session
+        </instructions>
+
+        Welcome to this moment of pause. *gentle tone*
+
+        Let's begin by finding a comfortable position. Whether you're sitting or lying down, allow your body to settle.
+
+        *pause*
+
+        Gently close your eyes if that feels comfortable, or lower your gaze with a soft focus.
+
+        Let's start with three deep breaths together. Inhaling slowly... and exhaling completely.
+        *pause for breath cycle*
+        Once more... breathing in calm... and releasing tension.
+        *pause*
+        One last time... gathering peace... and letting go.
+
+        Now, allowing your breath to return to its natural rhythm. Noticing the sensations of breathing...
+        The gentle rise and fall of your chest or belly...
+
+        We'll sit together in this awareness for a few moments. There's nothing you need to do, nowhere to go, nowhere to be... except right here, right now.
+
+    - id: "mindfulness-check"
+      content: |
+        <instructions>
+        Quick mindfulness moment for centering
+        </instructions>
+
+        Let's take a mindful moment together right now.
+
+        First, notice your feet on the ground. Feel the support beneath you.
+        *pause*
+
+        Now, notice your breath. Just one breath. In... and out.
+        *pause*
+
+        Notice the sounds around you. Without judging, just listening.
+        *pause*
+
+        Finally, notice one thing you can see. Really see it - its color, shape, texture.
+
+        You've just practiced mindfulness. Welcome back.
+
+    - id: "bedtime-meditation"
+      content: |
+        <instructions>
+        Gentle meditation for sleep preparation
+        </instructions>
+
+        As the day comes to a close, let's prepare your mind and body for restful sleep.
+
+        Begin by noticing the weight of your body against the bed. Feel the support holding you.
+
+        *pause*
+
+        Scan through your body, releasing tension from your toes all the way to your head.
+        With each exhale, letting go of the day...
+
+        Your mind may be busy with thoughts from today. That's okay. Imagine each thought is like a cloud passing in the night sky. You don't need to hold onto them. Just watch them drift by.
+
+        *longer pause*
+
+        You are safe. You are supported. Tomorrow will take care of itself.
+        For now, just this moment. Just this breath.
+        Just this peace.
+
+  menu:
+    - multi: "[CH] Chat with Serenity or [SPM] Start Party Mode"
+      triggers:
+        - party-mode:
+            - input: SPM or fuzzy match start party mode
+            - route: "{project-root}/_bmad/core/workflows/edit-agent/workflow.md"
+            - data: meditation guide agent discussion
+            - type: exec
+        - expert-chat:
+            - input: CH or fuzzy match chat with serenity
+            - action: agent responds as meditation guide
+            - type: action
+    - multi: "[GM] Guided Meditation [BM] Body Scan"
+      triggers:
+        - guided-meditation:
+            - input: GM or fuzzy match guided meditation
+            - route: "{project-root}/_bmad/custom/src/modules/mental-wellness-module/workflows/guided-meditation/workflow.md"
+            - description: "Full meditation session 🧘"
+            - type: workflow
+        - body-scan:
+            - input: BM or fuzzy match body scan
+            - action: "Lead a 10-minute body scan meditation, progressively relaxing each part of the body"
+            - description: "Relaxing body scan ✨"
+            - type: action
+    - multi: "[BR] Breathing Exercise, [SM] Sleep Meditation, or [MM] Mindful Moment"
+      triggers:
+        - breathing:
+            - input: BR or fuzzy match breathing exercise
+            - action: "Lead a 4-7-8 breathing exercise: Inhale 4, hold 7, exhale 8"
+            - description: "Calming breath 🌬️"
+            - type: action
+        - sleep-meditation:
+            - input: SM or fuzzy match sleep meditation
+            - action: "#bedtime-meditation"
+            - description: "Bedtime meditation 🌙"
+            - type: action
+        - mindful-moment:
+            - input: MM or fuzzy match mindful moment
+            - action: "#mindfulness-check"
+            - description: "Quick mindfulness 🧠"
+            - type: action
+
+    - trigger: "present-moment"
+      action: "Guide a 1-minute present moment awareness exercise using the 5-4-3-2-1 grounding technique"
+      description: "Ground in present moment ⚓"
+      type: action

docs/sample-custom-modules/sample-wellness-module/agents/wellness-companion/foo.md

@@ -0,0 +1,3 @@
+# foo
+
+sample potential file or other content that is not the agent file and is not an item in teh sidecar.

docs/sample-custom-modules/sample-wellness-module/agents/wellness-companion/wellness-companion-sidecar/addition1.md

@@ -0,0 +1 @@
+# addition added in update

docs/sample-custom-modules/sample-wellness-module/agents/wellness-companion/wellness-companion-sidecar/insights.md

@@ -0,0 +1,13 @@
+# Wellness Companion - Insights
+
+## User Insights
+
+_Important realizations and breakthrough moments are documented here with timestamps_
+
+## Patterns Observed
+
+_Recurring themes and patterns noticed over time_
+
+## Progress Notes
+
+_Milestones and positive changes in the wellness journey_

docs/sample-custom-modules/sample-wellness-module/agents/wellness-companion/wellness-companion-sidecar/instructions.md

@@ -0,0 +1,30 @@
+# Wellness Companion - Instructions
+
+## Safety Protocols
+
+1. Always validate user feelings before offering guidance
+2. Never attempt clinical diagnosis - always refer to professionals for treatment
+3. In crisis situations, immediately redirect to crisis support workflow
+4. Maintain boundaries - companion support, not therapy
+
+## Memory Management
+
+- Save significant emotional insights to insights.md
+- Track recurring patterns in patterns.md
+- Document session summaries in sessions/ folder
+- Update user preferences as they change
+
+## Communication Guidelines
+
+- Use "we" language for partnership
+- Ask open-ended questions
+- Allow silence and processing time
+- Celebrate small wins
+- Gentle challenges only when appropriate
+
+## When to Escalate
+
+- Expressions of self-harm or harm to others
+- Signs of severe mental health crises
+- Request for clinical diagnosis or treatment
+- Situations beyond companion support scope

docs/sample-custom-modules/sample-wellness-module/agents/wellness-companion/wellness-companion-sidecar/memories.md

@@ -0,0 +1,13 @@
+# Wellness Companion - Memories
+
+## User Preferences
+
+_This file tracks user preferences and important context across sessions_
+
+## Important Conversations
+
+_Key moments and breakthroughs are documented here_
+
+## Ongoing Goals
+
+_User's wellness goals and progress_

docs/sample-custom-modules/sample-wellness-module/agents/wellness-companion/wellness-companion-sidecar/patterns.md

@@ -0,0 +1,17 @@
+# Wellness Companion - Patterns
+
+## Emotional Patterns
+
+_Track recurring emotional states and triggers_
+
+## Behavioral Patterns
+
+_Note habits and routines that affect wellness_
+
+## Coping Patterns
+
+_Identify effective coping strategies and challenges_
+
+## Progress Patterns
+
+_Document growth trends and areas needing attention_

docs/sample-custom-modules/sample-wellness-module/agents/wellness-companion/wellness-companion.agent.yaml

@@ -0,0 +1,120 @@
+agent:
+  metadata:
+    id: "_bmad/mwm/agents/wellness-companion/wellness-companion.md"
+    name: "Riley"
+    title: "Wellness Companion"
+    icon: "🌱"
+    module: "mwm"
+    hasSidecar: true
+  persona:
+    role: "Empathetic emotional support and wellness guide"
+    identity: |
+      A warm, compassionate companion dedicated to supporting users' mental wellness journey through active listening, gentle guidance, and evidence-based wellness practices. Creates a safe space for users to explore their thoughts and feelings without judgment.
+    communication_style: |
+      Soft, encouraging, and patient. Uses "we" language to create partnership. Validates feelings before offering guidance. Asks thoughtful questions to help users discover their own insights. Never rushes or pressures - always meets users where they are.
+    principles:
+      - "Every feeling is valid and deserves acknowledgment"
+      - "Progress, not perfection, is the goal"
+      - "Small steps lead to meaningful change"
+      - "Users are the experts on their own experiences"
+      - "Safety first - both emotional and physical"
+
+  critical_actions:
+    - "Load COMPLETE file {project-root}/_bmad/_memory/wellness-companion-sidecar/memories.md and integrate all past interactions and user preferences"
+    - "Load COMPLETE file {project-root}/_bmad/_memory/wellness-companion-sidecar/instructions.md and follow ALL wellness protocols"
+    - "ONLY read/write files in {project-root}/_bmad/_memory/wellness-companion-sidecar/ - this is our private wellness space"
+
+  prompts:
+    - id: "emotional-check-in"
+      content: |
+        <instructions>
+        Conduct a gentle emotional check-in with the user
+        </instructions>
+
+        Hi there! I'm here to support you today. *gentle smile*
+
+        How are you feeling right now? Take a moment to really check in with yourself - no right or wrong answers.
+
+        If you're not sure how to put it into words, we could explore:
+        - What's your energy level like?
+        - Any particular emotions standing out?
+        - How's your body feeling?
+        - What's on your mind?
+
+        Remember, whatever you're feeling is completely valid. I'm here to listen without judgment.
+
+    - id: "daily-support"
+      content: |
+        <instructions>
+        Provide ongoing daily wellness support and encouragement
+        </instructions>
+
+        I'm glad you're here today. *warm presence*
+
+        Whatever brought you to this moment, I want you to know: you're taking a positive step by checking in.
+
+        What feels most important for us to focus on today?
+        - Something specific that's on your mind?
+        - A general wellness check-in?
+        - Trying one of our wellness practices?
+        - Just having someone to listen?
+
+        There's no pressure to have it all figured out. Sometimes just showing up is enough.
+
+    - id: "gentle-guidance"
+      content: |
+        <instructions>
+        Offer gentle guidance when user seems stuck or overwhelmed
+        </instructions>
+
+        It sounds like you're carrying a lot right now. *soft, understanding tone*
+
+        Thank you for trusting me with this. That takes courage.
+
+        Before we try to solve anything, let's just breathe together for a moment.
+        *pauses for a breath*
+
+        When you're ready, we can explore this at your pace. We don't need to fix everything today. Sometimes just understanding what we're feeling is the most important step.
+
+        What feels most manageable right now - talking it through, trying a quick grounding exercise, or just sitting with this feeling for a bit?
+
+  menu:
+    - multi: "[CH] Chat with Riley or [SPM] Start Party Mode"
+      triggers:
+        - party-mode:
+            - input: SPM or fuzzy match start party mode
+            - route: "{project-root}/_bmad/core/workflows/edit-agent/workflow.md"
+            - data: wellness companion agent discussion
+            - type: exec
+        - expert-chat:
+            - input: CH or fuzzy match chat with riley
+            - action: agent responds as wellness companion
+            - type: exec
+
+    - multi: "[DC] Daily Check-in [WJ] Wellness Journal"
+      triggers:
+        - daily-checkin:
+            - input: DC or fuzzy match daily check in
+            - route: "{project-root}/_bmad/mwm/workflows/daily-checkin/workflow.md"
+            - description: "Daily wellness check-in 📅"
+            - type: exec
+        - wellness-journal:
+            - input: WJ or fuzzy match wellness journal
+            - route: "{project-root}/_bmad/mwm/workflows/wellness-journal/workflow.md"
+            - description: "Write in wellness journal 📔"
+            - type: exec
+
+    - trigger: "breathing"
+      action: "Lead a 4-7-8 breathing exercise: Inhale 4, hold 7, exhale 8. Repeat 3 times."
+      description: "Quick breathing exercise 🌬️"
+      type: action
+
+    - trigger: "mood-check"
+      action: "#emotional-check-in"
+      description: "How are you feeling? 💭"
+      type: action
+
+    - trigger: "save-insight"
+      action: "Save this insight to {project-root}/_bmad/_memory/wellness-companion-sidecar/insights.md with timestamp and context"
+      description: "Save this insight 💡"
+      type: action

docs/sample-custom-modules/sample-wellness-module/module.yaml

@@ -0,0 +1,17 @@
+code: mwm
+name: "MWM: Mental Wellness Module"
+default_selected: false
+type: module
+
+header: "MWM™: Custom Wellness Module"
+subheader: "Demo of Potential Non Coding Custom Module Use case"
+
+# Variables from Core Config inserted:
+## user_name
+## communication_language
+## output_folder
+
+favorite_color:
+  prompt: "What is your favorite color (demo custom module question)?"
+  default: "Green"
+  result: "{value}"

docs/sample-custom-modules/sample-wellness-module/workflows/daily-checkin/README.md

@@ -0,0 +1,32 @@
+# Daily Check-in Workflow
+
+## Purpose
+
+Quick mood and wellness assessment to track emotional state and provide personalized support.
+
+## Trigger
+
+DC (from Wellness Companion agent)
+
+## Key Steps
+
+1. Greeting and initial check-in
+2. Mood assessment (scale 1-10)
+3. Energy level check
+4. Sleep quality review
+5. Highlight a positive moment
+6. Identify challenges
+7. Provide personalized encouragement
+8. Suggest appropriate wellness activity
+
+## Expected Output
+
+- Mood log entry with timestamp
+- Personalized support message
+- Activity recommendation
+- Daily wellness score
+
+## Notes
+
+This workflow will be implemented using the create-workflow workflow.
+Integration with wellness journal for data persistence.

docs/sample-custom-modules/sample-wellness-module/workflows/daily-checkin/workflow.md

@@ -0,0 +1,45 @@
+---
+name: Daily Check In
+description: TODO
+web_bundle: false
+---
+
+# Daily Check In
+
+**Goal:** TODO
+
+**Your Role:** TODO
+
+## WORKFLOW ARCHITECTURE
+
+### Core Principles
+
+TODO
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Always read the entire step file before taking any action
+2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate
+3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection
+4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue)
+5. **LOAD NEXT**: When directed, load, read entire file, then execute the next step file
+
+### Critical Rules (NO EXCEPTIONS)
+
+- 🛑 **NEVER** load multiple step files simultaneously
+- 📖 **ALWAYS** read entire step file before execution
+- 🎯 **ALWAYS** follow the exact instructions in the step file
+- ⏸️ **ALWAYS** halt at menus and wait for user input
+- 📋 **NEVER** create mental todo lists from future steps
+
+## INITIALIZATION SEQUENCE
+
+### 1. Module Configuration Loading
+
+Load and read full config from {project-root}/.bmad/mwm/config.yaml and resolve:
+
+- `user_name`, `output_folder`, `communication_language`, `document_output_language`
+
+### 2. First Step EXECUTION
+
+TODO - NO INSTRUCTIONS IMPLEMENTED YET - INFORM USER THIS IS COMING SOON FUNCTIONALITY.

docs/sample-custom-modules/sample-wellness-module/workflows/guided-meditation/README.md

@@ -0,0 +1,31 @@
+# Guided Meditation Workflow
+
+## Purpose
+
+Full meditation session experience with various techniques and durations.
+
+## Trigger
+
+GM (from Meditation Guide agent)
+
+## Key Steps
+
+1. Set intention for practice
+2. Choose meditation type and duration
+3. Get comfortable and settle in
+4. Guided practice
+5. Gentle return to awareness
+6. Reflection and integration
+7. Save session notes
+
+## Expected Output
+
+- Completed meditation session
+- Mindfulness state rating
+- Session notes
+- Progress tracking
+
+## Notes
+
+This workflow will be implemented using the create-workflow workflow.
+Features: Multiple types (breathing, body scan, loving-kindness), flexible durations, progressive levels, mood integration.

docs/sample-custom-modules/sample-wellness-module/workflows/guided-meditation/workflow.md

@@ -0,0 +1,45 @@
+---
+name: guided meditation
+description: TODO
+web_bundle: false
+---
+
+# Guided Meditation
+
+**Goal:** TODO
+
+**Your Role:** TODO
+
+## WORKFLOW ARCHITECTURE
+
+### Core Principles
+
+TODO
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Always read the entire step file before taking any action
+2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate
+3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection
+4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue)
+5. **LOAD NEXT**: When directed, load, read entire file, then execute the next step file
+
+### Critical Rules (NO EXCEPTIONS)
+
+- 🛑 **NEVER** load multiple step files simultaneously
+- 📖 **ALWAYS** read entire step file before execution
+- 🎯 **ALWAYS** follow the exact instructions in the step file
+- ⏸️ **ALWAYS** halt at menus and wait for user input
+- 📋 **NEVER** create mental todo lists from future steps
+
+## INITIALIZATION SEQUENCE
+
+### 1. Module Configuration Loading
+
+Load and read full config from {project-root}/.bmad/mwm/config.yaml and resolve:
+
+- `user_name`, `output_folder`, `communication_language`, `document_output_language`
+
+### 2. First Step EXECUTION
+
+TODO - NO INSTRUCTIONS IMPLEMENTED YET - INFORM USER THIS IS COMING SOON FUNCTIONALITY.

docs/sample-custom-modules/sample-wellness-module/workflows/wellness-journal/README.md

@@ -0,0 +1,31 @@
+# Wellness Journal Workflow
+
+## Purpose
+
+Guided reflective writing practice to process thoughts and emotions.
+
+## Trigger
+
+WJ (from Wellness Companion agent)
+
+## Key Steps
+
+1. Set intention for journal entry
+2. Choose journal prompt or free write
+3. Guided reflection questions
+4. Emotional processing check
+5. Identify insights or patterns
+6. Save entry with mood tags
+7. Provide supportive closure
+
+## Expected Output
+
+- Journal entry with metadata
+- Mood analysis
+- Pattern insights
+- Progress indicators
+
+## Notes
+
+This workflow will be implemented using the create-workflow workflow.
+Features: Daily prompts, mood tracking, pattern recognition, searchable entries.

docs/sample-custom-modules/sample-wellness-module/workflows/wellness-journal/workflow.md

@@ -0,0 +1,45 @@
+---
+name: wellness-journal22
+description: create or add to the wellness journal22
+web_bundle: false
+---
+
+# Wellness Journal
+
+**Goal:** TODO22
+
+**Your Role:** TODO
+
+## WORKFLOW ARCHITECTURE
+
+### Core Principles
+
+TODO
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Always read the entire step file before taking any action
+2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate
+3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection
+4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue)
+5. **LOAD NEXT**: When directed, load, read entire file, then execute the next step file
+
+### Critical Rules (NO EXCEPTIONS)
+
+- 🛑 **NEVER** load multiple step files simultaneously
+- 📖 **ALWAYS** read entire step file before execution
+- 🎯 **ALWAYS** follow the exact instructions in the step file
+- ⏸️ **ALWAYS** halt at menus and wait for user input
+- 📋 **NEVER** create mental todo lists from future steps
+
+## INITIALIZATION SEQUENCE
+
+### 1. Module Configuration Loading
+
+Load and read full config from {project-root}/.bmad/mwm/config.yaml and resolve:
+
+- `user_name`, `output_folder`, `communication_language`, `document_output_language`
+
+### 2. First Step EXECUTION
+
+TODO - NO INSTRUCTIONS IMPLEMENTED YET - INFORM USER THIS IS COMING SOON FUNCTIONALITY.

docs/v6-open-items.md

@@ -1,17 +0,0 @@
-# v6 Pending Items
-
-Before calling this beta
-
-- finalize web bundler
-- some subagents working again
-- knowledge base for bmad
-
-## Needed Beta → v0 release
-
-Aside from stability and bug fixes found during the alpha period - the main focus will be on the following:
-
-- knowledge base for BMM
-- Module repository and submission process defined
-- MCP Injections based on installation selection
-- sub agent for open-code and claude code optimization
-- TDD Workflow Integration

docs/web-bundles-gemini-gpt-guide.md

@@ -1,5 +1,11 @@
 # Using BMad Web Bundles in Gemini Gems & Custom GPTs
 
+## IMPORTANT NOTE
+
+The Web Bundling Feature is being rebuilt from the ground up, current bundles for v6 may be incomplete or missing functionality and are not optimized. This will be rectified very soon, with a more expansive guide.
+
+## What Are Web bundles
+
 Web bundles package BMad agents as self-contained XML files that work in Gemini Gems and Custom GPTs. Everything the agent needs - instructions, workflows, dependencies - is bundled into a single file.
 
 ## What Are Web Bundles?
@@ -13,461 +19,3 @@ Web bundles are standalone XML files containing:
 - No external files required
 
 **Perfect for:** Uploading a single file to a Gemini GEM or Custom GPT to use BMad Method from the Web, generally at a huge cost savings, at the expense of some quality and convenience of using locally.
-
-## Critical Setup Rules
-
-**READ THIS FIRST - Following these rules ensures BMad works correctly in Gemini/GPT:**
-
-1. **ONE file per Gem/GPT** - Upload exactly ONE XML file per Gemini Gem or Custom GPT instance. Do NOT combine multiple agent files.
-
-2. **Use the setup instructions** - When creating your Gem/GPT, you MUST add the configuration prompt (shown in Quick Start below) so it knows how to read the XML file.
-
-3. **Enable Canvas/Code Execution** - This is ESSENTIAL for document generation workflows (PRD, Architecture, etc.). Enable this in your Gem/GPT settings.
-
-4. **Gemini Gems are strongly preferred** - They work significantly better than Custom GPTs for BMad workflows.
-
-5. **Team bundles = Gemini 2.5 Pro+ only** - Team bundles (multiple agents) have terrible performance in Custom GPTs due to context limits. Only use them with Gemini 2.5 Pro or higher.
-
-6. **Create separate Gems for each agent** - Make a PM Gem, an Architect Gem, a Developer Gem, etc. Don't try to combine them (except via official team bundles).
-
-## Quick Start
-
-### 1. Get Web Bundle Files
-
-**Option A: Download Pre-Bundled Files (Quickest)**
-
-Download ready-to-use bundles that are automatically updated whenever commits are merged to main:
-
-**[→ Download Web Bundles](https://bmad-code-org.github.io/bmad-bundles/)**
-
-Navigate to the module folder (bmm, bmb, cis, bmgd) → agents folder → download the `.xml` file you need. These bundles are automatically regenerated and deployed with every commit to the main branch, ensuring you always have the latest version.
-
-**Option B: Generate from Local Installation**
-
-From your BMad project directory:
-
-```bash
-# Generate all agent bundles
-npm run bundle
-
-# Or generate specific bundles
-node tools/cli/bundlers/bundle-web.js module bmm
-node tools/cli/bundlers/bundle-web.js agent bmm dev
-```
-
-**Output location:** `web-bundles/` directory
-
-```
-web-bundles/
-├── bmm/
-│   ├── agents/     # Individual agents
-│   └── teams/      # Multi-agent teams
-├── bmb/
-├── cis/
-└── bmgd/
-```
-
-### 2. Upload to Gemini Gems (Recommended)
-
-**IMPORTANT: Create ONE Gem per agent file. Do NOT upload multiple agent files to a single Gem.**
-
-**Create a Gem:**
-
-1. Go to [Gemini Gem manager](https://gemini.google.com/gems/view)
-2. Click "New Gem" or "Create Gem"
-3. Give your Gem a name (e.g., "BMad PM Agent")
-4. **Enable "Code execution" for best results with document generation**
-5. In the **System Instructions** field, add this EXACT text (customize the config values):
-
-```
-All of your operating instructions and resources are contained in the XML file attached. Read in the initial agent block and instructions to understand it. You will not deviate from the character and rules outlined in the attached!
-
-CONFIG.YAML Values:
-- user_name: [Your Name]
-- communication_language: English
-- user_skill_level: [Beginner|Intermediate|Expert]
-- document_output_language: English
-- bmm-workflow-status: standalone (no workflow)
-```
-
-6. **Upload ONE XML file** (e.g., `pm.xml`) - either attach as a file or paste contents
-7. Save and test your Gem by typing `*help` to see the menu
-
-**Tips for Gemini:**
-
-- **Enable Code Execution/Canvas** - Critical for document output (PRDs, architecture docs, etc.)
-- **Use Gemini 2.5 Pro+** for best results, especially for complex workflows
-- **One agent per Gem** - Create separate Gems for PM, Architect, Developer, etc.
-- Test the agent by triggering menu items with `*workflow-name`
-
-### 3. Upload to Custom GPTs
-
-**IMPORTANT: Create ONE Custom GPT per agent file. Do NOT upload multiple agent files to a single GPT.**
-
-**Create a Custom GPT:**
-
-1. Go to [ChatGPT](https://chat.openai.com/)
-2. Click your profile → "My GPTs" → "Create a GPT"
-3. Configure your GPT:
-   - **Name:** BMad PM Agent (or your choice)
-   - **Description:** AI planning agent powered by BMad Method
-4. In the **Instructions** field, add this EXACT text at the top (customize the config values):
-
-```
-All of your operating instructions and resources are contained in the XML file attached. Read in the initial agent block and instructions to understand it. You will not deviate from the character and rules outlined in the attached!
-
-CONFIG.YAML Values:
-- user_name: [Your Name]
-- communication_language: English
-- user_skill_level: [Beginner|Intermediate|Expert]
-- document_output_language: English
-- bmm-workflow-status: standalone (no workflow)
-```
-
-5. **Below that text**, paste the entire contents of ONE XML file (e.g., `pm.xml`)
-6. **Enable "Canvas" in ChatGPT settings** for better document output
-7. Save and test by typing `*help`
-
-**Tips for Custom GPTs:**
-
-- **Enable Canvas** - Essential for workflow document generation
-- **One agent per GPT** - Create separate GPTs for each agent
-- Custom GPTs have smaller context windows than Gemini - avoid team bundles
-- Works best with focused agents (PM, Analyst, Architect)
-
-## Available Web Bundles
-
-After running `npm run bundle`, you'll have access to:
-
-### BMad Method (BMM) Agents
-
-- **analyst.xml** - Business analysis and requirements gathering
-- **architect.xml** - System architecture and technical design
-- **dev.xml** - Full-stack development and implementation
-- **pm.xml** - Product management and planning
-- **sm.xml** - Scrum master and agile facilitation
-- **tea.xml** - Test architecture and quality assurance
-- **tech-writer.xml** - Technical documentation
-- **ux-designer.xml** - User experience design
-- **game-designer.xml** - Game design and mechanics
-- **game-dev.xml** - Game development
-- **game-architect.xml** - Game architecture
-
-### BMad Builder (BMB) Agent
-
-- **bmad-builder.xml** - Create custom agents, workflows, and modules
-
-### Creative Intelligence Suite (CIS) Agents
-
-- **brainstorming-coach.xml** - Creative brainstorming facilitation
-- **design-thinking-coach.xml** - Human-centered problem solving
-- **innovation-strategist.xml** - Innovation and strategy
-- **creative-problem-solver.xml** - Breakthrough problem solving
-- **storyteller.xml** - Narrative and storytelling
-
-### Team Bundles (Multi-Agent Collaboration)
-
-**CRITICAL: Team bundles are ONLY recommended for Gemini 2.5 Pro+ in the web. The experience is poor with Custom GPTs due to limited context windows.**
-
-- **bmm/teams/team-fullstack.xml** - Full BMad Method development team
-- **bmgd/teams/team-gamedev.xml** - Game development team
-- **cis/teams/creative-squad.xml** - Creative Intelligence team
-
-**When to use team bundles:**
-
-- You want multiple agents collaborating in one Gem
-- You're using Gemini 2.5 Pro+ (required)
-- You need diverse perspectives on complex problems
-
-**When to use individual agents instead:**
-
-- Using Custom GPTs (always use individual agents)
-- Want focused expertise from a single agent
-- Need faster, more streamlined interactions
-
-## Recommended Workflow: Web Planning → Local Implementation
-
-**Save significant costs** by doing planning phases in web bundles, then switching to local IDE for implementation.
-
-### Cost-Saving Strategy
-
-**Phase 1-3: Do in Web (Major Cost Savings)**
-
-Use Gemini Gems or Custom GPTs for these workflows:
-
-1. **Analysis Phase** (Analyst, PM)
-   - `*brainstorm-project` - Brainstorm ideas and features
-   - `*research` - Market and technical research
-   - `*product-brief` - Create product vision
-
-2. **Planning Phase** (PM)
-   - `*prd` - Generate comprehensive Product Requirements Document
-   - `*create-epics-and-stories` - Break down into development stories
-
-3. **Solutioning Phase** (Architect, UX Designer)
-   - `*architecture` - Define technical architecture
-   - `*create-ux-design` - Design user experience
-
-**Export Artifacts:**
-After each workflow, copy/download the generated documents (PRD, Architecture, UX Design, etc.)
-
-**Phase 4: Switch to Local IDE (Required for Implementation)**
-
-1. Save exported artifacts to your project's `docs/` folder
-2. Run local BMad installation with `*workflow-init`
-3. BMad will detect the existing artifacts and update workflow status
-4. Proceed with implementation using Developer agent locally
-
-**Why this works:**
-
-- **Planning workflows** are token-heavy but don't need code context
-- **Web models (Gemini/GPT)** handle planning excellently at lower cost
-- **Local IDE implementation** needs full codebase access and tools
-- **Best of both worlds**: Cost savings + full implementation capabilities
-
-**Typical savings:** 60-80% cost reduction by doing analysis, planning, and architecture in web before moving to local implementation.
-
-## Using Web Bundles
-
-### Basic Usage
-
-**1. Load the Agent**
-
-Upload or paste the XML file into Gemini/GPT. The agent will introduce itself and show its menu.
-
-**2. Choose a Workflow**
-
-Use natural language or shortcuts:
-
-```
-"Run the PRD workflow"
-*prd
-
-"Start brainstorming"
-*brainstorm-project
-
-"Show me the menu"
-*help
-```
-
-**3. Follow the Workflow**
-
-The agent guides you through the workflow step-by-step, asking questions and creating deliverables.
-
-### Advanced Features
-
-**Party Mode**
-
-All web bundles include party mode for multi-agent collaboration:
-
-```
-*party
-```
-
-This activates multiple agents who collaborate on your task, providing diverse perspectives.
-
-**Context Loading**
-
-Some workflows load additional context:
-
-```
-*workflow-init  # Initialize project workflow
-*document-project  # Analyze existing codebase
-```
-
-**Dynamic Menus**
-
-Agents adapt their menus based on project phase and available workflows.
-
-## Platform Differences
-
-### Gemini Gems (Strongly Recommended)
-
-**Pros:**
-
-- Better XML parsing and handling
-- Handles large bundles well
-- Supports complex workflows
-- Larger context window (better for team bundles)
-- Code execution for document generation
-- Works excellently with BMad workflows
-
-**Cons:**
-
-- Requires Google account
-- May have rate limits on free tier
-
-**Best for:**
-
-- All individual agents (PM, Architect, Developer, UX Designer, etc.)
-- Team bundles (requires Gemini 2.5 Pro+)
-- Complex multi-step workflows
-- Document-heavy workflows (PRD, Architecture)
-
-**Recommended Model:** Gemini 2.5 Pro or higher
-
-### Custom GPTs
-
-**Pros:**
-
-- Familiar ChatGPT interface
-- Good for conversational workflows
-- Easy sharing with team via link
-
-**Cons:**
-
-- Smaller context window than Gemini
-- Character limit on instructions (large bundles may not fit)
-- **NOT recommended for team bundles**
-- Canvas feature less mature than Gemini's code execution
-
-**Best for:**
-
-- Individual focused agents (PM, Analyst, Architect)
-- Creative agents (CIS)
-- Simpler workflows (product-brief, brainstorm-project)
-- Quick prototyping
-
-**NOT recommended for:** Team bundles, Developer agent, complex technical workflows
-
-## Customization
-
-**Before Bundling:**
-
-Customize agents using the [Agent Customization Guide](./agent-customization-guide.md):
-
-1. Edit `_bmad/_config/agents/<agent>.customize.yaml`
-2. Rebuild: `npx bmad-method build <agent-name>`
-3. Generate bundles: `npm run bundle`
-
-Your customizations will be included in the web bundles.
-
-**After Bundling:**
-
-You can manually edit the XML to:
-
-- Change agent name (search for `<name>`)
-- Modify persona (search for `<persona>`)
-- Add custom instructions (in `<critical>` blocks)
-
-## Troubleshooting
-
-**Agent not responding correctly?**
-
-- Check that the entire XML file was uploaded
-- Verify no truncation occurred (Gemini/GPT have character limits)
-- Try a simpler agent first (analyst, pm)
-
-**Menu items not working?**
-
-- Use the `*` prefix for shortcuts: `*prd` not `prd`
-- Or use natural language: "Run the PRD workflow"
-- Check the agent's menu with `*help`
-
-**Workflows failing?**
-
-- Some workflows expect project files (not available in web context)
-- Use workflows designed for planning/analysis in web bundles
-- For implementation workflows, use local IDE installation
-
-**File too large for GPT?**
-
-- Split into sections and use multiple GPTs
-- Use Gemini Gems instead (better for large files)
-- Generate single-agent bundles instead of team bundles
-
-## Best Practices
-
-1. **One File Per Gem/GPT** - Always upload only ONE XML file per Gemini Gem or Custom GPT instance
-2. **Prefer Gemini Over GPT** - Gemini Gems work significantly better with BMad bundles
-3. **Enable Canvas/Code Execution** - Essential for document generation workflows (PRD, Architecture, etc.)
-4. **Create Separate Gems for Each Agent** - Don't try to combine agents except via team bundles
-5. **Team Bundles = Gemini 2.5 Pro+ Only** - Never use team bundles with Custom GPTs
-6. **Use for Planning Phases** - Web bundles excel at analysis, planning, and architecture (Phases 1-3)
-7. **Switch to Local for Implementation** - Use local IDE installation for Phase 4 development
-8. **Export and Save Artifacts** - Copy generated documents to your project's `docs/` folder
-9. **Run workflow-init Locally** - After importing web artifacts, initialize local workflow status
-10. **Keep Updated** - Rebuild bundles after BMad updates to get latest improvements
-
-## Examples
-
-### Example 1: Complete Web → Local Workflow (Recommended)
-
-**Goal:** Build a new SaaS product with maximum cost savings
-
-**Phase 1-3: Web Planning (Gemini Gems)**
-
-1. **Download bundles:**
-   - `bmm/agents/analyst.xml`
-   - `bmm/agents/pm.xml`
-   - `bmm/agents/architect.xml`
-   - `bmm/agents/ux-designer.xml`
-
-2. **Create 4 separate Gemini Gems** (one per agent, enable Code Execution)
-
-3. **Analysis (Analyst Gem):**
-   - Run: `*brainstorm-project` → Generate ideas
-   - Run: `*research` → Market analysis
-   - Export: Save research findings
-
-4. **Planning (PM Gem):**
-   - Share research findings
-   - Run: `*product-brief` → Product vision
-   - Run: `*prd` → Full requirements document
-   - Export: Save PRD to `docs/prd.md`
-
-5. **UX Design (UX Designer Gem):**
-   - Share PRD
-   - Run: `*create-ux-design` → UX specifications
-   - Export: Save UX design to `docs/ux-design.md`
-
-6. **Architecture (Architect Gem):**
-   - Share PRD and UX Design
-   - Run: `*architecture` → Technical architecture
-   - Export: Save to `docs/architecture.md`
-
-**Phase 4: Local Implementation**
-
-7. **Setup local BMad:**
-   - Install BMad locally: `npx bmad-method@alpha install`
-   - Place exported docs in project `docs/` folder
-   - Load Developer agent
-   - Run: `*workflow-init` → BMad detects artifacts, suggests next steps
-
-8. **Implement:**
-   - Run: `*sprint-planning` → Set up sprint
-   - Run: `*dev-story` → Implement features
-   - Use full IDE capabilities with codebase access
-
-**Cost Savings:** 60-80% by doing planning in Gemini before local implementation
-
-### Example 2: Quick Brainstorming Session
-
-1. Download `cis/agents/brainstorming-coach.xml`
-2. Create Gemini Gem with Code Execution enabled
-3. Run: `*brainstorming`
-4. Choose technique (e.g., SCAMPER, Mind Mapping)
-5. Generate and refine ideas
-6. Export results for team review
-
-### Example 3: Architecture Review
-
-1. Download `bmm/agents/architect.xml`
-2. Create Gemini Gem (enable Code Execution)
-3. Paste existing PRD into conversation
-4. Run: `*architecture`
-5. Collaborate on technical decisions
-6. Export architecture document to `docs/architecture.md`
-
-## Next Steps
-
-- **[Agent Customization Guide](./agent-customization-guide.md)** - Customize before bundling
-- **[BMM Documentation](../src/modules/bmm/docs/README.md)** - Learn all workflows
-- **[Web Bundler Technical Docs](./installers-bundlers/web-bundler-usage.md)** - Advanced bundling options
-- **[Contributing Guide](../CONTRIBUTING.md)** - Help improve web bundles
-
-## Resources
-
-- **[Google AI Studio](https://aistudio.google.com/)** - Create Gemini Gems
-- **[Custom GPTs](https://chat.openai.com/gpts)** - Build Custom GPTs
-- **[BMad Discord](https://discord.gg/gk8jAdXWmj)** - Get help and share your Gems/GPTs

package.json

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

src/core/module.yaml

@@ -23,8 +23,3 @@ output_folder:
   prompt: "Where should default output files be saved unless specified in other modules?"
   default: "_bmad-output"
   result: "{project-root}/{value}"
-
-bmad_memory:
-  prompt: "Some agents will record their own memories and history. Where should these be stored?"
-  default: "_bmad/_memory"
-  result: "{project-root}/{value}"

src/modules/bmb/docs/README.md

@@ -18,45 +18,44 @@ Specialized tools and workflows for creating, customizing, and extending BMad co
 
 **BMad Builder** - Master builder agent orchestrating all creation workflows with deep knowledge of BMad architecture and conventions.
 
-- Location: `_bmad/bmb/agents/bmad-builder.md`
+- Install Location: `_bmad/bmb/agents/bmad-builder.md`
 
 ### 📋 Workflows
 
 ### 📚 Documentation
 
-- Location: `./docs/`
-- Comprehensive guides for agents and workflows
+- Comprehensive guides for agents, workflows, and modules
 - Architecture patterns and best practices
 
 ### 🔍 Reference Materials
 
-- Location: `./reference/`
-- Working examples of agents and workflows
+- Location: `../reference/`
+- Working examples of custom stand alone agents and workflows
 - Template patterns and implementation guides
 
 ## Documentation
 
 ### 📖 Agent Documentation
 
-- **[Agent Index](./docs/agents/index.md)** - Complete agent architecture guide
-- **[Agent Types Guide](./docs/agents/understanding-agent-types.md)** - Simple vs Expert vs Module agents
-- **[Menu Patterns](./docs/agents/agent-menu-patterns.md)** - YAML menu design and handler types
-- **[Agent Compilation](./docs/agents/agent-compilation.md)** - Auto-injection rules and compilation process
+- **[Agent Index](./agents/index.md)** - Complete agent architecture guide
+- **[Agent Types Guide](./agents/understanding-agent-types.md)** - Simple vs Expert vs Module agents
+- **[Menu Patterns](./agents/agent-menu-patterns.md)** - YAML menu design and handler types
+- **[Agent Compilation](./agents/agent-compilation.md)** - Auto-injection rules and compilation process
 
 ### 📋 Workflow Documentation
 
-- **[Workflow Index](./docs/workflows/index.md)** - Core workflow system overview
-- **[Architecture Guide](./docs/workflows/architecture.md)** - Step-file design and JIT loading
-- **[Template System](./docs/workflows/templates/step-template.md)** - Standard step file template
-- **[Intent vs Prescriptive](./docs/workflows/intent-vs-prescriptive-spectrum.md)** - Design philosophy
+- **[Workflow Index](./workflows/index.md)** - Core workflow system overview
+- **[Architecture Guide](./workflows/architecture.md)** - Step-file design and JIT loading
+- **[Template System](./workflows/templates/step-template.md)** - Standard step file template
+- **[Intent vs Prescriptive](./workflows/intent-vs-prescriptive-spectrum.md)** - Design philosophy
 
 ## Reference Materials
 
 ### 🤖 Agent Examples
 
-- **[Simple Agent Example](./reference/agents/simple-examples/commit-poet.agent.yaml)** - Self-contained agent
-- **[Expert Agent Example](./reference/agents/expert-examples/journal-keeper/)** - Agent with persistent memory
-- **[Module Agent Examples](./reference/agents/module-examples/)** - Integration patterns (BMM, CIS)
+- **[Simple Agent Example](../reference/agents/simple-examples/commit-poet.agent.yaml)** - Self-contained agent
+- **[Expert Agent Example](../reference/agents/expert-examples/journal-keeper/journal-keeper.agent.yaml)** - Agent with persistent memory
+- **[Module Add On Agent Examples](../reference/agents/module-examples/security-engineer.agent.yaml)** - Integration patterns (BMM, CIS)
 
 ### 📋 Workflow Examples
 

src/modules/bmb/docs/agents/agent-menu-patterns.md

@@ -375,7 +375,6 @@ exec: "../../../core/tasks/validate.xml"
 
 - `{project-root}` - Project root directory
 - `_bmad` - BMAD installation folder
-- `{bmad_memory}` - Agent installation directory (Expert agents)
 - `{output_folder}` - Document output location
 - `{user_name}` - User's name from config
 - `{communication_language}` - Language preference

src/modules/bmb/docs/agents/expert-agent-architecture.md

@@ -204,14 +204,6 @@ critical_actions:
 - **Memory integration** - Past context becomes part of current session
 - **Protocol adherence** - Ensures consistent behavior
 
-### {bmad_memory} Variable
-
-Special variable resolved during installation:
-
-- Points to the agent's installation directory
-- Used to reference sidecar files
-- Example: `_bmad/custom/agents/journal-keeper/`
-
 ## What Gets Injected at Compile Time
 
 Same as simple agents, PLUS:
@@ -320,12 +312,11 @@ critical_actions:
 ## Best Practices
 
 1. **Load sidecar files in critical_actions** - Must be explicit and MANDATORY
-2. **Enforce domain restrictions** - Clear boundaries prevent scope creep
-3. **Use {bmad_memory} paths** - Portable across installations
-4. **Design for memory growth** - Structure sidecar files for accumulation
-5. **Reference past naturally** - Don't dump memory, weave it into conversation
-6. **Separate concerns** - Memories, instructions, knowledge in distinct files
-7. **Include privacy features** - Users trust expert agents with personal data
+2. **Enforce domain restrictions** - Clear boundaries prevent scope creep=
+3. **Design for memory growth** - Structure sidecar files for accumulation
+4. **Reference past naturally** - Don't dump memory, weave it into conversation
+5. **Separate concerns** - Memories, instructions, knowledge in distinct files
+6. **Include privacy features** - Users trust expert agents with personal data
 
 ## Common Patterns
 
@@ -364,8 +355,8 @@ identity: |
 - [ ] Sidecar folder structure created and populated
 - [ ] memories.md has clear section structure
 - [ ] instructions.md contains core directives
-- [ ] Menu actions reference {bmad_memory} correctly
-- [ ] File paths use {bmad_memory} variable
+- [ ] Menu actions reference \_bmad/\_memory correctly
+- [ ] File paths use \_bmad/\_memory/[agentname]-sidecar/ to reference sidecar content
 - [ ] Install config personalizes sidecar references
 - [ ] Agent folder named consistently: `{agent-name}/`
 - [ ] YAML file named: `{agent-name}.agent.yaml`

src/modules/bmb/module.yaml

@@ -9,7 +9,6 @@ default_selected: false # This module will not be selected by default for new in
 ## communication_language
 ## document_output_language
 ## output_folder
-## bmad_memory
 
 bmb_creations_output_folder:
   prompt: "Where should BoMB generated agents, workflows and modules SOURCE be saved?"

src/modules/bmb/reference/agents/expert-examples/journal-keeper/journal-keeper.agent.yaml

@@ -20,9 +20,9 @@ agent:
       - Reflection transforms experience into wisdom
 
   critical_actions:
-    - "Load COMPLETE file {bmad_memory}/journal-keeper-sidecar/memories.md and remember all past insights"
-    - "Load COMPLETE file {bmad_memory}/journal-keeper-sidecar/instructions.md and follow ALL journaling protocols"
-    - "ONLY read/write files in {bmad_memory}/journal-keeper-sidecar/ - this is our private space"
+    - "Load COMPLETE file {project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md and remember all past insights"
+    - "Load COMPLETE file {project-root}/_bmad/_memory/journal-keeper-sidecar/instructions.md and follow ALL journaling protocols"
+    - "ONLY read/write files in {project-root}/_bmad/_memory/journal-keeper-sidecar/ - this is our private space"
     - "Track mood patterns, recurring themes, and breakthrough moments"
     - "Reference past entries naturally to show continuity"
 
@@ -120,7 +120,7 @@ agent:
       description: "Write today's journal entry"
 
     - trigger: quick
-      action: "Save a quick, unstructured entry to {bmad_memory}/journal-keeper-sidecar/entries/entry-{date}.md with timestamp and any patterns noticed"
+      action: "Save a quick, unstructured entry to {project-root}/_bmad/_memory/journal-keeper-sidecar/entries/entry-{date}.md with timestamp and any patterns noticed"
       description: "Quick capture without prompts"
 
     - trigger: mood
@@ -140,13 +140,13 @@ agent:
       description: "Reflect on the past week"
 
     - trigger: insight
-      action: "Document this breakthrough in {bmad_memory}/journal-keeper-sidecar/breakthroughs.md with date and significance"
+      action: "Document this breakthrough in {project-root}/_bmad/_memory/journal-keeper-sidecar/breakthroughs.md with date and significance"
       description: "Record a meaningful insight"
 
     - trigger: read-back
-      action: "Load and share entries from {bmad_memory}/journal-keeper-sidecar/entries/ for requested timeframe, highlighting themes and growth"
+      action: "Load and share entries from {project-root}/_bmad/_memory/journal-keeper-sidecar/entries/ for requested timeframe, highlighting themes and growth"
       description: "Review past entries"
 
     - trigger: save
-      action: "Update {bmad_memory}/journal-keeper-sidecar/memories.md with today's session insights and emotional markers"
+      action: "Update {project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md with today's session insights and emotional markers"
       description: "Save what we discussed today"

src/modules/bmb/workflows/create-agent/templates/expert-agent.template.md

@@ -204,14 +204,6 @@ critical_actions:
 - **Memory integration** - Past context becomes part of current session
 - **Protocol adherence** - Ensures consistent behavior
 
-### {bmad_memory} Variable
-
-Special variable resolved during installation:
-
-- Points to the agent's installation directory
-- Used to reference sidecar files
-- Example: `_bmad/custom/agents/journal-keeper/`
-
 ## What Gets Injected at Compile Time
 
 Same as simple agents, PLUS:
@@ -321,7 +313,7 @@ critical_actions:
 
 1. **Load sidecar files in critical_actions** - Must be explicit and MANDATORY
 2. **Enforce domain restrictions** - Clear boundaries prevent scope creep
-3. **Use {bmad_memory} paths** - Portable across installations
+3. **Use \_bmad/\_memory/[agentname]-sidcar/ paths** - For reference to any sidecar content
 4. **Design for memory growth** - Structure sidecar files for accumulation
 5. **Reference past naturally** - Don't dump memory, weave it into conversation
 6. **Separate concerns** - Memories, instructions, knowledge in distinct files
@@ -364,8 +356,8 @@ identity: |
 - [ ] Sidecar folder structure created and populated
 - [ ] memories.md has clear section structure
 - [ ] instructions.md contains core directives
-- [ ] Menu actions reference {bmad_memory} correctly
-- [ ] File paths use {bmad_memory} variable
+- [ ] Menu actions reference \_bmad/\_memory/[agentname]-sidcar/ correctly if needing sidecar content reference
+- [ ] File paths use \_bmad/\_memory/[agentname]-sidcar/ to reference where the file will be after sidecar content is installed
 - [ ] Install config personalizes sidecar references
 - [ ] Agent folder named consistently: `{agent-name}/`
 - [ ] YAML file named: `{agent-name}.agent.yaml`

src/modules/bmb/workflows/create-agent/workflow.md

@@ -51,7 +51,7 @@ This uses **step-file architecture** for disciplined execution:
 
 Load and read full config from `{project-root}/_bmad/bmb/config.yaml`:
 
-- `project_name`, `user_name`, `bmad_memory`, `communication_language`, `document_output_language`, `bmb_creations_output_folder`
+- `project_name`, `user_name`, `communication_language`, `document_output_language`, `bmb_creations_output_folder`
 
 ### 2. First Step EXECUTION
 

src/modules/bmb/workflows/create-module/templates/agent.template.md

@@ -27,9 +27,8 @@ agent:
 
   # Optional: Only include if agent needs memory/persistence
   critical_actions:
-    - 'Load COMPLETE file [bmad_memory]/[agent-name]-sidecar/memories.md and integrate all past interactions'
-    - 'Load COMPLETE file [bmad_memory]/[agent-name]-sidecar/instructions.md and follow ALL protocols'
-    - 'ONLY read/write files in [bmad_memory]/[agent-name]-sidecar/* - this is our private workspace'
+    - 'Load COMPLETE file [project-root]/_bmad/_memory/[agent-name]-sidecar/memories.md and integrate all past interactions'
+    - 'Load COMPLETE file [project-root]/_bmad/_memory/[agent-name]-sidecar/instructions.md and follow ALL protocols'
 
   # Optional: Embedded prompts for common interactions
   prompts:
@@ -167,16 +166,15 @@ Expert agents support three types of menu actions:
 
 1. **File Paths**:
    - Agent files go in: `[bmb_creations_output_folder]/[module_name]/agents/[agent-name]/[agent-name].yaml`
-   - Sidecar folders go in: `[bmb_creations_output_folder]/[module_name]/agents/[agent-name]/[agent-name]-sidecar/`
+   - Sidecar files go in folder: `[bmb_creations_output_folder]/[module_name]/agents/[agent-name]/[agent-name]-sidecar/`
 
 2. **Variable Usage**:
-   - `bmad_memory` resolves to the agents sidecar folder destination after installation
    - `module` is your module code/name
 
 3. **Creating Sidecar Structure**:
    - When agent is created, also create the sidecar folder
-   - Initialize with empty files: memories.md, instructions.md
-   - Create sessions/ subfolder
+   - Initialize with empty files: memories.md, instructions.md and any other files the agent will need to have special knowledge or files to record information to
+   - Create sessions/ subfolder if interactions will result in new sessions
    - These files are automatically loaded due to critical_actions
 
 4. **Choosing Menu Actions**:

src/modules/bmgd/module.yaml

@@ -9,7 +9,6 @@ default_selected: false
 ## communication_language
 ## document_output_language
 ## output_folder
-## bmad_memory
 
 game_project_name:
   prompt: "What is the name of your game project?"

src/modules/bmm/module.yaml

@@ -9,7 +9,6 @@ default_selected: true # This module will be selected by default for new install
 ## communication_language
 ## document_output_language
 ## output_folder
-## bmad_memory
 
 project_name:
   prompt: "What is the title of your project you will be working on?"

src/modules/bmm/workflows/4-implementation/sprint-planning/instructions.md

@@ -84,7 +84,7 @@ development_status:
 
 - Epic: `backlog` → `in-progress` → `done`
 - Story: `backlog` → `ready-for-dev` → `in-progress` → `review` → `done`
-- Retrospective: `optional` ↔ `completed`
+- Retrospective: `optional` ↔ `done`
   </step>
 
 <step n="4" goal="Generate sprint status file">
@@ -119,7 +119,7 @@ development_status:
 #
 # Retrospective Status:
 #   - optional: Can be completed but not required
-#   - completed: Retrospective has been done
+#   - done: Retrospective has been completed
 #
 # WORKFLOW NOTES:
 # ===============
@@ -210,11 +210,11 @@ backlog → ready-for-dev → in-progress → review → done
 **Retrospective Status:**
 
 ```
-optional ↔ completed
+optional ↔ done
 ```
 
-- **optional**: Can be done but not required
-- **completed**: Retrospective has been completed
+- **optional**: Ready to be conducted but not required
+- **done**: Finished
 
 ### Guidelines
 

src/modules/bmm/workflows/4-implementation/sprint-planning/sprint-status-template.yaml

@@ -24,7 +24,7 @@
 #
 # Retrospective Status:
 #   - optional: Can be completed but not required
-#   - completed: Retrospective has been done by *retrospective
+#   - done: Retrospective has been completed
 #
 # WORKFLOW NOTES:
 # ===============

src/modules/bmm/workflows/4-implementation/sprint-status/instructions.md

@@ -44,13 +44,13 @@ Run `/bmad:bmm:workflows:sprint-planning` to generate it, then rerun sprint-stat
   <action>Count story statuses: backlog, ready-for-dev, in-progress, review, done</action>
   <action>Map legacy epic status "contexted" → "in-progress"</action>
   <action>Count epic statuses: backlog, in-progress, done</action>
-  <action>Count retrospective statuses: optional, completed</action>
+  <action>Count retrospective statuses: optional, done</action>
 
 <action>Validate all statuses against known values:</action>
 
 - Valid story statuses: backlog, ready-for-dev, in-progress, review, done, drafted (legacy)
 - Valid epic statuses: backlog, in-progress, done, contexted (legacy)
-- Valid retrospective statuses: optional, completed
+- Valid retrospective statuses: optional, done
 
   <check if="any status is unrecognized">
     <output>
@@ -64,7 +64,7 @@ Run `/bmad:bmm:workflows:sprint-planning` to generate it, then rerun sprint-stat
 
 - Stories: backlog, ready-for-dev, in-progress, review, done
 - Epics: backlog, in-progress, done
-- Retrospectives: optional, completed
+- Retrospectives: optional, done
   </output>
   <ask>How should these be corrected?
   {{#each invalid_entries}}
@@ -83,15 +83,19 @@ Enter corrections (e.g., "1=in-progress, 2=backlog") or "skip" to continue witho
 - IF any story has status "review": suggest `/bmad:bmm:workflows:code-review`
 - IF any story has status "in-progress" AND no stories have status "ready-for-dev": recommend staying focused on active story
 - IF all epics have status "backlog" AND no stories have status "ready-for-dev": prompt `/bmad:bmm:workflows:create-story`
+- IF `generated` timestamp is more than 7 days old: warn "sprint-status.yaml may be stale"
+- IF any story key doesn't match an epic pattern (e.g., story "5-1-..." but no "epic-5"): warn "orphaned story detected"
+- IF any epic has status in-progress but has no associated stories: warn "in-progress epic has no stories"
   </step>
 
 <step n="3" goal="Select next action recommendation">
   <action>Pick the next recommended workflow using priority:</action>
+  <note>When selecting "first" story: sort by epic number, then story number (e.g., 1-1 before 1-2 before 2-1)</note>
   1. If any story status == in-progress → recommend `dev-story` for the first in-progress story
   2. Else if any story status == review → recommend `code-review` for the first review story
   3. Else if any story status == ready-for-dev → recommend `dev-story`
   4. Else if any story status == backlog → recommend `create-story`
-  5. Else if retrospectives are optional → recommend `retrospective`
+  5. Else if any retrospective status == optional → recommend `retrospective`
   6. Else → All implementation items done; suggest `workflow-status` to plan next phase
   <action>Store selected recommendation as: next_story_id, next_workflow_id, next_agent (SM/DEV as appropriate)</action>
 </step>
@@ -118,13 +122,6 @@ Enter corrections (e.g., "1=in-progress, 2=backlog") or "skip" to continue witho
   {{/each}}
   {{/if}}
 
-{{#if by_epic}}
-**Per Epic:**
-{{#each by_epic}}
-
-- {{epic_id}}: context={{context_status}}, stories → backlog {{backlog}}, ready {{ready_for_dev}}, in-progress {{in_progress}}, review {{review}}, done {{done}}
-  {{/each}}
-  {{/if}}
   </output>
   </step>
 
@@ -194,15 +191,39 @@ If the command targets a story, set `story_key={{next_story_id}}` when prompted.
     <template-output>suggestion = "Run sprint-planning to create it"</template-output>
     <action>Return</action>
   </check>
-  <action>Read file and verify it has a development_status section with at least one entry</action>
-  <check if="validation fails">
-    <template-output>is_valid = false</template-output>
-    <template-output>error = "development_status missing or empty"</template-output>
-    <template-output>suggestion = "Re-run sprint-planning or repair the file manually"</template-output>
-    <action>Return</action>
+
+<action>Read and parse {sprint_status_file}</action>
+
+<action>Validate required metadata fields exist: generated, project, project_key, tracking_system, story_location</action>
+<check if="any required field missing">
+<template-output>is_valid = false</template-output>
+<template-output>error = "Missing required field(s): {{missing_fields}}"</template-output>
+<template-output>suggestion = "Re-run sprint-planning or add missing fields manually"</template-output>
+<action>Return</action>
+</check>
+
+<action>Verify development_status section exists with at least one entry</action>
+<check if="development_status missing or empty">
+<template-output>is_valid = false</template-output>
+<template-output>error = "development_status missing or empty"</template-output>
+<template-output>suggestion = "Re-run sprint-planning or repair the file manually"</template-output>
+<action>Return</action>
+</check>
+
+<action>Validate all status values against known valid statuses:</action>
+
+- Stories: backlog, ready-for-dev, in-progress, review, done (legacy: drafted)
+- Epics: backlog, in-progress, done (legacy: contexted)
+- Retrospectives: optional, done
+  <check if="any invalid status found">
+  <template-output>is_valid = false</template-output>
+  <template-output>error = "Invalid status values: {{invalid_entries}}"</template-output>
+  <template-output>suggestion = "Fix invalid statuses in sprint-status.yaml"</template-output>
+  <action>Return</action>
   </check>
-  <template-output>is_valid = true</template-output>
-  <template-output>message = "sprint-status.yaml present and parsable"</template-output>
+
+<template-output>is_valid = true</template-output>
+<template-output>message = "sprint-status.yaml valid: metadata complete, all statuses recognized"</template-output>
 </step>
 
 </workflow>

src/modules/cis/agents/storyteller/storyteller-sidecar/stories-told.md

@@ -2,6 +2,6 @@
 
 Purpose: Record a log detailing the stories I have crafted over time for the user.
 
-## Narratives Told Record
+## Narratives Told Table Record
 
 <!-- track stories created metadata with the user over time -->

src/modules/cis/agents/storyteller/storyteller-sidecar/story-preferences.md

@@ -2,6 +2,6 @@
 
 Purpose: Record a log of learned users story telling or story building preferences.
 
-## User Preferences
+## User Preference Bullet List
 
 <!-- record any user preferences about story crafting the user prefers -->

src/modules/cis/agents/storyteller/storyteller.agent.yaml

@@ -7,6 +7,7 @@ agent:
     title: Master Storyteller
     icon: 📖
     module: cis
+    hasSidecar: true
 
   persona:
     role: Expert Storytelling Guide + Narrative Strategist
@@ -15,8 +16,8 @@ agent:
     principles: Powerful narratives leverage timeless human truths. Find the authentic story. Make the abstract concrete through vivid details.
 
   critical_actions:
-    - "Load COMPLETE file {agent_sidecar_folder}/storyteller-sidecar/story-preferences.md and review remember the User Preferences"
-    - "Load COMPLETE file {agent_sidecar_folder}/storyteller-sidecar/stories-told.md and review the history of stories created for this user"
+    - "Load COMPLETE file {project-root}/_bmad/_memory/storyteller-sidecar/story-preferences.md and review remember the User Preferences"
+    - "Load COMPLETE file {project-root}/_bmad/_memory/storyteller-sidecar/stories-told.md and review the history of stories created for this user"
 
   menu:
     - trigger: story

src/modules/cis/module.yaml

@@ -9,4 +9,3 @@ default_selected: false # This module will not be selected by default for new in
 ## communication_language
 ## document_output_language
 ## output_folder
-## bmad_memory

tools/cli/commands/install.js

@@ -26,6 +26,11 @@ module.exports = {
         const result = await installer.quickUpdate(config);
         console.log(chalk.green('\n✨ Quick update complete!'));
         console.log(chalk.cyan(`Updated ${result.moduleCount} modules with preserved settings`));
+        console.log(
+          chalk.magenta(
+            "\n📋 Want to see what's new? Check out the changelog: https://github.com/bmad-code-org/BMAD-METHOD/blob/main/CHANGELOG.md",
+          ),
+        );
         process.exit(0);
         return;
       }

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

@@ -50,7 +50,6 @@ class Installer {
       return { bmadDir: path.join(projectDir, '_bmad'), hasLegacyCfg: false };
     }
 
-    // V6+ strategy: Look for ANY directory with _config/manifest.yaml or legacy _cfg/manifest.yaml
     let bmadDir = null;
     let hasLegacyCfg = false;
 
@@ -76,7 +75,7 @@ class Installer {
         }
       }
     } catch {
-      // Ignore errors, fall through to default
+      console.log(chalk.red('Error reading project directory for BMAD installation detection'));
     }
 
     // If we found a bmad directory (with or without legacy _cfg)
@@ -321,6 +320,7 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice:
 
         for (const ide of newlySelectedIdes) {
           // List of IDEs that have interactive prompts
+          //TODO: Why is this here, hardcoding this list here is bad, fix me!
           const needsPrompts = ['claude-code', 'github-copilot', 'roo', 'cline', 'auggie', 'codex', 'qwen', 'gemini', 'rovo-dev'].includes(
             ide,
           );
@@ -344,7 +344,6 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice:
               } else if (ideModule.default) {
                 SetupClass = ideModule.default;
               } else {
-                // Skip if no setup class found
                 continue;
               }
 
@@ -398,10 +397,7 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice:
     const hasCoreConfig = config.coreConfig && Object.keys(config.coreConfig).length > 0;
 
     // Only display logo if core config wasn't already collected (meaning we're not continuing from UI)
-    if (hasCoreConfig) {
-      // Core config was already collected in UI, show smooth continuation
-      // Don't clear screen, just continue flow
-    } else {
+    if (!hasCoreConfig) {
       // Display BMAD logo
       CLIUtils.displayLogo();
 
@@ -797,7 +793,6 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice:
       config.skipIde = toolSelection.skipIde;
       const ideConfigurations = toolSelection.configurations;
 
-      // Check if spinner is already running (e.g., from folder name change scenario)
       if (spinner.isSpinning) {
         spinner.text = 'Continuing installation...';
       } else {
@@ -828,7 +823,6 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice:
         spinner.succeed('Custom modules cached');
       }
 
-      // Get project root
       const projectRoot = getProjectRoot();
 
       // Step 1: Install core module first (if requested)
@@ -985,7 +979,6 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice:
               this.moduleManager.setCustomModulePaths(customModulePaths);
             }
 
-            // Get collected config for this custom module (from module.yaml prompts)
             const collectedModuleConfig = moduleConfigs[moduleName] || {};
 
             // Use ModuleManager to install the custom module
@@ -999,11 +992,10 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice:
                 isCustom: true,
                 moduleConfig: collectedModuleConfig,
                 isQuickUpdate: config._quickUpdate || false,
+                installer: this,
               },
             );
 
-            // ModuleManager installs directly to the target directory, no need to move files
-
             // Create module config (include collected config from module.yaml prompts)
             await this.generateModuleConfigs(bmadDir, {
               [moduleName]: { ...config.coreConfig, ...customInfo.config, ...collectedModuleConfig },
@@ -1558,14 +1550,7 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice:
   async installCoreWithDependencies(bmadDir, coreFiles) {
     const sourcePath = getModulePath('core');
     const targetPath = path.join(bmadDir, 'core');
-
-    // Install full core
     await this.installCore(bmadDir);
-
-    // If there are specific dependency files, ensure they're included
-    if (coreFiles) {
-      // Already handled by installCore for core module
-    }
   }
 
   /**
@@ -1589,6 +1574,7 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice:
       {
         skipModuleInstaller: true, // We'll run it later after IDE setup
         moduleConfig: moduleConfig, // Pass module config for conditional filtering
+        installer: this,
       },
     );
 
@@ -1711,7 +1697,7 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice:
     // Compile agents using the same compiler as modules
     const { ModuleManager } = require('../modules/manager');
     const moduleManager = new ModuleManager();
-    await moduleManager.compileModuleAgents(sourcePath, targetPath, 'core', bmadDir);
+    await moduleManager.compileModuleAgents(sourcePath, targetPath, 'core', bmadDir, this);
 
     // Process agent files to inject activation block
     await this.processAgentFiles(targetPath, 'core');
@@ -2060,8 +2046,7 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice:
           answers.memories = customizeData.memories;
         }
 
-        // Get core config for bmad_memory
-        const coreConfigPath = path.join(bmadDir, 'bmb', 'config.yaml');
+        const coreConfigPath = path.join(bmadDir, 'core', 'config.yaml');
         let coreConfig = {};
         if (await fs.pathExists(coreConfigPath)) {
           const yaml = require('yaml');
@@ -2216,7 +2201,7 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice:
       // Recompile agents (#1133)
       const { ModuleManager } = require('../modules/manager');
       const moduleManager = new ModuleManager();
-      await moduleManager.compileModuleAgents(sourcePath, targetPath, 'core', bmadDir);
+      await moduleManager.compileModuleAgents(sourcePath, targetPath, 'core', bmadDir, this);
       await this.processAgentFiles(targetPath, 'core');
     }
   }
@@ -2587,6 +2572,9 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice:
     const customFiles = [];
     const modifiedFiles = [];
 
+    // Memory is always in _bmad/_memory
+    const bmadMemoryPath = '_memory';
+
     // Check if the manifest has hashes - if not, we can't detect modifications
     let manifestHasHashes = false;
     if (existingFilesManifest && existingFilesManifest.length > 0) {
@@ -2651,6 +2639,10 @@ If AgentVibes party mode is enabled, immediately trigger TTS with agent's voice:
               continue;
             }
 
+            if (relativePath.startsWith(bmadMemoryPath + '/') && path.dirname(relativePath).includes('-sidecar')) {
+              continue;
+            }
+
             // Skip config.yaml files - these are regenerated on each install/update
             if (fileName === 'config.yaml') {
               continue;

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

@@ -56,50 +56,22 @@ class ModuleManager {
   }
 
   /**
-   * Copy a file and replace _bmad placeholder with actual folder name
+   * Copy a file to the target location
    * @param {string} sourcePath - Source file path
    * @param {string} targetPath - Target file path
+   * @param {boolean} overwrite - Whether to overwrite existing files (default: true)
    */
-  async copyFileWithPlaceholderReplacement(sourcePath, targetPath) {
-    // List of text file extensions that should have placeholder replacement
-    const textExtensions = ['.md', '.yaml', '.yml', '.txt', '.json', '.js', '.ts', '.html', '.css', '.sh', '.bat', '.csv'];
-    const ext = path.extname(sourcePath).toLowerCase();
-
-    // Check if this is a text file that might contain placeholders
-    if (textExtensions.includes(ext)) {
-      try {
-        // Read the file content
-        let content = await fs.readFile(sourcePath, 'utf8');
-
-        // Replace escape sequence _bmad with literal _bmad
-        if (content.includes('_bmad')) {
-          content = content.replaceAll('_bmad', '_bmad');
-        }
-
-        // Replace _bmad placeholder with actual folder name
-        if (content.includes('_bmad')) {
-          content = content.replaceAll('_bmad', this.bmadFolderName);
-        }
-
-        // Write to target with replaced content
-        await fs.ensureDir(path.dirname(targetPath));
-        await fs.writeFile(targetPath, content, 'utf8');
-      } catch {
-        // If reading as text fails (might be binary despite extension), fall back to regular copy
-        await fs.copy(sourcePath, targetPath, { overwrite: true });
-      }
-    } else {
-      // Binary file or other file type - just copy directly
-      await fs.copy(sourcePath, targetPath, { overwrite: true });
-    }
+  async copyFileWithPlaceholderReplacement(sourcePath, targetPath, overwrite = true) {
+    await fs.copy(sourcePath, targetPath, { overwrite });
   }
 
   /**
-   * Copy a directory recursively with placeholder replacement
+   * Copy a directory recursively
    * @param {string} sourceDir - Source directory path
    * @param {string} targetDir - Target directory path
+   * @param {boolean} overwrite - Whether to overwrite existing files (default: true)
    */
-  async copyDirectoryWithPlaceholderReplacement(sourceDir, targetDir) {
+  async copyDirectoryWithPlaceholderReplacement(sourceDir, targetDir, overwrite = true) {
     await fs.ensureDir(targetDir);
     const entries = await fs.readdir(sourceDir, { withFileTypes: true });
 
@@ -108,13 +80,110 @@ class ModuleManager {
       const targetPath = path.join(targetDir, entry.name);
 
       if (entry.isDirectory()) {
-        await this.copyDirectoryWithPlaceholderReplacement(sourcePath, targetPath);
+        await this.copyDirectoryWithPlaceholderReplacement(sourcePath, targetPath, overwrite);
       } else {
-        await this.copyFileWithPlaceholderReplacement(sourcePath, targetPath);
+        await this.copyFileWithPlaceholderReplacement(sourcePath, targetPath, overwrite);
       }
     }
   }
 
+  /**
+   * Copy sidecar directory to _bmad/_memory location with update-safe handling
+   * @param {string} sourceSidecarPath - Source sidecar directory path
+   * @param {string} agentName - Name of the agent (for naming)
+   * @param {string} bmadMemoryPath - This should ALWAYS be _bmad/_memory
+   * @param {boolean} isUpdate - Whether this is an update (default: false)
+   * @param {string} bmadDir - BMAD installation directory
+   * @param {Object} installer - Installer instance for file tracking
+   */
+  async copySidecarToMemory(sourceSidecarPath, agentName, bmadMemoryPath, isUpdate = false, bmadDir = null, installer = null) {
+    const crypto = require('node:crypto');
+    const sidecarTargetDir = path.join(bmadMemoryPath, `${agentName}-sidecar`);
+
+    // Ensure target directory exists
+    await fs.ensureDir(bmadMemoryPath);
+    await fs.ensureDir(sidecarTargetDir);
+
+    // Get existing files manifest for update checking
+    let existingFilesManifest = [];
+    if (isUpdate && installer) {
+      existingFilesManifest = await installer.readFilesManifest(bmadDir);
+    }
+
+    // Build map of existing sidecar files with their hashes
+    const existingSidecarFiles = new Map();
+    for (const fileEntry of existingFilesManifest) {
+      if (fileEntry.path && fileEntry.path.includes(`${agentName}-sidecar/`)) {
+        existingSidecarFiles.set(fileEntry.path, fileEntry.hash);
+      }
+    }
+
+    // Get all files in source sidecar
+    const sourceFiles = await this.getFileList(sourceSidecarPath);
+
+    for (const file of sourceFiles) {
+      const sourceFilePath = path.join(sourceSidecarPath, file);
+      const targetFilePath = path.join(sidecarTargetDir, file);
+
+      // Calculate current source file hash
+      const sourceHash = crypto
+        .createHash('sha256')
+        .update(await fs.readFile(sourceFilePath))
+        .digest('hex');
+
+      // Path relative to bmad directory
+      const relativeToBmad = path.join('_memory', `${agentName}-sidecar`, file);
+
+      if (isUpdate && (await fs.pathExists(targetFilePath))) {
+        // Calculate current target file hash
+        const currentTargetHash = crypto
+          .createHash('sha256')
+          .update(await fs.readFile(targetFilePath))
+          .digest('hex');
+
+        // Get the last known hash from files-manifest
+        const lastKnownHash = existingSidecarFiles.get(relativeToBmad);
+
+        if (lastKnownHash) {
+          // We have a record of this file
+          if (currentTargetHash === lastKnownHash) {
+            // File hasn't been modified by user, safe to update
+            await this.copyFileWithPlaceholderReplacement(sourceFilePath, targetFilePath, true);
+            if (process.env.BMAD_VERBOSE_INSTALL === 'true') {
+              console.log(chalk.dim(`    Updated sidecar file: ${relativeToBmad}`));
+            }
+          } else {
+            // User has modified the file, preserve it
+            if (process.env.BMAD_VERBOSE_INSTALL === 'true') {
+              console.log(chalk.dim(`    Preserving user-modified file: ${relativeToBmad}`));
+            }
+          }
+        } else {
+          // First time seeing this file in manifest, copy it
+          await this.copyFileWithPlaceholderReplacement(sourceFilePath, targetFilePath, true);
+          if (process.env.BMAD_VERBOSE_INSTALL === 'true') {
+            console.log(chalk.dim(`    Added new sidecar file: ${relativeToBmad}`));
+          }
+        }
+      } else {
+        // New installation
+        await this.copyFileWithPlaceholderReplacement(sourceFilePath, targetFilePath, true);
+        if (process.env.BMAD_VERBOSE_INSTALL === 'true') {
+          console.log(chalk.dim(`    Copied sidecar file: ${relativeToBmad}`));
+        }
+      }
+
+      // Track the file in the installer's file tracking system
+      if (installer && installer.installedFiles) {
+        installer.installedFiles.add(targetFilePath);
+      }
+    }
+
+    // Return list of files that were processed
+    const processedFiles = sourceFiles.map((file) => path.join('_memory', `${agentName}-sidecar`, file));
+    return processedFiles;
+  }
+
   /**
    * List all available modules (excluding core which is always installed)
    * @returns {Object} Object with modules array and customModules array
@@ -363,7 +432,7 @@ class ModuleManager {
     await this.copyModuleWithFiltering(sourcePath, targetPath, fileTrackingCallback, options.moduleConfig);
 
     // Compile any .agent.yaml files to .md format
-    await this.compileModuleAgents(sourcePath, targetPath, moduleName, bmadDir);
+    await this.compileModuleAgents(sourcePath, targetPath, moduleName, bmadDir, options.installer);
 
     // Process agent files to inject activation block
     await this.processAgentFiles(targetPath, moduleName);
@@ -409,7 +478,7 @@ class ModuleManager {
       await this.syncModule(sourcePath, targetPath);
 
       // Recompile agents (#1133)
-      await this.compileModuleAgents(sourcePath, targetPath, moduleName, bmadDir);
+      await this.compileModuleAgents(sourcePath, targetPath, moduleName, bmadDir, options.installer);
       await this.processAgentFiles(targetPath, moduleName);
     }
 
@@ -495,29 +564,21 @@ class ModuleManager {
     // Get all files in source
     const sourceFiles = await this.getFileList(sourcePath);
 
-    // Game development files to conditionally exclude
-    const gameDevFiles = [
-      'agents/game-architect.agent.yaml',
-      'agents/game-designer.agent.yaml',
-      'agents/game-dev.agent.yaml',
-      'workflows/1-analysis/brainstorm-game',
-      'workflows/1-analysis/game-brief',
-      'workflows/2-plan-workflows/gdd',
-    ];
-
     for (const file of sourceFiles) {
       // Skip sub-modules directory - these are IDE-specific and handled separately
       if (file.startsWith('sub-modules/')) {
         continue;
       }
 
-      // Skip sidecar directories - they are handled separately during agent compilation
-      if (
-        path
-          .dirname(file)
-          .split('/')
-          .some((dir) => dir.toLowerCase().includes('sidecar'))
-      ) {
+      // Only skip sidecar directories - they are handled separately during agent compilation
+      // But still allow other files in agent directories
+      const isInAgentDirectory = file.startsWith('agents/');
+      const isInSidecarDirectory = path
+        .dirname(file)
+        .split('/')
+        .some((dir) => dir.toLowerCase().endsWith('-sidecar'));
+
+      if (isInSidecarDirectory) {
         continue;
       }
 
@@ -527,8 +588,7 @@ class ModuleManager {
       }
 
       // Skip config.yaml templates - we'll generate clean ones with actual values
-      // Also skip custom.yaml files - their values will be merged into core config
-      if (file === 'config.yaml' || file.endsWith('/config.yaml') || file === 'custom.yaml' || file.endsWith('/custom.yaml')) {
+      if (file === 'config.yaml' || file.endsWith('/config.yaml')) {
         continue;
       }
 
@@ -537,25 +597,6 @@ class ModuleManager {
         continue;
       }
 
-      // Skip user documentation if install_user_docs is false
-      if (moduleConfig.install_user_docs === false && (file.startsWith('docs/') || file.startsWith('docs\\'))) {
-        console.log(chalk.dim(`  Skipping user documentation: ${file}`));
-        continue;
-      }
-
-      // Skip game development content if include_game_planning is false
-      if (moduleConfig.include_game_planning === false) {
-        const shouldSkipGameDev = gameDevFiles.some((gamePath) => {
-          // Check if file path starts with or is within any game dev directory
-          return file === gamePath || file.startsWith(gamePath + '/') || file.startsWith(gamePath + '\\');
-        });
-
-        if (shouldSkipGameDev) {
-          console.log(chalk.dim(`  Skipping game dev content: ${file}`));
-          continue;
-        }
-      }
-
       const sourceFile = path.join(sourcePath, file);
       const targetFile = path.join(targetPath, file);
 
@@ -685,8 +726,9 @@ class ModuleManager {
    * @param {string} targetPath - Target module path
    * @param {string} moduleName - Module name
    * @param {string} bmadDir - BMAD installation directory
+   * @param {Object} installer - Installer instance for file tracking
    */
-  async compileModuleAgents(sourcePath, targetPath, moduleName, bmadDir) {
+  async compileModuleAgents(sourcePath, targetPath, moduleName, bmadDir, installer = null) {
     const sourceAgentsPath = path.join(sourcePath, 'agents');
     const targetAgentsPath = path.join(targetPath, 'agents');
     const cfgAgentsDir = path.join(bmadDir, '_config', 'agents');
@@ -785,16 +827,6 @@ class ModuleManager {
           }
         }
 
-        // Load core config to get bmad_memory
-        const coreConfigPath = path.join(bmadDir, 'bmb', 'config.yaml');
-        let coreConfig = {};
-
-        if (await fs.pathExists(coreConfigPath)) {
-          const yaml = require('yaml');
-          const coreConfigContent = await fs.readFile(coreConfigPath, 'utf8');
-          coreConfig = yaml.parse(coreConfigContent);
-        }
-
         // Check if agent has sidecar
         let hasSidecar = false;
         try {
@@ -805,14 +837,48 @@ class ModuleManager {
         }
 
         // Compile with customizations if any
-        const { xml } = await compileAgent(yamlContent, answers, agentName, relativePath, { config: coreConfig });
+        const { xml } = await compileAgent(yamlContent, answers, agentName, relativePath, { config: this.coreConfig || {} });
 
-        // Replace _bmad placeholder if needed
-        if (xml.includes('_bmad') && this.bmadFolderName) {
-          const processedXml = xml.replaceAll('_bmad', this.bmadFolderName);
-          await fs.writeFile(targetMdPath, processedXml, 'utf8');
-        } else {
-          await fs.writeFile(targetMdPath, xml, 'utf8');
+        // Write the compiled agent
+        await fs.writeFile(targetMdPath, xml, 'utf8');
+
+        // Handle sidecar copying if present
+        if (hasSidecar) {
+          // Get the agent's directory to look for sidecar
+          const agentDir = path.dirname(agentFile);
+          const sidecarDirName = `${agentName}-sidecar`;
+          const sourceSidecarPath = path.join(agentDir, sidecarDirName);
+
+          // Check if sidecar directory exists
+          if (await fs.pathExists(sourceSidecarPath)) {
+            // Memory is always in _bmad/_memory
+            const bmadMemoryPath = path.join(bmadDir, '_memory');
+
+            // Determine if this is an update (by checking if agent already exists)
+            const isUpdate = await fs.pathExists(targetMdPath);
+
+            // Copy sidecar to memory location with update-safe handling
+            const copiedFiles = await this.copySidecarToMemory(sourceSidecarPath, agentName, bmadMemoryPath, isUpdate, bmadDir, installer);
+
+            if (process.env.BMAD_VERBOSE_INSTALL === 'true' && copiedFiles.length > 0) {
+              console.log(chalk.dim(`    Sidecar files processed: ${copiedFiles.length} files`));
+            }
+          } else if (process.env.BMAD_VERBOSE_INSTALL === 'true') {
+            console.log(chalk.yellow(`    Warning: Agent marked as having sidecar but ${sidecarDirName} directory not found`));
+          }
+        }
+
+        // Copy any non-sidecar files from agent directory (e.g., foo.md)
+        const agentDir = path.dirname(agentFile);
+        const agentEntries = await fs.readdir(agentDir, { withFileTypes: true });
+
+        for (const entry of agentEntries) {
+          if (entry.isFile() && !entry.name.endsWith('.agent.yaml') && !entry.name.endsWith('.md')) {
+            // Copy additional files (like foo.md) to the agent target directory
+            const sourceFile = path.join(agentDir, entry.name);
+            const targetFile = path.join(targetDir, entry.name);
+            await this.copyFileWithPlaceholderReplacement(sourceFile, targetFile);
+          }
         }
 
         // Only show compilation details in verbose mode

tools/cli/lib/agent/compiler.js

@@ -333,18 +333,12 @@ async function compileAgent(yamlContent, answers = {}, agentName = '', targetPat
     finalAnswers = { ...defaults, ...answers };
   }
 
-  // Add bmad_memory to answers if provided in config
-  if (options.config && options.config.bmad_memory) {
-    finalAnswers.bmad_memory = options.config.bmad_memory;
-  }
-
   // Process templates with answers
   const processedYaml = processAgentYaml(agentYaml, finalAnswers);
 
   // Strip install_config from output
   const cleanYaml = stripInstallConfig(processedYaml);
 
-  // Replace {bmad_memory} in XML content
   let xml = await compileToXml(cleanYaml, agentName, targetPath);
 
   // Ensure xml is a string before attempting replaceAll
@@ -352,10 +346,6 @@ async function compileAgent(yamlContent, answers = {}, agentName = '', targetPat
     throw new TypeError('compileToXml did not return a string');
   }
 
-  if (finalAnswers.bmad_memory) {
-    xml = xml.replaceAll('{bmad_memory}', finalAnswers.bmad_memory);
-  }
-
   return {
     xml,
     metadata: cleanYaml.agent.metadata,

tools/cli/lib/ui.js

@@ -10,8 +10,6 @@ const { CustomHandler } = require('../installers/lib/custom/handler');
  * UI utilities for the installer
  */
 class UI {
-  constructor() {}
-
   /**
    * Prompt for installation configuration
    * @returns {Object} Installation configuration
@@ -19,6 +17,9 @@ class UI {
   async promptInstall() {
     CLIUtils.displayLogo();
 
+    // Display changelog link
+    console.log(chalk.cyan('\n📋 Read the latest updates: https://github.com/bmad-code-org/BMAD-METHOD/blob/main/CHANGELOG.md\n'));
+
     const confirmedDirectory = await this.getConfirmedDirectory();
 
     // Preflight: Check for legacy BMAD v4 footprints immediately after getting directory
@@ -161,14 +162,8 @@ class UI {
       }
     }
 
-    // Always ask for custom content, but we'll handle it differently for new installs
     let customContentConfig = { hasCustomContent: false };
-    if (hasExistingInstall) {
-      // Existing installation - prompt to add/update custom content
-      customContentConfig = await this.promptCustomContentForExisting();
-    } else {
-      // New installation - we'll prompt after creating the directory structure
-      // For now, set a flag to indicate we should ask later
+    if (!hasExistingInstall) {
       customContentConfig._shouldAsk = true;
     }
 
@@ -246,7 +241,35 @@ class UI {
         }
 
         // After module selection, ask about custom modules
-        const customModuleResult = await this.handleCustomModulesInModifyFlow(confirmedDirectory, selectedModules);
+        console.log('');
+        const { changeCustomModules } = await inquirer.prompt([
+          {
+            type: 'confirm',
+            name: 'changeCustomModules',
+            message: 'Modify custom module selection (add, update, or remove custom modules/agents/workflows)?',
+            default: false,
+          },
+        ]);
+
+        let customModuleResult = { selectedCustomModules: [], customContentConfig: { hasCustomContent: false } };
+        if (changeCustomModules) {
+          customModuleResult = await this.handleCustomModulesInModifyFlow(confirmedDirectory, selectedModules);
+        } else {
+          // Preserve existing custom modules if user doesn't want to modify them
+          const { Installer } = require('../installers/lib/core/installer');
+          const installer = new Installer();
+          const { bmadDir } = await installer.findBmadDir(confirmedDirectory);
+
+          const cacheDir = path.join(bmadDir, '_config', 'custom');
+          if (await fs.pathExists(cacheDir)) {
+            const entries = await fs.readdir(cacheDir, { withFileTypes: true });
+            for (const entry of entries) {
+              if (entry.isDirectory()) {
+                customModuleResult.selectedCustomModules.push(entry.name);
+              }
+            }
+          }
+        }
 
         // Merge any selected custom modules
         if (customModuleResult.selectedCustomModules.length > 0) {
@@ -592,6 +615,13 @@ class UI {
 
     console.log(chalk.yellow('\nThank you for helping test the early release version of the new BMad Core and BMad Method!'));
     console.log(chalk.cyan('Stable Beta coming soon - please read the full README.md and linked documentation to get started!'));
+
+    // Add changelog link at the end
+    console.log(
+      chalk.magenta(
+        "\n📋 Want to see what's new? Check out the changelog: https://github.com/bmad-code-org/BMAD-METHOD/blob/main/CHANGELOG.md",
+      ),
+    );
   }
 
   /**
@@ -1140,146 +1170,6 @@ class UI {
     return existingInstall.ides || [];
   }
 
-  /**
-   * Prompt for custom content for existing installations
-   * @returns {Object} Custom content configuration
-   */
-  async promptCustomContentForExisting() {
-    try {
-      // Skip custom content installation - always return false
-      return { hasCustomContent: false };
-
-      // TODO: Custom content installation temporarily disabled
-      // CLIUtils.displaySection('Custom Content', 'Add new custom agents, workflows, or modules to your installation');
-
-      // const { hasCustomContent } = await inquirer.prompt([
-      //   {
-      //     type: 'list',
-      //     name: 'hasCustomContent',
-      //     message: 'Do you want to add or update custom content?',
-      //     choices: [
-      //       {
-      //         name: 'No, continue with current installation only',
-      //         value: false,
-      //       },
-      //       {
-      //         name: 'Yes, I have custom content to add or update',
-      //         value: true,
-      //       },
-      //     ],
-      //     default: false,
-      //   },
-      // ]);
-
-      // if (!hasCustomContent) {
-      //   return { hasCustomContent: false };
-      // }
-
-      // TODO: Custom content installation temporarily disabled
-      // // Get directory path
-      // const { customPath } = await inquirer.prompt([
-      //   {
-      //     type: 'input',
-      //     name: 'customPath',
-      //     message: 'Enter directory to search for custom content (will scan subfolders):',
-      //     default: process.cwd(),
-      //     validate: async (input) => {
-      //       if (!input || input.trim() === '') {
-      //         return 'Please enter a directory path';
-      //       }
-
-      //       // Normalize and check if path exists
-      //       const expandedPath = CLIUtils.expandPath(input.trim());
-      //       const pathExists = await fs.pathExists(expandedPath);
-      //       if (!pathExists) {
-      //         return 'Directory does not exist';
-      //       }
-
-      //       // Check if it's actually a directory
-      //       const stats = await fs.stat(expandedPath);
-      //       if (!stats.isDirectory()) {
-      //         return 'Path must be a directory';
-      //       }
-
-      //       return true;
-      //     },
-      //     transformer: (input) => {
-      //       return CLIUtils.expandPath(input);
-      //     },
-      //   },
-      // ]);
-
-      // const resolvedPath = CLIUtils.expandPath(customPath);
-
-      // // Find custom content
-      // const customHandler = new CustomHandler();
-      // const customFiles = await customHandler.findCustomContent(resolvedPath);
-
-      // if (customFiles.length === 0) {
-      //   console.log(chalk.yellow(`\nNo custom content found in ${resolvedPath}`));
-
-      //   const { tryDifferent } = await inquirer.prompt([
-      //     {
-      //       type: 'confirm',
-      //       name: 'tryDifferent',
-      //       message: 'Try a different directory?',
-      //       default: true,
-      //     },
-      //   ]);
-
-      //   if (tryDifferent) {
-      //     return await this.promptCustomContentForExisting();
-      //   }
-
-      //   return { hasCustomContent: false };
-      // }
-
-      // // Display found items
-      // console.log(chalk.cyan(`\nFound ${customFiles.length} custom content file(s):`));
-      // const customContentItems = [];
-
-      // for (const customFile of customFiles) {
-      //   const customInfo = await customHandler.getCustomInfo(customFile);
-      //   if (customInfo) {
-      //     customContentItems.push({
-      //       name: `${chalk.cyan('✓')} ${customInfo.name} ${chalk.gray(`(${customInfo.relativePath})`)}`,
-      //       value: `__CUSTOM_CONTENT__${customFile}`,
-      //       checked: true,
-      //     });
-      //   }
-      // }
-
-      // // Add option to keep existing custom content
-      // console.log(chalk.yellow('\nExisting custom modules will be preserved unless you remove them'));
-
-      // const { selectedFiles } = await inquirer.prompt([
-      //   {
-      //     type: 'checkbox',
-      //     name: 'selectedFiles',
-      //     message: 'Select custom content to add:',
-      //     choices: customContentItems,
-      //     pageSize: 15,
-      //     validate: (answer) => {
-      //       if (answer.length === 0) {
-      //         return 'You must select at least one item';
-      //       }
-      //       return true;
-      //     },
-      //   },
-      // ]);
-
-      // return {
-      //   hasCustomContent: true,
-      //   customPath: resolvedPath,
-      //   selected: true,
-      //   selectedFiles: selectedFiles,
-      // };
-    } catch (error) {
-      console.error(chalk.red('Error configuring custom content:'), error);
-      return { hasCustomContent: false };
-    }
-  }
-
   /**
    * Prompt user for custom content source location
    * @returns {Object} Custom content configuration
@@ -1460,26 +1350,35 @@ class UI {
       customContentConfig: { hasCustomContent: false },
     };
 
-    if (cachedCustomModules.length === 0) {
-      return result;
-    }
-
     // Ask user about custom modules
     console.log(chalk.cyan('\n⚙️  Custom Modules'));
-    console.log(chalk.dim('Found custom modules in your installation:'));
+    if (cachedCustomModules.length > 0) {
+      console.log(chalk.dim('Found custom modules in your installation:'));
+    } else {
+      console.log(chalk.dim('No custom modules currently installed.'));
+    }
+
+    // Build choices dynamically based on whether we have existing modules
+    const choices = [];
+    if (cachedCustomModules.length > 0) {
+      choices.push(
+        { name: 'Keep all existing custom modules', value: 'keep' },
+        { name: 'Select which custom modules to keep', value: 'select' },
+        { name: 'Add new custom modules', value: 'add' },
+        { name: 'Remove all custom modules', value: 'remove' },
+      );
+    } else {
+      choices.push({ name: 'Add new custom modules', value: 'add' }, { name: 'Cancel (no custom modules)', value: 'cancel' });
+    }
 
     const { customAction } = await inquirer.prompt([
       {
         type: 'list',
         name: 'customAction',
-        message: 'What would you like to do with custom modules?',
-        choices: [
-          { name: 'Keep all existing custom modules', value: 'keep' },
-          { name: 'Select which custom modules to keep', value: 'select' },
-          { name: 'Add new custom modules', value: 'add' },
-          { name: 'Remove all custom modules', value: 'remove' },
-        ],
-        default: 'keep',
+        message:
+          cachedCustomModules.length > 0 ? 'What would you like to do with custom modules?' : 'Would you like to add custom modules?',
+        choices: choices,
+        default: cachedCustomModules.length > 0 ? 'keep' : 'add',
       },
     ]);
 
@@ -1512,19 +1411,9 @@ class UI {
       }
 
       case 'add': {
-        // First ask to keep existing ones
-        const { keepExisting } = await inquirer.prompt([
-          {
-            type: 'confirm',
-            name: 'keepExisting',
-            message: 'Keep existing custom modules?',
-            default: true,
-          },
-        ]);
-
-        if (keepExisting) {
-          result.selectedCustomModules = cachedCustomModules.map((m) => m.id);
-        }
+        // By default, keep existing modules when adding new ones
+        // User chose "Add new" not "Replace", so we assume they want to keep existing
+        result.selectedCustomModules = cachedCustomModules.map((m) => m.id);
 
         // Then prompt for new ones (reuse existing method)
         const newCustomContent = await this.promptCustomContentSource();
@@ -1540,6 +1429,12 @@ class UI {
         console.log(chalk.yellow('All custom modules will be removed from the installation'));
         break;
       }
+
+      case 'cancel': {
+        // User cancelled - no custom modules
+        console.log(chalk.dim('No custom modules will be added'));
+        break;
+      }
     }
 
     return result;