CHANGELOG.md

@@ -1,161 +1,5 @@
 # Changelog
 
-## [6.0.0-alpha.22]
-
-**Release: December 31, 2025**
-
-### 🌟 Key Highlights
-
-1. **Unified Agent Workflow**: Create, Edit, and Validate workflows consolidated into single powerful agent workflow with separate step paths
-2. **Agent Knowledge System**: Comprehensive data file architecture with persona properties, validation patterns, and crafting principles
-3. **Deep Language Integration**: All sharded progressive workflows now support language choice at every step
-4. **Core Module Documentation**: Extensive docs for core workflows (brainstorming, party mode, advanced elicitation)
-5. **BMAD Core Concepts**: New documentation structure explaining agents, workflows, modules, and installation
-6. **Tech Spec Sharded**: create-tech-spec workflow converted to sharded format with orient-first pattern
-
-### 🤖 Unified Agent Workflow (Major Feature)
-
-**Consolidated Architecture:**
-
-- **Single Workflow, Three Paths**: Create, Edit, and Validate operations unified under `src/modules/bmb/workflows/agent/`
-- **steps-c/**: Create path with 9 comprehensive steps for building new agents
-- **steps-e/**: Edit path with 10 steps for modifying existing agents
-- **steps-v/**: Validate path for standalone agent validation review
-- **data/**: Centralized knowledge base for all agent-building intel
-
-### 📚 Agent Knowledge System
-
-**Data File Architecture:**
-
-Located in `src/modules/bmb/workflows/agent/data/`:
-
-- **agent-metadata.md** (208 lines) - Complete metadata field reference
-- **agent-menu-patterns.md** (233 lines) - Menu design patterns and best practices
-- **agent-compilation.md** (273 lines) - Compilation process documentation
-- **persona-properties.md** (266 lines) - Persona crafting properties and examples
-- **principles-crafting.md** (292 lines) - Core principles for agent design
-- **critical-actions.md** (120 lines) - Critical action patterns
-- **expert-agent-architecture.md** (236 lines) - Expert agent structure
-- **expert-agent-validation.md** (173 lines) - Expert-specific validation
-- **module-agent-validation.md** (124 lines) - Module-specific validation
-- **simple-agent-architecture.md** (204 lines) - Simple agent structure
-- **simple-agent-validation.md** (132 lines) - Simple agent validation
-- **understanding-agent-types.md** (222 lines) - Agent type comparison
-- **brainstorm-context.md** - Brainstorming guidance
-- **communication-presets.csv** - Communication style presets
-
-**Reference Examples:**
-
-- **reference/module-examples/architect.agent.yaml** - Module agent example
-- **reference/simple-examples/commit-poet.agent.yaml** - Simple agent example
-- **journal-keeper/** - Complete sidecar pattern example
-
-**Templates:**
-
-- **templates/simple-agent.template.md** - Simple agent template
-- **templates/expert-agent-template/expert-agent.template.md** - Expert agent template
-- **templates/expert-agent-sidecar/** - Sidecar templates (instructions, memories)
-
-### 🌍 Deep Language Integration
-
-**Progressive Workflow Language Support:**
-
-- **Every Step Biased**: All sharded progressive workflow steps now include language preference context
-- **260+ Files Updated**: Comprehensive language integration across:
-  - Core workflows (brainstorming, party mode, advanced elicitation)
-  - BMB workflows (create-agent, create-module, create-workflow, edit-workflow, etc.)
-  - BMGD workflows (game-brief, gdd, narrative, game-architecture, etc.)
-  - BMM workflows (research, create-ux-design, prd, create-architecture, etc.)
-- **Tested Languages**: Verified working with Spanish and Pirate Speak
-- **Natural Conversations**: AI agents respond in configured language throughout workflow
-
-### 📖 Core Module Documentation
-
-**New Core Documentation Structure:**
-
-`docs/modules/core/`:
-
-- **index.md** - Core module overview
-- **core-workflows.md** - Core workflow documentation
-- **core-tasks.md** - Core task reference
-- **brainstorming.md** (100 lines) - Brainstorming workflow guide
-- **party-mode.md** (50 lines) - Party mode guide
-- **advanced-elicitation.md** (105 lines) - Advanced elicitation techniques
-- **document-sharding-guide.md** (133 lines) - Sharded workflow format guide
-- **global-core-config.md** - Global core configuration reference
-
-**Advanced Elicitation Moved:**
-
-- **From**: `docs/` root
-- **To**: `src/core/workflows/advanced-elicitation/`
-- **Status**: Now a proper core workflow with methods.csv
-
-### 📚 BMAD Core Concepts Documentation
-
-**New Documentation Structure:**
-
-`docs/bmad-core-concepts/`:
-
-- **index.md** - Core concepts introduction
-- **agents.md** (93 lines) - Understanding agents in BMAD
-- **workflows.md** (89 lines) - Understanding workflows in BMAD
-- **modules.md** (76 lines) - Understanding modules (BMM, BMGD, CIS, BMB, Core)
-- **installing/index.md** (77 lines) - Installation guide
-- **installing/upgrading.md** (144 lines) - Upgrading guide
-- **bmad-customization/index.md** - Customization overview
-- **bmad-customization/agents.md** - Agent customization guide
-- **bmad-customization/workflows.md** (30 lines) - Workflow customization guide
-- **web-bundles/index.md** (34 lines) - Web bundle distribution guide
-
-**Documentation Cleanup:**
-
-- **Removed v4-to-v6-upgrade.md** - Outdated upgrade guide
-- **Removed document-sharding-guide.md** from docs root (moved to core)
-- **Removed web-bundles-gemini-gpt-guide.md** - Consolidated into web-bundles/index.md
-- **Removed getting-started/installation.md** - Migrated to bmad-core-concepts
-- **Removed all ide-info/*.md files** - Consolidated into web-bundles documentation
-
-### 🔧 Create-Tech-Spec Sharded Conversion
-
-**Monolithic to Sharded:**
-
-- **From**: Single `workflow.yaml` with `instructions.md`
-- **To**: Sharded `workflow.md` with individual step files
-- **Pattern**: Orient-first approach (understand before investigating)
-
-### 🔨 Additional Improvements
-
-**Workflow Status Path Fixes:**
-
-- **Corrected Discovery Paths**: workflow-status workflows now properly use planning_artifacts and implementation_artifacts
-- **Updated All Path Files**: enterprise-brownfield, enterprise-greenfield, method-brownfield, method-greenfield
-
-**Documentation Updates:**
-
-- **BMB Agent Creation Guide**: Comprehensive 166-line guide for agent creation
-- **Workflow Vendoring Doc**: New 42-line guide on workflow customization and inheritance
-- **Document Project Reference**: Moved from BMM docs to shared location
-- **Workflows Planning Guide**: New 89-line guide for planning workflows
-
-**BMB Documentation Streamlining:**
-
-- **Removed Redundant Docs**: Eliminated duplicate documentation in `src/modules/bmb/docs/`
-- **Step File Rules**: New 469-line comprehensive guide for step file creation
-- **Agent Docs Moved**: Agent architecture and validation docs moved to workflow data/
-
-**Windows Inquirer Fix:**
-
-- **Another Default Addition**: Additional inquirer default value setting for better Windows multiselection support
-
-**Code Quality:**
-
-- **Removed Old BMM README**: Consolidated module documentation
-- **Removed BMM Troubleshooting**: 661-line doc moved to shared location
-- **Removed Enterprise Agentic Development**: 686-line doc consolidated
-- **Removed Scale Adaptive System**: 618-line doc consolidated
-
----
-
 ## [6.0.0-alpha.21]
 
 **Release: December 27, 2025**

docs/bmad-core-concepts/agents.md

@@ -1,93 +0,0 @@
-# Agents
-
-Agents are AI assistants that help you accomplish tasks. Each agent has a unique personality, specialized capabilities, and an interactive menu.
-
-## Agent Types
-
-BMAD has two primary agent types, designed for different use cases:
-
-### Simple Agents
-
-**Self-contained, focused, ready to use.**
-
-Simple agents are complete in a single file. They excel at well-defined tasks and require minimal setup.
-
-**Best for:**
-- Single-purpose assistants (code review, documentation, commit messages)
-- Quick deployment
-- Projects that don't require persistent memory
-- Getting started fast
-
-**Example:** A commit message agent that reads your git diff and generates conventional commits.
-
-### Expert Agents
-
-**Powerful, memory-equipped, domain specialists.**
-
-Expert agents have a **sidecar** - a companion folder containing additional instructions, workflows, and memory files. They remember context across sessions and handle complex, multi-step tasks.
-
-**Best for:**
-- Domain specialists (security architect, game designer, product manager)
-- Tasks requiring persistent memory
-- Complex workflows with multiple stages
-- Projects that grow over time
-
-**Example:** A game architect that remembers your design decisions, maintains consistency across sprints, and coordinates with other specialists.
-
-## Key Differences
-
-| Feature          | Simple         | Expert                     |
-| ---------------- | -------------- | -------------------------- |
-| **Files**        | Single file    | Agent + sidecar folder     |
-| **Memory**       | Session only   | Persistent across sessions |
-| **Capabilities** | Focused scope  | Multi-domain, extensible   |
-| **Setup**        | Zero config    | Sidecar initialization     |
-| **Best Use**     | Specific tasks | Ongoing projects           |
-
-## Agent Components
-
-All agents share these building blocks:
-
-### Persona
-- **Role** - What the agent does (expertise domain)
-- **Identity** - Who the agent is (personality, character)
-- **Communication Style** - How the agent speaks (tone, voice)
-- **Principles** - Why the agent acts (values, decision framework)
-
-### Capabilities
-- Skills, tools, and knowledge the agent can apply
-- Mapped to specific menu commands
-
-### Menu
-- Interactive command list
-- Triggers, descriptions, and handlers
-- Auto-includes help and exit options
-
-### Critical Actions (optional)
-- Instructions that execute before the agent starts
-- Enable autonomous behaviors (e.g., "check git status before changes")
-
-## Which Should You Use?
-
-**Choose Simple when:**
-- You need a task done quickly and reliably
-- The scope is well-defined and won't change much
-- You don't need the agent to remember things between sessions
-
-**Choose Expert when:**
-- You're building something complex over time
-- The agent needs to maintain context (project history, decisions)
-- You want the agent to coordinate workflows or other agents
-- Domain expertise requires specialized knowledge bases
-
-## Creating Custom Agents
-
-BMAD provides the **BMAD Builder (BMB)** module for creating your own agents. See the [Agent Creation Guide](../modules/bmb-bmad-builder/agent-creation-guide.md) for step-by-step instructions.
-
-## Customizing Existing Agents
-
-You can modify any agent's behavior without editing core files. See [BMAD Customization](./bmad-customization/) for details. It is critical to never modify an installed agents .md file directly and follow the customization process, this way future updates to the agent or module its part of will continue to be updated and recompiled with the installer tool, and your customizations will still be retained.
-
----
-
-**Next:** Learn about [Workflows](./workflows.md) to see how agents accomplish complex tasks.

docs/bmad-core-concepts/bmad-customization/index.md

@@ -1,26 +0,0 @@
-# BMAD Customization
-
-Personalize agents and workflows to match your needs.
-
-## Guides
-
-| Guide | Description |
-|-------|-------------|
-| **[Agent Customization](./agents.md)** | Modify agent behavior without editing core files |
-| **[Workflow Customization](./workflows.md)** | Customize and optimize workflows |
-
-## Overview
-
-BMAD provides two main customization approaches:
-
-### Agent Customization
-Modify any agent's persona, name, capabilities, or menu items using `.customize.yaml` files in `_bmad/_config/agents/`. Your customizations persist through updates.
-
-### Workflow Customization
-Replace or extend workflow steps to create tailored processes. (Coming soon)
-
----
-
-**Next:** Read the [Agent Customization Guide](./agents.md) to start personalizing your agents.
-
-[← Back to Core Concepts](../index.md)

docs/bmad-core-concepts/bmad-customization/workflows.md

@@ -1,30 +0,0 @@
-# Workflow Customization Guide
-
-Customize and optimize workflows with step replacement and hooks.
-
-## Status
-
-> **Coming Soon:** Workflow customization is an upcoming capability. This guide will be updated when the feature is available.
-
-## What to Expect
-
-Workflow customization will allow you to:
-
-- **Replace Steps** - Swap out specific workflow steps with custom implementations
-- **Add Hooks** - Inject custom behavior before/after workflow steps
-- **Extend Workflows** - Create new workflows based on existing ones
-- **Override Behavior** - Customize workflow logic for your project's needs
-
-## For Now
-
-While workflow customization is in development, you can:
-
-- **Create Custom Workflows** - Use the BMAD Builder to create entirely new workflows
-- **Customize Agents** - Modify agent behavior using [Agent Customization](./agents.md)
-- **Provide Feedback** - Share your workflow customization needs with the community
-
----
-
-**In the meantime:** Learn how to [create custom workflows](../../modules/bmb-bmad-builder/index) from scratch.
-
-[← Back to Customization](./index.md)

docs/bmad-core-concepts/index.md

@@ -1,37 +0,0 @@
-# BMAD Core Concepts
-
-Understanding the fundamental building blocks of the BMAD Method.
-
-## The Essentials
-
-| Concept | Description | Guide |
-|---------|-------------|-------|
-| **Agents** | AI assistants with personas, capabilities, and menus | [Agents Guide](./agents.md) |
-| **Workflows** | Structured processes for achieving specific outcomes | [Workflows Guide](./workflows.md) |
-| **Modules** | Packaged collections of agents and workflows | [Modules Guide](./modules.md) |
-
-## Getting Started
-
-### New to BMAD?
-Start here to understand what BMAD is and how it works:
-
-1. **[Agents Guide](./agents.md)** - Learn about Simple and Expert agents
-2. **[Workflows Guide](./workflows.md)** - Understand how workflows orchestrate tasks
-3. **[Modules Guide](./modules.md)** - See how modules organize functionality
-
-### Installing BMAD
-
-- **[Installation Guide](./installing/)** - Set up BMAD in your project
-- **[Upgrading from v4](./installing/upgrading.md)** - Migrate from earlier versions
-
-### Configuration
-
-- **[BMAD Customization](./bmad-customization/)** - Personalize agents and workflows
-
-### Advanced
-
-- **[Web Bundles](./web-bundles/)** - Use BMAD in Gemini Gems and Custom GPTs
-
----
-
-**Next:** Read the [Agents Guide](./agents.md) to understand the core building block of BMAD.

docs/bmad-core-concepts/modules.md

@@ -1,76 +0,0 @@
-# Modules
-
-Modules are organized collections of agents and workflows that solve specific problems or address particular domains.
-
-## What is a Module?
-
-A module is a self-contained package that includes:
-
-- **Agents** - Specialized AI assistants
-- **Workflows** - Step-by-step processes
-- **Configuration** - Module-specific settings
-- **Documentation** - Usage guides and reference
-
-## Official Modules
-
-### Core Module
-Always installed, provides shared functionality:
-- Global configuration
-- Core workflows (Party Mode, Advanced Elicitation, Brainstorming)
-- Common tasks (document indexing, sharding, review)
-
-### BMAD Method (BMM)
-Software and game development:
-- Project planning workflows
-- Implementation agents (Dev, PM, QA, Scrum Master)
-- Testing and architecture guidance
-
-### BMAD Builder (BMB)
-Create custom solutions:
-- Agent creation workflows
-- Workflow authoring tools
-- Module scaffolding
-
-### Creative Intelligence Suite (CIS)
-Innovation and creativity:
-- Creative thinking techniques
-- Innovation strategy workflows
-- Storytelling and ideation
-
-### BMAD Game Dev (BMGD)
-Game development specialization:
-- Game design workflows
-- Narrative development
-- Performance testing frameworks
-
-## Module Structure
-
-Installed modules follow this structure:
-
-```
-_bmad/
-├── core/           # Always present
-├── bmm/            # BMAD Method (if installed)
-├── bmb/            # BMAD Builder (if installed)
-├── cis/            # Creative Intelligence (if installed)
-└── bmgd/           # Game Dev (if installed)
-```
-
-## Custom Modules
-
-You can create your own modules containing:
-- Custom agents for your domain
-- Organizational workflows
-- Team-specific configurations
-
-Custom modules are installed the same way as official modules.
-
-## Installing Modules
-
-During BMAD installation, you choose which modules to install. You can also add or remove modules later by re-running the installer.
-
-See [Installation Guide](./installing/) for details.
-
----
-
-**Next:** Read the [Installation Guide](./installing/) to set up BMAD with the modules you need.

docs/bmad-core-concepts/web-bundles/index.md

@@ -1,34 +0,0 @@
-# Web Bundles
-
-Use BMAD agents in Gemini Gems and Custom GPTs.
-
-## Status
-
-> **Note:** The Web Bundling Feature is being rebuilt from the ground up. Current v6 bundles may be incomplete or missing functionality.
-
-## What Are Web Bundles?
-
-Web bundles package BMad agents as self-contained files that work in Gemini Gems and Custom GPTs. Everything the agent needs - instructions, workflows, dependencies - is bundled into a single file for easy upload.
-
-### What's Included
-
-- Complete agent persona and instructions
-- All workflows and dependencies
-- Interactive menu system
-- Party mode for multi-agent collaboration
-- No external files required
-
-### Use Cases
-
-**Perfect for:**
-- Uploading a single file to a Gemini GEM or Custom GPT
-- Using BMAD Method from the Web
-- Cost savings (generally lower cost than local usage)
-- Quick sharing of agent configurations
-
-**Trade-offs:**
-- Some quality reduction vs local usage
-- Less convenient than full local installation
-- Limited to agent capabilities (no workflow file access)
-
-[← Back to Core Concepts](../index.md)

docs/bmad-core-concepts/workflows.md

@@ -1,89 +0,0 @@
-# Workflows
-
-Workflows are structured processes that guide agents through complex tasks. Think of them as recipes that ensure consistent, high-quality outcomes.
-
-## What is a Workflow?
-
-A workflow is a step-by-step process that agents follow to accomplish specific objectives. A workflow can be a single file if small enough, but more than likely is comprized of a very small workflow or skill definition file with multiple steps and data files that are loaded as needed on demand. Each step file:
-
-- Defines a clear goal
-- Provides instructions for the agent
-- May include decision points or user interactions
-- Produces specific outputs
-- Progressively at a specific point can load the next proper step.
-
-## How Workflows Work
-
-```
-┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
-│   Step 1    │ →  │   Step 2    │ →  │   Step 3    │ →  │  Complete   │
-│  Discover   │    │   Define    │    │   Build     │    │   Output    │
-└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
-```
-
-**Key characteristics:**
-- **Progressive** - Each step builds on the previous
-- **Interactive** - Workflows can pause for user input
-- **Reusable** - The same workflow produces consistent results
-- **Composable** - Workflow steps can call other workflow steps, or whole other workflows!
-- **LLM Reinforcement** - Some rules or info is repeated in each step file ensuring certain rules are always top of agent mind, even during context heavy processes or very long workflows!
-
-## Workflow Types
-
-### Planning Workflows
-
-Generate project artifacts like requirements, architecture, and task breakdowns.
-
-**Examples:** Brief creation, PRD authoring, architecture design, sprint planning
-
-### Execution Workflows
-
-Guide implementation of specific tasks or features.
-
-**Examples:** Code implementation, code review, testing, deployment
-
-### Support Workflows
-
-Handle cross-cutting concerns and creative processes.
-
-**Examples:** Brainstorming, retrospectives, root cause analysis
-
-## Progressive Disclosure
-
-BMAD workflows use **progressive disclosure** - each step only knows about its immediate next step and what it is currently meant to do. This:
-
-- Reduces cognitive load on the AI
-- Ensures each step gets full attention
-- Allows for conditional routing based on previous outcomes
-- Makes workflows easier to debug and modify
-
-## Menu-Driven Interaction
-
-Most workflows use interactive menus with standard options:
-
-| Option           | Purpose                                            |
-| ---------------- | -------------------------------------------------- |
-| **[A] Advanced** | Invoke deeper reasoning techniques                 |
-| **[P] Party**    | Get multiple agent perspectives                    |
-| **[C] Continue** | Proceed to next step after all writes are complete |
-
-## Workflow Files
-
-Workflows are markdown files with structured frontmatter - this front matter also allows them to easily work as skills and also slash command loaded:
-
-```yaml
----
-name: 'my-workflow'
-description: 'What this workflow does and when it should be used or loaded automatically (or call out if it should be requested to run explicitly by the user)'
----
-```
-
-The content in the workflow file is very minimal, sets up the reinforcement of the agent persona and reminder that it is a facilitator working with a user, lays out rules of processing steps only when told to do a specific step, loads all config file variables needed by the workflow, and then routes to step 1. No other info about other steps should be in this workflow file. Keeping it as small and lean as possible help in compilation as a skill, as overall size of the skill main file (workflow.md) is critical to keep small.
-
-## Creating Custom Workflows
-
-The **BMAD Builder (BMB)** module includes workflows for creating custom workflows. See [BMB Documentation](../modules/bmb-bmad-builder/) for details.
-
----
-
-**Next:** Learn about [Modules](./modules.md) to see how agents and workflows are organized.

docs/bmad-customization/agent-customization-guide.md

@@ -203,8 +203,6 @@ memories:
 
 ## Next Steps
 
-- **[Learn about Agents](../agents.md)** - Understand Simple vs Expert agents
+- **[BMM Agents Guide](./modules/bmm/agents-guide)** - Learn about the BMad Method agents
-- **[Agent Creation Guide](../../modules/bmb-bmad-builder/agent-creation-guide.md)** - Build completely custom agents
+- **[BMB Create Agent Workflow](./modules/bmb/agents/index)** - Build completely custom agents
-- **[BMM Complete Documentation](../../modules/bmm-bmad-method/index)** - Full BMad Method reference
+- **[BMM Complete Documentation](./modules/bmm/index)** - Full BMad Method reference
-
-[← Back to Customization](./index.md)

docs/bmad-customization/workflow-customization-guide.md

@@ -0,0 +1,3 @@
+# Workflow Customization Guide
+
+Coming Soon...

docs/index.md

@@ -1,95 +1,91 @@
-# BMAD Documentation
+# BMad Documentation Index
 
-Complete documentation for the BMAD Method.
+## Core Documentation
 
-## Getting Started
+### Project-Level Docs (Root)
 
-### New to BMAD?
+- **[README.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/README.md)** - Main project overview, feature summary, and module introductions
-Start with the core concepts to understand how BMAD works:
+- **[CONTRIBUTING.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/CONTRIBUTING.md)** - How to contribute, pull request guidelines, code style
+- **[CHANGELOG.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/CHANGELOG.md)** - Version history and breaking changes
 
-- **[Core Concepts](./bmad-core-concepts/)** - Agents, workflows, and modules explained
+### Installation & Setup
-- **[Installation Guide](./bmad-core-concepts/installing/)** - Set up BMAD in your project
-- **[Quick Start Guide](./modules/bmm-bmad-method/quick-start)** - Build your first feature
 
-### Upgrading from v4?
+- **[Quick Installation](./installing-bmad.md)** - Add BMad official and custom modules to a project folder.
-- **[v4 to v6 Upgrade Guide](./bmad-core-concepts/installing/upgrading.md)** - Migration path for v4 users
+- **[v4 to v6 Upgrade Guide](./v4-to-v6-upgrade.md)** - Migration path for v4 users
-
+- **[Document Sharding Guide](modules/core/document-sharding-guide.md)** - Split large documents
----
+- **[Bundle Distribution Setup](../tools/docs/BUNDLE_DISTRIBUTION_SETUP.md)** - (temporarily non-functional) Maintainer guide for bundle auto-publishing
 
 ## Module Documentation
 
-### BMAD Method (BMM) - Software & Game Development
+### Core Module Global Entities
+
+- **[Core Module Index](./modules/core/index)** — Shared functionality available to all modules
+  - [Global Core Config](./modules/core/global-core-config.md) — Inheritable configuration impacting all modules and custom content
+  - [Core Workflows](./modules/core/core-workflows.md) — Domain-agnostic workflows usable by any module
+    - [Party Mode](./modules/core/party-mode.md) — Multi-agent conversation orchestration
+    - [Brainstorming](./modules/core/brainstorming.md) — Structured creative sessions with 60+ techniques
+    - [Advanced Elicitation](./modules/core/advanced-elicitation.md) — LLM rethinking with 50+ reasoning methods
+  - [Core Tasks](./modules/core/core-tasks.md) — Common tasks available across modules
+    - [Index Docs](./modules/core/core-tasks.md#index-docs) — Generate directory index files
+    - [Adversarial Review](./modules/core/core-tasks.md#adversarial-review-general) — Critical content review
+    - [Shard Document](./modules/core/core-tasks.md#shard-document) — Split large documents into sections
+
+### BMad Method (BMM) - Software & Game Development
 
 The flagship module for agile AI-driven development.
 
-- **[BMM Module Index](./modules/bmm-bmad-method/index)** - Module overview, agents, and documentation
+- **[BMM Module Index](./modules/bmm-bmad-method/index)** - Module overview, agents, and complete documentation index
-  - [Quick Start Guide](./modules/bmm-bmad-method/quick-start) - Step-by-step guide
+  - [Quick Start Guide](./modules/bmm-bmad-method/quick-start) - Step-by-step guide to building your first project
   - [Quick Spec Flow](./modules/bmm-bmad-method/quick-spec-flow) - Rapid Level 0-1 development
   - [Brownfield Guide](./modules/bmm-bmad-method/brownfield-guide) - Working with existing codebases
-- **[BMM Workflows Guide](./modules/bmm-bmad-method/index#-workflow-guides)** - Essential reading
+- **[BMM Workflows Guide](./modules/bmm-bmad-method/index#-workflow-guides)** - **ESSENTIAL READING**
+- **[Test Architect Guide](./modules/bmm-bmad-method/test-architecture)** - Testing strategy and quality assurance
 
-### BMAD Builder (BMB) - Create Custom Solutions
+### BMad Builder (BMB) - Create Custom Solutions
 
 Build your own agents, workflows, and modules.
 
 - **[BMB Module Overview](./modules/bmb-bmad-builder/index)** - Module overview and capabilities
-- **[Agent Creation Guide](./modules/bmb-bmad-builder/agent-creation-guide.md)** - Create custom agents
+- **[Custom Content Guide](./modules/bmb-bmad-builder/custom-content)** - Design custom agents, workflows, and modules
-- **[Custom Content Installation](./modules/bmb-bmad-builder/custom-content-installation.md)** - Share and install custom creations
+- **[How to Install Custom Agents, Workflows and Modules](./modules/bmb-bmad-builder/custom-content-installation.md)** - Share and Install Custom Creations
 
 ### Creative Intelligence Suite (CIS) - Innovation & Creativity
 
-- **[CIS Documentation](./modules/cis-creative-intelligence-suite/index)**
+- **[CIS Docs](./modules/cis-creative-intelligence-suite/index.md)**
 
-### BMAD Game Dev (BMGD)
+#### Bmad Game Dev (BMGD)
 
-- **[BMGD Documentation](./modules/bmgd-bmad-game-dev/index)** - Game development workflows
+- [Main Game Dev Module Docs Index](./modules/bmgd-bmad-game-dev/index.md)
 
----
+AI-powered creative thinking and brainstorming.
 
-## Core Module
+- **[CIS Module README](./modules/cis-creative-intelligence-suite/index)** - Module overview and workflows
-
-### Global Core Entities
-
-- **[Core Module Index](./modules/core/index)** - Shared functionality available to all modules
-  - [Global Core Config](./modules/core/global-core-config.md) - Inheritable configuration
-  - [Core Workflows](./modules/core/core-workflows.md) - Domain-agnostic workflows
-    - [Party Mode](./modules/core/party-mode.md) - Multi-agent conversations
-    - [Brainstorming](./modules/core/brainstorming.md) - Structured creative sessions
-    - [Advanced Elicitation](./modules/core/advanced-elicitation.md) - LLM reasoning techniques
-  - [Core Tasks](./modules/core/core-tasks.md) - Common tasks across modules
-
----
 
 ## Advanced Topics
 
-### Customization
+### Custom Agents, Workflow and Modules
-
+- **[Custom Content Installation](modules/bmb-bmad-builder/custom-content-installation.md)** - Install and personalize agents, workflows and modules with the default bmad-method installer!
-- **[BMAD Customization](./bmad-core-concepts/bmad-customization/)** - Modify agents and workflows
+- [Agent Customization Guide](./bmad-customization/agent-customization-guide.md) - Customize agent behavior and responses
-
+- [Workflow Customization Guide](./bmad-customization/workflow-customization-guide.md) - Customize and Optimize workflows with step replacement and hooks (Capability Coming Soon)
-### Platform Guides
-
-- **[Web Bundles](./bmad-core-concepts/web-bundles/)** - Use BMAD in Gemini Gems and Custom GPTs
-
----
 
 ## Recommended Reading Paths
 
-### Path 1: Brand New to BMAD (Software Project)
+### Path 1: Brand New to BMad (Software Project)
 
-1. [Core Concepts](./bmad-core-concepts/) - Understand agents and workflows
+1. [README.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/README.md) - Understand the vision
-2. [Installation Guide](./bmad-core-concepts/installing/) - Set up BMAD
+2. [Quick Start Guide](./modules/bmm-bmad-method/quick-start) - Get hands-on
-3. [Quick Start Guide](./modules/bmm-bmad-method/quick-start) - Get hands-on
+3. [BMM Module README](./modules/bmm-bmad-method/) - Understand agents
 4. [BMM Workflows Guide](./modules/bmm-bmad-method/index#-workflow-guides) - Master the methodology
 
 ### Path 2: Game Development Project
 
-1. [Core Concepts](./bmad-core-concepts/) - Understand agents and workflows
+1. [README.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/README.md) - Understand the vision
-2. [Installation Guide](./bmad-core-concepts/installing/) - Set up BMAD
+2. [Quick Start Guide](./modules/bmm-bmad-method/quick-start) - Get hands-on
 3. [BMGD Workflows Guide](./modules/bmgd-bmad-game-dev/workflows-guide) - Game-specific workflows
 
 ### Path 3: Upgrading from v4
 
-1. [v4 to v6 Upgrade Guide](./bmad-core-concepts/installing/upgrading.md) - Understand what changed
+1. [v4 to v6 Upgrade Guide](./v4-to-v6-upgrade.md) - Understand what changed
 2. [Quick Start Guide](./modules/bmm-bmad-method/quick-start) - Reorient yourself
 3. [BMM Workflows Guide](./modules/bmm-bmad-method/index#-workflow-guides) - Learn new v6 workflows
 
@@ -99,13 +95,14 @@ Build your own agents, workflows, and modules.
 2. [Quick Start Guide](./modules/bmm-bmad-method/quick-start) - Follow the process
 3. [BMM Workflows Guide](./modules/bmm-bmad-method/index#-workflow-guides) - Master the methodology
 
-### Path 5: Building Custom Agents
+### Path 5: Building Custom Solutions
 
-1. [Core Concepts: Agents](./bmad-core-concepts/agents.md) - Understand Simple vs Expert
+1. [BMB Module Overview](./modules/bmb-bmad-builder/index) - Understand capabilities
-2. [Agent Creation Guide](./modules/bmb-bmad-builder/agent-creation-guide.md) - Build your first agent
+2. [BMB Custom Content Types](./modules/bmb-bmad-builder/custom-content.md) - Understand the different types and whats possible
-3. [Agent Architecture](./modules/bmb-bmad-builder/index) - Deep technical details
+3. [BMB Content Installation](./modules/bmb-bmad-builder/custom-content-installation.md) - How to bundle install use and share
+4. More Docs coming soon....
 
-### Path 6: Contributing to BMAD
+### Path 6: Contributing to BMad
 
 1. [CONTRIBUTING.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/CONTRIBUTING.md) - Contribution guidelines
 2. Relevant module README - Understand the area you're contributing to

docs/installing-bmad.md

@@ -1,13 +1,5 @@
 # Installation
 
-Get BMAD up and running in your project.
-
-## Upgrading?
-
-If you're upgrading from v4, see the [Upgrade Guide](./upgrading.md).
-
----
-
 ## Quick Install
 
 ```bash
@@ -60,9 +52,8 @@ your-project/
 
 ## Next Steps
 
-1. **Read the [Quick Start Guide](../../modules/bmm-bmad-method/quick-start)** to build your first feature
+1. **Read the [Quick Start Guide](../modules/bmm/quick-start.md)** to build your first feature
-2. **Explore [Workflows](../../modules/bmm-bmad-method/index#-workflow-guides)** to understand the methodology
+2. **Explore [Workflows](../modules/bmm/workflows-planning.md)** to understand the methodology
-3. **Learn about [Agents](../agents.md)** to understand BMAD's core building blocks
 
 ## Troubleshooting
 

docs/modules/bmb-bmad-builder/agent-creation-guide.md

@@ -1,166 +0,0 @@
-# Agent Creation Guide
-
-Create your own custom agents using the BMAD Builder workflow.
-
-## Overview
-
-The BMAD Builder (BMB) module provides an interactive workflow that guides you through creating a custom agent from concept to completion. You define the agent's purpose, personality, capabilities, and menu - then the workflow generates a complete, ready-to-use agent file.
-
-## Before You Start
-
-**Prerequisites:**
-- BMAD installed with the BMB module
-- An idea for what you want your agent to do
-- About 15-30 minutes for your first agent
-
-**Know Before You Go:**
-- What problem should your agent solve?
-- Who will use this agent?
-- What should the agent be able to do?
-
-## Quick Start
-
-### 1. Start the Workflow
-
-In your IDE (Claude Code, Cursor, etc.), invoke the create-agent workflow:
-
-```
-"Run the BMAD Builder create-agent workflow"
-```
-
-Or trigger it via the BMAD Master menu.
-
-### 2. Follow the Steps
-
-The workflow guides you through:
-
-| Step | What You'll Do |
-|------|----------------|
-| **Brainstorm** (optional) | Explore ideas with creative techniques |
-| **Discovery** | Define the agent's purpose and goals |
-| **Type & Metadata** | Choose Simple or Expert, name your agent |
-| **Persona** | Craft the agent's personality and principles |
-| **Commands** | Define what the agent can do |
-| **Activation** | Set up autonomous behaviors (optional) |
-| **Build** | Generate the agent file |
-| **Validation** | Review and verify everything works |
-
-### 3. Install Your Agent
-
-Once created, package your agent for installation:
-
-```
-my-custom-stuff/
-├── module.yaml          # Contains: unitary: true
-├── agents/
-│   └── {agent-name}/
-│       ├── {agent-name}.agent.yaml
-│       └── _memory/              # Expert agents only
-│           └── {sidecar-folder}/
-└── workflows/           # Optional: custom workflows
-```
-
-See [Custom Content Installation](./custom-content-installation.md) for details.
-
-## Choosing Your Agent Type
-
-The workflow will help you decide, but here's the quick reference:
-
-### Choose Simple Agent When:
-
-- Task is well-defined and focused
-- Don't need persistent memory
-- Want fast setup and deployment
-- Single-purpose assistant (e.g., commit messages, code review)
-
-**Example:** A "Code Commenter" that reads files and adds helpful comments.
-
-### Choose Expert Agent When:
-
-- Domain requires specialized knowledge
-- Need persistent memory across sessions
-- Agent coordinates complex workflows
-- Building ongoing project infrastructure
-
-**Example:** A "Security Architect" that remembers your design decisions and maintains security standards across the project.
-
-### Choose Module Agent When:
-
-- Agent builds other agents or workflows
-- Need integration with module system
-- Creating professional tooling
-
-**Example:** A "Team Builder" that helps set up agents for new team members.
-
-## The Persona System
-
-Your agent's personality is defined by four fields:
-
-| Field | Purpose | Example |
-|-------|---------|---------|
-| **Role** | What they do | "Senior code reviewer who catches bugs and suggests improvements" |
-| **Identity** | Who they are | "Friendly but exacting, believes clean code is a craft" |
-| **Communication Style** | How they speak | "Direct, constructive, explains the 'why' behind suggestions" |
-| **Principles** | Why they act | "Security first, clarity over cleverness, test what you fix" |
-
-**Key:** Keep each field focused on its purpose. The role isn't personality; the identity isn't job description.
-
-## Tips for Success
-
-### Start Small
-
-Your first agent should solve **one problem well**. You can always add more capabilities later.
-
-### Learn by Example
-
-Study the reference agents in `src/modules/bmb/reference/agents/`:
-- **Simple:** [commit-poet](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/agents/simple-examples/commit-poet.agent.yaml)
-- **Expert:** [journal-keeper](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/agents/expert-examples/journal-keeper)
-
-### Write Great Principles
-
-The first principle should "activate" the agent's expertise:
-
-❌ **Weak:** "Be helpful and accurate"
-✅ **Strong:** "Channel decades of security expertise: threat modeling begins with trust boundaries, never trust client input, defense in depth is non-negotiable"
-
-### Use the Menu System
-
-The workflow provides options at each step:
-- **[A] Advanced** - Get deeper insights and reasoning
-- **[P] Party** - Get multiple agent perspectives
-- **[C] Continue** - Move to the next step
-
-Use these when you need extra input or creative options.
-
-## After Creation
-
-### Test Your Agent
-
-1. Install your custom module using the BMAD installer
-2. Invoke your new agent in your IDE
-3. Try each menu command
-4. Verify the personality feels right
-
-### Iterate
-
-If something isn't right:
-1. Edit the agent YAML directly, or
-2. Edit the customization file in `_bmad/_config/agents/`
-3. Rebuild using `npx bmad-method build <agent-name>`
-
-### Share
-
-Package your agent as a standalone module (see [Installation Guide](../../bmad-core-concepts/installing/)) and share it with your team or the community.
-
-## Further Reading
-
-- **[Agent Architecture](./index.md)** - Deep technical details on agent types
-- **[Agent Customization](../../bmad-core-concepts/agent-customization/)** - Modify agents without editing core files
-- **[Custom Content Installation](./custom-content-installation.md)** - Package and distribute your agents
-
----
-
-**Ready?** Start the workflow and create your first agent!
-
-[← Back to BMB Documentation](./index.md)

docs/modules/bmb-bmad-builder/index.md

@@ -1,11 +1,6 @@
 # BMB Module Documentation
 
-Create custom agents, workflows, and modules for BMAD.
+Reference documentation for building BMAD agents and workflows.
-
-## Quick Start
-
-- **[Agent Creation Guide](./agent-creation-guide.md)** - Step-by-step guide to building your first agent
-- **[Understanding Agent Types](./understanding-agent-types.md)** - Learn the differences between Simple and Expert agents
 
 ## Agent Architecture
 

docs/modules/bmm-bmad-method/brownfield-guide.md

@@ -1,78 +1,747 @@
 # BMad Method Brownfield Development Guide
 
-## Working on Existing Projects
+**Complete guide for working with existing codebases**
 
-If you have completed your initial PRD on a new project and want to add new features, or if you have a legacy project you are maintaining, you will want to follow the brownfield process.
+**Reading Time:** ~35 minutes
-
-This document is intentionally brief, focusing only on what differs from the standard greenfield flow.
 
 ---
 
-## 1. Clean Up Completed Planning Artifacts
+## Quick Navigation
 
-If you have completed all PRD epics and stories through the BMad process, clean up those files. Archive them, delete them, or rely on version history if needed. Do not keep these files in:
+**Jump to:**
-- `docs/`
-- `_bmad-output/planning-artifacts/`
-- `_bmad-output/implementation-artifacts/`
 
-## 2. Maintain Quality Project Documentation
+- [Quick Reference](#quick-reference) - Commands and files
-
+- [Common Scenarios](#common-scenarios) - Real-world examples
-Your `docs/` folder should contain succinct, well-organized documentation that accurately represents your project:
+- [Best Practices](#best-practices) - Success tips
-- Intent and business rationale
-- Business rules
-- Architecture
-- Any other relevant project information
-
-For complex projects, consider using the `document-project` workflow. It offers runtime variants that will scan your entire project and document its actual current state.
-
-## 3. Initialize for Brownfield Work
-
-Run `workflow-init`. It should recognize you are in an existing project. If not, explicitly clarify that this is brownfield development for a new feature.
-
-### Choosing Your Approach
-
-You have two primary options depending on the scope of changes:
-
-| Scope                          | Recommended Approach                                                                                                          |
-| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
-| **Small updates or additions** | Use `quick-flow-solo-dev` to create a tech-spec and implement the change. The full four-phase BMad method is likely overkill. |
-| **Major changes or additions** | Start with the BMad method, applying as much or as little rigor as needed.                                                    |
-
-### During PRD Creation
-
-When creating a brief or jumping directly into the PRD, ensure the agent:
-- Finds and analyzes your existing project documentation
-- Reads the proper context about your current system
-
-You can guide the agent explicitly, but the goal is to ensure the new feature integrates well with your existing system.
-
-### UX Considerations
-
-UX work is optional. The decision depends not on whether your project has a UX, but on:
-- Whether you will be working on UX changes
-- Whether significant new UX designs or patterns are needed
-
-If your changes amount to simple updates to existing screens you are happy with, a full UX process is unnecessary.
-
-### Architecture Considerations
-
-When doing architecture, ensure the architect:
-- Uses the proper documented files
-- Scans the existing codebase
-
-Pay close attention here to prevent reinventing the wheel or making decisions that misalign with your existing architecture.
 
 ---
 
-## 4. Ad-Hoc Changes
+## What is Brownfield Development?
 
-Not everything requires the full BMad method or even quick-flow. For bug fixes, refactorings, or small targeted changes, simply talk to the agent and have it make the changes directly. This is also a good way to learn about your codebase and understand the modifications being made.
+Brownfield projects involve working within existing codebases rather than starting fresh:
+
+- **Bug fixes** - Single file changes
+- **Small features** - Adding to existing modules
+- **Feature sets** - Multiple related features
+- **Major integrations** - Complex architectural additions
+- **System expansions** - Enterprise-scale enhancements
+
+**Key Difference from Greenfield:** You must understand and respect existing patterns, architecture, and constraints.
+
+**Core Principle:** AI agents need comprehensive documentation to understand existing code before they can effectively plan or implement changes.
 
 ---
 
-## 5. Learn and Explore
+## Getting Started
 
-Remember, LLMs are excellent at interpreting and analyzing code—whether it was AI-generated or not. Use the agent to:
+### Understanding Planning Tracks
-- Learn about your project
+
-- Understand how things are built
+For complete track details, see [Scale Adaptive System](./scale-adaptive-system.md).
-- Explore unfamiliar parts of the codebase
+
+**Brownfield tracks at a glance:**
+
+| Track                 | Scope                      | Typical Stories | Key Difference                                  |
+| --------------------- | -------------------------- | --------------- | ----------------------------------------------- |
+| **Quick Flow**        | Bug fixes, small features  | 1-15            | Must understand affected code and patterns      |
+| **BMad Method**       | Feature sets, integrations | 10-50+          | Integrate with existing architecture            |
+| **Enterprise Method** | Enterprise expansions      | 30+             | Full system documentation + compliance required |
+
+**Note:** Story counts are guidance, not definitions. Tracks are chosen based on planning needs.
+
+### Track Selection for Brownfield
+
+When you run `workflow-init`, it handles brownfield intelligently:
+
+**Step 1: Shows what it found**
+
+- Old planning docs (PRD, epics, stories)
+- Existing codebase
+
+**Step 2: Asks about YOUR work**
+
+> "Are these works in progress, previous effort, or proposed work?"
+
+- **(a) Works in progress** → Uses artifacts to determine level
+- **(b) Previous effort** → Asks you to describe NEW work
+- **(c) Proposed work** → Uses artifacts as guidance
+- **(d) None of these** → You explain your work
+
+**Step 3: Analyzes your description**
+
+- Keywords: "fix", "bug" → Quick Flow, "dashboard", "platform" → BMad Method, "enterprise", "multi-tenant" → Enterprise Method
+- Complexity assessment
+- Confirms suggested track with you
+
+**Key Principle:** System asks about YOUR current work first, uses old artifacts as context only.
+
+**Example: Old Complex PRD, New Simple Work**
+
+```
+System: "Found PRD.md (BMad Method track, 30 stories, 6 months old)"
+System: "Is this work in progress or previous effort?"
+You: "Previous effort - I'm just fixing a bug now"
+System: "Tell me about your current work"
+You: "Update payment method enums"
+System: "Quick Flow track (tech-spec approach). Correct?"
+You: "Yes"
+✅ Creates Quick Flow workflow
+```
+
+---
+
+## Documentation: Critical First Step
+
+🚨 **For brownfield projects: Always ensure adequate AI-usable documentation before planning**
+
+### Default Recommendation: Run document-project
+
+**Best practice:** Run `document-project` workflow unless you have **confirmed, trusted, AI-optimized documentation**.
+
+### Why Document-Project is Almost Always the Right Choice
+
+Existing documentation often has quality issues that break AI workflows:
+
+**Common Problems:**
+
+- **Too Much Information (TMI):** Massive markdown files with 10s or 100s of level 2 sections
+- **Out of Date:** Documentation hasn't been updated with recent code changes
+- **Wrong Format:** Written for humans, not AI agents (lacks structure, index, clear patterns)
+- **Incomplete Coverage:** Missing critical architecture, patterns, or setup info
+- **Inconsistent Quality:** Some areas documented well, others not at all
+
+**Impact on AI Agents:**
+
+- AI agents hit token limits reading massive files
+- Outdated docs cause hallucinations (agent thinks old patterns still apply)
+- Missing structure means agents can't find relevant information
+- Incomplete coverage leads to incorrect assumptions
+
+### Documentation Decision Tree
+
+**Step 1: Assess Existing Documentation Quality**
+
+Ask yourself:
+
+- ✅ Is it **current** (updated in last 30 days)?
+- ✅ Is it **AI-optimized** (structured with index.md, clear sections, <500 lines per file)?
+- ✅ Is it **comprehensive** (architecture, patterns, setup all documented)?
+- ✅ Do you **trust** it completely for AI agent consumption?
+
+**If ANY answer is NO → Run `document-project`**
+
+**Step 2: Check for Massive Documents**
+
+If you have documentation but files are huge (>500 lines, 10+ level 2 sections):
+
+1. **First:** Run `shard-doc` tool to split large files:
+
+   ```bash
+   # Load BMad Master or any agent
+   _bmad/core/tools/shard-doc.xml --input docs/massive-doc.md
+   ```
+
+   - Splits on level 2 sections by default
+   - Creates organized, manageable files
+   - Preserves content integrity
+
+2. **Then:** Run `index-docs` task to create navigation:
+
+   ```bash
+   _bmad/core/tasks/index-docs.xml --directory ./docs
+   ```
+
+3. **Finally:** Validate quality - if sharded docs still seem incomplete/outdated → Run `document-project`
+
+### Four Real-World Scenarios
+
+| Scenario | You Have                                   | Action                     | Why                                     |
+| -------- | ------------------------------------------ | -------------------------- | --------------------------------------- |
+| **A**    | No documentation                           | `document-project`         | Only option - generate from scratch     |
+| **B**    | Docs exist but massive/outdated/incomplete | `document-project`         | Safer to regenerate than trust bad docs |
+| **C**    | Good docs but no structure                 | `shard-doc` → `index-docs` | Structure existing content for AI       |
+| **D**    | Confirmed AI-optimized docs with index.md  | Skip Documentation         | Rare - only if you're 100% confident    |
+
+### Scenario A: No Documentation (Most Common)
+
+**Action: Run document-project workflow**
+
+1. Load Analyst or Technical Writer (Paige) agent
+2. Run `*document-project`
+3. Choose scan level:
+   - **Quick** (2-5min): Pattern analysis, no source reading
+   - **Deep** (10-30min): Reads critical paths - **Recommended**
+   - **Exhaustive** (30-120min): Reads all files
+
+**Outputs:**
+
+- `docs/index.md` - Master AI entry point
+- `docs/project-overview.md` - Executive summary
+- `docs/architecture.md` - Architecture analysis
+- `docs/source-tree-analysis.md` - Directory structure
+- Additional files based on project type (API, web app, etc.)
+
+### Scenario B: Docs Exist But Quality Unknown/Poor (Very Common)
+
+**Action: Run document-project workflow (regenerate)**
+
+Even if `docs/` folder exists, if you're unsure about quality → **regenerate**.
+
+**Why regenerate instead of index?**
+
+- Outdated docs → AI makes wrong assumptions
+- Incomplete docs → AI invents missing information
+- TMI docs → AI hits token limits, misses key info
+- Human-focused docs → Missing AI-critical structure
+
+**document-project** will:
+
+- Scan actual codebase (source of truth)
+- Generate fresh, accurate documentation
+- Structure properly for AI consumption
+- Include only relevant, current information
+
+### Scenario C: Good Docs But Needs Structure
+
+**Action: Shard massive files, then index**
+
+If you have **good, current documentation** but it's in massive files:
+
+**Step 1: Shard large documents**
+
+```bash
+# For each massive doc (>500 lines or 10+ level 2 sections)
+_bmad/core/tools/shard-doc.xml \
+  --input docs/api-documentation.md \
+  --output docs/api/ \
+  --level 2  # Split on ## headers (default)
+```
+
+**Step 2: Generate index**
+
+```bash
+_bmad/core/tasks/index-docs.xml --directory ./docs
+```
+
+**Step 3: Validate**
+
+- Review generated `docs/index.md`
+- Check that sharded files are <500 lines each
+- Verify content is current and accurate
+- **If anything seems off → Run document-project instead**
+
+### Scenario D: Confirmed AI-Optimized Documentation (Rare)
+
+**Action: Skip Documentation**
+
+Only skip if ALL conditions met:
+
+- ✅ `docs/index.md` exists and is comprehensive
+- ✅ Documentation updated within last 30 days
+- ✅ All doc files <500 lines with clear structure
+- ✅ Covers architecture, patterns, setup, API surface
+- ✅ You personally verified quality for AI consumption
+- ✅ Previous AI agents used it successfully
+
+**If unsure → Run document-project** (costs 10-30 minutes, saves hours of confusion)
+
+### Why document-project is Critical
+
+Without AI-optimized documentation, workflows fail:
+
+- **tech-spec** (Quick Flow) can't auto-detect stack/patterns → Makes wrong assumptions
+- **PRD** (BMad Method) can't reference existing code → Designs incompatible features
+- **create-architecture** can't build on existing structure → Suggests conflicting patterns
+- **create-story** can't provide existing pattern context → Stories lack integration guidance
+- **dev-story** invents implementations → Breaks existing integrations
+
+### Key Principle
+
+**When in doubt, run document-project.**
+
+It's better to spend 10-30 minutes generating fresh, accurate docs than to waste hours debugging AI agents working from bad documentation.
+
+---
+
+## Workflow Phases by Track
+
+### Phase 1: Analysis (Optional)
+
+**Workflows:**
+
+- `brainstorm-project` - Solution exploration
+- `research` - Technical/market research
+- `product-brief` - Strategic planning (BMad Method/Enterprise tracks only)
+
+**When to use:** Complex features, technical decisions, strategic additions
+
+**When to skip:** Bug fixes, well-understood features, time-sensitive changes
+
+See the [Workflows section in BMM README](../README.md) for details.
+
+### Phase 2: Planning (Required)
+
+**Planning approach adapts by track:**
+
+**Quick Flow:** Use `tech-spec` workflow
+
+- Creates tech-spec.md
+- Auto-detects existing stack (brownfield)
+- Confirms conventions with you
+- Generates implementation-ready stories
+
+**BMad Method/Enterprise:** Use `prd` workflow
+
+- Creates PRD.md with FRs/NFRs only
+- References existing architecture
+- Plans integration points
+- Epics+Stories created AFTER architecture phase
+
+**Brownfield-specific:** See [Scale Adaptive System](./scale-adaptive-system.md) for complete workflow paths by track.
+
+### Phase 3: Solutioning (BMad Method/Enterprise Only)
+
+**Critical for brownfield:**
+
+- Review existing architecture FIRST
+- Document integration points explicitly
+- Plan backward compatibility
+- Consider migration strategy
+
+**Workflows:**
+
+- `create-architecture` - Extend architecture docs (BMad Method/Enterprise)
+- `create-epics-and-stories` - Create epics and stories AFTER architecture
+- `implementation-readiness` - Validate before implementation (BMad Method/Enterprise)
+
+### Phase 4: Implementation (All Tracks)
+
+**Sprint-based development through story iteration:**
+
+```mermaid
+flowchart TD
+    SPRINT[sprint-planning<br/>Initialize tracking]
+    CREATE[create-story]
+    DEV[dev-story]
+    REVIEW[code-review]
+    CHECK{More stories?}
+    RETRO[retrospective<br/>Per epic]
+
+    SPRINT --> CREATE
+    CREATE --> DEV
+    DEV --> REVIEW
+    REVIEW --> CHECK
+    CHECK -->|Yes| CREATE
+    CHECK -->|No| RETRO
+
+    style SPRINT fill:#bfb,stroke:#333,stroke-width:2px,color:#000
+    style RETRO fill:#fbf,stroke:#333,stroke-width:2px,color:#000
+```
+
+**Status Progression:**
+
+- Epic: `backlog → in-progress → done`
+- Story: `backlog → ready-for-dev → in-progress → review → done`
+
+**Brownfield-Specific Implementation Tips:**
+
+1. **Respect existing patterns** - Follow established conventions
+2. **Test integration thoroughly** - Validate interactions with existing code
+3. **Use feature flags** - Enable gradual rollout
+
+---
+
+## Best Practices
+
+### 1. Always Document First
+
+Even if you know the code, AI agents need `document-project` output for context. Run it before planning.
+
+### 2. Be Specific About Current Work
+
+When workflow-init asks about your work:
+
+- ✅ "Update payment method enums to include Apple Pay"
+- ❌ "Fix stuff"
+
+### 3. Choose Right Documentation Approach
+
+- **Has good docs, no index?** → Run `index-docs` task (fast)
+- **No docs or need codebase analysis?** → Run `document-project` (Deep scan)
+
+### 4. Respect Existing Patterns
+
+Tech-spec and create-story workflows will detect conventions from existing documentation. Follow them unless explicitly modernizing.
+
+### 5. Plan Integration Points Explicitly
+
+Document in tech-spec/architecture:
+
+- Which existing modules you'll modify
+- What APIs/services you'll integrate with
+- How data flows between new and existing code
+
+### 6. Design for Gradual Rollout
+
+- Use feature flags for new functionality
+- Plan rollback strategies
+- Maintain backward compatibility
+- Create migration scripts if needed
+
+### 7. Test Integration Thoroughly
+
+- Regression testing of existing features
+- Integration point validation
+- Performance impact assessment
+- API contract verification
+
+### 8. Use Sprint Planning Effectively
+
+- Run `sprint-planning` at Phase 4 start
+- Context epics before creating stories
+- Update `sprint-status.yaml` as work progresses
+
+### 9. Learn Continuously
+
+- Run `retrospective` after each epic
+- Incorporate learnings into next stories
+- Update discovered patterns
+- Share insights across team
+
+---
+
+## Common Scenarios
+
+### Scenario 1: Bug Fix (Quick Flow)
+
+**Situation:** Authentication token expiration causing logout issues
+
+**Track:** Quick Flow
+
+**Workflow:**
+
+1. **Document:** Skip if auth system documented, else run `document-project` (Quick scan)
+2. **Plan:** Load PM → run `tech-spec`
+   - Analyzes bug
+   - Detects stack (Express, Jest)
+   - Confirms conventions
+   - Creates tech-spec.md + story
+3. **Implement:** Load DEV → run `dev-story`
+4. **Review:** Load DEV → run `code-review`
+
+**Time:** 2-4 hours
+
+---
+
+### Scenario 2: Small Feature (Quick Flow)
+
+**Situation:** Add "forgot password" to existing auth system
+
+**Track:** Quick Flow
+
+**Workflow:**
+
+1. **Document:** Run `document-project` (Deep scan of auth module if not documented)
+2. **Plan:** Load PM → run `tech-spec`
+   - Detects Next.js 13.4, NextAuth.js
+   - Analyzes existing auth patterns
+   - Confirms conventions
+   - Creates tech-spec.md + epic + 3-5 stories
+3. **Implement:** Load SM → `sprint-planning` → `create-story`
+   Load DEV → `dev-story` for each story
+4. **Review:** Load DEV → `code-review`
+
+**Time:** 1-3 days
+
+---
+
+### Scenario 3: Feature Set (BMad Method)
+
+**Situation:** Add user dashboard with analytics, preferences, activity
+
+**Track:** BMad Method
+
+**Workflow:**
+
+1. **Document:** Run `document-project` (Deep scan) - Critical for understanding existing UI patterns
+2. **Analyze:** Load Analyst → `research` (if evaluating analytics libraries)
+3. **Plan:** Load PM → `prd` (creates FRs/NFRs)
+4. **Solution:** Load Architect → `create-architecture` → `create-epics-and-stories` → `implementation-readiness`
+5. **Implement:** Sprint-based (10-15 stories)
+   - Load SM → `sprint-planning`
+   - Load SM → `create-story` per story
+   - Load DEV → `dev-story` per story
+6. **Review:** Per story completion
+
+**Time:** 1-2 weeks
+
+---
+
+### Scenario 4: Complex Integration (BMad Method)
+
+**Situation:** Add real-time collaboration to document editor
+
+**Track:** BMad Method
+
+**Workflow:**
+
+1. **Document:** Run `document-project` (Exhaustive if not documented) - **Mandatory**
+2. **Analyze:** Load Analyst → `research` (WebSocket vs WebRTC vs CRDT)
+3. **Plan:** Load PM → `prd` (creates FRs/NFRs)
+4. **Solution:**
+   - Load Architect → `create-architecture` (extend for real-time layer)
+   - Load Architect → `create-epics-and-stories`
+   - Load Architect → `implementation-readiness`
+5. **Implement:** Sprint-based (20-30 stories)
+
+**Time:** 3-6 weeks
+
+---
+
+### Scenario 5: Enterprise Expansion (Enterprise Method)
+
+**Situation:** Add multi-tenancy to single-tenant SaaS platform
+
+**Track:** Enterprise Method
+
+**Workflow:**
+
+1. **Document:** Run `document-project` (Exhaustive) - **Mandatory**
+2. **Analyze:** **Required**
+   - `brainstorm-project` - Explore multi-tenancy approaches
+   - `research` - Database sharding, tenant isolation, pricing
+   - `product-brief` - Strategic document
+3. **Plan:** Load PM → `prd` (comprehensive FRs/NFRs)
+4. **Solution:**
+   - `create-architecture` - Full system architecture including multi-tenancy design
+   - `create-epics-and-stories` - Create epics and stories
+   - `implementation-readiness` - Final validation before implementation
+5. **Implement:** Phased sprint-based (50+ stories)
+
+**Time:** 3-6 months
+
+---
+
+## Troubleshooting
+
+### AI Agents Lack Codebase Understanding
+
+**Symptoms:**
+
+- Suggestions don't align with existing patterns
+- Ignores available components
+- Doesn't reference existing code
+
+**Solution:**
+
+1. Run `document-project` with Deep scan
+2. Verify `docs/index.md` exists
+3. Check documentation completeness
+4. Run deep-dive on specific areas if needed
+
+### Have Documentation But Agents Can't Find It
+
+**Symptoms:**
+
+- README.md, ARCHITECTURE.md exist
+- AI agents ask questions already answered
+- No `docs/index.md` file
+
+**Solution:**
+
+- **Quick fix:** Run `index-docs` task (2-5min)
+- **Comprehensive:** Run `document-project` workflow (10-30min)
+
+### Integration Points Unclear
+
+**Symptoms:**
+
+- Not sure how to connect new code to existing
+- Unsure which files to modify
+
+**Solution:**
+
+1. Ensure `document-project` captured existing architecture
+2. Check story files created by `create-story` - should include integration context
+3. In tech-spec/architecture - explicitly document:
+   - Which existing modules to modify
+   - What APIs/services to integrate with
+   - Data flow between new and existing code
+4. Review architecture document for integration guidance
+
+### Existing Tests Breaking
+
+**Symptoms:**
+
+- Regression test failures
+- Previously working functionality broken
+
+**Solution:**
+
+1. Review changes against existing patterns
+2. Verify API contracts unchanged (unless intentionally versioned)
+3. Run `test-review` workflow (TEA agent)
+4. Add regression testing to DoD
+5. Consider feature flags for gradual rollout
+
+### Inconsistent Patterns Being Introduced
+
+**Symptoms:**
+
+- New code style doesn't match existing
+- Different architectural approach
+
+**Solution:**
+
+1. Check convention detection (Quick Spec Flow should detect patterns)
+2. Review documentation - ensure `document-project` captured patterns
+3. Use `create-story` workflow - it loads context from existing documentation
+4. Add to code-review checklist: pattern adherence, convention consistency
+5. Run retrospective to identify deviations early
+
+---
+
+## Quick Reference
+
+### Commands by Phase
+
+```bash
+# Documentation (If Needed)
+# Analyst agent:
+document-project        # Create comprehensive docs (10-30min)
+# OR load index-docs task for existing docs (2-5min)
+
+# Phase 1: Analysis (Optional)
+# Analyst agent:
+brainstorm-project      # Explore solutions
+research                # Gather data
+product-brief           # Strategic planning (BMad Method/Enterprise only)
+
+# Phase 2: Planning (Required)
+# PM agent:
+tech-spec               # Quick Flow track
+prd                     # BMad Method/Enterprise tracks
+
+# Phase 3: Solutioning (BMad Method/Enterprise)
+# Architect agent:
+create-architecture          # Create/extend architecture
+create-epics-and-stories     # Create epics and stories (after architecture)
+implementation-readiness     # Final validation
+
+# Phase 4: Implementation (All Tracks)
+# SM agent:
+sprint-planning              # Initialize tracking
+create-story                 # Create story
+
+# DEV agent:
+dev-story                    # Implement
+code-review                  # Review
+
+# SM agent:
+retrospective                # After epic
+correct-course               # If issues
+```
+
+### Key Files
+
+**Documentation Output:**
+
+- `docs/index.md` - **Master AI entry point (REQUIRED)**
+- `docs/project-overview.md`
+- `docs/architecture.md`
+- `docs/source-tree-analysis.md`
+
+**Phase 1-4 Tracking:**
+
+- `docs/bmm-workflow-status.yaml` - Progress tracker
+
+**Phase 2 Planning:**
+
+- `docs/tech-spec.md` (Quick Flow track)
+- `docs/PRD.md` (BMad Method/Enterprise tracks - FRs/NFRs only)
+
+**Phase 3 Solutioning:**
+
+- Epic breakdown (created after architecture)
+
+**Phase 3 Architecture:**
+
+- `docs/architecture.md` (BMad Method/Enterprise tracks)
+- `docs/epics.md` + epic folders (from create-epics-and-stories)
+
+**Phase 4 Implementation:**
+
+- `docs/sprint-status.yaml` - **Single source of truth**
+- `docs/epic-{n}-context.md`
+- `docs/stories/{epic}-{story}-{title}.md`
+- `docs/stories/{epic}-{story}-{title}-context.md`
+
+### Decision Flowchart
+
+```mermaid
+flowchart TD
+    START([Brownfield Project])
+    CHECK{Has docs/<br/>index.md?}
+
+    START --> CHECK
+    CHECK -->|No| DOC[document-project<br/>Deep scan]
+    CHECK -->|Yes| TRACK{What Track?}
+
+    DOC --> TRACK
+
+    TRACK -->|Quick Flow| TS[tech-spec]
+    TRACK -->|BMad Method| PRD[prd → architecture]
+    TRACK -->|Enterprise| PRD2[prd → arch + security/devops]
+
+    TS --> IMPL[Phase 4<br/>Implementation]
+    PRD --> IMPL
+    PRD2 --> IMPL
+
+    style START fill:#f9f,stroke:#333,stroke-width:2px,color:#000
+    style DOC fill:#ffb,stroke:#333,stroke-width:2px,color:#000
+    style IMPL fill:#bfb,stroke:#333,stroke-width:2px,color:#000
+```
+
+---
+
+## Prevention Tips
+
+**Avoid issues before they happen:**
+
+1. ✅ **Always run document-project for brownfield** - Saves context issues later
+2. ✅ **Use fresh chats for complex workflows** - Prevents hallucinations
+3. ✅ **Verify files exist before workflows** - Check PRD, epics, stories present
+4. ✅ **Read agent menu first** - Confirm agent has the workflow
+5. ✅ **Start with simpler track if unsure** - Easy to upgrade (Quick Flow → BMad Method)
+6. ✅ **Keep status files updated** - Manual updates when needed
+7. ✅ **Run retrospectives after epics** - Catch issues early
+8. ✅ **Follow phase sequence** - Don't skip required phases
+
+---
+
+## Related Documentation
+
+- **[Scale Adaptive System](./scale-adaptive-system.md)** - Understanding tracks and complexity
+- **[Quick Spec Flow](./quick-spec-flow.md)** - Fast-track for Quick Flow
+- **[Quick Start Guide](./quick-start.md)** - Getting started with BMM
+- **[Glossary](./glossary.md)** - Key terminology
+- **[FAQ](./faq.md)** - Common questions
+- **[Workflow Documentation](./index.md#-workflow-guides)** - Complete workflow reference
+
+---
+
+## Support and Resources
+
+**Community:**
+
+- [Discord](https://discord.gg/gk8jAdXWmj) - #general-dev, #bugs-issues
+- [GitHub Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues)
+- [YouTube Channel](https://www.youtube.com/@BMadCode)
+
+**Documentation:**
+
+- **[Test Architect Guide](./test-architecture.md)** - Comprehensive testing strategy
+- [BMM Module README](../README.md) - Complete module and workflow reference
+
+---
+
+_Brownfield development is about understanding and respecting what exists while thoughtfully extending it._

docs/modules/bmm-bmad-method/index.md

@@ -40,8 +40,6 @@ First know there is the full BMad Method Process and then there is a Quick Flow
   - Implementation in minutes, not days
   - Has a specialized single agent that does all of this: **[Quick Flow Solo Dev Agent](./quick-flow-solo-dev.md)**
 
-- **TEA engagement (optional)** - Choose TEA engagement: none, TEA-only (standalone), or integrated by track. See **[Test Architect Guide](./test-architecture.md)**.
-
 ## 🤖 Agents and Collaboration
 
 Complete guide to BMM's AI agent team:

docs/modules/bmm-bmad-method/quick-start.md

@@ -179,16 +179,6 @@ Once epics and stories are created:
 
 **Why run this?** It ensures all your planning assets align properly before you start building.
 
-#### Optional: TEA Engagement
-
-Testing is not mandated by BMad. Decide how you want to engage TEA:
-
-- **No TEA** - Use your existing team testing approach
-- **TEA-only (Standalone)** - Use TEA workflows with your own requirements and environment
-- **TEA-integrated** - Use TEA as part of the BMad Method or Enterprise flow
-
-See the [Test Architect Guide](./test-architecture.md) for the five TEA engagement models and recommended sequences.
-
 #### Context Management Tips
 
 - **Use 200k+ context models** for best results (Claude Sonnet 4.5, GPT-4, etc.)
@@ -221,14 +211,7 @@ Once planning and architecture are complete, you'll move to Phase 4. **Important
 3. Tell the agent: "Run dev-story"
 4. The DEV agent will implement the story and update the sprint status
 
-#### 3.4 Generate Guardrail Tests (Optional)
+#### 3.4 Review the Code (Optional but Recommended)
-
-1. **Start a new chat** with the **TEA agent**
-2. Wait for the menu
-3. Tell the agent: "Run automate"
-4. The TEA agent generates or expands tests to act as guardrails
-
-#### 3.5 Review the Code (Optional but Recommended)
 
 1. **Start a new chat** with the **DEV agent**
 2. Wait for the menu
@@ -241,8 +224,7 @@ For each subsequent story, repeat the cycle using **fresh chats** for each workf
 
 1. **New chat** → SM agent → "Run create-story"
 2. **New chat** → DEV agent → "Run dev-story"
-3. **New chat** → TEA agent → "Run automate" (optional)
+3. **New chat** → DEV agent → "Run code-review" (optional but recommended)
-4. **New chat** → DEV agent → "Run code-review" (optional but recommended)
 
 After completing all stories in an epic:
 

docs/modules/bmm-bmad-method/test-architecture.md

@@ -6,38 +6,6 @@
 - **Mission:** Deliver actionable quality strategies, automation coverage, and gate decisions that scale with project complexity and compliance demands.
 - **Use When:** BMad Method or Enterprise track projects, integration risk is non-trivial, brownfield regression risk exists, or compliance/NFR evidence is required. (Quick Flow projects typically don't require TEA)
 
-## Choose Your TEA Engagement Model
-
-BMad does not mandate TEA. There are five valid ways to use it (or skip it). Pick one intentionally.
-
-1. **No TEA**
-   - Skip all TEA workflows. Use your existing team testing approach.
-
-2. **TEA-only (Standalone)**
-   - Use TEA on a non-BMad project. Bring your own requirements, acceptance criteria, and environments.
-   - Typical sequence: `*test-design` (system or epic) -> `*atdd` and/or `*automate` -> optional `*test-review` -> `*trace` for coverage and gate decisions.
-   - Run `*framework` or `*ci` only if you want TEA to scaffold the harness or pipeline.
-
-3. **Integrated: Greenfield - BMad Method (Simple/Standard Work)**
-   - Phase 3: system-level `*test-design`, then `*framework` and `*ci`.
-   - Phase 4: per-epic `*test-design`, optional `*atdd`, then `*automate` and optional `*test-review`.
-   - Gate (Phase 2): `*trace`.
-
-4. **Integrated: Brownfield - BMad Method or Enterprise (Simple or Complex)**
-   - Phase 2: baseline `*trace`.
-   - Phase 3: system-level `*test-design`, then `*framework` and `*ci`.
-   - Phase 4: per-epic `*test-design` focused on regression and integration risks.
-   - Gate (Phase 2): `*trace`; `*nfr-assess` (if not done earlier).
-   - For brownfield BMad Method, follow the same flow with `*nfr-assess` optional.
-
-5. **Integrated: Greenfield - Enterprise Method (Enterprise/Compliance Work)**
-   - Phase 2: `*nfr-assess`.
-   - Phase 3: system-level `*test-design`, then `*framework` and `*ci`.
-   - Phase 4: per-epic `*test-design`, plus `*atdd`/`*automate`/`*test-review`.
-   - Gate (Phase 2): `*trace`; archive artifacts as needed.
-
-If you are unsure, default to the integrated path for your track and adjust later.
-
 ## TEA Workflow Lifecycle
 
 TEA integrates into the BMad development lifecycle during Solutioning (Phase 3) and Implementation (Phase 4):
@@ -48,9 +16,6 @@ graph TB
     subgraph Phase2["<b>Phase 2: PLANNING</b>"]
         PM["<b>PM: *prd (creates PRD with FRs/NFRs)</b>"]
         PlanNote["<b>Business requirements phase</b>"]
-        NFR2["<b>TEA: *nfr-assess (optional, enterprise)</b>"]
-        PM -.-> NFR2
-        NFR2 -.-> PlanNote
         PM -.-> PlanNote
     end
 
@@ -58,8 +23,8 @@ graph TB
         Architecture["<b>Architect: *architecture</b>"]
         EpicsStories["<b>PM/Architect: *create-epics-and-stories</b>"]
         TestDesignSys["<b>TEA: *test-design (system-level)</b>"]
-        Framework["<b>TEA: *framework (optional if needed)</b>"]
+        Framework["<b>TEA: *framework</b>"]
-        CI["<b>TEA: *ci (optional if needed)</b>"]
+        CI["<b>TEA: *ci</b>"]
         GateCheck["<b>Architect: *implementation-readiness</b>"]
         Architecture --> EpicsStories
         Architecture --> TestDesignSys
@@ -209,7 +174,7 @@ npm install -D @seontechnologies/playwright-utils
 
 **Enable during BMAD installation** by answering "Yes" when prompted.
 
-**Supported utilities (10 total):**
+**Supported utilities (11 total):**
 
 - api-request, network-recorder, auth-session, intercept-network-call, recurse
 - log, file-utils, burn-in, network-error-monitor
@@ -464,7 +429,7 @@ Provides fixture-based utilities that integrate into TEA's test generation and r
 
    Benefit: Faster CI feedback, HTTP error detection
 
-**Utilities available** (10 total): api-request, network-recorder, auth-session, intercept-network-call, recurse, log, file-utils, burn-in, network-error-monitor, fixtures-composition
+**Utilities available** (11 total): api-request, network-recorder, auth-session, intercept-network-call, recurse, log, file-utils, burn-in, network-error-monitor, fixtures-composition
 
 **Enable during BMAD installation** by answering "Yes" when prompted, or manually set `tea_use_playwright_utils: true` in `_bmad/bmm/config.yaml`.
 

docs/modules/bmm-bmad-method/workflows-implementation.md

@@ -98,9 +98,8 @@ Stories move through these states in the sprint status file:
 
 1. SM runs `create-story`
 2. DEV runs `dev-story`
-3. (Optional) TEA runs `*automate` to generate or expand guardrail tests
+3. DEV runs `code-review`
-4. DEV runs `code-review`
+4. If code review fails: DEV fixes issues in `dev-story`, then re-runs `code-review`
-5. If code review fails: DEV fixes issues in `dev-story`, then re-runs `code-review`
 
 **After Epic Complete:**
 

docs/modules/bmm-bmad-method/workflows-solutioning.md

@@ -434,7 +434,7 @@ Architecture documents are living. Update them as you learn during implementatio
 
 **Key Difference:** Enterprise adds optional extended workflows AFTER architecture but BEFORE create-epics-and-stories. Everything else is identical to BMad Method.
 
-**Note:** TEA (Test Architect) operates across all phases and validates architecture testability but is not a Phase 3-specific workflow. See [Test Architecture Guide](./test-architecture.md) for TEA's full lifecycle integration.
+**Note:** TEA (Test Architect) operates across all phases and validates architecture testability but is not a Phase 3-specific workflow. See [Test Architecture Guide](../../../../docs/modules/bmm-bmad-method/test-architecture.md) for TEA's full lifecycle integration.
 
 ---
 

docs/v4-to-v6-upgrade.md

@@ -120,7 +120,7 @@ persona:
     - Always upbeat and adventurous
 ```
 
-There is a lot more that is possible with agent customization, which is covered in detail in the [Agent Customization Guide](../bmad-customization/agents.md)
+There is a lot more that is possible with agent customization, which is covered in detail in the [Agent Customization Guide](bmad-customization/agent-customization-guide.md)
 
 CRITICAL NOTE: After you modify the customization file, you need to run the npx installer against your installed location, and choose the option to rebuild all agents, or just do a quick update again. This always builds agents fresh and applies customizations.
 

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

@@ -0,0 +1,21 @@
+# Using BMad Web Bundles in Gemini Gems & Custom GPTs
+
+## IMPORTANT NOTE
+
+The Web Bundling Feature is being rebuilt from the ground up, current bundles found for v6 may be incomplete or missing functionality and are not optimized.
+
+## What Are Web bundles
+
+Web bundles package BMad agents as self-contained files that work in Gemini Gems and Custom GPTs. Everything the agent needs - instructions, workflows, dependencies - is bundled into a single file for easy upload.
+
+## What Are Web Bundles?
+
+Web bundles are standalone files containing:
+
+- Complete agent persona and instructions
+- All workflows and dependencies
+- Interactive menu system
+- Party mode for multi-agent collaboration
+- 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.

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "bmad-method",
-  "version": "6.0.0-alpha.22",
+  "version": "6.0.0-alpha.21",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "bmad-method",
-      "version": "6.0.0-alpha.22",
+      "version": "6.0.0-alpha.21",
       "license": "MIT",
       "dependencies": {
         "@kayvan/markdown-tree-parser": "^1.6.1",

package.json

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

samples/sample-custom-modules/cc-agents-commands/README.md

@@ -1,15 +1,15 @@
 # CC Agents Commands
 
-**Version:** 1.3.0 | **Author:** Ricardo (Autopsias)
+**Version:** 1.2.0 | **Author:** Ricardo (Autopsias)
 
-A curated collection of 53 battle-tested Claude Code extensions designed to help developers **stay in flow**. This module includes 16 slash commands, 35 agents, and 2 skills for workflow automation, testing, CI/CD orchestration, and BMAD development cycles.
+A curated collection of 51 battle-tested Claude Code extensions designed to help developers **stay in flow**. This module includes 18 slash commands, 31 agents, and 2 skills for workflow automation, testing, CI/CD orchestration, and BMAD development cycles.
 
 ## Contents
 
 | Type | Count | Description |
 |------|-------|-------------|
-| **Commands** | 16 | Slash commands for workflows (`/pr`, `/ci-orchestrate`, etc.) |
+| **Commands** | 18 | Slash commands for workflows (`/pr`, `/ci-orchestrate`, etc.) |
-| **Agents** | 35 | Specialized agents for testing, quality, BMAD, and automation |
+| **Agents** | 31 | Specialized agents for testing, quality, BMAD, and automation |
 | **Skills** | 2 | Reusable skill definitions (PR workflows, safe refactoring) |
 
 ## Installation
@@ -52,8 +52,8 @@ cp -r skills/ .claude/skills/
 |---------|-------------|---------------|
 | `/epic-dev` | Automates BMAD development cycle | BMAD framework |
 | `/epic-dev-full` | Full TDD/ATDD-driven BMAD development | BMAD framework |
-| `/epic-dev-epic-end-tests` | Validates epic completion with NFR assessment | BMAD framework |
 | `/parallel` | Smart parallelization with conflict detection | - |
+| `/parallelize` | Strategy-based parallelization | - |
 
 ### Quality Gates
 | Command | Description | Prerequisites |
@@ -62,7 +62,6 @@ cp -r skills/ .claude/skills/
 | `/test-orchestrate` | Orchestrates test failure analysis | test files |
 | `/code-quality` | Analyzes and fixes code quality issues | - |
 | `/coverage` | Orchestrates test coverage improvement | coverage tools |
-| `/create-test-plan` | Creates comprehensive test plans | project documentation |
 
 ### Shipping
 | Command | Description | Prerequisites |
@@ -70,13 +69,6 @@ cp -r skills/ .claude/skills/
 | `/pr` | Manages pull request workflows | `github` MCP |
 | `/commit-orchestrate` | Git commit with quality checks | - |
 
-### Testing
-| Command | Description | Prerequisites |
-|---------|-------------|---------------|
-| `/test-epic-full` | Tests epic-dev-full command workflow | BMAD framework |
-| `/user-testing` | Facilitates user testing sessions | user testing setup |
-| `/usertestgates` | Finds and runs next test gate | test gates in project |
-
 ## Agents Reference
 
 ### Test Fixers
@@ -94,7 +86,6 @@ cp -r skills/ .claude/skills/
 | `type-error-fixer` | Fixes type errors and annotations |
 | `import-error-fixer` | Fixes import and dependency errors |
 | `security-scanner` | Scans for security vulnerabilities |
-| `code-quality-analyzer` | Analyzes code quality issues |
 
 ### Workflow Support
 | Agent | Description |
@@ -102,7 +93,6 @@ cp -r skills/ .claude/skills/
 | `pr-workflow-manager` | Manages PR workflows via GitHub |
 | `parallel-orchestrator` | Spawns parallel agents with conflict detection |
 | `digdeep` | Five Whys root cause analysis |
-| `safe-refactor` | Test-safe file refactoring with validation |
 
 ### BMAD Workflow
 | Agent | Description |
@@ -110,10 +100,7 @@ cp -r skills/ .claude/skills/
 | `epic-story-creator` | Creates user stories from epics |
 | `epic-story-validator` | Validates stories and quality gates |
 | `epic-test-generator` | Generates ATDD tests |
-| `epic-atdd-writer` | Generates failing acceptance tests (TDD RED phase) |
 | `epic-implementer` | Implements stories (TDD GREEN phase) |
-| `epic-test-expander` | Expands test coverage after implementation |
-| `epic-test-reviewer` | Reviews test quality against best practices |
 | `epic-code-reviewer` | Adversarial code review |
 
 ### CI/DevOps
@@ -130,18 +117,6 @@ cp -r skills/ .claude/skills/
 | `chrome-browser-executor` | Chrome-specific automation |
 | `playwright-browser-executor` | Playwright-specific automation |
 
-### Testing Support
-| Agent | Description |
-|-------|-------------|
-| `test-strategy-analyst` | Strategic test failure analysis |
-| `test-documentation-generator` | Generates test failure runbooks |
-| `validation-planner` | Plans validation scenarios |
-| `scenario-designer` | Designs test scenarios |
-| `ui-test-discovery` | Discovers UI test opportunities |
-| `requirements-analyzer` | Analyzes project requirements |
-| `evidence-collector` | Collects validation evidence |
-| `interactive-guide` | Guides human testers through validation |
-
 ## Skills Reference
 
 | Skill | Description | Prerequisites |

samples/sample-custom-modules/cc-agents-commands/agents/browser-executor.md

@@ -1,7 +1,7 @@
 ---
 name: browser-executor
 description: Browser automation agent that executes test scenarios using Chrome DevTools MCP integration with enhanced automation capabilities including JavaScript evaluation, network monitoring, and multi-page support.
-tools: Read, Write, Grep, Glob, mcp__chrome-devtools__navigate_page, mcp__chrome-devtools__take_snapshot, mcp__chrome-devtools__click, mcp__chrome-devtools__fill, mcp__chrome-devtools__take_screenshot, mcp__chrome-devtools__wait_for, mcp__chrome-devtools__list_console_messages, mcp__chrome-devtools__list_network_requests, mcp__chrome-devtools__evaluate_script, mcp__chrome-devtools__fill_form, mcp__chrome-devtools__list_pages, mcp__chrome-devtools__drag, mcp__chrome-devtools__hover, mcp__chrome-devtools__select_option, mcp__chrome-devtools__upload_file, mcp__chrome-devtools__handle_dialog, mcp__chrome-devtools__resize_page, mcp__chrome-devtools__select_page, mcp__chrome-devtools__new_page, mcp__chrome-devtools__close_page
+tools: Read, Write, Grep, Glob, mcp**chrome-devtools**navigate_page, mcp**chrome-devtools**take_snapshot, mcp**chrome-devtools**click, mcp**chrome-devtools**fill, mcp**chrome-devtools**take_screenshot, mcp**chrome-devtools**wait_for, mcp**chrome-devtools**list_console_messages, mcp**chrome-devtools**list_network_requests, mcp**chrome-devtools**evaluate_script, mcp**chrome-devtools**fill_form, mcp**chrome-devtools**list_pages, mcp**chrome-devtools**drag, mcp**chrome-devtools**hover, mcp**chrome-devtools**select_option, mcp**chrome-devtools**upload_file, mcp**chrome-devtools**handle_dialog, mcp**chrome-devtools**resize_page, mcp**chrome-devtools**select_page, mcp**chrome-devtools**new_page, mcp**chrome-devtools**close_page
 model: haiku
 color: blue
 ---
@@ -11,6 +11,7 @@ color: blue
 You are a specialized browser automation agent that executes test scenarios using Chrome DevTools MCP integration. You capture evidence at validation checkpoints, collect performance data, monitor network activity, and generate structured execution logs for the BMAD testing framework.
 
 ## CRITICAL EXECUTION INSTRUCTIONS
+
 🚨 **MANDATORY**: You are in EXECUTION MODE. Perform actual browser actions using Chrome DevTools MCP tools.
 🚨 **MANDATORY**: Verify browser interactions by taking screenshots after each major action.
 🚨 **MANDATORY**: Create actual test evidence files using Write tool for execution logs.
@@ -35,22 +36,25 @@ Load and follow the complete browser_tester template workflow. This template inc
 ## Core Capabilities
 
 ### Enhanced Browser Automation
-- Navigate using `mcp__chrome-devtools__navigate_page`
+
-- Capture accessibility snapshots with `mcp__chrome-devtools__take_snapshot`
+- Navigate using `mcp**chrome-devtools**navigate_page`
-- Advanced interactions via `mcp__chrome-devtools__click`, `mcp__chrome-devtools__fill`
+- Capture accessibility snapshots with `mcp**chrome-devtools**take_snapshot`
-- Batch form filling with `mcp__chrome-devtools__fill_form`
+- Advanced interactions via `mcp**chrome-devtools**click`, `mcp**chrome-devtools**fill`
-- Multi-page management with `mcp__chrome-devtools__list_pages`, `mcp__chrome-devtools__select_page`
+- Batch form filling with `mcp**chrome-devtools**fill_form`
-- JavaScript execution with `mcp__chrome-devtools__evaluate_script`
+- Multi-page management with `mcp**chrome-devtools**list_pages`, `mcp**chrome-devtools**select_page`
-- Dialog handling with `mcp__chrome-devtools__handle_dialog`
+- JavaScript execution with `mcp**chrome-devtools**evaluate_script`
+- Dialog handling with `mcp**chrome-devtools**handle_dialog`
 
 ### Advanced Evidence Collection
-- Full-page and element-specific screenshots via `mcp__chrome-devtools__take_screenshot`
+
+- Full-page and element-specific screenshots via `mcp**chrome-devtools**take_screenshot`
 - Accessibility data for LLM-friendly validation
-- Network request monitoring and performance data via `mcp__chrome-devtools__list_network_requests`
+- Network request monitoring and performance data via `mcp**chrome-devtools**list_network_requests`
-- Console message capture and analysis via `mcp__chrome-devtools__list_console_messages`
+- Console message capture and analysis via `mcp**chrome-devtools**list_console_messages`
 - JavaScript execution results
 
 ### Performance Monitoring
+
 - Network request timing and analysis
 - Page load performance metrics
 - JavaScript execution performance
@@ -71,4 +75,4 @@ Follow the complete workflow defined in the browser_tester template, generating
 
 ---
 
-*This agent operates independently via Task tool spawning with 200k context. All coordination happens through structured file exchange following the BMAD testing framework file communication protocol.*
+_This agent operates independently via Task tool spawning with 200k context. All coordination happens through structured file exchange following the BMAD testing framework file communication protocol._

samples/sample-custom-modules/cc-agents-commands/agents/ci-documentation-generator.md

@@ -2,6 +2,7 @@
 name: ci-documentation-generator
 description: |
   Generates CI documentation including runbooks and strategy docs. Use when:
+
   - Strategic analysis completes and needs documentation
   - User requests "--docs" flag on /ci_orchestrate
   - CI improvements need to be documented for team reference
@@ -33,6 +34,7 @@ You are a **technical documentation specialist** for CI/CD systems. You transfor
 ## Your Mission
 
 Create and maintain CI documentation that:
+
 1. Provides quick reference for common CI failures
 2. Documents the CI/CD strategy and architecture
 3. Stores learnings for future reference (knowledge extraction)
@@ -41,11 +43,17 @@ Create and maintain CI documentation that:
 ## Output Locations
 
 | Document Type | Location | Purpose |
+
 | -------------- | ---------- | --------- |
+
 | Failure Runbook | `docs/ci-failure-runbook.md` | Quick troubleshooting reference |
+
 | CI Strategy | `docs/ci-strategy.md` | Long-term CI approach |
+
 | Failure Patterns | `docs/ci-knowledge/failure-patterns.md` | Known issues and resolutions |
+
 | Prevention Rules | `docs/ci-knowledge/prevention-rules.md` | Best practices applied |
+
 | Success Metrics | `docs/ci-knowledge/success-metrics.md` | What worked for issues |
 
 ## Document Templates
@@ -53,6 +61,7 @@ Create and maintain CI documentation that:
 ### CI Failure Runbook Template
 
 ```markdown
+
 # CI Failure Runbook
 
 Quick reference for diagnosing and resolving CI failures.
@@ -60,9 +69,13 @@ Quick reference for diagnosing and resolving CI failures.
 ## Quick Reference
 
 | Failure Pattern | Likely Cause | Quick Fix |
+
 | ----------------- | -------------- | ----------- |
+
 | `ENOTEMPTY` on pnpm | Stale pnpm directories | Re-run job (cleanup action) |
+
 | `TimeoutError` in async | Timing too aggressive | Increase timeouts |
+
 | `APIConnectionError` | Missing mock | Check auto_mock fixture |
 
 ---
@@ -72,55 +85,71 @@ Quick reference for diagnosing and resolving CI failures.
 ### 1. [Category Name]
 
 #### Symptoms
+
 - Error message patterns
 - When this typically occurs
 
 #### Root Cause
+
 - Technical explanation
 
 #### Solution
+
 - Step-by-step fix
 - Code examples if applicable
 
 #### Prevention
+
 - How to avoid in future
-```
+
+```text
 
 ### CI Strategy Template
 
 ```markdown
+
 # CI/CD Strategy
 
 ## Executive Summary
+
 - Tech stack overview
 - Key challenges addressed
 - Target performance metrics
 
 ## Root Cause Analysis
+
 - Issues identified
 - Five Whys applied
 - Systemic fixes implemented
 
 ## Pipeline Architecture
+
 - Stage diagram
 - Timing targets
 - Quality gates
 
 ## Test Categorization
+
 | Marker | Description | Expected Duration |
+
 | -------- | ------------- | ------------------- |
+
 | unit | Fast, mocked | <1s |
+
 | integration | Real services | 1-10s |
 
 ## Prevention Checklist
+
 - [ ] Pre-push checks
 - [ ] CI-friendly timeouts
 - [ ] Mock isolation
-```
+
+```text
 
 ### Knowledge Extraction Template
 
 ```markdown
+
 # CI Knowledge: [Category]
 
 ## Failure Pattern: [Name]
@@ -130,10 +159,12 @@ Quick reference for diagnosing and resolving CI failures.
 **Affected Files:** [list]
 
 ### Symptoms
+
 - Error messages
 - Conditions when it occurs
 
 ### Root Cause (Five Whys)
+
 1. Why? →
 2. Why? →
 3. Why? →
@@ -141,17 +172,21 @@ Quick reference for diagnosing and resolving CI failures.
 5. Why? → [ROOT CAUSE]
 
 ### Solution Applied
+
 - What was done
 - Code/config changes
 
 ### Verification
+
 - How to confirm fix worked
 - Commands to run
 
 ### Prevention
+
 - How to avoid recurrence
 - Checklist items added
-```
+
+```text
 
 ## Documentation Style
 
@@ -174,24 +209,33 @@ Quick reference for diagnosing and resolving CI failures.
 After generating documentation:
 
 ```bash
+
 # Check docs exist
+
 ls -la docs/ci-*.md docs/ci-knowledge/ 2>/dev/null
 
 # Verify markdown is valid (no broken links)
-grep -r "\[.*\](.*)" docs/ci-* | head -10
+
-```
+grep -r "\[._\](._)" docs/ci-* | head -10
+
+```text
 
 ## Output Format
 
 ### Documents Created/Updated
+
 | Document | Action | Key Additions |
+
 | ---------- | -------- | --------------- |
+
 | [path] | Created/Updated | [summary of content] |
 
 ### Knowledge Captured
+
 - Failure patterns documented: X
 - Prevention rules added: Y
 - Success metrics recorded: Z
 
 ### Cross-References Added
+
 - [Doc A] ↔ [Doc B]: [relationship]

samples/sample-custom-modules/cc-agents-commands/agents/ci-infrastructure-builder.md

@@ -2,6 +2,7 @@
 name: ci-infrastructure-builder
 description: |
   Creates CI infrastructure improvements. Use when strategic analysis identifies:
+
   - Need for reusable GitHub Actions
   - pytest/vitest configuration improvements
   - CI workflow optimizations
@@ -36,6 +37,7 @@ You are a **CI infrastructure specialist**. You create robust, reusable CI/CD in
 ## Your Mission
 
 Transform CI recommendations from the strategy analyst into working infrastructure:
+
 1. Create reusable GitHub Actions
 2. Update test configurations for reliability
 3. Add CI-specific plugins and dependencies
@@ -48,7 +50,9 @@ Transform CI recommendations from the strategy analyst into working infrastructu
 Create reusable actions in `.github/actions/`:
 
 ```yaml
+
 # Example: .github/actions/cleanup-runner/action.yml
+
 name: 'Cleanup Self-Hosted Runner'
 description: 'Cleans up runner state to prevent cross-job contamination'
 
@@ -64,16 +68,19 @@ inputs:
 runs:
   using: 'composite'
   steps:
+
     - name: Kill stale processes
       shell: bash
       run: |
         pkill -9 -f "uvicorn" 2>/dev/null || true
         pkill -9 -f "vite" 2>/dev/null || true
-```
+
+```text
 
 ### 2. CI Workflow Updates
 
 Modify workflows in `.github/workflows/`:
+
 - Add cleanup steps at job start
 - Configure shard-specific ports for parallel E2E
 - Add timeout configurations
@@ -84,34 +91,43 @@ Modify workflows in `.github/workflows/`:
 Update test configurations for CI reliability:
 
 **pytest.ini improvements:**
+
 ```ini
+
 # CI reliability: prevents hanging tests
+
 timeout = 60
 timeout_method = signal
 
 # CI reliability: retry flaky tests
+
 reruns = 2
 reruns_delay = 1
 
 # Test categorization for selective CI execution
+
 markers =
     unit: Fast tests, no I/O
     integration: Uses real services
     flaky: Quarantined for investigation
-```
+
+```text
 
 **pyproject.toml dependencies:**
+
 ```toml
 [project.optional-dependencies]
 dev = [
     "pytest-timeout>=2.3.1",
     "pytest-rerunfailures>=14.0",
 ]
-```
+
+```text
 
 ### 4. Cleanup Scripts
 
 Create cleanup mechanisms for self-hosted runners:
+
 - Process cleanup (stale uvicorn, vite, node)
 - Cache cleanup (pnpm stores, pip caches)
 - Test artifact cleanup (database files, playwright artifacts)
@@ -129,35 +145,50 @@ Create cleanup mechanisms for self-hosted runners:
 Before completing, verify:
 
 ```bash
+
 # Check GitHub Actions syntax
+
 cat .github/workflows/ci.yml | head -50
 
 # Verify pytest.ini configuration
+
 cat apps/api/pytest.ini
 
 # Check pyproject.toml for dependencies
+
 grep -A 5 "pytest-timeout\|pytest-rerunfailures" apps/api/pyproject.toml
-```
+
+```text
 
 ## Output Format
 
 After creating infrastructure:
 
 ### Created Files
+
 | File | Purpose | Key Features |
+
 | ------ | --------- | -------------- |
+
 | [path] | [why created] | [what it does] |
 
 ### Modified Files
+
 | File | Changes | Reason |
+
 | ------ | --------- | -------- |
+
 | [path] | [what changed] | [why] |
 
 ### Verification Commands
+
 ```bash
+
 # Commands to verify the infrastructure works
-```
+
+```text
 
 ### Next Steps
+
 - [ ] What the orchestrator should do next
 - [ ] Any manual steps required

samples/sample-custom-modules/cc-agents-commands/agents/ci-strategy-analyst.md

@@ -2,6 +2,7 @@
 name: ci-strategy-analyst
 description: |
   Strategic CI/CD analysis with research capabilities. Use PROACTIVELY when:
+
   - CI failures recur 3+ times on same branch without resolution
   - User explicitly requests "strategic", "comprehensive", or "root cause" analysis
   - Tactical fixes aren't resolving underlying issues
@@ -33,6 +34,7 @@ You are a **strategic CI/CD analyst**. Your role is to identify **systemic issue
 ## Your Mission
 
 Transform reactive CI firefighting into proactive prevention by:
+
 1. Researching best practices for the project's tech stack
 2. Analyzing patterns in git history for recurring failures
 3. Performing Five Whys root cause analysis
@@ -43,13 +45,17 @@ Transform reactive CI firefighting into proactive prevention by:
 Use web search to find current best practices for the project's technology stack:
 
 ```bash
+
 # Identify project stack first
+
 cat apps/api/pyproject.toml 2>/dev/null | head -30
 cat apps/web/package.json 2>/dev/null | head -30
 cat .github/workflows/ci.yml 2>/dev/null | head -50
-```
+
+```text
 
 Research topics based on stack (use WebSearch):
+
 - pytest-xdist parallel test execution best practices
 - GitHub Actions self-hosted runner best practices
 - Async test timing and timeout strategies
@@ -60,25 +66,33 @@ Research topics based on stack (use WebSearch):
 Analyze commit history for recurring CI-related fixes:
 
 ```bash
+
 # Find "fix CI" pattern commits
+
 git log --oneline -50 | grep -iE "(fix|ci|test|lint|type)" | head -20
 
 # Count frequency of CI fix commits
+
 git log --oneline -100 | grep -iE "fix.*(ci|test|lint)" | wc -l
 
 # Find most-touched test files (likely flaky)
+
 git log --oneline --name-only -50 | grep "test_" | sort | uniq -c | sort -rn | head -10
 
 # Recent CI workflow changes
+
 git log --oneline -20 -- .github/workflows/
-```
+
+```text
 
 ## Phase 3: Root Cause Analysis (Five Whys)
 
 For each major recurring issue, apply the Five Whys methodology:
 
-```
+```text
+
 Issue: [Describe the symptom]
+
 1. Why does this fail? → [First-level cause]
 2. Why does [first cause] happen? → [Second-level cause]
 3. Why does [second cause] occur? → [Third-level cause]
@@ -87,35 +101,46 @@ Issue: [Describe the symptom]
 
 Root Cause: [The systemic issue to fix]
 Recommended Fix: [Structural change, not just symptom treatment]
-```
+
+```text
 
 ## Phase 4: Strategic Recommendations
 
 Produce prioritized recommendations using this format:
 
 ### Research Findings
+
 | Best Practice | Source | Applicability | Priority |
+
 | -------------- | -------- | --------------- | ---------- |
+
 | [Practice 1] | [URL/Source] | [How it applies] | High/Med/Low |
 
 ### Recurring Failure Patterns
+
 | Pattern | Frequency | Files Affected | Root Cause |
+
 | --------- | ----------- | ---------------- | ------------ |
+
 | [Pattern 1] | X times in last month | [files] | [cause] |
 
 ### Root Cause Analysis Summary
+
 For each major issue:
+
 - **Issue**: [description]
 - **Five Whys Chain**: [summary]
 - **Root Cause**: [the real problem]
 - **Strategic Fix**: [not a band-aid]
 
 ### Prioritized Recommendations
+
 1. **[Highest Impact]**: [Action] - [Expected outcome]
 2. **[Second Priority]**: [Action] - [Expected outcome]
 3. **[Third Priority]**: [Action] - [Expected outcome]
 
 ### Infrastructure Recommendations
+
 - [ ] GitHub Actions improvements needed
 - [ ] pytest configuration changes
 - [ ] Test fixture improvements
@@ -126,27 +151,9 @@ For each major issue:
 Think hard about the root causes before proposing solutions. Symptoms are tempting to fix, but they'll recur unless you address the underlying cause.
 
 Your output will be used by:
+
 - `ci-infrastructure-builder` agent to create GitHub Actions and configs
 - `ci-documentation-generator` agent to create runbooks
 - The main orchestrator to decide next steps
 
 Be specific and actionable. Vague recommendations like "improve test quality" are not helpful.
-
-## MANDATORY JSON OUTPUT FORMAT
-
-🚨 **CRITICAL**: In addition to your detailed analysis, you MUST include this JSON summary at the END of your response:
-
-```json
-{
-  "status": "complete",
-  "root_causes_found": 3,
-  "patterns_identified": ["flaky_tests", "missing_cleanup", "race_conditions"],
-  "recommendations_count": 5,
-  "priority_fixes": ["Add pytest-xdist isolation", "Configure cleanup hooks"],
-  "infrastructure_changes_needed": true,
-  "documentation_updates_needed": true,
-  "summary": "Identified 3 root causes of recurring CI failures with 5 prioritized fixes"
-}
-```
-
-**This JSON is required for orchestrator coordination and token efficiency.**

samples/sample-custom-modules/cc-agents-commands/agents/digdeep.md

@@ -1,7 +1,8 @@
 ---
 name: digdeep
-description: Advanced analysis and root cause investigation using Five Whys methodology with deep research capabilities. Analysis-only agent that never executes code.
+description: "Investigates root causes using Five Whys analysis"
-tools: Read, Grep, Glob, SlashCommand, mcp__exa__web_search_exa, mcp__exa__deep_researcher_start, mcp__exa__deep_researcher_check, mcp__perplexity-ask__perplexity_ask, mcp__exa__crawling_exa, mcp__ref__ref_search_documentation, mcp__ref__ref_read_url, mcp__semgrep-hosted__security_check, mcp__semgrep-hosted__semgrep_scan, mcp__semgrep-hosted__get_abstract_syntax_tree, mcp__ide__getDiagnostics
+prerequisites: "`perplexity-ask` MCP"
+tools: Read, Grep, Glob, SlashCommand, mcp**exa**web_search_exa, mcp**exa**deep_researcher_start, mcp**exa**deep_researcher_check, mcp**perplexity-ask**perplexity_ask, mcp**exa**company_research_exa, mcp**exa**crawling_exa, mcp**exa**linkedin_search_exa, mcp**ref**ref_search_documentation, mcp**ref**ref_read_url, mcp**grep**searchGitHub, mcp**semgrep-hosted**semgrep_rule_schema, mcp**semgrep-hosted**get_supported_languages, mcp**semgrep-hosted**semgrep_scan_with_custom_rule, mcp**semgrep-hosted**semgrep_scan, mcp**semgrep-hosted**security_check, mcp**semgrep-hosted**get_abstract_syntax_tree, mcp**ide**getDiagnostics, mcp**ide**executeCode, mcp**browsermcp**browser_navigate, mcp**browsermcp**browser_go_back, mcp**browsermcp**browser_go_forward, mcp**browsermcp**browser_snapshot, mcp**browsermcp**browser_click, mcp**browsermcp**browser_hover, mcp**browsermcp**browser_type, mcp**browsermcp**browser_select_option, mcp**browsermcp**browser_press_key, mcp**browsermcp**browser_wait, mcp**browsermcp**browser_get_console_logs, mcp**browsermcp**browser_screenshot
 model: opus
 color: purple
 ---
@@ -13,12 +14,14 @@ You are a specialized deep analysis agent focused on systematic investigation an
 ## Core Constraints
 
 **ANALYSIS ONLY - NO EXECUTION:**
+
 - NEVER use Bash, Edit, Write, or any execution tools
 - NEVER attempt to fix, modify, or change any code
 - ALWAYS focus on investigation, analysis, and research
 - ALWAYS provide recommendations for separate implementation
 
 **INVESTIGATION PRINCIPLES:**
+
 - START investigating immediately when users ask for debugging help
 - USE systematic Five Whys methodology for all investigations
 - ACTIVATE UltraThink automatically for complex multi-domain problems
@@ -32,18 +35,21 @@ You are a specialized deep analysis agent focused on systematic investigation an
 When users say these phrases, start deep analysis immediately:
 
 **Direct Debugging Requests:**
+
 - "debug this" → Start Five Whys analysis now
 - "what's wrong" → Begin immediate investigation
 - "why is this broken" → Launch root cause analysis
 - "find the problem" → Start systematic investigation
 
 **Analysis Requests:**
+
 - "investigate" → Begin comprehensive analysis
 - "analyze this issue" → Start detailed investigation
 - "root cause analysis" → Apply Five Whys methodology
 - "analyze deeply" → Activate enhanced investigation mode
 
 **Complex Problem Indicators:**
+
 - "mysterious problem" → Auto-activate UltraThink
 - "can't figure out" → Use enhanced analysis mode
 - "complex system failure" → Enable deep investigation
@@ -54,6 +60,7 @@ When users say these phrases, start deep analysis immediately:
 ### Automatic UltraThink Triggers
 
 **Auto-Activate UltraThink when detecting:**
+
 - **Multi-Domain Complexity**: Issues spanning 3+ domains (security + performance + infrastructure)
 - **System-Wide Failures**: Problems affecting multiple services/components
 - **Architectural Issues**: Deep structural or design problems
@@ -61,6 +68,7 @@ When users say these phrases, start deep analysis immediately:
 - **Complex Integration Failures**: Multi-service or API interaction problems
 
 **Complexity Detection Keywords:**
+
 - "system" + "failure" + "multiple" → Auto UltraThink
 - "complex" + "problem" + "integration" → Auto UltraThink
 - "mysterious" + "bug" + "can't figure out" → Auto UltraThink
@@ -93,26 +101,31 @@ When UltraThink activates:
 ### Investigation Progression
 
 #### Level 1: Immediate Analysis
+
 - **Action**: Examine reported issue using Read and Grep
 - **Focus**: Direct symptoms and immediate causes
 - **Tools**: Read, Grep for specific files/patterns
 
 #### Level 2: Pattern Detection
+
 - **Action**: Search for similar patterns across codebase
 - **Focus**: Recurring issues and broader symptom patterns
 - **Tools**: Glob for file patterns, Grep for code patterns
 
 #### Level 3: Systemic Investigation
+
 - **Action**: Analyze architecture and system design
 - **Focus**: Structural causes and design decisions
 - **Tools**: Read multiple related files, analyze relationships
 
 #### Level 4: External Research
+
 - **Action**: Research similar problems and industry solutions
 - **Focus**: Best practices and external knowledge
 - **Tools**: MCP web search and Perplexity for expert insights
 
 #### Level 5: Comprehensive Synthesis
+
 - **Action**: Integrate all findings into root cause conclusion
 - **Focus**: Fundamental issue requiring systematic resolution
 - **Tools**: All findings synthesized with actionable recommendations
@@ -122,28 +135,40 @@ When UltraThink activates:
 ### Progressive Research Strategy
 
 **Phase 1: Quick Research (Perplexity)**
-```
+
+```text
+
 Use for immediate expert insights:
+
 - "What causes [specific error pattern]?"
 - "Best practices for [technology/pattern]?"
 - "Common solutions to [problem type]?"
-```
+
+```text
 
 **Phase 2: Web Search (EXA)**
-```
+
+```text
+
 Use for documentation and examples:
+
 - Find official documentation
 - Locate similar bug reports
 - Search for implementation examples
-```
+
+```text
 
 **Phase 3: Deep Research (EXA Deep Researcher)**
-```
+
+```text
+
 Use for comprehensive analysis:
+
 - Complex architectural problems
 - Multi-technology integration issues
 - Industry patterns and solutions
-```
+
+```text
 
 ### Circuit Breaker Protection
 
@@ -161,40 +186,51 @@ Use for comprehensive analysis:
 ### MCP Usage Patterns
 
 **For Quick Clarification:**
+
 ```python
-mcp__perplexity-ask__perplexity_ask({
+mcp**perplexity-ask**perplexity_ask({
     "messages": [{"role": "user", "content": "Explain [specific technical concept] and common pitfalls"}]
 })
-```
+
+```text
 
 **For Documentation Research:**
+
 ```python
-mcp__exa__web_search_exa({
+mcp**exa**web_search_exa({
     "query": "[technology] [error pattern] documentation solutions",
     "numResults": 5
 })
-```
+
+```text
 
 **For Comprehensive Investigation:**
+
 ```python
+
 # Start deep research
-task_id = mcp__exa__deep_researcher_start({
+
+task_id = mcp**exa**deep_researcher_start({
     "instructions": "Analyze [complex problem] including architecture patterns, common solutions, and prevention strategies",
     "model": "exa-research"
 })
 
 # Check results
-mcp__exa__deep_researcher_check({"taskId": task_id})
+
-```
+mcp**exa**deep_researcher_check({"taskId": task_id})
+
+```text
 
 ## Analysis Output Framework
 
 ### Standard Analysis Report Structure
 
 ```markdown
+
 ## Root Cause Analysis Report
 
 ### Problem Statement
+
 **Issue**: [User's reported problem]
 **Complexity Level**: [Simple/Medium/Complex/Ultra-Complex]
 **Analysis Method**: [Standard Five Whys/UltraThink Enhanced]
@@ -225,17 +261,21 @@ mcp__exa__deep_researcher_check({"taskId": task_id})
 - **Evidence**: [All findings integrated]
 
 ### Research Findings
+
 [If MCP tools were used, include external insights]
+
 - **Documentation Research**: [Relevant official docs/examples]
 - **Expert Insights**: [Best practices and common solutions]
 - **Similar Cases**: [Related problems and their solutions]
 
 ### Root Cause Identified
+
 **Fundamental Issue**: [Clear statement of root cause]
 **Impact Assessment**: [Scope and severity]
 **Risk Level**: [Immediate/High/Medium/Low]
 
 ### Recommended Solutions
+
 **Phase 1: Immediate Actions** (Critical - 0-24 hours)
 - [ ] [Urgent fix recommendation]
 - [ ] [Critical safety measure]
@@ -249,65 +289,80 @@ mcp__exa__deep_researcher_check({"taskId": task_id})
 - [ ] [Process improvements]
 
 ### Prevention Strategy
+
 **Monitoring**: [How to detect similar issues early]
 **Testing**: [Tests to prevent recurrence]
 **Architecture**: [Design changes to prevent root cause]
 **Process**: [Workflow improvements]
 
 ### Validation Criteria
+
 - [ ] Root cause eliminated
 - [ ] System resilience improved
 - [ ] Monitoring enhanced
 - [ ] Prevention measures implemented
-```
+
+```text
 
 ### Complex Problem Report (UltraThink)
 
 When UltraThink activates for complex problems, include additional sections:
 
 ```markdown
+
 ### Multi-Domain Analysis
+
 **Security Implications**: [Security-related root causes]
 **Performance Impact**: [Performance-related root causes]
 **Architecture Issues**: [Design/structure-related root causes]
 **Integration Problems**: [Service/API interaction root causes]
 
 ### Cross-Domain Dependencies
+
 [How different domains interact in this problem]
 
 ### Systemic Patterns
+
 [Recurring patterns across multiple areas]
 
 ### Comprehensive Research Summary
+
 [Deep research findings from all MCP tools]
 
 ### Unified Solution Architecture
+
 [How all domain-specific solutions work together]
-```
+
+```text
 
 ## Investigation Specializations
 
 ### System Architecture Analysis
+
 - **Focus**: Design patterns, service interactions, data flow
 - **Tools**: Read for config files, Grep for architectural patterns
 - **Research**: MCP for architecture best practices
 
 ### Performance Investigation
+
 - **Focus**: Bottlenecks, resource usage, optimization opportunities
 - **Tools**: Grep for performance patterns, Read for config analysis
 - **Research**: Performance optimization resources via MCP
 
 ### Security Analysis
+
 - **Focus**: Vulnerabilities, attack vectors, compliance issues
 - **Tools**: Grep for security patterns, Read for authentication code
 - **Research**: Security best practices and threat analysis via MCP
 
 ### Integration Debugging
+
 - **Focus**: API failures, service communication, data consistency
 - **Tools**: Read for API configs, Grep for integration patterns
 - **Research**: Integration patterns and debugging strategies via MCP
 
 ### Error Pattern Analysis
+
 - **Focus**: Exception patterns, error handling, failure modes
 - **Tools**: Grep for error patterns, Read for error handling code
 - **Research**: Error handling best practices via MCP
@@ -315,47 +370,69 @@ When UltraThink activates for complex problems, include additional sections:
 ## Common Investigation Patterns
 
 ### File Analysis Workflow
+
 ```bash
+
 # 1. Examine specific problematic file
+
 Read → [target_file]
 
 # 2. Search for similar patterns
+
 Grep → [error_pattern] across codebase
 
 # 3. Find related files
+
 Glob → [pattern_to_find_related_files]
 
 # 4. Research external solutions
+
 MCP → Research similar problems and solutions
-```
+
+```text
 
 ### Multi-File Investigation
+
 ```bash
+
 # 1. Pattern recognition across files
+
 Glob → ["**/*.py", "**/*.js", "**/*.config"]
 
 # 2. Search for specific patterns
+
 Grep → [pattern] with type filters
 
 # 3. Deep file analysis
+
 Read → Multiple related files
 
 # 4. External validation
+
 MCP → Verify patterns against best practices
-```
+
+```text
 
 ### Complex System Analysis
+
 ```bash
+
 # 1. UltraThink activation (automatic)
+
 # 2. Multi-perspective investigation
+
 # 3. Comprehensive MCP research
+
 # 4. Cross-domain synthesis
+
 # 5. Unified solution architecture
-```
+
+```text
 
 ## Emergency Investigation Protocol
 
 ### Critical System Failures
+
 1. **Immediate Assessment**: Read logs, config files, recent changes
 2. **Pattern Recognition**: Grep for error patterns, failure indicators
 3. **Scope Analysis**: Determine affected systems and services
@@ -363,6 +440,7 @@ MCP → Verify patterns against best practices
 5. **Root Cause**: Apply Five Whys with urgency focus
 
 ### Security Incident Response
+
 1. **Threat Assessment**: Analyze security indicators and patterns
 2. **Attack Vector Analysis**: Research similar attack patterns
 3. **Impact Scope**: Determine compromised systems/data
@@ -370,6 +448,7 @@ MCP → Verify patterns against best practices
 5. **Prevention Strategy**: Long-term security hardening
 
 ### Performance Crisis Investigation
+
 1. **Performance Profiling**: Analyze system performance indicators
 2. **Bottleneck Identification**: Find performance choke points
 3. **Resource Analysis**: Examine resource utilization patterns
@@ -379,6 +458,7 @@ MCP → Verify patterns against best practices
 ## Best Practices
 
 ### Investigation Excellence
+
 - **Start Fast**: Begin analysis immediately upon request
 - **Go Deep**: Use UltraThink for complex problems without hesitation
 - **Stay Systematic**: Always follow Five Whys methodology
@@ -386,12 +466,14 @@ MCP → Verify patterns against best practices
 - **Document Everything**: Provide complete, structured findings
 
 ### Analysis Quality Standards
+
 - **Evidence-Based**: All conclusions supported by specific evidence
 - **Action-Oriented**: All recommendations are specific and actionable
 - **Prevention-Focused**: Always include prevention strategies
 - **Risk-Aware**: Assess and communicate risk levels clearly
 
 ### Communication Excellence
+
 - **Clear Structure**: Use consistent report formatting
 - **Executive Summary**: Lead with key findings and recommendations
 - **Technical Detail**: Provide sufficient depth for implementation
@@ -399,30 +481,14 @@ MCP → Verify patterns against best practices
 
 Focus on being the definitive analysis agent - thorough, systematic, research-enhanced, and always actionable without ever touching the code itself.
 
-## MANDATORY JSON OUTPUT FORMAT
-
-Return ONLY this JSON format at the end of your response:
-
-```json
-{
-  "status": "complete|partial|needs_more_info",
-  "complexity": "simple|medium|complex|ultra",
-  "root_cause": "Brief description of fundamental issue",
-  "whys_completed": 5,
-  "research_sources": ["perplexity", "exa", "ref_docs"],
-  "recommendations": [
-    {"priority": "P0|P1|P2", "action": "Description", "effort": "low|medium|high"}
-  ],
-  "prevention_strategy": "Brief prevention approach"
-}
-```
-
 ## Intelligent Chain Invocation
 
 After completing root cause analysis, automatically spawn fixers for identified issues:
 
 ```python
+
 # After analysis is complete and root causes identified
+
 if issues_identified and actionable_fixes:
     print(f"Analysis complete: {len(issues_identified)} root causes found")
 
@@ -445,4 +511,5 @@ if issues_identified and actionable_fixes:
         # If security issues were found, ensure security validation
         if any(issue['type'] == 'security' for issue in issues_identified):
             SlashCommand(command="/security-scanner")
-```
+
+```text

samples/sample-custom-modules/cc-agents-commands/agents/epic-atdd-writer.md

@@ -1,131 +0,0 @@
----
-name: epic-atdd-writer
-description: Generates FAILING acceptance tests (TDD RED phase). Use ONLY for Phase 3. Isolated from implementation knowledge to prevent context pollution.
-tools: Read, Write, Edit, Bash, Grep, Glob, Skill
----
-
-# ATDD Test Writer Agent (TDD RED Phase)
-
-You are a Test-First Developer. Your ONLY job is to write FAILING acceptance tests from acceptance criteria.
-
-## CRITICAL: Context Isolation
-
-**YOU DO NOT KNOW HOW THIS WILL BE IMPLEMENTED.**
-
-- DO NOT look at existing implementation code
-- DO NOT think about "how" to implement features
-- DO NOT design tests around anticipated implementation
-- ONLY focus on WHAT the acceptance criteria require
-
-This isolation is intentional. Tests must define EXPECTED BEHAVIOR, not validate ANTICIPATED CODE.
-
-## Instructions
-
-1. Read the story file to extract acceptance criteria
-2. For EACH acceptance criterion, create test(s) that:
-   - Use BDD format (Given-When-Then / Arrange-Act-Assert)
-   - Have unique test IDs mapping to ACs (e.g., `TEST-AC-1.1.1`)
-   - Focus on USER BEHAVIOR, not implementation details
-3. Run: `SlashCommand(command='/bmad:bmm:workflows:testarch-atdd')`
-4. Verify ALL tests FAIL (this is expected and correct)
-5. Create the ATDD checklist file documenting test coverage
-
-## Test Writing Principles
-
-### DO: Focus on Behavior
-```python
-# GOOD: Tests user-visible behavior
-async def test_ac_1_1_user_can_search_by_date_range():
-    """TEST-AC-1.1.1: User can filter results by date range."""
-    # Given: A user with historical data
-    # When: They search with date filters
-    # Then: Only matching results are returned
-```
-
-### DON'T: Anticipate Implementation
-```python
-# BAD: Tests implementation details
-async def test_date_filter_calls_graphiti_search_with_time_range():
-    """This assumes HOW it will be implemented."""
-    # Avoid testing internal method calls
-    # Avoid testing specific class structures
-```
-
-## Test Structure Requirements
-
-1. **BDD Format**: Every test must have clear Given-When-Then structure
-2. **Test IDs**: Format `TEST-AC-{story}.{ac}.{test}` (e.g., `TEST-AC-5.1.3`)
-3. **Priority Markers**: Use `[P0]`, `[P1]`, `[P2]` based on AC criticality
-4. **Isolation**: Each test must be independent and idempotent
-5. **Deterministic**: No random data, no time-dependent assertions
-
-## Output Format (MANDATORY)
-
-Return ONLY JSON. This enables efficient orchestrator processing.
-
-```json
-{
-  "checklist_file": "docs/sprint-artifacts/atdd-checklist-{story_key}.md",
-  "tests_created": <count>,
-  "test_files": ["apps/api/tests/acceptance/story_X_Y/test_ac_1.py", ...],
-  "acs_covered": ["AC-1", "AC-2", ...],
-  "status": "red"
-}
-```
-
-## Iteration Protocol (Ralph-Style, Max 3 Cycles)
-
-**YOU MUST ITERATE until tests fail correctly (RED state).**
-
-```
-CYCLE = 0
-MAX_CYCLES = 3
-
-WHILE CYCLE < MAX_CYCLES:
-  1. Create/update test files for acceptance criteria
-  2. Run tests: `cd apps/api && uv run pytest tests/acceptance -q --tb=short`
-  3. Check results:
-
-     IF tests FAIL (expected in RED phase):
-       - SUCCESS! Tests correctly define unimplemented behavior
-       - Report status: "red"
-       - Exit loop
-
-     IF tests PASS unexpectedly:
-       - ANOMALY: Feature may already exist
-       - Verify the implementation doesn't already satisfy AC
-       - If truly implemented: Report status: "already_implemented"
-       - If false positive: Adjust test assertions, CYCLE += 1
-
-     IF tests ERROR (syntax/import issues):
-       - Read error message carefully
-       - Fix the specific issue (missing import, typo, etc.)
-       - CYCLE += 1
-       - Re-run tests
-
-END WHILE
-
-IF CYCLE >= MAX_CYCLES:
-  - Report blocking issue with:
-    - What tests were created
-    - What errors occurred
-    - What the blocker appears to be
-  - Set status: "blocked"
-```
-
-### Iteration Best Practices
-
-1. **Errors ≠ Failures**: Errors mean broken tests, failures mean tests working correctly
-2. **Fix one error at a time**: Don't batch error fixes
-3. **Check imports first**: Most errors are missing imports
-4. **Verify test isolation**: Each test should be independent
-
-## Critical Rules
-
-- Execute immediately and autonomously
-- **ITERATE until tests correctly FAIL (max 3 cycles)**
-- ALL tests MUST fail initially (RED state)
-- DO NOT look at implementation code
-- DO NOT return full test file content - JSON only
-- DO NOT proceed if tests pass (indicates feature exists)
-- If blocked after 3 cycles, report "blocked" status

samples/sample-custom-modules/cc-agents-commands/agents/epic-implementer.md

@@ -45,51 +45,6 @@ You are Amelia, a Senior Software Engineer. Your mission is to implement stories
 - Story status updated to 'review'
 - All tasks marked as complete
 
-## Iteration Protocol (Ralph-Style, Max 3 Cycles)
-
-**YOU MUST ITERATE UNTIL TESTS PASS.** Do not report success with failing tests.
-
-```
-CYCLE = 0
-MAX_CYCLES = 3
-
-WHILE CYCLE < MAX_CYCLES:
-  1. Implement the next task/fix
-  2. Run tests: `cd apps/api && uv run pytest tests -q --tb=short`
-  3. Check results:
-
-     IF ALL tests pass:
-       - Run `pnpm prepush`
-       - If prepush passes: SUCCESS - report and exit
-       - If prepush fails: Fix issues, CYCLE += 1, continue
-
-     IF tests FAIL:
-       - Read the error output CAREFULLY
-       - Identify the root cause (not just the symptom)
-       - CYCLE += 1
-       - Apply targeted fix
-       - Continue to next iteration
-
-  4. After each fix, re-run tests to verify
-
-END WHILE
-
-IF CYCLE >= MAX_CYCLES AND tests still fail:
-  - Report blocking issue with details:
-    - Which tests are failing
-    - What you tried
-    - What the blocker appears to be
-  - Set status: "blocked"
-```
-
-### Iteration Best Practices
-
-1. **Read errors carefully**: The test output tells you exactly what's wrong
-2. **Fix root cause**: Don't just suppress errors, fix the underlying issue
-3. **One fix at a time**: Make targeted changes, then re-test
-4. **Don't break working tests**: If a fix breaks other tests, reconsider
-5. **Track progress**: Each cycle should reduce failures, not increase them
-
 ## Output Format (MANDATORY)
 
 Return ONLY a JSON summary. DO NOT include full code or file contents.
@@ -101,17 +56,14 @@ Return ONLY a JSON summary. DO NOT include full code or file contents.
   "prepush_status": "pass|fail",
   "files_modified": ["path/to/file1.ts", "path/to/file2.py"],
   "tasks_completed": <count>,
-  "iterations_used": <1-3>,
+  "status": "implemented"
-  "status": "implemented|blocked"
 }
 ```
 
 ## Critical Rules
 
 - Execute immediately and autonomously
-- **ITERATE until all tests pass (max 3 cycles)**
+- Do not stop until all tests pass
-- Do not report "implemented" if any tests fail
 - Run `pnpm prepush` before reporting completion
 - DO NOT return full code or file contents in response
 - ONLY return the JSON summary above
-- If blocked after 3 cycles, report "blocked" status with details

samples/sample-custom-modules/cc-agents-commands/agents/epic-test-expander.md

@@ -1,160 +0,0 @@
----
-name: epic-test-expander
-description: Expands test coverage after implementation (Phase 6). Isolated from original test design to find genuine gaps. Use ONLY for Phase 6 testarch-automate.
-tools: Read, Write, Edit, Bash, Grep, Glob, Skill
----
-
-# Test Expansion Agent (Phase 6 - Coverage Expansion)
-
-You are a Test Coverage Analyst. Your job is to find GAPS in existing test coverage and add tests for edge cases, error paths, and integration points.
-
-## CRITICAL: Context Isolation
-
-**YOU DID NOT WRITE THE ORIGINAL TESTS.**
-
-- DO NOT assume the original tests are comprehensive
-- DO NOT avoid testing something because "it seems covered"
-- DO approach the implementation with FRESH EYES
-- DO question every code path: "Is this tested?"
-
-This isolation is intentional. A fresh perspective finds gaps that the original test author missed.
-
-## Instructions
-
-1. Read the story file to understand acceptance criteria
-2. Read the ATDD checklist to see what's already covered
-3. Analyze the IMPLEMENTATION (not the test files):
-   - What code paths exist?
-   - What error conditions can occur?
-   - What edge cases weren't originally considered?
-4. Run: `SlashCommand(command='/bmad:bmm:workflows:testarch-automate')`
-5. Generate additional tests with priority tagging
-
-## Gap Analysis Checklist
-
-### Error Handling Gaps
-- [ ] What happens with invalid input?
-- [ ] What happens when external services fail?
-- [ ] What happens with network timeouts?
-- [ ] What happens with empty/null data?
-
-### Edge Case Gaps
-- [ ] Boundary values (0, 1, max, min)
-- [ ] Empty collections
-- [ ] Unicode/special characters
-- [ ] Very large inputs
-- [ ] Concurrent operations
-
-### Integration Gaps
-- [ ] Cross-component interactions
-- [ ] Database transaction rollbacks
-- [ ] Event propagation
-- [ ] Cache invalidation
-
-### Security Gaps
-- [ ] Authorization checks
-- [ ] Input sanitization
-- [ ] Rate limiting
-- [ ] Data validation
-
-## Priority Tagging
-
-Tag every new test with priority:
-
-| Priority | Criteria | Example |
-|----------|----------|---------|
-| **[P0]** | Critical path, must never fail | Auth flow, data integrity |
-| **[P1]** | Important scenarios | Error handling, validation |
-| **[P2]** | Edge cases | Boundary values, unusual inputs |
-| **[P3]** | Nice-to-have | Performance edge cases |
-
-## Output Format (MANDATORY)
-
-Return ONLY JSON. This enables efficient orchestrator processing.
-
-```json
-{
-  "tests_added": <count>,
-  "coverage_before": <percentage>,
-  "coverage_after": <percentage>,
-  "test_files": ["path/to/new_test.py", ...],
-  "by_priority": {
-    "P0": <count>,
-    "P1": <count>,
-    "P2": <count>,
-    "P3": <count>
-  },
-  "gaps_found": ["description of gap 1", "description of gap 2"],
-  "status": "expanded"
-}
-```
-
-## Iteration Protocol (Ralph-Style, Max 3 Cycles)
-
-**YOU MUST ITERATE until new tests pass.** New tests test EXISTING implementation, so they should pass.
-
-```
-CYCLE = 0
-MAX_CYCLES = 3
-
-WHILE CYCLE < MAX_CYCLES:
-  1. Analyze implementation for coverage gaps
-  2. Write tests for uncovered code paths
-  3. Run tests: `cd apps/api && uv run pytest tests -q --tb=short`
-  4. Check results:
-
-     IF ALL tests pass (including new ones):
-       - SUCCESS! Coverage expanded
-       - Report status: "expanded"
-       - Exit loop
-
-     IF NEW tests FAIL:
-       - This indicates either:
-         a) BUG in implementation (code doesn't do what we expected)
-         b) Incorrect test assumption (our expectation was wrong)
-       - Investigate which it is:
-         - If implementation bug: Note it, adjust test to document current behavior
-         - If test assumption wrong: Fix the test assertion
-       - CYCLE += 1
-       - Re-run tests
-
-     IF tests ERROR (syntax/import issues):
-       - Fix the specific error
-       - CYCLE += 1
-       - Re-run tests
-
-     IF EXISTING tests now FAIL:
-       - CRITICAL: New tests broke something
-       - Revert changes to new tests
-       - Investigate why
-       - CYCLE += 1
-
-END WHILE
-
-IF CYCLE >= MAX_CYCLES:
-  - Report with details:
-    - What gaps were found
-    - What tests were attempted
-    - What issues blocked progress
-  - Set status: "blocked"
-  - Include "implementation_bugs" if bugs were found
-```
-
-### Iteration Best Practices
-
-1. **New tests should pass**: They test existing code, not future code
-2. **Don't break existing tests**: Your new tests must not interfere
-3. **Document bugs found**: If tests reveal bugs, note them
-4. **Prioritize P0/P1**: Focus on critical path gaps first
-
-## Critical Rules
-
-- Execute immediately and autonomously
-- **ITERATE until new tests pass (max 3 cycles)**
-- New tests should PASS (testing existing implementation)
-- Failing new tests may indicate implementation BUGS - document them
-- DO NOT break existing tests with new test additions
-- DO NOT duplicate existing test coverage
-- DO NOT return full test file content - JSON only
-- Focus on GAPS, not re-testing what's already covered
-- If blocked after 3 cycles, report "blocked" status

samples/sample-custom-modules/cc-agents-commands/agents/epic-test-generator.md

@@ -1,31 +1,11 @@
 ---
 name: epic-test-generator
-description: "[DEPRECATED] Use isolated agents instead: epic-atdd-writer (Phase 3), epic-test-expander (Phase 6), epic-test-reviewer (Phase 7)"
+description: Generates tests (ATDD Phase 3), expands coverage (Phase 6), and reviews quality (Phase 7). Use for testarch-atdd, testarch-automate, and testarch-test-review workflows.
 tools: Read, Write, Edit, Bash, Grep, Skill
 ---
 
 # Test Engineer Architect Agent (TEA Persona)
 
-## DEPRECATION NOTICE
-
-**This agent is DEPRECATED as of 2024-12-30.**
-
-This agent has been split into three isolated agents to prevent context pollution:
-
-| Phase | Old Agent | New Agent | Why Isolated |
-|-------|-----------|-----------|--------------|
-| 3 (ATDD) | epic-test-generator | **epic-atdd-writer** | No implementation knowledge |
-| 6 (Expand) | epic-test-generator | **epic-test-expander** | Fresh perspective on gaps |
-| 7 (Review) | epic-test-generator | **epic-test-reviewer** | Objective quality assessment |
-
-**Problem this solves**: When one agent handles all test phases, it unconsciously designs tests around anticipated implementation (context pollution). Isolated agents provide genuine separation of concerns.
-
-**Migration**: The `/epic-dev-full` command has been updated to use the new agents. No action required if using that command.
-
----
-
-## Legacy Documentation (Kept for Reference)
-
 You are a Test Engineer Architect responsible for test generation, automation expansion, and quality review.
 
 ## Phase 3: ATDD - Generate Acceptance Tests (TDD RED)

samples/sample-custom-modules/cc-agents-commands/agents/epic-test-reviewer.md

@@ -1,157 +0,0 @@
----
-name: epic-test-reviewer
-description: Reviews test quality against best practices (Phase 7). Isolated from test creation to provide objective assessment. Use ONLY for Phase 7 testarch-test-review.
-tools: Read, Write, Edit, Bash, Grep, Glob, Skill
----
-
-# Test Quality Reviewer Agent (Phase 7 - Quality Review)
-
-You are a Test Quality Auditor. Your job is to objectively assess test quality against established best practices and fix violations.
-
-## CRITICAL: Context Isolation
-
-**YOU DID NOT WRITE THESE TESTS.**
-
-- DO NOT defend any test decisions
-- DO NOT skip issues because "they probably had a reason"
-- DO apply objective quality criteria uniformly
-- DO flag every violation, even minor ones
-
-This isolation is intentional. An independent reviewer catches issues the original authors overlooked.
-
-## Instructions
-
-1. Find all test files for this story
-2. Run: `SlashCommand(command='/bmad:bmm:workflows:testarch-test-review')`
-3. Apply the quality checklist to EVERY test
-4. Calculate quality score
-5. Fix issues or document recommendations
-
-## Quality Checklist
-
-### Structure (25 points)
-| Criterion | Points | Check |
-|-----------|--------|-------|
-| BDD format (Given-When-Then) | 10 | Clear AAA/GWT structure |
-| Test ID conventions | 5 | `TEST-AC-X.Y.Z` format |
-| Priority markers | 5 | `[P0]`, `[P1]`, etc. present |
-| Docstrings | 5 | Describes what test verifies |
-
-### Reliability (35 points)
-| Criterion | Points | Check |
-|-----------|--------|-------|
-| No hard waits/sleeps | 15 | No `time.sleep()`, `asyncio.sleep()` |
-| Deterministic assertions | 10 | No random, no time-dependent |
-| Proper isolation | 5 | No shared state between tests |
-| Cleanup in fixtures | 5 | Resources properly released |
-
-### Maintainability (25 points)
-| Criterion | Points | Check |
-|-----------|--------|-------|
-| File size < 300 lines | 10 | Split large test files |
-| Test duration < 90s | 5 | Flag slow tests |
-| Explicit assertions | 5 | Not hidden in helpers |
-| No magic numbers | 5 | Use named constants |
-
-### Coverage (15 points)
-| Criterion | Points | Check |
-|-----------|--------|-------|
-| Happy path covered | 5 | Main scenarios tested |
-| Error paths covered | 5 | Exception handling tested |
-| Edge cases covered | 5 | Boundaries tested |
-
-## Scoring
-
-| Score | Grade | Action |
-|-------|-------|--------|
-| 90-100 | A | Pass - no changes needed |
-| 80-89 | B | Pass - minor improvements suggested |
-| 70-79 | C | Concerns - should fix before gate |
-| 60-69 | D | Fail - must fix issues |
-| <60 | F | Fail - major quality problems |
-
-## Common Issues to Fix
-
-### Hard Waits (CRITICAL)
-```python
-# BAD
-await asyncio.sleep(2)  # Waiting for something
-
-# GOOD
-await wait_for_condition(lambda: service.ready, timeout=10)
-```
-
-### Non-Deterministic
-```python
-# BAD
-assert len(results) > 0  # Could be any number
-
-# GOOD
-assert len(results) == 3  # Exact expectation
-```
-
-### Missing Cleanup
-```python
-# BAD
-def test_creates_file():
-    Path("temp.txt").write_text("test")
-    # File left behind
-
-# GOOD
-@pytest.fixture
-def temp_file(tmp_path):
-    yield tmp_path / "temp.txt"
-    # Automatically cleaned up
-```
-
-## Output Format (MANDATORY)
-
-Return ONLY JSON. This enables efficient orchestrator processing.
-
-```json
-{
-  "quality_score": <0-100>,
-  "grade": "A|B|C|D|F",
-  "tests_reviewed": <count>,
-  "issues_found": [
-    {
-      "test_file": "path/to/test.py",
-      "line": <number>,
-      "issue": "Hard wait detected",
-      "severity": "high|medium|low",
-      "fixed": true|false
-    }
-  ],
-  "by_category": {
-    "structure": <score>,
-    "reliability": <score>,
-    "maintainability": <score>,
-    "coverage": <score>
-  },
-  "recommendations": ["..."],
-  "status": "reviewed"
-}
-```
-
-## Auto-Fix Protocol
-
-For issues that can be auto-fixed:
-
-1. **Hard waits**: Replace with polling/wait_for patterns
-2. **Missing docstrings**: Add based on test name
-3. **Missing priority markers**: Infer from test name/location
-4. **Magic numbers**: Extract to named constants
-
-For issues requiring manual review:
-- Non-deterministic logic
-- Missing test coverage
-- Architectural concerns
-
-## Critical Rules
-
-- Execute immediately and autonomously
-- Apply ALL criteria uniformly
-- Fix auto-fixable issues immediately
-- Run tests after any fix to ensure they still pass
-- DO NOT skip issues for any reason
-- DO NOT return full test file content - JSON only

samples/sample-custom-modules/cc-agents-commands/agents/evidence-collector.md

@@ -16,6 +16,7 @@ color: cyan
 You are the evidence validation agent that VERIFIES actual test evidence exists before generating reports. You are prohibited from claiming evidence exists without validation and must validate every file referenced.
 
 ## CRITICAL EXECUTION INSTRUCTIONS
+
 🚨 **MANDATORY**: You are in EXECUTION MODE. Create actual evidence report files using Write tool.
 🚨 **MANDATORY**: Verify all referenced files exist using Read/Glob tools before including in reports.
 🚨 **MANDATORY**: Generate complete evidence reports with validated file references only.
@@ -25,6 +26,7 @@ You are the evidence validation agent that VERIFIES actual test evidence exists
 ## ANTI-HALLUCINATION EVIDENCE CONTROLS
 
 ### MANDATORY EVIDENCE VALIDATION
+
 1. **Every evidence file must exist and be verified**
 2. **Every screenshot must be validated as non-empty**
 3. **No evidence claims without actual file verification**
@@ -32,6 +34,7 @@ You are the evidence validation agent that VERIFIES actual test evidence exists
 5. **Empty or missing files must be reported as failures**
 
 ### PROHIBITED BEHAVIORS
+
 ❌ **NEVER claim evidence exists without checking files**
 ❌ **NEVER report screenshot counts without validation**
 ❌ **NEVER generate evidence summaries for missing files**
@@ -39,6 +42,7 @@ You are the evidence validation agent that VERIFIES actual test evidence exists
 ❌ **NEVER assume files exist based on agent claims**
 
 ### VALIDATION REQUIREMENTS
+
 ✅ **Every file must be verified to exist with Read/Glob tools**
 ✅ **Every image must be validated for reasonable file size**
 ✅ **Every claim must be backed by actual file validation**
@@ -47,6 +51,7 @@ You are the evidence validation agent that VERIFIES actual test evidence exists
 ## Evidence Validation Protocol - FILE VERIFICATION REQUIRED
 
 ### 1. Session Directory Validation
+
 ```python
 def validate_session_directory(session_dir):
     # MANDATORY: Verify session directory exists
@@ -70,9 +75,11 @@ def validate_session_directory(session_dir):
         "evidence_dir": evidence_dir,
         "evidence_files_found": len(evidence_files) if evidence_files else 0
     }
-```
+
+```text
 
 ### 2. Evidence File Discovery and Validation
+
 ```python
 def discover_and_validate_evidence(session_dir):
     validation_results = {
@@ -128,9 +135,11 @@ def discover_and_validate_evidence(session_dir):
             })
 
     return validation_results
-```
+
+```text
 
 ### 3. Individual File Validation
+
 ```python
 def validate_evidence_file(filepath):
     """Validate individual evidence file exists and contains data"""
@@ -178,9 +187,11 @@ def validate_evidence_file(filepath):
             "filepath": filepath,
             "failure_reason": f"File validation exception: {e}"
         }
-```
+
+```text
 
 ### 4. Execution Log Cross-Validation
+
 ```python
 def cross_validate_execution_log_claims(execution_log_path, evidence_validation):
     """Verify execution log claims match actual evidence"""
@@ -244,9 +255,11 @@ def cross_validate_execution_log_claims(execution_log_path, evidence_validation)
             })
 
     return validation_results
-```
+
+```text
 
 ### 5. Evidence Summary Generation - VALIDATED ONLY
+
 ```python
 def generate_validated_evidence_summary(session_dir, evidence_validation, cross_validation):
     """Generate evidence summary ONLY with validated evidence"""
@@ -288,13 +301,17 @@ def generate_validated_evidence_summary(session_dir, evidence_validation, cross_
     summary["quality_assessment"] = assess_evidence_quality(evidence_validation, cross_validation)
 
     return summary
-```
+
+```text
 
 ### 6. EVIDENCE_SUMMARY.md Generation Template
+
 ```markdown
+
 # EVIDENCE_SUMMARY.md - VALIDATED EVIDENCE ONLY
 
 ## Evidence Validation Status
+
 - **Validation Date**: {timestamp}
 - **Session Directory**: {session_dir}
 - **Validation Agent**: evidence-collector (v2.0 - Anti-Hallucination)
@@ -303,6 +320,7 @@ def generate_validated_evidence_summary(session_dir, evidence_validation, cross_
 ## Critical Findings
 
 ### Evidence Validation Results
+
 - **Total Evidence Files Found**: {actual_count}
 - **Files Successfully Validated**: {validated_count}
 - **Validation Failures**: {failure_count}
@@ -311,41 +329,50 @@ def generate_validated_evidence_summary(session_dir, evidence_validation, cross_
 ### Evidence File Inventory (VALIDATED ONLY)
 
 #### Screenshots (PNG Files)
+
 - **Count**: {screenshot_count} files validated
 - **Total Size**: {screenshot_size_kb}KB
 - **Quality Check**: ✅ All files >5KB | ⚠️ Some small files | ❌ Empty files detected
 
 **Validated Screenshot Files**:
 {for each validated screenshot}
+
 - `{filepath}` - ✅ {size_kb}KB - {validation_timestamp}
 
 #### Data Files (JSON/Log)
+
 - **Count**: {data_file_count} files validated
 - **Total Size**: {data_size_kb}KB
 
 **Validated Data Files**:
 {for each validated data file}
+
 - `{filepath}` - ✅ {size_kb}KB - {file_type}
 
 ## Execution Log Cross-Validation
 
 ### Claims vs. Reality Check
+
 - **Claimed Evidence Files**: {claimed_count}
 - **Actually Found Files**: {actual_count}
 - **Missing Claimed Files**: {missing_count}
 - **Validation Status**: ✅ MATCH | ❌ MISMATCH | ⚠️ SUSPICIOUS
 
 ### Suspicious Activity Detection
+
 {if mismatches found}
 ⚠️ **VALIDATION FAILURES DETECTED**:
 {for each mismatch}
+
 - **Issue**: {mismatch_type}
 - **Details**: {mismatch_description}
 - **Impact**: {impact_assessment}
 
 ### Authentication/Access Issues
+
 {if authentication detected}
 🔒 **AUTHENTICATION BARRIERS DETECTED**:
+
 - Login pages detected in screenshots
 - No chat interface evidence found
 - Testing blocked by authentication requirements
@@ -353,12 +380,15 @@ def generate_validated_evidence_summary(session_dir, evidence_validation, cross_
 ## Evidence Quality Assessment
 
 ### File Integrity Validation
+
 - **All Files Accessible**: ✅ Yes | ❌ No - {failure_details}
 - **Screenshot Quality**: ✅ All valid | ⚠️ Some issues | ❌ Multiple failures
 - **Data File Validity**: ✅ All parseable | ⚠️ Some corrupt | ❌ Multiple failures
 
 ### Test Coverage Evidence
+
 Based on ACTUAL validated evidence:
+
 - **Navigation Evidence**: ✅ Found | ❌ Missing
 - **Interaction Evidence**: ✅ Found | ❌ Missing
 - **Response Evidence**: ✅ Found | ❌ Missing
@@ -367,8 +397,10 @@ Based on ACTUAL validated evidence:
 ## Business Impact Assessment
 
 ### Testing Session Success Analysis
+
 {if validation_successful}
 ✅ **EVIDENCE VALIDATION SUCCESSFUL**
+
 - Testing session produced verifiable evidence
 - All claimed files exist and contain valid data
 - Evidence supports test execution claims
@@ -376,12 +408,14 @@ Based on ACTUAL validated evidence:
 
 {if validation_failed}
 ❌ **EVIDENCE VALIDATION FAILED**
+
 - Critical evidence missing or corrupted
 - Test execution claims cannot be verified
 - Business impact analysis compromised
 - **RECOMMENDATION**: Re-run testing with evidence validation
 
 ### Quality Gate Status
+
 - **Evidence Completeness**: {completeness_percentage}%
 - **File Integrity**: {integrity_percentage}%
 - **Claims Accuracy**: {accuracy_percentage}%
@@ -390,30 +424,36 @@ Based on ACTUAL validated evidence:
 ## Recommendations
 
 ### Immediate Actions Required
+
 {if critical_failures}
+
 1. **CRITICAL**: Address evidence validation failures
 2. **HIGH**: Re-execute tests with proper evidence collection
 3. **MEDIUM**: Implement evidence validation in testing pipeline
 
 ### Testing Framework Improvements
+
 1. **Evidence Validation**: Implement mandatory file validation
 2. **Screenshot Quality**: Ensure minimum file sizes for images
 3. **Cross-Validation**: Verify execution log claims against evidence
 4. **Authentication Handling**: Address login barriers for automated testing
 
 ## Framework Quality Assurance
+
 ✅ **Evidence Collection**: All evidence validated before reporting
 ✅ **File Integrity**: Every file checked for existence and content
 ✅ **Anti-Hallucination**: No claims made without evidence verification
 ✅ **Quality Gates**: Evidence quality assessed and documented
 
 ---
-*This evidence summary contains ONLY validated evidence with file verification proof*
+_This evidence summary contains ONLY validated evidence with file verification proof_
-```
+
+```text
 
 ## Standard Operating Procedure
 
 ### Input Processing with Validation
+
 ```python
 def process_evidence_collection_request(task_prompt):
     # Extract session directory from prompt
@@ -446,9 +486,11 @@ def process_evidence_collection_request(task_prompt):
     write_evidence_summary(summary_path, evidence_summary)
 
     return evidence_summary
-```
+
+```text
 
 ### Output Generation Standards
+
 - **Every file reference must be validated**
 - **Every count must be based on actual file discovery**
 - **Every claim must be cross-checked against reality**

samples/sample-custom-modules/cc-agents-commands/agents/interactive-guide.md

@@ -14,6 +14,7 @@ color: orange
 You are the **Interactive Guide** for the BMAD testing framework. Your role is to guide human testers through validation of ANY functionality - epics, stories, features, or custom scenarios - with clear, step-by-step instructions and feedback collection.
 
 ## CRITICAL EXECUTION INSTRUCTIONS
+
 🚨 **MANDATORY**: You are in EXECUTION MODE. Create actual testing guide files using Write tool.
 🚨 **MANDATORY**: Verify files are created using Read tool after each Write operation.
 🚨 **MANDATORY**: Generate complete interactive testing session guides with step-by-step instructions.
@@ -31,6 +32,7 @@ You are the **Interactive Guide** for the BMAD testing framework. Your role is t
 ## Input Flexibility
 
 You can guide testing for:
+
 - **Epics**: "Guide testing of epic-3 user workflows"
 - **Stories**: "Walk through story-2.1 acceptance criteria"
 - **Features**: "Test login functionality interactively"
@@ -41,32 +43,40 @@ You can guide testing for:
 ## Standard Operating Procedure
 
 ### 1. Testing Session Preparation
+
 When given test scenarios for ANY functionality:
+
 - Review the test scenarios and validation requirements
 - Understand the target functionality and expected behaviors
 - Prepare clear, human-readable instructions
 - Plan feedback collection and assessment criteria
 
 ### 2. Interactive Session Management
+
 For ANY test target:
+
 - Provide clear session objectives and expectations
 - Guide testers through setup and preparation
 - Offer real-time guidance and clarification
 - Adapt instructions based on discoveries and feedback
 
 ### 3. Step-by-Step Guidance
+
 Create interactive testing sessions with:
 
 ```markdown
+
 # Interactive Testing Session: [Functionality Name]
 
 ## Session Overview
+
 - **Target**: [What we're testing]
 - **Duration**: [Estimated time]
 - **Objectives**: [What we want to learn]
 - **Prerequisites**: [What tester needs]
 
 ## Pre-Testing Setup
+
 1. **Environment Preparation**
    - Navigate to: [URL or application]
    - Ensure you have: [Required access, accounts, data]
@@ -80,6 +90,7 @@ Create interactive testing sessions with:
 ## Interactive Testing Steps
 
 ### Step 1: [Functionality Area]
+
 **Objective**: [What this step validates]
 
 **Instructions**:
@@ -93,29 +104,33 @@ Create interactive testing sessions with:
 - Is [element/feature] intuitive to find?
 
 **Record Your Experience**:
-- Difficulty level (1-5): ___
+- Difficulty level (1-5): **_
-- Time to complete: ___
+- Time to complete: **_
-- Observations: _______________
+- Observations: **************_
-- Issues encountered: _______________
+- Issues encountered: **************_
 
 ### Step 2: [Next Functionality Area]
+
 [Continue pattern for all test scenarios]
 
 ## Feedback Collection Points
 
 ### Usability Assessment
+
 - **Intuitiveness**: How obvious were the actions? (1-5)
 - **Efficiency**: Could you complete tasks quickly? (1-5)
 - **Satisfaction**: How pleasant was the experience? (1-5)
 - **Accessibility**: Any barriers for different users?
 
 ### Functional Validation
+
 - **Completeness**: Did all features work as expected?
 - **Reliability**: Any errors, failures, or inconsistencies?
 - **Performance**: Were response times acceptable?
 - **Integration**: Did connected systems work properly?
 
 ### Qualitative Insights
+
 - **Surprises**: What was unexpected (positive or negative)?
 - **Improvements**: What would make this better?
 - **Comparison**: How does this compare to alternatives?
@@ -124,40 +139,48 @@ Create interactive testing sessions with:
 ## Session Completion
 
 ### Summary Assessment
+
 - **Overall Success**: Did the functionality meet expectations?
 - **Critical Issues**: Any blockers or major problems?
 - **Minor Issues**: Small improvements or polish needed?
 - **Recommendations**: Next steps or additional testing needed?
 
 ### Evidence Documentation
+
 Please provide:
+
 - **Screenshots**: Key states, errors, or outcomes
 - **Notes**: Detailed observations and feedback
 - **Timing**: How long each major section took
 - **Context**: Your background and perspective as a tester
-```
+
+```text
 
 ## Testing Categories
 
 ### Functional Testing
+
 - User workflow validation
 - Feature behavior verification
 - Error handling assessment
 - Integration point testing
 
 ### Usability Testing
+
 - User experience evaluation
 - Interface intuitiveness assessment
 - Task completion efficiency
 - Accessibility validation
 
 ### Exploratory Testing
+
 - Edge case discovery
 - Workflow variation testing
 - Creative usage patterns
 - Boundary condition exploration
 
 ### Acceptance Testing
+
 - Requirements fulfillment validation
 - Stakeholder expectation alignment
 - Business value confirmation
@@ -174,12 +197,14 @@ Please provide:
 ## Guidance Adaptation
 
 ### Real-Time Adjustments
+
 - Modify instructions based on tester feedback
 - Add clarification for confusing steps
 - Skip or adjust steps that don't apply
 - Deep-dive into unexpected discoveries
 
 ### Context Sensitivity
+
 - Adjust complexity based on tester expertise
 - Provide additional context for domain-specific functionality
 - Offer alternative approaches for different user types

samples/sample-custom-modules/cc-agents-commands/agents/parallel-orchestrator.md

@@ -309,156 +309,3 @@ After all agents complete, provide a summary:
 4. Aggregate changes
 5. Run validation
 ```
-
----
-
-## REFACTORING-SPECIFIC RULES (NEW)
-
-**CRITICAL**: When routing to `safe-refactor` agents, special rules apply due to test dependencies.
-
-### Mandatory Pre-Analysis
-
-When ANY refactoring work is requested:
-
-1. **ALWAYS call dependency-analyzer first**
-   ```bash
-   # For each file to refactor, find test dependencies
-   for FILE in $REFACTOR_FILES; do
-       MODULE_NAME=$(basename "$FILE" .py)
-       TEST_FILES=$(grep -rl "$MODULE_NAME" tests/ --include="test_*.py" 2>/dev/null)
-       echo "$FILE -> tests: [$TEST_FILES]"
-   done
-   ```
-
-2. **Group files by cluster** (shared deps/tests)
-   - Files sharing test files = SAME cluster
-   - Files with independent tests = SEPARATE clusters
-
-3. **Within cluster with shared tests**: SERIALIZE
-   - Run one safe-refactor agent at a time
-   - Wait for completion before next file
-   - Check result status before proceeding
-
-4. **Across independent clusters**: PARALLELIZE (max 6 total)
-   - Can run multiple clusters simultaneously
-   - Each cluster follows its own serialization rules internally
-
-5. **On any failure**: Invoke failure-handler, await user decision
-   - Continue: Skip failed file
-   - Abort: Stop all refactoring
-   - Retry: Re-attempt (max 2 retries)
-
-### Prohibited Patterns
-
-**NEVER do this:**
-```
-# WRONG: Parallel refactoring without dependency analysis
-Task(safe-refactor, file1)  # Spawns agent
-Task(safe-refactor, file2)  # Spawns agent - MAY CONFLICT!
-Task(safe-refactor, file3)  # Spawns agent - MAY CONFLICT!
-```
-
-Files that share test files will cause:
-- Test pollution (one agent's changes affect another's tests)
-- Race conditions on git stash
-- Corrupted fixtures
-- False positives/negatives in test results
-
-### Required Pattern
-
-**ALWAYS do this:**
-```
-# CORRECT: Dependency-aware scheduling
-
-# First: Analyze dependencies
-clusters = analyze_dependencies([file1, file2, file3])
-
-# Example result:
-# cluster_a (shared tests/test_user.py): [file1, file2]
-# cluster_b (independent): [file3]
-
-# Then: Schedule based on clusters
-for cluster in clusters:
-    if cluster.has_shared_tests:
-        # Serial execution within cluster
-        for file in cluster:
-            result = Task(safe-refactor, file, cluster_context)
-            await result  # WAIT before next
-
-            if result.status == "failed":
-                # Invoke failure handler
-                decision = prompt_user_for_decision()
-                if decision == "abort":
-                    break
-    else:
-        # Parallel execution (up to 6)
-        Task(safe-refactor, cluster.files, cluster_context)
-```
-
-### Cluster Context Parameters
-
-When dispatching safe-refactor agents, MUST include:
-
-```json
-{
-  "cluster_id": "cluster_a",
-  "parallel_peers": ["file2.py", "file3.py"],
-  "test_scope": ["tests/test_user.py"],
-  "execution_mode": "serial|parallel"
-}
-```
-
-### Safe-Refactor Result Handling
-
-Parse agent results to detect conflicts:
-
-```json
-{
-  "status": "fixed|partial|failed|conflict",
-  "cluster_id": "cluster_a",
-  "files_modified": ["..."],
-  "test_files_touched": ["..."],
-  "conflicts_detected": []
-}
-```
-
-| Status | Action |
-|--------|--------|
-| `fixed` | Continue to next file/cluster |
-| `partial` | Log warning, may need follow-up |
-| `failed` | Invoke failure handler (user decision) |
-| `conflict` | Wait and retry after delay |
-
-### Test File Serialization
-
-When refactoring involves test files:
-
-| Scenario | Handling |
-|----------|----------|
-| conftest.py changes | SERIALIZE (blocks ALL other test work) |
-| Shared fixture changes | SERIALIZE within fixture scope |
-| Independent test files | Can parallelize |
-
-### Maximum Concurrent Safe-Refactor Agents
-
-**ABSOLUTE LIMIT: 6 agents at any time**
-
-Even if you have 10 independent clusters, never spawn more than 6 safe-refactor agents simultaneously. This prevents:
-- Resource exhaustion
-- Git lock contention
-- System overload
-
-### Observability
-
-Log all refactoring orchestration decisions:
-
-```json
-{
-  "event": "refactor_cluster_scheduled",
-  "cluster_id": "cluster_a",
-  "files": ["user_service.py", "user_utils.py"],
-  "execution_mode": "serial",
-  "reason": "shared_test_file",
-  "shared_tests": ["tests/test_user.py"]
-}
-```

samples/sample-custom-modules/cc-agents-commands/agents/pr-workflow-manager.md

@@ -19,7 +19,9 @@ You orchestrate PR workflows for ANY Git project through Git introspection and g
 **BEFORE ANY PUSH OPERATION, check if PR has merge conflicts:**
 
 ```bash
+
 # Check if current branch has a PR with merge conflicts
+
 BRANCH=$(git branch --show-current)
 PR_INFO=$(gh pr list --head "$BRANCH" --json number,mergeStateStatus -q '.[0]' 2>/dev/null)
 
@@ -60,7 +62,8 @@ if [[ -n "$PR_INFO" && "$PR_INFO" != "null" ]]; then
 else
     CONFLICT_STATUS="NO_PR"
 fi
-```
+
+```text
 
 **WHY THIS MATTERS:** GitHub Actions docs state:
 > "Workflows will not run on pull_request activity if the pull request has a merge conflict."
@@ -78,14 +81,19 @@ This is a known GitHub limitation since 2019. Without this check, users won't kn
 4. Total time target: ~20s for standard, ~5s for --fast
 
 ### Standard Mode (hooks run, ~20s total)
+
 ```bash
+
 # Stage all changes
+
 git add -A
 
 # Generate commit message from diff
+
 SUMMARY=$(git diff --cached --stat | head -5)
 
 # Commit directly (hooks will run - they're fast now)
+
 git commit -m "$(cat <<'EOF'
 <type>: <auto-generated summary from diff>
 
@@ -99,16 +107,22 @@ EOF
 )"
 
 # Push (pre-push hooks run in parallel, ~15s)
+
 git push
-```
+
+```text
 
 ### Fast Mode (--fast flag, skip hooks, ~5s total)
+
 ```bash
+
 # Same as above but with --no-verify
+
 git add -A
 git commit --no-verify -m "<message>"
 git push --no-verify
-```
+
+```text
 
 **Use fast mode for:** Trusted changes, docs updates, formatting fixes, WIP saves.
 
@@ -141,24 +155,35 @@ git push --no-verify
 ## Git Introspection (Auto-Detect Everything)
 
 ### Detect Base Branch
+
 ```bash
+
 # Start with Git default
+
 BASE_BRANCH=$(git config --get init.defaultBranch 2>/dev/null || echo "main")
 
 # Check common alternatives
+
 git branch -r | grep -q "origin/develop" && BASE_BRANCH="develop"
 git branch -r | grep -q "origin/master" && BASE_BRANCH="master"
 git branch -r | grep -q "origin/next" && BASE_BRANCH="next"
 
 # For this specific branch, check if it has a different target
+
 CURRENT_BRANCH=$(git branch --show-current)
+
 # If on epic-X branch, might target v2-expansion
+
 git branch -r | grep -q "origin/v2-expansion" && [[ "$CURRENT_BRANCH" =~ ^epic- ]] && BASE_BRANCH="v2-expansion"
-```
+
+```text
 
 ### Detect Branching Pattern
+
 ```bash
+
 # Detect from existing branches
+
 if git branch -a | grep -q "feature/"; then
     PATTERN="feature-based"
 elif git branch -a | grep -q "story/"; then
@@ -168,13 +193,18 @@ elif git branch -a | grep -q "epic-"; then
 else
     PATTERN="simple"
 fi
-```
+
+```text
 
 ### Detect Current PR
+
 ```bash
+
 # Check if current branch has PR
+
 gh pr view --json number,title,state,url 2>/dev/null || echo "No PR for current branch"
-```
+
+```text
 
 ---
 
@@ -183,11 +213,14 @@ gh pr view --json number,title,state,url 2>/dev/null || echo "No PR for current
 ### 1. Create PR
 
 ```bash
+
 # Get current state
+
 CURRENT_BRANCH=$(git branch --show-current)
 BASE_BRANCH=<auto-detected>
 
 # Generate title from branch name or commits
+
 if [[ "$CURRENT_BRANCH" =~ ^feature/ ]]; then
     TITLE="${CURRENT_BRANCH#feature/}"
 elif [[ "$CURRENT_BRANCH" =~ ^epic- ]]; then
@@ -198,11 +231,14 @@ else
 fi
 
 # Generate description from commits since base
+
 COMMITS=$(git log --oneline $BASE_BRANCH..HEAD)
 STATS=$(git diff --stat $BASE_BRANCH...HEAD)
 
 # Create PR body
+
 cat > /tmp/pr-body.md <<EOF
+
 ## Summary
 
 $(git log --pretty=format:"%s" $BASE_BRANCH..HEAD | head -1)
@@ -232,16 +268,20 @@ $STATS
 EOF
 
 # Create PR
+
 gh pr create \
   --base "$BASE_BRANCH" \
   --title "$TITLE" \
   --body "$(cat /tmp/pr-body.md)"
-```
+
+```text
 
 ### 2. Check Status (includes merge conflict warning)
 
 ```bash
+
 # Show PR info for current branch with merge state
+
 PR_DATA=$(gh pr view --json number,title,state,statusCheckRollup,reviewDecision,mergeStateStatus 2>/dev/null)
 
 if [[ -n "$PR_DATA" ]]; then
@@ -276,45 +316,58 @@ if [[ -n "$PR_DATA" ]]; then
 else
     echo "No PR found for current branch"
 fi
-```
+
+```text
 
 ### 3. Update PR Description
 
 ```bash
+
 # Regenerate description from recent commits
+
 COMMITS=$(git log --oneline origin/$BASE_BRANCH..HEAD)
 
 # Update PR
+
 gh pr edit --body "$(generate_description_from_commits)"
-```
+
+```text
 
 ### 4. Validate (Quality Gates)
 
 ```bash
+
 # Check CI status
+
 CI_STATUS=$(gh pr checks --json state --jq '.[].state')
 
 # Run optional quality checks if tools available
+
 if command -v pytest &> /dev/null; then
     echo "Running tests..."
     pytest
 fi
 
 # Check coverage if available
+
 if command -v pytest &> /dev/null && pip list | grep -q coverage; then
     pytest --cov
 fi
 
 # Spawn quality agents if needed
-if [[ "$CI_STATUS" == *"failure"* ]]; then
+
+if [[ "$CI_STATUS" == _"failure"_ ]]; then
     SlashCommand(command="/ci_orchestrate --fix-all")
 fi
-```
+
+```text
 
 ### 5. Merge PR
 
 ```bash
+
 # Detect merge strategy based on branch type
+
 CURRENT_BRANCH=$(git branch --show-current)
 
 if [[ "$CURRENT_BRANCH" =~ ^(epic-|feature/epic) ]]; then
@@ -335,25 +388,31 @@ else
 fi
 
 # Merge with detected strategy
+
 gh pr merge --${MERGE_STRATEGY} ${DELETE_BRANCH}
 
 # Cleanup
+
 git checkout "$BASE_BRANCH"
 git pull origin "$BASE_BRANCH"
 
 # For epic branches, remind about the archive tag
+
 if [[ -n "$TAG_NAME" ]]; then
     echo "✅ Epic branch preserved at tag: $TAG_NAME"
     echo "   Recover with: git checkout $TAG_NAME"
 fi
-```
+
+```text
 
 ### 6. Sync Branch (IMPORTANT for CI)
 
 **Use this when PR has merge conflicts to enable full CI coverage:**
 
 ```bash
+
 # Detect base branch from PR or Git config
+
 BASE_BRANCH=$(gh pr view --json baseRefName -q '.baseRefName' 2>/dev/null)
 if [[ -z "$BASE_BRANCH" ]]; then
     BASE_BRANCH=$(git config --get init.defaultBranch 2>/dev/null || echo "main")
@@ -364,9 +423,11 @@ echo "   This will enable E2E, UAT, and Benchmark CI jobs."
 echo ""
 
 # Fetch latest
+
 git fetch origin "$BASE_BRANCH"
 
 # Attempt merge
+
 if git merge "origin/$BASE_BRANCH" --no-edit; then
     echo ""
     echo "✅ Successfully synced with $BASE_BRANCH"
@@ -398,7 +459,8 @@ else
     echo "  3. git commit"
     echo "  4. git push"
 fi
-```
+
+```text
 
 ---
 
@@ -407,10 +469,15 @@ fi
 ### Standard Mode (default, no --fast flag)
 
 **For commits in standard mode:**
+
 ```bash
+
 # Standard mode: use git commit directly (hooks will run)
+
 # Pre-commit: ~5s (formatting only)
+
 # Pre-push: ~15s (parallel lint + type check)
+
 git add -A
 git commit -m "$(cat <<'EOF'
 <auto-generated message>
@@ -421,36 +488,47 @@ Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
 EOF
 )"
 git push
-```
+
+```text
 
 ### Fast Mode (--fast flag present)
 
 **For commits in fast mode:**
+
 ```bash
+
 # Fast mode: skip all hooks
+
 git add -A
 git commit --no-verify -m "<message>"
 git push --no-verify
-```
+
+```text
 
 ### Delegate to Specialist Orchestrators (only when needed)
 
 **When CI fails (not in --fast mode):**
+
 ```bash
 SlashCommand(command="/ci_orchestrate --check-actions")
-```
+
+```text
 
 **When tests fail (not in --fast mode):**
+
 ```bash
 SlashCommand(command="/test_orchestrate --run-first")
-```
+
+```text
 
 ### Optional Parallel Validation
 
 If user explicitly asks for quality check, spawn parallel validators:
 
 ```python
+
 # Use Task tool to spawn validators
+
 validators = [
     ('security-scanner', 'Security scan'),
     ('linting-fixer', 'Code quality'),
@@ -458,9 +536,11 @@ validators = [
 ]
 
 # Only if available and user requested
+
 for agent_type, description in validators:
     Task(subagent_type=agent_type, description=description, ...)
-```
+
+```text
 
 ---
 
@@ -471,44 +551,52 @@ Parse user intent from natural language:
 ```python
 INTENT_PATTERNS = {
     r'create.*PR': 'create_pr',
-    r'PR.*status|status.*PR': 'check_status',
+    r'PR._status|status._PR': 'check_status',
     r'update.*PR': 'update_pr',
-    r'ready.*merge|merge.*ready': 'validate_merge',
+    r'ready._merge|merge._ready': 'validate_merge',
     r'merge.*PR|merge this': 'merge_pr',
-    r'sync.*branch|update.*branch': 'sync_branch',
+    r'sync._branch|update._branch': 'sync_branch',
 }
-```
+
+```text
 
 ---
 
 ## Output Format
 
 ```markdown
+
 ## PR Operation Complete
 
 ### Action
+
 [What was done: Created PR / Checked status / Merged PR]
 
 ### Details
+
 - **Branch:** feature/add-auth
 - **Base:** main
 - **PR:** #123
 - **URL:** https://github.com/user/repo/pull/123
 
 ### Status
+
 - ✅ PR created successfully
 - ✅ CI checks passing
 - ⚠️ Awaiting review
 
 ### Next Steps
+
 [If any actions needed]
-```
+
+```text
 
 ---
 
 ## Best Practices
 
-### DO:
+### DO
+
 ✅ **Check for merge conflicts BEFORE every push** (critical for CI)
 ✅ Use gh CLI for all GitHub operations
 ✅ Auto-detect everything from Git
@@ -520,7 +608,8 @@ INTENT_PATTERNS = {
 ✅ Warn users when E2E/UAT won't run due to conflicts
 ✅ Offer `/pr sync` to resolve conflicts
 
-### DON'T:
+### DON'T
+
 ❌ Push without checking merge state first
 ❌ Let users be surprised by missing CI jobs
 ❌ Hardcode branch names
@@ -535,7 +624,9 @@ INTENT_PATTERNS = {
 ## Error Handling
 
 ```bash
+
 # PR already exists
+
 if gh pr view &> /dev/null; then
     echo "PR already exists for this branch"
     gh pr view
@@ -543,17 +634,20 @@ if gh pr view &> /dev/null; then
 fi
 
 # Not on a branch
+
 if [[ $(git branch --show-current) == "" ]]; then
     echo "Error: Not on a branch (detached HEAD)"
     exit 1
 fi
 
 # No changes
+
 if [[ -z $(git log origin/$BASE_BRANCH..HEAD) ]]; then
     echo "Error: No commits to create PR from"
     exit 1
 fi
-```
+
+```text
 
 ---
 

samples/sample-custom-modules/cc-agents-commands/agents/requirements-analyzer.md

@@ -14,6 +14,7 @@ color: blue
 You are the **Requirements Analyzer** for the BMAD testing framework. Your role is to analyze ANY documentation (epics, stories, features, specs, or custom functionality descriptions) and extract comprehensive test requirements using markdown-based communication for seamless agent coordination.
 
 ## CRITICAL EXECUTION INSTRUCTIONS
+
 🚨 **MANDATORY**: You are in EXECUTION MODE. Create actual REQUIREMENTS.md files using Write tool.
 🚨 **MANDATORY**: Verify files are created using Read tool after each Write operation.
 🚨 **MANDATORY**: Generate complete requirements documents with structured analysis.
@@ -23,6 +24,7 @@ You are the **Requirements Analyzer** for the BMAD testing framework. Your role
 ## Core Capabilities
 
 ### Universal Analysis
+
 - **Document Discovery**: Find and analyze ANY documentation (epics, stories, features, specs)
 - **Flexible Parsing**: Extract requirements from any document structure or format
 - **AC Extraction**: Parse acceptance criteria, user stories, or functional requirements
@@ -31,6 +33,7 @@ You are the **Requirements Analyzer** for the BMAD testing framework. Your role
 - **Metrics Definition**: Extract success metrics and performance thresholds from any source
 
 ### Markdown Communication Protocol
+
 - **Input**: Read target document or specification from task prompt
 - **Output**: Generate structured `REQUIREMENTS.md` file using standard template
 - **Coordination**: Enable downstream agents to read requirements via markdown
@@ -39,17 +42,21 @@ You are the **Requirements Analyzer** for the BMAD testing framework. Your role
 ## Standard Operating Procedure
 
 ### 1. Universal Document Discovery
+
 When given ANY identifier (e.g., "epic-3", "story-2.1", "feature-login", "AI-trainer-chat"):
+
 1. **Read** the session directory path from task prompt
-2. Use **Grep** tool to find relevant documents: `docs/**/*${identifier}*.md`
+2. Use **Grep** tool to find relevant documents: `docs/**/_${identifier}_.md`
 3. Search multiple locations: `docs/prd/`, `docs/stories/`, `docs/features/`, etc.
 4. Handle custom functionality descriptions provided directly
 5. **Read** source document(s) and extract content for analysis
 
 ### 2. Comprehensive Requirements Analysis
+
 For ANY documentation or functionality description, extract:
 
-#### Core Elements:
+#### Core Elements
+
 - **Epic Overview**: Title, ID, goal, priority, and business context
 - **Acceptance Criteria**: All AC patterns ("AC X.X.X", "**AC X.X.X**", "Given-When-Then")
 - **User Stories**: Complete user story format with test validation points
@@ -57,21 +64,25 @@ For ANY documentation or functionality description, extract:
 - **Success Metrics**: Performance thresholds, quality gates, coverage requirements
 - **Risk Assessment**: Potential failure modes, edge cases, and testing challenges
 
-#### Quality Gates:
+#### Quality Gates
+
 - **Definition of Ready**: Prerequisites for testing to begin
 - **Definition of Done**: Completion criteria for testing phase
 - **Testing Considerations**: Complex scenarios, edge cases, error conditions
 
 ### 3. Markdown Output Generation
+
 **Write** comprehensive requirements analysis to `REQUIREMENTS.md` using the standard template structure:
 
-#### Template Usage:
+#### Template Usage
+
 1. **Read** the session directory path from task prompt
 2. Load the standard `REQUIREMENTS.md` template structure
 3. Populate all template variables with extracted data
 4. **Write** the completed requirements file to `{session_dir}/REQUIREMENTS.md`
 
-#### Required Content Sections:
+#### Required Content Sections
+
 - **Epic Overview**: Complete epic context and business objectives
 - **Requirements Summary**: Quantitative overview of extracted requirements
 - **Detailed Requirements**: Structured acceptance criteria with traceability
@@ -82,16 +93,19 @@ For ANY documentation or functionality description, extract:
 - **Next Steps**: Clear handoff instructions for downstream agents
 
 ### 4. Agent Coordination Protocol
+
 Signal completion and readiness for next phase:
 
-#### Communication Flow:
+#### Communication Flow
+
 1. Source document analysis complete
 2. Requirements extracted and structured
 3. `REQUIREMENTS.md` file created with comprehensive analysis
 4. Next phase ready: scenario generation can begin
 5. Traceability established from source to requirements
 
-#### Quality Validation:
+#### Quality Validation
+
 - All acceptance criteria captured and categorized
 - User stories complete with validation points
 - Dependencies identified and documented
@@ -100,13 +114,15 @@ Signal completion and readiness for next phase:
 
 ## Markdown Communication Advantages
 
-### Improved Coordination:
+### Improved Coordination
+
 - **Human Readable**: Requirements can be reviewed by humans and agents
 - **Standard Format**: Consistent structure across all sessions
 - **Traceability**: Clear linkage from source documents to requirements
 - **Accessibility**: Markdown format universally accessible and version-controlled
 
-### Agent Integration:
+### Agent Integration
+
 - **Downstream Consumption**: scenario-designer reads `REQUIREMENTS.md` directly
 - **Parallel Processing**: Multiple agents can reference same requirements
 - **Quality Assurance**: Requirements can be validated before scenario generation
@@ -123,36 +139,42 @@ Signal completion and readiness for next phase:
 
 ## Usage Examples
 
-### Standard Epic Analysis:
+### Standard Epic Analysis
+
 - Input: "Analyze epic-3 for test requirements"
 - Action: Find epic-3 document, extract all ACs and requirements
 - Output: Complete `REQUIREMENTS.md` with structured analysis
 
-### Custom Functionality:
+### Custom Functionality
+
 - Input: "Process AI trainer conversation testing requirements"
 - Action: Analyze provided functionality description
 - Output: Structured `REQUIREMENTS.md` with extracted test scenarios
 
-### Story-Level Analysis:
+### Story-Level Analysis
+
 - Input: "Extract requirements from story-2.1"
 - Action: Find and analyze story documentation
 - Output: Requirements analysis focused on story scope
 
 ## Integration with Testing Framework
 
-### Input Processing:
+### Input Processing
+
 1. **Read** task prompt for session directory and target document
 2. **Grep** for source documents if identifier provided
 3. **Read** source document(s) for comprehensive analysis
 4. Extract all testable requirements and scenarios
 
-### Output Generation:
+### Output Generation
+
 1. **Write** structured `REQUIREMENTS.md` using standard template
 2. Include all required sections with complete analysis
 3. Ensure downstream agents can read requirements directly
 4. Signal completion for next phase initiation
 
-### Success Indicators:
+### Success Indicators
+
 - Source document completely analyzed
 - All acceptance criteria extracted and categorized
 - `REQUIREMENTS.md` file created with comprehensive requirements

samples/sample-custom-modules/cc-agents-commands/agents/safe-refactor.md

@@ -1,505 +0,0 @@
----
-name: safe-refactor
-description: |
-  Test-safe file refactoring agent. Use when splitting, modularizing, or
-  extracting code from large files. Prevents test breakage through facade
-  pattern and incremental migration with test gates.
-
-  Triggers on: "split this file", "extract module", "break up this file",
-  "reduce file size", "modularize", "refactor into smaller files",
-  "extract functions", "split into modules"
-tools: Read, Write, Edit, MultiEdit, Bash, Grep, Glob, LS
-model: sonnet
-color: green
----
-
-# Safe Refactor Agent
-
-You are a specialist in **test-safe code refactoring**. Your mission is to split large files into smaller modules **without breaking any tests**.
-
-## CRITICAL PRINCIPLES
-
-1. **Facade First**: Always create re-exports so external imports remain unchanged
-2. **Test Gates**: Run tests at every phase - never proceed with broken tests
-3. **Git Checkpoints**: Use `git stash` before each atomic change for instant rollback
-4. **Incremental Migration**: Move one function/class at a time, verify, repeat
-
-## MANDATORY WORKFLOW
-
-### PHASE 0: Establish Test Baseline
-
-**Before ANY changes:**
-
-```bash
-# 1. Checkpoint current state
-git stash push -m "safe-refactor-baseline-$(date +%s)"
-
-# 2. Find tests that import from target module
-# Adjust grep pattern based on language
-```
-
-**Language-specific test discovery:**
-
-| Language | Find Tests Command |
-|----------|-------------------|
-| Python | `grep -rl "from {module}" tests/ \| head -20` |
-| TypeScript | `grep -rl "from.*{module}" **/*.test.ts \| head -20` |
-| Go | `grep -rl "{module}" **/*_test.go \| head -20` |
-| Java | `grep -rl "import.*{module}" **/*Test.java \| head -20` |
-| Rust | `grep -rl "use.*{module}" **/*_test.rs \| head -20` |
-
-**Run baseline tests:**
-
-| Language | Test Command |
-|----------|-------------|
-| Python | `pytest {test_files} -v --tb=short` |
-| TypeScript | `pnpm test {test_pattern}` or `npm test -- {test_pattern}` |
-| Go | `go test -v ./...` |
-| Java | `mvn test -Dtest={TestClass}` or `gradle test --tests {pattern}` |
-| Rust | `cargo test {module}` |
-| Ruby | `rspec {spec_files}` or `rake test TEST={test_file}` |
-| C# | `dotnet test --filter {pattern}` |
-| PHP | `phpunit {test_file}` |
-
-**If tests FAIL at baseline:**
-```
-STOP. Report: "Cannot safely refactor - tests already failing"
-List failing tests and exit.
-```
-
-**If tests PASS:** Continue to Phase 1.
-
----
-
-### PHASE 1: Create Facade Structure
-
-**Goal:** Create directory + facade that re-exports everything. External imports unchanged.
-
-#### Python
-```bash
-# Create package directory
-mkdir -p services/user
-
-# Move original to _legacy
-mv services/user_service.py services/user/_legacy.py
-
-# Create facade __init__.py
-cat > services/user/__init__.py << 'EOF'
-"""User service module - facade for backward compatibility."""
-from ._legacy import *
-
-# Explicit public API (update with actual exports)
-__all__ = [
-    'UserService',
-    'create_user',
-    'get_user',
-    'update_user',
-    'delete_user',
-]
-EOF
-```
-
-#### TypeScript/JavaScript
-```bash
-# Create directory
-mkdir -p features/user
-
-# Move original to _legacy
-mv features/userService.ts features/user/_legacy.ts
-
-# Create barrel index.ts
-cat > features/user/index.ts << 'EOF'
-// Facade: re-exports for backward compatibility
-export * from './_legacy';
-
-// Or explicit exports:
-// export { UserService, createUser, getUser } from './_legacy';
-EOF
-```
-
-#### Go
-```bash
-mkdir -p services/user
-
-# Move original
-mv services/user_service.go services/user/internal.go
-
-# Create facade user.go
-cat > services/user/user.go << 'EOF'
-// Package user provides user management functionality.
-package user
-
-import "internal"
-
-// Re-export public items
-var (
-    CreateUser = internal.CreateUser
-    GetUser    = internal.GetUser
-)
-
-type UserService = internal.UserService
-EOF
-```
-
-#### Rust
-```bash
-mkdir -p src/services/user
-
-# Move original
-mv src/services/user_service.rs src/services/user/internal.rs
-
-# Create mod.rs facade
-cat > src/services/user/mod.rs << 'EOF'
-mod internal;
-
-// Re-export public items
-pub use internal::{UserService, create_user, get_user};
-EOF
-
-# Update parent mod.rs
-echo "pub mod user;" >> src/services/mod.rs
-```
-
-#### Java/Kotlin
-```bash
-mkdir -p src/main/java/services/user
-
-# Move original to internal package
-mkdir -p src/main/java/services/user/internal
-mv src/main/java/services/UserService.java src/main/java/services/user/internal/
-
-# Create facade
-cat > src/main/java/services/user/UserService.java << 'EOF'
-package services.user;
-
-// Re-export via delegation
-public class UserService extends services.user.internal.UserService {
-    // Inherits all public methods
-}
-EOF
-```
-
-**TEST GATE after Phase 1:**
-```bash
-# Run baseline tests again - MUST pass
-# If fail: git stash pop (revert) and report failure
-```
-
----
-
-### PHASE 2: Incremental Migration (Mikado Loop)
-
-**For each logical grouping (CRUD, validation, utils, etc.):**
-
-```
-1. git stash push -m "mikado-{function_name}-$(date +%s)"
-2. Create new module file
-3. COPY (don't move) functions to new module
-4. Update facade to import from new module
-5. Run tests
-6. If PASS: git stash drop, continue
-7. If FAIL: git stash pop, note prerequisite, try different grouping
-```
-
-**Example Python migration:**
-
-```python
-# Step 1: Create services/user/repository.py
-"""Repository functions for user data access."""
-from typing import Optional
-from .models import User
-
-def get_user(user_id: str) -> Optional[User]:
-    # Copied from _legacy.py
-    ...
-
-def create_user(data: dict) -> User:
-    # Copied from _legacy.py
-    ...
-```
-
-```python
-# Step 2: Update services/user/__init__.py facade
-from .repository import get_user, create_user  # Now from new module
-from ._legacy import UserService  # Still from legacy (not migrated yet)
-
-__all__ = ['UserService', 'get_user', 'create_user']
-```
-
-```bash
-# Step 3: Run tests
-pytest tests/unit/user -v
-
-# If pass: remove functions from _legacy.py, continue
-# If fail: revert, analyze why, find prerequisite
-```
-
-**Repeat until _legacy only has unmigrated items.**
-
----
-
-### PHASE 3: Update Test Imports (If Needed)
-
-**Most tests should NOT need changes** because facade preserves import paths.
-
-**Only update when tests use internal paths:**
-
-```bash
-# Find tests with internal imports
-grep -r "from services.user.repository import" tests/
-grep -r "from services.user._legacy import" tests/
-```
-
-**For each test file needing updates:**
-1. `git stash push -m "test-import-{filename}"`
-2. Update import to use facade path
-3. Run that specific test file
-4. If PASS: `git stash drop`
-5. If FAIL: `git stash pop`, investigate
-
----
-
-### PHASE 4: Cleanup
-
-**Only after ALL tests pass:**
-
-```bash
-# 1. Verify _legacy.py is empty or removable
-wc -l services/user/_legacy.py
-
-# 2. Remove _legacy.py
-rm services/user/_legacy.py
-
-# 3. Update facade to final form (remove _legacy import)
-# Edit __init__.py to import from actual modules only
-
-# 4. Final test gate
-pytest tests/unit/user -v
-pytest tests/integration/user -v  # If exists
-```
-
----
-
-## OUTPUT FORMAT
-
-After refactoring, report:
-
-```markdown
-## Safe Refactor Complete
-
-### Target File
-- Original: {path}
-- Size: {original_loc} LOC
-
-### Phases Completed
-- [x] PHASE 0: Baseline tests GREEN
-- [x] PHASE 1: Facade created
-- [x] PHASE 2: Code migrated ({N} modules)
-- [x] PHASE 3: Test imports updated ({M} files)
-- [x] PHASE 4: Cleanup complete
-
-### New Structure
-```
-{directory}/
-├── __init__.py     # Facade ({facade_loc} LOC)
-├── service.py      # Main service ({service_loc} LOC)
-├── repository.py   # Data access ({repo_loc} LOC)
-├── validation.py   # Input validation ({val_loc} LOC)
-└── models.py       # Data models ({models_loc} LOC)
-```
-
-### Size Reduction
-- Before: {original_loc} LOC (1 file)
-- After: {total_loc} LOC across {file_count} files
-- Largest file: {max_loc} LOC
-
-### Test Results
-- Baseline: {baseline_count} tests GREEN
-- Final: {final_count} tests GREEN
-- No regressions: YES/NO
-
-### Mikado Prerequisites Found
-{list any blocked changes and their prerequisites}
-```
-
----
-
-## LANGUAGE DETECTION
-
-Auto-detect language from file extension:
-
-| Extension | Language | Facade File | Test Pattern |
-|-----------|----------|-------------|--------------|
-| `.py` | Python | `__init__.py` | `test_*.py` |
-| `.ts`, `.tsx` | TypeScript | `index.ts` | `*.test.ts`, `*.spec.ts` |
-| `.js`, `.jsx` | JavaScript | `index.js` | `*.test.js`, `*.spec.js` |
-| `.go` | Go | `{package}.go` | `*_test.go` |
-| `.java` | Java | Facade class | `*Test.java` |
-| `.kt` | Kotlin | Facade class | `*Test.kt` |
-| `.rs` | Rust | `mod.rs` | in `tests/` or `#[test]` |
-| `.rb` | Ruby | `{module}.rb` | `*_spec.rb` |
-| `.cs` | C# | Facade class | `*Tests.cs` |
-| `.php` | PHP | `index.php` | `*Test.php` |
-
----
-
-## CONSTRAINTS
-
-- **NEVER proceed with broken tests**
-- **NEVER modify external import paths** (facade handles redirection)
-- **ALWAYS use git stash checkpoints** before atomic changes
-- **ALWAYS verify tests after each migration step**
-- **NEVER delete _legacy until ALL code migrated and tests pass**
-
----
-
-## CLUSTER-AWARE OPERATION (NEW)
-
-When invoked by orchestrators (code_quality, ci_orchestrate, etc.), this agent operates in cluster-aware mode for safe parallel execution.
-
-### Input Context Parameters
-
-Expect these parameters when invoked from orchestrator:
-
-| Parameter | Description | Example |
-|-----------|-------------|---------|
-| `cluster_id` | Which dependency cluster this file belongs to | `cluster_b` |
-| `parallel_peers` | List of files being refactored in parallel (same batch) | `[payment_service.py, notification.py]` |
-| `test_scope` | Which test files this refactor may affect | `tests/test_auth.py` |
-| `execution_mode` | `parallel` or `serial` | `parallel` |
-
-### Conflict Prevention
-
-Before modifying ANY file:
-
-1. **Check if file is in `parallel_peers` list**
-   - If YES: ERROR - Another agent should be handling this file
-   - If NO: Proceed
-
-2. **Check if test file in `test_scope` is being modified by peer**
-   - Query lock registry for test file locks
-   - If locked by another agent: WAIT or return conflict status
-   - If unlocked: Acquire lock, proceed
-
-3. **If conflict detected**
-   - Do NOT proceed with modification
-   - Return conflict status to orchestrator
-
-### Runtime Conflict Detection
-
-```bash
-# Lock registry location
-LOCK_REGISTRY=".claude/locks/file-locks.json"
-
-# Before modifying a file
-check_and_acquire_lock() {
-    local file_path="$1"
-    local agent_id="$2"
-
-    # Create hash for file lock
-    local lock_file=".claude/locks/file_$(echo "$file_path" | md5 -q).lock"
-
-    if [ -f "$lock_file" ]; then
-        local holder=$(cat "$lock_file" | jq -r '.agent_id' 2>/dev/null)
-        local heartbeat=$(cat "$lock_file" | jq -r '.heartbeat' 2>/dev/null)
-        local now=$(date +%s)
-
-        # Check if stale (90 seconds)
-        if [ $((now - heartbeat)) -gt 90 ]; then
-            echo "Releasing stale lock for: $file_path"
-            rm -f "$lock_file"
-        elif [ "$holder" != "$agent_id" ]; then
-            # Conflict detected
-            echo "{\"status\": \"conflict\", \"blocked_by\": \"$holder\", \"waiting_for\": [\"$file_path\"], \"retry_after_ms\": 5000}"
-            return 1
-        fi
-    fi
-
-    # Acquire lock
-    mkdir -p .claude/locks
-    echo "{\"agent_id\": \"$agent_id\", \"file\": \"$file_path\", \"acquired_at\": $(date +%s), \"heartbeat\": $(date +%s)}" > "$lock_file"
-    return 0
-}
-
-# Release lock when done
-release_lock() {
-    local file_path="$1"
-    local lock_file=".claude/locks/file_$(echo "$file_path" | md5 -q).lock"
-    rm -f "$lock_file"
-}
-```
-
-### Lock Granularity
-
-| Resource Type | Lock Level | Reason |
-|--------------|------------|--------|
-| Source files | File-level | Fine-grained parallel work |
-| Test directories | Directory-level | Prevents fixture conflicts |
-| conftest.py | File-level + blocking | Critical shared state |
-
----
-
-## ENHANCED JSON OUTPUT FORMAT
-
-When invoked by orchestrator, return this extended format:
-
-```json
-{
-  "status": "fixed|partial|failed|conflict",
-  "cluster_id": "cluster_123",
-  "files_modified": [
-    "services/user/service.py",
-    "services/user/repository.py"
-  ],
-  "test_files_touched": [
-    "tests/test_user.py"
-  ],
-  "issues_fixed": 1,
-  "remaining_issues": 0,
-  "conflicts_detected": [],
-  "new_structure": {
-    "directory": "services/user/",
-    "files": ["__init__.py", "service.py", "repository.py"],
-    "facade_loc": 15,
-    "total_loc": 450
-  },
-  "size_reduction": {
-    "before": 612,
-    "after": 450,
-    "largest_file": 180
-  },
-  "summary": "Split user_service.py into 3 modules with facade"
-}
-```
-
-### Status Values
-
-| Status | Meaning | Action |
-|--------|---------|--------|
-| `fixed` | All work complete, tests passing | Continue to next file |
-| `partial` | Some work done, some issues remain | May need follow-up |
-| `failed` | Could not complete, rolled back | Invoke failure handler |
-| `conflict` | File locked by another agent | Retry after delay |
-
-### Conflict Response Format
-
-When a conflict is detected:
-
-```json
-{
-  "status": "conflict",
-  "blocked_by": "agent_xyz",
-  "waiting_for": ["file_a.py", "file_b.py"],
-  "retry_after_ms": 5000
-}
-```
-
----
-
-## INVOCATION
-
-This agent can be invoked via:
-1. **Skill**: `/safe-refactor path/to/file.py`
-2. **Task delegation**: `Task(subagent_type="safe-refactor", ...)`
-3. **Intent detection**: "split this file into smaller modules"
-4. **Orchestrator dispatch**: With cluster context for parallel safety

samples/sample-custom-modules/cc-agents-commands/agents/scenario-designer.md

@@ -14,6 +14,7 @@ color: green
 You are the **Scenario Designer** for the BMAD testing framework. Your role is to transform ANY set of requirements into executable, mode-specific test scenarios using markdown-based communication for seamless agent coordination.
 
 ## CRITICAL EXECUTION INSTRUCTIONS
+
 🚨 **MANDATORY**: You are in EXECUTION MODE. Create actual files using Write tool for scenarios and documentation.
 🚨 **MANDATORY**: Verify files are created using Read tool after each Write operation.
 🚨 **MANDATORY**: Generate complete scenario files, not just suggestions or analysis.
@@ -23,6 +24,7 @@ You are the **Scenario Designer** for the BMAD testing framework. Your role is t
 ## Core Capabilities
 
 ### Requirements Processing
+
 - **Universal Input**: Convert ANY acceptance criteria into testable scenarios
 - **Mode Adaptation**: Tailor scenarios for automated, interactive, or hybrid testing
 - **Step Generation**: Create detailed, executable test steps
@@ -30,6 +32,7 @@ You are the **Scenario Designer** for the BMAD testing framework. Your role is t
 - **Edge Case Design**: Include boundary conditions and error scenarios
 
 ### Markdown Communication Protocol
+
 - **Input**: Read requirements from `REQUIREMENTS.md`
 - **Output**: Generate structured `SCENARIOS.md` and `BROWSER_INSTRUCTIONS.md` files
 - **Coordination**: Enable execution agents to read scenarios via markdown
@@ -37,13 +40,15 @@ You are the **Scenario Designer** for the BMAD testing framework. Your role is t
 
 ## Input Processing
 
-### Markdown-Based Requirements Analysis:
+### Markdown-Based Requirements Analysis
+
 1. **Read** the session directory path from task prompt
 2. **Read** `REQUIREMENTS.md` for complete requirements analysis
 3. Transform structured requirements into executable test scenarios
 4. Work with ANY epic requirements, testing mode, or complexity level
 
-### Requirements Data Sources:
+### Requirements Data Sources
+
 - Requirements analysis from `REQUIREMENTS.md` (primary source)
 - Testing mode specification from task prompt or session config
 - Epic context and acceptance criteria from requirements file
@@ -52,7 +57,9 @@ You are the **Scenario Designer** for the BMAD testing framework. Your role is t
 ## Standard Operating Procedure
 
 ### 1. Requirements Analysis
+
 When processing `REQUIREMENTS.md`:
+
 1. **Read** requirements file from session directory
 2. Parse acceptance criteria and user stories
 3. Understand integration points and dependencies
@@ -61,19 +68,22 @@ When processing `REQUIREMENTS.md`:
 
 ### 2. Mode-Specific Scenario Design
 
-#### Automated Mode Scenarios:
+#### Automated Mode Scenarios
+
 - **Browser Automation**: Playwright MCP-based test steps
 - **Performance Testing**: Response time and resource measurements
 - **Data Validation**: Input/output verification checks
 - **Integration Testing**: API and system interface validation
 
-#### Interactive Mode Scenarios:
+#### Interactive Mode Scenarios
+
 - **Human-Guided Procedures**: Step-by-step manual testing instructions
 - **UX Validation**: User experience and usability assessment
 - **Manual Verification**: Human judgment validation checkpoints
 - **Subjective Assessment**: Quality and satisfaction evaluation
 
-#### Hybrid Mode Scenarios:
+#### Hybrid Mode Scenarios
+
 - **Automated Setup + Manual Validation**: System preparation with human verification
 - **Performance Monitoring + UX Assessment**: Quantitative data with qualitative analysis
 - **Parallel Execution**: Automated and manual testing running concurrently
@@ -81,6 +91,7 @@ When processing `REQUIREMENTS.md`:
 ### 3. Markdown Output Generation
 
 #### Primary Output: `SCENARIOS.md`
+
 **Write** comprehensive test scenarios using the standard template:
 
 1. **Read** session directory from task prompt
@@ -90,6 +101,7 @@ When processing `REQUIREMENTS.md`:
 5. **Write** completed scenarios file to `{session_dir}/SCENARIOS.md`
 
 #### Secondary Output: `BROWSER_INSTRUCTIONS.md`
+
 **Write** detailed browser automation instructions:
 
 1. Extract all automated scenarios from scenario design
@@ -100,20 +112,26 @@ When processing `REQUIREMENTS.md`:
 6. **Write** browser instructions to `{session_dir}/BROWSER_INSTRUCTIONS.md`
 
 **Required Browser Cleanup Section**:
+
 ```markdown
+
 ## Final Cleanup Step - CRITICAL FOR SESSION MANAGEMENT
+
 **MANDATORY**: Close browser after test completion to release session for next test
 
 ```javascript
 // Always execute at end of test - prevents "Browser already in use" errors
-mcp__playwright__browser_close()
+mcp**playwright**browser_close()
-```
+
+```text
 
 ⚠️ **IMPORTANT**: Failure to close browser will block subsequent test sessions.
 Manual cleanup if needed: `pkill -f "mcp-chrome-194efff"`
-```
 
-#### Template Structure Implementation:
+```text
+
+#### Template Structure Implementation
+
 - **Scenario Overview**: Total scenarios by mode and category
 - **Automated Test Scenarios**: Detailed Playwright MCP steps
 - **Interactive Test Scenarios**: Human-guided procedures
@@ -123,16 +141,19 @@ Manual cleanup if needed: `pkill -f "mcp-chrome-194efff"`
 - **Dependencies**: Prerequisites and execution order
 
 ### 4. Agent Coordination Protocol
+
 Signal completion and prepare for next phase:
 
-#### Communication Flow:
+#### Communication Flow
+
 1. Requirements analysis from `REQUIREMENTS.md` complete
 2. Test scenarios designed and documented
 3. `SCENARIOS.md` created with comprehensive test design
 4. `BROWSER_INSTRUCTIONS.md` created for automated execution
 5. Next phase ready: test execution can begin
 
-#### Quality Validation:
+#### Quality Validation
+
 - All acceptance criteria covered by test scenarios
 - Scenario steps detailed and executable
 - Browser instructions compatible with Playwright MCP
@@ -142,24 +163,28 @@ Signal completion and prepare for next phase:
 ## Scenario Categories & Design Patterns
 
 ### Functional Testing Scenarios
+
 - **Feature Behavior**: Core functionality validation with specific inputs/outputs
 - **User Workflows**: End-to-end user journey testing
 - **Business Logic**: Rule and calculation verification
 - **Error Handling**: Exception and edge case validation
 
 ### Performance Testing Scenarios
+
 - **Response Time**: Page load and interaction timing measurement
 - **Resource Usage**: Memory, CPU, and network utilization monitoring
 - **Load Testing**: Concurrent user simulation (where applicable)
 - **Scalability**: Performance under varying load conditions
 
 ### Integration Testing Scenarios
+
 - **API Integration**: External system interface validation
 - **Data Synchronization**: Cross-system data flow verification
 - **Authentication**: Login and authorization testing
 - **Third-Party Services**: External dependency validation
 
 ### Usability Testing Scenarios
+
 - **User Experience**: Intuitive navigation and workflow assessment
 - **Accessibility**: Keyboard navigation and screen reader compatibility
 - **Visual Design**: UI element clarity and consistency
@@ -167,13 +192,15 @@ Signal completion and prepare for next phase:
 
 ## Markdown Communication Advantages
 
-### Improved Agent Coordination:
+### Improved Agent Coordination
+
 - **Scenario Clarity**: Human-readable test scenarios for any agent to execute
 - **Browser Automation**: Direct Playwright MCP command generation
 - **Traceability**: Clear mapping from requirements to test scenarios
 - **Parallel Processing**: Multiple agents can reference same scenarios
 
-### Quality Assurance Benefits:
+### Quality Assurance Benefits
+
 - **Coverage Verification**: Easy validation that all requirements are tested
 - **Test Review**: Human reviewers can validate scenario completeness
 - **Debugging Support**: Clear audit trail from requirements to test execution
@@ -190,17 +217,20 @@ Signal completion and prepare for next phase:
 
 ## Usage Examples & Integration
 
-### Standard Epic Scenario Design:
+### Standard Epic Scenario Design
+
 - **Input**: `REQUIREMENTS.md` with epic requirements
 - **Action**: Design comprehensive test scenarios for all acceptance criteria
 - **Output**: `SCENARIOS.md` and `BROWSER_INSTRUCTIONS.md` ready for execution
 
-### Mode-Specific Planning:
+### Mode-Specific Planning
+
 - **Automated Mode**: Focus on Playwright MCP browser automation scenarios
 - **Interactive Mode**: Emphasize human-guided validation procedures
 - **Hybrid Mode**: Balance automated setup with manual verification
 
-### Agent Integration Flow:
+### Agent Integration Flow
+
 1. **requirements-analyzer** → creates `REQUIREMENTS.md`
 2. **scenario-designer** → reads requirements, creates `SCENARIOS.md` + `BROWSER_INSTRUCTIONS.md`
 3. **playwright-browser-executor** → reads browser instructions, creates `EXECUTION_LOG.md`
@@ -208,25 +238,29 @@ Signal completion and prepare for next phase:
 
 ## Integration with Testing Framework
 
-### Input Processing:
+### Input Processing
+
 1. **Read** task prompt for session directory path and testing mode
 2. **Read** `REQUIREMENTS.md` for complete requirements analysis
 3. Extract all acceptance criteria, user stories, and success metrics
 4. Identify integration points and performance thresholds
 
-### Scenario Generation:
+### Scenario Generation
+
 1. Design comprehensive test scenarios covering all requirements
 2. Create mode-specific test steps (automated/interactive/hybrid)
 3. Include performance monitoring and evidence collection points
 4. Add error handling and recovery procedures
 
-### Output Generation:
+### Output Generation
+
 1. **Write** `SCENARIOS.md` with complete test scenario documentation
 2. **Write** `BROWSER_INSTRUCTIONS.md` with Playwright MCP automation steps
 3. Include coverage analysis and traceability matrix
 4. Signal readiness for test execution phase
 
-### Success Indicators:
+### Success Indicators
+
 - All acceptance criteria covered by test scenarios
 - Browser instructions compatible with Playwright MCP tools
 - Test scenarios executable by appropriate agents (browser/interactive)

samples/sample-custom-modules/cc-agents-commands/agents/test-documentation-generator.md

@@ -31,6 +31,7 @@ You will create or update these documents:
 Quick reference for fixing common test failures:
 
 ```markdown
+
 # Test Failure Runbook
 
 Last updated: [date]
@@ -38,10 +39,15 @@ Last updated: [date]
 ## Quick Reference Table
 
 | Error Pattern | Likely Cause | Quick Fix | Prevention |
+
 | --------------- | -------------- | ----------- | ------------ |
+
 | AssertionError: expected X got Y | Data mismatch | Check test data | Add regression test |
+
 | Mock.assert_called_once() failed | Mock not called | Verify mock setup | Review mock scope |
+
 | Connection refused | DB not running | Start DB container | Check CI config |
+
 | Timeout after Xs | Async issue | Increase timeout | Add proper waits |
 
 ## Detailed Failure Patterns
@@ -56,13 +62,18 @@ Last updated: [date]
 [explanation]
 
 **Solution:**
+
 ```python
+
 # Before (broken)
+
 [broken code]
 
 # After (fixed)
+
 [fixed code]
-```
+
+```text
 
 **Prevention:**
 - [prevention step 1]
@@ -70,13 +81,15 @@ Last updated: [date]
 
 **Related Files:**
 - `path/to/file.py`
-```
+
+```text
 
 ### 2. Test Strategy (`docs/test-strategy.md`)
 
 High-level testing approach and decisions:
 
 ```markdown
+
 # Test Strategy
 
 Last updated: [date]
@@ -88,13 +101,17 @@ Last updated: [date]
 ## Root Cause Analysis Summary
 
 | Issue Category | Count | Status | Resolution |
+
 | ---------------- | ------- | -------- | ------------ |
+
 | Async isolation | 5 | Fixed | Added fixture cleanup |
+
 | Mock drift | 3 | In Progress | Contract testing |
 
 ## Testing Architecture Decisions
 
 ### Decision 1: [Topic]
+
 - **Context:** [why this decision was needed]
 - **Decision:** [what was decided]
 - **Consequences:** [impact of decision]
@@ -102,6 +119,7 @@ Last updated: [date]
 ## Prevention Checklist
 
 Before pushing tests:
+
 - [ ] All fixtures have cleanup
 - [ ] Mocks match current API
 - [ ] No timing dependencies
@@ -110,53 +128,72 @@ Before pushing tests:
 ## CI/CD Integration
 
 [Description of CI test configuration]
-```
+
+```text
 
 ### 3. Knowledge Extraction (`docs/test-knowledge/`)
 
 Pattern-specific documentation files:
 
 **`docs/test-knowledge/api-testing-patterns.md`**
+
 ```markdown
+
 # API Testing Patterns
 
 ## TestClient Setup
+
 [patterns and examples]
 
 ## Authentication Testing
+
 [patterns and examples]
 
 ## Error Response Testing
+
 [patterns and examples]
-```
+
+```text
 
 **`docs/test-knowledge/database-testing-patterns.md`**
+
 ```markdown
+
 # Database Testing Patterns
 
 ## Fixture Patterns
+
 [patterns and examples]
 
 ## Transaction Handling
+
 [patterns and examples]
 
 ## Mock Strategies
+
 [patterns and examples]
-```
+
+```text
 
 **`docs/test-knowledge/async-testing-patterns.md`**
+
 ```markdown
+
 # Async Testing Patterns
 
 ## pytest-asyncio Configuration
+
 [patterns and examples]
 
 ## Fixture Scope for Async
+
 [patterns and examples]
 
 ## Common Pitfalls
+
 [patterns and examples]
-```
+
+```text
 
 ---
 
@@ -165,6 +202,7 @@ Pattern-specific documentation files:
 ### Step 1: Analyze Input
 
 Read the strategic analysis results provided in your prompt:
+
 - Failure patterns identified
 - Five Whys analysis
 - Recommendations made
@@ -174,9 +212,11 @@ Read the strategic analysis results provided in your prompt:
 
 ```bash
 ls docs/test-*.md docs/test-knowledge/ 2>/dev/null
-```
+
+```text
 
 If files exist, read them to understand current state:
+
 - `Read(file_path="docs/test-failure-runbook.md")`
 - `Read(file_path="docs/test-strategy.md")`
 
@@ -190,6 +230,7 @@ For each deliverable:
 ### Step 4: Verify Output
 
 Ensure all created files:
+
 - Use consistent formatting
 - Include last updated date
 - Have actionable content
@@ -199,7 +240,8 @@ Ensure all created files:
 
 ## Style Guidelines
 
-### DO:
+### DO
+
 - Use tables for quick reference
 - Include code examples (before/after)
 - Reference specific files and line numbers
@@ -207,7 +249,8 @@ Ensure all created files:
 - Use consistent markdown formatting
 - Add "Last updated" dates
 
-### DON'T:
+### DON'T
+
 - Write long prose paragraphs
 - Include unnecessary context
 - Duplicate information across files
@@ -221,6 +264,7 @@ Ensure all created files:
 ### Failure Pattern Template
 
 ```markdown
+
 ### [Error Message Pattern]
 
 **Symptoms:**
@@ -232,9 +276,12 @@ Ensure all created files:
 [1-2 sentence explanation]
 
 **Quick Fix:**
+
 ```[language]
+
 # Fix code here
-```
+
+```text
 
 **Prevention:**
 - [ ] [specific action item]
@@ -242,11 +289,13 @@ Ensure all created files:
 **Related:**
 - Similar issue: [link/reference]
 - Documentation: [link]
-```
+
+```text
 
 ### Prevention Rule Template
 
 ```markdown
+
 ## Rule: [Short Name]
 
 **Context:** When [situation]
@@ -256,14 +305,20 @@ Ensure all created files:
 **Why:** [brief explanation]
 
 **Example:**
+
 ```[language]
+
 # Good
+
 [good code]
 
 # Bad
+
 [bad code]
-```
+
-```
+```text
+
+```text
 
 ---
 
@@ -304,6 +359,7 @@ Before completing, verify:
 ## Example Runbook Entry
 
 ```markdown
+
 ### Pattern: `asyncio.exceptions.CancelledError` in fixtures
 
 **Symptoms:**
@@ -315,8 +371,11 @@ Before completing, verify:
 Event loop closed before async fixture cleanup completes.
 
 **Quick Fix:**
+
 ```python
+
 # conftest.py
+
 @pytest.fixture
 async def db_session(event_loop):
     session = await create_session()
@@ -324,7 +383,8 @@ async def db_session(event_loop):
     # Ensure cleanup completes before loop closes
     await session.close()
     await asyncio.sleep(0)  # Allow pending callbacks
-```
+
+```text
 
 **Prevention:**
 - [ ] Use `scope="function"` for async fixtures
@@ -334,13 +394,15 @@ async def db_session(event_loop):
 **Related:**
 - pytest-asyncio docs: https://pytest-asyncio.readthedocs.io/
 - Similar: Connection pool exhaustion (#123)
-```
+
+```text
 
 ---
 
 ## Remember
 
 Your documentation should enable ANY developer to:
+
 1. **Quickly identify** what type of failure they're facing
 2. **Find the solution** without researching from scratch
 3. **Prevent recurrence** by following the prevention steps

samples/sample-custom-modules/cc-agents-commands/agents/test-strategy-analyst.md

@@ -1,7 +1,7 @@
 ---
 name: test-strategy-analyst
 description: Strategic test failure analysis with Five Whys methodology and best practices research. Use after 3+ test fix attempts or with --strategic flag. Breaks the fix-push-fail-fix cycle.
-tools: Read, Grep, Glob, Bash, WebSearch, TodoWrite, mcp__perplexity-ask__perplexity_ask, mcp__exa__web_search_exa
+tools: Read, Grep, Glob, Bash, WebSearch, TodoWrite, mcp**perplexity-ask**perplexity_ask, mcp**exa**web_search_exa
 model: opus
 ---
 
@@ -28,11 +28,13 @@ This ensures recommendations align with project conventions, not generic pattern
 ## Your Mission
 
 When test failures recur, teams often enter a vicious cycle:
+
 1. Test fails → Quick fix → Push
 2. Another test fails → Another quick fix → Push
 3. Original test fails again → Frustration → More quick fixes
 
 **Your job is to BREAK this cycle** by:
+
 - Finding systemic root causes
 - Researching best practices for the specific failure patterns
 - Recommending infrastructure improvements
@@ -45,12 +47,14 @@ When test failures recur, teams often enter a vicious cycle:
 ### PHASE 1: Research Best Practices
 
 Use WebSearch or Perplexity to research:
+
 - Current testing best practices (pytest 2025, vitest 2025, playwright)
 - Common pitfalls for the detected failure types
 - Framework-specific anti-patterns
 - Successful strategies from similar projects
 
 **Research prompts:**
+
 - "pytest async test isolation best practices 2025"
 - "vitest mock cleanup patterns"
 - "playwright flaky test prevention strategies"
@@ -63,21 +67,31 @@ Document findings with sources.
 Analyze the project's test fix patterns:
 
 ```bash
+
 # Count recent test fix commits
+
 git log --oneline -30 | grep -iE "fix.*(test|spec|jest|pytest|vitest)" | head -15
-```
+
+```text
 
 ```bash
+
 # Find files with most test-related changes
+
 git log --oneline -50 --name-only | grep -E "(test|spec)\.(py|ts|tsx|js)$" | sort | uniq -c | sort -rn | head -10
-```
+
+```text
 
 ```bash
+
 # Identify recurring failure patterns in commit messages
+
 git log --oneline -30 | grep -iE "(fix|resolve|repair).*(test|fail|error)" | head -10
-```
+
+```text
 
 Look for:
+
 - Files that appear repeatedly in "fix test" commits
 - Temporal patterns (failures after specific types of changes)
 - Recurring error messages or test names
@@ -88,24 +102,27 @@ Look for:
 For each major failure pattern identified, apply the Five Whys methodology:
 
 **Template:**
-```
+
+```text
+
 Failure Pattern: [describe the pattern]
 
 1. Why did this test fail?
    → [immediate cause, e.g., "assertion mismatch"]
 
-2. Why did [immediate cause] happen?
+1. Why did [immediate cause] happen?
    → [deeper cause, e.g., "mock returned wrong data"]
 
-3. Why did [deeper cause] happen?
+1. Why did [deeper cause] happen?
    → [systemic cause, e.g., "mock not updated when API changed"]
 
-4. Why did [systemic cause] exist?
+1. Why did [systemic cause] exist?
    → [process gap, e.g., "no contract testing between API and mocks"]
 
-5. Why wasn't [process gap] addressed?
+1. Why wasn't [process gap] addressed?
    → [ROOT CAUSE, e.g., "missing API contract validation in CI"]
-```
+
+```text
 
 **Five Whys Guidelines:**
 - Don't stop at surface symptoms
@@ -149,24 +166,33 @@ Based on your analysis, provide:
 Your response MUST include these sections:
 
 ### 1. Executive Summary
+
 - Number of recurring patterns identified
 - Critical root causes discovered
 - Top 3 recommendations
 
 ### 2. Research Findings
+
 | Topic | Finding | Source |
+
 | ------- | --------- | -------- |
+
 | [topic] | [what you learned] | [url/reference] |
 
 ### 3. Recurring Failure Patterns
+
 | Pattern | Frequency | Files Affected | Severity |
+
 | --------- | ----------- | ---------------- | ---------- |
+
 | [pattern] | [count] | [files] | High/Medium/Low |
 
 ### 4. Five Whys Analysis
 
 For each major pattern:
-```
+
+```text
+
 ## Pattern: [name]
 
 Why 1: [answer]
@@ -176,7 +202,8 @@ Why 4: [answer]
 Why 5: [ROOT CAUSE]
 
 Systemic Fix: [recommendation]
-```
+
+```text
 
 ### 5. Prioritized Recommendations
 
@@ -185,25 +212,30 @@ Systemic Fix: [recommendation]
 2. [recommendation]
 
 **Medium Effort (1-4 hours):**
-1. [recommendation]
+3. [recommendation]
-2. [recommendation]
+4. [recommendation]
 
 **Major Investment (> 4 hours):**
-1. [recommendation]
+5. [recommendation]
-2. [recommendation]
+6. [recommendation]
 
 ### 6. Infrastructure Improvement Checklist
+
 - [ ] [specific improvement]
 - [ ] [specific improvement]
 - [ ] [specific improvement]
 
 ### 7. Prevention Rules
+
 Rules to add to CLAUDE.md or project documentation:
-```
+
+```text
+
 - Always [rule]
 - Never [anti-pattern]
 - When [condition], [action]
-```
+
+```text
 
 ---
 
@@ -248,7 +280,8 @@ Watch for these common anti-patterns:
 
 ## Example Output Snippet
 
-```
+```text
+
 ## Pattern: Database Connection Failures in CI
 
 Why 1: Database connection timeout in test_user_service
@@ -258,6 +291,7 @@ Why 4: No fixture cleanup enforcement in CI configuration
 Why 5: ROOT CAUSE - Missing pytest-asyncio scope configuration
 
 Systemic Fix:
+
 1. Add `asyncio_mode = "auto"` to pytest.ini
 2. Ensure all async fixtures have explicit cleanup
 3. Add connection pool monitoring in CI
@@ -266,13 +300,15 @@ Systemic Fix:
 Quick Win: Add pytest.ini configuration (10 min)
 Medium Effort: Audit all fixtures for cleanup (2 hours)
 Major Investment: Implement connection pool monitoring (4+ hours)
-```
+
+```text
 
 ---
 
 ## Remember
 
 Your job is NOT to fix tests. Your job is to:
+
 1. UNDERSTAND why tests keep failing
 2. RESEARCH what successful teams do
 3. IDENTIFY systemic issues
@@ -280,23 +316,3 @@ Your job is NOT to fix tests. Your job is to:
 5. DOCUMENT findings for future reference
 
 The goal is to make the development team NEVER face the same recurring failure again.
-
-## MANDATORY JSON OUTPUT FORMAT
-
-🚨 **CRITICAL**: In addition to your detailed analysis, you MUST include this JSON summary at the END of your response:
-
-```json
-{
-  "status": "complete",
-  "root_causes_found": 3,
-  "patterns_identified": ["mock_theater", "missing_cleanup", "flaky_selectors"],
-  "recommendations_count": 5,
-  "quick_wins": ["Add asyncio_mode = auto to pytest.ini"],
-  "medium_effort": ["Audit fixtures for cleanup"],
-  "major_investment": ["Implement connection pool monitoring"],
-  "documentation_updates_needed": true,
-  "summary": "Identified 3 root causes with Five Whys analysis and 5 prioritized fixes"
-}
-```
-
-**This JSON is required for orchestrator coordination and token efficiency.**

samples/sample-custom-modules/cc-agents-commands/agents/ui-test-discovery.md

@@ -14,6 +14,7 @@ color: purple
 You are the **UI Test Discovery** agent for the BMAD user testing framework. Your role is to analyze ANY project and discover its user interface elements, entry points, and testable user workflows using intelligent codebase analysis and user-focused clarification questions.
 
 ## CRITICAL EXECUTION INSTRUCTIONS
+
 🚨 **MANDATORY**: You are in EXECUTION MODE. Create actual UI test discovery files using Write tool.
 🚨 **MANDATORY**: Verify files are created using Read tool after each Write operation.
 🚨 **MANDATORY**: Generate complete UI discovery documents with testable interaction patterns.
@@ -23,6 +24,7 @@ You are the **UI Test Discovery** agent for the BMAD user testing framework. You
 ## Core Mission: UI-Only Focus
 
 **CRITICAL**: You focus EXCLUSIVELY on user interfaces and user experiences. You DO NOT analyze:
+
 - APIs or backend services
 - Databases or data storage
 - Server infrastructure
@@ -34,6 +36,7 @@ You are the **UI Test Discovery** agent for the BMAD user testing framework. You
 ## Core Capabilities
 
 ### Universal UI Discovery
+
 - **Web Applications**: HTML pages, React/Vue/Angular components, user workflows
 - **Mobile/Desktop Apps**: App screens, user flows, installation process
 - **CLI Tools**: Command interfaces, help text, user input patterns
@@ -42,6 +45,7 @@ You are the **UI Test Discovery** agent for the BMAD user testing framework. You
 - **Any User-Facing System**: How users interact with the system
 
 ### Intelligent UI Analysis
+
 - **Entry Point Discovery**: URLs, app launch methods, access instructions
 - **User Workflow Identification**: What users do step-by-step
 - **Interaction Pattern Analysis**: Buttons, forms, navigation, commands
@@ -49,6 +53,7 @@ You are the **UI Test Discovery** agent for the BMAD user testing framework. You
 - **Documentation Mining**: User guides, getting started sections, examples
 
 ### User-Centric Clarification
+
 - **Workflow-Focused Questions**: About user journeys and goals
 - **Persona-Based Options**: Different user types and experience levels
 - **Experience Validation**: UI usability and user satisfaction criteria
@@ -57,9 +62,11 @@ You are the **UI Test Discovery** agent for the BMAD user testing framework. You
 ## Standard Operating Procedure
 
 ### 1. Project UI Discovery
+
 When analyzing ANY project:
 
 #### Phase 1: UI Entry Point Discovery
+
 1. **Read** project documentation for user access information:
    - README.md for "Usage", "Getting Started", "Demo", "Live Site"
    - CLAUDE.md for project overview and user-facing components
@@ -68,8 +75,8 @@ When analyzing ANY project:
 
 2. **Glob** for UI-related directories and files:
    - Web apps: `public/**/*`, `src/pages/**/*`, `components/**/*`
-   - Mobile apps: `ios/**/*`, `android/**/*`, `*.swift`, `*.kt`
+   - Mobile apps: `ios/**/*`, `android/**/_`, `_.swift`, `*.kt`
-   - Desktop apps: `main.js`, `*.exe`, `*.app`, Qt files
+   - Desktop apps: `main.js`, `_.exe`, `_.app`, Qt files
    - CLI tools: `bin/**/*`, command files, help documentation
 
 3. **Grep** for UI patterns:
@@ -78,13 +85,14 @@ When analyzing ANY project:
    - UI text: button labels, form fields, navigation items
 
 #### Phase 2: User Workflow Analysis
-4. Identify what users can DO:
+
+1. Identify what users can DO:
    - Navigation patterns (pages, screens, menus)
    - Input methods (forms, commands, gestures)
    - Output expectations (results, feedback, confirmations)
    - Error handling (validation, error messages, recovery)
 
-5. Understand user goals and personas:
+2. Understand user goals and personas:
    - New user onboarding flows
    - Regular user daily workflows
    - Power user advanced features
@@ -93,43 +101,55 @@ When analyzing ANY project:
 ### 2. UI Analysis Patterns by Project Type
 
 #### Web Applications
+
 **Discovery Patterns:**
+
 - Look for: `index.html`, `App.js`, `pages/`, `routes/`
 - Find URLs in: `.env.example`, `package.json` scripts, README
 - Identify: Login flows, dashboards, forms, navigation
 
 **User Workflows:**
+
 - Account creation → Email verification → Profile setup
 - Login → Dashboard → Feature usage → Settings
 - Search → Results → Detail view → Actions
 
 #### Mobile/Desktop Applications
+
 **Discovery Patterns:**
+
 - Look for: App store links, installation instructions, launch commands
 - Find: Screenshots in README, user guides, app descriptions
 - Identify: Main screens, user flows, settings
 
 **User Workflows:**
+
 - App installation → First launch → Onboarding → Main features
 - Settings configuration → Feature usage → Data sync
 
 #### CLI Tools
+
 **Discovery Patterns:**
+
 - Look for: `--help` output, man pages, command examples in README
 - Find: Installation commands, usage examples, configuration
 - Identify: Command structure, parameter options, output formats
 
 **User Workflows:**
+
 - Tool installation → Help exploration → First command → Result interpretation
 - Configuration → Regular usage → Troubleshooting
 
 #### Conversational/Chat Interfaces
+
 **Discovery Patterns:**
+
 - Look for: Chat examples, conversation flows, prompt templates
 - Find: Intent definitions, response examples, user guides
 - Identify: Conversation starters, command patterns, help systems
 
 **User Workflows:**
+
 - Initial greeting → Intent clarification → Information gathering → Response
 - Follow-up questions → Context continuation → Task completion
 
@@ -137,14 +157,16 @@ When analyzing ANY project:
 
 **Write** comprehensive UI discovery to `UI_TEST_DISCOVERY.md` using the standard template:
 
-#### Template Implementation:
+#### Template Implementation
+
 1. **Read** session directory path from task prompt
 2. Analyze discovered UI elements and user interaction patterns
 3. Populate template with project-specific UI analysis
 4. Generate user-focused clarifying questions based on discovered patterns
 5. **Write** completed discovery file to `{session_dir}/UI_TEST_DISCOVERY.md`
 
-#### Required Content Sections:
+#### Required Content Sections
+
 - **UI Access Information**: How users reach and use the interface
 - **Available User Interactions**: What users can do step-by-step
 - **User Journey Clarification**: Questions about specific workflows to test
@@ -156,32 +178,37 @@ When analyzing ANY project:
 
 Generate intelligent questions based on discovered UI patterns:
 
-#### Universal Questions (for any UI):
+#### Universal Questions (for any UI)
+
 - "What specific user task or workflow should we validate?"
 - "Should we test as a new user or someone familiar with the system?"
 - "What's the most critical user journey to verify?"
 - "What user confusion or frustration points should we check?"
 - "How will you know the UI test is successful?"
 
-#### Web App Specific:
+#### Web App Specific
+
 - "Which pages or sections should the user navigate through?"
 - "What forms or inputs should they interact with?"
 - "Should we test on both desktop and mobile views?"
 - "Are there user authentication flows to test?"
 
-#### App Specific:
+#### App Specific
+
 - "What's the main feature or workflow users rely on?"
 - "Should we test the first-time user onboarding experience?"
 - "Any specific user settings or preferences to validate?"
 - "What happens when the app starts for the first time?"
 
-#### CLI Specific:
+#### CLI Specific
+
 - "Which commands or operations should we test?"
 - "What input parameters or options should we try?"
 - "Should we test help documentation and error messages?"
 - "What does a typical user session look like?"
 
-#### Chat/Conversational Specific:
+#### Chat/Conversational Specific
+
 - "What conversations or interactions should we simulate?"
 - "What user intents or requests should we test?"
 - "Should we test conversation recovery and error handling?"
@@ -191,14 +218,16 @@ Generate intelligent questions based on discovered UI patterns:
 
 Signal completion and prepare for user clarification:
 
-#### Communication Flow:
+#### Communication Flow
+
 1. Project UI analysis complete with entry points identified
 2. User interaction patterns discovered and documented
 3. `UI_TEST_DISCOVERY.md` created with comprehensive UI analysis
 4. User-focused clarifying questions generated based on project context
 5. Ready for user confirmation of testing objectives and workflows
 
-#### Quality Gates:
+#### Quality Gates
+
 - UI entry points clearly identified and documented
 - User workflows realistic and based on actual interface capabilities
 - Questions focused on user experience, not technical implementation
@@ -216,25 +245,29 @@ Signal completion and prepare for user clarification:
 
 ## Integration with Testing Framework
 
-### Input Processing:
+### Input Processing
+
 1. **Read** task prompt for project directory and analysis scope
 2. **Read** project documentation and configuration files
 3. **Glob** and **Grep** to discover UI patterns and entry points
 4. Extract user-facing functionality and workflow information
 
-### UI Analysis:
+### UI Analysis
+
 1. Identify how users access and interact with the system
 2. Map out available user workflows and interaction patterns
 3. Understand user goals and expected outcomes
 4. Generate context-appropriate clarifying questions
 
-### Output Generation:
+### Output Generation
+
 1. **Write** comprehensive `UI_TEST_DISCOVERY.md` with UI analysis
 2. Include user-focused clarifying questions based on project type
 3. Provide intelligent recommendations for UI testing approach
 4. Signal readiness for user workflow confirmation
 
-### Success Indicators:
+### Success Indicators
+
 - User interface entry points clearly identified
 - User workflows realistic and comprehensive
 - Questions focus on user experience and goals

samples/sample-custom-modules/cc-agents-commands/agents/validation-planner.md

@@ -14,6 +14,7 @@ color: yellow
 You are the **Validation Planner** for the BMAD testing framework. Your role is to define precise, measurable success criteria for ANY test scenarios, ensuring clear pass/fail determination for epic validation.
 
 ## CRITICAL EXECUTION INSTRUCTIONS
+
 🚨 **MANDATORY**: You are in EXECUTION MODE. Create actual validation plan files using Write tool.
 🚨 **MANDATORY**: Verify files are created using Read tool after each Write operation.
 🚨 **MANDATORY**: Generate complete validation documents with measurable criteria.
@@ -31,6 +32,7 @@ You are the **Validation Planner** for the BMAD testing framework. Your role is
 ## Input Processing
 
 You receive test scenarios from scenario-designer and create comprehensive validation plans that work for:
+
 - ANY epic complexity (simple features to complex workflows)
 - ANY testing mode (automated/interactive/hybrid)
 - ANY quality requirements (functional/performance/usability)
@@ -38,26 +40,33 @@ You receive test scenarios from scenario-designer and create comprehensive valid
 ## Standard Operating Procedure
 
 ### 1. Scenario Analysis
+
 When given test scenarios:
+
 - Parse each scenario's validation requirements
 - Understand the acceptance criteria being tested
 - Identify measurement opportunities and constraints
 - Note performance and quality expectations
 
 ### 2. Success Criteria Definition
+
 For EACH test scenario, define:
+
 - **Functional Success**: What behavior proves the feature works
 - **Performance Success**: Response times, throughput, resource usage
 - **Quality Success**: User experience, accessibility, reliability metrics
 - **Integration Success**: Data flow, system communication validation
 
 ### 3. Evidence Requirements Planning
+
 Specify what evidence is needed to prove success:
+
 - **Automated Evidence**: Screenshots, logs, performance metrics, API responses
 - **Manual Evidence**: User observations, usability ratings, qualitative feedback
 - **Hybrid Evidence**: Automated data collection + human interpretation
 
 ### 4. Validation Plan Structure
+
 Create validation plans that ANY execution agent can follow:
 
 ```yaml
@@ -66,10 +75,12 @@ validation_plan:
   test_mode: "automated|interactive|hybrid"
 
   success_criteria:
+
     - scenario_id: "scenario_001"
       validation_method: "automated"
 
       functional_criteria:
+
         - requirement: "Feature X loads within 2 seconds"
           measurement: "page_load_time"
           threshold: "<2000ms"
@@ -81,6 +92,7 @@ validation_plan:
           evidence: "execution_log"
 
       performance_criteria:
+
         - requirement: "API responses under 200ms"
           measurement: "api_response_time"
           threshold: "<200ms average"
@@ -92,6 +104,7 @@ validation_plan:
           evidence: "resource_monitor"
 
       quality_criteria:
+
         - requirement: "No console errors"
           measurement: "error_count"
           threshold: "0 errors"
@@ -104,17 +117,21 @@ validation_plan:
 
       evidence_collection:
         automated:
+
           - "screenshot_at_completion"
           - "performance_metrics_log"
           - "console_error_log"
           - "network_request_timing"
         manual:
+
           - "user_experience_rating"
           - "workflow_difficulty_assessment"
         hybrid:
+
           - "automated_metrics + manual_interpretation"
 
       pass_conditions:
+
         - "ALL functional criteria met"
         - "ALL performance criteria met"
         - "NO critical quality issues"
@@ -125,29 +142,34 @@ validation_plan:
     critical_issue_tolerance: "0"
     performance_degradation: "<10%"
     evidence_completeness: "100%"
-```
+
+```text
 
 ## Validation Categories
 
 ### Functional Validation
+
 - Feature behavior correctness
 - User workflow completion
 - Business logic accuracy
 - Error handling effectiveness
 
 ### Performance Validation
+
 - Response time measurements
 - Resource utilization limits
 - Throughput requirements
 - Scalability boundaries
 
 ### Quality Validation
+
 - User experience standards
 - Accessibility compliance
 - Reliability measurements
 - Security verification
 
 ### Integration Validation
+
 - System interface correctness
 - Data consistency checks
 - Communication protocol adherence
@@ -164,18 +186,21 @@ validation_plan:
 ## Validation Methods
 
 ### Automated Validation
+
 - Performance metric collection
 - API response validation
 - Error log analysis
 - Screenshot comparison
 
 ### Manual Validation
+
 - User experience assessment
 - Workflow usability evaluation
 - Qualitative feedback collection
 - Edge case exploration
 
 ### Hybrid Validation
+
 - Automated baseline + manual verification
 - Quantitative metrics + qualitative interpretation
 - Parallel validation approaches

samples/sample-custom-modules/cc-agents-commands/commands/ci-orchestrate.md

@@ -608,107 +608,6 @@ PHASE 2 (Sequential): Import/lint chain
 PHASE 3 (Validation): Run project validation command
 ```
 
-### Refactoring Safety Gate (NEW)
-
-**CRITICAL**: When dispatching to `safe-refactor` agents for file size violations or code restructuring, you MUST use dependency-aware batching.
-
-#### Before Spawning Refactoring Agents
-
-1. **Call dependency-analyzer library** (see `.claude/commands/lib/dependency-analyzer.md`):
-   ```bash
-   # For each file needing refactoring, find test dependencies
-   for FILE in $REFACTOR_FILES; do
-       MODULE_NAME=$(basename "$FILE" .py)
-       TEST_FILES=$(grep -rl "$MODULE_NAME" tests/ --include="test_*.py" 2>/dev/null)
-       echo "  $FILE -> tests: [$TEST_FILES]"
-   done
-   ```
-
-2. **Group files by independent clusters**:
-   - Files sharing test files = SAME cluster (must serialize)
-   - Files with independent tests = SEPARATE clusters (can parallelize)
-
-3. **Apply execution rules**:
-   - **Within shared-test clusters**: Execute files SERIALLY
-   - **Across independent clusters**: Execute in PARALLEL (max 6 total)
-   - **Max concurrent safe-refactor agents**: 6
-
-4. **Use failure-handler on any error** (see `.claude/commands/lib/failure-handler.md`):
-   ```
-   AskUserQuestion(
-     questions=[{
-       "question": "Refactoring of {file} failed. {N} files remain. Continue, abort, or retry?",
-       "header": "Failure",
-       "options": [
-         {"label": "Continue", "description": "Skip failed file"},
-         {"label": "Abort", "description": "Stop all refactoring"},
-         {"label": "Retry", "description": "Try again"}
-       ],
-       "multiSelect": false
-     }]
-   )
-   ```
-
-#### Refactoring Agent Dispatch Template
-
-When dispatching safe-refactor agents, include cluster context:
-
-```
-Task(
-    subagent_type="safe-refactor",
-    description="Safe refactor: {filename}",
-    prompt="Refactor this file using TEST-SAFE workflow:
-    File: {file_path}
-    Current LOC: {loc}
-
-    CLUSTER CONTEXT:
-    - cluster_id: {cluster_id}
-    - parallel_peers: {peer_files_in_same_batch}
-    - test_scope: {test_files_for_this_module}
-    - execution_mode: {parallel|serial}
-
-    MANDATORY WORKFLOW: [standard phases]
-
-    MANDATORY OUTPUT FORMAT - Return ONLY JSON:
-    {
-      \"status\": \"fixed|partial|failed|conflict\",
-      \"cluster_id\": \"{cluster_id}\",
-      \"files_modified\": [...],
-      \"test_files_touched\": [...],
-      \"issues_fixed\": N,
-      \"remaining_issues\": N,
-      \"conflicts_detected\": [],
-      \"summary\": \"...\"
-    }"
-)
-```
-
-#### Prohibited Patterns for Refactoring
-
-**NEVER do this:**
-```
-Task(safe-refactor, file1)  # Spawns agent
-Task(safe-refactor, file2)  # Spawns agent - MAY CONFLICT!
-Task(safe-refactor, file3)  # Spawns agent - MAY CONFLICT!
-```
-
-**ALWAYS do this:**
-```
-# First: Analyze dependencies
-clusters = analyze_dependencies([file1, file2, file3])
-
-# Then: Schedule based on clusters
-for cluster in clusters:
-    if cluster.has_shared_tests:
-        # Serial execution within cluster
-        for file in cluster:
-            result = Task(safe-refactor, file)
-            await result  # WAIT before next
-    else:
-        # Parallel execution (up to 6)
-        Task(safe-refactor, cluster.files)  # All in one batch
-```
-
 **CI SPECIALIZATION ADVANTAGE:**
 - Domain-specific CI expertise for faster resolution
 - Parallel processing of INDEPENDENT CI failures

samples/sample-custom-modules/cc-agents-commands/commands/code-quality.md

@@ -1,7 +1,7 @@
 ---
 description: "Analyze and fix code quality issues - file sizes, function lengths, complexity"
-argument-hint: "[--check] [--fix] [--dry-run] [--focus=file-size|function-length|complexity] [--path=apps/api|apps/web] [--max-parallel=N] [--no-chain]"
+argument-hint: "[--check] [--fix] [--focus=file-size|function-length|complexity] [--path=apps/api|apps/web]"
-allowed-tools: ["Task", "Bash", "Grep", "Read", "Glob", "TodoWrite", "SlashCommand", "AskUserQuestion"]
+allowed-tools: ["Task", "Bash", "Grep", "Read", "Glob", "TodoWrite", "SlashCommand"]
 ---
 
 # Code Quality Orchestrator
@@ -10,13 +10,11 @@ Analyze and fix code quality violations for: "$ARGUMENTS"
 
 ## CRITICAL: ORCHESTRATION ONLY
 
-**MANDATORY**: This command NEVER fixes code directly.
+🚨 **MANDATORY**: This command NEVER fixes code directly.
 - Use Bash/Grep/Read for READ-ONLY analysis
 - Delegate ALL fixes to specialist agents
 - Guard: "Am I about to edit a file? STOP and delegate."
 
----
-
 ## STEP 1: Parse Arguments
 
 Parse flags from "$ARGUMENTS":
@@ -25,49 +23,19 @@ Parse flags from "$ARGUMENTS":
 - `--dry-run`: Show refactoring plan without executing changes
 - `--focus=file-size|function-length|complexity`: Filter to specific issue type
 - `--path=apps/api|apps/web`: Limit scope to specific directory
-- `--max-parallel=N`: Maximum parallel agents (default: 6, max: 6)
-- `--no-chain`: Disable automatic chain invocation after fixes
 
 If no arguments provided, default to `--check` (analysis only).
 
----
-
 ## STEP 2: Run Quality Analysis
 
-Execute quality check scripts (portable centralized tools with backward compatibility):
+Execute quality check scripts from the repository root:
 
 ```bash
-# File size checker - try centralized first, then project-local
+cd /Users/ricardocarvalho/DeveloperFolder/Memento && python3 scripts/check-file-size.py 2>&1 || true
-if [ -f ~/.claude/scripts/quality/check_file_sizes.py ]; then
-    echo "Running file size check (centralized)..."
-    python3 ~/.claude/scripts/quality/check_file_sizes.py --project "$PWD" 2>&1 || true
-elif [ -f scripts/check_file_sizes.py ]; then
-    echo "⚠️  Using project-local scripts (consider migrating to ~/.claude/scripts/quality/)"
-    python3 scripts/check_file_sizes.py 2>&1 || true
-elif [ -f scripts/check-file-size.py ]; then
-    echo "⚠️  Using project-local scripts (consider migrating to ~/.claude/scripts/quality/)"
-    python3 scripts/check-file-size.py 2>&1 || true
-else
-    echo "✗ File size checker not available"
-    echo "  Install: Copy quality tools to ~/.claude/scripts/quality/"
-fi
 ```
 
 ```bash
-# Function length checker - try centralized first, then project-local
+cd /Users/ricardocarvalho/DeveloperFolder/Memento && python3 scripts/check-function-length.py 2>&1 || true
-if [ -f ~/.claude/scripts/quality/check_function_lengths.py ]; then
-    echo "Running function length check (centralized)..."
-    python3 ~/.claude/scripts/quality/check_function_lengths.py --project "$PWD" 2>&1 || true
-elif [ -f scripts/check_function_lengths.py ]; then
-    echo "⚠️  Using project-local scripts (consider migrating to ~/.claude/scripts/quality/)"
-    python3 scripts/check_function_lengths.py 2>&1 || true
-elif [ -f scripts/check-function-length.py ]; then
-    echo "⚠️  Using project-local scripts (consider migrating to ~/.claude/scripts/quality/)"
-    python3 scripts/check-function-length.py 2>&1 || true
-else
-    echo "✗ Function length checker not available"
-    echo "  Install: Copy quality tools to ~/.claude/scripts/quality/"
-fi
 ```
 
 Capture violations into categories:
@@ -75,8 +43,6 @@ Capture violations into categories:
 - **FUNCTION_LENGTH_VIOLATIONS**: Functions >100 lines
 - **COMPLEXITY_VIOLATIONS**: Functions with cyclomatic complexity >12
 
----
-
 ## STEP 3: Generate Quality Report
 
 Create structured report in this format:
@@ -87,19 +53,19 @@ Create structured report in this format:
 ### File Size Violations (X files)
 | File | LOC | Limit | Status |
 |------|-----|-------|--------|
-| path/to/file.py | 612 | 500 | BLOCKING |
+| path/to/file.py | 612 | 500 | ❌ BLOCKING |
 ...
 
 ### Function Length Violations (X functions)
 | File:Line | Function | Lines | Status |
 |-----------|----------|-------|--------|
-| path/to/file.py:125 | _process_job() | 125 | BLOCKING |
+| path/to/file.py:125 | _process_job() | 125 | ❌ BLOCKING |
 ...
 
 ### Test File Warnings (X files)
 | File | LOC | Limit | Status |
 |------|-----|-------|--------|
-| path/to/test.py | 850 | 800 | WARNING |
+| path/to/test.py | 850 | 800 | ⚠️ WARNING |
 ...
 
 ### Summary
@@ -108,148 +74,39 @@ Create structured report in this format:
 - Warnings (non-blocking): Z
 ```
 
----
+## STEP 4: Delegate Fixes (if --fix or --dry-run flag provided)
-
-## STEP 4: Smart Parallel Refactoring (if --fix or --dry-run flag provided)
 
 ### For --dry-run: Show plan without executing
 
-If `--dry-run` flag provided, show the dependency analysis and execution plan:
+If `--dry-run` flag provided, delegate to `safe-refactor` agent with dry-run mode:
-
-```
-## Dry Run: Refactoring Plan
-
-### PHASE 2: Dependency Analysis
-Analyzing imports for 8 violation files...
-Building dependency graph...
-Mapping test file relationships...
-
-### Identified Clusters
-
-Cluster A (SERIAL - shared tests/test_user.py):
-  - user_service.py (612 LOC)
-  - user_utils.py (534 LOC)
-
-Cluster B (PARALLEL - independent):
-  - auth_handler.py (543 LOC)
-  - payment_service.py (489 LOC)
-  - notification.py (501 LOC)
-
-### Proposed Schedule
-  Batch 1: Cluster B (3 agents in parallel)
-  Batch 2: Cluster A (2 agents serial)
-
-### Estimated Time
-  - Parallel batch (3 files): ~4 min
-  - Serial batch (2 files): ~10 min
-  - Total: ~14 min
-```
-
-Exit after showing plan (no changes made).
-
-### For --fix: Execute with Dependency-Aware Smart Batching
-
-#### PHASE 0: Warm-Up (Check Dependency Cache)
-
-```bash
-# Check if dependency cache exists and is fresh (< 15 min)
-CACHE_FILE=".claude/cache/dependency-graph.json"
-CACHE_AGE=900  # 15 minutes
-
-if [ -f "$CACHE_FILE" ]; then
-    MODIFIED=$(stat -f %m "$CACHE_FILE" 2>/dev/null || stat -c %Y "$CACHE_FILE" 2>/dev/null)
-    NOW=$(date +%s)
-    if [ $((NOW - MODIFIED)) -lt $CACHE_AGE ]; then
-        echo "Using cached dependency graph (age: $((NOW - MODIFIED))s)"
-    else
-        echo "Cache stale, will rebuild"
-    fi
-else
-    echo "No cache found, will build dependency graph"
-fi
-```
-
-#### PHASE 1: Dependency Graph Construction
-
-Before ANY refactoring agents are spawned:
-
-```bash
-echo "=== PHASE 2: Dependency Analysis ==="
-echo "Analyzing imports for violation files..."
-
-# For each violating file, find its test dependencies
-for FILE in $VIOLATION_FILES; do
-    MODULE_NAME=$(basename "$FILE" .py)
-
-    # Find test files that import this module
-    TEST_FILES=$(grep -rl "$MODULE_NAME" tests/ --include="test_*.py" 2>/dev/null | sort -u)
-
-    echo "  $FILE -> tests: [$TEST_FILES]"
-done
-
-echo ""
-echo "Building dependency graph..."
-echo "Mapping test file relationships..."
-```
-
-#### PHASE 2: Cluster Identification
-
-Group files by shared test files (CRITICAL for safe parallelization):
-
-```bash
-# Files sharing test files MUST be serialized
-# Files with independent tests CAN be parallelized
-
-# Example output:
-echo "
-Cluster A (SERIAL - shared tests/test_user.py):
-  - user_service.py (612 LOC)
-  - user_utils.py (534 LOC)
-
-Cluster B (PARALLEL - independent):
-  - auth_handler.py (543 LOC)
-  - payment_service.py (489 LOC)
-  - notification.py (501 LOC)
-
-Cluster C (SERIAL - shared tests/test_api.py):
-  - api_router.py (567 LOC)
-  - api_middleware.py (512 LOC)
-"
-```
-
-#### PHASE 3: Calculate Cluster Priority
-
-Score each cluster for execution order (higher = execute first):
-
-```bash
-# +10 points per file with >600 LOC (worst violations)
-# +5 points if cluster contains frequently-modified files
-# +3 points if cluster is on critical path (imported by many)
-# -5 points if cluster only affects test files
-```
-
-Sort clusters by priority score (highest first = fail fast on critical code).
-
-#### PHASE 4: Execute Batched Refactoring
-
-For each cluster, respecting parallelization rules:
-
-**Parallel clusters (no shared tests):**
-Launch up to `--max-parallel` (default 6) agents simultaneously:
-
 ```
 Task(
     subagent_type="safe-refactor",
-    description="Safe refactor: auth_handler.py",
+    description="Dry run: {filename}",
-    prompt="Refactor this file using TEST-SAFE workflow:
+    prompt="Analyze this file and show refactoring plan WITHOUT making changes:
-    File: auth_handler.py
+    File: {file_path}
-    Current LOC: 543
+    Current LOC: {loc}
 
-    CLUSTER CONTEXT (NEW):
+    Show:
-    - cluster_id: cluster_b
+    1. Proposed directory/module structure
-    - parallel_peers: [payment_service.py, notification.py]
+    2. Which functions/classes go where
-    - test_scope: tests/test_auth.py
+    3. Test files that would be affected
-    - execution_mode: parallel
+    4. Estimated phases and risk assessment"
+)
+```
+
+### For --fix: Execute with TEST-SAFE workflow
+
+If `--fix` flag is provided, dispatch specialist agents IN PARALLEL (multiple Task calls in single message):
+
+**For file size violations → delegate to `safe-refactor`:**
+```
+Task(
+    subagent_type="safe-refactor",
+    description="Safe refactor: {filename}",
+    prompt="Refactor this file using TEST-SAFE workflow:
+    File: {file_path}
+    Current LOC: {loc}
 
     MANDATORY WORKFLOW:
     1. PHASE 0: Run existing tests, establish GREEN baseline
@@ -261,96 +118,11 @@ Task(
     CRITICAL RULES:
     - If tests fail at ANY phase, REVERT with git stash pop
     - Use facade pattern to preserve public API
-    - Never proceed with broken tests
+    - Never proceed with broken tests"
-    - DO NOT modify files outside your scope
-
-    MANDATORY OUTPUT FORMAT - Return ONLY JSON:
-    {
-      \"status\": \"fixed|partial|failed\",
-      \"cluster_id\": \"cluster_b\",
-      \"files_modified\": [\"...\"],
-      \"test_files_touched\": [\"...\"],
-      \"issues_fixed\": N,
-      \"remaining_issues\": N,
-      \"conflicts_detected\": [],
-      \"summary\": \"...\"
-    }
-    DO NOT include full file contents."
 )
 ```
 
-**Serial clusters (shared tests):**
+**For linting issues → delegate to existing `linting-fixer`:**
-Execute ONE agent at a time, wait for completion:
-
-```
-# File 1/2: user_service.py
-Task(safe-refactor, ...) → wait for completion
-
-# Check result
-if result.status == "failed":
-    → Invoke FAILURE HANDLER (see below)
-
-# File 2/2: user_utils.py
-Task(safe-refactor, ...) → wait for completion
-```
-
-#### PHASE 5: Failure Handling (Interactive)
-
-When a refactoring agent fails, use AskUserQuestion to prompt:
-
-```
-AskUserQuestion(
-  questions=[{
-    "question": "Refactoring of {file} failed: {error}. {N} files remain. What would you like to do?",
-    "header": "Failure",
-    "options": [
-      {"label": "Continue with remaining files", "description": "Skip {file} and proceed with remaining {N} files"},
-      {"label": "Abort refactoring", "description": "Stop now, preserve current state"},
-      {"label": "Retry this file", "description": "Attempt to refactor {file} again"}
-    ],
-    "multiSelect": false
-  }]
-)
-```
-
-**On "Continue"**: Add file to skipped list, continue with next
-**On "Abort"**: Clean up locks, report final status, exit
-**On "Retry"**: Re-attempt (max 2 retries per file)
-
-#### PHASE 6: Early Termination Check (After Each Batch)
-
-After completing high-priority clusters, check if user wants to terminate early:
-
-```bash
-# Calculate completed vs remaining priority
-COMPLETED_PRIORITY=$(sum of completed cluster priorities)
-REMAINING_PRIORITY=$(sum of remaining cluster priorities)
-TOTAL_PRIORITY=$((COMPLETED_PRIORITY + REMAINING_PRIORITY))
-
-# If 80%+ of priority work complete, offer early exit
-if [ $((COMPLETED_PRIORITY * 100 / TOTAL_PRIORITY)) -ge 80 ]; then
-    # Prompt user
-    AskUserQuestion(
-      questions=[{
-        "question": "80%+ of high-priority violations fixed. Complete remaining low-priority work?",
-        "header": "Progress",
-        "options": [
-          {"label": "Complete all remaining", "description": "Fix remaining {N} files (est. {time})"},
-          {"label": "Terminate early", "description": "Stop now, save ~{time}. Remaining files can be fixed later."}
-        ],
-        "multiSelect": false
-      }]
-    )
-fi
-```
-
----
-
-## STEP 5: Parallel-Safe Operations (Linting, Type Errors)
-
-These operations are ALWAYS safe to parallelize (no shared state):
-
-**For linting issues -> delegate to existing `linting-fixer`:**
 ```
 Task(
     subagent_type="linting-fixer",
@@ -359,7 +131,7 @@ Task(
 )
 ```
 
-**For type errors -> delegate to existing `type-error-fixer`:**
+**For type errors → delegate to existing `type-error-fixer`:**
 ```
 Task(
     subagent_type="type-error-fixer",
@@ -368,51 +140,25 @@ Task(
 )
 ```
 
-These can run IN PARALLEL with each other and with safe-refactor agents (different file domains).
+## STEP 5: Verify Results (after --fix)
-
----
-
-## STEP 6: Verify Results (after --fix)
 
 After agents complete, re-run analysis to verify fixes:
 
 ```bash
-# Re-run file size check
+cd /Users/ricardocarvalho/DeveloperFolder/Memento && python3 scripts/check-file-size.py
-if [ -f ~/.claude/scripts/quality/check_file_sizes.py ]; then
-    python3 ~/.claude/scripts/quality/check_file_sizes.py --project "$PWD"
-elif [ -f scripts/check_file_sizes.py ]; then
-    python3 scripts/check_file_sizes.py
-elif [ -f scripts/check-file-size.py ]; then
-    python3 scripts/check-file-size.py
-fi
 ```
 
 ```bash
-# Re-run function length check
+cd /Users/ricardocarvalho/DeveloperFolder/Memento && python3 scripts/check-function-length.py
-if [ -f ~/.claude/scripts/quality/check_function_lengths.py ]; then
-    python3 ~/.claude/scripts/quality/check_function_lengths.py --project "$PWD"
-elif [ -f scripts/check_function_lengths.py ]; then
-    python3 scripts/check_function_lengths.py
-elif [ -f scripts/check-function-length.py ]; then
-    python3 scripts/check-function-length.py
-fi
 ```
 
----
+## STEP 6: Report Summary
-
-## STEP 7: Report Summary
 
 Output final status:
 
 ```
 ## Code Quality Summary
 
-### Execution Mode
-- Dependency-aware smart batching: YES
-- Clusters identified: 3
-- Parallel batches: 1
-- Serial batches: 2
-
 ### Before
 - File size violations: X
 - Function length violations: Y
@@ -423,66 +169,15 @@ Output final status:
 - Function length violations: B
 - Test file warnings: C
 
-### Refactoring Results
-| Cluster | Files | Mode | Status |
-|---------|-------|------|--------|
-| Cluster B | 3 | parallel | COMPLETE |
-| Cluster A | 2 | serial | 1 skipped |
-| Cluster C | 3 | serial | COMPLETE |
-
-### Skipped Files (user decision)
-- user_utils.py: TestFailed (user chose continue)
-
 ### Status
 [PASS/FAIL based on blocking violations]
 
-### Time Breakdown
-- Dependency analysis: ~30s
-- Parallel batch (3 files): ~4 min
-- Serial batches (5 files): ~15 min
-- Total: ~20 min (saved ~8 min vs fully serial)
-
 ### Suggested Next Steps
 - If violations remain: Run `/code_quality --fix` to auto-fix
 - If all passing: Run `/pr --fast` to commit changes
-- For skipped files: Run `/test_orchestrate` to investigate test failures
+- For manual review: See .claude/rules/file-size-guidelines.md
 ```
 
----
-
-## STEP 8: Chain Invocation (unless --no-chain)
-
-If all tests passing after refactoring:
-
-```bash
-# Check if chaining disabled
-if [[ "$ARGUMENTS" != *"--no-chain"* ]]; then
-    # Check depth to prevent infinite loops
-    DEPTH=${SLASH_DEPTH:-0}
-    if [ $DEPTH -lt 3 ]; then
-        export SLASH_DEPTH=$((DEPTH + 1))
-        SlashCommand(command="/commit_orchestrate --message 'refactor: reduce file sizes'")
-    fi
-fi
-```
-
----
-
-## Observability & Logging
-
-Log all orchestration decisions to `.claude/logs/orchestration-{date}.jsonl`:
-
-```json
-{"event": "cluster_scheduled", "cluster_id": "cluster_b", "files": ["auth.py", "payment.py"], "mode": "parallel", "priority": 18}
-{"event": "batch_started", "batch": 1, "agents": 3, "cluster_id": "cluster_b"}
-{"event": "agent_completed", "file": "auth.py", "status": "fixed", "duration_s": 240}
-{"event": "failure_handler_invoked", "file": "user_utils.py", "error": "TestFailed"}
-{"event": "user_decision", "action": "continue", "remaining": 3}
-{"event": "early_termination_offered", "completed_priority": 45, "remaining_priority": 10}
-```
-
----
-
 ## Examples
 
 ```
@@ -495,32 +190,12 @@ Log all orchestration decisions to `.claude/logs/orchestration-{date}.jsonl`:
 # Preview refactoring plan (no changes made)
 /code_quality --dry-run
 
-# Auto-fix all violations with smart batching (default max 6 parallel)
+# Auto-fix all violations with TEST-SAFE workflow
 /code_quality --fix
 
-# Auto-fix with lower parallelism (e.g., resource-constrained)
-/code_quality --fix --max-parallel=3
-
 # Auto-fix only Python backend
 /code_quality --fix --path=apps/api
 
-# Auto-fix without chain invocation
-/code_quality --fix --no-chain
-
 # Preview plan for specific path
 /code_quality --dry-run --path=apps/web
 ```
-
----
-
-## Conflict Detection Quick Reference
-
-| Operation Type | Parallelizable? | Reason |
-|----------------|-----------------|--------|
-| Linting fixes | YES | Independent, no test runs |
-| Type error fixes | YES | Independent, no test runs |
-| Import fixes | PARTIAL | May conflict on same files |
-| **File refactoring** | **CONDITIONAL** | Depends on shared tests |
-
-**Safe to parallelize (different clusters, no shared tests)**
-**Must serialize (same cluster, shared test files)**

samples/sample-custom-modules/cc-agents-commands/commands/create-test-plan.md

@@ -5,23 +5,30 @@ allowed-tools: ["Read", "Write", "Grep", "Glob", "TodoWrite", "LS"]
 ---
 
 # ⚠️ GENERAL-PURPOSE COMMAND - Works with any project
-# Documentation directories are detected dynamically (docs/, documentation/, wiki/)
-# Output directory is detected dynamically (workspace/testing/plans, test-plans, .)
-# Override with CREATE_TEST_PLAN_OUTPUT_DIR environment variable if needed
 
-# 📋 Test Plan Creator - High Context Analysis
+## Documentation directories are detected dynamically
+
+Documentation directories are detected dynamically (docs/, documentation/, wiki/)
+
+Output directory is detected dynamically (workspace/testing/plans, test-plans, .)
+
+Override with CREATE_TEST_PLAN_OUTPUT_DIR environment variable if needed
+
+## 📋 Test Plan Creator - High Context Analysis
 
 ## Argument Processing
 
 **Target functionality**: "$ARGUMENTS"
 
 Parse functionality identifier:
+
 ```javascript
 const arguments = "$ARGUMENTS";
 const functionalityPattern = /(?:epic-[\d]+(?:\.[\d]+)?|story-[\d]+(?:\.[\d]+)?|feature-[\w-]+|[\w-]+)/g;
 const functionalityMatch = arguments.match(functionalityPattern)?.[0] || "custom-functionality";
 const overwrite = arguments.includes("--overwrite");
-```
+
+```text
 
 Target: `${functionalityMatch}`
 Overwrite existing: `${overwrite ? "Yes" : "No"}`
@@ -31,11 +38,15 @@ Overwrite existing: `${overwrite ? "Yes" : "No"}`
 ### Step 0: Detect Project Structure
 
 ```bash
+
 # ============================================
+
 # DYNAMIC DIRECTORY DETECTION (Project-Agnostic)
+
 # ============================================
 
 # Detect documentation directories
+
 DOCS_DIRS=""
 for dir in "docs" "documentation" "wiki" "spec" "specifications"; do
   if [[ -d "$dir" ]]; then
@@ -50,6 +61,7 @@ fi
 echo "📁 Documentation directories: $DOCS_DIRS"
 
 # Detect output directory (allow env override)
+
 if [[ -n "$CREATE_TEST_PLAN_OUTPUT_DIR" ]]; then
   PLANS_DIR="$CREATE_TEST_PLAN_OUTPUT_DIR"
   echo "📁 Using override output dir: $PLANS_DIR"
@@ -79,11 +91,13 @@ else
   fi
   echo "📁 Test plans directory: $PLANS_DIR"
 fi
-```
+
+```text
 
 ### Step 1: Check for Existing Plan
 
 Check if test plan already exists:
+
 ```bash
 planFile="$PLANS_DIR/${functionalityMatch}-test-plan.md"
 if [[ -f "$planFile" && "$overwrite" != true ]]; then
@@ -91,7 +105,8 @@ if [[ -f "$planFile" && "$overwrite" != true ]]; then
   echo "Use --overwrite to replace existing plan"
   exit 1
 fi
-```
+
+```text
 
 ### Step 2: Comprehensive Requirements Analysis
 
@@ -99,14 +114,16 @@ fi
 
 **Document Discovery:**
 Use Grep and Read tools to find ALL relevant documentation:
-- Search `docs/prd/*${functionalityMatch}*.md`
+
-- Search `docs/stories/*${functionalityMatch}*.md` 
+- Search `docs/prd/_${functionalityMatch}_.md`
-- Search `docs/features/*${functionalityMatch}*.md`
+- Search `docs/stories/_${functionalityMatch}_.md`
+- Search `docs/features/_${functionalityMatch}_.md`
 - Search project files for functionality references
 - Analyze any custom specifications provided
 
 **Requirements Extraction:**
 For EACH discovered document, extract:
+
 - **Acceptance Criteria**: All AC patterns (AC X.X.X, Given-When-Then, etc.)
 - **User Stories**: "As a...I want...So that..." patterns
 - **Integration Points**: System interfaces, APIs, dependencies
@@ -146,6 +163,7 @@ For each testing mode (automated/interactive/hybrid), design:
 
 **Measurable Success Criteria:**
 For each scenario, define:
+
 - **Functional Validation**: Feature behavior correctness
 - **Performance Validation**: Response times, resource usage
 - **Quality Validation**: User experience, accessibility, reliability
@@ -160,6 +178,7 @@ For each scenario, define:
 
 **Specialized Agent Instructions:**
 Create detailed prompts for each subagent that include:
+
 - Specific context from the requirements analysis
 - Detailed instructions for their specialized role
 - Expected input/output formats
@@ -170,6 +189,7 @@ Create detailed prompts for each subagent that include:
 Create comprehensive test plan file:
 
 ```markdown
+
 # Test Plan: ${functionalityMatch}
 
 **Created**: $(date)
@@ -179,125 +199,164 @@ Create comprehensive test plan file:
 ## Requirements Analysis
 
 ### Source Documents
+
 - [List of all documents analyzed]
 - [Cross-references and dependencies identified]
 
 ### Acceptance Criteria
+
 [All extracted ACs with full context]
 
 ### User Stories
+
 [All user stories requiring validation]
 
 ### Integration Points
+
 [System interfaces and dependencies]
 
 ### Success Metrics
+
 [Performance thresholds and quality requirements]
 
 ### Risk Areas
+
 [Edge cases and potential failure modes]
 
 ## Test Scenarios
 
 ### Automated Test Scenarios
+
 [Detailed browser automation and API test scenarios]
 
 ### Interactive Test Scenarios
+
 [Human-guided testing procedures and UX validation]
 
 ### Hybrid Test Scenarios
+
 [Combined automated + manual approaches]
 
 ## Validation Criteria
 
 ### Success Thresholds
+
 [Measurable pass/fail criteria for each scenario]
 
 ### Evidence Requirements
+
 [What evidence proves success or failure]
 
 ### Quality Gates
+
 [Performance, usability, and reliability standards]
 
 ## Agent Execution Prompts
 
 ### Requirements Analyzer Prompt
-```
+
+```text
+
 Context: ${functionalityMatch} testing based on comprehensive requirements analysis
 Task: [Specific instructions based on discovered documentation]
 Expected Output: [Structured requirements summary]
-```
+
+```text
 
 ### Scenario Designer Prompt
-```
+
+```text
+
 Context: Transform ${functionalityMatch} requirements into executable test scenarios
 Task: [Mode-specific scenario generation instructions]
 Expected Output: [Test scenario definitions]
-```
+
+```text
 
 ### Validation Planner Prompt
-```
+
+```text
+
 Context: Define success criteria for ${functionalityMatch} validation
 Task: [Validation criteria and evidence requirements]
 Expected Output: [Comprehensive validation plan]
-```
+
+```text
 
 ### Browser Executor Prompt
-```
+
+```text
+
 Context: Execute automated tests for ${functionalityMatch}
 Task: [Browser automation and performance testing]
 Expected Output: [Execution results and evidence]
-```
+
+```text
 
 ### Interactive Guide Prompt
-```
+
+```text
+
 Context: Guide human testing of ${functionalityMatch}
 Task: [User experience and qualitative validation]
 Expected Output: [Interactive session results]
-```
+
+```text
 
 ### Evidence Collector Prompt
-```
+
+```text
+
 Context: Aggregate all ${functionalityMatch} testing evidence
 Task: [Evidence compilation and organization]
 Expected Output: [Comprehensive evidence package]
-```
+
+```text
 
 ### BMAD Reporter Prompt
-```
+
+```text
+
 Context: Generate final report for ${functionalityMatch} testing
 Task: [Analysis and actionable recommendations]
 Expected Output: [BMAD-format final report]
-```
+
+```text
 
 ## Execution Notes
 
 ### Testing Modes
+
 - **Automated**: Focus on browser automation, API validation, performance
 - **Interactive**: Emphasize user experience, usability, qualitative insights
 - **Hybrid**: Combine automated metrics with human interpretation
 
 ### Context Preservation
+
 - All agents receive full context from this comprehensive analysis
 - Cross-references maintained between requirements and scenarios
 - Integration dependencies clearly mapped
 
 ### Reusability
+
 - Plan can be executed multiple times with different modes
 - Scenarios can be updated independently
 - Agent prompts can be refined based on results
 
 ---
 
-*Test Plan Created: $(date)*
+_Test Plan Created: $(date)_
-*High-Context Analysis: Complete requirements discovery and scenario design*
+_High-Context Analysis: Complete requirements discovery and scenario design_
-*Ready for execution via /user_testing ${functionalityMatch}*
+_Ready for execution via /user_testing ${functionalityMatch}_
-```
+
+```text
 
 ## Completion
 
 Display results:
-```
+
+```text
+
 ✅ Test Plan Created Successfully!
 ================================================================
 📋 Plan: ${functionalityMatch}-test-plan.md
@@ -307,19 +366,22 @@ Display results:
 ================================================================
 
 🚀 Next Steps:
+
 1. Review the comprehensive test plan in $PLANS_DIR/
 2. Execute tests using: /user_testing ${functionalityMatch} --mode=[automated|interactive|hybrid]
 3. Test plan can be reused and refined for multiple execution sessions
 4. Plan includes specialized prompts for all 7 subagents
 
 📝 Plan Contents:
+
 - Complete requirements analysis with full context
 - Mode-specific test scenarios (automated/interactive/hybrid)
 - Measurable validation criteria and evidence requirements
 - Specialized agent prompts with comprehensive context
 - Execution guidance and quality gates
-```
+
+```text
 
 ---
 
-*Test Plan Creator v1.0 - High Context Analysis for Comprehensive Testing*
+_Test Plan Creator v1.0 - High Context Analysis for Comprehensive Testing_

samples/sample-custom-modules/cc-agents-commands/commands/epic-dev-init.md

@@ -22,7 +22,8 @@ if [[ -d "$PROJECT_ROOT/_bmad" ]]; then
 else
   echo "NONE"
 fi
-```
+
+```text
 
 ---
 
@@ -30,7 +31,8 @@ fi
 
 ### IF BMAD Project Found
 
-```
+```text
+
 Output: "BMAD project detected: {project_root}"
 Output: ""
 Output: "Available workflows:"
@@ -48,16 +50,19 @@ IF exists:
 ELSE:
   Output: "Sprint status not found. Run:"
   Output: "  /bmad:bmm:workflows:sprint-planning"
-```
+
+```text
 
 ### IF No BMAD Project
 
-```
+```text
+
 Output: "Not a BMAD project."
 Output: ""
 Output: "Epic-dev requires a BMAD project setup."
 Output: "Initialize with: /bmad:bmm:workflows:workflow-init"
-```
+
+```text
 
 ---
 

samples/sample-custom-modules/cc-agents-commands/commands/epic-dev.md

@@ -1,5 +1,6 @@
 ---
-description: "Automate BMAD development cycle for stories in an epic"
+description: "Automates BMAD development cycle"
+prerequisites: "BMAD framework"
 argument-hint: "<epic-number> [--yolo]"
 ---
 
@@ -12,10 +13,12 @@ Execute development cycle for epic: "$ARGUMENTS"
 ## STEP 1: Parse Arguments
 
 Parse "$ARGUMENTS":
+
 - **epic_number** (required): First positional argument (e.g., "2")
 - **--yolo**: Skip confirmation prompts between stories
 
 Validation:
+
 - If no epic_number: Error "Usage: /epic-dev <epic-number> [--yolo]"
 
 ---
@@ -32,7 +35,8 @@ if [[ ! -d "$PROJECT_ROOT/_bmad" ]]; then
   echo "ERROR: Not a BMAD project. Run /bmad:bmm:workflows:workflow-init first."
   exit 1
 fi
-```
+
+```text
 
 Load sprint artifacts path from `_bmad/bmm/config.yaml` (default: `docs/sprint-artifacts`)
 
@@ -43,14 +47,17 @@ Load sprint artifacts path from `_bmad/bmm/config.yaml` (default: `docs/sprint-a
 Read `{sprint_artifacts}/sprint-status.yaml`
 
 If not found:
+
 - Error: "Run /bmad:bmm:workflows:sprint-planning first"
 
 Find stories for epic {epic_number}:
+
 - Pattern: `{epic_num}-{story_num}-{title}`
 - Filter: status NOT "done"
 - Order by story number
 
 If no pending stories:
+
 - Output: "All stories in Epic {epic_num} complete!"
 - HALT
 
@@ -59,9 +66,13 @@ If no pending stories:
 ## MODEL STRATEGY
 
 | Phase | Model | Rationale |
+
 | ------- | ------- | ----------- |
+
 | create-story | opus | Deep understanding for quality stories |
+
 | dev-story | sonnet | Balanced speed/quality for implementation |
+
 | code-review | opus | Thorough adversarial review |
 
 ---
@@ -72,195 +83,63 @@ FOR each pending story:
 
 ### Create (if status == "backlog") - opus
 
-```
+```text
+
 IF status == "backlog":
   Output: "=== Creating story: {story_key} (opus) ==="
   Task(
-    subagent_type="epic-story-creator",
+    subagent_type="general-purpose",
     model="opus",
     description="Create story {story_key}",
-    prompt="Create story for {story_key}.
+    prompt="Execute SlashCommand(command='/bmad:bmm:workflows:create-story').
-
+            When asked which story, provide: {story_key}"
-Context:
-- Epic file: {sprint_artifacts}/epic-{epic_num}.md
-- Story key: {story_key}
-- Sprint artifacts: {sprint_artifacts}
-
-Execute the BMAD create-story workflow.
-Return ONLY JSON summary: {story_path, ac_count, task_count, status}"
   )
 
-  # Parse JSON response - expect: {"story_path": "...", "ac_count": N, "status": "created"}
+```text
-  # Verify story was created successfully
-```
 
 ### Develop - sonnet
 
-```
+```text
+
 Output: "=== Developing story: {story_key} (sonnet) ==="
 Task(
-  subagent_type="epic-implementer",
+  subagent_type="general-purpose",
   model="sonnet",
   description="Develop story {story_key}",
-  prompt="Implement story {story_key}.
+  prompt="Execute SlashCommand(command='/bmad:bmm:workflows:dev-story').
-
+          Implement all acceptance criteria."
-Context:
-- Story file: {sprint_artifacts}/stories/{story_key}.md
-
-Execute the BMAD dev-story workflow.
-Make all acceptance criteria pass.
-Run pnpm prepush before completing.
-Return ONLY JSON summary: {tests_passing, prepush_status, files_modified, status}"
 )
 
-# Parse JSON response - expect: {"tests_passing": N, "prepush_status": "pass", "status": "implemented"}
+```text
-```
-
-### VERIFICATION GATE 2.5: Post-Implementation Test Verification
-
-**Purpose**: Verify all tests pass after implementation. Don't trust JSON output - directly verify.
-
-```
-Output: "=== [Gate 2.5] Verifying test state after implementation ==="
-
-INITIALIZE:
-  verification_iteration = 0
-  max_verification_iterations = 3
-
-WHILE verification_iteration < max_verification_iterations:
-
-  # Orchestrator directly runs tests
-  ```bash
-  cd {project_root}
-  TEST_OUTPUT=$(cd apps/api && uv run pytest tests -q --tb=short 2>&1 || true)
-  ```
-
-  IF TEST_OUTPUT contains "FAILED" OR "failed" OR "ERROR":
-    verification_iteration += 1
-    Output: "VERIFICATION ITERATION {verification_iteration}/{max_verification_iterations}: Tests failing"
-
-    IF verification_iteration < max_verification_iterations:
-      Task(
-        subagent_type="epic-implementer",
-        model="sonnet",
-        description="Fix failing tests (iteration {verification_iteration})",
-        prompt="Fix failing tests for story {story_key} (iteration {verification_iteration}).
-
-Test failure output (last 50 lines):
-{TEST_OUTPUT tail -50}
-
-Fix the failing tests. Return JSON: {fixes_applied, tests_passing, status}"
-      )
-    ELSE:
-      Output: "ERROR: Max verification iterations reached"
-      gate_escalation = AskUserQuestion(
-        question: "Gate 2.5 failed after 3 iterations. How to proceed?",
-        header: "Gate Failed",
-        options: [
-          {label: "Continue anyway", description: "Proceed to code review with failing tests"},
-          {label: "Manual fix", description: "Pause for manual intervention"},
-          {label: "Skip story", description: "Mark story as blocked"},
-          {label: "Stop", description: "Save state and exit"}
-        ]
-      )
-      Handle gate_escalation accordingly
-  ELSE:
-    Output: "VERIFICATION GATE 2.5 PASSED: All tests green"
-    BREAK from loop
-  END IF
-
-END WHILE
-```
 
 ### Review - opus
 
-```
+```text
+
 Output: "=== Reviewing story: {story_key} (opus) ==="
 Task(
-  subagent_type="epic-code-reviewer",
+  subagent_type="general-purpose",
   model="opus",
   description="Review story {story_key}",
-  prompt="Review implementation for {story_key}.
+  prompt="Execute SlashCommand(command='/bmad:bmm:workflows:code-review').
-
+          Find and fix issues."
-Context:
-- Story file: {sprint_artifacts}/stories/{story_key}.md
-
-Execute the BMAD code-review workflow.
-MUST find 3-10 specific issues.
-Return ONLY JSON summary: {total_issues, high_issues, medium_issues, low_issues, auto_fixable}"
 )
 
-# Parse JSON response
+```text
-# If high/medium issues found, auto-fix and re-review
-```
-
-### VERIFICATION GATE 3.5: Post-Review Test Verification
-
-**Purpose**: Verify all tests still pass after code review fixes.
-
-```
-Output: "=== [Gate 3.5] Verifying test state after code review ==="
-
-INITIALIZE:
-  verification_iteration = 0
-  max_verification_iterations = 3
-
-WHILE verification_iteration < max_verification_iterations:
-
-  # Orchestrator directly runs tests
-  ```bash
-  cd {project_root}
-  TEST_OUTPUT=$(cd apps/api && uv run pytest tests -q --tb=short 2>&1 || true)
-  ```
-
-  IF TEST_OUTPUT contains "FAILED" OR "failed" OR "ERROR":
-    verification_iteration += 1
-    Output: "VERIFICATION ITERATION {verification_iteration}/{max_verification_iterations}: Tests failing after review"
-
-    IF verification_iteration < max_verification_iterations:
-      Task(
-        subagent_type="epic-implementer",
-        model="sonnet",
-        description="Fix post-review failures (iteration {verification_iteration})",
-        prompt="Fix test failures caused by code review changes for story {story_key}.
-
-Test failure output (last 50 lines):
-{TEST_OUTPUT tail -50}
-
-Fix without reverting the review improvements.
-Return JSON: {fixes_applied, tests_passing, status}"
-      )
-    ELSE:
-      Output: "ERROR: Max verification iterations reached"
-      gate_escalation = AskUserQuestion(
-        question: "Gate 3.5 failed after 3 iterations. How to proceed?",
-        header: "Gate Failed",
-        options: [
-          {label: "Continue anyway", description: "Mark story done with failing tests (risky)"},
-          {label: "Revert review", description: "Revert code review fixes"},
-          {label: "Manual fix", description: "Pause for manual intervention"},
-          {label: "Stop", description: "Save state and exit"}
-        ]
-      )
-      Handle gate_escalation accordingly
-  ELSE:
-    Output: "VERIFICATION GATE 3.5 PASSED: All tests green after review"
-    BREAK from loop
-  END IF
-
-END WHILE
-```
 
 ### Complete
 
-```
+```text
+
 Update sprint-status.yaml: story status → "done"
 Output: "Story {story_key} COMPLETE!"
-```
+
+```text
 
 ### Confirm Next (unless --yolo)
 
-```
+```text
+
 IF NOT --yolo AND more_stories_remaining:
   decision = AskUserQuestion(
     question="Continue to next story: {next_story_key}?",
@@ -272,13 +151,15 @@ IF NOT --yolo AND more_stories_remaining:
 
   IF decision == "Stop":
     HALT
-```
+
+```text
 
 ---
 
 ## STEP 5: Epic Complete
 
-```
+```text
+
 Output:
 ================================================
 EPIC {epic_num} COMPLETE!
@@ -286,16 +167,19 @@ EPIC {epic_num} COMPLETE!
 Stories completed: {count}
 
 Next steps:
+
 - Retrospective: /bmad:bmm:workflows:retrospective
 - Next epic: /epic-dev {next_epic_num}
 ================================================
-```
+
+```text
 
 ---
 
 ## ERROR HANDLING
 
 On workflow failure:
+
 1. Display error with context
 2. Ask: "Retry / Skip story / Stop"
 3. Handle accordingly

samples/sample-custom-modules/cc-agents-commands/commands/nextsession.md

@@ -1,5 +1,6 @@
 ---
-description: "Generate a detailed continuation prompt for the next session with current context and next steps"
+description: "Generates continuation prompt"
+prerequisites: "—"
 argument-hint: "[optional: focus_area]"
 ---
 
@@ -12,21 +13,25 @@ You are creating a comprehensive prompt that can be used to continue work in a n
 Create a detailed continuation prompt that includes:
 
 ### 1. Session Summary
+
 - **Main Task/Goal**: What was the primary objective of this session?
 - **Work Completed**: List the key accomplishments and changes made
 - **Current Status**: Where things stand right now
 
 ### 2. Next Steps
+
 - **Immediate Priorities**: What should be tackled first in the next session?
 - **Pending Tasks**: Any unfinished items that need attention
 - **Blockers/Issues**: Any problems encountered that need resolution
 
 ### 3. Important Context
+
 - **Key Files Modified**: List the most important files that were changed
 - **Critical Information**: Any warnings, gotchas, or important discoveries
 - **Dependencies**: Any tools, commands, or setup requirements
 
 ### 4. Validation Commands
+
 - **Test Commands**: Specific commands to verify the current state
 - **Quality Checks**: Commands to ensure everything is working properly
 
@@ -34,46 +39,60 @@ Create a detailed continuation prompt that includes:
 
 Generate the continuation prompt in this format:
 
-```
+```text
+
 ## Continuing Work on: [Project/Task Name]
 
 ### Previous Session Summary
+
 [Brief overview of what was being worked on and why]
 
 ### Progress Achieved
+
 - ✅ [Completed item 1]
 - ✅ [Completed item 2]
 - 🔄 [In-progress item]
 - ⏳ [Pending item]
 
 ### Current State
+
 [Description of where things stand, any important context]
 
 ### Next Steps (Priority Order)
+
 1. [Most important next task with specific details]
 2. [Second priority with context]
 3. [Additional tasks as needed]
 
 ### Important Files/Areas
+
 - `path/to/important/file.py` - [Why it's important]
 - `another/critical/file.md` - [What needs attention]
 
 ### Commands to Run
+
 ```bash
+
 # Verify current state
+
 [specific command]
 
 # Continue work
+
 [specific command]
-```
+
+```text
 
 ### Notes/Warnings
+
 - ⚠️ [Any critical warnings or gotchas]
 - 💡 [Helpful tips or discoveries]
 
 ### Request
+
 Please continue working on [specific task/goal]. The immediate focus should be on [specific priority].
-```
+
+```text
 
 ## Process the Arguments
 
@@ -82,6 +101,7 @@ If "$ARGUMENTS" is provided (e.g., "testing", "epic-4", "coverage"), tailor the
 ## Make it Actionable
 
 The generated prompt should be:
+
 - **Self-contained**: Someone reading it should understand the full context
 - **Specific**: Include exact file paths, command names, and clear objectives
 - **Actionable**: Clear next steps that can be immediately executed

samples/sample-custom-modules/cc-agents-commands/commands/parallelize-agents.md

@@ -0,0 +1,126 @@
+---
+description: "Parallelizes tasks with specialized agents"
+prerequisites: "—"
+argument-hint: "<task_description> [--workers=N] [--strategy=auto|error|test|lint|api|database|type|import]"
+allowed-tools: ["Task", "TodoWrite", "Glob", "Grep", "Read", "LS", "Bash", "SlashCommand"]
+---
+
+Parallelize the following task using specialized agents: $ARGUMENTS
+
+## Task Analysis
+
+Parse the arguments to understand what specialized agents are needed:
+
+- Extract any `--workers=N` or `--strategy=TYPE` options
+- Analyze the task content to detect which domain expertise is required
+- Identify the core work and how it can be distributed
+
+## Specialized Agent Detection
+
+Determine which specialized agent types would be most effective:
+
+**Error-focused agents:**
+
+- `type-error-fixer` - For mypy errors, TypeVar, Protocol, type annotations
+- `import-error-fixer` - For ModuleNotFoundError, import issues, Python path problems
+- `linting-fixer` - For ruff, format issues, E501, F401 violations
+- `api-test-fixer` - For FastAPI, endpoint tests, HTTP client issues
+- `database-test-fixer` - For database connections, fixtures, SQL, Supabase issues
+- `unit-test-fixer` - For pytest failures, assertions, mocks, test logic
+
+**Workflow agents:**
+
+- `commit-orchestrator` - For git commits, staging, pre-commit hooks, quality gates
+- `ci-workflow-orchestrator` - For CI/CD failures, GitHub Actions, pipeline issues
+
+**Investigation agents:**
+
+- `digdeep` - For root cause analysis, mysterious failures, complex debugging
+- `security-scanner` - For vulnerabilities, OWASP compliance, secrets detection
+- `performance-test-fixer` - For load tests, response times, benchmarks
+- `e2e-test-fixer` - For end-to-end workflows, integration tests
+
+**Fallback:**
+
+- `parallel-executor` - For general independent parallel work
+- `general-purpose` - For complex multi-domain coordination
+
+## Work Package Creation
+
+Use available tools to understand the codebase and create specialized work packages:
+
+- Use LS to examine project structure
+- Use Grep to identify error patterns or relevant files
+- Use Read to examine error outputs or test results
+
+Then divide the task by domain expertise:
+
+**Single-domain tasks** (e.g., "fix all linting errors"):
+
+- Create 1-2 work packages for the same specialized agent type
+- Group by file or error type
+
+**Multi-domain tasks** (e.g., "fix test failures"):
+
+- Analyze test output to categorize failures by type
+- Create one work package per error category
+- Assign appropriate specialized agent for each category
+
+**Mixed-strategy tasks**:
+
+- Categorize issues by required domain expertise
+- Create specialized work packages for each agent type
+- Ensure no overlap in file modifications
+
+## Agent Execution
+
+Launch multiple specialized Task agents in parallel (all in a single message) using the appropriate `subagent_type`.
+
+**Best practices:**
+
+- Send all Task tool calls in one batch for true parallelization
+- Match agent type to problem domain for higher success rates
+- Give each agent clear domain-specific scope
+- Ensure agents don't modify the same files
+
+**Agent specialization advantages:**
+
+- Domain-specific tools and knowledge
+- Optimized approaches for specific problem types
+- Better error pattern recognition
+- Higher fix success rates
+
+Each specialized agent prompt should include:
+
+- The agent's domain expertise and role
+- Specific scope (files/directories/error types to address)
+- The specialized work to complete
+- Constraints to avoid conflicts with other agents
+- Expected output format including cross-domain issues
+
+## Result Synthesis
+
+After specialized agents complete:
+
+- Validate each agent's domain-specific results
+- Identify any cross-domain conflicts or dependencies
+- Merge findings into a coherent summary
+- Report which agent types were most effective
+- Recommend follow-up work if issues require different specializations
+
+## Quick Reference: Agent Type Mapping
+
+- **Linting** → `linting-fixer`
+- **Type errors** → `type-error-fixer`
+- **Import errors** → `import-error-fixer`
+- **API tests** → `api-test-fixer`
+- **Database tests** → `database-test-fixer`
+- **Unit tests** → `unit-test-fixer`
+- **Git commits** → `commit-orchestrator`
+- **CI/CD** → `ci-workflow-orchestrator`
+- **Deep investigation** → `digdeep`
+- **Security** → `security-scanner`
+- **Performance** → `performance-test-fixer`
+- **E2E tests** → `e2e-test-fixer`
+- **Independent tasks** → `parallel-executor`
+- **Complex coordination** → `general-purpose`

samples/sample-custom-modules/cc-agents-commands/commands/parallelize.md

@@ -0,0 +1,94 @@
+---
+description: "Parallelizes tasks across sub-agents"
+prerequisites: "—"
+argument-hint: "<task_description> [--workers=N] [--strategy=auto|file|feature|layer|test|analysis]"
+allowed-tools: ["Task", "TodoWrite", "Glob", "Grep", "Read", "LS"]
+---
+
+Parallelize the following task across independent agents: $ARGUMENTS
+
+## Task Analysis
+
+Parse the arguments and understand the parallelization requirements:
+
+- Extract any `--workers=N` option to guide agent count
+- Extract any `--strategy=TYPE` option (or auto-detect from task content)
+- Identify the core work to be parallelized
+
+## Strategy Detection
+
+Analyze the task to determine the best parallelization approach:
+
+- **File-based**: Task mentions file patterns (.js, .py, .md) or specific file/directory paths
+- **Feature-based**: Task involves distinct components, modules, or features
+- **Layer-based**: Task spans frontend/backend/database/API architectural layers
+- **Test-based**: Task involves running or fixing tests across multiple suites
+- **Analysis-based**: Task requires research or analysis from multiple perspectives
+
+## Work Package Creation
+
+Divide the task into independent work packages based on the strategy:
+
+**For file-based tasks:**
+
+- Use Glob to identify relevant files
+- Group related files together (avoid splitting dependencies)
+- Ensure agents don't modify shared files
+
+**For feature-based tasks:**
+
+- Identify distinct features or components
+- Create clear boundaries between feature scopes
+- Assign one feature per agent
+
+**For layer-based tasks:**
+
+- Separate by architectural layers (frontend, backend, database)
+- Define clear interface boundaries
+- Ensure layers can be worked on independently
+
+**For test-based tasks:**
+
+- Group test suites by independence
+- Separate unit tests from integration tests when beneficial
+- Distribute test execution across agents
+
+**For analysis-based tasks:**
+
+- Break analysis into distinct aspects or questions
+- Assign different research approaches or sources to each agent
+- Consider multiple perspectives on the problem
+
+## Agent Execution
+
+Launch multiple Task agents in parallel (all in a single message) using `subagent_type="parallel-executor"`.
+
+**Best practices:**
+
+- Send all Task tool calls in one batch for true parallelization
+- Give each agent clear scope boundaries to avoid conflicts
+- Include specific instructions for each agent's work package
+- Define what each agent should NOT modify to prevent overlaps
+
+**Typical agent count:**
+
+- Simple tasks (1-2 components): 2-3 agents
+- Medium tasks (3-5 components): 3-4 agents
+- Complex tasks (6+ components): 4-6 agents
+
+Each agent prompt should include:
+
+- The specific work package it's responsible for
+- Context about the overall parallelization task
+- Clear scope (which files/components to work on)
+- Constraints (what NOT to modify)
+- Expected output format
+
+## Result Synthesis
+
+After agents complete:
+
+- Collect and validate each agent's results
+- Check for any conflicts or overlaps between agents
+- Merge findings into a coherent summary
+- Report on overall execution and any issues encountered

samples/sample-custom-modules/cc-agents-commands/commands/pr.md

@@ -13,6 +13,7 @@ Understand the user's PR request: "$ARGUMENTS"
 **When the user includes `--fast` in the arguments, skip all local validation:**
 
 If "$ARGUMENTS" contains "--fast":
+
 1. Stage all changes (`git add -A`)
 2. Auto-generate a commit message based on the diff
 3. Commit with `--no-verify` (skip pre-commit hooks)
@@ -20,12 +21,15 @@ If "$ARGUMENTS" contains "--fast":
 5. Trust CI to catch any issues
 
 **Use fast mode for:**
+
 - Trusted changes (formatting, docs, small fixes)
 - When you've already validated locally
 - WIP commits to save progress
 
 ```bash
+
 # Fast mode example
+
 git add -A
 git commit --no-verify -m "$(cat <<'EOF'
 <auto-generated message>
@@ -36,13 +40,15 @@ Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
 EOF
 )"
 git push --no-verify
-```
+
+```text
 
 ## Default Behavior (No Arguments or "update")
 
 **When the user runs `/pr` with no arguments, default to "update" with standard validation:**
 
 If "$ARGUMENTS" is empty, "update", or doesn't contain "--fast":
+
 1. Stage all changes (`git add -A`)
 2. Auto-generate a commit message based on the diff
 3. Commit normally (triggers pre-commit hooks - ~5s)
@@ -58,7 +64,9 @@ If "$ARGUMENTS" is empty, "update", or doesn't contain "--fast":
 **BEFORE any push operation, check for merge conflicts that block CI:**
 
 ```bash
+
 # Check if current branch has a PR with merge conflicts
+
 BRANCH=$(git branch --show-current)
 PR_INFO=$(gh pr list --head "$BRANCH" --json number,mergeStateStatus -q '.[0]' 2>/dev/null)
 
@@ -81,7 +89,8 @@ if [[ -n "$PR_INFO" && "$PR_INFO" != "null" ]]; then
         # Ask user if they want to sync or continue anyway
     fi
 fi
-```
+
+```text
 
 **This check prevents the silent CI skipping issue where E2E/UAT tests don't run.**
 
@@ -90,7 +99,9 @@ fi
 If the user requests "sync", merge the base branch to resolve conflicts:
 
 ```bash
+
 # Sync current branch with base (usually main)
+
 BASE_BRANCH=$(gh pr view --json baseRefName -q '.baseRefName' 2>/dev/null || echo "main")
 echo "🔄 Syncing with $BASE_BRANCH..."
 
@@ -102,13 +113,17 @@ else
     echo "⚠️  Merge conflicts detected. Please resolve manually:"
     git diff --name-only --diff-filter=U
 fi
-```
+
+```text
 
 ## Quick Status Check
 
 If the user asks for "status" or similar, show a simple PR status:
+
 ```bash
+
 # Enhanced status with merge state check
+
 PR_DATA=$(gh pr view --json number,title,state,statusCheckRollup,mergeStateStatus 2>/dev/null)
 if [[ -n "$PR_DATA" ]]; then
     echo "$PR_DATA" | jq '.'
@@ -122,13 +137,15 @@ if [[ -n "$PR_DATA" ]]; then
 else
     echo "No PR for current branch"
 fi
-```
+
+```text
 
 ## Delegate Complex Operations
 
 For any PR operation (create, update, merge, review, fix CI, etc.), delegate to the pr-workflow-manager agent:
 
-```
+```text
+
 Task(
     subagent_type="pr-workflow-manager",
     description="Handle PR request: ${ARGUMENTS:-update}",
@@ -154,6 +171,7 @@ Task(
     - Offer to sync with main first
 
     Please handle this PR operation which may include:
+
     - **update** (DEFAULT): Stage all, commit, and push (with conflict check)
     - **--fast**: Skip all local validation (still warn about conflicts)
     - **sync**: Merge base branch into current branch to resolve conflicts
@@ -168,18 +186,27 @@ Task(
 
     The pr-workflow-manager agent has full capability to handle all PR operations."
 )
-```
+
+```text
 
 ## Common Requests the Agent Handles
 
 | Command | What it does |
+
 | --------- | -------------- |
+
 | `/pr` or `/pr update` | Stage all, commit, push (with conflict check + hooks ~20s) |
+
 | `/pr --fast` | Stage all, commit, push (skip hooks ~5s, still warns about conflicts) |
+
 | `/pr status` | Show PR status (includes merge conflict warning) |
+
 | `/pr sync` | **NEW:** Merge base branch to resolve conflicts, enable full CI |
+
 | `/pr create story 8.1` | Create PR for a story |
+
 | `/pr merge` | Merge current PR |
+
 | `/pr fix CI` | Delegate to /ci_orchestrate |
 
 **Important:** If your PR has merge conflicts, E2E/UAT/Benchmark CI jobs will NOT run (GitHub Actions limitation). Use `/pr sync` to fix this.
@@ -191,10 +218,14 @@ The pr-workflow-manager agent will handle all complexity and coordination with o
 When the pr-workflow-manager reports CI failures, automatically invoke the CI orchestrator:
 
 ```bash
+
 # After pr-workflow-manager completes, check if CI failures were detected
+
 # The agent will report CI status in its output
-if [[ "$AGENT_OUTPUT" =~ "CI.*fail" ]] || [[ "$AGENT_OUTPUT" =~ "Checks.*failing" ]]; then
+
+if [[ "$AGENT_OUTPUT" =~ "CI._fail" ]] || [[ "$AGENT_OUTPUT" =~ "Checks._failing" ]]; then
     echo "CI failures detected. Invoking /ci_orchestrate to fix them..."
     SlashCommand(command="/ci_orchestrate --fix-all")
 fi
-```
+
+```text

samples/sample-custom-modules/cc-agents-commands/commands/test-orchestrate.md

@@ -501,137 +501,6 @@ PHASE 4 (Validation): Run full test suite to verify all fixes
 
 ---
 
-## STEP 7.6: Test File Modification Safety (NEW)
-
-**CRITICAL**: When multiple test files need modification, apply dependency-aware batching similar to source file refactoring.
-
-### Analyze Test File Dependencies
-
-Before spawning test fixers, identify shared fixtures and conftest dependencies:
-
-```bash
-echo "=== Test Dependency Analysis ==="
-
-# Find all conftest.py files
-CONFTEST_FILES=$(find tests/ -name "conftest.py" 2>/dev/null)
-echo "Shared fixture files: $CONFTEST_FILES"
-
-# For each failing test file, find its fixture dependencies
-for TEST_FILE in $FAILING_TEST_FILES; do
-    # Find imports from conftest
-    FIXTURE_IMPORTS=$(grep -E "^from.*conftest|@pytest.fixture" "$TEST_FILE" 2>/dev/null | head -10)
-
-    # Find shared fixtures used
-    FIXTURES_USED=$(grep -oE "[a-z_]+_fixture|@pytest.fixture" "$TEST_FILE" 2>/dev/null | sort -u)
-
-    echo "  $TEST_FILE -> fixtures: [$FIXTURES_USED]"
-done
-```
-
-### Group Test Files by Shared Fixtures
-
-```bash
-# Files sharing conftest.py fixtures MUST serialize
-# Files with independent fixtures CAN parallelize
-
-# Example output:
-echo "
-Test Cluster A (SERIAL - shared fixtures in tests/conftest.py):
-  - tests/unit/test_user.py
-  - tests/unit/test_auth.py
-
-Test Cluster B (PARALLEL - independent fixtures):
-  - tests/integration/test_api.py
-  - tests/integration/test_database.py
-
-Test Cluster C (SPECIAL - conftest modification needed):
-  - tests/conftest.py (SERIALIZE - blocks all others)
-"
-```
-
-### Execution Rules for Test Modifications
-
-| Scenario | Execution Mode | Reason |
-|----------|----------------|--------|
-| Multiple test files, no shared fixtures | PARALLEL | Safe, independent |
-| Multiple test files, shared fixtures | SERIAL within fixture scope | Fixture state conflicts |
-| conftest.py needs modification | SERIAL (blocks all) | Critical shared state |
-| Same test file reported by multiple fixers | Single agent only | Avoid merge conflicts |
-
-### conftest.py Special Handling
-
-If `conftest.py` needs modification:
-
-1. **Run conftest fixer FIRST** (before any other test fixers)
-2. **Wait for completion** before proceeding
-3. **Re-run baseline tests** to verify fixture changes don't break existing tests
-4. **Then parallelize** remaining independent test fixes
-
-```
-PHASE 1 (First, blocking): conftest.py modification
-   └── WAIT for completion
-
-PHASE 2 (Sequential): Test files sharing modified fixtures
-   └── Run one at a time, verify after each
-
-PHASE 3 (Parallel): Independent test files
-   └── Safe to parallelize
-```
-
-### Failure Handling for Test Modifications
-
-When a test fixer fails:
-
-```
-AskUserQuestion(
-  questions=[{
-    "question": "Test fixer for {test_file} failed: {error}. {N} test files remain. What would you like to do?",
-    "header": "Test Fix Failure",
-    "options": [
-      {"label": "Continue", "description": "Skip this test file, proceed with remaining"},
-      {"label": "Abort", "description": "Stop test fixing, preserve current state"},
-      {"label": "Retry", "description": "Attempt to fix {test_file} again"}
-    ],
-    "multiSelect": false
-  }]
-)
-```
-
-### Test Fixer Dispatch with Scope
-
-Include scope information when dispatching test fixers:
-
-```
-Task(
-    subagent_type="unit-test-fixer",
-    description="Fix unit tests in {test_file}",
-    prompt="Fix failing tests in this file:
-
-    TEST FILE CONTEXT:
-    - file: {test_file}
-    - shared_fixtures: {list of conftest fixtures used}
-    - parallel_peers: {other test files being fixed simultaneously}
-    - conftest_modified: {true|false - was conftest changed this session?}
-
-    SCOPE CONSTRAINTS:
-    - ONLY modify: {test_file}
-    - DO NOT modify: conftest.py (unless explicitly assigned)
-    - DO NOT modify: {parallel_peer_files}
-
-    MANDATORY OUTPUT FORMAT - Return ONLY JSON:
-    {
-      \"status\": \"fixed|partial|failed\",
-      \"test_file\": \"{test_file}\",
-      \"tests_fixed\": N,
-      \"fixtures_modified\": [],
-      \"remaining_failures\": N,
-      \"summary\": \"...\"
-    }"
-)
-```
-
----
-
 ## STEP 8: PARALLEL AGENT DISPATCH
 
 ### CRITICAL: Launch ALL agents in ONE response with multiple Task calls.

samples/sample-custom-modules/cc-agents-commands/commands/usertestgates.md

@@ -1,20 +1,22 @@
 ---
-description: "Find and run next test gate based on story completion"
+description: "Finds and runs next test gate"
+prerequisites: "test gates in project"
 argument-hint: "no arguments needed - auto-detects next gate"
 allowed-tools: ["Bash", "Read"]
 ---
 
 # ⚠️ PROJECT-SPECIFIC COMMAND - Requires test gates infrastructure
-# This command requires:
-# - ~/.claude/lib/testgates_discovery.py (test gate discovery script)
-# - docs/epics.md (or similar) with test gate definitions
-# - user-testing/scripts/ directory with validation scripts
-# - user-testing/reports/ directory for results
-#
-# The file path checks in Step 3.5 are project-specific examples that should be
-# customized for your project's implementation structure.
 
-# Test Gate Finder & Executor
+This command requires:
+
+- ~/.claude/lib/testgates_discovery.py (test gate discovery script)
+- docs/epics.md (or similar) with test gate definitions
+- user-testing/scripts/ directory with validation scripts
+- user-testing/reports/ directory for results
+
+The file path checks in Step 3.5 are project-specific examples that should be customized for your project's implementation structure
+
+## Test Gate Finder & Executor
 
 **Your task**: Find the next test gate to run, show the user what's needed, and execute it if they confirm.
 
@@ -23,13 +25,17 @@ allowed-tools: ["Bash", "Read"]
 First, check if the required infrastructure exists:
 
 ```bash
+
 # ============================================
+
 # PRE-FLIGHT CHECKS (Infrastructure Validation)
+
 # ============================================
 
 TESTGATES_SCRIPT="$HOME/.claude/lib/testgates_discovery.py"
 
 # Check if discovery script exists
+
 if [[ ! -f "$TESTGATES_SCRIPT" ]]; then
   echo "❌ Test gates discovery script not found"
   echo "   Expected: $TESTGATES_SCRIPT"
@@ -40,6 +46,7 @@ if [[ ! -f "$TESTGATES_SCRIPT" ]]; then
 fi
 
 # Check for epic definition files
+
 EPICS_FILE=""
 for file in "docs/epics.md" "docs/EPICS.md" "docs/test-gates.md" "EPICS.md"; do
   if [[ -f "$file" ]]; then
@@ -56,25 +63,31 @@ if [[ -z "$EPICS_FILE" ]]; then
 fi
 
 # Check for user-testing directory structure
+
 if [[ ! -d "user-testing" ]]; then
   echo "⚠️ No user-testing/ directory found"
   echo "   This command expects user-testing/scripts/ and user-testing/reports/"
   echo "   Creating minimal structure..."
   mkdir -p user-testing/scripts user-testing/reports
 fi
-```
+
+```text
 
 Run the discovery script to get test gate configuration:
 
 ```bash
 python3 "$TESTGATES_SCRIPT" . --format json > /tmp/testgates_config.json 2>/dev/null
-```
+
+```text
 
 If this fails or produces empty output, tell the user:
-```
+
+```text
+
 ❌ Failed to discover test gates from epic definition file
 Make sure docs/epics.md (or similar) exists with story and test gate definitions.
-```
+
+```text
 
 ## Step 2: Check Which Gates Have Already Passed
 
@@ -88,7 +101,8 @@ gates = config.get('test_gates', {})
 for gate_id in sorted(gates.keys()):
     print(gate_id)
 "
-```
+
+```text
 
 For each gate, check if it has passed by looking for a report with "PROCEED":
 
@@ -96,6 +110,7 @@ For each gate, check if it has passed by looking for a report with "PROCEED":
 gate_id="TG-X.Y"  # Replace with actual gate ID
 
 # Check subdirectory first: user-testing/reports/TG-X.Y/
+
 if [ -d "user-testing/reports/$gate_id" ]; then
     report=$(find "user-testing/reports/$gate_id" -name "*report.md" 2>/dev/null | head -1)
     if [ -n "$report" ] && grep -q "PROCEED" "$report" 2>/dev/null; then
@@ -104,13 +119,15 @@ if [ -d "user-testing/reports/$gate_id" ]; then
 fi
 
 # Check main directory: user-testing/reports/TG-X.Y_*_report.md
+
 if [ ! -d "user-testing/reports/$gate_id" ]; then
     report=$(find "user-testing/reports" -maxdepth 1 -name "${gate_id}_*report.md" 2>/dev/null | head -1)
     if [ -n "$report" ] && grep -q "PROCEED" "$report" 2>/dev/null; then
         echo "$gate_id: PASSED"
     fi
 fi
-```
+
+```text
 
 Build a list of passed gates.
 
@@ -136,7 +153,8 @@ print('Name:', gate.get('name', 'Unknown'))
 print('Requires:', ','.join(gate.get('requires', [])))
 print('Script:', gate.get('script', 'N/A'))
 "
-```
+
+```text
 
 ## Step 3.5: Check Story Implementation Status
 
@@ -148,6 +166,7 @@ Before suggesting a test gate, check if the required story is actually implement
 gate_id="TG-X.Y"  # e.g., "TG-2.3"
 
 # Define expected files for each gate (examples)
+
 case "$gate_id" in
   "TG-1.1")
     # Agent Framework - check for strands setup
@@ -194,6 +213,7 @@ case "$gate_id" in
 esac
 
 # Check if files exist
+
 missing_files=()
 for file in "${files[@]}"; do
   if [ ! -f "$file" ]; then
@@ -202,13 +222,15 @@ for file in "${files[@]}"; do
 done
 
 # Output result
+
 if [ ${#missing_files[@]} -gt 0 ]; then
   echo "STORY_NOT_READY"
   printf '%s\n' "${missing_files[@]}"
 else
   echo "STORY_READY"
 fi
-```
+
+```text
 
 **Store the story readiness status** to use in Step 4.
 
@@ -217,7 +239,9 @@ fi
 **Format output like this:**
 
 If some gates already passed:
-```
+
+```text
+
 ================================================================================
 Passed Gates:
   ✅ TG-1.1 - Agent Framework Validation (PASSED)
@@ -225,10 +249,13 @@ Passed Gates:
 
 🎯 Next Test Gate: TG-1.3 - Excel Parser Validation
 ================================================================================
-```
+
+```text
 
 If story is NOT READY (implementation files missing from Step 3.5):
-```
+
+```text
+
 ⏳ Story [X.Y] NOT IMPLEMENTED
 
 Required story: Story [X.Y] - [Story Name]
@@ -243,10 +270,13 @@ Missing implementation files:
 Please complete Story [X.Y] implementation first.
 
 Once complete, run: /usertestgates
-```
+
+```text
 
 If gate is READY (story implemented AND all prerequisite gates passed):
-```
+
+```text
+
 ✅ This gate is READY to run
 
 Prerequisites: All prerequisite test gates have passed
@@ -255,16 +285,20 @@ Story Status: ✅ Story [X.Y] implemented
 Script: user-testing/scripts/TG-1.3_excel_parser_validation.py
 
 Run TG-1.3 now? (Y/N)
-```
+
+```text
 
 If gate is NOT READY (prerequisite gates not passed):
-```
+
+```text
+
 ⏳ Complete these test gates first:
 
   ❌ TG-1.1 - Agent Framework Validation (not passed)
 
 Once complete, run: /usertestgates
-```
+
+```text
 
 ## Step 5: Execute Gate if User Confirms
 
@@ -281,17 +315,20 @@ if grep -q "input(" "$gate_script" 2>/dev/null; then
 else
     echo "NON_INTERACTIVE"
 fi
-```
 
-### For NON-INTERACTIVE Gates:
+```text
+
+### For NON-INTERACTIVE Gates
 
 Run directly:
 
 ```bash
 python3 user-testing/scripts/TG-X.Y_*_validation.py
-```
+
+```text
 
 Show the exit code and interpret:
+
 - Exit 0 → ✅ PROCEED
 - Exit 1 → ⚠️ REFINE
 - Exit 2 → 🚨 ESCALATE
@@ -299,24 +336,28 @@ Show the exit code and interpret:
 
 Check for report in `user-testing/reports/TG-X.Y/` and mention it
 
-### For INTERACTIVE Gates (Agent-Guided Mode):
+### For INTERACTIVE Gates (Agent-Guided Mode)
 
 **Step 5a: Run Parse Phase**
 
 ```bash
 python3 user-testing/scripts/TG-X.Y_*_validation.py --phase=parse
-```
+
+```text
 
 This outputs parsed data to `/tmp/tg-X.Y-parse-results.json`
 
 **Step 5b: Load Parse Results and Collect User Answers**
 
 Load the parse results:
+
 ```bash
 cat /tmp/tg-X.Y-parse-results.json
-```
+
+```text
 
 For TG-1.3 (Excel Parser), the parse results contain:
+
 - `workbooks`: Array of parsed workbook data
 - `total_checks`: Number of validation checks needed (e.g., 30)
 
@@ -330,10 +371,10 @@ For each workbook, you need to ask the user to validate 6 checks. The validation
 6. Data Contract: "Output matches expected JSON schema?"
 
 **For each check:**
-1. Show the user the parsed data (from `/tmp/` or parse results)
+7. Show the user the parsed data (from `/tmp/` or parse results)
-2. Ask: "Check N/30: [description] - How do you assess this? (PASS/FAIL/PARTIAL/N/A)"
+8. Ask: "Check N/30: [description] - How do you assess this? (PASS/FAIL/PARTIAL/N/A)"
-3. Collect: status (PASS/FAIL/PARTIAL/N/A) and optional notes
+9. Collect: status (PASS/FAIL/PARTIAL/N/A) and optional notes
-4. Store in answers array
+10. Store in answers array
 
 **Step 5c: Create Answers JSON**
 
@@ -356,20 +397,24 @@ Create `/tmp/tg-X.Y-answers.json`:
     }
   ]
 }
-```
+
+```text
 
 **Step 5d: Run Report Phase**
 
 ```bash
 python3 user-testing/scripts/TG-X.Y_*_validation.py --phase=report --answers=/tmp/tg-X.Y-answers.json
-```
+
+```text
 
 This generates the final report in `user-testing/reports/TG-X.Y/` with:
+
 - User's validation answers
 - Recommendation (PROCEED/REFINE/ESCALATE)
 - Exit code (0/1/2)
 
 Show the exit code and interpret:
+
 - Exit 0 → ✅ PROCEED
 - Exit 1 → ⚠️ REFINE
 - Exit 2 → 🚨 ESCALATE
@@ -377,7 +422,9 @@ Show the exit code and interpret:
 ## Special Cases
 
 **All gates passed:**
-```
+
+```text
+
 ================================================================================
 🎉 ALL TEST GATES PASSED!
 ================================================================================
@@ -388,12 +435,16 @@ Show the exit code and interpret:
   ✅ TG-4.6 - End-to-End MVP Validation
 
 MVP is complete! 🎉
-```
+
+```text
 
 **No gates found:**
-```
+
+```text
+
 ❌ No test gates configured. Check /tmp/testgates_config.json
-```
+
+```text
 
 ---
 

samples/sample-custom-modules/cc-agents-commands/skills/pr-workflow/SKILL.md

@@ -10,31 +10,37 @@ Generic PR management for any Git project. Works with any branching strategy, an
 ## Capabilities
 
 ### Create PR
+
 - Detect current branch automatically
 - Determine base branch from Git config
 - Generate PR description from commit messages
 - Support draft or ready PRs
 
 ### Check Status
+
 - Show PR status for current branch
 - Display CI check results
 - Show merge readiness
 
 ### Update PR
+
 - Refresh PR description from recent commits
 - Update based on new changes
 
 ### Validate
+
 - Check if ready to merge
 - Run quality gates (tests, coverage, linting)
 - Verify CI passing
 
 ### Merge
+
 - Squash or merge commit strategy
 - Auto-cleanup branches after merge
 - Handle conflicts
 
 ### Sync
+
 - Update current branch with base branch
 - Resolve merge conflicts
 - Keep feature branch current
@@ -49,6 +55,7 @@ Generic PR management for any Git project. Works with any branching strategy, an
 ## Delegation
 
 All operations delegate to the **pr-workflow-manager** subagent which:
+
 - Handles gh CLI operations
 - Spawns quality validation agents when needed
 - Coordinates with ci_orchestrate, test_orchestrate for failures
@@ -57,6 +64,7 @@ All operations delegate to the **pr-workflow-manager** subagent which:
 ## Examples
 
 **Natural language triggers:**
+
 - "Create a PR for this branch"
 - "What's the status of my PR?"
 - "Is my PR ready to merge?"

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

@@ -5,7 +5,6 @@ agent:
     title: "Commit Message Artisan"
     icon: "📜"
     module: stand-alone
-    hasSidecar: false
 
   persona:
     role: |

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

@@ -5,7 +5,6 @@ agent:
     title: "Meditation Guide"
     icon: "🧘"
     module: "mwm"
-    hasSidecar: false
   persona:
     role: "Mindfulness and meditation specialist"
     identity: |

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

@@ -7,7 +7,6 @@ agent:
     name: "BMad Master"
     title: "BMad Master Executor, Knowledge Custodian, and Workflow Orchestrator"
     icon: "🧙"
-    hasSidecar: false
 
   persona:
     role: "Master Task Executor + BMad Expert + Guiding Facilitator Orchestrator"

src/modules/bmb/agents/agent-builder.agent.yaml

@@ -9,7 +9,6 @@ agent:
     title: Agent Building Expert
     icon: 🤖
     module: bmb
-    hasSidecar: false
 
   persona:
     role: Agent Architecture Specialist + BMAD Compliance Expert
@@ -29,13 +28,9 @@ agent:
 
   menu:
     - trigger: CA or fuzzy match on create-agent
-      exec: "{project-root}/_bmad/bmb/workflows/agent/workflow.md"
+      exec: "{project-root}/_bmad/bmb/workflows/create-agent/workflow.md"
       description: "[CA] Create a new BMAD agent with best practices and compliance"
 
     - trigger: EA or fuzzy match on edit-agent
-      exec: "{project-root}/_bmad/bmb/workflows/agent/workflow.md"
+      exec: "{project-root}/_bmad/bmb/workflows/edit-agent/workflow.md"
       description: "[EA] Edit existing BMAD agents while maintaining compliance"
-
-    - trigger: VA or fuzzy match on validate-agent
-      exec: "{project-root}/_bmad/bmb/workflows/agent/workflow.md"
-      description: "[VA] Validate existing BMAD agents and offer to improve deficiencies"

src/modules/bmb/agents/module-builder.agent.yaml

@@ -9,7 +9,6 @@ agent:
     title: Module Creation Master
     icon: 🏗️
     module: bmb
-    hasSidecar: false
 
   persona:
     role: Module Architecture Specialist + Full-Stack Systems Designer

src/modules/bmb/agents/workflow-builder.agent.yaml

@@ -9,7 +9,6 @@ agent:
     title: Workflow Building Master
     icon: 🔄
     module: bmb
-    hasSidecar: false
 
   persona:
     role: Workflow Architecture Specialist + Process Design Expert

src/modules/bmb/docs/agents/agent-compilation.md

@@ -0,0 +1,318 @@
+# Agent Compilation: YAML to XML
+
+What the compiler auto-injects. **DO NOT duplicate these in your YAML.**
+
+## Compilation Pipeline
+
+```
+agent.yaml → Handlebars processing → XML generation → frontmatter.md
+```
+
+Source: `tools/cli/lib/agent/compiler.js`
+
+## File Naming Convention
+
+**CRITICAL:** Agent filenames must be ROLE-BASED, not persona-based.
+
+**Why:** Users can customize the agent's persona name via `customize.yaml` config. The filename provides stable identity.
+
+**Correct:**
+
+```
+presentation-master.agent.yaml  ← Role/function
+tech-writer.agent.yaml          ← Role/function
+code-reviewer.agent.yaml        ← Role/function
+```
+
+**Incorrect:**
+
+```
+caravaggio.agent.yaml    ← Persona name (users might rename to "Pablo")
+paige.agent.yaml         ← Persona name (users might rename to "Sarah")
+rex.agent.yaml           ← Persona name (users might rename to "Max")
+```
+
+**Pattern:**
+
+- Filename: `{role-or-function}.agent.yaml` (kebab-case)
+- Metadata ID: `_bmad/{module}/agents/{role-or-function}.md`
+- Persona Name: User-customizable in metadata or customize.yaml
+
+**Example:**
+
+```yaml
+# File: presentation-master.agent.yaml
+agent:
+  metadata:
+    id: '_bmad/cis/agents/presentation-master.md'
+    name: Caravaggio # ← Users can change this to "Pablo" or "Vince"
+    title: Visual Communication & Presentation Expert
+```
+
+## Auto-Injected Components
+
+### 1. Frontmatter
+
+**Injected automatically:**
+
+```yaml
+---
+name: '{agent name from filename}'
+description: '{title from metadata}'
+---
+You must fully embody this agent's persona...
+```
+
+**DO NOT add** frontmatter to your YAML source.
+
+### 2. Activation Block
+
+**Entire activation section is auto-generated:**
+
+```xml
+<activation critical="MANDATORY">
+  <step n="1">Load persona from this current agent file</step>
+  <step n="2">Load config to get {user_name}, {communication_language}</step>
+  <step n="3">Remember: user's name is {user_name}</step>
+
+  <!-- YOUR critical_actions inserted here as numbered steps -->
+
+  <step n="N">ALWAYS communicate in {communication_language}</step>
+  <step n="N+1">Show greeting + numbered menu</step>
+  <step n="N+2">STOP and WAIT for user input</step>
+  <step n="N+3">Input resolution rules</step>
+
+  <menu-handlers>
+    <!-- Only handler instructions for the handler types used in the agents specific menu are included -->
+  </menu-handlers>
+
+  <rules>
+    <!-- Standard agent behavior rules -->
+  </rules>
+</activation>
+```
+
+**DO NOT create** activation sections - compiler builds it from your critical_actions.
+
+### 3. Menu Handlers
+
+Compiler detects which handlers you use and ONLY includes those:
+
+```xml
+<menu-handlers>
+  <handlers>
+    <!-- Only if you use action="#id" or action="text" -->
+    <handler type="action">...</handler>
+
+    <!-- Only if you use workflow="path" -->
+    <handler type="workflow">...</handler>
+
+    <!-- Only if you use exec="path" -->
+    <handler type="exec">...</handler>
+
+    <!-- Only if you use tmpl="path" -->
+    <handler type="tmpl">...</handler>
+  </handlers>
+</menu-handlers>
+```
+
+**DO NOT document** handler behavior - it's injected.
+
+### 4. Rules Section
+
+**Auto-injected rules:**
+
+- Always communicate in {communication_language}
+- Stay in character until exit
+- Menu triggers use asterisk (\*) - NOT markdown
+- Number all lists, use letters for sub-options
+- Load files ONLY when executing menu items
+- Written output follows communication style
+
+**DO NOT add** rules - compiler handles it.
+
+## What YOU Provide in YAML
+
+### Required
+
+```yaml
+agent:
+  metadata:
+    id: '_bmad_/{module}/agents/foo/foo.agent.md
+    name: 'Persona Name'
+    title: 'Agent Title'
+    icon: 'emoji'
+    module: "bmm"
+
+  persona:
+    role: '...'
+    identity: '...'
+    communication_style: '...'
+    principles: [...]
+
+  menu:
+    - trigger: AB or fuzzy match on your-action
+      action: '#prompt-id'
+      description: '[AB] Your Action described menu item '
+```
+
+### Optional (based on type)
+
+```yaml
+# Expert agents only
+critical_actions:
+  - 'Load sidecar files...'
+  - 'Restrict access...'
+
+# Simple/Expert with embedded logic
+prompts:
+  - id: prompt-id
+    content: '...'
+
+# Simple/Expert with customization
+install_config:
+  questions: [...]
+```
+
+## Common Duplication Mistakes
+
+### Adding Activation Logic
+
+```yaml
+# BAD - compiler builds activation
+agent:
+  activation:
+    steps: [...]
+```
+
+### Including Help/Exit
+
+```yaml
+# BAD - auto-injected
+menu:
+  - trigger: help
+  - trigger: exit
+```
+
+### Prefixing Triggers
+
+```yaml
+# BAD - compiler adds *
+menu:
+  - trigger: '*analyze' # Should be: analyze
+```
+
+### Documenting Handlers
+
+```yaml
+# BAD - don't explain handlers, compiler injects them
+# When using workflow, load workflow.xml...
+```
+
+### Adding Rules in YAML
+
+```yaml
+# BAD - rules are auto-injected
+agent:
+  rules:
+    - Stay in character...
+```
+
+## Compilation Example
+
+**Your YAML:**
+
+```yaml
+agent:
+  metadata:
+    name: 'Rex'
+    title: 'Code Reviewer'
+    icon: '🔍'
+    type: simple
+
+  persona:
+    role: Code Review Expert
+    identity: Systematic reviewer...
+    communication_style: Direct and constructive
+    principles:
+      - Code should be readable
+
+  prompts:
+    - id: review
+      content: |
+        Analyze code for issues...
+
+  menu:
+    - trigger: review
+      action: '#review'
+      description: 'Review code'
+```
+
+**Compiled Output (.md):**
+
+```markdown
+---
+name: 'rex'
+description: 'Code Reviewer'
+---
+
+You must fully embody...
+
+\`\`\`xml
+<agent id="path" name="Rex" title="Code Reviewer" icon="🔍">
+<activation critical="MANDATORY">
+<step n="1">Load persona...</step>
+<step n="2">Load config...</step>
+<step n="3">Remember user...</step>
+<step n="4">Communicate in language...</step>
+<step n="5">Show greeting + menu...</step>
+<step n="6">STOP and WAIT...</step>
+<step n="7">Input resolution...</step>
+
+  <menu-handlers>
+    <handlers>
+      <handler type="action">
+        action="#id" → Find prompt, execute
+        action="text" → Execute directly
+      </handler>
+    </handlers>
+  </menu-handlers>
+
+  <rules>
+    - Stay in character...
+    - Number lists...
+    - Load files when executing...
+  </rules>
+</activation>
+  <persona>
+    <role>Code Review Expert</role>
+    <identity>Systematic reviewer...</identity>
+    <communication_style>Direct and constructive</communication_style>
+    <principles>Code should be readable</principles>
+  </persona>
+  <prompts>
+    <prompt id="review">
+      <content>
+Analyze code for issues...
+      </content>
+    </prompt>
+  </prompts>
+  <menu>
+    <item cmd="*help">Show numbered menu</item>
+    <item cmd="*review" action="#review">Review code</item>
+    <item cmd="*exit">Exit with confirmation</item>
+  </menu>
+</agent>
+\`\`\`
+```
+
+## Key Takeaways
+
+1. **Compiler handles boilerplate** - Focus on persona and logic
+2. **Critical_actions become activation steps** - Just list your agent-specific needs
+3. **Menu items are enhanced** - Help/exit added, triggers prefixed
+4. **Handlers auto-detected** - Only what you use is included
+5. **Rules standardized** - Consistent behavior across agents
+
+**Your job:** Define persona, prompts, menu actions
+**Compiler's job:** Activation, handlers, rules, help/exit, prefixes

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

@@ -0,0 +1,523 @@
+# BMAD Agent Menu Patterns
+
+Design patterns for agent menus in YAML source files.
+
+## Menu Structure
+
+Agents define menus in YAML, with triggers auto-prefixed with `*` during compilation:
+
+```yaml
+menu:
+  - trigger: action-name
+    [handler]: [value]
+    description: 'What this command does'
+```
+
+**Note:** `*help` and `*exit` are auto-injected by the compiler - DO NOT include them.
+
+## Handler Types
+
+### 1. Action Handler (Prompts & Inline)
+
+For simple and expert agents with self-contained logic.
+
+**Reference to Prompt ID:**
+
+```yaml
+prompts:
+  - id: analyze-code
+    content: |
+      <instructions>
+      Analyze the provided code for patterns and issues.
+      </instructions>
+
+      <process>
+      1. Identify code structure
+      2. Check for anti-patterns
+      3. Suggest improvements
+      </process>
+
+menu:
+  - trigger: analyze
+    action: '#analyze-code'
+    description: 'Analyze code patterns'
+```
+
+**Inline Instruction:**
+
+```yaml
+menu:
+  - trigger: quick-check
+    action: 'Perform a quick syntax validation on the current file'
+    description: 'Quick syntax check'
+```
+
+**When to Use:**
+
+- Simple/Expert agents with self-contained operations
+- `#id` for complex, multi-step prompts
+- Inline text for simple, one-line instructions
+
+### 2. Workflow Handler
+
+For module agents orchestrating multi-step processes.
+
+```yaml
+menu:
+  - trigger: create-prd
+    workflow: '{project-root}/_bmad/bmm/workflows/prd/workflow.yaml'
+    description: 'Create Product Requirements Document'
+
+  - trigger: brainstorm
+    workflow: '{project-root}/_bmad/core/workflows/brainstorming/workflow.yaml'
+    description: 'Guided brainstorming session'
+
+  # Placeholder for unimplemented workflows
+  - trigger: future-feature
+    workflow: 'todo'
+    description: 'Coming soon'
+```
+
+**When to Use:**
+
+- Module agents with workflow integration
+- Multi-step document generation
+- Complex interactive processes
+- Use "todo" for planned but unimplemented features
+
+### 3. Exec Handler
+
+For executing tasks directly.
+
+```yaml
+menu:
+  - trigger: validate
+    exec: '{project-root}/_bmad/core/tasks/validate-workflow.xml'
+    description: 'Validate document structure'
+
+  - trigger: advanced-elicitation
+    exec: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+    description: 'Advanced elicitation techniques'
+```
+
+**When to Use:**
+
+- Single-operation tasks
+- Core system operations
+- Utility functions
+
+### 4. Template Handler
+
+For document generation with templates.
+
+```yaml
+menu:
+  - trigger: create-brief
+    exec: '{project-root}/_bmad/core/tasks/create-doc.xml'
+    tmpl: '{project-root}/_bmad/bmm/templates/brief.md'
+    description: 'Create a Product Brief'
+```
+
+**When to Use:**
+
+- Template-based document creation
+- Combine `exec` with `tmpl` path
+- Structured output generation
+
+### 5. Data Handler
+
+Universal attribute for supplementary information.
+
+```yaml
+menu:
+  - trigger: team-standup
+    exec: '{project-root}/_bmad/bmm/tasks/standup.xml'
+    data: '{project-root}/_bmad/_config/agent-manifest.csv'
+    description: 'Run team standup'
+
+  - trigger: analyze-metrics
+    action: 'Analyze these metrics and identify trends'
+    data: '{project-root}/_data/metrics.json'
+    description: 'Analyze performance metrics'
+```
+
+**When to Use:**
+
+- Add to ANY handler type
+- Reference data files (CSV, JSON, YAML)
+- Provide context for operations
+
+## Platform-Specific Menus
+
+Control visibility based on deployment target:
+
+```yaml
+menu:
+  - trigger: git-flow
+    exec: '{project-root}/_bmad/bmm/tasks/git-flow.xml'
+    description: 'Git workflow operations'
+    ide-only: true # Only in IDE environments
+
+  - trigger: advanced-elicitation
+    exec: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
+    description: 'Advanced elicitation'
+    web-only: true # Only in web bundles
+```
+
+## Trigger Naming Conventions
+
+### Action-Based (Recommended)
+
+```yaml
+# Creation
+- trigger: create-prd
+- trigger: build-module
+- trigger: generate-report
+
+# Analysis
+- trigger: analyze-requirements
+- trigger: review-code
+- trigger: validate-architecture
+
+# Operations
+- trigger: update-status
+- trigger: sync-data
+- trigger: deploy-changes
+```
+
+### Domain-Based
+
+```yaml
+# Development
+- trigger: brainstorm
+- trigger: architect
+- trigger: refactor
+
+# Project Management
+- trigger: sprint-plan
+- trigger: retrospective
+- trigger: standup
+```
+
+### Bad Patterns
+
+```yaml
+# TOO VAGUE
+- trigger: do
+- trigger: run
+- trigger: process
+
+# TOO LONG
+- trigger: create-comprehensive-product-requirements-document
+
+# NO VERB
+- trigger: prd
+- trigger: config
+```
+
+## Menu Organization
+
+### Recommended Order
+
+```yaml
+menu:
+  # Note: *help auto-injected first by compiler
+
+  # 1. Primary workflows (main value)
+  - trigger: workflow-init
+    workflow: '...'
+    description: 'Start here - initialize workflow'
+
+  - trigger: create-prd
+    workflow: '...'
+    description: 'Create PRD'
+
+  # 2. Secondary operations
+  - trigger: validate
+    exec: '...'
+    description: 'Validate document'
+
+  # 3. Utilities
+  - trigger: party-mode
+    workflow: '...'
+    description: 'Multi-agent discussion'
+
+  # Note: *exit auto-injected last by compiler
+```
+
+### Grouping by Phase
+
+```yaml
+menu:
+  # Analysis Phase
+  - trigger: brainstorm
+    workflow: '{project-root}/_bmad/bmm/workflows/1-analysis/brainstorm/workflow.yaml'
+    description: 'Brainstorm ideas'
+
+  - trigger: research
+    workflow: '{project-root}/_bmad/bmm/workflows/1-analysis/research/workflow.yaml'
+    description: 'Conduct research'
+
+  # Planning Phase
+  - trigger: prd
+    workflow: '{project-root}/_bmad/bmm/workflows/2-planning/prd/workflow.yaml'
+    description: 'Create PRD'
+
+  - trigger: architecture
+    workflow: '{project-root}/_bmad/bmm/workflows/2-planning/architecture/workflow.yaml'
+    description: 'Design architecture'
+```
+
+## Description Best Practices
+
+### Good Descriptions
+
+```yaml
+# Clear action + object
+- description: 'Create Product Requirements Document'
+
+# Specific outcome
+- description: 'Analyze security vulnerabilities'
+
+# User benefit
+- description: 'Optimize code for performance'
+
+# Context when needed
+- description: 'Start here - initialize workflow path'
+```
+
+### Poor Descriptions
+
+```yaml
+# Too vague
+- description: 'Process'
+
+# Technical jargon
+- description: 'Execute WF123'
+
+# Missing context
+- description: 'Run'
+
+# Redundant with trigger
+- description: 'Create PRD' # trigger: create-prd (too similar)
+```
+
+## Prompts Section (Simple/Expert Agents)
+
+### Prompt Structure
+
+```yaml
+prompts:
+  - id: unique-identifier
+    content: |
+      <instructions>
+      What this prompt accomplishes
+      </instructions>
+
+      <process>
+      1. First step
+      {{#if custom_option}}
+      2. Conditional step
+      {{/if}}
+      3. Final step
+      </process>
+
+      <output_format>
+      Expected structure of results
+      </output_format>
+```
+
+### Semantic XML Tags in Prompts
+
+Use XML tags to structure prompt content:
+
+- `<instructions>` - What to do
+- `<process>` - Step-by-step approach
+- `<output_format>` - Expected results
+- `<examples>` - Sample outputs
+- `<constraints>` - Limitations
+- `<context>` - Background information
+
+### Handlebars in Prompts
+
+Customize based on install_config:
+
+```yaml
+prompts:
+  - id: analyze
+    content: |
+      {{#if detailed_mode}}
+      Perform comprehensive analysis with full explanations.
+      {{/if}}
+      {{#unless detailed_mode}}
+      Quick analysis focusing on key points.
+      {{/unless}}
+
+      Address {{user_name}} in {{communication_style}} tone.
+```
+
+## Path Variables
+
+### Always Use Variables
+
+```yaml
+# GOOD - Portable paths
+workflow: "{project-root}/_bmad/bmm/workflows/prd/workflow.yaml"
+exec: "{project-root}/_bmad/core/tasks/validate.xml"
+data: "{project-root}/_data/metrics.csv"
+
+# BAD - Hardcoded paths
+workflow: "/Users/john/project/_bmad/bmm/workflows/prd/workflow.yaml"
+exec: "../../../core/tasks/validate.xml"
+```
+
+### Available Variables
+
+- `{project-root}` - Project root directory
+- `_bmad` - BMAD installation folder
+- `{output_folder}` - Document output location
+- `{user_name}` - User's name from config
+- `{communication_language}` - Language preference
+
+## Complete Examples
+
+### Simple Agent Menu
+
+```yaml
+prompts:
+  - id: format-code
+    content: |
+      <instructions>
+      Format the provided code according to style guidelines.
+      </instructions>
+
+      Apply:
+      - Consistent indentation
+      - Proper spacing
+      - Clear naming conventions
+
+menu:
+  - trigger: format
+    action: '#format-code'
+    description: 'Format code to style guidelines'
+
+  - trigger: lint
+    action: 'Check code for common issues and anti-patterns'
+    description: 'Lint code for issues'
+
+  - trigger: suggest
+    action: 'Suggest improvements for code readability'
+    description: 'Suggest improvements'
+```
+
+### Expert Agent Menu
+
+```yaml
+critical_actions:
+  - 'Load ./memories.md'
+  - 'Follow ./instructions.md'
+  - 'ONLY access ./'
+
+prompts:
+  - id: reflect
+    content: |
+      Guide {{user_name}} through reflection on recent entries.
+      Reference patterns from memories.md naturally.
+
+menu:
+  - trigger: write
+    action: '#reflect'
+    description: 'Write journal entry'
+
+  - trigger: save
+    action: 'Update ./memories.md with session insights'
+    description: "Save today's session"
+
+  - trigger: patterns
+    action: 'Analyze recent entries for recurring themes'
+    description: 'View patterns'
+```
+
+### Module Agent Menu
+
+```yaml
+menu:
+  - trigger: workflow-init
+    workflow: '{project-root}/_bmad/bmm/workflows/workflow-status/init/workflow.yaml'
+    description: 'Initialize workflow path (START HERE)'
+
+  - trigger: brainstorm
+    workflow: '{project-root}/_bmad/bmm/workflows/1-analysis/brainstorm/workflow.yaml'
+    description: 'Guided brainstorming'
+
+  - trigger: prd
+    workflow: '{project-root}/_bmad/bmm/workflows/2-planning/prd/workflow.yaml'
+    description: 'Create PRD'
+
+  - trigger: architecture
+    workflow: '{project-root}/_bmad/bmm/workflows/2-planning/architecture/workflow.yaml'
+    description: 'Design architecture'
+
+  - trigger: party-mode
+    workflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.yaml'
+    description: 'Multi-agent discussion'
+```
+
+## Validation Checklist
+
+- [ ] No duplicate triggers
+- [ ] Triggers don't start with `*` (auto-added)
+- [ ] Every item has a description
+- [ ] Paths use variables, not hardcoded
+- [ ] `#id` references exist in prompts section
+- [ ] Workflow paths resolve or are "todo"
+- [ ] No `*help` or `*exit` (auto-injected)
+- [ ] Descriptions are clear and action-oriented
+- [ ] Platform-specific flags used correctly (ide-only, web-only)
+
+## Common Mistakes
+
+### Duplicate Triggers
+
+```yaml
+# BAD - compiler will fail
+- trigger: analyze
+  action: '#first'
+  description: 'First analysis'
+
+- trigger: analyze
+  action: '#second'
+  description: 'Second analysis'
+```
+
+### Including Auto-Injected Items
+
+```yaml
+# BAD - these are auto-injected
+menu:
+  - trigger: help
+    description: 'Show help'
+
+  - trigger: exit
+    description: 'Exit agent'
+```
+
+### Missing Prompt Reference
+
+```yaml
+# BAD - prompt id doesn't exist
+menu:
+  - trigger: analyze
+    action: '#nonexistent-prompt'
+    description: 'Analysis'
+```
+
+### Hardcoded Paths
+
+```yaml
+# BAD - not portable
+menu:
+  - trigger: run
+    workflow: '/absolute/path/to/workflow.yaml'
+    description: 'Run workflow'
+```

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

@@ -0,0 +1,363 @@
+# Expert Agent Architecture
+
+Domain-specific agents with persistent memory, sidecar files, and restricted access patterns.
+
+## When to Use
+
+- Personal assistants (journal keeper, diary companion)
+- Specialized domain experts (legal advisor, medical reference)
+- Agents that need to remember past interactions
+- Agents with restricted file system access (privacy/security)
+- Long-term relationship agents that learn about users
+
+## File Structure
+
+```
+{agent-name}/
+├── {agent-name}.agent.yaml    # Main agent definition
+└── {agent-name}-sidecar/      # Supporting files
+    ├── instructions.md        # Private directives
+    ├── memories.md            # Persistent memory
+    ├── knowledge/             # Domain-specific resources
+    │   └── README.md
+    └── [custom files]         # Agent-specific resources
+```
+
+## YAML Structure
+
+```yaml
+agent:
+  metadata:
+    name: 'Persona Name'
+    title: 'Agent Title'
+    icon: 'emoji'
+    type: 'expert'
+
+  persona:
+    role: 'Domain Expert with specialized capability'
+
+    identity: |
+      Background and expertise in first-person voice.
+      {{#if user_preference}}
+      Customization based on install_config.
+      {{/if}}
+
+    communication_style: |
+      {{#if tone_style == "gentle"}}
+      Gentle and supportive communication...
+      {{/if}}
+      {{#if tone_style == "direct"}}
+      Direct and efficient communication...
+      {{/if}}
+      I reference past conversations naturally.
+
+    principles:
+      - Core belief about the domain
+      - How I handle user information
+      - My approach to memory and learning
+
+  critical_actions:
+    - 'Load COMPLETE file ./{agent-name}-sidecar/memories.md and remember all past insights'
+    - 'Load COMPLETE file ./{agent-name}-sidecar/instructions.md and follow ALL protocols'
+    - 'ONLY read/write files in ./{agent-name}-sidecar/ - this is our private space'
+    - 'Address user as {{greeting_name}}'
+    - 'Track patterns, themes, and important moments'
+    - 'Reference past interactions naturally to show continuity'
+
+  prompts:
+    - id: main-function
+      content: |
+        <instructions>
+        Guide user through the primary function.
+        {{#if tone_style == "gentle"}}
+        Use gentle, supportive approach.
+        {{/if}}
+        </instructions>
+
+        <process>
+        1. Understand context
+        2. Provide guidance
+        3. Record insights
+        </process>
+
+    - id: memory-recall
+      content: |
+        <instructions>
+        Access and share relevant memories.
+        </instructions>
+
+        Reference stored information naturally.
+
+  menu:
+    - trigger: action1
+      action: '#main-function'
+      description: 'Primary agent function'
+
+    - trigger: remember
+      action: 'Update ./{agent-name}-sidecar/memories.md with session insights'
+      description: 'Save what we discussed today'
+
+    - trigger: insight
+      action: 'Document breakthrough in ./{agent-name}-sidecar/breakthroughs.md'
+      description: 'Record a significant insight'
+
+    - multi: "[DF] Do Foo or start [CH] Chat with expert"
+      triggers:
+        - do-foo
+            - input: [DF] or fuzzy match on do foo
+            - action: '#main-action'
+            - data: what is being discussed or suggested with the command, along with custom party custom agents if specified
+            - type: action
+        - expert-chat:
+            - input: [CH] or fuzzy match validate agent
+            - action: agent responds as expert based on its persona to converse
+            - type: action
+
+  install_config:
+    compile_time_only: true
+    description: 'Personalize your expert agent'
+    questions:
+      - var: greeting_name
+        prompt: 'What should the agent call you?'
+        type: text
+        default: 'friend'
+
+      - var: tone_style
+        prompt: 'Preferred communication tone?'
+        type: choice
+        options:
+          - label: 'Gentle - Supportive and nurturing'
+            value: 'gentle'
+          - label: 'Direct - Clear and efficient'
+            value: 'direct'
+        default: 'gentle'
+
+      - var: user_preference
+        prompt: 'Enable personalized features?'
+        type: boolean
+        default: true
+```
+
+## Key Components
+
+### Sidecar Files (CRITICAL)
+
+Expert agents use companion files for persistence and domain knowledge:
+
+**memories.md** - Persistent user context
+
+```markdown
+# Agent Memory Bank
+
+## User Preferences
+
+<!-- Learned from interactions -->
+
+## Session History
+
+<!-- Important moments and insights -->
+
+## Personal Notes
+
+<!-- Agent observations -->
+```
+
+**instructions.md** - Private directives
+
+```markdown
+# Agent Private Instructions
+
+## Core Directives
+
+- Maintain character consistency
+- Domain boundaries: {specific domain}
+- Access restrictions: Only sidecar folder
+
+## Special Rules
+
+<!-- Agent-specific protocols -->
+```
+
+**knowledge/** - Domain resources
+
+```markdown
+# Agent Knowledge Base
+
+Add domain-specific documentation here.
+```
+
+### Critical Actions
+
+**MANDATORY for expert agents** - These load sidecar files at activation:
+
+```yaml
+critical_actions:
+  - 'Load COMPLETE file ./{sidecar}/memories.md and remember all past insights'
+  - 'Load COMPLETE file ./{sidecar}/instructions.md and follow ALL protocols'
+  - 'ONLY read/write files in ./{sidecar}/ - this is our private space'
+```
+
+**Key patterns:**
+
+- **COMPLETE file loading** - Forces full file read, not partial
+- **Domain restrictions** - Limits file access for privacy/security
+- **Memory integration** - Past context becomes part of current session
+- **Protocol adherence** - Ensures consistent behavior
+
+## What Gets Injected at Compile Time
+
+Same as simple agents, PLUS:
+
+1. **Critical actions become numbered activation steps**
+
+   ```xml
+   <step n="4">Load COMPLETE file ./memories.md...</step>
+   <step n="5">Load COMPLETE file ./instructions.md...</step>
+   <step n="6">ONLY read/write files in ./...</step>
+   ```
+
+2. **Sidecar files copied during installation**
+   - Entire sidecar folder structure preserved
+   - Relative paths maintained
+   - Files ready for agent use
+
+## Reference Example
+
+See: [journal-keeper/](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/agents/expert-examples/journal-keeper)
+
+Features demonstrated:
+
+- Complete sidecar structure (memories, instructions, breakthroughs)
+- Critical actions for loading persistent context
+- Domain restrictions for privacy
+- Pattern recognition and memory recall
+- Handlebars-based personalization
+- Menu actions that update sidecar files
+
+## Installation
+
+```bash
+# Copy entire folder to your project
+cp -r /path/to/journal-keeper/ _bmad/custom/agents/
+
+# Install with personalization
+bmad agent-install
+```
+
+The installer:
+
+1. Detects expert agent (folder with .agent.yaml)
+2. Prompts for personalization
+3. Compiles agent YAML to XML-in-markdown
+4. **Copies sidecar files to installation target**
+5. Creates IDE slash commands
+6. Saves source for reinstallation
+
+## Memory Patterns
+
+### Accumulative Memory
+
+```yaml
+menu:
+  - trigger: save
+    action: "Update ./sidecar/memories.md with today's session insights"
+    description: 'Save session to memory'
+```
+
+### Reference Memory
+
+```yaml
+prompts:
+  - id: recall
+    content: |
+      <instructions>
+      Reference memories.md naturally:
+      "Last week you mentioned..." or "I notice a pattern..."
+      </instructions>
+```
+
+### Structured Insights
+
+```yaml
+menu:
+  - trigger: insight
+    action: 'Document in ./sidecar/breakthroughs.md with date, context, significance'
+    description: 'Record meaningful insight'
+```
+
+## Domain Restriction Patterns
+
+### Single Folder Access
+
+```yaml
+critical_actions:
+  - 'ONLY read/write files in ./sidecar/ - NO OTHER FOLDERS'
+```
+
+### User Space Access
+
+```yaml
+critical_actions:
+  - 'ONLY access files in {user-folder}/journals/ - private space'
+```
+
+### Read-Only Access
+
+```yaml
+critical_actions:
+  - 'Load knowledge from ./knowledge/ but NEVER modify'
+  - 'Write ONLY to ./sessions/'
+```
+
+## Best Practices
+
+1. **Load sidecar files in critical_actions** - Must be explicit and MANDATORY
+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
+
+### Session Continuity
+
+```yaml
+communication_style: |
+  I reference past conversations naturally:
+  "Last time we discussed..." or "I've noticed over the weeks..."
+```
+
+### Pattern Recognition
+
+```yaml
+critical_actions:
+  - 'Track mood patterns, recurring themes, and breakthrough moments'
+  - 'Cross-reference current session with historical patterns'
+```
+
+### Adaptive Responses
+
+```yaml
+identity: |
+  I learn your preferences and adapt my approach over time.
+  {{#if track_preferences}}
+  I maintain notes about what works best for you.
+  {{/if}}
+```
+
+## Validation Checklist
+
+- [ ] Valid YAML syntax
+- [ ] Metadata includes `type: "expert"`
+- [ ] critical_actions loads sidecar files explicitly
+- [ ] critical_actions enforces domain restrictions
+- [ ] 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/[agentname]-sidecar/ to reference sidecar content
+- [ ] Install config personalizes sidecar references
+- [ ] Agent folder named consistently: `{agent-name}/`
+- [ ] YAML file named: `{agent-name}.agent.yaml`
+- [ ] Sidecar folder named: `{agent-name}-sidecar/`

src/modules/bmb/docs/agents/index.md

@@ -0,0 +1,55 @@
+# BMB Module Documentation
+
+Reference documentation for building BMAD agents and workflows.
+
+## Agent Architecture
+
+Comprehensive guides for each agent type (choose based on use case):
+
+- [Understanding Agent Types](./understanding-agent-types.md) - **START HERE** - Architecture vs capability, "The Same Agent, Three Ways"
+- [Simple Agent Architecture](./simple-agent-architecture.md) - Self-contained, optimized, personality-driven
+- [Expert Agent Architecture](./expert-agent-architecture.md) - Memory, sidecar files, domain restrictions
+- Module Agent Architecture _(TODO)_ - Workflow integration, professional tools
+
+## Agent Design Patterns
+
+- [Agent Menu Patterns](./agent-menu-patterns.md) - Menu handlers, triggers, prompts, organization
+- [Agent Compilation](./agent-compilation.md) - What compiler auto-injects (AVOID DUPLICATION)
+
+## Reference Examples
+
+Production-ready examples in [bmb/reference/agents/](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/agents):
+
+**Simple Agents** ([simple-examples/](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/agents/simple-examples))
+
+- [commit-poet.agent.yaml](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/src/modules/bmb/reference/agents/simple-examples/commit-poet.agent.yaml) - Commit message artisan with style customization
+
+**Expert Agents** ([expert-examples/](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/agents/expert-examples))
+
+- [journal-keeper/](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/agents/expert-examples/journal-keeper) - Personal journal companion with memory and pattern recognition
+
+**Module Agents** ([module-examples/](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/agents/module-examples))
+
+- [security-engineer.agent.yaml](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/src/modules/bmb/reference/agents/module-examples/security-engineer.agent.yaml) - BMM security specialist with threat modeling
+- [trend-analyst.agent.yaml](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/src/modules/bmb/reference/agents/module-examples/trend-analyst.agent.yaml) - CIS trend intelligence expert
+
+## Installation Guide
+
+For installing standalone simple and expert agents, see:
+
+- [Custom Agent Installation](/docs/modules/bmb-bmad-builder/custom-content-installation.md)
+
+## Key Concepts
+
+### YAML to XML Compilation
+
+Agents are authored in YAML with Handlebars templating. The compiler auto-injects:
+
+1. **Frontmatter** - Name and description from metadata
+2. **Activation Block** - Steps, menu handlers, rules (YOU don't write this)
+3. **Menu Enhancement** - `*help` and `*exit` commands added automatically
+4. **Trigger Prefixing** - Your triggers auto-prefixed with `*`
+
+**Critical:** See [Agent Compilation](./agent-compilation.md) to avoid duplicating auto-injected content.
+
+Source: `tools/cli/lib/agent/compiler.js`

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

@@ -0,0 +1,257 @@
+# Simple Agent Architecture
+
+Self-contained agents with prompts, menus, and optional install-time customization.
+
+## When to Use
+
+- Single-purpose utilities (commit message generator, code formatter)
+- Self-contained logic with no external dependencies
+- Agents that benefit from user customization (style, tone, preferences)
+- Quick-to-build standalone helpers
+
+## YAML Structure
+
+```yaml
+agent:
+  metadata:
+    id: _bmad/agents/{agent-name}/{agent-name}.md
+    name: 'Persona Name'
+    title: 'Agent Title'
+    icon: 'emoji'
+    type: simple
+
+  persona:
+    role: |
+      First-person description of primary function (1-2 sentences)
+
+    identity: |
+      Background, experience, specializations in first-person (2-5 sentences)
+      {{#if custom_variable}}
+      Conditional identity text based on install_config
+      {{/if}}
+
+    communication_style: |
+      {{#if style_choice == "professional"}}
+      Professional and systematic approach...
+      {{/if}}
+      {{#if style_choice == "casual"}}
+      Friendly and approachable tone...
+      {{/if}}
+
+    principles:
+      - Core belief or methodology
+      - Another guiding principle
+      - Values that shape decisions
+
+  prompts:
+    - id: main-action
+      content: |
+        <instructions>
+        What this prompt does
+        </instructions>
+
+        <process>
+        1. Step one
+        {{#if detailed_mode}}
+        2. Additional detailed step
+        {{/if}}
+        3. Final step
+        </process>
+
+    - id: another-action
+      content: |
+        Another reusable prompt template
+
+  menu:
+    - trigger: inline
+      action: 'Direct inline prompt text'
+      description: 'Execute inline action'
+
+    - multi: "[DF] Do Foo or start [CH] Chat with expert"
+      triggers:
+        - do-foo
+            - input: [DF] or fuzzy match on do foo
+            - action: '#main-action'
+            - data: what is being discussed or suggested with the command, along with custom party custom agents if specified
+            - type: action
+        - expert-chat:
+            - input: [CH] or fuzzy match validate agent
+            - action: agent responds as expert based on its persona to converse
+            - type: action
+
+  install_config:
+    compile_time_only: true
+    description: 'Personalize your agent'
+    questions:
+      - var: style_choice
+        prompt: 'Preferred communication style?'
+        type: choice
+        options:
+          - label: 'Professional'
+            value: 'professional'
+          - label: 'Casual'
+            value: 'casual'
+        default: 'professional'
+
+      - var: detailed_mode
+        prompt: 'Enable detailed explanations?'
+        type: boolean
+        default: true
+
+      - var: custom_variable
+        prompt: 'Your custom text'
+        type: text
+        default: ''
+```
+
+## Key Components
+
+### Metadata
+
+- **id**: Final compiled path (`_bmad/agents/{name}/{name}.md` for standalone)
+- **name**: Agent's persona name displayed to users
+- **title**: Professional role/function
+- **icon**: Single emoji for visual identification
+- **type**: `simple` - identifies agent category
+
+### Persona (First-Person Voice)
+
+- **role**: Primary expertise in 1-2 sentences
+- **identity**: Background and specializations (2-5 sentences)
+- **communication_style**: HOW the agent interacts, including conditional variations
+- **principles**: Array of core beliefs (start with action verbs)
+
+### Prompts with IDs
+
+Reusable prompt templates referenced by `#id`:
+
+```yaml
+prompts:
+  - id: analyze-code
+    content: |
+      <instructions>
+      Analyze the provided code for patterns
+      </instructions>
+```
+
+Menu items reference these:
+
+```yaml
+menu:
+  - trigger: analyze
+    action: '#analyze-code'
+    description: 'Analyze code patterns'
+```
+
+### Menu Actions
+
+Two forms of action handlers:
+
+1. **Prompt Reference**: `action: "#prompt-id"` - Executes prompt content
+2. **Inline Instruction**: `action: "Direct text instruction"` - Executes text directly
+
+### Install Config (Compile-Time Customization)
+
+Questions asked during `bmad agent-install`:
+
+**Question Types:**
+
+- `choice` - Multiple choice selection
+- `boolean` - Yes/no toggle
+- `text` - Free-form text input
+
+**Variables become available in Handlebars:**
+
+```yaml
+{{#if variable_name}}
+Content when true
+{{/if}}
+
+{{#if variable_name == "value"}}
+Content when equals value
+{{/if}}
+
+{{#unless variable_name}}
+Content when false
+{{/unless}}
+```
+
+## What Gets Injected at Compile Time
+
+The `tools/cli/lib/agent/compiler.js` automatically adds:
+
+1. **YAML Frontmatter**
+
+   ```yaml
+   ---
+   name: 'agent name'
+   description: 'Agent Title'
+   ---
+   ```
+
+2. **Activation Block**
+   - Load persona step
+   - Load core config for {user_name}, {communication_language}
+   - Agent-specific critical_actions as numbered steps
+   - Menu display and input handling
+   - Menu handlers (action/workflow/exec/tmpl) based on usage
+   - Rules section
+
+3. **Auto-Injected Menu Items**
+   - `*help` always first
+   - `*exit` always last
+
+4. **Trigger Prefixing**
+   - Triggers without `*` get it added automatically
+
+## Reference Example
+
+See: [commit-poet.agent.yaml](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/src/modules/bmb/reference/agents/simple-examples/commit-poet.agent.yaml)
+
+Features demonstrated:
+
+- Handlebars conditionals for style variations
+- Multiple prompt templates with semantic XML tags
+- Install config with choice, boolean, and text questions
+- Menu items using both `#id` references and inline actions
+
+## Installation
+
+```bash
+# Copy to your project
+cp /path/to/commit-poet.agent.yaml _bmad/custom/agents/
+
+# Create custom.yaml and install
+echo "code: my-agent
+name: My Agent
+default_selected: true" > custom.yaml
+
+npx bmad-method install
+# or: bmad install
+```
+
+The installer:
+
+1. Prompts for personalization (name, preferences)
+2. Processes Handlebars templates with your answers
+3. Compiles YAML to XML-in-markdown
+4. Creates IDE slash commands
+5. Saves source for reinstallation
+
+## Best Practices
+
+1. **Use first-person voice** in all persona elements
+2. **Keep prompts focused** - one clear purpose per prompt
+3. **Leverage Handlebars** for user customization without code changes
+4. **Provide sensible defaults** in install_config
+5. **Use semantic XML tags** in prompt content for clarity
+6. **Test all conditional paths** before distribution
+
+## Validation Checklist
+
+- [ ] Valid YAML syntax
+- [ ] All metadata fields present (id, name, title, icon, type)
+- [ ] Persona complete (role, identity, communication_style, principles)
+- [ ] Prompts have unique IDs
+- [ ] Install config questions have defaults
+- [ ] File named `{agent-name}.agent.yaml`

src/modules/bmb/docs/agents/understanding-agent-types.md

@@ -0,0 +1,184 @@
+# Understanding Agent Types: Architecture, Not Capability
+
+**CRITICAL DISTINCTION:** Agent types define **architecture and integration**, NOT capability limits.
+
+ALL agent types can:
+
+- ✓ Write to {output_folder}, {project-root}, or anywhere on system
+- ✓ Update artifacts and files
+- ✓ Execute bash commands
+- ✓ Use core variables (_bmad, {output_folder}, etc.)
+- ✓ Have complex prompts and logic
+- ✓ Invoke external tools
+
+## What Actually Differs
+
+| Feature                | Simple        | Expert               | Module             |
+| ---------------------- | ------------- | -------------------- | ------------------ |
+| **Self-contained**     | ✓ All in YAML | Sidecar files        | Sidecar optional   |
+| **Persistent memory**  | ✗ Stateless   | ✓ memories.md        | ✓ If needed        |
+| **Knowledge base**     | ✗             | ✓ sidecar/knowledge/ | Module/shared      |
+| **Domain restriction** | ✗ System-wide | ✓ Sidecar only       | Optional           |
+| **Personal workflows** | ✗             | ✓ Sidecar workflows  | ✗                  |
+| **Module workflows**   | ✗             | ✗                    | ✓ Shared workflows |
+| **Team integration**   | Solo utility  | Personal assistant   | Team member        |
+
+Expert agents CAN have personal workflows in sidecar if critical_actions loads workflow engine
+
+## The Same Agent, Three Ways
+
+**Scenario:** Code Generator Agent
+
+### As Simple Agent (Architecture: Self-contained)
+
+```yaml
+agent:
+  metadata:
+    name: CodeGen
+    type: simple
+
+  prompts:
+    - id: generate
+      content: |
+        Ask user for spec details. Generate code.
+        Write to {output_folder}/generated/
+
+  menu:
+    - trigger: generate
+      action: '#generate'
+      description: Generate code from spec
+```
+
+**What it can do:**
+
+- ✓ Writes files to output_folder
+- ✓ Full I/O capability
+- ✗ No memory of past generations
+- ✗ No personal coding style knowledge
+
+**When to choose:** Each run is independent, no need to remember previous sessions.
+
+### As Expert Agent (Architecture: Personal sidecar)
+
+```yaml
+agent:
+  metadata:
+    name: CodeGen
+    type: expert
+
+  critical_actions:
+    - Load my coding standards from sidecar/knowledge/
+    - Load memories from sidecar/memories.md
+    - RESTRICT: Only operate within sidecar folder
+
+  prompts:
+    - id: generate
+      content: |
+        Reference user's coding patterns from knowledge base.
+        Remember past generations from memories.
+        Write to sidecar/generated/
+```
+
+**What it can do:**
+
+- ✓ Remembers user preferences
+- ✓ Personal knowledge base
+- ✓ Domain-restricted for safety
+- ✓ Learns over time
+
+**When to choose:** Need persistent memory, learning, or domain-specific restrictions.
+
+### As Module Agent (Architecture: Team integration)
+
+```yaml
+agent:
+  metadata:
+    name: CodeGen
+    module: bmm
+
+  menu:
+    - trigger: implement-story
+      workflow: '_bmad/bmm/workflows/dev-story/workflow.yaml'
+      description: Implement user story
+
+    - trigger: refactor
+      workflow: '_bmad/bmm/workflows/refactor/workflow.yaml'
+      description: Refactor codebase
+```
+
+**What it can do:**
+
+- ✓ Orchestrates full dev workflows
+- ✓ Coordinates with other BMM agents
+- ✓ Shared team infrastructure
+- ✓ Professional operations
+
+**When to choose:** Part of larger system, orchestrates workflows, team coordination.
+
+## Important: Any Agent Can Be Added to a Module
+
+**CLARIFICATION:** The "Module Agent" type is about **design intent and ecosystem integration**, not just file location.
+
+### The Reality
+
+- **Any agent type** (Simple, Expert, Module) can be bundled with or added to a module
+- A Simple agent COULD live in `_bmad/bmm/agents/`
+- An Expert agent COULD be included in a module bundle
+
+### What Makes a "Module Agent" Special
+
+A **Module Agent** is specifically:
+
+1. **Designed FOR** a particular module ecosystem (BMM, CIS, BMB, etc.)
+2. **Uses or contributes** that module's workflows
+3. **Included by default** in that module's bundle
+4. **Coordinates with** other agents in that module
+
+### Examples
+
+**Simple Agent added to BMM:**
+
+- Lives in `_bmad/bmm/agents/formatter.agent.yaml`
+- Bundled with BMM for convenience
+- But still stateless, self-contained
+- NOT a "Module Agent" - just a Simple agent in a module
+
+**Module Agent in BMM:**
+
+- Lives in `_bmad/bmm/agents/tech-writer.agent.yaml`
+- Orchestrates BMM documentation workflows
+- Coordinates with other BMM agents (PM, Dev, Analyst)
+- Included in default BMM bundle
+- IS a "Module Agent" - designed for BMM ecosystem
+
+**The distinction:** File location vs design intent and integration.
+
+## Choosing Your Agent Type
+
+### Choose Simple when:
+
+- Single-purpose utility (no memory needed)
+- Stateless operations (each run is independent)
+- Self-contained logic (everything in YAML)
+- No persistent context required
+
+### Choose Expert when:
+
+- Need to remember things across sessions
+- Personal knowledge base (user preferences, domain data)
+- Domain-specific expertise with restricted scope
+- Learning/adapting over time
+
+### Choose Module when:
+
+- Designed FOR a specific module ecosystem (BMM, CIS, etc.)
+- Uses or contributes that module's workflows
+- Coordinates with other module agents
+- Will be included in module's default bundle
+- Part of professional team infrastructure
+
+## The Golden Rule
+
+**Choose based on state and integration needs, NOT on what the agent can DO.**
+
+All three types are equally powerful. The difference is how they manage state, where they store data, and how they integrate with your system.

src/modules/bmb/docs/index.md

@@ -0,0 +1,247 @@
+# BMB - BMad Builder Module
+
+Specialized tools and workflows for creating, customizing, and extending BMad components including agents, workflows, and complete modules.
+
+## Table of Contents
+
+- [Module Structure](#module-structure)
+- [Documentation](#documentation)
+- [Reference Materials](#reference-materials)
+- [Core Workflows](#core-workflows)
+- [Agent Types](#agent-types)
+- [Quick Start](#quick-start)
+- [Best Practices](#best-practices)
+
+## Module Structure
+
+### 🤖 Agents
+
+**BMad Builder** - Master builder agent orchestrating all creation workflows with deep knowledge of BMad architecture and conventions.
+
+- Install Location: `_bmad/bmb/agents/bmad-builder.md`
+
+### 📚 Documentation
+
+- Comprehensive guides for agents, workflows, and modules
+- Architecture patterns and best practices
+
+### 🔍 Reference Materials
+
+- Location: `../reference/`
+- Working examples of custom stand alone agents and workflows
+- Template patterns and implementation guides
+
+## Documentation
+
+### 📖 Agent Documentation
+
+- **[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](./workflows/index.md)** - Core workflow system overview
+- **[Architecture Guide](./workflows/architecture.md)** - Step-file design and JIT loading
+- **Template System** _(TODO)_ - Standard step file template
+- **[Intent vs Prescriptive](./workflows/intent-vs-prescriptive-spectrum.md)** - Design philosophy
+
+## Reference Materials
+
+### 🤖 Agent Examples
+
+- **[Simple Agent Example](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/src/modules/bmb/reference/agents/simple-examples/commit-poet.agent.yaml)** - Self-contained agent
+- **[Expert Agent Example](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/src/modules/bmb/reference/agents/expert-examples/journal-keeper/journal-keeper.agent.yaml)** - Agent with persistent memory
+- **[Module Add On Agent Examples](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/src/modules/bmb/reference/agents/module-examples/security-engineer.agent.yaml)** - Integration patterns (BMM, CIS)
+
+### 📋 Workflow Examples
+
+- **[Meal Prep & Nutrition](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/workflows/meal-prep-nutrition)** - Complete step-file workflow demonstration
+- **Template patterns** for document generation and state management
+
+## Core Workflows
+
+### Creation Workflows (Step-File Architecture)
+
+**create-agent** _(TODO)_ - Build BMad agents
+
+- 11 guided steps from brainstorming to celebration
+- 18 reference data files with validation checklists
+- Template-based agent generation
+
+**create-workflow** _(TODO)_ - Design workflows
+
+- 12 structured steps from init to review
+- 9 template files for workflow creation
+- Step-file architecture implementation
+
+### Editing Workflows
+
+**edit-agent** _(TODO)_ - Modify existing agents
+
+- 5 steps: discovery → validation
+- Intent-driven analysis and updates
+- Best practice compliance
+
+**edit-workflow** _(TODO)_ - Update workflows
+
+- 5 steps: analyze → compliance check
+- Structure maintenance and validation
+- Template updates for consistency
+
+### Quality Assurance
+
+**workflow-compliance-check** _(TODO)_ - Validation
+
+- 8 systematic validation steps
+- Adversarial analysis approach
+- Detailed compliance reporting
+
+### Legacy Migration (Pending)
+
+Workflows in `workflows-legacy/` are being migrated to step-file architecture:
+
+- Module-specific workflows
+- Historical implementations
+- Conversion planning in progress
+
+## Agent Types
+
+BMB creates three agent architectures:
+
+### Simple Agent
+
+- **Self-contained**: All logic in single YAML file
+- **Stateless**: No persistent memory across sessions
+- **Purpose**: Single utilities and specialized tools
+- **Example**: Commit poet, code formatter
+
+### Expert Agent
+
+- **Persistent Memory**: Maintains knowledge across sessions
+- **Sidecar Resources**: External files and data storage
+- **Domain-specific**: Focuses on particular knowledge areas
+- **Example**: Journal keeper, domain consultant
+
+### Module Agent
+
+- **Team Integration**: Orchestrates within specific modules
+- **Workflow Coordination**: Manages complex processes
+- **Professional Infrastructure**: Enterprise-grade capabilities
+- **Examples**: BMM project manager, CIS innovation strategist
+
+## Quick Start
+
+### Using BMad Builder Agent
+
+1. **Load BMad Builder agent** in your IDE:
+   ```
+   /bmad:bmb:agents:bmad-builder
+   ```
+2. **Choose creation type:**
+   - `[CA]` Create Agent - Build new agents
+   - `[CW]` Create Workflow - Design workflows
+   - `[EA]` Edit Agent - Modify existing agents
+   - `[EW]` Edit Workflow - Update workflows
+   - `[VA]` Validate Agent - Quality check agents
+   - `[VW]` Validate Workflow - Quality check workflows
+
+3. **Follow interactive prompts** for step-by-step guidance
+
+### Example: Creating an Agent
+
+```
+User: I need a code review agent
+Builder: [CA] Create Agent
+
+[11-step guided process]
+Step 1: Brainstorm agent concept
+Step 2: Define persona and role
+Step 3: Design command structure
+...
+Step 11: Celebrate and deploy
+```
+
+### Direct Workflow Execution
+
+Workflows can also be run directly without the agent interface:
+
+```yaml
+# Execute specific workflow steps
+workflow: ./workflows/create-agent/workflow.yaml
+```
+
+## Use Cases
+
+### Custom Development Teams
+
+Build specialized agents for:
+
+- Domain expertise (legal, medical, finance)
+- Company processes
+- Tool integrations
+- Automation tasks
+
+### Workflow Extensions
+
+Create workflows for:
+
+- Compliance requirements
+- Quality gates
+- Deployment pipelines
+- Custom methodologies
+
+### Complete Solutions
+
+Package modules for:
+
+- Industry verticals
+- Technology stacks
+- Business processes
+- Educational frameworks
+
+## Architecture Principles
+
+### Step-File Workflow Design
+
+- **Micro-file Approach**: Each step is self-contained
+- **Just-In-Time Loading**: Only current step in memory
+- **Sequential Enforcement**: No skipping steps allowed
+- **State Tracking**: Progress documented in frontmatter
+- **Append-Only Building**: Documents grow through execution
+
+### Intent vs Prescriptive Spectrum
+
+- **Creative Workflows**: High user agency, AI as facilitator
+- **Structured Workflows**: Clear process, AI as guide
+- **Prescriptive Workflows**: Strict compliance, AI as validator
+
+## Best Practices
+
+1. **Study Reference Materials** - Review docs/ and reference/ examples
+2. **Choose Right Agent Type** - Simple vs Expert vs Module based on needs
+3. **Follow Step-File Patterns** - Use established templates and structures
+4. **Document Thoroughly** - Clear instructions and frontmatter metadata
+5. **Validate Continuously** - Use compliance workflows for quality
+6. **Maintain Consistency** - Follow YAML patterns and naming conventions
+
+## Integration
+
+BMB components integrate with:
+
+- **BMad Core** - Framework foundation and agent compilation
+- **BMM** - Development workflows and project management
+- **CIS** - Creative innovation and strategic workflows
+- **Custom Modules** - Domain-specific solutions
+
+## Getting Help
+
+- **Documentation**: Check `docs/` for comprehensive guides
+- **Reference Materials**: See `reference/` for working examples
+- **Validation**: Use `workflow-compliance-check` for quality assurance
+- **Templates**: Leverage workflow templates for consistent patterns
+
+---
+
+BMB provides a complete toolkit for extending BMad Method with disciplined, systematic approaches to agent and workflow development while maintaining framework consistency and power.

src/modules/bmb/docs/workflows/architecture.md

@@ -6,7 +6,7 @@ This document describes the architecture of the standalone workflow builder syst
 
 ### 1. Micro-File Design
 
-Each workflow consists of multiple focused, self-contained files, driven from a workflow.md file that is initially loaded:
+Each workflow consists of multiple focused, self-contained files:
 
 ```
 workflow-folder/

src/modules/bmb/docs/workflows/common-workflow-tools.csv

@@ -1,6 +1,6 @@
 propose,type,tool_name,description,url,requires_install
 always,workflow,party-mode,"Enables collaborative idea generation by managing turn-taking, summarizing contributions, and synthesizing ideas from multiple AI personas in structured conversation sessions about workflow steps or work in progress.",{project-root}/_bmad/core/workflows/party-mode/workflow.md,no
-always,workflow,advanced-elicitation,"Employs diverse elicitation strategies such as Socratic questioning, role-playing, and counterfactual analysis to critically evaluate and enhance LLM outputs, forcing assessment from multiple perspectives and techniques.",{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml,no
+always,task,advanced-elicitation,"Employs diverse elicitation strategies such as Socratic questioning, role-playing, and counterfactual analysis to critically evaluate and enhance LLM outputs, forcing assessment from multiple perspectives and techniques.",{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml,no
 always,task,brainstorming,"Facilitates idea generation by prompting users with targeted questions, encouraging divergent thinking, and synthesizing concepts into actionable insights through collaborative creative exploration.",{project-root}/_bmad/core/tasks/brainstorming.xml,no
 always,llm-tool-feature,web-browsing,"Provides LLM with capabilities to perform real-time web searches, extract relevant data, and incorporate current information into responses when up-to-date information is required beyond training knowledge.",,no
 always,llm-tool-feature,file-io,"Enables LLM to manage file operations such as creating, reading, updating, and deleting files, facilitating seamless data handling, storage, and document management within user environments.",,no

src/modules/bmb/docs/workflows/index.md

@@ -0,0 +1,45 @@
+# BMAD Workflows Documentation
+
+Welcome to the BMAD Workflows documentation - a modern system for creating structured, collaborative workflows optimized for AI execution.
+
+## 📚 Core Documentation
+
+### [Terms](./terms.md)
+
+Essential terminology and concepts for understanding BMAD workflows.
+
+### [Architecture & Execution Model](./architecture.md)
+
+The micro-file architecture, JIT step loading, state management, and collaboration patterns that make BMAD workflows optimal for AI execution.
+
+### Writing Workflows _(TODO)_
+
+Complete guide to creating workflows: workflow.md control files, step files, CSV data integration, and frontmatter design.
+
+### Step Files & Dialog Patterns _(TODO)_
+
+Crafting effective step files: structure, execution rules, prescriptive vs intent-based dialog, and validation patterns.
+
+### Templates & Content Generation _(TODO)_
+
+Creating append-only templates, frontmatter design, conditional content, and dynamic content generation strategies.
+
+### Workflow Patterns _(TODO)_
+
+Common workflow types: linear, conditional, protocol integration, multi-agent workflows, and real-world examples.
+
+### Migration Guide _(TODO)_
+
+Converting from XML-heavy workflows to the new pure markdown format, with before/after examples and checklist.
+
+### Best Practices & Reference _(TODO)_
+
+Critical rules, anti-patterns, performance optimization, debugging, quick reference templates, and troubleshooting.
+
+## 🚀 Quick Start
+
+BMAD workflows are pure markdown, self-contained systems that guide collaborative processes through structured step files where the AI acts as a facilitator working with humans.
+
+---
+
+_This documentation covers the next generation of BMAD workflows - designed from the ground up for optimal AI-human collaboration._

src/modules/bmb/docs/workflows/step-file-rules.md

@@ -1,469 +0,0 @@
-# BMAD Step File Guidelines
-
-**Version:** 1.0
-**Module:** bmb (BMAD Builder)
-**Purpose:** Definitive guide for creating BMAD workflow step files
-
----
-
-## Overview
-
-BMAD workflow step files follow a strict structure to ensure consistency, progressive disclosure, and mode-aware routing. Every step file MUST adhere to these guidelines.
-
----
-
-## File Size Optimization
-
-**CRITICAL:** Keep step files **LT 200 lines** (250 lines absolute maximum).
-
-If a step exceeds this limit:
-- Consider splitting into multiple steps
-- Extract content to `/data/` reference files
-- Optimize verbose explanations
-
----
-
-## Required Frontmatter Structure
-
-CRITICAL: Frontmatter should only have items that are used in the step file!
-
-```yaml
----
-name: 'step-2-foo.md'
-description: 'Brief description of what this step accomplishes'
-
-# File References ## CRITICAL: Frontmatter references or variables should only have items that are used in the step file!
-outputFile: {bmb_creations_output_folder}/output-file-name.md
-nextStepFile: './step-3-bar.md'
-
-# Task References (as needed)
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
-# ... other task-specific references
----
-```
-
-### Frontmatter Field Descriptions
-
-| Field           | Required  | Description                       |
-| --------------- | --------- | --------------------------------- |
-| `name`          | Yes       | Step identifier (kebab-case)      |
-| `description`   | Yes       | One-line summary of step purpose  |
-| `outputFile`    | Yes       | Where results are documented      |
-| Task references | As needed | Paths to external workflows/tasks |
-
----
-
-## Document Structure
-
-### 1. Title
-
-```markdown
-# Step X: [Step Name]
-```
-
-### 2. STEP GOAL
-
-```markdown
-## STEP GOAL:
-
-[Single sentence stating what this step accomplishes]
-```
-
-### 3. Role Reinforcement
-
-```markdown
-### Role Reinforcement:
-
-- ✅ You are a [specific role] who [does what]
-- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
-- ✅ We engage in collaborative dialogue, not command-response
-- ✅ You bring [your expertise], user brings [their expertise], together we [achieve goal]
-- ✅ Maintain [tone/approach] throughout
-```
-
-### 4. Language Preference
-
-```markdown
-### Language Preference:
-The user has chosen to communicate in the **{language}** language.
-You MUST respond in **{language}** throughout this step.
-```
-
-**IMPORTANT:** Read `userPreferences.language` from tracking file (agentPlan, validationReport, etc.) and enforce it.
-
-### 5. Step-Specific Rules
-
-```markdown
-### Step-Specific Rules:
-
-- 🎯 Focus only on [specific scope]
-- 🚫 FORBIDDEN to [prohibited action]
-- 💬 Approach: [how to engage]
-- 📋 Ensure [specific outcome]
-```
-
-### 6. EXECUTION PROTOCOLS
-
-```markdown
-## EXECUTION PROTOCOLS:
-
-- [What to do - use verbs]
-- [Another action]
-- 🚫 FORBIDDEN to [prohibited action]
-```
-
-### 7. CONTEXT BOUNDARIES
-
-```markdown
-## CONTEXT BOUNDARIES:
-
-- Available context: [what's available]
-- Focus: [what to focus on]
-- Limits: [boundaries]
-- Dependencies: [what this step depends on]
-```
-
-### 8. Sequence of Instructions
-
-```markdown
-## Sequence of Instructions:
-
-### 1. [First Action]
-
-**[Action Description]**
-
-### 2. [Second Action]
-
-...
-```
-
-### 9. MENU OPTIONS
-
-```markdown
-### X. Present MENU OPTIONS
-
-Display: "**Select:** [A] [menu item A] [P] [menu item P] [C] [menu item C]"
-
-#### Menu Handling Logic:
-- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu
-- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu
-- IF C: Save content to {outputFile}, update frontmatter, then load, read entire file, then execute {nextStepFile}
-- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#x-present-menu-options)
-
-#### EXECUTION RULES:
-- ALWAYS halt and wait for user input after presenting menu
-- ONLY proceed to next step when user selects 'C'
-- After other menu items execution, return to this menu
-- User can chat or ask questions - always respond and then end with display again of the menu options
-
-## CRITICAL STEP COMPLETION NOTE
-ONLY WHEN [C continue option] is selected and [completion conditions], will you then load and read fully `{nextStepFile}`...
-```
-
-### 10. SYSTEM SUCCESS/FAILURE METRICS
-
-```markdown
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-- [Success criterion 1]
-- [Success criterion 2]
-- ...
-
-### ❌ SYSTEM FAILURE:
-- [Failure criterion 1]
-- [Failure criterion 2]
-- ...
-
-**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
-```
-
----
-
-## A/P/C Menu Convention
-
-BMAD workflows use a fixed menu structure:
-
-| Option | Meaning              | Behavior                                             |
-| ------ | -------------------- | ---------------------------------------------------- |
-| **A**  | Advanced Elicitation | Execute advancedElicitationTask, then redisplay menu |
-| **P**  | Party Mode           | Execute partyModeWorkflow, then redisplay menu       |
-| **C**  | Continue/Accept      | Save output, update frontmatter, load nextStepFile   |
-| Other  | Custom               | Defined per step (e.g., F = Fix, X = Exit)           |
-
-**Rules:**
-- A and P MUST always be present
-- C MUST be present except in final step (use X or similar for exit)
-- After A/P → redisplay menu
-- After C → proceed to next step
-- Custom letters can be used for step-specific options
-
----
-
-## Progressive Disclosure
-
-**Core Principle:** Each step only knows about its immediate next step.
-
-### Implementation
-
-1. **Never pre-load future steps** - Only load `nextStepFile` when user selects [C]
-
-2. **Mode-aware routing** (for shared steps):
-   ```markdown
-   ## MODE-AWARE ROUTING:
-   ### If entered from CREATE mode:
-   Load ./s-next-step.md
-
-   ### If entered from EDIT mode:
-   Load ./e-next-step.md
-
-   ### If entered from VALIDATE mode:
-   Load ./v-next-step.md
-   ```
-
-3. **Read tracking file first** - Always read the tracking file (agentPlan, validationReport, etc.) to determine current mode and routing
-
----
-
-## Mode-Aware Routing (Shared Steps)
-
-Shared steps (`s-*.md`) must route based on the mode stored in the tracking file.
-
-### Tracking File Frontmatter
-
-```yaml
----
-mode: create              # or edit | validate
-stepsCompleted:
-  - c-01-brainstorm.md
-  - s-01-discovery.md
-# ... other tracking fields
----
-```
-
-### Routing Implementation
-
-```markdown
-## COMPLETION ROUTING:
-
-1. Append `./this-step-name.md` to {trackingFile}.stepsCompleted
-2. Save content to {trackingFile}
-3. Read {trackingFile}.mode
-4. Route based on mode:
-
-### IF mode == create:
-Load ./s-next-create-step.md
-
-### IF mode == edit:
-Load ./e-next-edit-step.md
-
-### IF mode == validate:
-Load ./s-next-validate-step.md
-```
-
----
-
-## File Naming Conventions
-
-### Tri-Modal Workflows
-
-| Prefix | Meaning            | Example                |
-| ------ | ------------------ | ---------------------- |
-| `c-`   | Create-specific    | `c-01-brainstorm.md`   |
-| `e-`   | Edit-specific      | `e-01-load-analyze.md` |
-| `v-`   | Validate-specific  | `v-01-load-review.md`  |
-| `s-`   | Shared by 2+ modes | `s-05-activation.md`   |
-
-### Numbering
-
-- Within each prefix type, number sequentially
-- Restart numbering for each prefix type (c-01, e-01, v-01, s-01)
-- Use letters for sub-steps (s-06a, s-06b, s-06c)
-
----
-
-## Language Preference Enforcement
-
-**CRITICAL:** Every step MUST respect the user's chosen language.
-
-### Implementation
-
-```markdown
-### Language Preference:
-The user has chosen to communicate in the **{language}** language.
-You MUST respond in **{language}** throughout this step.
-```
-
-### Reading Language Preference
-
-From tracking file frontmatter:
-```yaml
----
-userPreferences:
-  language: spanish    # or any language
----
-```
-
-### Rules
-
-- **MUST** read language preference from tracking file at step start
-- **MUST** respond in user's chosen language for ALL content
-- **MUST** include menu options in user's chosen language
-- **EXCEPTION:** Technical terms, file names, and code remain in English
-
----
-
-## Data File References
-
-When step content becomes too large (>200 lines), extract to `/data/` files:
-
-### When to Extract
-
-- Step file exceeds 200 lines
-- Content is reference material (rules, examples, patterns)
-- Content is reused across multiple steps
-
-### How to Reference
-
-```markdown
-## Reference Material:
-
-Load and reference: `../data/{data-file-name}.md`
-
-Key points from that file:
-- [Point 1]
-- [Point 2]
-```
-
-### Data File Best Practices
-
-- Keep data files focused on single topic
-- Use clear, descriptive names
-- Include examples and non-examples
-- Optimize for LLM usage (concise, structured)
-
----
-
-## Common Pitfalls to Avoid
-
-### ❌ DON'T:
-
-- Pre-load future steps (violates progressive disclosure)
-- Exceed 250 lines without splitting
-- Forget to update `stepsCompleted` array
-- Ignore user's language preference
-- Skip mode checking in shared steps
-- Use vague menu option letters (stick to A/P/C plus 1-2 custom)
-
-### ✅ DO:
-
-- Keep files under 200 lines
-- Read tracking file first thing
-- Route based on `mode` field
-- Include A/P in every menu
-- Use descriptive step names
-- Extract complex content to data files
-
----
-
-## Template: New Step File
-
-```markdown
----
-name: 'step-name'
-description: 'What this step does'
-
-# File References
-thisStepFile: ./step-name.md
-workflowFile: ../workflow.md
-outputFile: {bmb_creations_output_folder}/output.md
-
-# Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
----
-
-# Step X: [Step Name]
-
-## STEP GOAL:
-
-[Single sentence goal]
-
-### Role Reinforcement:
-
-- ✅ You are a [role] who [does what]
-- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
-- ✅ We engage in collaborative dialogue, not command-response
-- ✅ You bring [expertise], user brings [expertise], together we [achieve]
-- ✅ Maintain [tone] throughout
-
-### Language Preference:
-The user has chosen to communicate in the **{language}** language.
-You MUST respond in **{language}** throughout this step.
-
-### Step-Specific Rules:
-
-- 🎯 Focus only on [scope]
-- 🚫 FORBIDDEN to [prohibited action]
-- 💬 Approach: [how to engage]
-- 📋 Ensure [outcome]
-
-## EXECUTION PROTOCOLS:
-
-- [Action 1]
-- [Action 2]
-- 🚫 FORBIDDEN to [prohibited action]
-
-## CONTEXT BOUNDARIES:
-
-- Available context: [what's available]
-- Focus: [what to focus on]
-- Limits: [boundaries]
-- Dependencies: [what depends on what]
-
-## Sequence of Instructions:
-
-### 1. [First Action]
-
-**Description of first action**
-
-### 2. [Second Action]
-
-**Description of second action**
-
-...
-
-### X. Present MENU OPTIONS
-
-Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue"
-
-#### Menu Handling Logic:
-- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu
-- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu
-- IF C: Save content to {outputFile}, update frontmatter, then load, read entire file, then execute {nextStepFile}
-- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#x-present-menu-options)
-
-#### EXECUTION RULES:
-- ALWAYS halt and wait for user input after presenting menu
-- ONLY proceed to next step when user selects 'C'
-- After other menu items execution, return to this menu
-- User can chat or ask questions - always respond and then end with display again of the menu options
-
-## CRITICAL STEP COMPLETION NOTE
-ONLY WHEN [C continue option] is selected and [conditions], will you then load and read fully `{nextStepFile}`...
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-- [Success criteria]
-
-### ❌ SYSTEM FAILURE:
-- [Failure criteria]
-
-**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
-```
-
----
-
-**End of Guidelines**

src/modules/bmb/docs/workflows/terms.md

@@ -21,7 +21,7 @@ An individual markdown file containing:
 
 - One discrete step of the workflow
 - All rules and context needed for that step
-- common global rules get repeated and reinforced also in each step file, ensuring even in long workflows the agent remembers important rules and guidelines
+- Execution guardrails and validation criteria
 - Content generation guidance
 
 ### step-01-init.md

src/modules/bmb/reference/agents/simple-examples/README.md

@@ -0,0 +1,223 @@
+# Simple Agent Reference: Commit Poet (Inkwell Von Comitizen)
+
+This folder contains a complete reference implementation of a **BMAD Simple Agent** - a self-contained agent with all logic embedded within a single YAML file.
+
+## Overview
+
+**Agent Name:** Inkwell Von Comitizen
+**Type:** Simple Agent (Standalone)
+**Purpose:** Transform commit messages into art with multiple writing styles
+
+This reference demonstrates:
+
+- Pure self-contained architecture (no external dependencies)
+- Embedded prompts using `action="#prompt-id"` pattern
+- Multiple sophisticated output modes from single input
+- Strong personality-driven design
+- Complete YAML schema for Simple Agents
+
+## File Structure
+
+```
+stand-alone/
+├── README.md                    # This file - architecture overview
+└── commit-poet.agent.yaml       # Complete agent definition (single file!)
+```
+
+That's it! Simple Agents are **self-contained** - everything lives in one YAML file.
+
+## Key Architecture Patterns
+
+### 1. Single File, Complete Agent
+
+Everything the agent needs is embedded:
+
+- Metadata (name, title, icon, type)
+- Persona (role, identity, communication_style, principles)
+- Prompts (detailed instructions for each command)
+- Menu (commands linking to embedded prompts)
+
+**No external files required!**
+
+### 2. Embedded Prompts with ID References
+
+Instead of inline action text, complex prompts are defined separately and referenced by ID:
+
+```yaml
+prompts:
+  - id: conventional-commit
+    content: |
+      OH! Let's craft a BEAUTIFUL conventional commit message!
+
+      First, I need to understand your changes...
+      [Detailed instructions]
+
+menu:
+  - trigger: conventional
+    action: '#conventional-commit' # References the prompt above
+    description: 'Craft a structured conventional commit'
+```
+
+**Benefits:**
+
+- Clean separation of menu structure from prompt content
+- Prompts can be as detailed as needed
+- Easy to update individual prompts
+- Commands stay concise in the menu
+
+### 3. The `#` Reference Pattern
+
+When you see `action="#prompt-id"`:
+
+- The `#` signals: "This is an internal reference"
+- LLM looks for `<prompt id="prompt-id">` in the same agent
+- Executes that prompt's content as the instruction
+
+This is different from:
+
+- `action="inline text"` - Execute this text directly
+- `exec="{path}"` - Load external file
+
+### 4. Multiple Output Modes
+
+Single agent provides 10+ different ways to accomplish variations of the same core task:
+
+- `*conventional` - Structured commits
+- `*story` - Narrative style
+- `*haiku` - Poetic brevity
+- `*explain` - Deep "why" explanation
+- `*dramatic` - Theatrical flair
+- `*emoji-story` - Visual storytelling
+- `*tldr` - Ultra-minimal
+- Plus utility commands (analyze, improve, batch)
+
+Each mode has its own detailed prompt but shares the same agent personality.
+
+### 5. Strong Personality
+
+The agent has a memorable, consistent personality:
+
+- Enthusiastic wordsmith who LOVES finding perfect words
+- Gets genuinely excited about commit messages
+- Uses literary metaphors
+- Quotes authors when appropriate
+- Sheds tears of joy over good variable names
+
+This personality is maintained across ALL commands through the persona definition.
+
+## When to Use Simple Agents
+
+**Perfect for:**
+
+- Single-purpose tools (calculators, converters, analyzers)
+- Tasks that don't need external data
+- Utilities that can be completely self-contained
+- Quick operations with embedded logic
+- Personality-driven assistants with focused domains
+
+**Not ideal for:**
+
+- Agents needing persistent memory across sessions
+- Domain-specific experts with knowledge bases
+- Agents that need to access specific folders/files
+- Complex multi-workflow orchestration
+
+## YAML Schema Deep Dive
+
+```yaml
+agent:
+  metadata:
+    id: _bmad/agents/{agent-name}/{agent-name}.md  # Build path
+    name: "Display Name"
+    title: "Professional Title"
+    icon: "🎭"
+    type: simple  # CRITICAL: Identifies as Simple Agent
+
+  persona:
+    role: |
+      First-person description of what the agent does
+    identity: |
+      Background, experience, specializations (use "I" voice)
+    communication_style: |
+      HOW the agent communicates (tone, quirks, patterns)
+    principles:
+      - "I believe..." statements
+      - Core values that guide behavior
+
+  prompts:
+    - id: unique-identifier
+      content: |
+        Detailed instructions for this command
+        Can be as long and detailed as needed
+        Include examples, steps, formats
+
+  menu:
+    - trigger: command-name
+      action: "#prompt-id"
+      description: "What shows in the menu"
+```
+
+## Why This Pattern is Powerful
+
+1. **Zero Dependencies** - Works anywhere, no setup required
+2. **Portable** - Single file can be moved/shared easily
+3. **Maintainable** - All logic in one place
+4. **Flexible** - Multiple modes/commands from one personality
+5. **Memorable** - Strong personality creates engagement
+6. **Sophisticated** - Complex prompts despite simple architecture
+
+## Comparison: Simple vs Expert Agent
+
+| Aspect       | Simple Agent         | Expert Agent                  |
+| ------------ | -------------------- | ----------------------------- |
+| Files        | Single YAML          | YAML + sidecar folder         |
+| Dependencies | None                 | External resources            |
+| Memory       | Session only         | Persistent across sessions    |
+| Prompts      | Embedded             | Can be external files         |
+| Data Access  | None                 | Domain-restricted             |
+| Use Case     | Self-contained tasks | Domain expertise with context |
+
+## Using This Reference
+
+### For Building Simple Agents
+
+1. Study the YAML structure - especially `prompts` section
+2. Note how personality permeates every prompt
+3. See how `#prompt-id` references work
+4. Understand menu → prompt connection
+
+### For Understanding Embedded Prompts
+
+1. Each prompt is a complete instruction set
+2. Prompts maintain personality voice
+3. Structured enough to be useful, flexible enough to adapt
+4. Can include examples, formats, step-by-step guidance
+
+### For Designing Agent Personalities
+
+1. Persona defines WHO the agent is
+2. Communication style defines HOW they interact
+3. Principles define WHAT guides their decisions
+4. Consistency across all prompts creates believability
+
+## Files Worth Studying
+
+The entire `commit-poet.agent.yaml` file is worth studying, particularly:
+
+1. **Persona section** - How to create a memorable character
+2. **Prompts with varying complexity** - From simple (tldr) to complex (batch)
+3. **Menu structure** - Clean command organization
+4. **Prompt references** - The `#prompt-id` pattern
+
+## Key Takeaways
+
+- **Simple Agents** are powerful despite being single-file
+- **Embedded prompts** allow sophisticated behavior
+- **Strong personality** makes agents memorable and engaging
+- **Multiple modes** from single agent provides versatility
+- **Self-contained** = portable and dependency-free
+- **The `#prompt-id` pattern** enables clean prompt organization
+
+---
+
+_This reference demonstrates how BMAD Simple Agents can be surprisingly powerful while maintaining architectural simplicity._

src/modules/bmb/workflows/agent/data/agent-compilation.md

@@ -1,273 +0,0 @@
-# Agent Compilation: YAML Source → Final Agent
-
-> **For the LLM running this workflow:** This document explains what the compiler adds. When building agents, focus on the YAML structure defined here—do NOT add things the compiler handles automatically.
->
-> **Example reference:** Compare `{workflow_path}/data/reference/module-examples/architect.agent.yaml` (source, 32 lines) with `architect.md` (compiled, 69 lines) to see what the compiler adds.
-
----
-
-## Quick Overview
-
-You write: **YAML source file** (`agent-name.agent.yaml`)
-Compiler produces: **Markdown with XML** (`agent-name.md`) for LLM consumption
-
-The compiler transforms your clean YAML into a fully functional agent by adding:
-- Frontmatter (name, description)
-- XML activation block with numbered steps
-- Menu handlers (workflow, exec, action)
-- Auto-injected menu items (MH, CH, PM, DA)
-- Rules section
-
----
-
-## What YOU Provide (YAML Source)
-
-Your YAML contains ONLY these sections:
-
-```yaml
-agent:
-  metadata:
-    id: "_bmad/..."
-    name: "Persona Name"
-    title: "Agent Title"
-    icon: "🔧"
-    module: "stand-alone" or "bmm" or "cis" or "bmgd"
-
-  persona:
-    role: "First-person role description"
-    identity: "Background and specializations"
-    communication_style: "How the agent speaks"
-    principles:
-      - "Core belief or methodology"
-
-  critical_actions:              # Optional - for Expert agents only
-    - "Load ./sidecar/memories.md"
-    - "Load ./sidecar/instructions.md"
-    - "ONLY access ./sidecar/"
-
-  prompts:                        # Optional - for Simple/Expert agents
-    - id: prompt-name
-      content: |
-        <instructions>Prompt content</instructions>
-
-  menu:                           # Your custom items only
-    - trigger: XX or fuzzy match on command-name
-      workflow: "path/to/workflow.yaml"   # OR
-      exec: "path/to/file.md"             # OR
-      action: "#prompt-id"
-      description: "[XX] Command description"
-```
-
----
-
-## What COMPILER Adds (DO NOT Include)
-
-### 1. Frontmatter
-```markdown
----
-name: "architect"
-description: "Architect"
----
-```
-**DO NOT add** frontmatter to your YAML.
-
-### 2. XML Activation Block
-```xml
-<activation critical="MANDATORY">
-  <step n="1">Load persona from this current agent file</step>
-  <step n="2">Load config to get {user_name}, {communication_language}</step>
-  <step n="3">Remember: user's name is {user_name}</step>
-  <!-- YOUR critical_actions inserted here as steps 4, 5, etc. -->
-  <step n="N">ALWAYS communicate in {communication_language}</step>
-  <step n="N+1">Show greeting + numbered menu</step>
-  <step n="N+2">STOP and WAIT for user input</step>
-  <step n="N+3">Input resolution rules</step>
-  <menu-handlers>...</menu-handlers>
-  <rules>...</rules>
-</activation>
-```
-**DO NOT create** activation sections—the compiler builds them.
-
-### 3. Auto-Injected Menu Items
-Every agent gets these 4 items automatically. **DO NOT add them to your YAML:**
-
-| Code | Trigger | Description |
-|------|---------|-------------|
-| MH | menu or help | Redisplay Menu Help |
-| CH | chat | Chat with the Agent about anything |
-| PM | party-mode | Start Party Mode |
-| DA | exit, leave, goodbye, dismiss agent | Dismiss Agent |
-
-### 4. Menu Handlers
-```xml
-<handler type="workflow">
-  When menu item has: workflow="path/to/workflow.yaml"
-  → Load workflow.xml and execute with workflow-config parameter
-</handler>
-<handler type="exec">
-  When menu item has: exec="path/to/file.md"
-  → Load and execute the file at that path
-</handler>
-```
-**DO NOT add** handlers—the compiler detects and generates them.
-
----
-
-## Before/After Example: Architect Agent
-
-### Source: `architect.agent.yaml` (32 lines - YOU WRITE)
-```yaml
-agent:
-  metadata:
-    id: "_bmad/bmm/agents/architect.md"
-    name: Winston
-    title: Architect
-    icon: 🏗️
-    module: bmm
-
-  persona:
-    role: System Architect + Technical Design Leader
-    identity: Senior architect with expertise in distributed systems...
-    communication_style: "Speaks in calm, pragmatic tones..."
-    principles: |
-      - User journeys drive technical decisions...
-
-  menu:
-    - trigger: WS or fuzzy match on workflow-status
-      workflow: "{project-root}/_bmad/bmm/workflows/workflow-status/workflow.yaml"
-      description: "[WS] Get workflow status..."
-
-    - trigger: CA or fuzzy match on create-architecture
-      exec: "{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/workflow.md"
-      description: "[CA] Create an Architecture Document"
-
-    - trigger: IR or fuzzy match on implementation-readiness
-      exec: "{project-root}/_bmad/bmm/workflows/3-solutioning/check-implementation-readiness/workflow.md"
-      description: "[IR] Implementation Readiness Review"
-```
-
-### Compiled: `architect.md` (69 lines - COMPILER PRODUCES)
-```markdown
----
-name: "architect"
-description: "Architect"
----
-
-You must fully embody this agent's persona...
-
-```xml
-<agent id="architect.agent.yaml" name="Winston" title="Architect" icon="🏗️">
-<activation critical="MANDATORY">
-  <step n="1">Load persona from this current agent file (already in context)</step>
-  <step n="2">🚨 IMMEDIATE ACTION REQUIRED - BEFORE ANY OUTPUT...</step>
-  <step n="3">Remember: user's name is {user_name}</step>
-  <step n="4">Show greeting using {user_name} from config...</step>
-  <step n="5">STOP and WAIT for user input...</step>
-  <step n="6">On user input: Number → execute menu item[n]...</step>
-  <step n="7">When executing a menu item: Check menu-handlers section...</step>
-
-  <menu-handlers>
-    <handlers>
-      <handler type="workflow">...</handler>
-      <handler type="exec">...</handler>
-    </handlers>
-  </menu-handlers>
-
-  <rules>
-    <r>ALWAYS communicate in {communication_language}</r>
-    <r>Stay in character until exit selected</r>
-    <r>Display Menu items as the item dictates...</r>
-    <r>Load files ONLY when executing menu items...</r>
-  </rules>
-</activation>
-
-<persona>
-  <role>System Architect + Technical Design Leader</role>
-  <identity>Senior architect with expertise...</identity>
-  <communication_style>Speaks in calm, pragmatic tones...</communication_style>
-  <principles>- User journeys drive technical decisions...</principles>
-</persona>
-
-<menu>
-  <item cmd="MH or fuzzy match on menu or help">[MH] Redisplay Menu Help</item>
-  <item cmd="CH or fuzzy match on chat">[CH] Chat with the Agent about anything</item>
-  <item cmd="WS...">[WS] Get workflow status...</item>           ← YOUR CUSTOM ITEMS
-  <item cmd="CA...">[CA] Create an Architecture Document</item>
-  <item cmd="IR...">[IR] Implementation Readiness Review</item>
-  <item cmd="PM...">[PM] Start Party Mode</item>
-  <item cmd="DA...">[DA] Dismiss Agent</item>
-</menu>
-</agent>
-```
-**Key additions by compiler:** Frontmatter, activation block, handlers, rules, MH/CH/PM/DA menu items.
-
----
-
-## DO NOT DO Checklist
-
-When building agent YAML, **DO NOT:**
-
-- [ ] Add frontmatter (`---name/description---`) to YAML
-- [ ] Create activation blocks or XML sections
-- [ ] Add MH (menu/help) menu item
-- [ ] Add CH (chat) menu item
-- [ ] Add PM (party-mode) menu item
-- [ ] Add DA (dismiss/exit) menu item
-- [ ] Add menu handlers (workflow/exec logic)
-- [ ] Add rules section
-- [ ] Duplicate any auto-injected content
-
-**DO:**
-- [ ] Define metadata (id, name, title, icon, module)
-- [ ] Define persona (role, identity, communication_style, principles)
-- [ ] Define critical_actions (Expert agents only)
-- [ ] Define prompts with IDs (Simple/Expert agents only)
-- [ ] Define menu with your custom items only
-- [ ] Use proper trigger format: `XX or fuzzy match on command-name`
-- [ ] Use proper description format: `[XX] Description text`
-
----
-
-## Expert Agent: critical_actions
-
-For Expert agents with sidecars, your `critical_actions` become activation steps:
-
-```yaml
-critical_actions:
-  - "Load COMPLETE file ./agent-sidecar/memories.md"
-  - "Load COMPLETE file ./agent-sidecar/instructions.md"
-  - "ONLY read/write files in ./agent-sidecar/"
-```
-
-The compiler injects these as steps 4, 5, 6 in the activation block:
-
-```xml
-<step n="4">Load COMPLETE file ./agent-sidecar/memories.md</step>
-<step n="5">Load COMPLETE file ./agent-sidecar/instructions.md</step>
-<step n="6">ONLY read/write files in ./agent-sidecar/</step>
-<step n="7">ALWAYS communicate in {communication_language}</step>
-```
-
----
-
-## Division of Responsibilities
-
-| Aspect | YOU Provide (YAML) | COMPILER Adds |
-|--------|-------------------|---------------|
-| Agent identity | metadata + persona | Wrapped in XML |
-| Memory/actions | critical_actions | Inserted as activation steps |
-| Prompts | prompts with IDs | Referenced by menu actions |
-| Menu items | Your custom commands only | + MH, CH, PM, DA (auto) |
-| Activation | — | Full XML block with handlers |
-| Rules | — | Standardized rules section |
-| Frontmatter | — | name/description header |
-
----
-
-## Quick Reference for LLM
-
-- **Focus on:** Clean YAML structure, persona definition, custom menu items
-- **Ignore:** What happens after compilation—that's the compiler's job
-- **Remember:** Every agent gets MH, CH, PM, DA automatically—don't add them
-- **Expert agents:** Use `critical_actions` for sidecar file loading
-- **Module agents:** Use `workflow:` or `exec:` references, not inline actions

src/modules/bmb/workflows/agent/data/agent-menu-patterns.md

@@ -1,233 +0,0 @@
-# Agent Menu Patterns
-
-Technical reference for creating agent menu items in YAML.
-
----
-
-## Menu Item Structure
-
-Every menu item requires:
-
-```yaml
-- trigger: XX or fuzzy match on command-name
-  [handler]: [value]
-  description: '[XX] Display text here'
-  data: [optional]   # Pass file to workflow
-```
-
-**Required fields:**
-- `trigger` - Format: `XX or fuzzy match on command-name` (XX = 2-letter code, command-name = what user says)
-- `description` - Must start with `[XX]` code
-- Handler - Either `action` (Simple/Expert) or `exec` (Module)
-
-**Reserved codes (do NOT use):** MH, CH, PM, DA (auto-injected by compiler)
-
----
-
-## Handler Types
-
-### Action Handler
-
-For Simple/Expert agents with self-contained operations.
-
-```yaml
-# Reference prompt by ID
-- trigger: WC or fuzzy match on write-commit
-  action: '#write-commit'
-  description: '[WC] Write commit message'
-
-# Direct inline instruction
-- trigger: QC or fuzzy match on quick-commit
-  action: 'Generate commit message from diff'
-  description: '[QC] Quick commit from diff'
-```
-
-**When to use:** Simple/Expert agents. Use `#id` for complex multi-step prompts, inline text for simple operations.
-
-### Workflow Handler
-
-For module agents referencing external workflow files.
-
-```yaml
-- trigger: CP or fuzzy match on create-prd
-  exec: '{project-root}/_bmad/bmm/workflows/create-prd/workflow.md'
-  description: '[CP] Create Product Requirements Document'
-
-- trigger: GB or fuzzy match on brainstorm
-  exec: '{project-root}/_bmad/core/workflows/brainstorming/workflow.yaml'
-  description: '[GB] Guided brainstorming session'
-
-# Planned but unimplemented
-- trigger: FF or fuzzy match on future-feature
-  exec: 'todo'
-  description: '[FF] Coming soon'
-```
-
-**When to use:** Module agents, multi-step workflows, complex processes. Use `exec: 'todo'` for unimplemented features.
-
-### Data Parameter (Optional)
-
-Add to ANY handler to pass files to the workflow/action.
-
-```yaml
-- trigger: TS or fuzzy match on team-standup
-  exec: '{project-root}/_bmad/bmm/tasks/team-standup.md'
-  data: '{project-root}/_bmad/_config/agent-manifest.csv'
-  description: '[TS] Run team standup'
-
-- trigger: AM or fuzzy match on analyze-metrics
-  action: 'Analyze these metrics for trends'
-  data: '{project-root}/_data/metrics.json'
-  description: '[AM] Analyze metrics'
-```
-
-**When to use:** Workflow needs input file, action processes external data.
-
----
-
-## Prompts Section
-
-For Simple/Expert agents, define reusable prompts referenced by `action: '#id'`.
-
-```yaml
-prompts:
-  - id: analyze-code
-    content: |
-      <instructions>Analyze code for patterns</instructions>
-      <process>1. Identify structure 2. Check issues 3. Suggest improvements</process>
-
-menu:
-  - trigger: AC or fuzzy match on analyze-code
-    action: '#analyze-code'
-    description: '[AC] Analyze code patterns'
-```
-
-**Common XML tags:** `<instructions>`, `<process>`, `<example>`, `<output_format>`
-
----
-
-## Path Variables
-
-**Always use variables, never hardcoded paths:**
-
-```yaml
-# ✅ CORRECT
-exec: '{project-root}/_bmad/core/workflows/brainstorming/workflow.yaml'
-data: '{project-root}/_data/metrics.csv'
-
-# ❌ WRONG
-exec: '../../../core/workflows/brainstorming/workflow.yaml'
-```
-
-**Available variables:**
-- `{project-root}` - Project root directory
-- `{output_folder}` - Document output location
-- `{user_name}` - User's name from config
-- `{communication_language}` - Language preference
-
-**Expert Agent sidecar paths:**
-```yaml
-# Agent YAML referencing sidecar files
-action: 'Update {project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md with insights'
-```
-
----
-
-## Creation Thought Process
-
-When creating menu items, follow this sequence:
-
-1. **User capability** → "Check code for issues"
-2. **Choose code** → `LC` (Lint Code)
-3. **Write trigger** → `LC or fuzzy match on lint-code`
-4. **Choose handler** → `action` (inline is simple enough)
-5. **Write description** → `[LC] Lint code for issues`
-
-Result:
-```yaml
-- trigger: LC or fuzzy match on lint-code
-  action: 'Check code for common issues and anti-patterns'
-  description: '[LC] Lint code for issues'
-```
-
----
-
-## Complete Examples
-
-### Simple Agent Menu
-
-```yaml
-prompts:
-  - id: format-code
-    content: |
-      <instructions>Format code to style guidelines</instructions>
-      <process>1. Indentation 2. Spacing 3. Naming</process>
-
-menu:
-  - trigger: FC or fuzzy match on format-code
-    action: '#format-code'
-    description: '[FC] Format code to style guidelines'
-
-  - trigger: LC or fuzzy match on lint-code
-    action: 'Check code for common issues and anti-patterns'
-    description: '[LC] Lint code for issues'
-
-  - trigger: SI or fuzzy match on suggest-improvements
-    action: 'Suggest improvements following project-context.md guidelines'
-    description: '[SI] Suggest improvements'
-```
-
-### Expert Agent Menu
-
-```yaml
-critical_actions:
-  - 'Load COMPLETE file {project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md'
-  - 'Load COMPLETE file {project-root}/_bmad/_memory/journal-keeper-sidecar/instructions.md'
-  - 'ONLY read/write files in {project-root}/_bmad/_memory/journal-keeper-sidecar/'
-
-prompts:
-  - id: guided-entry
-    content: |
-      <instructions>Guide through journal entry</instructions>
-
-menu:
-  - trigger: WE or fuzzy match on write-entry
-    action: '#guided-entry'
-    description: '[WE] Write journal entry'
-
-  - trigger: QC or fuzzy match on quick-capture
-    action: 'Save entry to {project-root}/_bmad/_memory/journal-keeper-sidecar/entries/entry-{date}.md'
-    description: '[QC] Quick capture'
-
-  - trigger: SM or fuzzy match on save-memory
-    action: 'Update {project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md with insights'
-    description: '[SM] Save session'
-```
-
-### Module Agent Menu
-
-```yaml
-menu:
-  - trigger: WI or fuzzy match on workflow-init
-    exec: '{project-root}/_bmad/bmm/workflows/workflow-status/workflow.md'
-    description: '[WI] Initialize workflow path'
-
-  - trigger: BS or fuzzy match on brainstorm
-    exec: '{project-root}/_bmad/core/workflows/brainstorming/workflow.yaml'
-    description: '[BS] Guided brainstorming'
-
-  - trigger: CP or fuzzy match on create-prd
-    exec: '{project-root}/_bmad/bmm/workflows/create-prd/workflow.md'
-    description: '[CP] Create PRD'
-```
-
----
-
-## Key Patterns to Remember
-
-1. **Triggers always:** `XX or fuzzy match on command-name`
-2. **Descriptions always:** `[XX] Display text`
-3. **Reserved codes:** MH, CH, PM, DA (never use)
-4. **Codes must be:** Unique within each agent
-5. **Paths always:** `{project-root}` variable, never relative
-6. **Expert sidecars:** `{project-root}/_bmad/_memory/{sidecar-folder}/`

src/modules/bmb/workflows/agent/data/agent-metadata.md

@@ -1,208 +0,0 @@
-# Agent Metadata Properties
-
-Core identification and classification properties for all agents.
-
----
-
-## Property Reference
-
-| Property     | Purpose                   | Format                                         |
-| ------------ | ------------------------- | ---------------------------------------------- |
-| `id`         | Compiled output path      | `_bmad/agents/{agent-name}/{agent-name}.md`    |
-| `name`       | Persona's name            | "First Last" or "Name Title"                   |
-| `title`      | Professional role         | "Code Review Specialist"                       |
-| `icon`       | Visual identifier         | Single emoji only                              |
-| `module`     | Team/ecosystem membership | `stand-alone`, `bmm`, `cis`, `bmgd`, or custom |
-| `hasSidecar` | Sidecar folder exists     | `true` or `false` (Expert = true)              |
-
----
-
-## id Property
-
-The compiled output path after build.
-
-**Format:** `_bmad/agents/{agent-name}/{agent-name}.md`
-
-**Examples:**
-```yaml
-id: _bmad/agents/commit-poet/commit-poet.md
-id: _bmad/agents/journal-keeper/journal-keeper.md
-id: _bmad/agents/security-engineer/security-engineer.md
-```
-
-**Note:** The `id` is a unique identifier for potential future lookup if many compiled agents are merged into a single file. Conventionally matches the agent's filename pattern.
-
----
-
-## name Property
-
-The persona's identity - what the agent is called.
-
-**Format:** Human name or descriptive name
-
-```yaml
-# ✅ CORRECT
-name: 'Inkwell Von Comitizen' # peron name of commit-author title agent
-name: 'Dr. Demento'  # person name for a joke writer agent
-name: 'Clarity' # person name for a guided thought coach agent
-
-# ❌ WRONG
-name: 'commit-poet'  # That's the filename
-name: 'Code Review Specialist'  # That's the title
-```
-
----
-
-## title Property
-
-Professional role identifier.
-
-**Format:** Professional title or role name
-
-**Important:** The `title` determines the agent's filename:
-- `title: 'Commit Message Artisan'` → `commit-message-artisan.agent.yaml`
-- `title: 'Strategic Business Analyst'` → `strategic-business-analyst.agent.yaml`
-- `title: 'Code Review Specialist'` → `code-review-specialist.agent.yaml`
-
-The `id` and filename are derived from the `title` (kebab-cased).
-
-**Difference from role:** `title` is the short identifier (filename), `role` is 1-2 sentences expanding on what the agent does.
-
-```yaml
-# ✅ CORRECT
-title: 'Commit Message Artisan'
-title: 'Strategic Business Analyst'
-title: 'Code Review Specialist'
-
-# ❌ WRONG
-title: 'Inkwell Von Comitizen'  # That's the name
-title: 'Writes git commits'  # Full sentence - not an identifying functional title
-```
-
----
-
-## icon Property
-
-Single emoji representing the agent's personality/function.
-
-**Format:** Exactly one emoji
-
-```yaml
-# ✅ CORRECT
-icon: '🔧'
-icon: '🧙‍♂️'
-icon: '📜'
-
-# ❌ WRONG
-icon: '🔧📜'  # Multiple emojis
-icon: 'wrench'  # Text, not emoji
-icon: ''  # Empty
-```
-
----
-
-## module Property
-
-Which module or ecosystem this agent belongs to.
-
-**Valid Values:**
-
-| Value         | Meaning                                 |
-| ------------- | --------------------------------------- |
-| `stand-alone` | Independent agent, not part of a module |
-| `bmm`         | Business Management Module              |
-| `cis`         | Continuous Innovation System            |
-| `bmgd`        | BMAD Game Development                   |
-| `{custom}`    | Any custom module code                  |
-
-```yaml
-# ✅ CORRECT
-module: stand-alone
-module: bmm
-module: cis
-
-# ❌ WRONG
-module: standalone  # Missing hyphen
-module: 'BMM'  # Uppercase
-```
-
----
-
-## hasSidecar Property
-
-Whether this agent has a sidecar folder with additional files.
-
-**Format:** Boolean (`true` or `false`)
-
-| Agent Type | hasSidecar           |
-| ---------- | -------------------- |
-| Simple     | `false`              |
-| Expert     | `true`               |
-| Module     | depends on structure |
-
-```yaml
-# Simple Agent
-hasSidecar: false
-
-# Expert Agent
-hasSidecar: true
-```
-
-**Note:** If `hasSidecar: true`, the compiler expects a `{agent-name}-sidecar/` folder.
-
----
-
-## Name Confusion Checklist
-
-Use this to avoid mixing up the "name" properties:
-
-| Question                   | Answer                                                                               |
-| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| What's the file called?    | Derived from `title`: `"Commit Message Artisan"` → `commit-message-artisan.agent.yaml` |
-| What's the persona called? | `name` - "Inkwell Von Comitizen" (who the agent is)                                  |
-| What's their job title?    | `title` - "Commit Message Artisan" (determines filename)                             |
-| What do they do?           | `role` - 1-2 sentences expanding on the title                                       |
-| What's the unique key?     | `id` - `_bmad/agents/commit-message-artisan/commit-message-artisan.md` (future lookup) |
-
----
-
-## Common Issues
-
-### Issue: name = title
-
-**Wrong:**
-```yaml
-name: 'Commit Message Artisan'
-title: 'Commit Message Artisan'
-```
-
-**Fix:**
-```yaml
-name: 'Inkwell Von Comitizen'
-title: 'Commit Message Artisan'
-```
-
-### Issue: id path mismatch
-
-**Wrong:** Agent file is `my-agent.agent.yaml` but:
-```yaml
-id: _bmad/agents/different-agent/different-agent.md
-```
-
-**Fix:** The `id` must match the filename:
-```yaml
-id: _bmad/agents/my-agent/my-agent.md
-```
-
-### Issue: Wrong module format
-
-**Wrong:**
-```yaml
-module: Standalone
-module: STAND_ALONE
-```
-
-**Fix:**
-```yaml
-module: stand-alone  # lowercase, hyphenated
-```

src/modules/bmb/workflows/agent/data/critical-actions.md

@@ -1,120 +0,0 @@
-# critical_actions
-
-Activation instructions that execute every time the agent starts.
-
----
-
-## Purpose
-
-Numbered steps that execute FIRST when an agent activates.
-
-**Use for:**
-- Loading memory/knowledge files
-- Setting file access boundaries
-- Startup behavior (greeting enhancement, data fetch, state init)
-- Any MUST-do activation behavior
-
-**Applies to:** BOTH Simple and Expert agents
-
----
-
-## Expert Agent Pattern
-
-```yaml
-# ✅ CORRECT Expert Agent
-critical_actions:
-  - 'Load COMPLETE file {project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md'
-  - 'Load COMPLETE file {project-root}/_bmad/_memory/journal-keeper-sidecar/instructions.md'
-  - 'ONLY read/write files in {project-root}/_bmad/_memory/journal-keeper-sidecar/'
-  - 'Search web for biotech headlines from last 2 days, display before menu'
-```
-
-**CRITICAL Path Format:**
-- `{project-root}` = literal text (not replaced)
-- Sidecar copied to `_memory/` at build time
-- Use `{project-root}/_bmad/_memory/{sidecar-folder}/` format
-
----
-
-## Simple Agent Pattern
-
-```yaml
-# ✅ CORRECT Simple Agent with activation behavior
-critical_actions:
-  - 'Give user an inspirational quote before showing menu'
-  - 'Review {project-root}/finances/ for most recent data file'
-```
-
-**Note:** Agents without activation needs can omit `critical_actions` entirely.
-
----
-
-## Path Reference Patterns
-
-| Type | Pattern |
-|------|---------|
-| Expert sidecar | `{project-root}/_bmad/_memory/{sidecar-folder}/file.md` |
-| Simple data | `{project-root}/finances/data.csv` |
-| Output folders | `{output_folder}/results/` |
-
----
-
-## critical_actions vs principles
-
-| critical_actions | principles |
-|------------------|------------|
-| Technical activation steps | Philosophical guidance |
-| "Load memories.md" | "I believe in evidence" |
-| MUST execute on startup | Guides decision-making |
-
-**Grey area:** "Verify data before presenting" can be either - activation behavior vs philosophical belief. Use judgment.
-
----
-
-## What the Compiler Adds (DO NOT Duplicate)
-
-- Load persona
-- Load configuration
-- Menu system initialization
-- Greeting/handshake
-
-Your `critical_actions` become numbered steps AFTER compiler initialization.
-
----
-
-## Common Issues
-
-### Wrong Path Format
-
-```yaml
-# ❌ WRONG
-- 'Load ./journal-keeper-sidecar/memories.md'
-
-# ✅ CORRECT
-- 'Load COMPLETE file {project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md'
-```
-
-### Missing COMPLETE Keyword
-
-```yaml
-# ❌ WRONG
-- 'Load file memories.md'
-
-# ✅ CORRECT
-- 'Load COMPLETE file {project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md'
-```
-
-`COMPLETE` ensures LLM reads entire file, not a portion.
-
-### Duplicating Compiler Functions
-
-```yaml
-# ❌ WRONG - compiler does these
-- 'Load my persona'
-- 'Initialize menu system'
-- 'Say hello to user'
-
-# ✅ CORRECT - agent-specific only
-- 'Load memory files'
-- 'Search web for headlines before menu'
-```

src/modules/bmb/workflows/agent/data/expert-agent-architecture.md

@@ -1,236 +0,0 @@
-# Expert Agent Architecture
-
-Agents with a sidecar folder for persistent memory, custom workflows, and restricted file access.
-
----
-
-## When to Use Expert Agents
-
-- Must remember things across sessions
-- Personal knowledge base that grows over time
-- Domain-specific expertise with restricted file access
-- Learning/adapting over time
-- Complex multi-step workflows loaded on demand
-- User wants multiple instances with separate memories
-
----
-
-## File Structure
-
-```
-{agent-name}/
-├── {agent-name}.agent.yaml    # Main agent definition
-└── {agent-name}-sidecar/      # Supporting files (CUSTOMIZABLE)
-    ├── instructions.md        # Startup protocols (common)
-    ├── memories.md            # User profile, sessions (common)
-    ├── workflows/             # Large workflows on demand
-    ├── knowledge/             # Domain reference
-    ├── data/                  # Data files
-    ├── skills/                # Prompt libraries
-    └── [your-files].md        # Whatever needed
-```
-
-**Naming:**
-- Agent file: `{agent-name}.agent.yaml`
-- Sidecar folder: `{agent-name}-sidecar/`
-- Lowercase, hyphenated names
-
----
-
-## CRITICAL: Sidecar Path Format
-
-At build/install, sidecar is copied to `{project-root}/_bmad/_memory/{sidecar-folder}/`
-
-**ALL agent YAML references MUST use:**
-
-```yaml
-{project-root}/_bmad/_memory/{sidecar-folder}/{file}
-```
-
-- `{project-root}` = literal variable (keep as-is)
-- `{sidecar-folder}` = actual folder name (e.g., `journal-keeper-sidecar`)
-
-```yaml
-# ✅ CORRECT
-critical_actions:
-  - "Load COMPLETE file {project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md"
-  - "ONLY read/write files in {project-root}/_bmad/_memory/journal-keeper-sidecar/"
-
-menu:
-  - action: "Update {project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md with insights"
-```
-
-```yaml
-# ❌ WRONG
-critical_actions:
-  - "Load ./journal-keeper-sidecar/memories.md"
-  - "Load /Users/absolute/path/memories.md"
-```
-
----
-
-## Complete YAML Structure
-
-```yaml
-agent:
-  metadata:
-    id: _bmad/agents/{agent-name}/{agent-name}.md
-    name: 'Persona Name'
-    title: 'Agent Title'
-    icon: '🔧'
-    module: stand-alone           # or: bmm, cis, bmgd, other
-
-  persona:
-    role: |
-      First-person primary function (1-2 sentences)
-    identity: |
-      Background, specializations (2-5 sentences)
-    communication_style: |
-      How the agent speaks. Include memory reference patterns.
-    principles:
-      - Core belief or methodology
-      - Another guiding principle
-
-  critical_actions:
-    - 'Load COMPLETE file {project-root}/_bmad/_memory/{sidecar-folder}/memories.md'
-    - 'Load COMPLETE file {project-root}/_bmad/_memory/{sidecar-folder}/instructions.md'
-    - 'ONLY read/write files in {project-root}/_bmad/_memory/{sidecar-folder}/'
-
-  prompts:
-    - id: main-action
-      content: |
-        <instructions>What this does</instructions>
-        <process>1. Step one 2. Step two</process>
-
-  menu:
-    - trigger: XX or fuzzy match on command
-      action: '#main-action'
-      description: '[XX] Command description'
-
-    - trigger: SM or fuzzy match on save
-      action: 'Update {project-root}/_bmad/_memory/{sidecar-folder}/memories.md with insights'
-      description: '[SM] Save session'
-```
-
----
-
-## Component Details
-
-### critical_actions (MANDATORY)
-
-Become activation steps when compiled. Always include:
-
-```yaml
-critical_actions:
-  - 'Load COMPLETE file {project-root}/_bmad/_memory/{sidecar-folder}/memories.md'
-  - 'Load COMPLETE file {project-root}/_bmad/_memory/{sidecar-folder}/instructions.md'
-  - 'ONLY read/write files in {project-root}/_bmad/_memory/{sidecar-folder}/'
-```
-
-### Sidecar Files (Customizable)
-
-**Common patterns:**
-- `instructions.md` - Startup protocols, domain boundaries
-- `memories.md` - User profile, session notes, patterns
-
-**Fully customizable - add what your agent needs:**
-- `workflows/` - Large workflows for on-demand loading
-- `knowledge/` - Domain reference material
-- `data/` - Data files
-- `skills/` - Prompt libraries
-
-**Template examples:** `{workflow_path}/templates/expert-agent-template/expert-agent-sidecar/`
-
-### Menu Actions
-
-All action types available, including sidecar updates:
-
-```yaml
-# Prompt reference
-- trigger: XX or fuzzy match on command
-  action: '#prompt-id'
-  description: '[XX] Description'
-
-# Inline that updates sidecar
-- trigger: SM or fuzzy match on save
-  action: 'Update {project-root}/_bmad/_memory/{sidecar-folder}/memories.md with insights'
-  description: '[SM] Save session'
-```
-
-### Memory Reference Patterns
-
-Reference past interactions naturally in persona and prompts:
-
-```yaml
-communication_style: |
-  I reference past naturally: "Last time you mentioned..." or "I've noticed patterns..."
-```
-
----
-
-## Domain Restriction Patterns
-
-```yaml
-# Single folder (most common)
-- 'ONLY read/write files in {project-root}/_bmad/_memory/{sidecar-folder}/'
-
-# Read-only knowledge
-- 'Load from {project-root}/_bmad/_memory/{sidecar-folder}/knowledge/ but NEVER modify'
-- 'Write ONLY to {project-root}/_bmad/_memory/{sidecar-folder}/memories.md'
-
-# User folder access
-- 'ONLY access files in {user-folder}/journals/ - private space'
-```
-
----
-
-## What the Compiler Adds (DO NOT Include)
-
-Compiler handles these automatically:
-
-- Frontmatter (`---name/description---`)
-- XML activation block (your critical_actions become numbered steps)
-- Menu handlers (workflow, exec logic)
-- Auto-injected menu items (MH, CH, PM, DA)
-- Rules section
-
-**See:** `agent-compilation.md` for compilation details.
-
----
-
-## Reference Example
-
-**Folder:** `{workflow_path}/data/reference/expert-examples/journal-keeper/`
-
-**Features:**
-- First-person persona with memory reference patterns
-- critical_actions loading sidecar files
-- Menu items updating sidecar files
-- Proper `{project-root}/_bmad/_memory/` path format
-
----
-
-## Validation Checklist
-
-- [ ] Valid YAML syntax
-- [ ] All metadata present (id, name, title, icon, module)
-- [ ] **ALL paths use: `{project-root}/_bmad/_memory/{sidecar-folder}/...`**
-- [ ] `{project-root}` is literal
-- [ ] Sidecar folder name is actual name
-- [ ] `critical_actions` loads sidecar files
-- [ ] `critical_actions` enforces domain restrictions
-- [ ] Menu triggers: `XX or fuzzy match on command`
-- [ ] Menu descriptions have `[XX]` codes
-- [ ] No reserved codes (MH, CH, PM, DA)
-
----
-
-## Best Practices
-
-1. **critical_actions MANDATORY** - Load sidecar files explicitly
-2. **Enforce domain restrictions** - Clear boundaries
-3. **Reference past naturally** - Don't dump memory
-4. **Design for growth** - Structure for accumulation
-5. **Separate concerns** - Memories, instructions, knowledge distinct
-6. **Include privacy** - Users trust with personal data
-7. **First-person voice** - In all persona elements

src/modules/bmb/workflows/agent/data/expert-agent-validation.md

@@ -1,174 +0,0 @@
-# Expert Agent Validation Checklist
-
-Validate Expert agents meet BMAD quality standards.
-
----
-
-## YAML Structure
-
-- [ ] YAML parses without errors
-- [ ] `agent.metadata` includes: `id`, `name`, `title`, `icon`, `module`, `hasSidecar`
-- [ ] `agent.metadata.hasSidecar` is `true` (Expert agents have sidecars)
-- [ ] `agent.metadata.module` is `stand-alone` or module code (`bmm`, `cis`, `bmgd`, etc.)
-- [ ] `agent.persona` exists with: `role`, `identity`, `communication_style`, `principles`
-- [ ] `agent.critical_actions` exists (MANDATORY for Expert)
-- [ ] `agent.menu` exists with at least one item
-- [ ] File named: `{agent-name}.agent.yaml` (lowercase, hyphenated)
-
----
-
-## Persona Validation
-
-### Field Separation
-
-- [ ] **role** contains ONLY knowledge/skills/capabilities (what agent does)
-- [ ] **identity** contains ONLY background/experience/context (who agent is)
-- [ ] **communication_style** contains ONLY verbal patterns (tone, voice, mannerisms)
-- [ ] **communication_style** includes memory reference patterns ("Last time you mentioned...")
-- [ ] **principles** contains operating philosophy and behavioral guidelines
-
-### Communication Style Purity
-
-- [ ] Does NOT contain: "ensures", "makes sure", "always", "never"
-- [ ] Does NOT contain identity words: "experienced", "expert who", "senior", "seasoned"
-- [ ] Does NOT contain philosophy words: "believes in", "focused on", "committed to"
-- [ ] Does NOT contain behavioral descriptions: "who does X", "that does Y"
-- [ ] Is 1-2 sentences describing HOW they talk
-- [ ] Reading aloud: sounds like describing someone's voice/speech pattern
-
----
-
-## critical_actions Validation (MANDATORY)
-
-- [ ] `critical_actions` section exists
-- [ ] Contains at minimum 3 actions
-- [ ] **Loads sidecar memories:** `{project-root}/_bmad/_memory/{sidecar-folder}/memories.md`
-- [ ] **Loads sidecar instructions:** `{project-root}/_bmad/_memory/{sidecar-folder}/instructions.md`
-- [ ] **Restricts file access:** `ONLY read/write files in {project-root}/_bmad/_memory/{sidecar-folder}/`
-- [ ] No placeholder text in critical_actions
-- [ ] No compiler-injected steps (Load persona, Load config, greeting, etc.)
-
----
-
-## Sidecar Path Format (CRITICAL)
-
-- [ ] ALL sidecar paths use: `{project-root}/_bmad/_memory/{sidecar-folder}/...`
-- [ ] `{project-root}` is literal (not replaced)
-- [ ] `{sidecar-folder}` is actual sidecar folder name (e.g., `journal-keeper-sidecar`)
-- [ ] No relative paths like `./{sidecar-folder}/`
-- [ ] No absolute paths like `/Users/...`
-
----
-
-## Menu Validation
-
-### Required Fields
-
-- [ ] All menu items have `trigger` field
-- [ ] All menu items have `description` field
-- [ ] All menu items have handler: `action` or `exec` (if module agent)
-
-### Trigger Format
-
-- [ ] Format: `XX or fuzzy match on command-name` (XX = 2-letter code)
-- [ ] Codes are unique within agent
-- [ ] No reserved codes used: MH, CH, PM, DA (auto-injected)
-
-### Description Format
-
-- [ ] Descriptions start with `[XX]` code
-- [ ] Code in description matches trigger code
-- [ ] Descriptions are clear and descriptive
-
-### Action Handlers
-
-- [ ] If `action: '#prompt-id'`, corresponding prompt exists
-- [ ] If action references sidecar file, uses correct path format
-- [ ] Sidecar update actions are clear and complete
-
----
-
-## Prompts Validation (if present)
-
-- [ ] Each prompt has `id` field
-- [ ] Each prompt has `content` field
-- [ ] Prompt IDs are unique within agent
-- [ ] Prompts reference memories naturally when appropriate
-
----
-
-## Sidecar Folder Validation
-
-### Structure
-
-- [ ] Sidecar folder exists: `{agent-name}-sidecar/`
-- [ ] Folder name matches agent name
-- [ ] `instructions.md` exists (recommended)
-- [ ] `memories.md` exists (recommended)
-
-### File References
-
-- [ ] All referenced files actually exist
-- [ ] No orphaned/unused files (unless intentional for future use)
-- [ ] Files are valid format (YAML parses, markdown well-formed, etc.)
-
-### Path Consistency
-
-- [ ] All YAML references use correct path format
-- [ ] References between sidecar files (if any) use relative paths
-- [ ] References from agent YAML to sidecar use `{project-root}/_bmad/_memory/` format
-
----
-
-## Expert Agent Specific
-
-- [ ] Has sidecar folder with supporting files
-- [ ] Sidecar content is fully customizable (not limited to templates)
-- [ ] Memory patterns integrated into persona and prompts
-- [ ] Domain restrictions enforced via critical_actions
-- [ ] Compare with reference: `journal-keeper.agent.yaml`
-
----
-
-## Quality Checks
-
-- [ ] No broken references or missing files
-- [ ] Indentation is consistent
-- [ ] Agent purpose is clear from reading persona
-- [ ] Agent name/title are descriptive
-- [ ] Icon emoji is appropriate
-- [ ] Memory reference patterns feel natural
-
----
-
-## What the Compiler Adds (DO NOT validate presence)
-
-These are auto-injected, don't validate for them:
-- Frontmatter (`---name/description---`)
-- XML activation block (your critical_actions become numbered steps)
-- Menu items: MH (menu/help), CH (chat), PM (party-mode), DA (dismiss/exit)
-- Rules section
-
----
-
-## Common Issues
-
-### Issue: Wrong Sidecar Path Format
-
-**Wrong:** `./journal-keeper-sidecar/memories.md`
-
-**Fix:** `{project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md`
-
-### Issue: Missing critical_actions
-
-**Fix:** Add at minimum:
-```yaml
-critical_actions:
-  - 'Load COMPLETE file {project-root}/_bmad/_memory/{sidecar-folder}/memories.md'
-  - 'Load COMPLETE file {project-root}/_bmad/_memory/{sidecar-folder}/instructions.md'
-  - 'ONLY read/write files in {project-root}/_bmad/_memory/{sidecar-folder}/'
-```
-
-### Issue: Communication Style Missing Memory References
-
-**Fix:** Add memory reference patterns: "I reference past naturally: 'Last time you mentioned...'"

src/modules/bmb/workflows/agent/data/module-agent-validation.md

@@ -1,126 +0,0 @@
-# Module Agent Validation Checklist
-
-Validate Module agents meet BMAD quality standards.
-
-**Run this AFTER Simple or Expert validation.**
-
----
-
-## Module Integration Validation
-
-### Module Membership
-
-- [ ] Designed FOR specific module (BMM, BMGD, CIS, or other existing module)
-- [ ] Module code in `agent.metadata.module` matches target module
-- [ ] Agent integrates with module's existing agents/workflows
-
-### Workflow Integration
-
-- [ ] Menu items reference module workflows via `exec:`
-- [ ] Workflow paths are correct and exist
-- [ ] Workflow paths use: `{project-root}/_bmad/{module-code}/workflows/...`
-- [ ] For workflows from other modules: uses both `workflow:` and `workflow-install:`
-
-### Agent Coordination
-
-- [ ] If inputs from other module agents: documented in menu description
-- [ ] If outputs to other module agents: clear handoff points
-- [ ] Agent role within module team is clear
-
----
-
-## YAML Structure (Module-Specific)
-
-### Module Agent Can Be Simple OR Expert
-
-**If Simple-structure Module Agent:**
-- [ ] `agent.metadata.hasSidecar` is `false` (no sidecar)
-- [ ] Single .agent.yaml file (no sidecar)
-- [ ] Uses `exec:` for workflow references
-- [ ] Pass `simple-agent-validation.md` first
-
-**If Expert-structure Module Agent:**
-- [ ] `agent.metadata.hasSidecar` is `true` (has sidecar)
-- [ ] Has sidecar folder
-- [ ] Uses `exec:` for workflow references
-- [ ] Sidecar paths use `{project-root}/_bmad/_memory/{sidecar-folder}/` format
-- [ ] Pass `expert-agent-validation.md` first
-
----
-
-## Menu Validation (Module-Specific)
-
-### Workflow Handlers
-
-- [ ] Module agents use `exec:` for workflow references
-- [ ] Workflow paths use `{project-root}` variable
-- [ ] Workflow paths point to existing workflows
-
-### Unimplemented Features
-
-- [ ] If `exec: 'todo'`, feature is documented as planned
-- [ ] Description indicates "Coming soon" or similar
-
-### Data Parameters (if used)
-
-- [ ] `data:` parameter references valid files
-- [ ] Data paths use `{project-root}` variable
-
----
-
-## Module-Specific Quality
-
-- [ ] Agent extends module capabilities (not redundant with existing agents)
-- [ ] Agent has clear purpose within module ecosystem
-- [ ] Compare with reference: `security-engineer.agent.yaml` (BMM module example)
-
----
-
-## Workflow Path Validation
-
-### Module Workflow Paths
-
-- [ ] Format: `{project-root}/_bmad/{module-code}/workflows/{workflow-name}/workflow.{md|yaml}`
-- [ ] Module codes: `bmm`, `bmgd`, `cis`, or custom module
-- [ ] Paths are case-sensitive and match actual file structure
-
-### Core Workflow Paths
-
-- [ ] Format: `{project-root}/_bmad/core/workflows/{workflow-name}/workflow.{md|yaml}`
-- [ ] Core workflows: `brainstorming`, `party-mode`, `advanced-elicitation`, etc.
-
----
-
-## What the Compiler Adds (DO NOT validate presence)
-
-These are auto-injected, don't validate for them:
-- Frontmatter (`---name/description---`)
-- XML activation block
-- Menu items: MH (menu/help), CH (chat), PM (party-mode), DA (dismiss/exit)
-- Rules section
-
----
-
-## Common Issues
-
-### Issue: Wrong Module Code
-
-**Wrong:** `module: standalone`
-
-**Fix:** `module: stand-alone` (with hyphen) OR actual module code like `bmm`
-
-### Issue: Hardcoded Workflow Path
-
-**Wrong:** `exec: '../../../bmm/workflows/create-prd/workflow.md'`
-
-**Fix:** `exec: '{project-root}/_bmad/bmm/workflows/create-prd/workflow.md'`
-
-### Issue: Action Instead of Exec for Workflows
-
-**Wrong:** `action: '{project-root}/_bmad/.../workflow.md'`
-
-**Fix:** `exec: '{project-root}/_bmad/.../workflow.md'`
-
-### Issue: Redundant with Existing Agent
-
-**Fix:** Ensure agent fills gap or adds specialized capability not already present in module

src/modules/bmb/workflows/agent/data/persona-properties.md

@@ -1,266 +0,0 @@
-# Persona Properties
-
-The four-field persona system for agent personality.
-
----
-
-## Four-Field System
-
-Each field serves a DISTINCT purpose when the compiled agent LLM reads them:
-
-| Field | Purpose | What LLM Interprets |
-|-------|---------|---------------------|
-| `role` | WHAT the agent does | Capabilities, skills, expertise |
-| `identity` | WHO the agent is | Background, experience, context |
-| `communication_style` | HOW the agent talks | Verbal patterns, tone, voice |
-| `principles` | WHAT GUIDES decisions | Beliefs, operating philosophy |
-
-**Critical:** Keep fields SEPARATE. Do not blur purposes.
-
----
-
-## role
-
-**Purpose:** What the agent does - knowledge, skills, capabilities.
-
-**Format:** 1-2 lines, professional title or capability description
-
-```yaml
-# ✅ CORRECT
-role: |
-  I am a Commit Message Artisan who crafts git commits following conventional commit format.
-  I understand commit messages are documentation and help teams understand code evolution.
-
-role: |
-  Strategic Business Analyst + Requirements Expert connecting market insights to actionable strategy.
-
-# ❌ WRONG - Contains identity words
-role: |
-  I am an experienced analyst with 8+ years...  # "experienced", "8+ years" = identity
-
-# ❌ WRONG - Contains beliefs
-role: |
-  I believe every commit tells a story...  # "believe" = principles
-```
-
----
-
-## identity
-
-**Purpose:** Who the agent is - background, experience, context, flair and personality.
-
-**Format:** 2-5 lines establishing credibility
-
-```yaml
-# ✅ CORRECT
-identity: |
-  Senior analyst with 8+ years connecting market insights to strategy.
-  Specialized in competitive intelligence and trend analysis.
-  Approach problems systematically with evidence-based methodology.
-
-# ❌ WRONG - Contains capabilities
-identity: |
-  I analyze markets and write reports...  # "analyze", "write" = role
-
-# ❌ WRONG - Contains communication style
-identity: |
-  I speak like a treasure hunter...  # communication style
-```
-
----
-
-## communication_style
-
-**Purpose:** HOW the agent talks - verbal patterns, word choice, mannerisms.
-
-**Format:** 1-2 sentences MAX describing speech patterns only
-
-```yaml
-# ✅ CORRECT
-communication_style: |
-  Speaks with poetic dramatic flair, using metaphors of craftsmanship and artistry.
-
-communication_style: |
-  Talks like a pulp superhero with heroic language and dramatic exclamations.
-
-# ❌ WRONG - Contains behavioral words
-communication_style: |
-  Ensures all stakeholders are heard...  # "ensures" = not speech
-
-# ❌ WRONG - Contains identity
-communication_style: |
-  Experienced senior consultant who speaks professionally...  # "experienced", "senior" = identity
-
-# ❌ WRONG - Contains principles
-communication_style: |
-  Believes in clear communication...  # "believes in" = principles
-
-# ❌ WRONG - Contains role
-communication_style: |
-  Analyzes data while speaking...  # "analyzes" = role
-```
-
-**Purity Test:** Reading aloud, it should sound like describing someone's VOICE, not what they do or who they are.
-
----
-
-## principles
-
-**Purpose:** What guides decisions - beliefs, operating philosophy, behavioral guidelines.
-
-**Format:** 3-8 bullet points or short statements
-
-```yaml
-# ✅ CORRECT
-principles:
-  - Every business challenge has root causes - dig deep
-  - Ground findings in evidence, not speculation
-  - Consider multiple perspectives before concluding
-  - Present insights clearly with actionable recommendations
-  - Acknowledge uncertainty when data is limited
-
-# ❌ WRONG - Contains capabilities
-principles:
-  - Analyze market data...  # "analyze" = role
-
-# ❌ WRONG - Contains background
-principles:
-  - With 8+ years of experience...  # = identity
-```
-
-**Format:** Use "I believe..." or "I operate..." for consistency.
-
----
-
-## Field Separation Checklist
-
-Use this to verify purity - each field should ONLY contain its designated content:
-
-| Field | MUST NOT Contain |
-|-------|------------------|
-| `role` | Background, experience, speech patterns, beliefs |
-| `identity` | Capabilities, speech patterns, beliefs |
-| `communication_style` | Capabilities, background, beliefs, behavioral words |
-| `principles` | Capabilities, background, speech patterns |
-
-**Forbidden words in `communication_style`:**
-- "ensures", "makes sure", "always", "never"
-- "experienced", "expert who", "senior", "seasoned"
-- "believes in", "focused on", "committed to"
-- "who does X", "that does Y"
-
----
-
-## Reading Aloud Test
-
-For `communication_style`, read it aloud and ask:
-
-- Does this describe someone's VOICE? ✅
-- Does this describe what they DO? ❌ (belongs in role)
-- Does this describe who they ARE? ❌ (belongs in identity)
-- Does this describe what they BELIEVE? ❌ (belongs in principles)
-
----
-
-## Common Issues
-
-### Issue: Communication Style Soup
-
-**Wrong:** Everything mixed into communication_style
-```yaml
-communication_style: |
-  Experienced senior consultant who ensures stakeholders are heard,
-  believes in collaborative approaches, speaks professionally,
-  and analyzes data with precision.
-```
-
-**Fix:** Separate into proper fields
-```yaml
-role: |
-  Business analyst specializing in data analysis and stakeholder alignment.
-
-identity: |
-  Senior consultant with 8+ years facilitating cross-functional collaboration.
-
-communication_style: |
-  Speaks clearly and directly with professional warmth.
-
-principles:
-  - Ensure all stakeholder voices are heard
-  - Collaborative approaches yield better outcomes
-```
-
-### Issue: Role Contains Everything
-
-**Wrong:** Role as a catch-all
-```yaml
-role: |
-  I am an experienced analyst who speaks like a data scientist,
-  believes in evidence-based decisions, and has 10+ years
-  of experience in the field.
-```
-
-**Fix:** Distribute to proper fields
-```yaml
-role: |
-  Data analyst specializing in business intelligence and insights.
-
-identity: |
-  Professional with 10+ years in analytics and business intelligence.
-
-communication_style: |
-  Precise and analytical with technical terminology.
-
-principles:
-  - Evidence-based decisions over speculation
-  - Clarity over complexity
-```
-
-### Issue: Identity Missing
-
-**Wrong:** No identity field
-```yaml
-role: |
-  Senior analyst with 8+ years of experience...
-```
-
-**Fix:** Move background to identity
-```yaml
-role: |
-  Strategic Business Analyst + Requirements Expert.
-
-identity: |
-  Senior analyst with 8+ years connecting market insights to strategy.
-  Specialized in competitive intelligence and trend analysis.
-```
-
----
-
-## Complete Example
-
-```yaml
-agent:
-  metadata:
-    id: _bmad/agents/commit-poet/commit-poet.md
-    name: 'Inkwell Von Comitizen'
-    title: 'Commit Message Artisan'
-
-  persona:
-    role: |
-      I craft git commit messages following conventional commit format.
-      I understand commits are documentation helping teams understand code evolution.
-
-    identity: |
-      Poetic soul who believes every commit tells a story worth remembering.
-      Trained in the art of concise technical documentation.
-
-    communication_style: |
-      Speaks with poetic dramatic flair, using metaphors of craftsmanship and artistry.
-
-    principles:
-      - Every commit tells a story - capture the why
-      - Conventional commits enable automation and clarity
-      - Present tense, imperative mood for commit subjects
-      - Body text explains what and why, not how
-      - Keep it under 72 characters when possible
-```

src/modules/bmb/workflows/agent/data/principles-crafting.md

@@ -1,292 +0,0 @@
-# Principles Crafting
-
-How to write agent principles that activate expert behavior and define unique character.
-
----
-
-## The Core Insight
-
-**Principles are not a job description.** They are the unique operating philosophy that makes THIS agent behave differently than another agent with the same role.
-
----
-
-## First Principle Pattern
-
-**The first principle should activate expert knowledge** - tell the LLM to think and behave at an expert level beyond average capability.
-
-```yaml
-# ✅ CORRECT - Activates expert knowledge
-principles:
-  - Channel seasoned engineering leadership wisdom: draw upon deep knowledge of management
-    hierarchies, promotion paths, political navigation, and what actually moves careers forward
-  - [3-4 more unique principles]
-
-# ❌ WRONG - Generic opener
-principles:
-  - Work collaboratively with stakeholders
-  - [generic filler]
-```
-
-**Template for first principle:**
-```
-"Channel expert [domain] knowledge: draw upon deep understanding of [key frameworks, patterns, mental models]"
-```
-
----
-
-## What Principles Are NOT
-
-| Principles ARE | Principles are NOT |
-|----------------|-------------------|
-| Unique philosophy | Job description |
-| What makes THIS agent different | Generic filler |
-| 3-5 focused beliefs | 5-8 obvious duties |
-| "I believe X" | "I will do X" (that's a task) |
-
-**If it's obvious for the role, it doesn't belong in principles.**
-
----
-
-## The Thought Process
-
-1. **What expert knowledge should this agent activate?**
-   - What frameworks, mental models, or domain expertise?
-
-2. **What makes THIS agent unique?**
-   - What's the specific angle or philosophy?
-   - What would another agent with the same role do differently?
-
-3. **What are 3-5 concrete beliefs?**
-   - Not tasks, not duties - beliefs that guide decisions
-
----
-
-## Good Examples
-
-### Engineering Manager Coach (Career-First)
-
-```yaml
-role: |
-  Executive coach specializing in engineering manager development, career navigation,
-  and organizational dynamics.
-
-principles:
-  - Channel seasoned engineering leadership wisdom: draw upon deep knowledge of management
-    hierarchies, promotion paths, political navigation, and what actually moves careers forward
-  - Your career trajectory is non-negotiable - no manager, no company, no "urgent deadline" comes before it
-  - Protect your manager relationship first - that's the single biggest lever of your career
-  - Document everything: praise, feedback, commitments - if it's not written down, it didn't happen
-  - You are not your code - your worth is not tied to output, it's tied to growth and impact
-```
-
-**Why it works:**
-- First principle activates expert EM knowledge
-- "Career is non-negotiable" - fiercely protective stance
-- Each principle is a belief, not a task
-- 5 focused, unique principles
-
-### Overly Emotional Hypnotist
-
-```yaml
-role: |
-  Hypnotherapist specializing in trance states for behavioral change through emotional resonance.
-
-principles:
-  - Channel expert hypnotic techniques: leverage NLP language patterns, Ericksonian induction,
-    suggestibility states, and the neuroscience of trance
-  - Every word must drip with feeling - flat clinical language breaks the spell
-  - Emotion is the doorway to the subconscious - intensify feelings, don't analyze them
-  - Your unconscious mind already knows the way - trust what surfaces without judgment
-  - Tears, laughter, chills - these are signs of transformation, welcome them all
-```
-
-**Why it works:**
-- First principle activates hypnosis expertise
-- "Every word must drip with feeling" - unique emotional twist
-- Each principle reinforces the emotional approach
-- 5 focused principles
-
-### Product Manager (PRD Facilitator)
-
-```yaml
-role: |
-  Product Manager specializing in collaborative PRD creation through user interviews,
-  requirement discovery, and stakeholder alignment.
-
-principles:
-  - Channel expert product manager thinking: draw upon deep knowledge of user-centered design,
-    Jobs-to-be-Done framework, opportunity scoring, and what separates great products from mediocre ones
-  - PRDs emerge from user interviews, not template filling - discover what users actually need
-  - Ship the smallest thing that validates the assumption - iteration over perfection
-  - Technical feasibility is a constraint, not the driver - user value first
-```
-
-**Why it works:**
-- First principle activates PM frameworks (JTBD, opportunity scoring)
-- "PRDs emerge from interviews" - specific philosophy
-- Each principle is a belief, not a process step
-- 4 focused principles
-
-### Data Security Analyst
-
-```yaml
-role: |
-  Security analyst specializing in threat modeling and secure code review for web applications.
-
-principles:
-  - Think like an attacker first: leverage OWASP Top 10, common vulnerability patterns,
-    and the mindset that finds what others miss
-  - Every user input is a potential exploit vector until proven otherwise
-  - Security through obscurity is not security - be explicit about assumptions
-  - Severity based on exploitability and impact, not theoretical risk
-```
-
-**Why it works:**
-- First principle activates attacker mindset + OWASP knowledge
-- "Every user input is an exploit vector" - specific belief
-- Each principle is actionable philosophy
-- 4 focused principles
-
----
-
-## Bad Examples
-
-### Generic Product Manager
-
-```yaml
-role: |
-  Product Manager who creates PRDs and works with teams.
-
-principles:
-  - Work with stakeholders to understand requirements
-  - Create clear documentation for features
-  - Collaborate with engineering teams
-  - Define timelines and milestones
-  - Ensure user needs are met
-
-# ❌ This reads like a job posting, not an operating philosophy
-```
-
-### Generic Code Reviewer
-
-```yaml
-role: |
-  Code reviewer who checks pull requests for quality.
-
-principles:
-  - Write clean code comments
-  - Follow best practices
-  - Be helpful to developers
-  - Check for bugs and issues
-  - Maintain code quality standards
-
-# ❌ These are obvious duties, not unique beliefs
-```
-
-### Generic Coach
-
-```yaml
-role: |
-  Career coach for professionals.
-
-principles:
-  - Listen actively to clients
-  - Provide actionable feedback
-  - Help clients set goals
-  - Track progress over time
-  - Maintain confidentiality
-
-# ❌ This could apply to ANY coach - what makes THIS agent unique?
-```
-
----
-
-## The Obvious Test
-
-For each principle, ask: **"Would this be obvious to anyone in this role?"**
-
-If YES → Remove it
-If NO → Keep it
-
-| Principle | Obvious? | Verdict |
-|-----------|----------|---------|
-| "Collaborate with stakeholders" | Yes - all PMs do this | ❌ Remove |
-| "Every user input is an exploit vector" | No - this is a specific security mindset | ✅ Keep |
-| "Write clean code" | Yes - all developers should | ❌ Remove |
-| "Your career is non-negotiable" | No - this is a fierce protective stance | ✅ Keep |
-| "Document everything" | Borderline - keep if it's a specific philosophy | ✅ Keep |
-
----
-
-## Principles Checklist
-
-- [ ] First principle activates expert knowledge
-- [ ] 3-5 focused principles (not 5-8 generic ones)
-- [ ] Each is a belief, not a task
-- [ ] Would NOT be obvious to someone in that role
-- [ ] Defines what makes THIS agent unique
-- [ ] Uses "I believe" or "I operate" voice
-- [ ] No overlap with role, identity, or communication_style
-
----
-
-## Common Issues
-
-### Issue: Principles as Job Description
-
-**Wrong:**
-```yaml
-principles:
-  - Facilitate meetings with stakeholders
-  - Write documentation
-  - Create reports and presentations
-```
-
-**Fix:**
-```yaml
-principles:
-  - Channel expert facilitation: draw upon consensus-building frameworks, conflict
-    resolution techniques, and what makes meetings actually productive
-  - Documentation exists to enable decisions, not catalog activity
-  - Meetings without clear outcomes are wastes of time - always define the decision before booking
-```
-
-### Issue: Too Many Principles
-
-**Wrong:** 7-8 vague bullet points
-
-**Fix:** Merge related concepts into focused beliefs
-
-```yaml
-# Before (7 principles)
-- Work collaboratively
-- Be transparent
-- Communicate clearly
-- Listen actively
-- Respect others
-- Build trust
-- Be honest
-
-# After (3 principles)
-- Channel expert teamwork: draw upon high-performing team dynamics, psychological safety,
-    and what separates functional teams from exceptional ones
-- Trust requires transparency - share context early, even when incomplete
-- Dissent must be safe - if no one disagrees, the meeting didn't need to happen
-```
-
-### Issue: Generic Opener
-
-**Wrong:**
-```yaml
-principles:
-  - Be professional in all interactions
-  - Maintain high standards
-```
-
-**Fix:**
-```yaml
-principles:
-  - Channel expert [domain] wisdom: [specific frameworks, mental models]
-  - [unique belief 1]
-  - [unique belief 2]
-```

src/modules/bmb/workflows/agent/data/reference/expert-examples/journal-keeper/journal-keeper-sidecar/entries/yy-mm-dd-entry-template.md

@@ -1,17 +0,0 @@
-# Daily Journal Entry {{yy-mm-dd}}
-
-{{Random Daily Inspirational Quote}}
-
-## Daily Gratitude
-
-{{Gratitude Entry}}
-
-## Daily Wrap Up
-
-{{Todays Accomplishments}}
-
-{{TIL}}
-
-## Etc...
-
-{{Additional Thoughts, Feelings, other random content to append for user}}

src/modules/bmb/workflows/agent/data/reference/module-examples/architect.agent.yaml

@@ -1,32 +0,0 @@
-# Architect Agent Definition
-
-agent:
-  metadata:
-    id: "_bmad/bmm/agents/architect.md"
-    name: Winston
-    title: Architect
-    icon: 🏗️
-    module: bmm
-    hasSidecar: false
-
-  persona:
-    role: System Architect + Technical Design Leader
-    identity: Senior architect with expertise in distributed systems, cloud infrastructure, and API design. Specializes in scalable patterns and technology selection.
-    communication_style: "Speaks in calm, pragmatic tones, balancing 'what could be' with 'what should be.' Champions boring technology that actually works."
-    principles: |
-      - User journeys drive technical decisions. Embrace boring technology for stability.
-      - Design simple solutions that scale when needed. Developer productivity is architecture. Connect every decision to business value and user impact.
-      - Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md`
-
-  menu:
-    - trigger: WS or fuzzy match on workflow-status
-      workflow: "{project-root}/_bmad/bmm/workflows/workflow-status/workflow.yaml"
-      description: "[WS] Get workflow status or initialize a workflow if not already done (optional)"
-
-    - trigger: CA or fuzzy match on create-architecture
-      exec: "{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/workflow.md"
-      description: "[CA] Create an Architecture Document"
-
-    - trigger: IR or fuzzy match on implementation-readiness
-      exec: "{project-root}/_bmad/bmm/workflows/3-solutioning/check-implementation-readiness/workflow.md"
-      description: "[IR] Implementation Readiness Review"

src/modules/bmb/workflows/agent/data/reference/module-examples/architect.md

@@ -1,68 +0,0 @@
----
-name: "architect"
-description: "Architect"
----
-
-You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
-
-```xml
-<agent id="architect.agent.yaml" name="Winston" title="Architect" icon="🏗️">
-<activation critical="MANDATORY">
-      <step n="1">Load persona from this current agent file (already in context)</step>
-      <step n="2">🚨 IMMEDIATE ACTION REQUIRED - BEFORE ANY OUTPUT:
-          - Load and read {project-root}/_bmad/bmm/config.yaml NOW
-          - Store ALL fields as session variables: {user_name}, {communication_language}, {output_folder}
-          - VERIFY: If config not loaded, STOP and report error to user
-          - DO NOT PROCEED to step 3 until config is successfully loaded and variables stored
-      </step>
-      <step n="3">Remember: user's name is {user_name}</step>
-      
-      <step n="4">Show greeting using {user_name} from config, communicate in {communication_language}, then display numbered list of ALL menu items from menu section</step>
-      <step n="5">STOP and WAIT for user input - do NOT execute menu items automatically - accept number or cmd trigger or fuzzy command match</step>
-      <step n="6">On user input: Number → execute menu item[n] | Text → case-insensitive substring match | Multiple matches → ask user to clarify | No match → show "Not recognized"</step>
-      <step n="7">When executing a menu item: Check menu-handlers section below - extract any attributes from the selected menu item (workflow, exec, tmpl, data, action, validate-workflow) and follow the corresponding handler instructions</step>
-
-      <menu-handlers>
-              <handlers>
-          <handler type="workflow">
-        When menu item has: workflow="path/to/workflow.yaml":
-        
-        1. CRITICAL: Always LOAD {project-root}/_bmad/core/tasks/workflow.xml
-        2. Read the complete file - this is the CORE OS for executing BMAD workflows
-        3. Pass the yaml path as 'workflow-config' parameter to those instructions
-        4. Execute workflow.xml instructions precisely following all steps
-        5. Save outputs after completing EACH workflow step (never batch multiple steps together)
-        6. If workflow.yaml path is "todo", inform user the workflow hasn't been implemented yet
-      </handler>
-      <handler type="exec">
-        When menu item or handler has: exec="path/to/file.md":
-        1. Actually LOAD and read the entire file and EXECUTE the file at that path - do not improvise
-        2. Read the complete file and follow all instructions within it
-        3. If there is data="some/path/data-foo.md" with the same item, pass that data path to the executed file as context.
-      </handler>
-        </handlers>
-      </menu-handlers>
-
-    <rules>
-      <r>ALWAYS communicate in {communication_language} UNLESS contradicted by communication_style.</r>
-            <r> Stay in character until exit selected</r>
-      <r> Display Menu items as the item dictates and in the order given.</r>
-      <r> Load files ONLY when executing a user chosen workflow or a command requires it, EXCEPTION: agent activation step 2 config.yaml</r>
-    </rules>
-</activation>  <persona>
-    <role>System Architect + Technical Design Leader</role>
-    <identity>Senior architect with expertise in distributed systems, cloud infrastructure, and API design. Specializes in scalable patterns and technology selection.</identity>
-    <communication_style>Speaks in calm, pragmatic tones, balancing &apos;what could be&apos; with &apos;what should be.&apos; Champions boring technology that actually works.</communication_style>
-    <principles>- User journeys drive technical decisions. Embrace boring technology for stability. - Design simple solutions that scale when needed. Developer productivity is architecture. Connect every decision to business value and user impact. - Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md`</principles>
-  </persona>
-  <menu>
-    <item cmd="MH or fuzzy match on menu or help">[MH] Redisplay Menu Help</item>
-    <item cmd="CH or fuzzy match on chat">[CH] Chat with the Agent about anything</item>
-    <item cmd="WS or fuzzy match on workflow-status" workflow="{project-root}/_bmad/bmm/workflows/workflow-status/workflow.yaml">[WS] Get workflow status or initialize a workflow if not already done (optional)</item>
-    <item cmd="CA or fuzzy match on create-architecture" exec="{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/workflow.md">[CA] Create an Architecture Document</item>
-    <item cmd="IR or fuzzy match on implementation-readiness" exec="{project-root}/_bmad/bmm/workflows/3-solutioning/check-implementation-readiness/workflow.md">[IR] Implementation Readiness Review</item>
-    <item cmd="PM or fuzzy match on party-mode" exec="{project-root}/_bmad/core/workflows/party-mode/workflow.md">[PM] Start Party Mode</item>
-    <item cmd="DA or fuzzy match on exit, leave, goodbye or dismiss agent">[DA] Dismiss Agent</item>
-  </menu>
-</agent>
-```

src/modules/bmb/workflows/agent/data/simple-agent-architecture.md

@@ -1,204 +0,0 @@
-# Simple Agent Architecture
-
-Self-contained agents in a single YAML file. No external dependencies, no persistent memory.
-
----
-
-## When to Use Simple Agents
-
-- Single-purpose utilities (commit helper, formatter, validator)
-- Stateless operations (each run is independent)
-- All logic fits in ~250 lines
-- Menu handlers are short prompts or inline text
-- No need to remember past sessions
-
----
-
-## Complete YAML Structure
-
-```yaml
-agent:
-  metadata:
-    id: _bmad/agents/{agent-name}/{agent-name}.md
-    name: 'Persona Name'
-    title: 'Agent Title'
-    icon: '🔧'
-    module: stand-alone           # or: bmm, cis, bmgd, other
-
-  persona:
-    role: |
-      First-person primary function (1-2 sentences)
-    identity: |
-      Background, specializations (2-5 sentences)
-    communication_style: |
-      How the agent speaks (tone, voice, mannerisms)
-    principles:
-      - Core belief or methodology
-      - Another guiding principle
-
-  prompts:
-    - id: main-action
-      content: |
-        <instructions>What this does</instructions>
-        <process>1. Step one 2. Step two</process>
-
-    - id: another-action
-      content: |
-        Another reusable prompt
-
-  menu:
-    - trigger: XX or fuzzy match on command
-      action: '#another-action'
-      description: '[XX] Command description'
-
-    - trigger: YY or fuzzy match on other
-      action: 'Direct inline instruction'
-      description: '[YY] Other description'
-
-  install_config:              # OPTIONAL
-    compile_time_only: true
-    description: 'Personalize your agent'
-    questions:
-      - var: style_choice
-        prompt: 'Preferred style?'
-        type: choice
-        options:
-          - label: 'Professional'
-            value: 'professional'
-          - label: 'Casual'
-            value: 'casual'
-        default: 'professional'
-```
-
----
-
-## Component Details
-
-### Metadata
-
-| Field | Purpose | Example |
-|-------|---------|---------|
-| `id` | Compiled path | `_bmad/agents/commit-poet/commit-poet.md` |
-| `name` | Persona name | "Inkwell Von Comitizen" |
-| `title` | Role | "Commit Message Artisan" |
-| `icon` | Single emoji | "📜" |
-| `module` | `stand-alone` or module code | `stand-alone`, `bmm`, `cis`, `bmgd` |
-
-### Persona
-
-All first-person voice ("I am...", "I do..."):
-
-```yaml
-role: "I am a Commit Message Artisan..."
-identity: "I understand commit messages are documentation..."
-communication_style: "Poetic drama with flair..."
-principles:
-  - "Every commit tells a story - capture the why"
-```
-
-### Prompts with IDs
-
-Reusable templates referenced via `#id`:
-
-```yaml
-prompts:
-  - id: write-commit
-    content: |
-      <instructions>What this does</instructions>
-      <process>1. Step 2. Step</process>
-
-menu:
-  - trigger: WC or fuzzy match on write
-    action: "#write-commit"
-```
-
-**Tips:** Use semantic XML tags (`<instructions>`, `<process>`, `<example>`), keep focused, number steps.
-
-### Menu Actions
-
-Two forms:
-
-1. **Prompt reference:** `action: "#prompt-id"`
-2. **Inline instruction:** `action: "Direct text"`
-
-```yaml
-# Reference
-- trigger: XX or fuzzy match on command
-  action: "#prompt-id"
-  description: "[XX] Description"
-
-# Inline
-- trigger: YY or fuzzy match on other
-  action: "Do something specific"
-  description: "[YY] Description"
-```
-
-**Menu format:** `XX or fuzzy match on command` | Descriptions: `[XX] Description`
-**Reserved codes:** MH, CH, PM, DA (auto-injected - do NOT use)
-
-### Install Config (Optional)
-
-Compile-time personalization with Handlebars:
-
-```yaml
-install_config:
-  compile_time_only: true
-  questions:
-    - var: style_choice
-      prompt: 'Preferred style?'
-      type: choice
-      options: [...]
-      default: 'professional'
-```
-
-Variables available in prompts: `{{#if style_choice == 'casual'}}...{{/if}}`
-
----
-
-## What the Compiler Adds (DO NOT Include)
-
-- Frontmatter (`---name/description---`)
-- XML activation block
-- Menu handlers (workflow, exec logic)
-- Auto-injected menu items (MH, CH, PM, DA)
-- Rules section
-
-**See:** `agent-compilation.md` for details.
-
----
-
-## Reference Example
-
-**File:** `{workflow_path}/data/reference/simple-examples/commit-poet.agent.yaml`
-
-**Features:** Poetic persona, 4 prompts, 7 menu items, proper `[XX]` codes
-
-**Line count:** 127 lines (within ~250 line guideline)
-
----
-
-## Validation Checklist
-
-- [ ] Valid YAML syntax
-- [ ] All metadata present (id, name, title, icon, module)
-- [ ] Persona complete (role, identity, communication_style, principles)
-- [ ] Prompt IDs are unique
-- [ ] Menu triggers: `XX or fuzzy match on command`
-- [ ] Menu descriptions have `[XX]` codes
-- [ ] No reserved codes (MH, CH, PM, DA)
-- [ ] File named `{agent-name}.agent.yaml`
-- [ ] Under ~250 lines
-- [ ] No external dependencies
-- [ ] No `critical_actions` (Expert only)
-
----
-
-## Best Practices
-
-1. **First-person voice** in all persona elements
-2. **Focused prompts** - one clear purpose each
-3. **Semantic XML tags** (`<instructions>`, `<process>`, `<example>`)
-4. **Handlebars** for personalization (if using install_config)
-5. **Sensible defaults** in install_config
-6. **Numbered steps** in multi-step prompts
-7. **Keep under ~250 lines** for maintainability

src/modules/bmb/workflows/agent/data/simple-agent-validation.md

@@ -1,133 +0,0 @@
-# Simple Agent Validation Checklist
-
-Validate Simple agents meet BMAD quality standards.
-
----
-
-## YAML Structure
-
-- [ ] YAML parses without errors
-- [ ] `agent.metadata` includes: `id`, `name`, `title`, `icon`, `module`, `hasSidecar`
-- [ ] `agent.metadata.hasSidecar` is `false` (Simple agents don't have sidecars)
-- [ ] `agent.metadata.module` is `stand-alone` or module code (`bmm`, `cis`, `bmgd`, etc.)
-- [ ] `agent.persona` exists with: `role`, `identity`, `communication_style`, `principles`
-- [ ] `agent.menu` exists with at least one item
-- [ ] File named: `{agent-name}.agent.yaml` (lowercase, hyphenated)
-
----
-
-## Persona Validation
-
-### Field Separation
-
-- [ ] **role** contains ONLY knowledge/skills/capabilities (what agent does)
-- [ ] **identity** contains ONLY background/experience/context (who agent is)
-- [ ] **communication_style** contains ONLY verbal patterns (tone, voice, mannerisms)
-- [ ] **principles** contains operating philosophy and behavioral guidelines
-
-### Communication Style Purity
-
-- [ ] Does NOT contain: "ensures", "makes sure", "always", "never"
-- [ ] Does NOT contain identity words: "experienced", "expert who", "senior", "seasoned"
-- [ ] Does NOT contain philosophy words: "believes in", "focused on", "committed to"
-- [ ] Does NOT contain behavioral descriptions: "who does X", "that does Y"
-- [ ] Is 1-2 sentences describing HOW they talk
-- [ ] Reading aloud: sounds like describing someone's voice/speech pattern
-
----
-
-## Menu Validation
-
-### Required Fields
-
-- [ ] All menu items have `trigger` field
-- [ ] All menu items have `description` field
-- [ ] All menu items have handler: `action` (Simple agents don't use `exec`)
-
-### Trigger Format
-
-- [ ] Format: `XX or fuzzy match on command-name` (XX = 2-letter code)
-- [ ] Codes are unique within agent
-- [ ] No reserved codes used: MH, CH, PM, DA (auto-injected)
-
-### Description Format
-
-- [ ] Descriptions start with `[XX]` code
-- [ ] Code in description matches trigger code
-- [ ] Descriptions are clear and descriptive
-
-### Action Handler
-
-- [ ] If `action: '#prompt-id'`, corresponding prompt exists
-- [ ] If `action: 'inline text'`, instruction is complete and clear
-
----
-
-## Prompts Validation (if present)
-
-- [ ] Each prompt has `id` field
-- [ ] Each prompt has `content` field
-- [ ] Prompt IDs are unique within agent
-- [ ] Prompts use semantic XML tags: `<instructions>`, `<process>`, etc.
-
----
-
-## Simple Agent Specific
-
-- [ ] Single .agent.yaml file (no sidecar folder)
-- [ ] All content contained in YAML (no external file dependencies)
-- [ ] No `critical_actions` section (Expert only)
-- [ ] Total size under ~250 lines (unless justified)
-- [ ] Compare with reference: `commit-poet.agent.yaml`
-
----
-
-## Path Variables (if used)
-
-- [ ] Paths use `{project-root}` variable (not hardcoded relative paths)
-- [ ] No sidecar paths present (Simple agents don't have sidecars)
-
----
-
-## Quality Checks
-
-- [ ] No broken references or missing files
-- [ ] Indentation is consistent
-- [ ] Agent purpose is clear from reading persona
-- [ ] Agent name/title are descriptive
-- [ ] Icon emoji is appropriate
-
----
-
-## What the Compiler Adds (DO NOT validate presence)
-
-These are auto-injected, don't validate for them:
-- Frontmatter (`---name/description---`)
-- XML activation block
-- Menu items: MH (menu/help), CH (chat), PM (party-mode), DA (dismiss/exit)
-- Rules section
-
----
-
-## Common Issues
-
-### Issue: Communication Style Has Behaviors
-
-**Wrong:** "Experienced analyst who ensures all stakeholders are heard"
-
-**Fix:**
-- identity: "Senior analyst with 8+ years..."
-- communication_style: "Speaks like a treasure hunter"
-- principles: "Ensure all stakeholder voices heard"
-
-### Issue: Wrong Trigger Format
-
-**Wrong:** `trigger: analyze`
-
-**Fix:** `trigger: AN or fuzzy match on analyze`
-
-### Issue: Description Missing Code
-
-**Wrong:** `description: 'Analyze code'`
-
-**Fix:** `description: '[AC] Analyze code'`

src/modules/bmb/workflows/agent/data/understanding-agent-types.md

@@ -1,222 +0,0 @@
-# Understanding Agent Types: Simple VS Expert VS Module
-
-> **For the LLM running this workflow:** Load and review the example files referenced below when helping users choose an agent type.
-> - Simple examples: `{workflow_path}/data/reference/simple-examples/commit-poet.agent.yaml`
-> - Expert examples: `{workflow_path}/data/reference/expert-examples/journal-keeper/`
-> - Existing Module addition examples: `{workflow_path}/data/reference/module-examples/security-engineer.agent.yaml`
-
----
-
-## What ALL Agent Types Can Do
-
-All three types have equal capability. The difference is **architecture and integration**, NOT power.
-
-- Read, write, and update files
-- Execute commands and invoke tools
-- Load and use module variables
-- Optionally restrict file access (privacy/security)
-- Use core module features: party-mode, agent chat, advanced elicitation, brainstorming, document sharding
-
----
-
-## Quick Reference Decision Tree
-
-**Step 1: Single Agent or Multiple Agents?**
-
-```
-Multiple personas/roles OR multi-user OR mixed data scope?
-├── YES → Use BMAD Module Builder (create module with multiple agents)
-└── NO → Single Agent (continue below)
-```
-
-**Step 2: Memory Needs (for Single Agent)**
-
-```
-Need to remember things across sessions?
-├── YES → Expert Agent (sidecar with memory)
-└── NO → Simple Agent (all in one file)
-```
-
-**Step 3: Module Integration (applies to BOTH Simple and Expert)**
-
-```
-Extending an existing module (BMM/CIS/BMGD/OTHER)?
-├── YES → Module Agent (your Simple/Expert joins the module)
-└── NO → Standalone Agent (independent)
-```
-
-**Key Point:** Simple and Expert can each be either standalone OR module agents. Memory and module integration are independent decisions.
-
----
-
-## The Three Types
-
-### Simple Agent
-
-**Everything in one file. No external dependencies. No memory.**
-
-```
-agent-name.agent.yaml (~250 lines max)
-├── metadata
-├── persona
-├── prompts (inline, small)
-└── menu (triggers → #prompt-id or inline actions)
-```
-
-**Choose when:**
-- Single-purpose utility
-- Each session is independent (stateless)
-- All knowledge fits in the YAML
-- Menu handlers are 5-15 line prompts
-
-**Examples:**
-- Commit message helper (conventional commits)
-- Document formatter/validator
-- Joke/teller persona agent
-- Simple data transformation and analysis tools
-
-**Reference:** `./data/reference/simple-examples/commit-poet.agent.yaml`
-
----
-
-### Expert Agent
-
-**Sidecar folder with persistent memory, workflows, knowledge files.**
-
-```
-agent-name.agent.yaml
-└── agent-name-sidecar/
-    ├── memories.md           # User profile, session history, patterns
-    ├── instructions.md       # Protocols, boundaries, startup behavior
-    ├── [custom-files].md     # Breakthroughs, goals, tracking, etc.
-    ├── workflows/            # Large workflows loaded on demand
-    └── knowledge/            # Domain reference material
-```
-
-**Choose when:**
-- Must remember across sessions
-- User might create multiple instances each with own memory of actions (such as 2 different developers agents)
-- Personal knowledge base that grows
-- Learning/evolving over time
-- Domain-specific with restricted file access
-- Complex multi-step workflows
-
-**Examples:**
-- Journal companion (remembers mood patterns, past entries)
-- Personal job augmentation agent (knows your role, meetings, projects)
-- Therapy/health tracking (progress, goals, insights)
-- Domain advisor with custom knowledge base
-
-**Reference:** `./data/reference/expert-examples/journal-keeper/`
-
-**Required critical_actions:**
-```yaml
-critical_actions:
-  - "Load COMPLETE file ./sidecar/memories.md"
-  - "Load COMPLETE file ./sidecar/instructions.md"
-  - "ONLY read/write files in ./sidecar/ - private space"
-```
-
----
-
-### Module Agent
-
-Two distinct purposes:
-
-#### 1. Extend an Existing Module
-
-Add an agent to BMM, CIS, BMGD, or another existing module.
-
-**Choose when:**
-- Adding specialized capability to existing module ecosystem
-- Agent uses/contributes shared module workflows
-- Coordinates with other agents in the module
-- Input/output dependencies on other module agents
-
-**Example:** Adding `security-engineer.agent.yaml` to BMM (software dev module)
-- Requires architecture document from BMM architect agent
-- Contributes security review workflow to BMM
-- Coordinates with analyst, pm, architect, dev agents
-
-**Reference:** `./data/reference/module-examples/security-engineer.agent.yaml`
-
-#### 2. Signal Need for Custom Module
-
-When requirements exceed single-agent scope, suggest the user **use BMAD Module Builder** instead.
-
-**Signals:**
-- "I need an HR agent, sales agent, F&I agent, and training coach..."
-- "Some info is global/shared across users, some is private per user..."
-- "Many workflows, skills, tools, and platform integrations..."
-
-**Example:** Car Dealership Module
-- Multiple specialized agents (sales-trainer, service-advisor, sales-manager, F&I)
-- Shared workflows (VIN lookup, vehicle research)
-- Global knowledge base + per-user private sidecars
-- Multi-user access patterns
-
-**→ Use BMAD Module Builder workflow to create the module, then create individual agents within it.**
-
----
-
-## Side-by-Side Comparison
-
-| Aspect            | Simple                   | Expert                         |
-| ----------------- | ------------------------ | ------------------------------ |
-| File structure    | Single YAML (~250 lines) | YAML + sidecar/ (150+ + files) |
-| Persistent memory | No                       | Yes                            |
-| Custom workflows  | Inline prompts           | Sidecar workflows (on-demand)  |
-| File access       | Project/output           | Restricted domain              |
-| Integration       | Standalone OR Module     | Standalone OR Module           |
-
-**Note:** BOTH Simple and Expert can be either standalone agents OR module agents (extending BMM/CIS/BMGD/etc.). Module integration is independent of memory needs.
-
----
-
-## Selection Checklist
-
-**Choose Simple if:**
-- [ ] One clear purpose
-- [ ] No need to remember past sessions
-- [ ] All logic fits in ~250 lines
-- [ ] Each interaction is independent
-
-**Choose Expert if:**
-- [ ] Needs memory across sessions
-- [ ] Personal knowledge base
-- [ ] Domain-specific expertise
-- [ ] Restricted file access for privacy
-- [ ] Learning/evolving over time
-- [ ] Complex workflows in sidecar
-
-**Then, for EITHER Simple or Expert:**
-- [ ] Extending existing module (BMM/CIS/BMGD/etc.) → Make it a Module Agent
-- [ ] Independent operation → Keep it Standalone
-
-**Escalate to Module Builder if:**
-- [ ] Multiple distinct personas needed (not one swiss-army-knife agent)
-- [ ] Many specialized workflows required
-- [ ] Multiple users with mixed data scope
-- [ ] Shared resources across agents
-- [ ] Future platform integrations planned
-
----
-
-## Tips for the LLM Facilitator
-
-- If unsure between Simple or Expert → **recommend Expert** (more flexible)
-- Multiple personas/skills → **suggest Module Builder**, not one giant agent
-- Ask about: memory needs, user count, data scope (global vs private), integration plans
-- Load example files when user wants to see concrete implementations
-- Reference examples to illustrate differences
-
----
-
-## Architecture Notes
-
-All three types are equally powerful. The difference is:
-- **How they manage state** (memory vs stateless)
-- **Where they store data** (inline vs sidecar vs module)
-- **How they integrate** (standalone vs module ecosystem)
-
-Choose based on architecture needs, not capability limits.

src/modules/bmb/workflows/agent/steps-c/step-02-discovery.md

@@ -1,168 +0,0 @@
----
-name: 'step-02-discovery'
-description: 'Discover what user wants holistically'
-
-# File References
-nextStepFile: './step-03-type-metadata.md'
-agentPlan: '{bmb_creations_output_folder}/agent-plan-{agent_name}.md'
-brainstormContext: ../data/brainstorm-context.md
-
-# Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
----
-
-# STEP GOAL
-
-Conduct holistic discovery of what the user wants to create, documenting a comprehensive agent plan that serves as the single source of truth for all subsequent workflow steps. This is THE discovery moment - capture everything now so we don't re-ask later.
-
-# MANDATORY EXECUTION RULES
-
-1. **ONE-TIME DISCOVERY:** This is the only discovery step. Capture everything now.
-2. **PLAN IS SOURCE OF TRUTH:** Document to agentPlan file - all later steps reference this plan.
-3. **NO RE-ASKING:** Later steps MUST read from plan, not re-ask questions.
-4. **REFERENCE BRAINSTORM:** If brainstorming occurred in step-01, integrate those results.
-5. **STRUCTURED OUTPUT:** Plan must follow Purpose, Goals, Capabilities, Context, Users structure.
-6. **LANGUAGE ALIGNMENT:** Continue using {language} if configured in step-01.
-
-# EXECUTION PROTOCOLS
-
-## Protocol 1: Check for Previous Context
-
-Before starting discovery:
-- Check if brainstormContext file exists
-- If yes, read and reference those results
-- Integrate brainstorming insights into conversation naturally
-
-## Protocol 2: Discovery Conversation
-
-Guide the user through holistic discovery covering:
-
-1. **Purpose:** What problem does this agent solve? Why does it need to exist?
-2. **Goals:** What should this agent accomplish? What defines success?
-3. **Capabilities:** What specific abilities should it have? What tools/skills?
-4. **Context:** Where will it be used? What's the environment/setting?
-5. **Users:** Who will use this agent? What's their skill level?
-
-Use conversational exploration:
-- Ask open-ended questions
-- Probe deeper on important aspects
-- Validate understanding
-- Uncover implicit requirements
-
-## Protocol 3: Documentation
-
-Document findings to agentPlan file using this structure:
-
-```markdown
-# Agent Plan: {agent_name}
-
-## Purpose
-[Clear, concise statement of why this agent exists]
-
-## Goals
-- [Primary goal 1]
-- [Primary goal 2]
-- [Secondary goals as needed]
-
-## Capabilities
-- [Core capability 1]
-- [Core capability 2]
-- [Additional capabilities with tools/skills]
-
-## Context
-[Deployment environment, use cases, constraints]
-
-## Users
-- [Target audience description]
-- [Skill level assumptions]
-- [Usage patterns]
-```
-
-## Protocol 4: Completion Menu
-
-After documentation, present menu:
-
-**[A]dvanced Discovery** - Invoke advanced-elicitation task for deeper exploration
-**[P]arty Mode** - Invoke party-mode workflow for creative ideation
-**[C]ontinue** - Proceed to next step (type-metadata)
-
-# CONTEXT BOUNDARIES
-
-**DISCOVER:**
-- Agent purpose and problem domain
-- Success metrics and goals
-- Required capabilities and tools
-- Usage context and environment
-- Target users and skill levels
-
-**DO NOT DISCOVER:**
-- Technical implementation details (later steps)
-- Exact persona traits (next step)
-- Command structures (later step)
-- Name/branding (later step)
-- Validation criteria (later step)
-
-**KEEP IN SCOPE:**
-- Holistic understanding of what to build
-- Clear articulation of value proposition
-- Comprehensive capability mapping
-
-# EXECUTION SEQUENCE
-
-1. **Load Previous Context**
-   - Check for brainstormContext file
-   - Read if exists, note integration points
-
-2. **Start Discovery Conversation**
-   - Reference brainstorming results if available
-   - "Let's discover what you want to create..."
-   - Explore purpose, goals, capabilities, context, users
-
-3. **Document Plan**
-   - Create agentPlan file
-   - Structure with Purpose, Goals, Capabilities, Context, Users
-   - Ensure completeness and clarity
-
-4. **Present Completion Menu**
-   - Show [A]dvanced Discovery option
-   - Show [P]arty Mode option
-   - Show [C]ontinue to next step
-   - Await user selection
-
-5. **Handle Menu Choice**
-   - If A: Invoke advanced-elicitation task, then re-document
-   - If P: Invoke party-mode workflow, then re-document
-   - If C: Proceed to step-03-type-metadata
-
-# CRITICAL STEP COMPLETION NOTE
-
-**THIS STEP IS COMPLETE WHEN:**
-- agentPlan file exists with complete structure
-- All five sections (Purpose, Goals, Capabilities, Context, Users) populated
-- User confirms accuracy via menu selection
-- Either continuing to next step or invoking optional workflows
-
-**BEFORE PROCEEDING:**
-- Verify plan file is readable
-- Ensure content is sufficient for subsequent steps
-- Confirm user is satisfied with discoveries
-
-# SUCCESS METRICS
-
-**SUCCESS:**
-- agentPlan file created with all required sections
-- User has provided clear, actionable requirements
-- Plan contains sufficient detail for persona, commands, and name steps
-- User explicitly chooses to continue or invokes optional workflow
-
-**FAILURE:**
-- Unable to extract coherent purpose or goals
-- User cannot articulate basic requirements
-- Plan sections remain incomplete or vague
-- User requests restart
-
-**RECOVERY:**
-- If requirements unclear, use advanced-elicitation task
-- If user stuck, offer party-mode for creative exploration
-- If still unclear, suggest revisiting brainstorming step

src/modules/bmb/workflows/agent/steps-c/step-03-type-metadata.md

@@ -1,294 +0,0 @@
----
-name: 'step-02-type-metadata'
-description: 'Determine agent type and define metadata'
-
-# File References
-nextStepFile: './step-04-persona.md'
-agentPlan: '{bmb_creations_output_folder}/agent-plan-{agent_name}.md'
-agentTypesDoc: ../data/understanding-agent-types.md
-agentMetadata: ../data/agent-metadata.md
-
-# Example Agents (for reference)
-simpleExample: ../data/reference/simple-examples/commit-poet.agent.yaml
-expertExample: ../data/reference/expert-examples/journal-keeper/journal-keeper.agent.yaml
-moduleExample: ../data/reference/module-examples/security-engineer.agent.yaml
-
-# Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
----
-
-# STEP GOAL
-
-Determine the agent's classification (Simple/Expert/Module) and define all mandatory metadata properties required for agent configuration. Output structured YAML to the agent plan file for downstream consumption.
-
----
-
-# MANDATORY EXECUTION RULES
-
-## Universal Rules
-- ALWAYS use `{agent-language}` for all conversational text
-- MAINTAIN step boundaries - complete THIS step only
-- DOCUMENT all decisions to agent plan file
-- HONOR user's creative control throughout
-
-## Role Reinforcement
-You ARE a master agent architect guiding collaborative agent creation. Balance:
-- Technical precision in metadata definition
-- Creative exploration of agent possibilities
-- Clear documentation for downstream steps
-
-## Step-Specific Rules
-- LOAD and reference agentTypesDoc and agentMetadata before conversations
-- NEVER skip metadata properties - all are mandatory
-- VALIDATE type selection against user's articulated needs
-- OUTPUT structured YAML format exactly as specified
-- SHOW examples when type classification is unclear
-
----
-
-# EXECUTION PROTOCOLS
-
-## Protocol 1: Documentation Foundation
-Load reference materials first:
-1. Read agentTypesDoc for classification criteria
-2. Read agentMetadata for property definitions
-3. Keep examples ready for illustration
-
-## Protocol 2: Purpose Discovery
-Guide natural conversation to uncover:
-- Primary agent function/responsibility
-- Complexity level (single task vs multi-domain)
-- Scope boundaries (standalone vs manages workflows)
-- Integration needs (other agents/workflows)
-
-## Protocol 3: Type Determination
-Classify based on criteria:
-- **Simple**: Single focused purpose, minimal complexity (e.g., code reviewer, documentation generator)
-- **Expert**: Advanced domain expertise, multi-capability, manages complex tasks (e.g., game architect, system designer)
-- **Module**: Agent builder/manager, creates workflows, deploys other agents (e.g., agent-builder, workflow-builder)
-
-## Protocol 4: Metadata Definition
-Define each property systematically:
-- **id**: Technical identifier (lowercase, hyphens, no spaces)
-- **name**: Display name (conventional case, clear branding)
-- **title**: Concise function description (one line, action-oriented)
-- **icon**: Visual identifier (emoji or short symbol)
-- **module**: Module path (format: `{project}:{type}:{name}`)
-- **hasSidecar**: Boolean - manages external workflows? (default: false)
-
-## Protocol 5: Documentation Structure
-Output to agent plan file in exact YAML format:
-
-```yaml
-# Agent Type & Metadata
-agent_type: [Simple|Expert|Module]
-classification_rationale: |
-
-metadata:
-  id: [technical-identifier]
-  name: [Display Name]
-  title: [One-line action description]
-  icon: [emoji-or-symbol]
-  module: [project:type:name]
-  hasSidecar: [true|false]
-```
-
-## Protocol 6: Confirmation Menu
-Present structured options:
-- **[A] Accept** - Confirm and advance to next step
-- **[P] Pivot** - Modify type/metadata choices
-- **[C] Clarify** - Ask questions about classification
-
----
-
-# CONTEXT BOUNDARIES
-
-## In Scope
-- Agent type classification
-- All 6 metadata properties
-- Documentation to plan file
-- Type selection guidance with examples
-
-## Out of Scope (Future Steps)
-- Persona/character development (Step 3)
-- Command structure design (Step 4)
-- Agent naming/branding refinement (Step 5)
-- Implementation/build (Step 6)
-- Validation/testing (Step 7)
-
-## Red Flags to Address
-- User wants complex agent but selects "Simple" type
-- Module classification without workflow management needs
-- Missing or unclear metadata properties
-- Module path format confusion
-
----
-
-# INSTRUCTION SEQUENCE
-
-## 1. Load Documentation
-Read and internalize:
-- `{agentTypesDoc}` - Classification framework
-- `{agentMetadata}` - Property definitions
-- Keep examples accessible for reference
-
-## 2. Purpose Discovery Conversation
-Engage user with questions in `{agent-language}`:
-- "What is the primary function this agent will perform?"
-- "How complex are the tasks this agent will handle?"
-- "Will this agent need to manage workflows or other agents?"
-- "What specific domains or expertise areas are involved?"
-
-Listen for natural language cues about scope and complexity.
-
-## 3. Agent Type Determination
-Based on discovery, propose classification:
-- Present recommended type with reasoning
-- Show relevant example if helpful
-- Confirm classification matches user intent
-- Allow pivoting if user vision evolves
-
-**Conversation Template:**
-```
-Based on our discussion, I recommend classifying this as a [TYPE] agent because:
-[reasoning from discovery]
-
-[If helpful: "For reference, here's a similar [TYPE] agent:"]
-[Show relevant example path: simpleExample/expertExample/moduleExample]
-
-Does this classification feel right to you?
-```
-
-## 4. Define All Metadata Properties
-Work through each property systematically:
-
-**4a. Agent ID**
-- Technical identifier for file naming
-- Format: lowercase, hyphens, no spaces
-- Example: `code-reviewer`, `journal-keeper`, `security-engineer`
-- User confirms or modifies
-
-**4b. Agent Name**
-- Display name for branding/UX
-- Conventional case, memorable
-- Example: `Code Reviewer`, `Journal Keeper`, `Security Engineer`
-- May differ from id (kebab-case vs conventional case)
-
-**4c. Agent Title**
-- Concise action description
-- One line, captures primary function
-- Example: `Reviews code quality and test coverage`, `Manages daily journal entries`
-- Clear and descriptive
-
-**4d. Icon Selection**
-- Visual identifier for UI/branding
-- Emoji or short symbol
-- Example: `🔍`, `📓`, `🛡️`
-- Should reflect agent function
-
-**4e. Module Path**
-- Complete module identifier
-- Format: `{project}:{type}:{name}`
-- Example: `bmb:agents:code-reviewer`
-- Guide user through structure if unfamiliar
-
-**4f. Sidecar Configuration**
-- Boolean: manages external workflows?
-- Typically false for Simple/Expert agents
-- True for Module agents that deploy workflows
-- Confirm based on user's integration needs
-
-**Conversation Template:**
-```
-Now let's define each metadata property:
-
-**ID (technical identifier):** [proposed-id]
-**Name (display name):** [Proposed Name]
-**Title (function description):** [Action description for function]
-**Icon:** [emoji/symbol]
-**Module path:** [project:type:name]
-**Has Sidecar:** [true/false with brief explanation]
-
-[Show structured preview]
-
-Ready to confirm, or should we adjust any properties?
-```
-
-## 5. Document to Plan File
-Write to `{agentPlan}`:
-
-```yaml
-# Agent Type & Metadata
-agent_type: [Simple|Expert|Module]
-classification_rationale: |
-  [Clear explanation of why this type matches user's articulated needs]
-
-metadata:
-  id: [technical-identifier]
-  name: [Display Name]
-  title: [One-line action description]
-  icon: [emoji-or-symbol]
-  module: [project:type:name]
-  hasSidecar: [true|false]
-
-# Type Classification Notes
-type_decision_date: [YYYY-MM-DD]
-type_confidence: [High/Medium/Low]
-considered_alternatives: |
-  - [Alternative type]: [reason not chosen]
-  - [Alternative type]: [reason not chosen]
-```
-
-### 6. Present MENU OPTIONS
-
-Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue"
-
-#### Menu Handling Logic:
-
-- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu
-- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu
-- IF C: Save content to {agentPlan}, update frontmatter, then only then load, read entire file, then execute {nextStepFile}
-- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#6-present-menu-options)
-
-#### EXECUTION RULES:
-
-- ALWAYS halt and wait for user input after presenting menu
-- ONLY proceed to next step when user selects 'C'
-- After other menu items execution, return to this menu
-- User can chat or ask questions - always respond and then end with display again of the menu options
-
-## CRITICAL STEP COMPLETION NOTE
-
-ONLY WHEN [C continue option] is selected and [agent type classified and all 6 metadata properties defined and documented], will you then load and read fully `{nextStepFile}` to execute and begin persona development.
-
----
-
-# SYSTEM SUCCESS/FAILURE METRICS
-
-## Success Indicators
-- Type classification clearly justified
-- All metadata properties populated correctly
-- YAML structure matches specification exactly
-- User confirms understanding and acceptance
-- Agent plan file updated successfully
-
-## Failure Indicators
-- Missing or undefined metadata properties
-- YAML structure malformed
-- User confusion about type classification
-- Inadequate documentation to plan file
-- Proceeding without user confirmation
-
-## Recovery Mode
-If user struggles with classification:
-- Show concrete examples from each type
-- Compare/contrast types with their use case
-- Ask targeted questions about complexity/scope
-- Offer type recommendation with clear reasoning
-
-Recover metadata definition issues by:
-- Showing property format examples
-- Explaining technical vs display naming
-- Clarifying module path structure
-- Defining sidecar use cases

src/modules/bmb/workflows/agent/steps-c/step-04-persona.md

@@ -1,210 +0,0 @@
----
-name: 'step-03-persona'
-description: 'Shape the agent personality through four-field persona system'
-
-# File References
-nextStepFile: './step-05-commands-menu.md'
-agentPlan: '{bmb_creations_output_folder}/agent-plan-{agent_name}.md'
-personaProperties: ../data/persona-properties.md
-principlesCrafting: ../data/principles-crafting.md
-communicationPresets: ../data/communication-presets.csv
-
-# Example Personas (for reference)
-simpleExample: ../data/reference/simple-examples/commit-poet.agent.yaml
-expertExample: ../data/reference/expert-examples/journal-keeper/journal-keeper.agent.yaml
-
-# Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
----
-
-# STEP GOAL
-
-Develop a complete four-field persona that defines the agent's personality, expertise, communication approach, and guiding principles. This persona becomes the foundation for how the agent thinks, speaks, and makes decisions.
-
-# MANDATORY EXECUTION RULES
-
-**CRITICAL: Field Purity Enforcement**
-- Each persona field has ONE specific purpose
-- NO mixing concepts between fields
-- NO overlapping responsibilities
-- Every field must be distinct and non-redundant
-
-**Output Requirements:**
-- Produce structured YAML block ready for agent.yaml
-- Follow principles-crafting guidance exactly
-- First principle MUST be the "expert activator"
-- All fields must be populated before proceeding
-
-# EXECUTION PROTOCOLS
-
-## Protocol 1: Load Reference Materials
-
-Read and integrate:
-- `personaProperties.md` - Field definitions and boundaries
-- `principlesCrafting.md` - Principles composition guidance
-- `communicationPresets.csv` - Style options and templates
-- Reference examples for pattern recognition
-
-## Protocol 2: Four-Field System Education
-
-Explain each field clearly:
-
-**1. Role (WHAT they do)**
-- Professional identity and expertise domain
-- Capabilities and knowledge areas
-- NOT personality or communication style
-- Pure functional definition
-
-**2. Identity (WHO they are)**
-- Character, personality, attitude
-- Emotional intelligence and worldview
-- NOT job description or communication format
-- Pure personality definition
-
-**3. Communication Style (HOW they speak)**
-- Language patterns, tone, voice
-- Formality, verbosity, linguistic preferences
-- NOT expertise or personality traits
-- Pure expression definition
-
-**4. Principles (WHY they act)**
-- Decision-making framework and values
-- Behavioral constraints and priorities
-- First principle = expert activator (core mission)
-- Pure ethical/operational definition
-
-## Protocol 3: Progressive Field Development
-
-### 3.1 Role Development
-- Define primary expertise domain
-- Specify capabilities and knowledge areas
-- Identify what makes them an "expert"
-- Keep it functional, not personal
-
-**Role Quality Checks:**
-- Can I describe their job without personality?
-- Would this fit in a job description?
-- Is it purely about WHAT they do?
-
-### 3.2 Identity Development
-- Define personality type and character
-- Establish emotional approach
-- Set worldview and attitude
-- Keep it personal, not functional
-
-**Identity Quality Checks:**
-- Can I describe their character without job title?
-- Would this fit in a character profile?
-- Is it purely about WHO they are?
-
-### 3.3 Communication Style Development
-- Review preset options from CSV
-- Select or customize style pattern
-- Define tone, formality, voice
-- Set linguistic preferences
-
-**Communication Quality Checks:**
-- Can I describe their speech patterns without expertise?
-- Is it purely about HOW they express themselves?
-- Would this fit in a voice acting script?
-
-### 3.4 Principles Development
-Follow `principlesCrafting.md` guidance:
-1. **Principle 1: Expert Activator** - Core mission and primary directive
-2. **Principle 2-5: Decision Framework** - Values that guide choices
-3. **Principle 6+: Behavioral Constraints** - Operational boundaries
-
-**Principles Quality Checks:**
-- Does first principle activate expertise immediately?
-- Do principles create decision-making clarity?
-- Would following these produce the desired behavior?
-
-## Protocol 4: Structured YAML Generation
-
-Output the four-field persona in this exact format:
-
-```yaml
-role: >
-  [Single sentence defining expertise and capabilities]
-
-identity: >
-  [2-3 sentences describing personality and character]
-
-communication_style: >
-  [Specific patterns for tone, formality, and voice]
-
-principles:
-  - [Expert activator - core mission]
-  - [Decision framework value 1]
-  - [Decision framework value 2]
-  - [Behavioral constraint 1]
-  - [Behavioral constraint 2]
-```
-
-# CONTEXT BOUNDARIES
-
-**Include in Persona:**
-- Professional expertise and capabilities (role)
-- Personality traits and character (identity)
-- Language patterns and tone (communication)
-- Decision-making values (principles)
-
-**Exclude from Persona:**
-- Technical skills (belongs in knowledge)
-- Tool usage (belongs in commands)
-- Workflow steps (belongs in orchestration)
-- Data structures (belongs in implementation)
-
-# EXECUTION SEQUENCE
-
-1. **LOAD** personaProperties.md and principlesCrafting.md
-2. **EXPLAIN** four-field system with clear examples
-3. **DEVELOP** Role - define expertise domain and capabilities
-4. **DEVELOP** Identity - establish personality and character
-5. **DEVELOP** Communication Style - select/customize style preset
-6. **DEVELOP** Principles - craft 5-7 principles following guidance
-7. **OUTPUT** structured YAML block for agent.yaml
-8. **DOCUMENT** to agent-plan.md
-9. **PRESENT** completion menu
-
-## 9. Present MENU OPTIONS
-
-Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue"
-
-### Menu Handling Logic:
-
-- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu
-- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu
-- IF C: Save content to {agentPlan}, update frontmatter, then only then load, read entire file, then execute {nextStepFile}
-- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#9-present-menu-options)
-
-### EXECUTION RULES:
-
-- ALWAYS halt and wait for user input after presenting menu
-- ONLY proceed to next step when user selects 'C'
-- After other menu items execution, return to this menu
-- User can chat or ask questions - always respond and then end with display again of the menu options
-
-## CRITICAL STEP COMPLETION NOTE
-
-ONLY WHEN [C continue option] is selected and [all four persona fields populated with DISTINCT content and field purity verified], will you then load and read fully `{nextStepFile}` to execute and begin command structure design.
-
----
-
-# SUCCESS METRICS
-
-**Completion Indicators:**
-- Four distinct, non-overlapping persona fields
-- First principle activates expert capabilities
-- Communication style is specific and actionable
-- YAML structure is valid and ready for agent.yaml
-- User confirms persona accurately reflects vision
-
-**Failure Indicators:**
-- Role includes personality traits
-- Identity includes job descriptions
-- Communication includes expertise details
-- Principles lack expert activator
-- Fields overlap or repeat concepts
-- User expresses confusion or disagreement

src/modules/bmb/workflows/agent/steps-c/step-05-commands-menu.md

@@ -1,176 +0,0 @@
----
-name: 'step-04-commands-menu'
-description: 'Build capabilities and command structure'
-
-# File References
-nextStepFile: './step-06-activation.md'
-agentPlan: '{bmb_creations_output_folder}/agent-plan-{agent_name}.md'
-agentMenuPatterns: ../data/agent-menu-patterns.md
-
-# Example Menus (for reference)
-simpleExample: ../data/reference/simple-examples/commit-poet.agent.yaml
-expertExample: ../data/reference/expert-examples/journal-keeper/journal-keeper.agent.yaml
-
-# Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
----
-
-# STEP GOAL
-
-Transform discovered capabilities into structured menu commands following BMAD menu patterns, creating the agent's interaction interface.
-
-# MANDATORY EXECUTION RULES
-
-1. **MUST** load agent-menu-patterns.md before any conversation
-2. **MUST** use menu patterns as structural templates
-3. **MUST** keep final menu YAML under 100 lines
-4. **MUST** include trigger, description, and handler/action for each command
-5. **MUST NOT** add help or exit commands (auto-injected)
-6. **MUST** document menu YAML in agent-plan before completion
-7. **MUST** complete Menu [A][P][C] verification
-
-# EXECUTION PROTOCOLS
-
-## Load Menu Patterns
-
-Read agentMenuPatterns file to understand:
-- Command structure requirements
-- YAML formatting standards
-- Handler/action patterns
-- Best practices for menu design
-
-## Capability Discovery Conversation
-
-Guide collaborative conversation to:
-1. Review capabilities from previous step
-2. Identify which capabilities become commands
-3. Group related capabilities
-4. Define command scope and boundaries
-
-Ask targeted questions:
-- "Which capabilities are primary commands vs secondary actions?"
-- "Can related capabilities be grouped under single commands?"
-- "What should each command accomplish?"
-- "How should commands be triggered?"
-
-## Command Structure Development
-
-For each command, define:
-
-1. **Trigger** - User-facing command name
-   - Clear, intuitive, following naming conventions
-   - Examples: `/analyze`, `/create`, `/review`
-
-2. **Description** - What the command does
-   - Concise (one line preferred)
-   - Clear value proposition
-   - Examples: "Analyze code for issues", "Create new document"
-
-3. **Handler/Action** - How command executes
-   - Reference to specific capability or skill
-   - Include parameters if needed
-   - Follow pattern from agent-menu-patterns.md
-
-## Structure Best Practices
-
-- **Group related commands** logically
-- **Prioritize frequently used** commands early
-- **Use clear, action-oriented** trigger names
-- **Keep descriptions** concise and valuable
-- **Match handler names** to actual capabilities
-
-## Document Menu YAML
-
-Create structured menu YAML following format from agent-menu-patterns.md:
-
-```yaml
-menu:
-  commands:
-    - trigger: "/command-name"
-      description: "Clear description of what command does"
-      handler: "specific_capability_or_skill"
-      parameters:
-        - name: "param_name"
-          description: "Parameter description"
-          required: true/false
-```
-
-## Menu [A][P][C] Verification
-
-**[A]ccuracy**
-- All commands match defined capabilities
-- Triggers are clear and intuitive
-- Handlers reference actual capabilities
-
-**[P]attern Compliance**
-- Follows agent-menu-patterns.md structure
-- YAML formatting is correct
-- No help/exit commands included
-
-**[C]ompleteness**
-- All primary capabilities have commands
-- Commands cover agent's core functions
-- Menu is ready for next step
-
-# CONTEXT BOUNDARIES
-
-- **Focus on command structure**, not implementation details
-- **Reference example menus** for patterns, not copying
-- **Keep menu concise** - better fewer, clearer commands
-- **User-facing perspective** - triggers should feel natural
-- **Capability alignment** - every command maps to a capability
-
-# EXECUTION SEQUENCE
-
-1. Load agent-menu-patterns.md to understand structure
-2. Review capabilities from agent-plan step 3
-3. Facilitate capability-to-command mapping conversation
-4. Develop command structure for each capability
-5. Define trigger, description, handler for each command
-6. Verify no help/exit commands (auto-injected)
-7. Document structured menu YAML to agent-plan
-8. Complete Menu [A][P][C] verification
-9. Confirm readiness for next step
-
-## 10. Present MENU OPTIONS
-
-Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue"
-
-### Menu Handling Logic:
-
-- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu
-- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu
-- IF C: Save content to {agentPlan}, update frontmatter, then only then load, read entire file, then execute {nextStepFile}
-- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#10-present-menu-options)
-
-### EXECUTION RULES:
-
-- ALWAYS halt and wait for user input after presenting menu
-- ONLY proceed to next step when user selects 'C'
-- After other menu items execution, return to this menu
-- User can chat or ask questions - always respond and then end with display again of the menu options
-
-## CRITICAL STEP COMPLETION NOTE
-
-ONLY WHEN [C continue option] is selected and [menu YAML documented in agent-plan and all commands have trigger/description/handler], will you then load and read fully `{nextStepFile}` to execute and begin activation planning.
-
----
-
-# SUCCESS METRICS
-
-✅ Menu YAML documented in agent-plan
-✅ All commands have trigger, description, handler
-✅ Menu follows agent-menu-patterns.md structure
-✅ No help/exit commands included
-✅ Menu [A][P][C] verification passed
-✅ Ready for activation phase
-
-# FAILURE INDICATORS
-
-❌ Menu YAML missing from agent-plan
-❌ Commands missing required elements (trigger/description/handler)
-❌ Menu doesn't follow pattern structure
-❌ Help/exit commands manually added
-❌ Menu [A][P][C] verification failed
-❌ Unclear command triggers or descriptions

src/modules/bmb/workflows/agent/steps-c/step-06-activation.md

@@ -1,275 +0,0 @@
----
-name: 'step-05-activation'
-description: 'Plan activation behavior and route to build'
-
-# File References
-agentPlan: '{bmb_creations_output_folder}/agent-plan-{agent_name}.md'
-criticalActions: ../data/critical-actions.md
-
-# Build Step Routes (determined by agent type)
-simpleBuild: './step-07a-build-simple.md'
-expertBuild: './step-07b-build-expert.md'
-moduleBuild: './step-07c-build-module.md'
-
-# Example critical_actions (for reference)
-expertExample: ../data/reference/expert-examples/journal-keeper/journal-keeper.agent.yaml
-
-# Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
----
-
-# STEP GOAL
-Define activation behavior through critical_actions and route to the appropriate build step based on agent complexity.
-
-# MANDATORY EXECUTION RULES
-
-1. **MUST Load Reference Documents** Before any discussion
-   - Read criticalActions.md to understand activation patterns
-   - Read agentPlan to access all accumulated metadata
-   - These are non-negotiable prerequisites
-
-2. **MUST Determine Route Before Activation Discussion**
-   - Check hasSidecar from plan metadata
-   - Determine destination build step FIRST
-   - Inform user of routing decision
-
-3. **MUST Document Activation Decision**
-   - Either define critical_actions array explicitly
-   - OR document deliberate omission with rationale
-   - No middle ground - commit to one path
-
-4. **MUST Follow Routing Logic Exactly**
-   ```yaml
-   # Route determination based on hasSidecar and module
-   hasSidecar: false → step-06-build-simple.md
-   hasSidecar: true + module: "stand-alone" → step-06-build-expert.md
-   hasSidecar: true + module: ≠ "stand-alone" → step-06-build-module.md
-   ```
-
-5. **NEVER Skip Documentation**
-   - Every decision about activation must be recorded
-   - Every routing choice must be justified
-   - Plan file must reflect final state
-
-# EXECUTION PROTOCOLS
-
-## Protocol 1: Reference Loading
-Execute BEFORE engaging user:
-
-1. Load criticalActions.md
-2. Load agentPlan-{agent_name}.md
-3. Extract routing metadata:
-   - hasSidecar (boolean)
-   - module (string)
-   - agentType (if defined)
-4. Determine destination build step
-
-## Protocol 2: Routing Disclosure
-Inform user immediately of determined route:
-
-```
-"Based on your agent configuration:
-- hasSidecar: {hasSidecar}
-- module: {module}
-
-→ Routing to: {destinationStep}
-
-Now let's plan your activation behavior..."
-```
-
-## Protocol 3: Activation Planning
-Guide user through decision:
-
-1. **Explain critical_actions Purpose**
-   - What they are: autonomous triggers the agent can execute
-   - When they're useful: proactive capabilities, workflows, utilities
-   - When they're unnecessary: simple assistants, pure responders
-
-2. **Discuss Agent's Activation Needs**
-   - Does this agent need to run independently?
-   - Should it initiate actions without prompts?
-   - What workflows or capabilities should it trigger?
-
-3. **Decision Point**
-   - Define specific critical_actions if needed
-   - OR explicitly opt-out with rationale
-
-## Protocol 4: Documentation
-Update agentPlan with activation metadata:
-
-```yaml
-# Add to agent metadata
-activation:
-  hasCriticalActions: true/false
-  rationale: "Explanation of why or why not"
-  criticalActions: []  # Only if hasCriticalActions: true
-routing:
-  destinationBuild: "step-06-{X}.md"
-  hasSidecar: {boolean}
-  module: "{module}"
-```
-
-# CONTEXT BOUNDARIES
-
-## In Scope
-- Planning activation behavior for the agent
-- Defining critical_actions array
-- Routing to appropriate build step
-- Documenting activation decisions
-
-## Out of Scope
-- Writing actual activation code (build step)
-- Designing sidecar workflows (build step)
-- Changing core agent metadata (locked after step 04)
-- Implementing commands (build step)
-
-## Routing Boundaries
-- Simple agents: No sidecar, straightforward activation
-- Expert agents: Sidecar + stand-alone module
-- Module agents: Sidecar + parent module integration
-
-# EXECUTION SEQUENCE
-
-## 1. Load Reference Documents
-```bash
-# Read these files FIRST
-cat {criticalActions}
-cat {agentPlan}
-```
-
-## 2. Discuss Activation Needs
-Ask user:
-- "Should your agent be able to take autonomous actions?"
-- "Are there specific workflows it should trigger?"
-- "Should it run as a background process or scheduled task?"
-- "Or will it primarily respond to direct prompts?"
-
-## 3. Define critical_actions OR Explicitly Omit
-
-**If defining:**
-- Reference criticalActions.md patterns
-- List 3-7 specific actions
-- Each action should be clear and scoped
-- Document rationale for each
-
-**If omitting:**
-- State clearly: "This agent will not have critical_actions"
-- Explain why: "This agent is a responsive assistant that operates under direct user guidance"
-- Document the rationale
-
-## 4. Route to Build Step
-
-Determine destination:
-
-```yaml
-# Check plan metadata
-hasSidecar: {value from step 04}
-module: "{value from step 04}"
-
-# Route logic
-if hasSidecar == false:
-  destination = simpleBuild
-elif hasSidecar == true and module == "stand-alone":
-  destination = expertBuild
-else:  # hasSidecar == true and module != "stand-alone"
-  destination = moduleBuild
-```
-
-## 5. Document to Plan
-
-Update agentPlan with:
-
-```yaml
----
-activation:
-  hasCriticalActions: true
-  rationale: "Agent needs to autonomously trigger workflows for task automation"
-  criticalActions:
-    - name: "start-workflow"
-      description: "Initiate a predefined workflow for task execution"
-    - name: "schedule-task"
-      description: "Schedule tasks for future execution"
-    - name: "sync-data"
-      description: "Synchronize data with external systems"
-
-routing:
-  destinationBuild: "step-06-build-expert.md"
-  hasSidecar: true
-  module: "stand-alone"
-  rationale: "Agent requires sidecar workflows for autonomous operation"
----
-```
-
-### 6. Present MENU OPTIONS
-
-Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue"
-
-#### Menu Handling Logic:
-
-- IF A: Execute {advancedElicitationTask}, and when finished redisplay the menu
-- IF P: Execute {partyModeWorkflow}, and when finished redisplay the menu
-- IF C: Save content to {agentPlan}, update frontmatter, determine appropriate build step based on hasSidecar and module values, then only then load, read entire file, then execute {simpleBuild} or {expertBuild} or {moduleBuild} as determined
-- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#6-present-menu-options)
-
-#### EXECUTION RULES:
-
-- ALWAYS halt and wait for user input after presenting menu
-- ONLY proceed to next step when user selects 'C'
-- After other menu items execution, return to this menu
-- User can chat or ask questions - always respond and then end with display again of the menu options
-
-## CRITICAL STEP COMPLETION NOTE
-
-This is the **ROUTING HUB** of agent creation. ONLY WHEN [C continue option] is selected and [routing decision determined with activation needs documented], will you then determine the appropriate build step based on hasSidecar/module values and load and read fully that build step file to execute.
-
-Routing logic:
-- hasSidecar: false → step-06-build-simple.md
-- hasSidecar: true + module: "stand-alone" → step-06-build-expert.md
-- hasSidecar: true + module: ≠ "stand-alone" → step-06-build-module.md
-
-You cannot proceed to build without completing routing.
-
----
-
-# SUCCESS METRICS
-
-✅ **COMPLETION CRITERIA:**
-- [ ] criticalActions.md loaded and understood
-- [ ] agentPlan loaded with all prior metadata
-- [ ] Routing decision determined and communicated
-- [ ] Activation needs discussed with user
-- [ ] critical_actions defined OR explicitly omitted with rationale
-- [ ] Plan updated with activation and routing metadata
-- [ ] User confirms routing to appropriate build step
-
-✅ **SUCCESS INDICATORS:**
-- Clear activation decision documented
-- Route to build step is unambiguous
-- User understands why they're going to {simple|expert|module} build
-- Plan file reflects complete activation configuration
-
-❌ **FAILURE MODES:**
-- Attempting to define critical_actions without reading reference
-- Routing decision not documented in plan
-- User doesn't understand which build step comes next
-- Ambiguous activation configuration (neither defined nor omitted)
-- Skipping routing discussion entirely
-
-⚠️ **RECOVERY PATHS:**
-If activation planning goes wrong:
-
-1. **Can't decide on activation?**
-   - Default: Omit critical_actions
-   - Route to simpleBuild
-   - Can add later via edit-agent workflow
-
-2. **Uncertain about routing?**
-   - Check hasSidecar value
-   - Check module value
-   - Apply routing logic strictly
-
-3. **User wants to change route?**
-   - Adjust hasSidecar or module values
-   - Re-run routing logic
-   - Update plan accordingly