bmad-method 6.0.0-Beta.7 → 6.0.0-Beta.8

package/docs/explanation/established-projects-faq.md

@@ -0,0 +1,50 @@
+---
+title: "Established Projects FAQ"
+description: Common questions about using BMad Method on established projects
+sidebar:
+  order: 8
+---
+Quick answers to common questions about working on established projects with the BMad Method (BMM).
+
+## Questions
+
+- [Do I have to run document-project first?](#do-i-have-to-run-document-project-first)
+- [What if I forget to run document-project?](#what-if-i-forget-to-run-document-project)
+- [Can I use Quick Flow for established projects?](#can-i-use-quick-flow-for-established-projects)
+- [What if my existing code doesn't follow best practices?](#what-if-my-existing-code-doesnt-follow-best-practices)
+
+### Do I have to run document-project first?
+
+Highly recommended, especially if:
+
+- No existing documentation
+- Documentation is outdated
+- AI agents need context about existing code
+
+You can skip it if you have comprehensive, up-to-date documentation including `docs/index.md` or will use other tools or techniques to aid in discovery for the agent to build on an existing system.
+
+### What if I forget to run document-project?
+
+Don't worry about it - you can do it at any time. You can even do it during or after a project to help keep docs up to date.
+
+### Can I use Quick Flow for established projects?
+
+Yes! Quick Flow works great for established projects. It will:
+
+- Auto-detect your existing stack
+- Analyze existing code patterns
+- Detect conventions and ask for confirmation
+- Generate context-rich tech-spec that respects existing code
+
+Perfect for bug fixes and small features in existing codebases.
+
+### What if my existing code doesn't follow best practices?
+
+Quick Flow detects your conventions and asks: "Should I follow these existing conventions?" You decide:
+
+- **Yes** → Maintain consistency with current codebase
+- **No** → Establish new standards (document why in tech-spec)
+
+BMM respects your choice — it won't force modernization, but it will offer it.
+
+**Have a question not answered here?** Please [open an issue](https://github.com/bmad-code-org/BMAD-METHOD/issues) or ask in [Discord](https://discord.gg/gk8jAdXWmj) so we can add it!

package/docs/explanation/party-mode.md

@@ -1,6 +1,8 @@
 ---
 title: "Party Mode"
 description: Multi-agent collaboration - get all your AI agents in one conversation
+sidebar:
+  order: 7
 ---
 
 Get all your AI agents in one conversation.

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

@@ -1,6 +1,8 @@
 ---
 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.
@@ -69,7 +71,7 @@ Explicit documentation of:
 
 Think of architecture as the shared context that all agents read before implementing:
 
-```
+```text
 PRD: "What to build"
      ↓
 Architecture: "How to build it"

package/docs/explanation/quick-flow.md

@@ -1,27 +1,73 @@
 ---
 title: "Quick Flow"
 description: Fast-track for small changes - skip the full methodology
+sidebar:
+  order: 1
 ---
 
-Quick Flow is for when you don't need the full BMad Method. Skip Product Brief, PRD, and Architecture - go straight to implementation.
+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
 
-1. **Run `quick-spec`** — generates a focused tech-spec
-2. **Run `quick-dev`** — implements it
+Quick Flow has two commands, each backed by a structured workflow. You can run them together or independently.
 
-That's it.
+### quick-spec: Plan
 
-## When to Use It
+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
 
-- Bug fixes
-- Refactoring
-- Small features
-- Prototyping
+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:
 
-## When to Use Full BMad Method Instead
+- **Light escalation** - Recommends running `quick-spec` first to create a plan
+- **Heavy escalation** - Recommends switching to the full BMad Method PRD process
 
-- New products
-- Major features
-- Multiple teams involved
-- Stakeholder alignment needed
+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

@@ -1,6 +1,8 @@
 ---
 title: "Why Solutioning Matters"
 description: Understanding why the solutioning phase is critical for multi-epic projects
+sidebar:
+  order: 3
 ---
 
 
@@ -8,7 +10,7 @@ Phase 3 (Solutioning) translates **what** to build (from Planning) into **how**
 
 ## 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
@@ -18,7 +20,7 @@ When multiple agents implement different parts of a system without shared archit
 
 ## The Solution With Solutioning
 
-```
+```text
 architecture workflow decides: "Use GraphQL for all APIs"
 All agents follow architecture decisions
 Result: Consistent implementation, no conflicts

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

@@ -1,33 +1,35 @@
 ---
-title: "BMad Method Customization Guide"
+title: "How to Customize BMad"
+description: Customize agents, workflows, and modules while preserving update compatibility
+sidebar:
+  order: 7
 ---
 
-The ability to customize the BMad Method and its core to your needs, while still being able to get updates and enhancements is a critical idea within the BMad Ecosystem.
+Use the `.customize.yaml` files to tailor agent behavior, personas, and menus while preserving your changes across updates.
 
-The Customization Guidance outlined here, while targeted at understanding BMad Method customization, applies to any other module use within the BMad Method.
+## When to Use This
 
-## Types of Customization
+- 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
 
-Customization includes Agent Customization, Workflow/Skill customization, the addition of new MCPs or Skills to be used by existing agents. Aside from all of this, a whole other realm of customization involves creating / adding your own relevant BMad Builder workflows, skills, agents and maybe even your own net new modules to compliment the BMad Method Module.
+:::note[Prerequisites]
+- BMad installed in your project (see [How to Install BMad](./install-bmad.md))
+- A text editor for YAML files
+:::
 
-Warning: The reason for customizing as this guide will prescribe will allow you to continue getting updates without worrying about losing your customization changes. And by continuing to get updates as BMad modules advance, you will be able to continue to evolve as the system improves.
+:::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.
+:::
 
-## Agent Customization
+## Steps
 
-### Agent Customization Areas
+### 1. Locate Customization Files
 
-- Change agent names, personas or manner of speech
-- Add project-specific memories or context
-- Add custom menu items to custom or inline prompts, skills or custom BMad workflows
-- Define critical actions that occur agent startup for consistent behavior
+After installation, find one `.customize.yaml` file per agent in:
 
-## How to customize an agent.
-
-**1. Locate Customization Files**
-
-After installation, find agent customization files in:
-
-```
+```text
 _bmad/_config/agents/
 ├── core-bmad-master.customize.yaml
 ├── bmm-dev.customize.yaml
@@ -35,28 +37,22 @@ _bmad/_config/agents/
 └── ... (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 install
-```
+### 2. Edit the Customization File
 
-You can either then:
+Open the `.customize.yaml` file for the agent you want to modify. Every section is optional -- customize only what you need.
 
-- Select `Quick Update` - This will also ensure all packages are up to date AND compile all agents to include any updates or customizations
-- Select `Rebuild Agents` - This will only rebuild and apply customizations to agents, without pulling the latest
+| 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         |
 
-There will be additional tools shortly after beta launch to allow install of individual agents, workflows, skills and modules without the need for using the full bmad installer.
+Sections marked **Replaces** overwrite the agent's defaults entirely. Sections marked **Appends** add to the existing configuration.
 
-### What Agent Properties Can Be Customized?
-
-#### Agent Name
+**Agent Name**
 
 Change how the agent introduces itself:
 
@@ -66,7 +62,7 @@ agent:
     name: 'Spongebob' # Default: "Amelia"
 ```
 
-#### Persona
+**Persona**
 
 Replace the agent's personality, role, and communication style:
 
@@ -80,9 +76,9 @@ persona:
     - 'Favor composition over inheritance'
 ```
 
-**Note:** The persona section replaces the entire default persona (not merged).
+The `persona` section replaces the entire default persona, so include all four fields if you set it.
 
-#### Memories
+**Memories**
 
 Add persistent context the agent will always remember:
 
@@ -90,12 +86,12 @@ Add persistent context the agent will always remember:
 memories:
   - 'Works at Krusty Krab'
   - 'Favorite Celebrity: David Hasslehoff'
-  - 'Learned in Epic 1 that its not cool to just pretend that tests have passed'
+  - 'Learned in Epic 1 that it is not cool to just pretend that tests have passed'
 ```
 
-### Custom Menu Items
+**Menu Items**
 
-Any custom items you add here will be included in the agents display menu.
+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:
@@ -107,18 +103,18 @@ menu:
     description: Deploy to production
 ```
 
-### Critical Actions
+**Critical Actions**
 
-Add instructions that execute before the agent starts:
+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
+**Custom Prompts**
 
-Define reusable prompts for `action="#id"` menu handlers:
+Create reusable prompts that menu items can reference with `action="#id"`:
 
 ```yaml
 prompts:
@@ -130,29 +126,47 @@ prompts:
       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?**
 
-- 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
+- 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
-- Ensure required fields aren't left empty if you uncommented them
-- Try reverting to the template and rebuilding
+- 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?**
+**Need to reset an agent?**
 
-- Remove content from the `.customize.yaml` file (or delete the file)
-- Run `npx bmad-method build <agent-name>` to regenerate defaults
+- Clear or delete the agent's `.customize.yaml` file
+- Run `npx bmad-method install` and select **Recompile Agents** to restore defaults
 
 ## Workflow Customization
 
-Information about customizing existing BMad Method workflows and skills are coming soon.
+Customization of existing BMad Method workflows and skills is coming soon.
 
 ## Module Customization
 
-Information on how to build expansion modules that augment BMad, or make other existing module customizations are coming soon.
+Guidance on building expansion modules and customizing existing modules is coming soon.

package/docs/how-to/{brownfield/index.md → established-projects.md}

@@ -1,15 +1,13 @@
 ---
-title: "Brownfield Development"
+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.
+Use BMad Method effectively when working on existing projects and legacy codebases, sometimes also referred to as brownfield projects.
 
-## 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 guide covers the essential workflow for onboarding to brownfield projects with BMad Method.
+This guide covers the essential workflow for onboarding to existing projects with BMad Method.
 
 :::note[Prerequisites]
 - BMad Method installed (`npx bmad-method install`)
@@ -48,8 +46,8 @@ 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.                                                    |
+| **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
 
@@ -80,5 +78,5 @@ Pay close attention here to prevent reinventing the wheel or making decisions th
 
 ## More Information
 
-- **[Quick Fix in Brownfield](/docs/how-to/brownfield/quick-fix-in-brownfield.md)** - Bug fixes and ad-hoc changes
-- **[Brownfield FAQ](/docs/explanation/brownfield-faq.md)** - Common questions about brownfield development
+- **[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

package/docs/how-to/get-answers-about-bmad.md

@@ -1,6 +1,8 @@
 ---
 title: "How to Get Answers About BMad"
 description: Use an LLM to quickly answer your own BMad questions
+sidebar:
+  order: 4
 ---
 
 If you have successfully installed BMad and the BMad Method (+ other modules as needed) - the first step in getting answers is `/bmad-help`. This will answer upwards of 80% of all questions and is available to you in the IDE as you are working.
@@ -38,11 +40,10 @@ The `_bmad` folder is created when you install BMad. If you don't have it yet, c
 
 Fetch `llms-full.txt` into your session:
 
-```
+```text
 https://bmad-code-org.github.io/BMAD-METHOD/llms-full.txt
 ```
 
-See the [Downloads page](/docs/downloads.md) for other downloadable resources.
 
 ### 3. Ask Your Question
 

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

@@ -1,10 +1,14 @@
 ---
 title: "How to Install BMad"
 description: Step-by-step guide to installing BMad in your project
+sidebar:
+  order: 1
 ---
 
 Use the `npx bmad-method install` command to set up BMad in your project with your choice of modules and AI tools.
 
+If you want to use a non interactive installer and provide all install options on the command line, see [this guide](./non-interactive-installation.md).
+
 ## When to Use This
 
 - Starting a new project with BMad
@@ -25,6 +29,13 @@ Use the `npx bmad-method install` command to set up BMad in your project with yo
 npx bmad-method install
 ```
 
+:::tip[Bleeding edge]
+To install the latest from the main branch (may be unstable):
+```bash
+npx github:bmad-code-org/BMAD-METHOD install
+```
+:::
+
 ### 2. Choose Installation Location
 
 The installer will ask where to install BMad files:
@@ -39,6 +50,7 @@ Pick which AI tools you use:
 - Claude Code
 - Cursor
 - Windsurf
+- Kiro
 - Others
 
 Each tool has its own way of integrating commands. The installer creates tiny prompt files to activate workflows and agents — it just puts them where your tool expects to find them.
@@ -53,7 +65,7 @@ The installer guides you through the rest — custom content, settings, etc.
 
 ## What You Get
 
-```
+```text
 your-project/
 ├── _bmad/
 │   ├── bmm/            # Your selected modules
@@ -61,22 +73,16 @@ your-project/
 │   ├── core/           # Required core module
 │   └── ...
 ├── _bmad-output/       # Generated artifacts
-└── .claude/            # Claude Code commands (if using Claude Code)
+├── .claude/            # Claude Code commands (if using Claude Code)
+└── .kiro/              # Kiro steering files (if using Kiro)
 ```
 
 ## Verify Installation
 
 Run the `help` workflow (`/bmad-help` on most platforms) to verify everything works and see what to do next.
 
-**Latest from main branch:**
-```bash
-npx github:bmad-code-org/BMAD-METHOD install
-```
-
-Use these if you want the newest features before they're officially released. Things might break.
-
 ## Troubleshooting
 
 **Installer throws an error** — Copy-paste the output into your AI assistant and let it figure it out.
 
-**Installer worked but something doesn't work later** — Your AI needs BMad context to help. See [How to Get Answers About BMad](/docs/how-to/get-answers-about-bmad.md) for how to point your AI at the right sources.
+**Installer worked but something doesn't work later** — Your AI needs BMad context to help. See [How to Get Answers About BMad](./get-answers-about-bmad.md) for how to point your AI at the right sources.