bmad-method 6.0.0-alpha.8 → 6.0.1

package/docs/explanation/preventing-agent-conflicts.md

@@ -0,0 +1,112 @@
+---
+title: "Preventing Agent Conflicts"
+description: How architecture prevents conflicts when multiple agents implement a system
+sidebar:
+  order: 4
+---
+
+When multiple AI agents implement different parts of a system, they can make conflicting technical decisions. Architecture documentation prevents this by establishing shared standards.
+
+## Common Conflict Types
+
+### API Style Conflicts
+
+Without architecture:
+- Agent A uses REST with `/users/{id}`
+- Agent B uses GraphQL mutations
+- Result: Inconsistent API patterns, confused consumers
+
+With architecture:
+- ADR specifies: "Use GraphQL for all client-server communication"
+- All agents follow the same pattern
+
+### Database Design Conflicts
+
+Without architecture:
+- Agent A uses snake_case column names
+- Agent B uses camelCase column names
+- Result: Inconsistent schema, confusing queries
+
+With architecture:
+- Standards document specifies naming conventions
+- All agents follow the same patterns
+
+### State Management Conflicts
+
+Without architecture:
+- Agent A uses Redux for global state
+- Agent B uses React Context
+- Result: Multiple state management approaches, complexity
+
+With architecture:
+- ADR specifies state management approach
+- All agents implement consistently
+
+## How Architecture Prevents Conflicts
+
+### 1. Explicit Decisions via ADRs
+
+Every significant technology choice is documented with:
+- Context (why this decision matters)
+- Options considered (what alternatives exist)
+- Decision (what we chose)
+- Rationale (why we chose it)
+- Consequences (trade-offs accepted)
+
+### 2. FR/NFR-Specific Guidance
+
+Architecture maps each functional requirement to technical approach:
+- FR-001: User Management → GraphQL mutations
+- FR-002: Mobile App → Optimized queries
+
+### 3. Standards and Conventions
+
+Explicit documentation of:
+- Directory structure
+- Naming conventions
+- Code organization
+- Testing patterns
+
+## Architecture as Shared Context
+
+Think of architecture as the shared context that all agents read before implementing:
+
+```text
+PRD: "What to build"
+     ↓
+Architecture: "How to build it"
+     ↓
+Agent A reads architecture → implements Epic 1
+Agent B reads architecture → implements Epic 2
+Agent C reads architecture → implements Epic 3
+     ↓
+Result: Consistent implementation
+```
+
+## Key ADR Topics
+
+Common decisions that prevent conflicts:
+
+| Topic            | Example Decision                             |
+| ---------------- | -------------------------------------------- |
+| API Style        | GraphQL vs REST vs gRPC                      |
+| Database         | PostgreSQL vs MongoDB                        |
+| Auth             | JWT vs Sessions                              |
+| State Management | Redux vs Context vs Zustand                  |
+| Styling          | CSS Modules vs Tailwind vs Styled Components |
+| Testing          | Jest + Playwright vs Vitest + Cypress        |
+
+## Anti-Patterns to Avoid
+
+:::caution[Common Mistakes]
+- **Implicit Decisions** — "We'll figure out the API style as we go" leads to inconsistency
+- **Over-Documentation** — Documenting every minor choice causes analysis paralysis
+- **Stale Architecture** — Documents written once and never updated cause agents to follow outdated patterns
+:::
+
+:::tip[Correct Approach]
+- Document decisions that cross epic boundaries
+- Focus on conflict-prone areas
+- Update architecture as you learn
+- Use `correct-course` for significant changes
+:::

package/docs/explanation/project-context.md

@@ -0,0 +1,157 @@
+---
+title: "Project Context"
+description: How project-context.md guides AI agents with your project's rules and preferences
+sidebar:
+  order: 7
+---
+
+The `project-context.md` file is your project's implementation guide for AI agents. Similar to a "constitution" in other development systems, it captures the rules, patterns, and preferences that ensure consistent code generation across all workflows.
+
+## What It Does
+
+AI agents make implementation decisions constantly — which patterns to follow, how to structure code, what conventions to use. Without clear guidance, they may:
+- Follow generic best practices that don't match your codebase
+- Make inconsistent decisions across different stories
+- Miss project-specific requirements or constraints
+
+The `project-context.md` file solves this by documenting what agents need to know in a concise, LLM-optimized format.
+
+## How It Works
+
+Every implementation workflow automatically loads `project-context.md` if it exists. The architect workflow also loads it to respect your technical preferences when designing the architecture.
+
+**Loaded by these workflows:**
+- `create-architecture` — respects technical preferences during solutioning
+- `create-story` — informs story creation with project patterns
+- `dev-story` — guides implementation decisions
+- `code-review` — validates against project standards
+- `quick-dev` — applies patterns when implementing tech-specs
+- `sprint-planning`, `retrospective`, `correct-course` — provides project-wide context
+
+## When to Create It
+
+The `project-context.md` file is useful at any stage of a project:
+
+| Scenario | When to Create | Purpose |
+|----------|----------------|---------|
+| **New project, before architecture** | Manually, before `create-architecture` | Document your technical preferences so the architect respects them |
+| **New project, after architecture** | Via `generate-project-context` or manually | Capture architecture decisions for implementation agents |
+| **Existing project** | Via `generate-project-context` | Discover existing patterns so agents follow established conventions |
+| **Quick Flow project** | Before or during `quick-dev` | Ensure quick implementation respects your patterns |
+
+:::tip[Recommended]
+For new projects, create it manually before architecture if you have strong technical preferences. Otherwise, generate it after architecture to capture those decisions.
+:::
+
+## What Goes In It
+
+The file has two main sections:
+
+### Technology Stack & Versions
+
+Documents the frameworks, languages, and tools your project uses with specific versions:
+
+```markdown
+## Technology Stack & Versions
+
+- Node.js 20.x, TypeScript 5.3, React 18.2
+- State: Zustand (not Redux)
+- Testing: Vitest, Playwright, MSW
+- Styling: Tailwind CSS with custom design tokens
+```
+
+### Critical Implementation Rules
+
+Documents patterns and conventions that agents might otherwise miss:
+
+```markdown
+## Critical Implementation Rules
+
+**TypeScript Configuration:**
+- Strict mode enabled — no `any` types without explicit approval
+- Use `interface` for public APIs, `type` for unions/intersections
+
+**Code Organization:**
+- Components in `/src/components/` with co-located `.test.tsx`
+- Utilities in `/src/lib/` for reusable pure functions
+- API calls use the `apiClient` singleton — never fetch directly
+
+**Testing Patterns:**
+- Unit tests focus on business logic, not implementation details
+- Integration tests use MSW to mock API responses
+- E2E tests cover critical user journeys only
+
+**Framework-Specific:**
+- All async operations use the `handleError` wrapper for consistent error handling
+- Feature flags accessed via `featureFlag()` from `@/lib/flags`
+- New routes follow the file-based routing pattern in `/src/app/`
+```
+
+Focus on what's **unobvious** — things agents might not infer from reading code snippets. Don't document standard practices that apply universally.
+
+## Creating the File
+
+You have three options:
+
+### Manual Creation
+
+Create the file at `_bmad-output/project-context.md` and add your rules:
+
+```bash
+# In your project root
+mkdir -p _bmad-output
+touch _bmad-output/project-context.md
+```
+
+Edit it with your technology stack and implementation rules. The architect and implementation workflows will automatically find and load it.
+
+### Generate After Architecture
+
+Run the `generate-project-context` workflow after completing your architecture:
+
+```bash
+/bmad-bmm-generate-project-context
+```
+
+This scans your architecture document and project files to generate a context file capturing the decisions made.
+
+### Generate for Existing Projects
+
+For existing projects, run `generate-project-context` to discover existing patterns:
+
+```bash
+/bmad-bmm-generate-project-context
+```
+
+The workflow analyzes your codebase to identify conventions, then generates a context file you can review and refine.
+
+## Why It Matters
+
+Without `project-context.md`, agents make assumptions that may not match your project:
+
+| Without Context | With Context |
+|----------------|--------------|
+| Uses generic patterns | Follows your established conventions |
+| Inconsistent style across stories | Consistent implementation |
+| May miss project-specific constraints | Respects all technical requirements |
+| Each agent decides independently | All agents align with same rules |
+
+This is especially important for:
+- **Quick Flow** — skips PRD and architecture, so context file fills the gap
+- **Team projects** — ensures all agents follow the same standards
+- **Existing projects** — prevents breaking established patterns
+
+## Editing and Updating
+
+The `project-context.md` file is a living document. Update it when:
+
+- Architecture decisions change
+- New conventions are established
+- Patterns evolve during implementation
+- You identify gaps from agent behavior
+
+You can edit it manually at any time, or re-run `generate-project-context` to update it after significant changes.
+
+:::note[File Location]
+The default location is `_bmad-output/project-context.md`. Workflows search for it there, and also check `**/project-context.md` anywhere in your project.
+:::

