bmad-method 6.0.0-alpha.12 → 6.0.0-alpha.14

package/CHANGELOG.md

@@ -1,6 +1,259 @@
 # Changelog
 
-## [Unreleased]
+## [6.0.0-alpha.14]
+
+**Release: December 7, 2025**
+
+### 🔧 Installation & Configuration Revolution
+
+**Custom Module Installation Overhaul:**
+
+- **Simple custom.yaml Installation**: Custom agents and workflows can now be installed with a single YAML file
+- **IDE Configuration Preservation**: Upgrades will no longer delete custom modules, agents, and workflows from IDE configuration
+- **Removed Legacy agent-install Command**: Streamlined installation process (BREAKING CHANGE)
+- **Sidecar File Retention**: Custom sidecar files are preserved during updates
+- **Flexible Agent Sidecar Locations**: Fully configurable via config options instead of hardcoded paths
+
+**Module Discovery System Transformation:**
+
+- **Recursive Agent Discovery**: Deep scanning for agents across entire project structure
+- **Enhanced Manifest Generation**: Comprehensive scanning of all installed modules
+- **Nested Agent Support**: Fixed nested agents appearing in CLI commands
+- **Module Reinstall Fix**: Prevented modules from showing as obsolete during reinstall
+
+### 🏗️ Advanced Builder Features
+
+**Workflow Builder Evolution:**
+
+- **Continuable Workflows**: Create workflows with sophisticated branching and continuation logic
+- **Template LOD Options**: Level of Detail output options for flexible workflow generation
+- **Step-Based Architecture**: Complete conversion to granular step-file system
+- **Enhanced Creation Process**: Improved workflow creation with better template handling
+
+**Module Builder Revolution:**
+
+- **11-Step Module Creation**: Comprehensive step-by-step module generation process
+- **Production-Ready Templates**: Complete templates for agents, installers, and workflow plans
+- **Built-in Validation System**: Ensures module quality and BMad Core compliance
+- **Professional Documentation**: Auto-generated module documentation and structure
+
+### 🚀 BMad Method (BMM) Enhancements
+
+**Workflow Improvements:**
+
+- **Brownfield PRD Support**: Enhanced PRD workflow for existing project integration
+- **Sprint Status Command**: New workflow for tracking development progress
+- **Step-Based Format**: Improved continue functionality across all workflows
+- **Quick-Spec-Flow Documentation**: Rapid development specification flows
+
+**Documentation Revolution:**
+
+- **Comprehensive Troubleshooting Guide**: 680-line detailed troubleshooting documentation
+- **Quality Check Integration**: Added markdownlint-cli2 for markdown quality assurance
+- **Enhanced Test Architecture**: Improved CI/CD templates and testing workflows
+
+### 🌟 New Features & Integrations
+
+**Kiro-Cli Installer:**
+
+- **Intelligent Routing**: Smart routing to quick-dev workflow
+- **BMad Core Compliance**: Full compliance with BMad standards
+
+**Discord Notifications:**
+
+- **Compact Format**: Streamlined plain-text notifications
+- **Bug Fixes**: Resolved notification delivery issues
+
+**Example Mental Wellness Module (MWM):**
+
+- **Complete Module Example**: Demonstrates advanced module patterns
+- **Multiple Agents**: CBT Coach, Crisis Navigator, Meditation Guide, Wellness Companion
+- **Workflow Showcase**: Crisis support, daily check-in, meditation, journaling workflows
+
+### 🐛 Bug Fixes & Optimizations
+
+- Fixed version reading from package.json instead of hardcoded fallback
+- Removed hardcoded years from WebSearch queries
+- Removed broken build caching mechanism
+- Fixed hardcoded 'bmad' prefix from files-manifest.csv paths
+- Enhanced TTS injection summary with tracking and documentation
+- Fixed CI nvmrc configuration issues
+
+### 📊 Statistics
+
+- **335 files changed** with 17,161 additions and 8,204 deletions
+- **46 commits** since alpha.13
+
+### ⚠️ Breaking Changes
+
+1. **Removed agent-install Command**: Migrate to new custom.yaml installation system
+2. **Agent Sidecar Configuration**: Now requires explicit config instead of hardcoded paths
+
+### 📦 New Dependencies
+
+- `markdownlint-cli2: ^0.19.1` - Professional markdown linting
+
+---
+
+## [6.0.0-alpha.13]
+
+**Release: November 30, 2025**
+
+### 🏗️ Revolutionary Workflow Architecture
+
+**Granular Step-File Workflow System (NEW in alpha.13):**
+
+- **Multi-Menu Support**: Workflows now support granular step-file architecture with dynamic menu generation
+- **Sharded Workflows**: Complete conversion of Phase 1 and 2 workflows to stepwise sharded architecture
+- **Improved Performance**: Reduced file loading times and eliminated time-based estimates throughout
+- **Workflow Builder**: New dedicated workflow builder for creating stepwise workflows
+- **PRD Workflow**: First completely reworked sharded workflow resolving Sonnet compatibility issues
+
+**Core Workflow Transformations:**
+
+- Phase 1 and 2 workflows completely converted to sharded step-flow architecture
+- UX Design workflow converted to sharded step workflow
+- Brainstorming, Research, and Party Mode updated to use sharded step-flow workflows
+- Architecture workflows enhanced with step sharding and performance improvements
+
+### 🎯 Code Review & Development Enhancement
+
+**Advanced Code Review System:**
+
+- **Adversarial Code Review**: Quick-dev workflow now recommends adversarial review approach for higher quality
+- **Multi-LLM Strategy**: Dev-story workflow recommends different LLM models for code review tasks
+- **Agent Compiler Optimization**: Complete handler cleanup and performance improvements
+
+### 🤖 Agent System Revolution
+
+**Universal Custom Agent Support:**
+
+- **Complete IDE Coverage**: Custom agent support extended to ALL remaining IDEs
+- **Antigravity IDE Integration**: Added custom agent support with proper gitignore configuration
+- **Multiple Source Locations**: Compile agents now checks multiple source locations for better discovery
+- **Persona Name Display**: Fixed proper persona names display in custom agent manifests
+- **New IDE Support**: Added support for Rovo Dev IDE
+
+**Agent Creation & Management:**
+
+- **Improved Creation Workflow**: Enhanced agent creation workflow with better documentation
+- **Parameter Clarity**: Renamed agent-install parameters for better understanding
+- **Menu Organization**: BMad Agents menu items logically ordered with optional/recommended/required tags
+- **GitHub Migration**: GitHub integration now uses agents folder instead of chatmodes
+
+### 🔧 Phase 4 & Sprint Evolution
+
+**Complete Phase 4 Transformation:**
+
+- **Simplified Architecture**: Phase 4 workflows completely transformed - simpler, faster, better results
+- **Sprint Planning Integration**: Unified sprint planning with placeholders for Jira, Linear, and Trello integration
+- **Status Management**: Better status loading and updating for Phase 4 artifacts
+- **Workflow Reduction**: Phase 4 streamlined to single sprint planning item with clear validation
+- **Dynamic Workflows**: All Level 1-3 workflows now dynamically suggest next steps based on context
+
+### 🧪 Testing Infrastructure Expansion
+
+**Playwright Utils Integration:**
+
+- Test Architect now supports `@seontechnologies/playwright-utils` integration
+- Installation prompt with `use_playwright_utils` configuration flag
+- 11 comprehensive knowledge fragments covering ALL utilities
+- Adaptive workflow recommendations across 6 testing workflows
+- Production-ready utilities from SEON Technologies integrated with TEA patterns
+
+**Testing Environment:**
+
+- **Web Bundle Support**: Enabled web bundles for test and development environments
+- **Test Architecture**: Enhanced test design for architecture level (Phase 3) testing
+
+### 📦 Installation & Configuration
+
+**Installer Improvements:**
+
+- **Cleanup Options**: Installer now allows cleanup of unneeded files during upgrades
+- **Username Default**: Installer now defaults to system username for better UX
+- **IDE Selection**: Added empty IDE selection warning and promoted Antigravity to recommended
+- **NPM Vulnerabilities**: Resolved all npm vulnerabilities for enhanced security
+- **Documentation Installation**: Made documentation installation optional to reduce footprint
+
+**Text-to-Speech from AgentVibes optional Integration:**
+
+- **TTS_INJECTION System**: Complete text-to-speech integration via injection system
+- **Agent Vibes**: Enhanced with TTS capabilities for voice feedback
+
+### 🛠️ Tool & IDE Updates
+
+**IDE Tool Enhancements:**
+
+- **GitHub Copilot**: Fixed tool names consistency across workflows
+- **KiloCode Integration**: Gave kilocode tool proper access to bmad modes
+- **Code Quality**: Added radix parameter to parseInt() calls for better reliability
+- **Agent Menu Optimization**: Improved agent performance in Claude Code slash commands
+
+### 📚 Documentation & Standards
+
+**Documentation Cleanup:**
+
+- **Installation Guide**: Removed fluff and updated with npx support
+- **Workflow Documentation**: Fixed documentation by removing non-existent workflows and Mermaid diagrams
+- **Phase Numbering**: Fixed phase numbering consistency throughout documentation
+- **Package References**: Corrected incorrect npm package references
+
+**Workflow Compliance:**
+
+- **Validation Checks**: Enhanced workflow validation checks for compliance
+- **Product Brief**: Updated to comply with documented workflow standards
+- **Status Integration**: Workflow-status can now call workflow-init for better integration
+
+### 🔍 Legacy Workflow Cleanup
+
+**Deprecated Workflows Removed:**
+
+- **Audit Workflow**: Completely removed audit workflow and all associated files
+- **Convert Legacy**: Removed legacy conversion utilities
+- **Create/Edit Workflows**: Removed old workflow creation and editing workflows
+- **Clean Architecture**: Simplified workflow structure by removing deprecated legacy workflows
+
+### 🐛 Technical Fixes
+
+**System Improvements:**
+
+- **File Path Handling**: Fixed various file path issues across workflows
+- **Manifest Updates**: Updated manifest to use agents folder structure
+- **Web Bundle Configuration**: Fixed web bundle configurations for better compatibility
+- **CSV Column Mismatch**: Fixed manifest schema upgrade issues
+
+### ⚠️ Breaking Changes
+
+**Workflow Architecture:**
+
+- All legacy workflows have been removed - ensure you're using the new stepwise sharded workflows
+- Phase 4 completely restructured - update any automation expecting old Phase 4 structure
+- Epic creation now requires architectural context (moved to Phase 3 in previous release)
+
+**Agent System:**
+
+- Custom agents now require proper compilation - use the new agent creation workflow
+- GitHub integration moved from chatmodes to agents folder - update any references
+
+### 📊 Impact Summary
+
+**New in alpha.13:**
+
+- **Stepwise Workflow Architecture**: Complete transformation of all workflows to granular step-file system
+- **Universal Custom Agent Support**: Extended to ALL IDEs with improved creation workflow
+- **Phase 4 Revolution**: Completely restructured with sprint planning integration
+- **Legacy Cleanup**: Removed all deprecated workflows for cleaner system
+- **Advanced Code Review**: New adversarial review approach with multi-LLM strategy
+- **Text-to-Speech**: Full TTS integration for voice feedback
+- **Testing Expansion**: Playwright utils integration across all testing workflows
+
+**Enhanced from alpha.12:**
+
+- **Performance**: Improved file loading and removed time-based estimates
+- **Documentation**: Complete cleanup with accurate references
+- **Installer**: Better UX with cleanup options and improved defaults
+- **Agent System**: More reliable compilation and better persona handling
 
 ## [6.0.0-alpha.12]
 

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+the official BMAD Discord server (https://discord.com/invite/gk8jAdXWmj) - DM a moderator or flag a post.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

package/README.md

@@ -101,6 +101,8 @@ Each phase has specialized workflows and agents working together to deliver exce
 | UX Designer | Test Architect | Analyst       | BMad Master    |
 | Tech Writer | Game Architect | Game Designer | Game Developer |
 
+**Test Architect** integrates with `@seontechnologies/playwright-utils` for production-ready fixture-based utilities.
+
 Each agent brings deep expertise and can be customized to match your team's style.
 
 ## 📦 What's Included
@@ -162,7 +164,7 @@ For contributors working on the BMad codebase:
 npm test
 
 # Development commands
-npm run lint          # Check code style
+npm run lint:fix      # Fix code style
 npm run format:fix    # Auto-format code
 npm run bundle        # Build web bundles
 ```

package/docs/agent-customization-guide.md

@@ -138,10 +138,10 @@ critical_actions:
 # {bmad_folder}/_cfg/agents/bmm-dev.customize.yaml
 menu:
   - trigger: deploy-staging
-    workflow: '{project-root}/.bmad-custom/deploy-staging.yaml'
+    workflow: '{project-root}/{bmad_folder}/deploy-staging.yaml'
     description: Deploy to staging environment
   - trigger: deploy-prod
-    workflow: '{project-root}/.bmad-custom/deploy-prod.yaml'
+    workflow: '{project-root}/{bmad_folder}/deploy-prod.yaml'
     description: Deploy to production (with approval)
 ```
 

package/docs/custom-agent-installation.md

@@ -1,101 +1,68 @@
 # Custom Agent Installation
 
-Install and personalize BMAD agents in your project.
+BMAD agents and workflows are now installed through the main CLI installer using a `custom.yaml` configuration file or by having an installer file.
 
 ## Quick Start
 
-```bash
-# From your project directory with BMAD installed
-npx bmad agent-install
-```
-
-Or if you have bmad-cli installed globally:
+Create a `custom.yaml` file in the root of your agent/workflow folder:
 
-```bash
-bmad agent-install
+```yaml
+code: my-custom-agent
+name: 'My Custom Agent'
+default_selected: true
 ```
 
-## What It Does
-
-1. **Discovers** available agent templates from your custom agents folder
-2. **Prompts** you to personalize the agent (name, behavior, preferences)
-3. **Compiles** the agent with your choices baked in
-4. **Installs** to your project's `.bmad/custom/agents/` directory
-5. **Creates** IDE commands for all your configured IDEs (Claude Code, Codex, Cursor, etc.)
-6. **Saves** your configuration for automatic reinstallation during BMAD updates
-
-## Options
+Then run the BMAD installer from your project directory:
 
 ```bash
-bmad agent-install [options]
-
-Options:
-  -p, --path <path>     Direct path to specific agent YAML file or folder
-  -d, --defaults        Use default values without prompting
-  -t, --target <path>   Target installation directory
+npx bmad-method install
 ```
 
-## Example Session
+Or if you have bmad-cli installed globally:
 
+```bash
+bmad install
 ```
-🔧 BMAD Agent Installer
-
-Found BMAD at: /project/.bmad
-Searching for agents in: /project/.bmad/custom/agents
-
-Available Agents:
-
-  1. 📄 commit-poet (simple)
-  2. 📚 journal-keeper (expert)
-
-Select agent to install (number): 1
 
-Selected: commit-poet
+## Installation Methods
 
-📛 Agent Persona Name
+### Method 1: Stand-alone Folder with custom.yaml
 
-   Agent type: commit-poet
-   Default persona: Inkwell Von Comitizen
+Place your agent or workflow in a folder with a `custom.yaml` file at the root:
 
-   Custom name (or Enter for default): Fred
+```
+my-agent/
+├── custom.yaml      # Required configuration file
+├── my-agent.agent.yaml
+└── sidecar/         # Optional
+    └── instructions.md
+```
 
-   Persona: Fred
-   File: fred-commit-poet.md
+### Method 2: Installer File
 
-📝 Agent Configuration
+For more complex installations, include an `installer.js` or `installer.yaml` file in your agent/workflow folder:
 
-   What's your preferred default commit message style?
-   * 1. Conventional (feat/fix/chore)
-     2. Narrative storytelling
-     3. Poetic haiku
-     4. Detailed explanation
-   Choice (default: 1): 1
+```
+my-workflow/
+├── workflow.md
+└── installer.yaml   # Custom installation logic
+```
 
-   How enthusiastic should the agent be?
-     1. Moderate - Professional with personality
-   * 2. High - Genuinely excited
-     3. EXTREME - Full theatrical drama
-   Choice (default: 2): 3
+## What It Does
 
-   Include emojis in commit messages? [Y/n]: y
+1. **Discovers** available agents and workflows from folders with `custom.yaml`
+2. **Installs** to your project's `.bmad/custom/` directory
+3. **Creates** IDE commands for all your configured IDEs (Claude Code, Codex, Cursor, etc.)
+4. **Registers** the agent/workflow in the BMAD system
 
-✨ Agent installed successfully!
-   Name: fred-commit-poet
-   Location: /project/.bmad/custom/agents/fred-commit-poet
-   Compiled: fred-commit-poet.md
+## Example custom.yaml
 
-   ✓ Source saved for reinstallation
-   ✓ Added to agent-manifest.csv
-   ✓ Created IDE commands:
-      claude-code: /bmad:custom:agents:fred-commit-poet
-      codex: /bmad-custom-agents-fred-commit-poet
-      github-copilot: bmad-agent-custom-fred-commit-poet
+```yaml
+code: my-custom-agent
+name: 'My Custom Agent'
+default_selected: true
 ```
 
-## Reinstallation
-
-Custom agents are automatically reinstalled when you run `bmad init --quick`. Your personalization choices are preserved in `.bmad/_cfg/custom/agents/`.
-
 ## Installing Reference Agents
 
 The BMAD source includes example agents you can install. **You must copy them to your project first.**
@@ -106,8 +73,9 @@ The BMAD source includes example agents you can install. **You must copy them to
 
 ```bash
 # From your project root
+mkdir -p .bmad/custom/agents/my-agent
 cp node_modules/bmad-method/src/modules/bmb/reference/agents/stand-alone/commit-poet.agent.yaml \
-   .bmad/custom/agents/
+   .bmad/custom/agents/my-agent/
 ```
 
 **For expert agents** (folder with sidecar files):
@@ -118,19 +86,29 @@ cp -r node_modules/bmad-method/src/modules/bmb/reference/agents/agent-with-memor
    .bmad/custom/agents/
 ```
 
-### Step 2: Install and Personalize
+### Step 2: Create custom.yaml
 
 ```bash
-npx bmad agent-install
-# or: bmad agent-install
+# In the agent folder, create custom.yaml
+cat > .bmad/custom/agents/my-agent/custom.yaml << EOF
+code: my-agent
+name: "My Custom Agent"
+default_selected: true
+EOF
+```
+
+### Step 3: Install
+
+```bash
+npx bmad-method install
+# or: bmad install (if BMAD installed locally)
 ```
 
 The installer will:
 
-1. Find the copied template in `.bmad/custom/agents/`
-2. Prompt for personalization (name, behavior, preferences)
-3. Compile and install with your choices baked in
-4. Create IDE commands for immediate use
+1. Find the agent with its `custom.yaml`
+2. Install it to the appropriate location
+3. Create IDE commands for immediate use
 
 ### Available Reference Agents
 
@@ -156,14 +134,4 @@ src/modules/bmb/reference/agents/
 
 ## Creating Your Own
 
-Place your `.agent.yaml` files in `.bmad/custom/agents/`. Use the reference agents as templates.
-
-Key sections in an agent YAML:
-
-- `metadata`: name, title, icon, type
-- `persona`: role, identity, communication_style, principles
-- `prompts`: reusable prompt templates
-- `menu`: numbered menu items
-- `install_config`: personalization questions (optional, at end of file)
-
-See the reference agents for complete examples with install_config templates and XML-style semantic tags.
+Use the BMB agent builder to craft your agents. Once ready to use, place your `.agent.yaml` files or folders with `custom.yaml` in `.bmad/custom/agents/` or `.bmad/custom/workflows/`.

package/docs/document-sharding-guide.md

@@ -190,7 +190,7 @@ Workflows load only needed sections:
 
 - Needs ALL epics to build complete status
 
-**epic-tech-context, create-story, story-context, code-review** (Selective):
+**create-story, code-review** (Selective):
 
 ```
 Working on Epic 3, Story 2: