bmad-method 6.0.0-alpha.22 → 6.0.0-alpha.23

package/docs/explanation/philosophy/facilitation-over-generation.md

@@ -0,0 +1,121 @@
+---
+title: "Facilitation Over Generation"
+description: Understanding CIS's facilitation-first approach to creative work
+---
+
+
+The Creative Intelligence Suite (CIS) takes a fundamentally different approach from typical AI tools. Instead of generating solutions directly, CIS agents act as master facilitators who guide you to discover insights yourself.
+
+---
+
+## The Problem with Generation
+
+Traditional AI approaches to creative work:
+
+```
+User: "Give me marketing ideas"
+AI: "Here are 10 marketing ideas..."
+```
+
+This approach:
+- Produces generic, predictable outputs
+- Removes human ownership of ideas
+- Misses context and nuance
+- Limits creative exploration
+
+---
+
+## The Facilitation Approach
+
+CIS agents use strategic questioning:
+
+```
+User: "I need marketing ideas"
+CIS: "What makes your customers choose you over alternatives?
+      What's the one thing they always mention?"
+User: "They say our support is exceptional"
+CIS: "Interesting! How might you make that exceptional
+      support visible before they become customers?"
+```
+
+This approach:
+- Draws out insights already within you
+- Maintains human ownership of ideas
+- Captures context and nuance
+- Enables deeper creative exploration
+
+---
+
+## Key Principles
+
+### 1. Questions Over Answers
+
+CIS agents ask strategic questions rather than providing direct answers. This:
+- Activates your own creative thinking
+- Uncovers assumptions
+- Reveals blind spots
+- Builds on your domain knowledge
+
+### 2. Energy-Aware Sessions
+
+CIS monitors engagement and adapts:
+- Adjusts pace when energy flags
+- Suggests breaks when needed
+- Changes techniques to maintain momentum
+- Recognizes productive vs. unproductive struggle
+
+### 3. Process Trust
+
+CIS uses proven methodologies:
+- Design Thinking's 5 phases
+- Structured brainstorming techniques
+- Root cause analysis frameworks
+- Innovation strategy patterns
+
+You're not just having a conversation—you're following time-tested creative processes.
+
+### 4. Persona-Driven Engagement
+
+Each CIS agent has a distinct personality:
+- **Carson** - Energetic, encouraging
+- **Maya** - Jazz-like, improvisational
+- **Dr. Quinn** - Analytical, methodical
+- **Victor** - Bold, strategic
+- **Sophia** - Narrative, imaginative
+
+These personas create engaging experiences that maintain creative flow.
+
+---
+
+## When Generation is Appropriate
+
+CIS does generate when appropriate:
+- Synthesizing session outputs
+- Documenting decisions
+- Creating structured artifacts
+- Providing technique examples
+
+But the core creative work happens through facilitated discovery.
+
+---
+
+## Benefits
+
+### For Individuals
+- Deeper insights than pure generation
+- Ownership of creative outputs
+- Skill development in creative thinking
+- More memorable and actionable ideas
+
+### For Teams
+- Shared creative experience
+- Aligned understanding
+- Documented rationale
+- Stronger buy-in to outcomes
+
+---
+
+## Related
+
+- [Creative Intelligence Suite](/docs/explanation/creative-intelligence/index.md) - CIS overview
+- [Brainstorming Techniques](/docs/explanation/features/brainstorming-techniques.md) - Available techniques

package/docs/explanation/philosophy/testing-as-engineering.md