package/docs/explanation/quick-flow.md

@@ -0,0 +1,73 @@
+---
+title: "Quick Flow"
+description: Fast-track for small changes - skip the full methodology
+sidebar:
+  order: 1
+---
+
+Skip the ceremony. Quick Flow takes you from idea to working code in two commands - no Product Brief, no PRD, no Architecture doc.
+
+## When to Use It
+
+- Bug fixes and patches
+- Refactoring existing code
+- Small, well-understood features
+- Prototyping and spikes
+- Single-agent work where one developer can hold the full scope
+
+## When NOT to Use It
+
+- New products or platforms that need stakeholder alignment
+- Major features spanning multiple components or teams
+- Work that requires architectural decisions (database schema, API contracts, service boundaries)
+- Anything where requirements are unclear or contested
+
+:::caution[Scope Creep]
+If you start a Quick Flow and realize the scope is bigger than expected, `quick-dev` will detect this and offer to escalate. You can switch to a full PRD workflow at any point without losing your work.
+:::
+
+## How It Works
+
+Quick Flow has two commands, each backed by a structured workflow. You can run them together or independently.
+
+### quick-spec: Plan
+
+Run `quick-spec` and Barry (the Quick Flow agent) walks you through a conversational discovery process:
+
+1. **Understand** - You describe what you want to build. Barry scans the codebase to ask informed questions, then captures a problem statement, solution approach, and scope boundaries.
+2. **Investigate** - Barry reads relevant files, maps code patterns, identifies files to modify, and documents the technical context.
+3. **Generate** - Produces a complete tech-spec with ordered implementation tasks (specific file paths and actions), acceptance criteria in Given/When/Then format, testing strategy, and dependencies.
+4. **Review** - Presents the full spec for your sign-off. You can edit, ask questions, run adversarial review, or refine with advanced elicitation before finalizing.
+
+The output is a `tech-spec-{slug}.md` file saved to your project's implementation artifacts folder. It contains everything a fresh agent needs to implement the feature - no conversation history required.
+
+### quick-dev: Build
+
+Run `quick-dev` and Barry implements the work. It operates in two modes:
+
+- **Tech-spec mode** - Point it at a spec file (`quick-dev tech-spec-auth.md`) and it executes every task in order, writes tests, and verifies acceptance criteria.
+- **Direct mode** - Give it instructions directly (`quick-dev "refactor the auth middleware"`) and it gathers context, builds a mental plan, and executes.
+
+After implementation, `quick-dev` runs a self-check audit against all tasks and acceptance criteria, then triggers an adversarial code review of the diff. Findings are presented for you to resolve before wrapping up.
+
+:::tip[Fresh Context]
+For best results, run `quick-dev` in a new conversation after finishing `quick-spec`. This gives the implementation agent clean context focused solely on building.
+:::
+
+## What Quick Flow Skips
+
+The full BMad Method produces a Product Brief, PRD, Architecture doc, and Epic/Story breakdown before any code is written. Quick Flow replaces all of that with a single tech-spec. This works because Quick Flow targets changes where:
+
+- The product direction is already established
+- Architecture decisions are already made
+- A single developer can reason about the full scope
+- Requirements fit in one conversation
+
+## Escalating to Full BMad Method
+
+Quick Flow includes built-in guardrails for scope detection. When you run `quick-dev` with a direct request, it evaluates signals like multi-component mentions, system-level language, and uncertainty about approach. If it detects the work is bigger than a quick flow:
+
+- **Light escalation** - Recommends running `quick-spec` first to create a plan
+- **Heavy escalation** - Recommends switching to the full BMad Method PRD process
+
+You can also escalate manually at any time. Your tech-spec work carries forward - it becomes input for the broader planning process rather than being discarded.

package/docs/explanation/why-solutioning-matters.md

