bmad-fh 6.0.0-alpha.052779ef

package/docs/how-to/customization/customize-agents.md

@@ -0,0 +1,212 @@
+---
+title: "Agent Customization Guide"
+---
+
+Use `.customize.yaml` files to customize BMad agents without modifying core files. All customizations persist through updates.
+
+## When to Use This
+
+- Change agent names or personas
+- Add project-specific memories or context
+- Add custom menu items and workflows
+- Define critical actions for consistent behavior
+
+## Quick Start
+
+**1. Locate Customization Files**
+
+After installation, find agent customization files in:
+
+```
+_bmad/_config/agents/
+├── core-bmad-master.customize.yaml
+├── bmm-dev.customize.yaml
+├── bmm-pm.customize.yaml
+└── ... (one file per installed agent)
+```
+
+**2. Edit Any Agent**
+
+Open the `.customize.yaml` file for the agent you want to modify. All sections are optional - customize only what you need.
+
+**3. Rebuild the Agent**
+
+After editing, IT IS CRITICAL to rebuild the agent to apply changes:
+
+```bash
+npx bmad-method@alpha install # and then select option to compile all agents
+npx bmad-method@alpha build <agent-name>
+
+npx bmad-method@alpha build bmm-dev
+npx bmad-method@alpha build core-bmad-master
+npx bmad-method@alpha build bmm-pm
+```
+
+## What You Can Customize
+
+### Agent Name
+
+Change how the agent introduces itself:
+
+```yaml
+agent:
+  metadata:
+    name: 'Spongebob' # Default: "Amelia"
+```
+
+### Persona
+
+Replace the agent's personality, role, and communication style:
+
+```yaml
+persona:
+  role: 'Senior Full-Stack Engineer'
+  identity: 'Lives in a pineapple (under the sea)'
+  communication_style: 'Spongebob'
+  principles:
+    - 'Never Nester, Spongebob Devs hate nesting more than 2 levels deep'
+    - 'Favor composition over inheritance'
+```
+
+**Note:** The persona section replaces the entire default persona (not merged).
+
+### Memories
+
+Add persistent context the agent will always remember:
+
+```yaml
+memories:
+  - 'Works at Krusty Krab'
+  - 'Favorite Celebrity: David Hasslehoff'
+  - 'Learned in Epic 1 that its not cool to just pretend that tests have passed'
+```
+
+### Custom Menu Items
+
+Add your own workflows to the agent's menu:
+
+```yaml
+menu:
+  - trigger: my-workflow
+    workflow: '{project-root}/my-custom/workflows/my-workflow.yaml'
+    description: My custom workflow
+  - trigger: deploy
+    action: '#deploy-prompt'
+    description: Deploy to production
+```
+
+**Don't include:** `*` prefix or `help`/`exit` items - these are auto-injected.
+
+### Critical Actions
+
+Add instructions that execute before the agent starts:
+
+```yaml
+critical_actions:
+  - 'Always check git status before making changes'
+  - 'Use conventional commit messages'
+```
+
+### Custom Prompts
+
+Define reusable prompts for `action="#id"` menu handlers:
+
+```yaml
+prompts:
+  - id: deploy-prompt
+    content: |
+      Deploy the current branch to production:
+      1. Run all tests
+      2. Build the project
+      3. Execute deployment script
+```
+
+## Real-World Examples
+
+**Example 1: Customize Developer Agent for TDD**
+
+```yaml
+agent:
+  metadata:
+    name: 'TDD Developer'
+
+memories:
+  - 'Always write tests before implementation'
+  - 'Project uses Jest and React Testing Library'
+
+critical_actions:
+  - 'Review test coverage before committing'
+```
+
+**Example 2: Add Custom Deployment Workflow**
+
+```yaml
+menu:
+  - trigger: deploy-staging
+    workflow: '{project-root}/_bmad/deploy-staging.yaml'
+    description: Deploy to staging environment
+  - trigger: deploy-prod
+    workflow: '{project-root}/_bmad/deploy-prod.yaml'
+    description: Deploy to production (with approval)
+```
+
+**Example 3: Multilingual Product Manager**
+
+```yaml
+persona:
+  role: 'Bilingual Product Manager'
+  identity: 'Expert in US and LATAM markets'
+  communication_style: 'Clear, strategic, with cultural awareness'
+  principles:
+    - 'Consider localization from day one'
+    - 'Balance business goals with user needs'
+
+memories:
+  - 'User speaks English and Spanish'
+  - 'Target markets: US and Latin America'
+```
+
+## Tips
+
+- **Start Small:** Customize one section at a time and rebuild to test
+- **Backup:** Copy customization files before major changes
+- **Update-Safe:** Your customizations in `_config/` survive all BMad updates
+- **Per-Project:** Customization files are per-project, not global
+- **Version Control:** Consider committing `_config/` to share customizations with your team
+
+## Module vs. Global Config
+
+**Module-Level (Recommended):**
+
+- Customize agents per-project in `_bmad/_config/agents/`
+- Different projects can have different agent behaviors
+
+**Global Config (Coming Soon):**
+
+- Set defaults that apply across all projects
+- Override with project-specific customizations
+
+## Troubleshooting
+
+**Changes not appearing?**
+
+- Make sure you ran `npx bmad-method build <agent-name>` after editing
+- Check YAML syntax is valid (indentation matters!)
+- Verify the agent name matches the file name pattern
+
+**Agent not loading?**
+
+- Check for YAML syntax errors
+- Ensure required fields aren't left empty if you uncommented them
+- Try reverting to the template and rebuilding
+
+**Need to reset?**
+
+- Delete the `.customize.yaml` file
+- Run `npx bmad-method build <agent-name>` to regenerate defaults
+
+## Next Steps
+
+- **[Learn about Agents](/docs/explanation/core-concepts/what-are-agents.md)** - Understand Simple vs Expert agents
+- **[Agent Creation Guide](https://github.com/bmad-code-org/bmad-builder/blob/main/docs/tutorials/create-custom-agent.md)** - Build completely custom agents
+- **[BMM Complete Documentation](/docs/explanation/bmm/index.md)** - Full BMad Method reference

package/docs/how-to/customization/enable-tea-mcp-enhancements.md

@@ -0,0 +1,424 @@
+---
+title: "Enable TEA MCP Enhancements"
+description: Configure Playwright MCP servers for live browser verification during TEA workflows
+---
+
+# Enable TEA MCP Enhancements
+
+Configure Model Context Protocol (MCP) servers to enable live browser verification, exploratory mode, and recording mode in TEA workflows.
+
+## What are MCP Enhancements?
+
+MCP (Model Context Protocol) servers enable AI agents to interact with live browsers during test generation. This allows TEA to:
+
+- **Explore UIs interactively** - Discover actual functionality through browser automation
+- **Verify selectors** - Generate accurate locators from real DOM
+- **Validate behavior** - Confirm test scenarios against live applications
+- **Debug visually** - Use trace viewer and screenshots during generation
+
+## When to Use This
+
+**For UI Testing:**
+- Want exploratory mode in `*test-design` (browser-based UI discovery)
+- Want recording mode in `*atdd` or `*automate` (verify selectors with live browser)
+- Want healing mode in `*automate` (fix tests with visual debugging)
+- Need accurate selectors from actual DOM
+- Debugging complex UI interactions
+
+**For API Testing:**
+- Want healing mode in `*automate` (analyze failures with trace data)
+- Need to debug test failures (network responses, request/response data, timing)
+- Want to inspect trace files (network traffic, errors, race conditions)
+
+**For Both:**
+- Visual debugging (trace viewer shows network + UI)
+- Test failure analysis (MCP can run tests and extract errors)
+- Understanding complex test failures (network + DOM together)
+
+**Don't use if:**
+- You don't have MCP servers configured
+
+## Prerequisites
+
+- BMad Method installed
+- TEA agent available
+- IDE with MCP support (Cursor, VS Code with Claude extension)
+- Node.js v18 or later
+- Playwright installed
+
+## Available MCP Servers
+
+**Two Playwright MCP servers** (actively maintained, continuously updated):
+
+### 1. Playwright MCP - Browser Automation
+
+**Command:** `npx @playwright/mcp@latest`
+
+**Capabilities:**
+- Navigate to URLs
+- Click elements
+- Fill forms
+- Take screenshots
+- Extract DOM information
+
+**Best for:** Exploratory mode, recording mode
+
+### 2. Playwright Test MCP - Test Runner
+
+**Command:** `npx playwright run-test-mcp-server`
+
+**Capabilities:**
+- Run test files
+- Analyze failures
+- Extract error messages
+- Show trace files
+
+**Best for:** Healing mode, debugging
+
+### Recommended: Configure Both
+
+Both servers work together to provide full TEA MCP capabilities.
+
+## Setup
+
+### 1. Configure MCP Servers
+
+Add to your IDE's MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["@playwright/mcp@latest"]
+    },
+    "playwright-test": {
+      "command": "npx",
+      "args": ["playwright", "run-test-mcp-server"]
+    }
+  }
+}
+```
+
+See [TEA Overview](/docs/explanation/features/tea-overview.md#playwright-mcp-enhancements) for IDE-specific config locations.
+
+### 2. Enable in BMAD
+
+Answer "Yes" when prompted during installation, or set in config:
+
+```yaml
+# _bmad/bmm/config.yaml
+tea_use_mcp_enhancements: true
+```
+
+### 3. Verify MCPs Running
+
+Ensure your MCP servers are running in your IDE.
+
+## How MCP Enhances TEA Workflows
+
+### *test-design: Exploratory Mode
+
+**Without MCP:**
+- TEA infers UI functionality from documentation
+- Relies on your description of features
+- May miss actual UI behavior
+
+**With MCP:**
+TEA can open live browser to:
+```
+"Let me explore the profile page to understand the UI"
+
+[TEA navigates to /profile]
+[Takes screenshot]
+[Extracts accessible elements]
+
+"I see the profile has:
+- Name field (editable)
+- Email field (editable)
+- Avatar upload button
+- Save button
+- Cancel button
+
+I'll design tests for these interactions."
+```
+
+**Benefits:**
+- Accurate test design based on actual UI
+- Discovers functionality you might not describe
+- Validates test scenarios are possible
+
+### *atdd: Recording Mode
+
+**Without MCP:**
+- TEA generates selectors from best practices
+- TEA infers API patterns from documentation
+
+**With MCP (Recording Mode):**
+
+**For UI Tests:**
+```
+[TEA navigates to /login with live browser]
+[Inspects actual form fields]
+
+"I see:
+- Email input has label 'Email Address' (not 'Email')
+- Password input has label 'Your Password'
+- Submit button has text 'Sign In' (not 'Login')
+
+I'll use these exact selectors."
+```
+
+**For API Tests:**
+```
+[TEA analyzes trace files from test runs]
+[Inspects network requests/responses]
+
+"I see the API returns:
+- POST /api/login → 200 with { token, userId }
+- Response time: 150ms
+- Required headers: Content-Type, Authorization
+
+I'll validate these in tests."
+```
+
+**Benefits:**
+- UI: Accurate selectors from real DOM
+- API: Validated request/response patterns from trace
+- Both: Tests work on first run
+
+### *automate: Healing + Recording Modes
+
+**Without MCP:**
+- TEA analyzes test code only
+- Suggests fixes based on static analysis
+- Generates tests from documentation/code
+
+**With MCP:**
+
+**Healing Mode (UI + API):**
+```
+[TEA opens trace file]
+[Analyzes screenshots + network tab]
+
+UI failures: "Button selector changed from 'Save' to 'Save Changes'"
+API failures: "Response structure changed, expected {id} got {userId}"
+
+[TEA makes fixes]
+[Verifies with trace analysis]
+```
+
+**Recording Mode (UI + API):**
+```
+UI: [Inspects actual DOM, generates verified selectors]
+API: [Analyzes network traffic, validates request/response patterns]
+
+[Generates tests with verified patterns]
+[Tests work on first run]
+```
+
+**Benefits:**
+- Visual debugging + trace analysis (not just UI)
+- Verified selectors (UI) + network patterns (API)
+- Tests verified against actual application behavior
+
+## Usage Examples
+
+### Exploratory Mode Example
+
+```
+User: Run *test-design
+
+TEA: What feature are you designing tests for?
+
+User: The checkout flow at https://shop.example.com
+
+TEA: [With MCP] Let me explore the checkout flow
+[Opens browser]
+[Navigates to checkout]
+[Takes screenshots]
+[Identifies all interactive elements]
+
+TEA: I've explored the checkout flow. I found:
+- 4-step wizard (Cart → Shipping → Payment → Confirm)
+- Shipping options (Standard, Express, Overnight)
+- Payment methods (Credit Card, PayPal)
+- Promo code field
+- Order summary with real-time totals
+
+Test design will cover all these scenarios.
+```
+
+### Recording Mode Example
+
+```
+User: Run *atdd for user registration feature
+
+TEA: [With MCP] Let me verify the registration form selectors
+[Opens browser at /register]
+[Inspects form]
+
+TEA: I see the actual form has:
+- "Full Name" label (not "Name")
+- "Email Address" label (not "Email")
+- "Create Password" label (not "Password")
+- "I agree to Terms" checkbox
+- "Create Account" button (not "Register")
+
+Generating tests with verified selectors...
+```
+
+### Healing Mode Example
+
+```
+User: Run *automate with healing mode
+
+TEA: [With MCP] Running tests and checking for failures
+[Runs test suite]
+[Test fails: selector not found]
+
+TEA: Test failed on selector '.submit-btn'
+[Opens trace viewer]
+[Sees button class changed to '.submit-button']
+
+Fixing selector and verifying...
+[Updates test]
+[Re-runs with MCP]
+[Test passes]
+
+Updated test with corrected selector.
+```
+
+## Troubleshooting
+
+### MCP Servers Not Running
+
+**Problem:** TEA says MCP enhancements aren't available.
+
+**Causes:**
+1. MCP servers not configured in IDE
+2. Config syntax error in JSON
+3. IDE not restarted after config
+
+**Solution:**
+```bash
+# Verify MCP config file exists
+ls ~/.cursor/config.json
+
+# Validate JSON syntax
+cat ~/.cursor/config.json | python -m json.tool
+
+# Restart IDE
+# Cmd+Q (quit) then reopen
+```
+
+### Browser Doesn't Open
+
+**Problem:** MCP enabled but browser never opens.
+
+**Causes:**
+1. Playwright browsers not installed
+2. Headless mode enabled
+3. MCP server crashed
+
+**Solution:**
+```bash
+# Install browsers
+npx playwright install
+
+# Check MCP server logs (in IDE)
+# Look for error messages
+
+# Try manual MCP server
+npx @playwright/mcp@latest
+# Should start without errors
+```
+
+### TEA Doesn't Use MCP
+
+**Problem:** `tea_use_mcp_enhancements: true` but TEA doesn't use browser.
+
+**Causes:**
+1. Config not saved
+2. Workflow run before config update
+3. MCP servers not running
+
+**Solution:**
+```bash
+# Verify config
+grep tea_use_mcp_enhancements _bmad/bmm/config.yaml
+# Should show: tea_use_mcp_enhancements: true
+
+# Restart IDE (reload MCP servers)
+
+# Start fresh chat (TEA loads config at start)
+```
+
+### Selector Verification Fails
+
+**Problem:** MCP can't find elements TEA is looking for.
+
+**Causes:**
+1. Page not fully loaded
+2. Element behind modal/overlay
+3. Element requires authentication
+
+**Solution:**
+TEA will handle this automatically:
+- Wait for page load
+- Dismiss modals if present
+- Handle auth if needed
+
+If persistent, provide TEA more context:
+```
+"The element is behind a modal - dismiss the modal first"
+"The page requires login - use credentials X"
+```
+
+### MCP Slows Down Workflows
+
+**Problem:** Workflows take much longer with MCP enabled.
+
+**Cause:** Browser automation adds overhead.
+
+**Solution:**
+Use MCP selectively:
+- **Enable for:** Complex UIs, new projects, debugging
+- **Disable for:** Simple features, well-known patterns, API-only testing
+
+Toggle quickly:
+```yaml
+# For this feature (complex UI)
+tea_use_mcp_enhancements: true
+
+# For next feature (simple API)
+tea_use_mcp_enhancements: false
+```
+
+## Related Guides
+
+**Getting Started:**
+- [TEA Lite Quickstart Tutorial](/docs/tutorials/getting-started/tea-lite-quickstart.md) - Learn TEA basics first
+
+**Workflow Guides (MCP-Enhanced):**
+- [How to Run Test Design](/docs/how-to/workflows/run-test-design.md) - Exploratory mode with browser
+- [How to Run ATDD](/docs/how-to/workflows/run-atdd.md) - Recording mode for accurate selectors
+- [How to Run Automate](/docs/how-to/workflows/run-automate.md) - Healing mode for debugging
+
+**Other Customization:**
+- [Integrate Playwright Utils](/docs/how-to/customization/integrate-playwright-utils.md) - Production-ready utilities
+
+## Understanding the Concepts
+
+- [TEA Overview](/docs/explanation/features/tea-overview.md) - MCP enhancements in lifecycle
+- [Engagement Models](/docs/explanation/tea/engagement-models.md) - When to use MCP enhancements
+
+## Reference
+
+- [TEA Configuration](/docs/reference/tea/configuration.md) - tea_use_mcp_enhancements option
+- [TEA Command Reference](/docs/reference/tea/commands.md) - MCP-enhanced workflows
+- [Glossary](/docs/reference/glossary/index.md#test-architect-tea-concepts) - MCP Enhancements term
+
+---
+
+Generated with [BMad Method](https://bmad-method.org) - TEA (Test Architect)

package/docs/how-to/customization/index.md

@@ -0,0 +1,23 @@
+---
+title: "BMad Customization"
+---
+
+Personalize agents and workflows to match your needs.
+
+## Guides
+
+| Guide | Description |
+|-------|-------------|
+| **[Agent Customization](/docs/how-to/customization/customize-agents.md)** | Modify agent behavior without editing core files |
+
+## 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)