@@ -0,0 +1,119 @@
+---
+title: "AI-Generated Testing: Why Most Approaches Fail"
+description: How Playwright-Utils, TEA workflows, and Playwright MCPs solve AI test quality problems
+---
+
+
+AI-generated tests frequently fail in production because they lack systematic quality standards. This document explains the problem and presents a solution combining three components: Playwright-Utils, TEA (Test Architect), and Playwright MCPs.
+
+:::note[Source]
+This article is adapted from [The Testing Meta Most Teams Have Not Caught Up To Yet](https://dev.to/muratkeremozcan/the-testing-meta-most-teams-have-not-caught-up-to-yet-5765) by Murat K Ozcan.
+:::
+
+## The Problem with AI-Generated Tests
+
+When teams use AI to generate tests without structure, they often produce what can be called "slop factory" outputs:
+
+| Issue | Description |
+|-------|-------------|
+| Redundant coverage | Multiple tests covering the same functionality |
+| Incorrect assertions | Tests that pass but don't actually verify behavior |
+| Flaky tests | Non-deterministic tests that randomly pass or fail |
+| Unreviewable diffs | Generated code too verbose or inconsistent to review |
+
+The core problem is that prompt-driven testing paths lean into nondeterminism, which is the exact opposite of what testing exists to protect.
+
+:::caution[The Paradox]
+AI excels at generating code quickly, but testing requires precision and consistency. Without guardrails, AI-generated tests amplify the chaos they're meant to prevent.
+:::
+
+## The Solution: A Three-Part Stack
+
+The solution combines three components that work together to enforce quality:
+
+### Playwright-Utils
+
+Bridges the gap between Cypress ergonomics and Playwright's capabilities by standardizing commonly reinvented primitives through utility functions.
+
+| Utility | Purpose |
+|---------|---------|
+| api-request | API calls with schema validation |
+| auth-session | Authentication handling |
+| intercept-network-call | Network mocking and interception |
+| recurse | Retry logic and polling |
+| log | Structured logging |
+| network-recorder | Record and replay network traffic |
+| burn-in | Smart test selection for CI |
+| network-error-monitor | HTTP error detection |
+| file-utils | CSV/PDF handling |
+
+These utilities eliminate the need to reinvent authentication, API calls, retries, and logging for every project.
+
+### TEA (Test Architect Agent)
+
+A quality operating model packaged as eight executable workflows spanning test design, CI/CD gates, and release readiness. TEA encodes test architecture expertise into repeatable processes.
+
+| Workflow | Purpose |
+|----------|---------|
+| `*test-design` | Risk-based test planning per epic |
+| `*framework` | Scaffold production-ready test infrastructure |
+| `*ci` | CI pipeline with selective testing |
+| `*atdd` | Acceptance test-driven development |
+| `*automate` | Prioritized test automation |
+| `*test-review` | Test quality audits (0-100 score) |
+| `*nfr-assess` | Non-functional requirements assessment |
+| `*trace` | Coverage traceability and gate decisions |
+
+:::tip[Key Insight]
+TEA doesn't just generate tests—it provides a complete quality operating model with workflows for planning, execution, and release gates.
+:::
+
+### Playwright MCPs
+
+Model Context Protocols enable real-time verification during test generation. Instead of inferring selectors and behavior from documentation, MCPs allow agents to:
+
+- Run flows and confirm the DOM against the accessibility tree
+- Validate network responses in real-time
+- Discover actual functionality through interactive exploration
+- Verify generated tests against live applications
+
+## How They Work Together
+
+The three components form a quality pipeline:
+
+| Stage | Component | Action |
+|-------|-----------|--------|
+| Standards | Playwright-Utils | Provides production-ready patterns and utilities |
+| Process | TEA Workflows | Enforces systematic test planning and review |
+| Verification | Playwright MCPs | Validates generated tests against live applications |
+
+**Before (AI-only):** 20 tests with redundant coverage, incorrect assertions, and flaky behavior.
+
+**After (Full Stack):** Risk-based selection, verified selectors, validated behavior, reviewable code.
+
+## Why This Matters
+
+Traditional AI testing approaches fail because they:
+
+- **Lack quality standards** — No consistent patterns or utilities
+- **Skip planning** — Jump straight to test generation without risk assessment
+- **Can't verify** — Generate tests without validating against actual behavior
+- **Don't review** — No systematic audit of generated test quality
+
+The three-part stack addresses each gap:
+
+| Gap | Solution |
+|-----|----------|
+| No standards | Playwright-Utils provides production-ready patterns |
+| No planning | TEA `*test-design` workflow creates risk-based test plans |
+| No verification | Playwright MCPs validate against live applications |
+| No review | TEA `*test-review` audits quality with scoring |
+
+This approach is sometimes called *context engineering*—loading domain-specific standards into AI context automatically rather than relying on prompts alone. TEA's `tea-index.csv` manifest loads relevant knowledge fragments so the AI doesn't relearn testing patterns each session.
+
+## Related
+
+- [TEA Overview](/docs/explanation/features/tea-overview.md) — Workflow details and cheat sheets
+- [Setup Test Framework](/docs/how-to/workflows/setup-test-framework.md) — Implementation guide
+- [The Testing Meta Most Teams Have Not Caught Up To Yet](https://dev.to/muratkeremozcan/the-testing-meta-most-teams-have-not-caught-up-to-yet-5765) — Original article by Murat K Ozcan
+- [Playwright-Utils Repository](https://github.com/seontechnologies/playwright-utils) — Source and documentation

package/docs/how-to/brownfield/add-feature-to-existing.md

@@ -0,0 +1,91 @@
+---
+title: "How to Add a Feature to an Existing Project"
+description: How to add new features to an existing brownfield project
+---
+
+
+Add new functionality to your brownfield codebase while respecting existing patterns and architecture.
+
+---
+
+## When to Use This
+
+- Adding a new feature to an existing codebase
+- Major enhancements that need proper planning
+- Features that touch multiple parts of the system
+
+---
+
+## Prerequisites
+
+- BMad Method installed
+- Existing project documentation (run `document-project` first if needed)
+- Clear understanding of what you want to build
+
+---
+
+## Steps
+
+### 1. Run workflow-init
+
+```
+Run workflow-init
+```
+
+The workflow should recognize you're in an existing project. If not, explicitly clarify that this is brownfield development.
+
+### 2. Choose Your Approach
+
+| Feature Scope | Recommended Approach |
+|---------------|---------------------|
+| Small (1-5 stories) | Quick Flow with tech-spec |
+| Medium (5-15 stories) | BMad Method with PRD |
+| Large (15+ stories) | Full BMad Method with architecture |
+
+### 3. Create Planning Documents
+
+**For Quick Flow:**
+- Load PM agent
+- Run tech-spec workflow
+- The agent will analyze your existing codebase and create a context-aware spec
+
+**For BMad Method:**
+- Load PM agent
+- Run PRD workflow
+- Ensure the agent reads your existing documentation
+- Review that integration points are clearly identified
+
+### 4. Consider Architecture Impact
+
+If your feature affects system architecture:
+
+- Load Architect agent
+- Run architecture workflow
+- Ensure alignment with existing patterns
+- Document any new ADRs (Architecture Decision Records)
+
+### 5. Implement
+
+Follow the standard Phase 4 implementation workflows:
+
+1. `sprint-planning` - Organize your work
+2. `create-story` - Prepare each story
+3. `dev-story` - Implement with tests
+4. `code-review` - Quality assurance
+
+---
+
+## Tips
+
+- Always ensure agents read your existing documentation
+- Pay attention to integration points with existing code
+- Follow existing conventions unless deliberately changing them
+- Document why you're adding new patterns (if any)
+
+---
+
+## Related
+
+- [Brownfield Development Guide](/docs/how-to/brownfield/index.md)
+- [Document Existing Project](/docs/how-to/brownfield/document-existing-project.md)
+- [Quick Fix in Brownfield](/docs/how-to/brownfield/quick-fix-in-brownfield.md)

package/docs/how-to/brownfield/document-existing-project.md

@@ -0,0 +1,84 @@
+---
+title: "How to Document an Existing Project"
+description: How to document an existing brownfield codebase using BMad Method
+---
+
+
+Use the `document-project` workflow to scan your entire codebase and generate comprehensive documentation about its current state.
+
+---
+
+## When to Use This
+
+- Starting work on an undocumented legacy project
+- Documentation is outdated and needs refresh
+- AI agents need context about existing code patterns
+- Onboarding new team members
+
+---
+
+## Prerequisites
+
+- BMad Method installed in your project
+- Access to the codebase you want to document
+
+---
+
+## Steps
+
+### 1. Load the Analyst Agent
+
+Start a fresh chat and load the Analyst agent.
+
+### 2. Run the document-project Workflow
+
+Tell the agent:
+
+```
+Run the document-project workflow
+```
+
+### 3. Let the Agent Scan Your Codebase
+
+The workflow will:
+
+- Scan your codebase structure
+- Identify architecture patterns
+- Document the technology stack
+- Create reference documentation
+- Generate a PRD-like document from existing code
+
+### 4. Review the Generated Documentation
+
+The output will be saved to `project-documentation-{date}.md` in your output folder.
+
+Review the documentation for:
+
+- Accuracy of detected patterns
+- Completeness of architecture description
+- Any missing business rules or intent
+
+---
+
+## What You Get
+
+- **Project overview** - High-level description of what the project does
+- **Technology stack** - Detected frameworks, libraries, and tools
+- **Architecture patterns** - Code organization and design patterns found
+- **Business rules** - Logic extracted from the codebase
+- **Integration points** - External APIs and services
+
+---
+
+## Tips
+
+- Run this before any major brownfield work
+- Keep the documentation updated as the project evolves
+- Use it as input for future PRD creation
+
+---
+
+## Related
+
+- [Brownfield Development Guide](/docs/how-to/brownfield/index.md)
+- [Add Feature to Existing Project](/docs/how-to/brownfield/add-feature-to-existing.md)

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

@@ -0,0 +1,102 @@
+---
+title: "Brownfield Development"
+description: How to use BMad Method on existing codebases
+---
+
+
+How to effectively use BMad Method when working on existing projects and legacy codebases.
+
+## What is Brownfield Development?
+
+**Brownfield** refers to working on existing projects with established codebases and patterns, as opposed to **greenfield** which means starting from scratch with a clean slate.
+
+This tutorial covers the essential workflow for onboarding to brownfield projects with BMad Method.
+
+---
+
+## Prerequisites
+
+- BMad Method installed (`npx bmad-method install`)
+- An existing codebase you want to work on
+- Access to an AI-powered IDE (Claude Code, Cursor, or Windsurf)
+
+---
+
+## Step 1: Clean Up Completed Planning Artifacts
+
+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:
+
+- `docs/`
+- `_bmad-output/planning-artifacts/`
+- `_bmad-output/implementation-artifacts/`
+
+---
+
+## Step 2: Maintain Quality Project Documentation
+
+Your `docs/` folder should contain succinct, well-organized documentation that accurately represents your project:
+
+- 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.
+
+---
+
+## Step 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.
+
+---
+
+## Next Steps
+
+- **[Document Existing Project](/docs/how-to/brownfield/document-existing-project.md)** - How to document your brownfield codebase
+- **[Add Feature to Existing Project](/docs/how-to/brownfield/add-feature-to-existing.md)** - Adding new functionality
+- **[Quick Fix in Brownfield](/docs/how-to/brownfield/quick-fix-in-brownfield.md)** - Bug fixes and ad-hoc changes
+- **[Brownfield FAQ](/docs/explanation/faq/brownfield-faq.md)** - Common questions about brownfield development
+
+---
+
+## Related Documentation
+
+- [Quick Start Guide](/docs/tutorials/getting-started/getting-started-bmadv6.md) - Getting started with BMM
+- [Quick Spec Flow](/docs/explanation/features/quick-flow.md) - Fast path for small changes

package/docs/how-to/brownfield/quick-fix-in-brownfield.md

@@ -0,0 +1,94 @@
+---
+title: "How to Make Quick Fixes in Brownfield Projects"
+description: How to make quick fixes and ad-hoc changes in brownfield projects
+---
+
+
+Not everything requires the full BMad method or even Quick Flow. For bug fixes, refactorings, or small targeted changes, you can work directly with the agent.
+
+---
+
+## When to Use This
+
+- Bug fixes
+- Small refactorings
+- Targeted code improvements
+- Learning about your codebase
+- One-off changes that don't need planning
+
+---
+
+## Steps
+
+### 1. Load an Agent
+
+For quick fixes, you can use:
+
+- **DEV agent** - For implementation-focused work
+- **Quick Flow Solo Dev** - For slightly larger changes that still need a tech-spec
+
+### 2. Describe the Change
+
+Simply tell the agent what you need:
+
+```
+Fix the login validation bug that allows empty passwords
+```
+
+or
+
+```
+Refactor the UserService to use async/await instead of callbacks
+```
+
+### 3. Let the Agent Work
+
+The agent will:
+
+- Analyze the relevant code
+- Propose a solution
+- Implement the change
+- Run tests (if available)
+
+### 4. Review and Commit
+
+Review the changes made and commit when satisfied.
+
+---
+
+## Learning Your Codebase
+
+This approach is also excellent for exploring unfamiliar code:
+
+```
+Explain how the authentication system works in this codebase
+```
+
+```
+Show me where error handling happens in the API layer
+```
+
+LLMs are excellent at interpreting and analyzing code—whether it was AI-generated or not. Use the agent to:
+
+- Learn about your project
+- Understand how things are built
+- Explore unfamiliar parts of the codebase
+
+---
+
+## When to Upgrade to Formal Planning
+
+Consider using Quick Flow or full BMad Method when:
+
+- The change affects multiple files or systems
+- You're unsure about the scope
+- The fix keeps growing in complexity
+- You need documentation for the change
+
+---
+
+## Related
+
+- [Brownfield Development Guide](/docs/how-to/brownfield/index.md)
+- [Add Feature to Existing Project](/docs/how-to/brownfield/add-feature-to-existing.md)
+- [Quick Spec Flow](/docs/explanation/features/quick-flow.md)

package/docs/{bmad-core-concepts/bmad-customization/agents.md → how-to/customization/customize-agents.md}

@@ -1,4 +1,7 @@
-# Agent Customization Guide
+---
+title: "Agent Customization Guide"
+---
+
 
 Customize BMad agents without modifying core files. All customizations persist through updates.
 
@@ -26,10 +29,8 @@ 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
-# OR for individual agent only
 npx bmad-method@alpha build <agent-name>
 
-# Examples:
 npx bmad-method@alpha build bmm-dev
 npx bmad-method@alpha build core-bmad-master
 npx bmad-method@alpha build bmm-pm
@@ -119,7 +120,6 @@ prompts:
 **Example 1: Customize Developer Agent for TDD**
 
 ```yaml
-# _bmad/_config/agents/bmm-dev.customize.yaml
 agent:
   metadata:
     name: 'TDD Developer'
@@ -135,7 +135,6 @@ critical_actions:
 **Example 2: Add Custom Deployment Workflow**
 
 ```yaml
-# _bmad/_config/agents/bmm-dev.customize.yaml
 menu:
   - trigger: deploy-staging
     workflow: '{project-root}/_bmad/deploy-staging.yaml'
@@ -148,7 +147,6 @@ menu:
 **Example 3: Multilingual Product Manager**
 
 ```yaml
-# _bmad/_config/agents/bmm-pm.customize.yaml
 persona:
   role: 'Bilingual Product Manager'
   identity: 'Expert in US and LATAM markets'
@@ -203,8 +201,8 @@ memories:
 
 ## Next Steps
 
-- **[Learn about Agents](../agents.md)** - Understand Simple vs Expert agents
-- **[Agent Creation Guide](../../modules/bmb-bmad-builder/agent-creation-guide.md)** - Build completely custom agents
-- **[BMM Complete Documentation](../../modules/bmm-bmad-method/index)** - Full BMad Method reference
+- **[Learn about Agents](/docs/explanation/core-concepts/what-are-agents.md)** - Understand Simple vs Expert agents
+- **[Agent Creation Guide](/docs/tutorials/advanced/create-custom-agent.md)** - Build completely custom agents
+- **[BMM Complete Documentation](/docs/explanation/bmm/index.md)** - Full BMad Method reference
 
-[← Back to Customization](./index.md)
+[← Back to Customization](/docs/how-to/customization/index.md)

package/docs/{bmad-core-concepts/bmad-customization/workflows.md → how-to/customization/customize-workflows.md}

@@ -1,4 +1,7 @@
-# Workflow Customization Guide
+---
+title: "Workflow Customization Guide"
+---
+
 
 Customize and optimize workflows with step replacement and hooks.
 
@@ -19,12 +22,12 @@ Workflow customization will allow you to:
 
 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)
+- **Create Custom Workflows** - Use the BMad Builder to create entirely new workflows
+- **Customize Agents** - Modify agent behavior using [Agent Customization](/docs/how-to/customization/customize-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.
+**In the meantime:** Learn how to [create custom workflows](/docs/explanation/bmad-builder/index.md) from scratch.
 
-[← Back to Customization](./index.md)
+[← Back to Customization](/docs/how-to/customization/index.md)