@@ -0,0 +1,77 @@
+---
+title: "Why Solutioning Matters"
+description: Understanding why the solutioning phase is critical for multi-epic projects
+sidebar:
+  order: 3
+---
+
+
+Phase 3 (Solutioning) translates **what** to build (from Planning) into **how** to build it (technical design). This phase prevents agent conflicts in multi-epic projects by documenting architectural decisions before implementation begins.
+
+## The Problem Without Solutioning
+
+```text
+Agent 1 implements Epic 1 using REST API
+Agent 2 implements Epic 2 using GraphQL
+Result: Inconsistent API design, integration nightmare
+```
+
+When multiple agents implement different parts of a system without shared architectural guidance, they make independent technical decisions that may conflict.
+
+## The Solution With Solutioning
+
+```text
+architecture workflow decides: "Use GraphQL for all APIs"
+All agents follow architecture decisions
+Result: Consistent implementation, no conflicts
+```
+
+By documenting technical decisions explicitly, all agents implement consistently and integration becomes straightforward.
+
+## Solutioning vs Planning
+
+| Aspect   | Planning (Phase 2)      | Solutioning (Phase 3)             |
+| -------- | ----------------------- | --------------------------------- |
+| Question | What and Why?           | How? Then What units of work?     |
+| Output   | FRs/NFRs (Requirements) | Architecture + Epics/Stories      |
+| Agent    | PM                      | Architect → PM                    |
+| Audience | Stakeholders            | Developers                        |
+| Document | PRD (FRs/NFRs)          | Architecture + Epic Files         |
+| Level    | Business logic          | Technical design + Work breakdown |
+
+## Key Principle
+
+**Make technical decisions explicit and documented** so all agents implement consistently.
+
+This prevents:
+- API style conflicts (REST vs GraphQL)
+- Database design inconsistencies
+- State management disagreements
+- Naming convention mismatches
+- Security approach variations
+
+## When Solutioning is Required
+
+| Track | Solutioning Required? |
+|-------|----------------------|
+| Quick Flow | No - skip entirely |
+| BMad Method Simple | Optional |
+| BMad Method Complex | Yes |
+| Enterprise | Yes |
+
+:::tip[Rule of Thumb]
+If you have multiple epics that could be implemented by different agents, you need solutioning.
+:::
+
+## The Cost of Skipping
+
+Skipping solutioning on complex projects leads to:
+
+- **Integration issues** discovered mid-sprint
+- **Rework** due to conflicting implementations
+- **Longer development time** overall
+- **Technical debt** from inconsistent patterns
+
+:::caution[Cost Multiplier]
+Catching alignment issues in solutioning is 10× faster than discovering them during implementation.
+:::

package/docs/how-to/customize-bmad.md

@@ -0,0 +1,172 @@
+---
+title: "How to Customize BMad"
+description: Customize agents, workflows, and modules while preserving update compatibility
+sidebar:
+  order: 7
+---
+
+Use the `.customize.yaml` files to tailor agent behavior, personas, and menus while preserving your changes across updates.
+
+## When to Use This
+
+- You want to change an agent's name, personality, or communication style
+- You need agents to remember project-specific context
+- You want to add custom menu items that trigger your own workflows or prompts
+- You want agents to perform specific actions every time they start up
+
+:::note[Prerequisites]
+- BMad installed in your project (see [How to Install BMad](./install-bmad.md))
+- A text editor for YAML files
+:::
+
+:::caution[Keep Your Customizations Safe]
+Always use the `.customize.yaml` files described here rather than editing agent files directly. The installer overwrites agent files during updates, but preserves your `.customize.yaml` changes.
+:::
+
+## Steps
+
+### 1. Locate Customization Files
+
+After installation, find one `.customize.yaml` file per agent in:
+
+```text
+_bmad/_config/agents/
+├── core-bmad-master.customize.yaml
+├── bmm-dev.customize.yaml
+├── bmm-pm.customize.yaml
+└── ... (one file per installed agent)
+```
+
+### 2. Edit the Customization File
+
+Open the `.customize.yaml` file for the agent you want to modify. Every section is optional -- customize only what you need.
+
+| Section             | Behavior     | Purpose                                        |
+| ------------------- | ------------ | ---------------------------------------------- |
+| `agent.metadata`    | Replaces     | Override the agent's display name               |
+| `persona`           | Replaces     | Set role, identity, style, and principles       |
+| `memories`          | Appends      | Add persistent context the agent always recalls |
+| `menu`              | Appends      | Add custom menu items for workflows or prompts  |
+| `critical_actions`  | Appends      | Define startup instructions for the agent       |
+| `prompts`           | Appends      | Create reusable prompts for menu actions         |
+
+Sections marked **Replaces** overwrite the agent's defaults entirely. Sections marked **Appends** add to the existing configuration.
+
+**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 annoying'
+  principles:
+    - 'Never Nester, Spongebob Devs hate nesting more than 2 levels deep'
+    - 'Favor composition over inheritance'
+```
+
+The `persona` section replaces the entire default persona, so include all four fields if you set it.
+
+**Memories**
+
+Add persistent context the agent will always remember:
+
+```yaml
+memories:
+  - 'Works at Krusty Krab'
+  - 'Favorite Celebrity: David Hasslehoff'
+  - 'Learned in Epic 1 that it is not cool to just pretend that tests have passed'
+```
+
+**Menu Items**
+
+Add custom entries to the agent's display menu. Each item needs a `trigger`, a target (`workflow` path or `action` reference), and a `description`:
+
+```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
+```
+
+**Critical Actions**
+
+Define instructions that run when the agent starts up:
+
+```yaml
+critical_actions:
+  - 'Check the CI Pipelines with the XYZ Skill and alert user on wake if anything is urgently needing attention'
+```
+
+**Custom Prompts**
+
+Create reusable prompts that menu items can reference with `action="#id"`:
+
+```yaml
+prompts:
+  - id: deploy-prompt
+    content: |
+      Deploy the current branch to production:
+      1. Run all tests
+      2. Build the project
+      3. Execute deployment script
+```
+
+### 3. Apply Your Changes
+
+After editing, recompile the agent to apply changes:
+
+```bash
+npx bmad-method install
+```
+
+The installer detects the existing installation and offers these options:
+
+| Option                | What It Does                                                        |
+| --------------------- | ------------------------------------------------------------------- |
+| **Quick Update**      | Updates all modules to the latest version and recompiles all agents |
+| **Recompile Agents**  | Applies customizations only, without updating module files          |
+| **Modify BMad Installation** | Full installation flow for adding or removing modules        |
+
+For customization-only changes, **Recompile Agents** is the fastest option.
+
+## Troubleshooting
+
+**Changes not appearing?**
+
+- Run `npx bmad-method install` and select **Recompile Agents** to apply changes
+- Check that your YAML syntax is valid (indentation matters)
+- Verify you edited the correct `.customize.yaml` file for the agent
+
+**Agent not loading?**
+
+- Check for YAML syntax errors using an online YAML validator
+- Ensure you did not leave fields empty after uncommenting them
+- Try reverting to the original template and rebuilding
+
+**Need to reset an agent?**
+
+- Clear or delete the agent's `.customize.yaml` file
+- Run `npx bmad-method install` and select **Recompile Agents** to restore defaults
+
+## Workflow Customization
+
+Customization of existing BMad Method workflows and skills is coming soon.
+
+## Module Customization
+
+Guidance on building expansion modules and customizing existing modules is coming soon.

package/docs/how-to/established-projects.md

@@ -0,0 +1,105 @@
+---
+title: "Established Projects"
+description: How to use BMad Method on existing codebases
+sidebar:
+  order: 6
+---
+
+Use BMad Method effectively when working on existing projects and legacy codebases.
+
+This guide covers the essential workflow for onboarding to existing projects with BMad Method.
+
+:::note[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: Create Project Context
+
+:::tip[Recommended for Existing Projects]
+Generate `project-context.md` to capture your existing codebase patterns and conventions. This ensures AI agents follow your established practices when implementing changes.
+:::
+
+Run the generate project context workflow:
+
+```bash
+/bmad-bmm-generate-project-context
+```
+
+This scans your codebase to identify:
+- Technology stack and versions
+- Code organization patterns
+- Naming conventions
+- Testing approaches
+- Framework-specific patterns
+
+You can review and refine the generated file, or create it manually at `_bmad-output/project-context.md` if you prefer.
+
+[Learn more about project context](../explanation/project-context.md)
+
+## Step 3: 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: Get Help
+
+Get help to know what to do next based on your unique needs
+
+Run `bmad-help` to get guidance when you are not sure what to do next.
+
+### 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.
+
+## More Information
+
+- **[Quick Fixes](./quick-fixes.md)** - Bug fixes and ad-hoc changes
+- **[Established Projects FAQ](../explanation/established-projects-faq.md)** - Common questions about working on established projects