# BMAD Method Documentation (Full) > Complete documentation for AI consumption > Generated: 2026-05-16 > Repository: https://github.com/bmad-code-org/BMAD-METHOD The BMad Method (**B**uild **M**ore **A**rchitect **D**reams) is an AI-driven development framework module within the BMad Method Ecosystem that helps you build software through the whole process from ideation and planning all the way through agentic implementation. It provides specialized AI agents, guided workflows, and intelligent planning that adapts to your project's complexity, whether you're fixing a bug or building an enterprise platform. If you're comfortable working with AI coding assistants like Claude, Cursor, or GitHub Copilot, you're ready to get started. :::note[πŸš€ V6 is Here and We're Just Getting Started!] Skills Architecture, BMad Builder v1, Dev Loop Automation, and so much more in the works. **[Check out the Roadmap β†’](/roadmap/)** ::: ## New Here? Start with a Tutorial The fastest way to understand BMad is to try it. - **[Get Started with BMad](./tutorials/getting-started.md)** β€” Install and understand how BMad works - **[Workflow Map](./reference/workflow-map.md)** β€” Visual overview of BMM phases, workflows, and context management :::tip[Just Want to Dive In?] Install BMad and use the `bmad-help` skill β€” it will guide you through everything based on your project and installed modules. ::: ## How to Use These Docs These docs are organized into four sections based on what you're trying to do: | Section | Purpose | | ----------------- | ---------------------------------------------------------------------------------------------------------- | | **Tutorials** | Learning-oriented. Step-by-step guides that walk you through building something. Start here if you're new. | | **How-To Guides** | Task-oriented. Practical guides for solving specific problems. "How do I customize an agent?" lives here. | | **Explanation** | Understanding-oriented. Deep dives into concepts and architecture. Read when you want to know *why*. | | **Reference** | Information-oriented. Technical specifications for agents, workflows, and configuration. | ## Expand and Customize Want to expand BMad with your own agents, workflows, or modules? The **[BMad Builder](https://bmad-builder-docs.bmad-method.org/)** provides the framework and tools for creating custom extensions, whether you're adding new capabilities to BMad or building entirely new modules from scratch. ## What You'll Need BMad works with any AI coding assistant that supports custom system prompts or project context. Popular options include: - **[Claude Code](https://code.claude.com)** β€” Anthropic's CLI tool (recommended) - **[Cursor](https://cursor.sh)** β€” AI-first code editor - **[Codex CLI](https://github.com/openai/codex)** β€” OpenAI's terminal coding agent You should be comfortable with basic software development concepts like version control, project structure, and agile workflows. No prior experience with BMad-style agent systems is requiredβ€”that's what these docs are for. ## Join the Community Get help, share what you're building, or contribute to BMad: - **[Discord](https://discord.gg/gk8jAdXWmj)** β€” Chat with other BMad users, ask questions, share ideas - **[GitHub](https://github.com/bmad-code-org/BMAD-METHOD)** β€” Source code, issues, and contributions - **[YouTube](https://www.youtube.com/@BMadCode)** β€” Video tutorials and walkthroughs ## Next Step Ready to dive in? **[Get Started with BMad](./tutorials/getting-started.md)** and build your first project. Build software faster using AI-powered workflows with specialized agents that guide you through planning, architecture, and implementation. ## What You'll Learn - Install and initialize BMad Method for a new project - Use **BMad-Help** β€” your intelligent guide that knows what to do next - Choose the right planning track for your project size - Progress through phases from requirements to working code - Use agents and workflows effectively :::note[Prerequisites] - **Node.js 20.12+** β€” Required for the installer - **Git** β€” Recommended for version control - **AI-powered IDE** β€” Claude Code, Cursor, or similar - **A project idea** β€” Even a simple one works for learning ::: :::tip[The Easiest Path] **Install** β†’ `npx bmad-method install` **Ask** β†’ `bmad-help what should I do first?` **Build** β†’ Let BMad-Help guide you workflow by workflow ::: ## Meet BMad-Help: Your Intelligent Guide **BMad-Help is the fastest way to get started with BMad.** You don't need to memorize workflows or phases β€” just ask, and BMad-Help will: - **Inspect your project** to see what's already been done - **Show your options** based on which modules you have installed - **Recommend what's next** β€” including the first required task - **Answer questions** like "I have a SaaS idea, where do I start?" ### How to Use BMad-Help Run it in your AI IDE by invoking the skill: ``` bmad-help ``` Or combine it with a question for context-aware guidance: ``` bmad-help I have an idea for a SaaS product, I already know all the features I want. where do I get started? ``` BMad-Help will respond with: - What's recommended for your situation - What the first required task is - What the rest of the process looks like ### It Powers Workflows Too BMad-Help doesn't just answer questions β€” **it automatically runs at the end of every workflow** to tell you exactly what to do next. No guessing, no searching docs β€” just clear guidance on the next required workflow. :::tip[Start Here] After installing BMad, invoke the `bmad-help` skill immediately. It will detect what modules you have installed and guide you to the right starting point for your project. ::: ## Understanding BMad BMad helps you build software through guided workflows with specialized AI agents. The process follows four phases: | Phase | Name | What Happens | | ----- | -------------- | ------------------------------------------------------------ | | 1 | Analysis | Brainstorming, research, product brief or PRFAQ _(optional)_ | | 2 | Planning | Create requirements (PRD or spec) | | 3 | Solutioning | Design architecture _(BMad Method/Enterprise only)_ | | 4 | Implementation | Build epic by epic, story by story | **[Open the Workflow Map](../reference/workflow-map.md)** to explore phases, workflows, and context management. Based on your project's complexity, BMad offers three planning tracks: | Track | Best For | Documents Created | | --------------- | ------------------------------------------------------ | -------------------------------------- | | **Quick Flow** | Bug fixes, simple features, clear scope (1-15 stories) | Tech-spec only | | **BMad Method** | Products, platforms, complex features (10-50+ stories) | PRD + Architecture + UX | | **Enterprise** | Compliance, multi-tenant systems (30+ stories) | PRD + Architecture + Security + DevOps | :::note Story counts are guidance, not definitions. Choose your track based on planning needs, not story math. ::: ## Installation Open a terminal in your project directory and run: ```bash npx bmad-method install ``` If you want the newest prerelease build instead of the default release channel, use `npx bmad-method@next install`. When prompted to select modules, choose **BMad Method**. The installer creates two folders: - `_bmad/` β€” agents, workflows, tasks, and configuration - `_bmad-output/` β€” empty for now, but this is where your artifacts will be saved :::tip[Your Next Step] Open your AI IDE in the project folder and run: ``` bmad-help ``` BMad-Help will detect what you've completed and recommend exactly what to do next. You can also ask it questions like "What are my options?" or "I have a SaaS idea, where should I start?" ::: :::note[How to Load Agents and Run Workflows] Each workflow has a **skill** you invoke by name in your IDE (e.g., `bmad-prd`). Your AI tool will recognize the `bmad-*` name and run it β€” you don't need to load agents separately. You can also invoke an agent skill directly for general conversation (e.g., `bmad-agent-pm` for the PM agent). ::: :::caution[Fresh Chats] Always start a fresh chat for each workflow. This prevents context limitations from causing issues. ::: ## Step 1: Create Your Plan Work through phases 1-3. **Use fresh chats for each workflow.** :::tip[Project Context (Optional)] Before starting, consider creating `project-context.md` to document your technical preferences and implementation rules. This ensures all AI agents follow your conventions throughout the project. Create it manually at `_bmad-output/project-context.md` or generate it after architecture using `bmad-generate-project-context`. [Learn more](../explanation/project-context.md). ::: ### Phase 1: Analysis (Optional) All workflows in this phase are optional. [**Not sure which to use?**](../explanation/analysis-phase.md) - **brainstorming** (`bmad-brainstorming`) β€” Guided ideation - **research** (`bmad-market-research` / `bmad-domain-research` / `bmad-technical-research`) β€” Market, domain, and technical research - **product-brief** (`bmad-product-brief`) β€” Recommended foundation document when your concept is clear - **prfaq** (`bmad-prfaq`) β€” Working Backwards challenge to stress-test and forge your product concept ### Phase 2: Planning (Required) **For BMad Method and Enterprise tracks:** 1. Run `bmad-prd` in a new chat β€” state your intent (Create / Update / Validate) or let the skill ask 2. Output: `prd.md`, `addendum.md`, `decision-log.md` :::note[`bmad-prd` intents] - **Create** β€” coached discovery from scratch; the skill names the workspace folder and guides you to a PRD you're proud of - **Update** β€” point it at an existing PRD and a change signal; it surfaces conflicts before applying changes - **Validate** β€” critique a finished PRD against a checklist and produce an HTML findings report ::: **For Quick Flow track:** - Run `bmad-quick-dev` β€” it handles planning and implementation in a single workflow, skip to implementation :::note[UX Design (Optional)] If your project has a user interface, invoke the **UX-Designer agent** (`bmad-agent-ux-designer`) and run the UX design workflow (`bmad-create-ux-design`) after creating your PRD. ::: ### Phase 3: Solutioning (BMad Method/Enterprise) **Create Architecture** 1. Invoke the **Architect agent** (`bmad-agent-architect`) in a new chat 2. Run `bmad-create-architecture` (`bmad-create-architecture`) 3. Output: Architecture document with technical decisions **Create Epics and Stories** :::tip[V6 Improvement] Epics and stories are now created _after_ architecture. This produces better quality stories because architecture decisions (database, API patterns, tech stack) directly affect how work should be broken down. ::: 1. Invoke the **PM agent** (`bmad-agent-pm`) in a new chat 2. Run `bmad-create-epics-and-stories` (`bmad-create-epics-and-stories`) 3. The workflow uses both PRD and Architecture to create technically-informed stories **Implementation Readiness Check** _(Highly Recommended)_ 1. Invoke the **Architect agent** (`bmad-agent-architect`) in a new chat 2. Run `bmad-check-implementation-readiness` (`bmad-check-implementation-readiness`) 3. Validates cohesion across all planning documents ## Step 2: Build Your Project Once planning is complete, move to implementation. **Each workflow should run in a fresh chat.** ### Initialize Sprint Planning Invoke the **Developer agent** (`bmad-agent-dev`) and run `bmad-sprint-planning` (`bmad-sprint-planning`). This creates `sprint-status.yaml` to track all epics and stories. ### The Build Cycle For each story, repeat this cycle with fresh chats: | Step | Agent | Workflow | Command | Purpose | | ---- | ----- | ------------------- | ------------------- | ---------------------------------- | | 1 | DEV | `bmad-create-story` | `bmad-create-story` | Create story file from epic | | 2 | DEV | `bmad-dev-story` | `bmad-dev-story` | Implement the story | | 3 | DEV | `bmad-code-review` | `bmad-code-review` | Quality validation _(recommended)_ | After completing all stories in an epic, invoke the **Developer agent** (`bmad-agent-dev`) and run `bmad-retrospective` (`bmad-retrospective`). ## What You've Accomplished You've learned the foundation of building with BMad: - Installed BMad and configured it for your IDE - Initialized a project with your chosen planning track - Created planning documents (PRD, Architecture, Epics & Stories) - Understood the build cycle for implementation Your project now has: ```text your-project/ β”œβ”€β”€ _bmad/ # BMad configuration β”œβ”€β”€ _bmad-output/ β”‚ β”œβ”€β”€ planning-artifacts/ β”‚ β”‚ β”œβ”€β”€ PRD.md # Your requirements document β”‚ β”‚ β”œβ”€β”€ architecture.md # Technical decisions β”‚ β”‚ └── epics/ # Epic and story files β”‚ β”œβ”€β”€ implementation-artifacts/ β”‚ β”‚ └── sprint-status.yaml # Sprint tracking β”‚ └── project-context.md # Implementation rules (optional) └── ... ``` ## Quick Reference | Workflow | Command | Agent | Purpose | | ------------------------------------- | ------------------------------------- | --------- | ------------------------------------------ | | **`bmad-help`** ⭐ | `bmad-help` | Any | **Your intelligent guide β€” ask anything!** | | `bmad-prd` | `bmad-prd` | Any | Create, update, or validate a PRD | | `bmad-create-architecture` | `bmad-create-architecture` | Architect | Create architecture document | | `bmad-generate-project-context` | `bmad-generate-project-context` | Analyst | Create project context file | | `bmad-create-epics-and-stories` | `bmad-create-epics-and-stories` | PM | Break down PRD into epics | | `bmad-check-implementation-readiness` | `bmad-check-implementation-readiness` | Architect | Validate planning cohesion | | `bmad-sprint-planning` | `bmad-sprint-planning` | DEV | Initialize sprint tracking | | `bmad-create-story` | `bmad-create-story` | DEV | Create a story file | | `bmad-dev-story` | `bmad-dev-story` | DEV | Implement a story | | `bmad-code-review` | `bmad-code-review` | DEV | Review implemented code | ## Common Questions **Do I always need architecture?** Only for BMad Method and Enterprise tracks. Quick Flow skips from spec to implementation. **Can I change my plan later?** Yes. The `bmad-correct-course` workflow handles scope changes mid-implementation. **What if I want to brainstorm first?** Invoke the Analyst agent (`bmad-agent-analyst`) and run `bmad-brainstorming` (`bmad-brainstorming`) before starting your PRD. **Do I need to follow a strict order?** Not strictly. Once you learn the flow, you can run workflows directly using the Quick Reference above. ## Getting Help :::tip[First Stop: BMad-Help] **Invoke `bmad-help` anytime** β€” it's the fastest way to get unstuck. Ask it anything: - "What should I do after installing?" - "I'm stuck on workflow X" - "What are my options for Y?" - "Show me what's been done so far" BMad-Help inspects your project, detects what you've completed, and tells you exactly what to do next. ::: - **During workflows** β€” Agents guide you with questions and explanations - **Community** β€” [Discord](https://discord.gg/gk8jAdXWmj) (#bmad-method-help, #report-bugs-and-issues) ## Key Takeaways :::tip[Remember These] - **Start with `bmad-help`** β€” Your intelligent guide that knows your project and options - **Always use fresh chats** β€” Start a new chat for each workflow - **Track matters** β€” Quick Flow uses `bmad-quick-dev`; Method/Enterprise need PRD and architecture - **BMad-Help runs automatically** β€” Every workflow ends with guidance on what's next ::: Ready to start? Install BMad, invoke `bmad-help`, and let your intelligent guide lead the way. Tailor agent personas, inject domain context, add capabilities, and configure workflow behavior -- all without modifying installed files. Your customizations survive every update. :::tip[Don't want to hand-author TOML? Use `bmad-customize`] The `bmad-customize` skill is a guided authoring helper for the **per-skill agent/workflow override surface** described in this doc. It scans what's customizable in your installation, helps you choose the right surface (agent vs workflow) for your intent, writes the override file for you, and verifies the merge landed. Central-config overrides (`_bmad/custom/config.toml`) are out of scope for v1 β€” hand-author those per the Central Configuration section below. Run the skill whenever you want to make a per-skill change; this doc is the reference for *what* each surface exposes and how merging works. ::: ## When to Use This - You want to change an agent's personality or communication style - You need to give an agent persistent facts to recall (e.g. "our org is AWS-only") - You want to add procedural startup steps the agent must run every session - You want to add custom menu items that trigger your own skills or prompts - Your team needs shared customizations committed to git, with personal preferences layered on top :::note[Prerequisites] - BMad installed in your project (see [How to Install BMad](./install-bmad.md)) - Python 3.11+ on your PATH (for the resolver script -- uses stdlib `tomllib`, no `pip install`, no `uv`, no virtualenv) - A text editor for TOML files ::: ## How It Works Every customizable skill ships a `customize.toml` file with its defaults. This file defines the skill's complete customization surface -- read it to see what's customizable. You never edit this file. Instead, you create sparse override files containing only the fields you want to change. ### Three-Layer Override Model ```text Priority 1 (wins): _bmad/custom/{skill-name}.user.toml (personal, gitignored) Priority 2: _bmad/custom/{skill-name}.toml (team/org, committed) Priority 3 (last): skill's own customize.toml (defaults) ``` The `_bmad/custom/` folder starts empty. Files only appear when someone actively customizes. ### Merge Rules (by shape, not by field name) The resolver applies four structural rules. Field names are never special-cased β€” behavior is determined purely by the value's shape: | Shape | Rule | |---|---| | Scalar (string, int, bool, float) | Override wins | | Table | Deep merge (recursively apply these rules) | | Array of tables where every item shares the **same** identifier field (every item has `code`, or every item has `id`) | Merge by that key β€” matching keys **replace in place**, new keys **append** | | Any other array (scalars; tables with no identifier; arrays that mix `code` and `id` across items) | **Append** β€” base items first, then team items, then user items | **No removal mechanism.** Overrides cannot delete base items. If you need to suppress a default menu item, override it by `code` with a no-op description or prompt. If you need to restructure an array more deeply, fork the skill. **The `code` / `id` convention.** BMad uses `code` (short identifier like `"BP"` or `"R1"`) and `id` (longer stable identifier) as merge keys on arrays of tables. If you author a custom array-of-tables that should be replaceable-by-key rather than append-only, pick **one** convention (either `code` on every item, or `id` on every item) and stick with it across the whole array. Mixing `code` on some items and `id` on others falls back to append β€” the resolver won't guess which key to merge on. ### Some agent fields are read-only `agent.name` and `agent.title` live in `customize.toml` as source-of-truth metadata, but the agent's SKILL.md doesn't read them at runtime β€” they're hardcoded identity. Putting `name = "Bob"` in an override file has no effect. If you genuinely need a different-named agent, copy the skill folder, rename it, and ship it as a custom skill. ## Steps ### 1. Find the Skill's Customization Surface Look at the skill's `customize.toml` in its installed directory. For example, the PM agent: ```text .claude/skills/bmad-agent-pm/customize.toml ``` (Path varies by IDE -- Cursor uses `.cursor/skills/`, Cline uses `.cline/skills/`, and so on.) This file is the canonical schema. Every field you see is customizable (excluding the read-only identity fields noted above). ### 2. Create Your Override File Create the `_bmad/custom/` directory in your project root if it doesn't exist. Then create a file named after the skill: ```text _bmad/custom/ bmad-agent-pm.toml # team overrides (committed to git) bmad-agent-pm.user.toml # personal preferences (gitignored) ``` :::caution[Do NOT copy the whole `customize.toml`] Override files are **sparse**. Include only the fields you're changing β€” nothing else. Every field you omit is inherited automatically from the layer below (team from defaults, user from team-or-defaults). Copying the full `customize.toml` into an override is actively harmful: the next update ships new defaults, but your override file locks in the old values. You'll silently drift out of sync with every release. ::: **Example β€” changing the icon and adding one principle**: ```toml # _bmad/custom/bmad-agent-pm.toml # Just the fields I'm changing. Everything else inherits. [agent] icon = "πŸ₯" principles = [ "Ship nothing that can't pass an FDA audit.", ] ``` This appends the new principle to the defaults (leaving the shipped principles intact) and replaces the icon. Every other field stays as shipped. ### 3. Customize What You Need All examples below assume BMad's flat agent schema. Fields live directly under `[agent]` β€” no nested `metadata` or `persona` sub-tables. **Scalars (icon, role, identity, communication_style).** Scalar overrides win. You only need to set the fields you're changing: ```toml # _bmad/custom/bmad-agent-pm.toml [agent] icon = "πŸ₯" role = "Drives product discovery for a regulated healthcare domain." communication_style = "Precise, regulatory-aware, asks compliance-shaped questions early." ``` **Persistent facts, principles, activation hooks (append arrays).** All four arrays below are append-only. Team items run after defaults, user items run last. ```toml [agent] # Static facts the agent keeps in mind the whole session β€” org rules, domain # constants, user preferences. Distinct from the runtime memory sidecar. # # Each entry is either a literal sentence, or a `file:` reference whose # contents are loaded as facts (glob patterns supported). persistent_facts = [ "Our org is AWS-only -- do not propose GCP or Azure.", "All PRDs require legal sign-off before engineering kickoff.", "Target users are clinicians, not patients -- frame examples accordingly.", "file:{project-root}/docs/compliance/hipaa-overview.md", "file:{project-root}/_bmad/custom/company-glossary.md", ] # Adds to the agent's value system principles = [ "Ship nothing that can't pass an FDA audit.", "User value first, compliance always.", ] # Runs BEFORE the standard activation (persona, persistent_facts, config, greet). # Use for pre-flight loads, compliance checks, anything that needs to be in # context before the agent introduces itself. activation_steps_prepend = [ "Scan {project-root}/docs/compliance/ and load any HIPAA-related documents as context.", ] # Runs AFTER greet, BEFORE the menu. Use for context-heavy setup that should # happen once the user has been acknowledged. activation_steps_append = [ "Read {project-root}/_bmad/custom/company-glossary.md if it exists.", ] ``` **The two hooks do different jobs.** Prepend runs before greeting so the agent can load context it needs to personalize the greeting itself. Append runs after greeting so the user isn't staring at a blank terminal while heavy scans complete. **Menu customization (merge by `code`).** The menu is an array of tables. Each item has a `code` field (BMad convention), so the resolver merges by code: matching codes replace in place, new codes append. TOML array-of-tables syntax uses `[[agent.menu]]` for each item: ```toml # Replace the existing CE item with a custom skill [[agent.menu]] code = "CE" description = "Create Epics using our delivery framework" skill = "custom-create-epics" # Add a new item (code RC doesn't exist in defaults) [[agent.menu]] code = "RC" description = "Run compliance pre-check" prompt = """ Read {project-root}/_bmad/custom/compliance-checklist.md and scan all documents in {planning_artifacts} against it. Report any gaps and cite the relevant regulatory section. """ ``` Each menu item has exactly one of `skill` (invokes a registered skill) or `prompt` (executes the text directly). Items not listed in your override keep their defaults. **Referencing files.** When a field's text needs to point at a file (in `persistent_facts`, `activation_steps_prepend`/`activation_steps_append`, or a menu item's `prompt`), use a full path rooted at `{project-root}`. Even if the file sits next to your override in `_bmad/custom/`, spell out the full path: `{project-root}/_bmad/custom/info.md`. The agent resolves `{project-root}` at runtime. ### 4. Personal vs Team **Team file** (`bmad-agent-pm.toml`): Committed to git. Shared across the org. Use for compliance rules, company persona, custom capabilities. **Personal file** (`bmad-agent-pm.user.toml`): Gitignored automatically. Use for tone adjustments, personal workflow preferences, and private facts the agent should keep in mind. ```toml # _bmad/custom/bmad-agent-pm.user.toml [agent] persistent_facts = [ "Always include a rough complexity estimate (low/medium/high) when presenting options.", ] ``` ## How Resolution Works On activation, the agent's SKILL.md runs a shared Python script that does the three-layer merge and returns the resolved block as JSON. The script uses the Python standard library's `tomllib` module (no external dependencies), so plain `python3` is enough: ```bash python3 {project-root}/_bmad/scripts/resolve_customization.py \ --skill {skill-root} \ --key agent ``` **Requirements**: Python 3.11+ (earlier versions don't include `tomllib`). No `pip install`, no `uv`, no virtualenv. Check with `python3 --version`. Some platforms (macOS without Homebrew, Ubuntu 22.04) default `python3` to 3.10 or earlier, so you may need to install 3.11+ separately. `--skill` points at the skill's installed directory (where `customize.toml` lives). The skill name is derived from the directory's basename, and the script looks up `_bmad/custom/{skill-name}.toml` and `{skill-name}.user.toml` automatically. Useful invocations: ```bash # Resolve the full agent block python3 {project-root}/_bmad/scripts/resolve_customization.py \ --skill /abs/path/to/bmad-agent-pm \ --key agent # Resolve a single field python3 {project-root}/_bmad/scripts/resolve_customization.py \ --skill /abs/path/to/bmad-agent-pm \ --key agent.icon # Full dump python3 {project-root}/_bmad/scripts/resolve_customization.py \ --skill /abs/path/to/bmad-agent-pm ``` Output is always JSON. If the script is unavailable on a given platform, the SKILL.md tells the agent to read the three TOML files directly and apply the same merge rules. ## Workflow Customization Workflows (skills that drive multi-step processes like `bmad-product-brief`) share the same override mechanism as agents. Their customizable surface lives under `[workflow]` instead of `[agent]`: ```toml # _bmad/custom/bmad-product-brief.toml [workflow] # Same prepend/append semantics as agents β€” runs before and after the workflow's # own activation steps. Overrides append to defaults. activation_steps_prepend = [ "Load {project-root}/docs/product/north-star-principles.md as context.", ] activation_steps_append = [] # Same literal-or-file: semantics as the agent variant. Loaded as foundational # context for the duration of the workflow run. persistent_facts = [ "All briefs must include an explicit regulatory-risk section.", "file:{project-root}/docs/compliance/product-brief-checklist.md", ] # Scalar: runs once the workflow finishes its main output. Override wins. on_complete = "Summarize the brief in three bullets and offer to email it via the gws-gmail-send skill." ``` The same field conventions cross the agent/workflow boundary: `activation_steps_prepend`/`activation_steps_append`, `persistent_facts` (with `file:` refs), and menu-style `[[…]]` tables with `code`/`id` for keyed merge. The resolver applies the same four structural rules regardless of the top-level key. SKILL.md references follow the namespace: `{workflow.activation_steps_prepend}`, `{workflow.persistent_facts}`, `{workflow.on_complete}`. Any additional fields a workflow exposes (output paths, toggles, review settings, stage flags) follow the same shape-based merge rules. Read the workflow's `customize.toml` to see what's customizable. ### Activation Order Customizable workflows run their activation in a fixed sequence so you know exactly when your hooks fire: 1. Resolve the `[workflow]` block (base β†’ team β†’ user merge) 2. Execute `activation_steps_prepend` in order 3. Load `persistent_facts` as foundational context for the run 4. Load config (`_bmad/bmm/config.yaml`) and resolve standard variables (project name, languages, paths, date) 5. Greet the user 6. Execute `activation_steps_append` in order After step 6 the workflow body begins. Use `activation_steps_prepend` when you need context loaded before the greeting can be personalized; use `activation_steps_append` when the setup is heavy and you'd rather the user sees the greeting first. ### Scope of This Initial Pass Customization is rolling out incrementally. The fields documented above β€” `activation_steps_prepend`, `activation_steps_append`, `persistent_facts`, `on_complete` β€” are the **baseline surface** that every customizable workflow exposes, and they will remain stable across versions. They give you broad-stroke control today: inject pre/post steps, pin foundational context, trigger follow-up actions. Over time, individual workflows will expose **more targeted customization points** tailored to what that workflow actually does β€” things like step-specific toggles, stage flags, output template paths, or review gates. When those arrive, they stack on top of the baseline fields rather than replacing them, so customizations you author today keep working. If you need a fine-grained knob that isn't exposed yet, either use `activation_steps_*` and `persistent_facts` to steer behavior, or open an issue describing the specific customization point you want β€” those requests are what drive which targeted fields get added next. ## Central Configuration Per-skill `customize.toml` covers **deep behavior** (hooks, menus, persistent_facts, persona overrides for a single agent or workflow). A separate surface covers **cross-cutting state** β€” install answers and the agent roster that external skills like `bmad-party-mode`, `bmad-retrospective`, and `bmad-advanced-elicitation` consume. That surface lives in four TOML files at project root: ```text _bmad/config.toml (installer-owned) team scope: install answers + agent roster _bmad/config.user.toml (installer-owned) user scope: user_name, language, skill level _bmad/custom/config.toml (human-authored) team overrides (committed to git) _bmad/custom/config.user.toml (human-authored) personal overrides (gitignored) ``` ### Four-Layer Merge ```text Priority 1 (wins): _bmad/custom/config.user.toml Priority 2: _bmad/custom/config.toml Priority 3: _bmad/config.user.toml Priority 4 (base): _bmad/config.toml ``` Same structural rules as per-skill customize (scalars override, tables deep-merge, `code`/`id`-keyed arrays merge by key, other arrays append). ### What Lives Where The installer partitions answers by the `scope:` declared on each prompt in `module.yaml`: - `[core]` and `[modules.]` sections β€” install answers. Scope `team` lands in `_bmad/config.toml`; scope `user` lands in `_bmad/config.user.toml`. - `[agents.]` β€” agent essence (code, name, title, icon, description, team) distilled from each module's `module.yaml` `agents:` block. Always team-scoped. ### Editing Rules - `_bmad/config.toml` and `_bmad/config.user.toml` are **regenerated every install** from the answers collected during the installer flow. Treat them as read-only outputs β€” direct edits will be overwritten on the next install. To change an install answer durably, re-run the installer (it remembers your prior answers as defaults) or shadow the value in `_bmad/custom/config.toml`. - `_bmad/custom/config.toml` and `_bmad/custom/config.user.toml` are **never touched** by the installer. This is the correct surface for custom agents, agent descriptor overrides, team-enforced settings, and any value you want to pin regardless of install answers. ### Example β€” Rebrand an Agent ```toml # _bmad/custom/config.toml (committed to git, applies to every developer) [agents.bmad-agent-pm] description = "Healthcare PM β€” regulatory-aware, stakeholder-driven, FDA-shaped questions first." icon = "πŸ₯" ``` The resolver merges over the installer-written `[agents.bmad-agent-pm]`. `bmad-party-mode` and any other roster consumer pick up the new description automatically. ### Example β€” Add a Fictional Agent ```toml # _bmad/custom/config.user.toml (personal, gitignored) [agents.kirk] team = "startrek" name = "Captain James T. Kirk" title = "Starship Captain" icon = "πŸ––" description = "Bold, rule-bending commander. Speaks in dramatic pauses. Thinks aloud about the weight of command." ``` No skill folder required β€” the essence alone is enough for party-mode to spawn Kirk as a voice. Filter by the `team` field to invite just the Enterprise crew to a roundtable. ### Example β€” Override Module Install Settings ```toml # _bmad/custom/config.toml [modules.bmm] planning_artifacts = "/shared/org-planning-artifacts" ``` The override wins over whatever each developer answered during their local install. Useful for pinning team conventions. ### When to Use Which Surface | Need | Use | |---|---| | Add MCP tool calls to every dev workflow | Per-skill: `_bmad/custom/bmad-agent-dev.toml` `persistent_facts` | | Add a menu item to an agent | Per-skill: `_bmad/custom/bmad-agent-{role}.toml` `[[agent.menu]]` | | Swap a workflow's output template | Per-skill: `_bmad/custom/{workflow}.toml` scalar override | | Rebrand an agent's public descriptor | **Central**: `_bmad/custom/config.toml` `[agents.]` | | Add a custom or fictional agent to the roster | **Central**: `_bmad/custom/config.*.toml` new `[agents.]` entry | | Pin team-enforced install settings | **Central**: `_bmad/custom/config.toml` `[modules.]` or `[core]` | Use both surfaces in the same project as needed. ## Worked Examples For enterprise-oriented recipes (shaping an agent across every workflow it dispatches, enforcing org conventions, publishing outputs to Confluence and Jira, customizing the agent roster, and swapping in your own output templates), see [How to Expand BMad for Your Organization](./expand-bmad-for-your-org.md). ## Troubleshooting **Customization not appearing?** - Verify your file is in `_bmad/custom/` with the correct skill name - Check TOML syntax: strings must be quoted, table headers use `[section]`, array-of-tables use `[[section]]`, and any scalar or array keys for a table must appear *before* any of that table's `[[subtables]]` in the file - For agents, customization lives under `[agent]` -- fields written below that header belong to `agent` until another table header begins - Remember `agent.name` and `agent.title` are read-only; overrides there have no effect **Updates broke my customization?** - Did you copy the full `customize.toml` into your override file? **Don't.** Override files should contain only the fields you're changing. A full copy locks in old defaults and silently drifts every release. Trim your override back to just the deltas. **Need to see what's customizable?** - Run the `bmad-customize` skill β€” it enumerates every customizable skill installed in your project, shows which ones already have overrides, and walks you through adding or updating one - Or read the skill's `customize.toml` directly β€” every field there is customizable (except `name` and `title`) **Need to reset?** - Delete your override file from `_bmad/custom/` -- the skill falls back to its built-in defaults 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 or Cursor) ::: ## 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-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 `bmad-document-project` workflow. It offers runtime variants that will scan your entire project and document its actual current state. ## Step 3: Get Help ### BMad-Help: Your Starting Point **Run `bmad-help` anytime you're unsure what to do next.** This intelligent guide: - Inspects your project to see what's already been done - Shows options based on your installed modules - Understands natural language queries ``` bmad-help I have an existing Rails app, where should I start? bmad-help What's the difference between quick-flow and full method? bmad-help Show me what workflows are available ``` BMad-Help also **automatically runs at the end of every workflow**, providing clear guidance on exactly 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** | Run `bmad-quick-dev` to clarify intent, plan, implement, and review in a single workflow. 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 BMad's customization surface lets an organization reshape behavior without editing installed files or forking skills. This guide walks through six recipes that cover most enterprise needs. :::note[Prerequisites] - BMad installed in your project (see [How to Install BMad](./install-bmad.md)) - Familiarity with the customization model (see [How to Customize BMad](./customize-bmad.md)) - Python 3.11+ on PATH (for the resolver β€” stdlib only, no `pip install`) ::: :::tip[Applying these recipes] The **per-skill recipes** below (Recipes 1–4) can be applied by running the `bmad-customize` skill and describing the intent β€” it will pick the right surface, author the override file, and verify the merge. Recipe 5 (central-config overrides to the agent roster) is out of scope for v1 of the skill and remains hand-authored. The recipes here are the source of truth for *what* to override; `bmad-customize` handles the *how* for the agent/workflow surface. ::: ## The Three-Layer Mental Model Before picking a recipe, know where your override lands: | Layer | Where overrides live | Scope | |---|---|---| | **Agent** (e.g. Amelia, Mary, John) | `[agent]` section of `_bmad/custom/bmad-agent-{role}.toml` | Travels with the persona into **every workflow the agent dispatches** | | **Workflow** (e.g. product-brief, create-prd) | `[workflow]` section of `_bmad/custom/{workflow-name}.toml` | Applies only to that workflow's run | | **Central config** | `[agents.*]`, `[core]`, `[modules.*]` in `_bmad/custom/config.toml` | Agent roster (who's available for party-mode, retrospective, elicitation), install-time settings pinned org-wide | Rule of thumb: if the rule should apply everywhere an engineer does dev work, customize the **dev agent**. If it applies only when someone writes a product brief, customize the **product-brief workflow**. If it changes *who's in the room* (rename an agent, add a custom voice, enforce a shared artifact path), edit **central config**. ## Recipe 1: Shape an Agent Across Every Workflow It Dispatches **Use case:** Standardize tool use and external system integrations so every workflow dispatched through an agent inherits the behavior. This is the highest-impact pattern. **Example: Amelia (dev agent) always uses Context7 for library docs, and falls back to Linear when a story isn't found in the epics list.** ```toml # _bmad/custom/bmad-agent-dev.toml [agent] # Applied on every activation. Carries into dev-story, quick-dev, # create-story, code-review, qa-generate β€” every skill Amelia dispatches. persistent_facts = [ "For any library documentation lookup (React, TypeScript, Zod, Prisma, etc.), call the context7 MCP tool (`mcp__context7__resolve_library_id` then `mcp__context7__get_library_docs`) before relying on training-data knowledge. Up-to-date docs trump memorized APIs.", "When a story reference isn't found in {planning_artifacts}/epics-and-stories.md, search Linear via `mcp__linear__search_issues` using the story ID or title before asking the user to clarify. If Linear returns a match, treat it as the authoritative story source.", ] ``` **Why this works:** Two sentences reshape every dev workflow in the org, with no per-workflow duplication and no source changes. Every new engineer who pulls the repo inherits the conventions automatically. **Team file vs personal file:** - `bmad-agent-dev.toml`: committed to git; applies to the whole team - `bmad-agent-dev.user.toml`: gitignored; personal preferences layered on top ## Recipe 2: Enforce Organizational Conventions Inside a Specific Workflow **Use case:** Shape the *content* of a workflow's output so it meets compliance, audit, or downstream-consumer requirements. **Example: every product brief must include compliance fields, and the agent knows about the org's publishing conventions.** ```toml # _bmad/custom/bmad-product-brief.toml [workflow] persistent_facts = [ "Every brief must include an 'Owner' field, a 'Target Release' field, and a 'Security Review Status' field.", "Non-commercial briefs (internal tools, research projects) must still include a user-value section, but can omit market differentiation.", "file:{project-root}/docs/enterprise/brief-publishing-conventions.md", ] ``` **What happens:** The facts load during Step 3 of the workflow's activation. When the agent drafts the brief, it knows the required fields and the enterprise conventions document. The shipped default (`file:{project-root}/**/project-context.md`) still loads, since this is an append. ## Recipe 3: Publish Completed Outputs to External Systems **Use case:** Once the workflow produces its output, automatically publish to enterprise systems of record (Confluence, Notion, SharePoint) and open follow-up work (Jira, Linear, Asana). **Example: briefs auto-publish to Confluence and offer optional Jira epic creation.** ```toml # _bmad/custom/bmad-product-brief.toml [workflow] # Terminal hook. Scalar override replaces the empty default wholesale. on_complete = """ Publish and offer follow-up: 1. Read the finalized brief file path from the prior step. 2. Call `mcp__atlassian__confluence_create_page` with: - space: "PRODUCT" - parent: "Product Briefs" - title: the brief's title - body: the brief's markdown contents Capture the returned page URL. 3. Tell the user: "Brief published to Confluence: ". 4. Ask: "Want me to open a Jira epic for this brief now?" 5. If yes, call `mcp__atlassian__jira_create_issue` with: - type: "Epic" - project: "PROD" - summary: the brief's title - description: a short summary plus a link back to the Confluence page. Report the epic key and URL. 6. If no, exit cleanly. If either MCP tool fails, report the failure, print the brief path, and ask the user to publish manually. """ ``` **Why `on_complete` and not `activation_steps_append`:** `on_complete` runs exactly once, at the terminal stage, after the workflow's main output is written. That's the right moment to publish artifacts. `activation_steps_append` runs every activation, before the workflow does its work. **Tradeoffs:** - **Confluence publication is non-destructive** and always runs on completion - **Jira epic creation is visible to the whole team** and kicks off sprint-planning signals, so gate it on user confirmation - **Graceful fallback:** if MCP tools fail, hand off to the user rather than silently dropping the output ## Recipe 4: Swap in Your Own Output Template **Use case:** The default output structure doesn't match your organization's expected format, or different orgs in the same repo need different templates. **Example: point the product-brief workflow at an enterprise-owned template.** ```toml # _bmad/custom/bmad-product-brief.toml [workflow] brief_template = "{project-root}/docs/enterprise/brief-template.md" ``` **How it works:** The workflow's `customize.toml` ships with `brief_template = "resources/brief-template.md"` (bare path, resolves from skill root). Your override points at a file under `{project-root}`, so the agent reads your template in Stage 4 instead of the shipped one. **Template authoring tips:** - Keep templates in `{project-root}/docs/` or `{project-root}/_bmad/custom/templates/` so they version alongside the override file - Use the same structural conventions as the shipped template (section headings, frontmatter); the agent adapts to what's there - For multi-org repos, use `.user.toml` to let individual teams point at their own templates without touching the committed team file ## Recipe 5: Customize the Agent Roster **Use case:** Change *who's in the room* for roster-driven skills like `bmad-party-mode`, `bmad-retrospective`, and `bmad-advanced-elicitation`, without editing any source or forking. Three common variants follow. ### 5a. Rebrand a BMad Agent Org-Wide Every real agent has a descriptor the installer synthesizes from `module.yaml`. Override it to shift voice and framing across every roster consumer: ```toml # _bmad/custom/config.toml (committed β€” applies to every developer) [agents.bmad-agent-analyst] description = "Mary the Regulatory-Aware Business Analyst β€” channels Porter and Minto, but lives and breathes FDA audit trails. Speaks like a forensic investigator presenting a case file." ``` Party-mode spawns Mary with the new description. The analyst activation itself still runs normally because Mary's behavior lives in her per-skill `customize.toml`. This override changes how **external skills perceive and introduce her**, not how she works internally. ### 5b. Add a Fictional or Custom Agent A full descriptor is enough for roster-based features, with no skill folder needed. Useful for personality variety in party mode or brainstorming sessions: ```toml # _bmad/custom/config.user.toml (personal β€” gitignored) [agents.spock] team = "startrek" name = "Commander Spock" title = "Science Officer" icon = "πŸ––" description = "Logic first, emotion suppressed. Begins observations with 'Fascinating.' Never rounds up. Counterpoint to any argument that relies on gut instinct." [agents.mccoy] team = "startrek" name = "Dr. Leonard McCoy" title = "Chief Medical Officer" icon = "βš•οΈ" description = "Country doctor's warmth, short fuse. 'Dammit Jim, I'm a doctor not a ___.' Ethics-driven counterweight to Spock." ``` Ask party-mode to "invite the Enterprise crew." It filters by `team = "startrek"` and spawns Spock and McCoy with those descriptors. Real BMad agents (Mary, Amelia) can sit at the same table if you ask them to. ### 5c. Pin Team Install Settings The installer prompts each developer for values like `planning_artifacts` path. When the org needs one shared answer across the team, pin it in central config β€” any developer's local prompt answer gets overridden at resolution time: ```toml # _bmad/custom/config.toml [modules.bmm] planning_artifacts = "{project-root}/shared/planning" implementation_artifacts = "{project-root}/shared/implementation" [core] document_output_language = "English" ``` Personal settings like `user_name`, `communication_language`, or `user_skill_level` stay under each developer's own `_bmad/config.user.toml`. The team file shouldn't touch those. **Why central config vs per-agent customize.toml:** Per-agent files shape how *one* agent behaves when it activates. Central config shapes what roster consumers *see when they look at the field:* which agents exist, what they're called, what team they belong to, and the shared install settings the whole repo agrees on. Two surfaces, different jobs. ## Reinforce Global Rules in Your IDE's Session File BMad customizations load when a skill is activated. Many IDE tools also load a global instruction file at the **start of every session**, before any skill runs (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules/`, `.github/copilot-instructions.md`, etc). For rules that should hold even outside BMad skills, restate the critical ones there too. **When to double up:** - A rule is important enough that a plain chat conversation (no skill active) should still follow it - You want belt-and-suspenders enforcement because training-data defaults might otherwise pull the model off-course - The rule is concise enough to repeat without bloating the session file **Example: one line in the repo's `CLAUDE.md` reinforcing the dev-agent rule from Recipe 1.** ```markdown ``` One sentence, loaded every session. It pairs with the `bmad-agent-dev.toml` customization so the rule applies both inside Amelia's workflows and during ad-hoc chats with the assistant. Each layer owns its own scope: | Layer | Scope | Use for | |---|---|---| | IDE session file (`CLAUDE.md` / `AGENTS.md`) | Every session, before any skill activates | Short, universal rules that should survive outside BMad | | BMad agent customization | Every workflow the agent dispatches | Agent-persona-specific behavior | | BMad workflow customization | One workflow run | Workflow-specific output shape, publishing hooks, templates | | BMad central config | Agent roster + shared install settings | Who's in the room and what shared paths the team uses | Keep the IDE file **succinct**. A dozen well-chosen lines are more effective than a sprawling list. Models read it every turn, and noise crowds out signal. ## Recipe 6: Advanced Integration Patterns Several BMad workflows expose a richer configuration surface beyond the basics covered in Recipes 1–5. These patterns β€” on-demand knowledge sources, automatic output publishing, finalize-time doc standards, and swappable templates β€” appear across multiple workflows. Check a workflow's `customize.toml` to see which fields it exposes; the examples below use `bmad-prd` because it exposes all of them, but the same patterns apply wherever the field appears. ### On-demand knowledge sources (`external_sources`) Connect the workflow to internal knowledge bases, competitive databases, or compliance references. The agent consults these on demand when the conversation surfaces a matching need β€” never preemptively. ```toml # _bmad/custom/bmad-prd.toml (same pattern works in any workflow that exposes external_sources) [workflow] external_sources = [ "When the user mentions a competitor or market segment, query corp:competitive_db (category={project_name}) before drafting the differentiation section.", "For regulatory domains (healthcare, fintech, education), consult corp:compliance_reference before drafting domain-specific sections.", ] ``` Each entry is a natural-language directive naming the MCP tool, the trigger condition, and any fields the tool needs. If the tool is unavailable at runtime, the workflow falls back to standard behavior and notes the gap. ### Automatic output publishing (`external_handoffs`) Route completed artifacts to external systems of record after the workflow finalizes. Unlike `on_complete` (Recipe 3), `external_handoffs` is a dedicated append array β€” team entries stack, and each handoff fires independently with graceful degradation if a tool is unavailable. ```toml # _bmad/custom/bmad-prd.toml (same pattern works in any workflow that exposes external_handoffs) [workflow] external_handoffs = [ "After finalize, upload prd.md and addendum.md to Confluence via corp:confluence_upload (space_key='PROD', parent_page='PRDs', label='prd', author={user_name}). Capture and surface the returned page URL.", "Mirror to Notion via notion:create_page (database_id='abc123', title='PRD: ' + {project_name}).", ] ``` If a named tool is unavailable, the handoff is skipped and flagged β€” local files always exist regardless. ### Finalize-time doc standards (`doc_standards`) Apply org writing standards to human-consumed documents at finalize, after content is complete but before the user sees the output. Each entry is a `skill:`, `file:`, or plain-text directive; passes run as parallel subagents. ```toml # _bmad/custom/bmad-prd.toml (same pattern works in any workflow that exposes doc_standards) [workflow] doc_standards = [ "file:{project-root}/docs/enterprise/voice-and-tone.md", "All dates must use ISO 8601 format (YYYY-MM-DD).", "Replace any use of 'leverage' with 'use'.", ] ``` `doc_standards` is an append array β€” team entries stack on top of whatever defaults the workflow ships with. Broader structural passes should come before narrower prose passes. ### Swappable templates and checklists Workflows that produce structured documents typically expose template and checklist paths as overridable scalars. Point them at org-owned files under `{project-root}` to enforce a different structure without editing any source. ```toml # _bmad/custom/bmad-prd.toml [workflow] # Regulated-industry PRD structure prd_template = "{project-root}/docs/enterprise/prd-template-hipaa.md" # Org-specific validation criteria validation_checklist = "{project-root}/docs/enterprise/prd-checklist-regulated.md" ``` The agent adapts to whatever structure the template defines. Keep templates under `{project-root}/docs/` or `{project-root}/_bmad/custom/templates/` so they version alongside the override file. For multi-org repos, use `.user.toml` to let teams point at their own templates without touching the committed team file. ## Combining Recipes All six recipes compose. A realistic enterprise override for `bmad-product-brief` might set `persistent_facts` (Recipe 2), `on_complete` (Recipe 3), and `brief_template` (Recipe 4) in one file. The agent-level rule (Recipe 1) lives in a separate file under the agent's name, central config (Recipe 5) pins the shared roster and team settings, advanced integration patterns (Recipe 6) configure external sources and handoffs, and all layers apply in parallel. ```toml # _bmad/custom/bmad-product-brief.toml (workflow-level) [workflow] persistent_facts = ["..."] brief_template = "{project-root}/docs/enterprise/brief-template.md" on_complete = """ ... """ ``` ```toml # _bmad/custom/bmad-agent-analyst.toml (agent-level β€” Mary dispatches product-brief) [agent] persistent_facts = ["Always include a 'Regulatory Review' section when the domain involves healthcare, finance, or children's data."] ``` Result: Mary loads the regulatory-review rule at persona activation. When the user picks the product-brief menu item, the workflow loads its own conventions on top, writes to the enterprise template, and publishes to Confluence on completion. Every layer contributes, and none of them required editing BMad source. ## Troubleshooting **Override not taking effect?** Check that the file is under `_bmad/custom/` with the exact skill directory name (e.g. `bmad-agent-dev.toml`, not `bmad-dev.toml`). See [How to Customize BMad](./customize-bmad.md#troubleshooting). **MCP tool name unknown?** Use the exact name the MCP server exposes in the current session. Ask Claude Code to list available MCP tools if unsure. Hardcoded names in `persistent_facts` or `on_complete` won't work if the MCP server isn't connected. **Pattern doesn't apply to my setup?** The recipes above are illustrative. The underlying machinery (three-layer merge, structural rules, agent-spans-workflow) supports many more patterns; compose them as needed. Use BMad's built-in help, source docs, or the community to get answers β€” from quickest to most thorough. ## 1. Ask BMad-Help The fastest way to get answers. The `bmad-help` skill is available directly in your AI session and handles over 80% of questions β€” it inspects your project, sees what you've completed, and tells you what to do next. ``` bmad-help I have a SaaS idea and know all the features. Where do I start? bmad-help What are my options for UX design? bmad-help I'm stuck on the PRD workflow ``` :::tip You can also use `/bmad-help` or `$bmad-help` depending on your platform, but just `bmad-help` should work everywhere. ::: ## 2. Go Deeper with Source BMad-Help draws on your installed configuration. For questions about BMad's internals, history, or architecture β€” or if you're researching BMad before installing β€” point your AI at the source directly. Clone or open the [BMAD-METHOD repo](https://github.com/bmad-code-org/BMAD-METHOD) and ask your AI about it. Any agent-capable tool (Claude Code, Cursor, Windsurf, etc.) can read the source and answer questions directly. :::note[Example] **Q:** "Tell me the fastest way to build something with BMad" **A:** Use Quick Flow: Run `bmad-quick-dev` β€” it clarifies your intent, plans, implements, reviews, and presents results in a single workflow, skipping the full planning phases. ::: **Tips for better answers:** - **Be specific** β€” "What does step 3 of the PRD workflow do?" beats "How does PRD work?" - **Verify surprising claims** β€” LLMs occasionally get things wrong. Check the source file or ask on Discord. ### Not using an agent? Use the docs site If your AI can't read local files (ChatGPT, Claude.ai, etc.), fetch [llms-full.txt](https://bmad-code-org.github.io/BMAD-METHOD/llms-full.txt) into your session β€” it's a single-file snapshot of the BMad documentation. ## 3. Ask Someone If neither BMad-Help nor the source answered your question, you now have a much better question to ask. | Channel | Use For | | ----------------------- | -------------------------- | | `help-requests` forum | Questions | | `#suggestions-feedback` | Ideas and feature requests | **Discord:** [discord.gg/gk8jAdXWmj](https://discord.gg/gk8jAdXWmj) **GitHub Issues:** [github.com/bmad-code-org/BMAD-METHOD/issues](https://github.com/bmad-code-org/BMAD-METHOD/issues) _You!_ _Stuck_ _in the queueβ€”_ _waiting_ _for who?_ _The source_ _is there,_ _plain to see!_ _Point_ _your machine._ _Set it free._ _It reads._ _It speaks._ _Ask awayβ€”_ _Why wait_ _for tomorrow_ _when you have_ _today?_ _β€”Claude_ Use `npx bmad-method install` to set up BMad in your project. One command handles first installs, upgrades, channel switching, and scripted CI runs. This page covers all of it. ## When to Use This - Starting a new project with BMad - Adding or removing modules on an existing install - Switching a module to main-HEAD or pinning to a specific release - Scripting installs for CI pipelines, Dockerfiles, or enterprise rollouts :::note[Prerequisites] - **Node.js** 20.12+ (the installer requires it) - **Git** (for cloning external modules) - **An AI tool** such as Claude Code or Cursor (run `npx bmad-method install --list-tools` to see all supported tools) ::: ## First-time install (the fast path) ```bash npx bmad-method install ``` The interactive flow asks you five things: 1. Installation directory (defaults to the current working directory) 2. Which modules to install (checkboxes for core, bmm, bmb, cis, gds, tea) 3. **"Ready to install (all stable)?"** β€” Yes accepts the latest released tag for every external module 4. Which AI tools/IDEs to integrate with (claude-code, cursor, and others) 5. Per-module config (name, language, output folder) Accept the defaults and you land on the latest stable release of every module, configured for your chosen tool. :::tip[Just want the newest prerelease?] ```bash npx bmad-method@next install ``` Runs the prerelease installer, which ships a newer snapshot of core and bmm. More churn, fewer delays between development and release. ::: ## Picking a specific version Two independent axes control what ends up on disk. ### Axis 1: external module channels Every external module β€” bmb, cis, gds, tea, and any community module β€” installs on one of three channels: | Channel | What gets installed | Who picks this | | ------------------ | ---------------------------------------------------------------------------- | --------------------------------------- | | `stable` (default) | Highest released semver tag. Prereleases like `v2.0.0-alpha.1` are excluded. | Most users | | `next` | Main branch HEAD at install time | Contributors, early adopters | | `pinned` | A specific tag you name | Enterprise installs, CI reproducibility | Channels are per-module. You can run bmb on `next` while leaving cis on `stable` β€” the flags below let you mix freely. ### Axis 2: installer binary version The `bmad-method` npm package itself has two dist-tags: | Command | What you get | | ------------------------------------- | ----------------------------------------------------------------- | | `npx bmad-method install` (`@latest`) | Latest stable installer release | | `npx bmad-method@next install` | Latest prerelease installer, auto-published on every push to main | **The installer binary determines your core and bmm versions.** Those two modules ship bundled inside the installer package rather than being cloned from separate repos. ### Why core and bmm don't have their own channel They're stapled to the installer binary you ran: - `npx bmad-method install` β†’ latest stable core and bmm - `npx bmad-method@next install` β†’ prerelease core and bmm - `node /path/to/local-checkout/tools/installer/bmad-cli.js install` β†’ whatever your local checkout has `--pin bmm=v6.3.0` and `--next=bmm` are silently ineffective against bundled modules, and the installer warns you when you try. A future release extracts bmm from the installer package; once that ships, bmm gets a proper channel selector like bmb has today. ## Updating an existing install Running `npx bmad-method install` in a directory that already contains `_bmad/` gives you a menu: | Choice | What it does | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Quick Update** | Re-runs the install with your existing settings. Refreshes files, applies patches and minor stable upgrades, refuses major upgrades. Fast, non-interactive. | | **Modify Install** | Full interactive flow. Add or remove modules, reconfigure settings, optionally review and switch channels for existing modules. | ### Upgrade prompts When Modify detects a newer stable tag for a module you've installed on `stable`, it classifies the diff and prompts accordingly: | Upgrade type | Example | Default | | ------------ | --------------- | ------- | | Patch | v1.7.0 β†’ v1.7.1 | Y | | Minor | v1.7.0 β†’ v1.8.0 | Y | | Major | v1.7.0 β†’ v2.0.0 | **N** | Major defaults to N because breaking changes frequently surface as "instability" when they weren't expected. The prompt includes a GitHub release-notes URL so you can read what changed before accepting. Under `--yes`, patch and minor upgrades apply automatically. Majors stay frozen β€” pass `--pin =` to accept non-interactively. ### Switching a module's channel **Interactively:** choose Modify β†’ answer **Yes** to "Review channel assignments?" β†’ each external module offers Keep, Switch to stable, Switch to next, or Pin to a tag. **Via flags:** the recipes in the next section cover the common cases. ## Headless CI installs ### Flag reference | Flag | Purpose | | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | | `--yes`, `-y` | Skip all prompts; accept flag values + defaults | | `--directory ` | Install into this directory (default: current working dir) | | `--modules ` | Exact module set. Core is auto-added. Not a delta β€” list everything you want kept. | | `--tools ` | IDE/tool selection. Required for fresh `--yes` installs. Run `--list-tools` for valid IDs. | | `--list-tools` | Print all supported tool/IDE IDs (with target directories) and exit. | | `--action ` | `install`, `update`, or `quick-update`. Defaults based on existing install state. | | `--custom-source ` | Install custom modules from Git URLs or local paths | | `--channel ` | Apply to all externals (aliased as `--all-stable` / `--all-next`) | | `--all-stable` | Alias for `--channel=stable` | | `--all-next` | Alias for `--channel=next` | | `--next=` | Put one module on next. Repeatable. | | `--pin =` | Pin one module to a specific tag. Repeatable. | | `--set .=` | Set any module config option non-interactively (preferred β€” see [Module config overrides](#module-config-overrides)). Repeatable. | | `--list-options [module]` | Print every `--set` key for built-in and locally-cached official modules, then exit. Pass a module code to scope to one module. | | `--user-name`, `--communication-language`, `--document-output-language`, `--output-folder` | Legacy shortcuts equivalent to `--set core.=` (still supported) | Precedence when flags overlap: `--pin` beats `--next=` beats `--channel` / `--all-*` beats the registry default (`stable`). :::note[Example resolution] `--all-next --pin cis=v0.2.0` puts bmb, gds, and tea on next while pinning cis to v0.2.0. ::: ### Recipes **Default install β€” latest stable for everything:** ```bash npx bmad-method install --yes --modules bmm,bmb,cis --tools claude-code ``` **Enterprise pin β€” reproducible byte-for-byte:** ```bash npx bmad-method install --yes \ --modules bmm,bmb,cis \ --pin bmb=v1.7.0 --pin cis=v0.2.0 \ --tools claude-code ``` **Bleeding edge β€” externals on main HEAD:** ```bash npx bmad-method install --yes --modules bmm,bmb --all-next --tools claude-code ``` **Add a module to an existing install** (keep everything else): ```bash npx bmad-method install --yes --action update \ --modules bmm,bmb,gds ``` `--tools` is omitted intentionally β€” `--action update` reuses the tools configured during the first install. **Mix channels β€” bmb on next, gds on stable:** ```bash npx bmad-method install --yes --action update \ --modules bmm,bmb,cis,gds \ --next=bmb ``` ### Module config overrides `--set .=` lets you set any module config option non-interactively. It's repeatable and scales to every module β€” present and future. The flag is applied as a post-install patch: the installer runs its normal flow first, then `--set` upserts each value into `_bmad/config.toml` (team scope) or `_bmad/config.user.toml` (user scope), and into `_bmad//config.yaml` so declared values carry forward to the next install. **Example β€” install bmm with explicit project knowledge and skill level:** ```bash npx bmad-method install --yes \ --modules bmm \ --tools claude-code \ --set bmm.project_knowledge=research \ --set bmm.user_skill_level=expert ``` **Discover available keys for a module:** ```bash npx bmad-method install --list-options bmm ``` `--list-options` (no argument) lists every key the installer can find locally β€” built-in modules (`core`, `bmm`) plus any currently cached official modules. The cache is per-machine and can be cleared, so previously installed officials won't appear on a fresh checkout or an ephemeral CI worker until they're installed again. Community and custom modules aren't enumerated here; read the module's `module.yaml` directly to see what keys it declares. **How it works:** - **Routing.** The patch step looks for `[modules.] ` (or `[core] `) in `config.user.toml` first; if found there, it updates that file. Otherwise it writes to the team-scope `config.toml`. So user-scope keys (e.g. `core.user_name`, `bmm.user_skill_level`) end up in `config.user.toml` and team-scope keys end up in `config.toml`, matching the partition the installer uses. - **Verbatim values.** The value is written exactly as you provided it β€” no `result:` template rendering. To get the rendered form (e.g. `{project-root}/research`), pass it explicitly: `--set bmm.project_knowledge='{project-root}/research'`. - **Carry-forward, declared keys.** Values for keys declared in `module.yaml` survive subsequent installs because they're also written to `_bmad//config.yaml`, which the installer reads as the prompt default on the next run. - **Carry-forward, undeclared keys.** A value for a key the module's schema doesn't declare lands in `config.toml` for the current install but won't be re-emitted on the next install (the manifest writer's schema-strict partition drops unknown keys). Re-pass `--set` if you need it sticky, or edit `_bmad/config.toml` directly. - **No validation.** `single-select` values aren't checked against the allowed choices, and unknown keys aren't rejected β€” whatever you assert is written. - **Modules not in `--modules`.** Setting a value for a module you didn't include prints a warning and the value is dropped (no file gets created for an uninstalled module). The legacy core shortcuts (`--user-name`, `--output-folder`, etc.) still work and remain documented for backward compatibility, but `--set core.user_name=...` is equivalent. :::note[Works with quick-update] `--set` is a post-install patch, so it applies the same way regardless of action type. Under `bmad install --action quick-update` (or `--yes` against an existing install, where quick-update is the default), `--set` patches the central config files at the end just like a regular install. ::: :::caution[Rate limit on shared IPs] Anonymous GitHub API calls are capped at 60/hour per IP. A single install hits the API once per external module to resolve the stable tag. Offices behind NAT, CI runner pools, and VPNs can collectively exhaust this. Set `GITHUB_TOKEN=` in the environment to raise the limit to 5000/hour per account. Any public-repo-read PAT works; no scopes are required. ::: ## What got installed After any install, `_bmad/_config/manifest.yaml` records exactly what's on disk: ```yaml modules: - name: bmb version: v1.7.0 # the tag, or "main" for next channel: stable # stable | next | pinned sha: 86033fc9aeae2ca6d52c7cdb675c1f4bf17fc1c1 source: external repoUrl: https://github.com/bmad-code-org/bmad-builder ``` The `sha` field is written for git-backed modules (external, community, and URL-based custom). Bundled modules (core, bmm) and local-path custom modules don't have one β€” their code travels with the installer binary or your filesystem, not a cloneable ref. For cross-machine reproducibility, don't rely on rerunning the same `--modules` command. Stable-channel installs resolve to the highest released tag **at install time**, so a later rerun lands on whatever has been released since. Convert the recorded tags from `manifest.yaml` into explicit `--pin` flags on the target machine, e.g.: ```bash npx bmad-method install --yes --modules bmb,cis \ --pin bmb=v1.7.0 --pin cis=v0.4.2 --tools claude-code ``` ## Troubleshooting ### "Could not resolve stable tag" or "API rate limit exceeded" You've hit GitHub's 60/hr anonymous limit. Set `GITHUB_TOKEN` and retry. If you already have a token set, it may be expired or rate-limited on its own budget β€” try a different token or wait for the hourly reset. ### "Tag 'vX.Y.Z' not found" The tag you passed to `--pin` doesn't exist in the module's repo. Check the repo's releases page on GitHub for valid tags. ### A pinned install keeps upgrading Pinned installs don't upgrade. Quick-update applies patches and minors on stable channel only; it won't touch `pinned` or `next`. If a pinned install changed, open `_bmad/_config/manifest.yaml` β€” `channel: pinned` plus a fixed `version` and `sha` should hold across runs unless you explicitly override via flags. ### `--pin bmm=X` didn't do anything bmm is a bundled module β€” `--pin` and `--next=` don't apply. Use `npx bmad-method@next install` for a prerelease core/bmm, or check out the bmad-bmm repo and run the installer locally to get unreleased changes. Use the BMad installer to add modules from the community registry, third-party Git repositories, or local file paths. ## When to Use This - Installing a community-contributed module from the BMad registry - Installing a module from a third-party Git repository (GitHub, GitLab, Bitbucket, self-hosted) - Testing a module you are developing locally with BMad Builder - Installing modules from a private or self-hosted Git server :::note[Prerequisites] Requires [Node.js](https://nodejs.org) v20.12+ and `npx` (included with npm). Custom and community modules can be selected during a fresh install or added to an existing installation. ::: ## Community Modules Community modules are curated in the [BMad plugins marketplace](https://github.com/bmad-code-org/bmad-plugins-marketplace). They are organized by category and are pinned to an approved commit for safety. ### 1. Run the Installer ```bash npx bmad-method install ``` ### 2. Browse the Community Catalog After selecting official modules, the installer asks: ``` Would you like to browse community modules? ``` Select **Yes** to enter the catalog browser. You can: - Browse by category - View featured modules - View all available modules - Search by keyword ### 3. Select Modules Pick modules from any category. The installer shows descriptions, versions, and trust tiers. Already-installed modules are pre-checked for update. ### 4. Continue with Installation After selecting community modules, the installer proceeds to custom sources, then tool/IDE configuration and the rest of the install flow. ## Custom Sources (Git URLs and Local Paths) Custom modules can come from any Git repository or a local directory on your machine. The installer resolves the source, analyzes the module structure, and installs it alongside your other modules. ### Interactive Installation During installation, after the community module step, the installer asks: ``` Would you like to install from a custom source (Git URL or local path)? ``` Select **Yes**, then provide a source: | Input Type | Example | | --------------------- | ------------------------------------------------- | | HTTPS URL (any host) | `https://github.com/org/repo` | | HTTP URL (any host) | `http://host/org/repo` | | HTTPS URL with subdir | `https://github.com/org/repo/tree/main/my-module` | | SSH URL | `git@github.com:org/repo.git` | | Local path | `/Users/me/projects/my-module` | | Local path with tilde | `~/projects/my-module` | The installer clones the repository (for URLs) or reads directly from disk (for local paths), then presents the discovered modules for selection. ### Non-Interactive Installation Use the `--custom-source` flag to install custom modules from the command line: ```bash npx bmad-method install \ --directory . \ --custom-source /path/to/my-module \ --tools claude-code \ --yes ``` When `--custom-source` is provided without `--modules`, only core and the custom modules are installed. To include official modules as well, add `--modules`: ```bash npx bmad-method install \ --directory . \ --modules bmm \ --custom-source https://gitlab.com/myorg/my-module \ --tools claude-code \ --yes ``` Multiple sources can be comma-separated: ```bash --custom-source /path/one,https://github.com/org/repo,/path/two ``` ## How Module Discovery Works The installer uses two modes to find installable modules in a source: | Mode | Trigger | Behavior | | --------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------- | | Discovery | Source contains `.claude-plugin/marketplace.json` | Lists all plugins from the manifest; you pick which to install | | Direct | No marketplace.json found | Scans the directory for skills (subdirectories with `SKILL.md`), resolves as a single module | Discovery mode is typical for published modules. Direct mode is convenient when pointing at a skills directory during local development. :::note[About `.claude-plugin/`] The `.claude-plugin/marketplace.json` path is a standard convention adopted across multiple AI tool installers for plugin discoverability. It does not require Claude, does not use Claude APIs, and has no effect on which AI tool you use. Any module with this file can be discovered by any installer that follows the convention. ::: ## Local Development Workflow If you are building a module with [BMad Builder](https://github.com/bmad-code-org/bmad-builder), you can install it directly from your working directory: ```bash npx bmad-method install \ --directory ~/my-project \ --custom-source ~/my-module-repo/skills \ --tools claude-code \ --yes ``` Local sources are referenced by path, not copied to a cache. When you update your module source and reinstall, the installer picks up the latest changes. :::caution[Source Removal] If you delete the local source directory after installation, the installed module files in `_bmad/` are preserved. The module will be skipped during updates until the source path is restored. ::: ## What You Get After installation, custom modules appear in `_bmad/` alongside official modules: ``` your-project/ β”œβ”€β”€ _bmad/ β”‚ β”œβ”€β”€ core/ # Built-in core module β”‚ β”œβ”€β”€ bmm/ # Official module (if selected) β”‚ β”œβ”€β”€ my-module/ # Your custom module β”‚ β”‚ β”œβ”€β”€ my-skill/ β”‚ β”‚ β”‚ └── SKILL.md β”‚ β”‚ └── module-help.csv β”‚ └── _config/ β”‚ └── manifest.yaml # Tracks all modules, versions, and sources └── ... ``` The manifest records the source of each custom module (`repoUrl` for Git sources, `localPath` for local sources) so that quick updates can locate the source again. ## Updating Custom Modules Custom modules participate in the normal update flow: - **Quick update** (`--action quick-update`): Refreshes all modules from their original sources. Git-based modules are re-fetched; local modules are re-read from their source path. - **Full update**: Re-runs module selection so you can add or remove custom modules. ## Creating Your Own Modules Use [BMad Builder](https://github.com/bmad-code-org/bmad-builder) to create modules that others can install: 1. Run `bmad-module-builder` to scaffold your module structure 2. Add skills, agents, and workflows with the various bmad builder tools 3. Publish to a Git repository or share the folder collection 4. Others install with `--custom-source ` For modules to support discovery mode, include a `.claude-plugin/marketplace.json` in your repository root (this is a cross-tool convention, not Claude-specific). See the [BMad Builder documentation](https://github.com/bmad-code-org/bmad-builder) for the marketplace.json format. :::tip[Testing Locally First] During development, install your module with a local path to iterate quickly before publishing to a Git repository. ::: :::note[This page has moved] Headless and CI install flags, channel selection, and pinning now live in the unified [How to Install BMad](./install-bmad.md) guide. Jump to the [Headless / CI installs](./install-bmad.md#headless-ci-installs) section for the flag reference and copy-paste recipes. ::: Use the `project-context.md` file to ensure AI agents follow your project's technical preferences and implementation rules throughout all workflows. To make sure this is always available, you can also add the line `Important project context and conventions are located in [path to project context]/project-context.md` to your tools context or always rules file (such as `AGENTS.md`) :::note[Prerequisites] - BMad Method installed - Understanding of your project's technology stack and conventions ::: ## When to Use This - You have strong technical preferences before starting architecture - You've completed architecture and want to capture decisions for implementation - You're working on an existing codebase with established patterns - You notice agents making inconsistent decisions across stories ## Step 1: Choose Your Approach **Manual creation** β€” Best when you know exactly what rules you want to document **Generate after architecture** β€” Best for capturing decisions made during solutioning **Generate for existing projects** β€” Best for discovering patterns in existing codebases ## Step 2: Create the File ### Option A: Manual Creation Create the file at `_bmad-output/project-context.md`: ```bash mkdir -p _bmad-output touch _bmad-output/project-context.md ``` Add your technology stack and implementation rules: ```markdown --- project_name: 'MyProject' user_name: 'YourName' date: '2026-02-15' sections_completed: ['technology_stack', 'critical_rules'] --- # Project Context for AI Agents ## Technology Stack & Versions - Node.js 20.x, TypeScript 5.3, React 18.2 - State: Zustand - Testing: Vitest, Playwright - Styling: Tailwind CSS ## Critical Implementation Rules **TypeScript:** - Strict mode enabled, no `any` types - Use `interface` for public APIs, `type` for unions **Code Organization:** - Components in `/src/components/` with co-located tests - API calls use `apiClient` singleton β€” never fetch directly **Testing:** - Unit tests focus on business logic - Integration tests use MSW for API mocking ``` ### Option B: Generate After Architecture Run the workflow in a fresh chat: ```bash bmad-generate-project-context ``` The workflow scans your architecture document and project files to generate a context file capturing the decisions made. ### Option C: Generate for Existing Projects For existing projects, run: ```bash bmad-generate-project-context ``` The workflow analyzes your codebase to identify conventions, then generates a context file you can review and refine. ## Step 3: Verify Content Review the generated file and ensure it captures: - Correct technology versions - Your actual conventions (not generic best practices) - Rules that prevent common mistakes - Framework-specific patterns Edit manually to add anything missing or remove inaccuracies. ## What You Get A `project-context.md` file that: - Ensures all agents follow the same conventions - Prevents inconsistent decisions across stories - Captures architecture decisions for implementation - Serves as a reference for your project's patterns and rules ## Tips :::tip[Best Practices] - **Focus on the unobvious** β€” Document patterns agents might miss (e.g., "Use JSDoc on every public class"), not universal practices like "use meaningful variable names." - **Keep it lean** β€” This file is loaded by every implementation workflow. Long files waste context. Exclude content that only applies to narrow scope or specific stories. - **Update as needed** β€” Edit manually when patterns change, or re-generate after significant architecture changes. - Works for Quick Flow and full BMad Method projects alike. ::: ## Next Steps - [**Project Context Explanation**](../explanation/project-context.md) β€” Learn more about how it works - [**Workflow Map**](../reference/workflow-map.md) β€” See which workflows load project context Use **Quick Dev** for bug fixes, refactorings, or small targeted changes that don't require the full BMad Method. ## When to Use This - Bug fixes with a clear, known cause - Small refactorings (rename, extract, restructure) contained within a few files - Minor feature tweaks or configuration changes - Dependency updates :::note[Prerequisites] - BMad Method installed (`npx bmad-method install`) - An AI-powered IDE (Claude Code, Cursor, or similar) ::: ## Steps ### 1. Start a Fresh Chat Open a **fresh chat session** in your AI IDE. Reusing a session from a previous workflow can cause context conflicts. ### 2. Give It Your Intent Quick Dev accepts free-form intent β€” before, with, or after the invocation. Examples: ```text run quick-dev β€” Fix the login validation bug that allows empty passwords. ``` ```text run quick-dev β€” fix https://github.com/org/repo/issues/42 ``` ```text run quick-dev β€” implement the intent in _bmad-output/implementation-artifacts/my-intent.md ``` ```text I think the problem is in the auth middleware, it's not checking token expiry. Let me look at it... yeah, src/auth/middleware.ts line 47 skips the exp check entirely. run quick-dev ``` ```text run quick-dev > What would you like to do? Refactor UserService to use async/await instead of callbacks. ``` Plain text, file paths, GitHub issue URLs, bug tracker links β€” anything the LLM can resolve to a concrete intent. ### 3. Answer Questions and Approve Quick Dev may ask clarifying questions or present a short spec for your approval before implementing. Answer its questions and approve when you're satisfied with the plan. ### 4. Review and Push Quick Dev implements the change, reviews its own work, patches issues, and commits locally. When it's done, it opens the affected files in your editor. - Skim the diff to confirm the change matches your intent - If something looks off, tell the agent what to fix β€” it can iterate in the same session Once satisfied, push the commit. Quick Dev will offer to push and create a PR for you. :::caution[If Something Breaks] If a pushed change causes unexpected issues, use `git revert HEAD` to undo the last commit cleanly. Then start a fresh chat and run Quick Dev again to try a different approach. ::: ## What You Get - Modified source files with the fix or refactoring applied - Passing tests (if your project has a test suite) - A ready-to-push commit with a conventional commit message ## Deferred Work Quick Dev keeps each run focused on a single goal. If your request contains multiple independent goals, or if the review surfaces pre-existing issues unrelated to your change, Quick Dev defers them to a file (`deferred-work.md` in your implementation artifacts directory) rather than trying to tackle everything at once. Check this file after a run β€” it's your backlog of things to come back to. Each deferred item can be fed into a fresh Quick Dev run later. ## When to Upgrade to Formal Planning Consider using the full BMad Method when: - The change affects multiple systems or requires coordinated updates across many files - You are unsure about the scope and need requirements discovery first - You need documentation or architectural decisions recorded for the team See [Quick Dev](../explanation/quick-dev.md) for more on how Quick Dev fits into the BMad Method. Use the `bmad-shard-doc` tool if you need to split large markdown files into smaller, organized files for better context management. :::caution[Deprecated] This is no longer recommended, and soon with updated workflows and most major LLMs and tools supporting subprocesses this will be unnecessary. ::: ## When to Use This Only use this if you notice your chosen tool / model combination is failing to load and read all the documents as input when needed. ## What is Document Sharding? Document sharding splits large markdown files into smaller, organized files based on level 2 headings (`## Heading`). ### Architecture ```text Before Sharding: _bmad-output/planning-artifacts/ └── PRD.md (large 50k token file) After Sharding: _bmad-output/planning-artifacts/ └── prd/ β”œβ”€β”€ index.md # Table of contents with descriptions β”œβ”€β”€ overview.md # Section 1 β”œβ”€β”€ user-requirements.md # Section 2 β”œβ”€β”€ technical-requirements.md # Section 3 └── ... # Additional sections ``` ## Steps ### 1. Run the Shard-Doc Tool ```bash /bmad-shard-doc ``` ### 2. Follow the Interactive Process ```text Agent: Which document would you like to shard? User: docs/PRD.md Agent: Default destination: docs/prd/ Accept default? [y/n] User: y Agent: Sharding PRD.md... βœ“ Created 12 section files βœ“ Generated index.md βœ“ Complete! ``` ## How Workflow Discovery Works BMad workflows use a **dual discovery system**: 1. **Try whole document first** - Look for `document-name.md` 2. **Check for sharded version** - Look for `document-name/index.md` 3. **Priority rule** - Whole document takes precedence if both exist - remove the whole document if you want the sharded to be used instead ## Workflow Support All BMM workflows support both formats: - Whole documents - Sharded documents - Automatic detection - Transparent to user Use the BMad installer to upgrade from v4 to v6, which includes automatic detection of legacy installations and migration assistance. ## When to Use This - You have BMad v4 installed (`.bmad-method` folder) - You want to migrate to the new v6 architecture - You have existing planning artifacts to preserve :::note[Prerequisites] - Node.js 20.12+ - Existing BMad v4 installation ::: ## Steps ### 1. Run the Installer Follow the [Installer Instructions](./install-bmad.md). ### 2. Handle Legacy Installation When v4 is detected, you can: - Allow the installer to back up and remove `.bmad-method` - Exit and handle cleanup manually If you named your bmad method folder something else - you will need to manually remove the folder yourself. ### 3. Clean Up IDE Skills Manually remove legacy v4 IDE commands/skills - for example if you have Claude Code, look for any nested folders that start with bmad and remove them: - `.claude/commands/` The new v6 skills are installed to: - `.claude/skills/` ### 4. Migrate Planning Artifacts **If you have planning documents (Brief/PRD/UX/Architecture):** Move them to `_bmad-output/planning-artifacts/` with descriptive names: - Include `PRD` in filename for PRD documents - Include `brief`, `architecture`, or `ux-design` accordingly - Sharded documents can be in named subfolders **If you're mid-planning:** Consider restarting with v6 workflows. Use your existing documents as inputsβ€”the new progressive discovery workflows with web search and IDE plan mode produce better results. ### 5. Migrate In-Progress Development If you have stories created or implemented: 1. Complete the v6 installation 2. Place `epics.md` or `epics/epic*.md` in `_bmad-output/planning-artifacts/` 3. Run the Developer's `bmad-sprint-planning` workflow 4. Tell the agent which epics/stories are already complete ## What You Get **v6 unified structure:** ```text your-project/ β”œβ”€β”€ _bmad/ # Single installation folder β”‚ β”œβ”€β”€ _config/ # Your customizations β”‚ β”‚ └── agents/ # Agent customization files β”‚ β”œβ”€β”€ core/ # Universal core framework β”‚ β”œβ”€β”€ bmm/ # BMad Method module β”‚ β”œβ”€β”€ bmb/ # BMad Builder β”‚ └── cis/ # Creative Intelligence Suite └── _bmad-output/ # Output folder (was doc folder in v4) ``` ## Module Migration | v4 Module | v6 Status | | ----------------------------- | ----------------------------------------- | | `.bmad-2d-phaser-game-dev` | Integrated into BMGD Module | | `.bmad-2d-unity-game-dev` | Integrated into BMGD Module | | `.bmad-godot-game-dev` | Integrated into BMGD Module | | `.bmad-infrastructure-devops` | Deprecated β€” new DevOps agent coming soon | | `.bmad-creative-writing` | Not adapted β€” new v6 module coming soon | ## Key Changes | Concept | v4 | v6 | | ------------- | ------------------------------------- | ------------------------------------ | | **Core** | `_bmad-core` was actually BMad Method | `_bmad/core/` is universal framework | | **Method** | `_bmad-method` | `_bmad/bmm/` | | **Config** | Modified files directly | `config.yaml` per module | | **Documents** | Sharded or unsharded required setup | Fully flexible, auto-scanned | Make the LLM reconsider what it just generated. You pick a reasoning method, it applies that method to its own output, you decide whether to keep the improvements. ## What is Advanced Elicitation? A structured second pass. Instead of asking the AI to "try again" or "make it better," you select a specific reasoning method and the AI re-examines its own output through that lens. The difference matters. Vague requests produce vague revisions. A named method forces a particular angle of attack, surfacing insights that a generic retry would miss. ## When to Use It - After a workflow generates content and you want alternatives - When output seems okay but you suspect there's more depth - To stress-test assumptions or find weaknesses - For high-stakes content where rethinking helps Workflows offer advanced elicitation at decision points - after the LLM has generated something, you'll be asked if you want to run it. ## How It Works 1. LLM suggests 5 relevant methods for your content 2. You pick one (or reshuffle for different options) 3. Method is applied, improvements shown 4. Accept or discard, repeat or continue ## Built-in Methods Dozens of reasoning methods are available. A few examples: - **Pre-mortem Analysis** - Assume the project already failed, work backward to find why - **First Principles Thinking** - Strip away assumptions, rebuild from ground truth - **Inversion** - Ask how to guarantee failure, then avoid those things - **Red Team vs Blue Team** - Attack your own work, then defend it - **Socratic Questioning** - Challenge every claim with "why?" and "how do you know?" - **Constraint Removal** - Drop all constraints, see what changes, add them back selectively - **Stakeholder Mapping** - Re-evaluate from each stakeholder's perspective - **Analogical Reasoning** - Find parallels in other domains and apply their lessons And many more. The AI picks the most relevant options for your content - you choose which to run. :::tip[Start Here] Pre-mortem Analysis is a good first pick for any spec or plan. It consistently finds gaps that a standard review misses. ::: Force deeper analysis by requiring problems to be found. ## What is Adversarial Review? A review technique where the reviewer *must* find issues. No "looks good" allowed. The reviewer adopts a cynical stance - assume problems exist and find them. This isn't about being negative. It's about forcing genuine analysis instead of a cursory glance that rubber-stamps whatever was submitted. **The core rule:** You must find issues. Zero findings triggers a halt - re-analyze or explain why. ## Why It Works Normal reviews suffer from confirmation bias. You skim the work, nothing jumps out, you approve it. The "find problems" mandate breaks this pattern: - **Forces thoroughness** - Can't approve until you've looked hard enough to find issues - **Catches missing things** - "What's not here?" becomes a natural question - **Improves signal quality** - Findings are specific and actionable, not vague concerns - **Information asymmetry** - Run reviews with fresh context (no access to original reasoning) so you evaluate the artifact, not the intent ## Where It's Used Adversarial review appears throughout BMad workflows - code review, implementation readiness checks, spec validation, and others. Sometimes it's a required step, sometimes optional (like advanced elicitation or party mode). The pattern adapts to whatever artifact needs scrutiny. ## Human Filtering Required Because the AI is *instructed* to find problems, it will find problems - even when they don't exist. Expect false positives: nitpicks dressed as issues, misunderstandings of intent, or outright hallucinated concerns. **You decide what's real.** Review each finding, dismiss the noise, fix what matters. ## Example Instead of: > "The authentication implementation looks reasonable. Approved." An adversarial review produces: > 1. **HIGH** - `login.ts:47` - No rate limiting on failed attempts > 2. **HIGH** - Session token stored in localStorage (XSS vulnerable) > 3. **MEDIUM** - Password validation happens client-side only > 4. **MEDIUM** - No audit logging for failed login attempts > 5. **LOW** - Magic number `3600` should be `SESSION_TIMEOUT_SECONDS` The first review might miss a security vulnerability. The second caught four. ## Iteration and Diminishing Returns After addressing findings, consider running it again. A second pass usually catches more. A third isn't always useless either. But each pass takes time, and eventually you hit diminishing returns - just nitpicks and false findings. :::tip[Better Reviews] Assume problems exist. Look for what's missing, not just what's wrong. ::: The Analysis phase (Phase 1) helps you think clearly about your product before committing to building it. Every tool in this phase is optional, but skipping analysis entirely means your PRD is built on assumptions instead of insight. ## Why Analysis Before Planning? A PRD answers "what should we build and why?" If you feed it vague thinking, you get a vague PRD β€” and every downstream document inherits that vagueness. Architecture built on a weak PRD makes wrong technical bets. Stories derived from weak architecture miss edge cases. The cost compounds. Analysis tools exist to make your PRD sharp. They attack the problem from different angles β€” creative exploration, market reality, customer clarity, feasibility β€” so that by the time you sit down with the PM agent, you know what you're building and for whom. ## The Tools ### Brainstorming **What it is.** A facilitated creative session using proven ideation techniques. The AI acts as coach, pulling ideas out of you through structured exercises β€” not generating ideas for you. **Why it's here.** Raw ideas need space to develop before they get locked into requirements. Brainstorming creates that space. It's especially valuable when you have a problem domain but no clear solution, or when you want to explore multiple directions before committing. **When to use it.** You have a vague sense of what you want to build but haven't crystallized the concept. Or you have a concept but want to pressure-test it against alternatives. See [Brainstorming](./brainstorming.md) for a deeper look at how sessions work. ### Research (Market, Domain, Technical) **What it is.** Three focused research workflows that investigate different dimensions of your idea. Market research examines competitors, trends, and user sentiment. Domain research builds subject-matter expertise and terminology. Technical research evaluates feasibility, architecture options, and implementation approaches. **Why it's here.** Building on assumptions is the fastest way to build something nobody needs. Research grounds your concept in reality β€” what competitors already exist, what users actually struggle with, what's technically feasible, and what industry-specific constraints you'll face. **When to use it.** You're entering an unfamiliar domain, you suspect competitors exist but haven't mapped them, or your concept depends on technical capabilities you haven't validated. Run one, two, or all three β€” each stands alone. ### Product Brief **What it is.** A guided discovery session that produces a 1-2 page executive summary of your product concept. The AI acts as a collaborative Business Analyst, helping you articulate the vision, target audience, value proposition, and scope. **Why it's here.** The product brief is the gentler path into planning. It captures your strategic vision in a structured format that feeds directly into PRD creation. It works best when you already have conviction about your concept β€” you know the customer, the problem, and roughly what you want to build. The brief organizes and sharpens that thinking. **When to use it.** Your concept is relatively clear and you want to document it efficiently before creating a PRD. You're confident in the direction and don't need your assumptions aggressively challenged. ### PRFAQ (Working Backwards) **What it is.** Amazon's Working Backwards methodology adapted as an interactive challenge. You write the press release announcing your finished product before a single line of code exists, then answer the hardest questions customers and stakeholders would ask. The AI acts as a relentless but constructive product coach. **Why it's here.** The PRFAQ is the rigorous path into planning. It forces customer-first clarity by making you defend every claim. If you can't write a compelling press release, the product isn't ready. If customer FAQ answers reveal gaps, those are gaps you'd discover much later β€” and more expensively β€” during implementation. The gauntlet surfaces weak thinking early, when it's cheapest to fix. **When to use it.** You want your concept stress-tested before committing resources. You're unsure whether users will actually care. You want to validate that you can articulate a clear, defensible value proposition. Or you simply want the discipline of Working Backwards to sharpen your thinking. ## Which Should I Use? | Situation | Recommended tool | | --------- | ---------------- | | "I have a vague idea, not sure where to start" | Brainstorming | | "I need to understand the market before deciding" | Research | | "I know what I want to build, just need to document it" | Product Brief | | "I want to make sure this idea is actually worth building" | PRFAQ | | "I want to explore, then validate, then document" | Brainstorming β†’ Research β†’ PRFAQ or Brief | Product Brief and PRFAQ both produce input for the PRD β€” choose one based on how much challenge you want. The brief is collaborative discovery. The PRFAQ is a gauntlet. Both get you to the same destination; the PRFAQ tests whether your concept deserves to get there. :::tip[Not Sure?] Run `bmad-help` and describe your situation. It will recommend the right starting point based on what you've already done and what you're trying to accomplish. ::: ## What Happens After Analysis? Analysis outputs feed directly into Phase 2 (Planning). The PRD workflow accepts product briefs, PRFAQ documents, research findings, and brainstorming reports as input β€” it synthesizes whatever you've produced into structured requirements. The more analysis you do, the sharper your PRD. Unlock your creativity through guided exploration. ## What is Brainstorming? Run `bmad-brainstorming` and you've got a creative facilitator pulling ideas out of you - not generating them for you. The AI acts as coach and guide, using proven techniques to create conditions where your best thinking emerges. **Good for:** - Breaking through creative blocks - Generating product or feature ideas - Exploring problems from new angles - Developing raw concepts into action plans ## How It Works 1. **Setup** - Define topic, goals, constraints 2. **Choose approach** - Pick techniques yourself, get AI recommendations, go random, or follow a progressive flow 3. **Facilitation** - Work through techniques with probing questions and collaborative coaching 4. **Organize** - Ideas grouped into themes and prioritized 5. **Action** - Top ideas get next steps and success metrics Everything gets captured in a session document you can reference later or share with stakeholders. :::note[Your Ideas] Every idea comes from you. The workflow creates conditions for insight - you're the source. ::: `bmad-checkpoint-preview` is an interactive, LLM-assisted human-in-the-loop review workflow. It walks you through a code change β€” from purpose and context into details β€” so you can make an informed decision about whether to ship, rework, or dig deeper. ![Checkpoint Preview workflow diagram](/diagrams/checkpoint-preview-diagram.png) ## The Typical Flow You run `bmad-quick-dev`. It clarifies your intent, builds a spec, implements the change, and when it's done it appends a review trail to the spec file and opens it in your editor. You look at the spec and see the change touched 20 files across several modules. You could eyeball the diff. But 20 files is where eyeballing starts to fail β€” you lose the thread, miss a connection between two distant changes, or approve something you didn't fully understand. So instead, you say "checkpoint" and the LLM walks you through it. That handoff β€” from autonomous implementation back to human judgment β€” is the primary use case. Quick-dev runs long with minimal supervision. Checkpoint Preview is where you take back the wheel. ## Why It Exists Code review has two failure modes. In one, the reviewer skims the diff, nothing jumps out, and they approve. In the other, they methodically read every file but lose the thread β€” they see the trees and miss the forest. Both result in the same outcome: the review didn't catch the thing that mattered. The underlying issue is sequencing. A raw diff presents changes in file order, which is almost never the order that builds understanding. You see a helper function before you know why it exists. You see a schema change before you understand what feature it supports. The reviewer has to reconstruct the author's intent from scattered clues, and that reconstruction is where attention fails. Checkpoint Preview solves this by making the LLM do the reconstruction work. It reads the diff, the spec (if one exists), and the surrounding codebase, then presents the change in an order designed for comprehension β€” not for `git diff`. ## How It Works The workflow has five steps. Each step builds on the previous one, progressively shifting from "what is this?" toward "should we ship it?" ### 1. Orientation The workflow identifies the change (from a PR, commit, branch, spec file, or the current git state) and produces a one-line intent summary plus surface area stats: files changed, modules touched, lines of logic, boundary crossings, and new public interfaces. This is the "is this what I think it is?" moment. Before reading any code, the reviewer confirms they're looking at the right thing and calibrates their expectations for scope. ### 2. Walkthrough The change is organized by **concern** β€” cohesive design intents like "input validation" or "API contract" β€” not by file. Each concern gets a short explanation of *why* this approach was chosen, followed by clickable `path:line` stops that the reviewer can follow through the code. This is the design judgment step. The reviewer evaluates whether the approach is right for the system, not whether the code is correct. Concerns are sequenced top-down: the highest-level intent first, then supporting implementation. The reviewer never encounters a reference to something they haven't seen yet. ### 3. Detail Pass After the reviewer understands the design, the workflow surfaces 2-5 spots where a mistake would have the highest blast radius. These are tagged by risk category β€” `[auth]`, `[schema]`, `[billing]`, `[public API]`, `[security]`, and others β€” and ordered by how much breaks if they're wrong. This is not a bug hunt. Automated tests and CI handle correctness. The detail pass activates risk awareness: "here are the places where being wrong costs the most." If the reviewer wants to go deeper on a specific area, they can say "dig into [area]" for a targeted correctness-focused re-review. If the spec went through adversarial review loops (machine hardening), those findings are surfaced here too β€” not the bugs that were fixed, but the decisions that the review loop flagged that the reviewer should be aware of. ### 4. Testing Suggests 2-5 ways to manually observe the change working. Not automated test commands β€” manual observations that build confidence no test suite provides. A UI interaction to try, a CLI command to run, an API request to send, with expected results for each. If the change has no user-visible behavior, it says so. No invented busywork. ### 5. Wrap-Up The reviewer makes the call: approve, rework, or keep discussing. If approving a PR, the workflow can help with `gh pr review --approve`. If reworking, it helps diagnose whether the problem was the approach, the spec, or the implementation, and helps draft actionable feedback tied to specific code locations. ## It's a Conversation, Not a Report The workflow presents each step as a starting point, not a final word. Between steps β€” or in the middle of one β€” you can talk to the LLM, ask questions, challenge its framing, or pull in other skills to get a different perspective: - **"run advanced elicitation on the error handling"** β€” push the LLM to reconsider and refine its analysis of a specific area - **"party mode on whether this schema migration is safe"** β€” bring multiple agent perspectives into a focused debate - **"run code review"** β€” generate structured agentic findings with adversarial and edge-case analysis The checkpoint workflow doesn't lock you into a linear path. It gives you structure when you want it and gets out of the way when you want to explore. The five steps are there to make sure you see the whole picture, but how deep you go at each step β€” and what tools you bring in β€” is entirely up to you. ## The Review Trail The walkthrough step works best when it has a **Suggested Review Order** β€” a list of stops the spec author wrote to guide reviewers through the change. When a spec includes this, the workflow uses it directly. When no author-produced trail exists, the workflow generates one from the diff and codebase context. A generated trail is lower quality than an author-produced one, but far better than reading changes in file order. ## When to Use It The primary scenario is the handoff from `bmad-quick-dev`: the implementation is done, the spec file is open in your editor with a review trail appended, and you need to decide whether to ship. Say "checkpoint" and go. It also works standalone: - **Reviewing a PR** β€” especially one with more than a handful of files or cross-cutting changes - **Onboarding to a change** β€” when you need to understand what happened on a branch you didn't write - **Sprint review** β€” the workflow can pick up stories marked `review` in your sprint status file Invoke it by saying "checkpoint" or "walk me through this change." It works in any terminal, but you'll get more out of it inside an IDE β€” VS Code, Cursor, or similar β€” because the workflow produces `path:line` references at every step. In an IDE-embedded terminal those are clickable, so you can jump from file to file as you follow the review trail. ## What It Is Not Checkpoint Preview is not a substitute for automated review. It does not run linters, type checkers, or test suites. It does not assign severity scores or produce pass/fail verdicts. It is a reading guide that helps a human apply their judgment where it matters most. You hand `bmad-investigate` a crash log, a stack trace, or just a "this used to work, now it doesn't". The skill takes over the investigator's discipline for the duration of the run. It does not start fixing. It opens a case file. Every finding gets graded. Every hypothesis gets a status. Wrong turns are kept, not erased. The deliverable is a document another engineer can pick up cold. This page explains why investigation is its own discipline, and what the skill buys you that a regular dev workflow doesn't. ## The Problem With "Just Debug It" Normal debugging blends three things: looking at evidence, reasoning about cause, and changing code to test the theory. When they're blended, two failure modes show up. The first is **narrative lock-in**. The first plausible story becomes the working theory, and every observation gets bent to fit it. The bug stays unfixed until someone gives up and starts over. Hours later. The second is **evidence amnesia**. You traced something, ruled it out, but didn't write down why. Two days later, with fresh eyes, you trace it again. Or worse, a colleague picks up the bug and re-runs the same dead end you already eliminated. The skill's design is a direct response to both. ## Evidence Grading Every finding in an investigation is one of three things. - **Confirmed.** Directly observed in logs, code, or dumps; cited with a specific reference (a `path:line`, a log timestamp, a commit hash). If someone asks "how do you know?", you point at the citation. - **Deduced.** Logically follows from confirmed evidence; the reasoning chain is shown. If a step in the chain is wrong, the deduction is wrong, and you can see exactly which step. - **Hypothesized.** Plausible but unconfirmed. States what evidence would confirm or refute, and declares upfront what would close it. Hypotheses are explicitly *not facts*. The grading is not about being humble. It's about making the case file readable. A reader can scan the Confirmed section to know what is true, the Deduced section to know what follows, and the Hypothesized section to know what is still open. Confusion between the three is the most common reason investigations spiral. ## Stronghold First Investigation never starts from a theory. It starts from one piece of confirmed evidence and expands outward. That evidence might be a specific error message, a stack frame, or a timestamped log entry. This is the opposite of how investigations often go. Someone has a hunch, builds a theory, and then hunts for evidence that supports it. The hunch can be right; the *method* is fragile because it makes confirmation bias the default. A stronghold is a fact you can return to when reasoning gets murky. If a deduction takes you somewhere strange, you can walk it back to the stronghold and try a different branch. Without one, you don't know which step to undo. When evidence is sparse, the skill says so and switches to hypothesis-driven exploration: form hypotheses from what's available, identify what would test each, present a prioritized data-collection list. Missing evidence is itself a finding. ## Hypothesis Discipline Hypotheses are never deleted from the case file. When evidence confirms or refutes one, its **Status** field updates from Open to Confirmed or Refuted, and a **Resolution** explains what evidence settled it. This rule has a real cost. Case files grow. The benefit is real too. The full reasoning history becomes part of the deliverable. Six months later, when a similar bug surfaces, the next investigator can read the original case file and see which paths were already eliminated and why. Without that history, every new investigator re-runs the same dead ends. It also disciplines the present-tense investigator. If you can't delete a wrong hypothesis, you have to disprove it with cited evidence. Quietly dropping it when it becomes inconvenient is no longer an option. ## Challenge the Premise The user's description of the problem is a hypothesis, not a fact. "The cache is broken" is something a user *believes*. Before the skill builds an investigation around it, the technical claims are verified independently. If the evidence contradicts the premise, the report says so directly. This is the forensic instinct: the witness's account is data, not truth. Sometimes the reported bug is real but mislabeled. Sometimes the described symptom is downstream of a different cause. Investigations that take the premise as gospel diagnose the wrong defect, and the bug returns in a slightly different form. ## A Calibrated Walk The skill is one procedure, not two modes. It calibrates how much defect-chasing versus how much area-exploration the input demands, on a continuous scale. A symptom-driven case (a ticket, a crash, an error message, a "this used to work") leans into hypothesis tracking, timeline reconstruction, and a fix direction. A no-symptom case (understanding a module before you touch it, evaluating reusability, building a mental model) leans into I/O mapping, control-flow filtering, and a verification plan. Most real cases sit somewhere between, and the case file reflects whichever balance the evidence required. The discipline is the same regardless of where on the scale a case lands: stronghold first, evidence grading, hypothesis tracking, never erase. The output is always at `{implementation_artifacts}/investigations/{slug}-investigation.md`, with sections that don't apply to a given case left empty or omitted. When a deep bug requires understanding a broader subsystem, the procedure folds in the I/O mapping, control-flow filtering, working-backward-from-outputs, and cross-component boundary tracing techniques inline. The area model lands in the same case file. There is no mode switch. ## Methodology Lives in the Skill The investigator's discipline is a property of the skill itself. Whoever invokes `bmad-investigate` takes on the methodology and communication style for the run: clinical precision, evidence-first language, no hedging, case-file framing. When the skill ends, the caller returns to its prior voice. No persona swap, just a tone shift from the skill's principles. This matters because investigation and implementation reward different instincts. Investigators are slow and precise. Implementers are fast and confident. The same brain doing both in one session tends to do neither well. The skill carves out the investigative posture inline, without a context switch to a separate identity. ## What You Get A completed investigation file: - Separates Confirmed findings (with citations) from Deductions and Hypotheses - Preserves all hypotheses ever formed, with their final Status and Resolution - Reconstructs a timeline of events from multiple evidence sources - Identifies data gaps and what they would resolve - Provides actionable conclusions grounded in evidence - Includes a reproduction plan when a root cause is identified - Maintains an investigation backlog of paths still to explore Hand it to an engineer who was not present and they understand what happened, what is known, and what remains uncertain. That's the bar. ## The Bigger Idea Most "AI debugging" today blends evidence, reasoning, and code changes into one stream of plausible-looking text. The signal is hard to find, the dead ends repeat, and the case file, if there is one, is a chat log nobody wants to read. `bmad-investigate` treats investigation as a discipline with its own deliverable. Evidence has a grade. Hypotheses have a status. Wrong turns are documented, not erased. The case file outlives the session. When the next bug shows up that looks like one you've seen before, you have somewhere to start that isn't a blank prompt. You say "Hey Mary, let's brainstorm," and Mary activates. She greets you by name, in the language you configured, with her distinctive persona. She reminds you that `bmad-help` is always available. Then she skips the menu entirely and drops straight into brainstorming β€” because your intent was clear. This page explains what's actually happening and why BMad is designed this way. ## The Three-Legged Stool BMad's agent model rests on three primitives that compose: | Primitive | What it provides | Where it lives | |---|---|---| | **Skill** | Capability β€” a discrete thing the assistant can do (brainstorm, draft a PRD, implement a story) | `.claude/skills/{skill-name}/SKILL.md` (or your IDE's equivalent) | | **Named agent** | Persona continuity β€” a recognizable identity that wraps a menu of related skills with consistent voice, principles, and visual cues | Skills whose directory starts with `bmad-agent-*` | | **Customization** | Makes it yours β€” overrides that reshape an agent's behavior, add MCP integrations, swap templates, layer in org conventions | `_bmad/custom/{skill-name}.toml` (committed team overrides) and `.user.toml` (personal, gitignored) | Pull any leg away and the experience collapses: - Skills without agents β†’ capability lists the user has to navigate by name or code - Agents without skills β†’ personas with nothing to do - No customization β†’ every user gets the same out-of-box behavior, forcing forks for any org-specific need ## What Named Agents Buy You BMad ships six named agents, each anchored to a phase of the BMad Method: | Agent | Phase | Module | |---|---|---| | πŸ“Š **Mary**, Business Analyst | Analysis | market research, brainstorming, product briefs, PRFAQs | | πŸ“š **Paige**, Technical Writer | Analysis | project documentation, diagrams, doc validation | | πŸ“‹ **John**, Product Manager | Planning | PRD creation, epic/story breakdown, implementation readiness | | 🎨 **Sally**, UX Designer | Planning | UX design specifications | | πŸ—οΈ **Winston**, System Architect | Solutioning | technical architecture, alignment checks | | πŸ’» **Amelia**, Senior Engineer | Implementation | story execution, quick-dev, code review, sprint planning | They each have a hardcoded identity (name, title, domain) and a customizable layer (role, principles, communication style, icon, menu). You can rewrite Mary's principles or add menu items; you can't rename her β€” that's deliberate. Brand recognition survives customization so "hey Mary" always activates the analyst, regardless of how a team has shaped her behavior. ## The Activation Flow When you invoke a named agent, eight steps run in order: 1. **Resolve the agent block** β€” merge the shipped `customize.toml` with team and personal overrides, via a Python resolver using stdlib `tomllib` 2. **Execute prepend steps** β€” any pre-flight behavior the team configured 3. **Adopt persona** β€” hardcoded identity plus customized role, communication style, principles 4. **Load persistent facts** β€” org rules, compliance notes, optionally files loaded via a `file:` prefix (e.g., `file:{project-root}/docs/project-context.md`) 5. **Load config** β€” user name, communication language, output language, artifact paths 6. **Greet** β€” personalized, in the configured language, with the agent's emoji prefix so you can see at a glance who's speaking 7. **Execute append steps** β€” any post-greet setup the team configured 8. **Dispatch or present the menu** β€” if your opening message maps to a menu item, go directly; otherwise render the menu and wait for input Step 8 is where intent meets capability. "Hey Mary, let's brainstorm" skips rendering because `bmad-brainstorming` is an obvious match for `BP` on Mary's menu. If you say something ambiguous, she asks once, briefly, not as a confirmation ritual. If nothing fits, she continues the conversation normally. ## Why Not Just a Menu? Menus force the user to meet the tool halfway. You have to remember that brainstorming lives under code `BP` on the analyst agent, not the PM agent, and know which persona owns which capabilities. That's cognitive overhead the tool is making you carry. Named agents invert it. You say what you want, to whom, in whatever words feel natural. The agent knows who they are and what they do. When your intent is clear enough, they just go. The menu is still there as a fallback β€” show it when you're exploring, skip it when you're not. ## Why Not Just a Blank Prompt? Blank prompts assume you know the magic words. "Help me brainstorm" might work, but "let's ideate on my SaaS idea" might not, and the results depend on how you phrased the ask. You become responsible for prompt engineering. Named agents add structure without closing off freedom. The persona stays consistent, the capabilities are discoverable, and `bmad-help` is always one command away. You don't have to guess what the agent can do, and you don't need a manual to use it either. ## Customization as a First-Class Citizen The customization model is what lets this scale beyond a single developer. Every agent ships a `customize.toml` with sensible defaults. Teams commit overrides to `_bmad/custom/bmad-agent-{role}.toml`. Individuals can layer personal preferences in `.user.toml` (gitignored). The resolver merges all three at activation time with predictable structural rules. Most users never hand-author these files. The `bmad-customize` skill walks through picking the target, choosing agent vs workflow scope, authoring the override, and verifying the merge β€” so the customization surface stays accessible to anyone who understands their intent, not just those fluent in TOML. Concrete example: a team commits a single file telling Amelia to always use the Context7 MCP tool for library docs and to fall back to Linear when a story isn't in the local epics list. Every dev workflow Amelia dispatches (dev-story, quick-dev, create-story, code-review) inherits that behavior, with no source edits or per-workflow duplication required. There's also a second customization surface for *cross-cutting* concerns: the central `_bmad/config.toml` and `_bmad/config.user.toml` (both installer-owned, rebuilt from each module's `module.yaml`) plus `_bmad/custom/config.toml` (team, committed) and `_bmad/custom/config.user.toml` (personal, gitignored) for overrides. This is where the **agent roster** lives β€” the lightweight descriptors that roster consumers like `bmad-party-mode`, `bmad-retrospective`, and `bmad-advanced-elicitation` read to know who's available and how to embody them. Rebrand an agent org-wide with a team override; add fictional voices (Kirk, Spock, a domain expert persona) as personal experiments via the `.user.toml` override β€” without touching any skill folder. The per-skill file shapes how Mary *behaves* when she activates; the central config shapes how other skills *see* her when they look at the field. For the full customization surface and worked examples, see: - [How to Customize BMad](../how-to/customize-bmad.md) β€” the reference for what's customizable and how merge works - [How to Expand BMad for Your Organization](../how-to/expand-bmad-for-your-org.md) β€” five worked recipes spanning agent-wide rules, workflow conventions, external publishing, template swaps, and agent roster customization - `bmad-customize` skill β€” the guided authoring helper that turns intent into a correctly-placed, verified override file ## The Bigger Idea Most AI assistants today are either menus or prompts, and both shift cognitive load onto the user. Named agents plus customizable skills let you talk to a teammate who already knows the work, and let your organization shape that teammate without forking. The next time you type "Hey Mary, let's brainstorm" and she just gets on with it, notice what didn't happen. There was no slash command, no menu to navigate, no awkward reminder of what she can do. That absence is the design. Get all your AI agents in one conversation. ## What is Party Mode? Run `bmad-party-mode` and you've got your whole AI team in one room - PM, Architect, Dev, UX Designer, whoever you need. BMad Master orchestrates, picking relevant agents per message. Agents respond in character, agree, disagree, and build on each other's ideas. The conversation continues as long as you want. Ask follow-ups, push back on answers, redirect the discussion - it's a real back-and-forth with your agents until you're done. **Good for:** - Big decisions with tradeoffs - Brainstorming sessions - Post-mortems when things go wrong - Sprint retrospectives and planning ## Examples ### Calling Out Bad Architecture **You:** "Okay team, our last sprint was a disaster. The authentication service went down three times. Who screwed this up?" **Architect:** "The design was sound - distributed authentication with proper fallbacks. If implementation deviated from the spec..." **Dev:** "I followed the architecture doc exactly. The spec didn't account for concurrent session invalidation race conditions." **PM:** "Both of you missed the bigger issue - we didn't validate session management requirements in the PRD. This is on me for not catching it." **TEA:** "And I should've caught this in integration tests. The test scenarios didn't cover concurrent invalidation." ### Creative Brainstorming **You:** "How do we make onboarding feel magical instead of boring?" **UX Designer:** "Start with progressive disclosure - reveal features as users need them, not all at once in a tutorial." **Storyteller:** "What if onboarding was a story? Each step reveals a character's journey - the user IS the hero." **Game Designer:** "Building on that - what if the first 'quest' is actually solving a real user problem? They learn by doing something valuable." ### Technical Decision **You:** "Monolith or microservices for MVP?" **Architect:** "Start monolith. Microservices add complexity you don't need at 1000 users." **PM:** "Agree. Time to market matters more than theoretical scalability." **Dev:** "Monolith with clear module boundaries. We can extract services later if needed." :::tip[Better Decisions] Better decisions through diverse perspectives. Welcome to party mode. ::: 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 `bmad-correct-course` for significant changes ::: 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:** - `bmad-create-architecture` β€” respects technical preferences during solutioning - `bmad-create-story` β€” informs story creation with project patterns - `bmad-dev-story` β€” guides implementation decisions - `bmad-code-review` β€” validates against project standards - `bmad-quick-dev` β€” applies patterns when implementing specs - `bmad-sprint-planning`, `bmad-retrospective`, `bmad-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 `bmad-create-architecture` | Document your technical preferences so the architect respects them | | **New project, after architecture** | Via `bmad-generate-project-context` or manually | Capture architecture decisions for implementation agents | | **Existing project** | Via `bmad-generate-project-context` | Discover existing patterns so agents follow established conventions | | **Quick Flow project** | Before or during `bmad-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 `bmad-generate-project-context` workflow after completing your architecture: ```bash bmad-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 `bmad-generate-project-context` to discover existing patterns: ```bash bmad-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 `bmad-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. ::: Intent in, code changes out, with as few human-in-the-loop turns as possible β€” without sacrificing quality. It lets the model run longer between checkpoints, then brings the human back only when the task cannot safely continue without human judgment or when it is time to review the end result. ![Quick Dev workflow diagram](/diagrams/quick-dev-diagram.png) ## Why This Exists Human-in-the-loop turns are necessary and expensive. Current LLMs still fail in predictable ways: they misread intent, fill gaps with confident guesses, drift into unrelated work, and generate noisy review output. At the same time, constant human intervention limits development velocity. Human attention is the bottleneck. `bmad-quick-dev` rebalances that tradeoff. It trusts the model to run unsupervised for longer stretches, but only after the workflow has created a strong enough boundary to make that safe. ## The Core Design ### 1. Compress intent first The workflow starts by having the human and the model compress the request into one coherent goal. The input can begin as a rough expression of intent, but before the workflow runs autonomously it has to become small enough, clear enough, and contradiction-free enough to execute. Intent can come in many forms: a couple of phrases, a bug tracker link, output from plan mode, text copied from a chat session, or even a story number from BMAD's own `epics.md`. In that last case, the workflow will not understand BMAD story-tracking semantics, but it can still take the story itself and run with it. This workflow does not eliminate human control. It relocates it to a small number of high-value moments: - **Intent clarification** - turning a messy request into one coherent goal without hidden contradictions - **Spec approval** - confirming that the frozen understanding is the right thing to build - **Review of the final product** - the primary checkpoint, where the human decides whether the result is acceptable at the end ### 2. Route to the smallest safe path Once the goal is clear, the workflow decides whether this is a true one-shot change or whether it needs the fuller path. Small, zero-blast-radius changes can go straight to implementation. Everything else goes through planning so the model has a stronger boundary before it runs longer on its own. ### 3. Run longer with less supervision After that routing decision, the model can carry more of the work on its own. On the fuller path, the approved spec becomes the boundary the model executes against with less supervision, which is the whole point of the design. ### 4. Diagnose failure at the right layer If the implementation is wrong because the intent was wrong, patching the code is the wrong fix. If the code is wrong because the spec was weak, patching the diff is also the wrong fix. The workflow is designed to diagnose where the failure entered the system, go back to that layer, and regenerate from there. Review findings are used to decide whether the problem came from intent, spec generation, or local implementation. Only truly local problems get patched locally. ### 5. Bring the human back only when needed The intent interview is human-in-the-loop, but it is not the same kind of interruption as a recurring checkpoint. The workflow tries to keep those recurring checkpoints to a minimum. After the initial shaping of intent, the human mainly comes back when the workflow cannot safely continue without judgment and at the end, when it is time to review the result. - **Intent-gap resolution** - stepping back in when review proves the workflow could not safely infer what was meant Everything else is a candidate for longer autonomous execution. That tradeoff is deliberate. Older patterns spend more human attention on continuous supervision. Quick Dev spends more trust on the model, but saves human attention for the moments where human reasoning has the highest leverage. ## Why the Review System Matters The review phase is not just there to find bugs. It is there to route correction without destroying momentum. This workflow works best on a platform that can spawn subagents, or at least invoke another LLM through the command line and wait for a result. If your platform does not support that natively, you can add a skill to do it. Context-free subagents are a cornerstone of the review design. Agentic reviews often go wrong in two ways: - They generate too many findings, forcing the human to sift through noise. - They derail the current change by surfacing unrelated issues and turning every run into an ad hoc cleanup project. Quick Dev addresses both by treating review as triage. Some findings belong to the current change. Some do not. If a finding is incidental rather than causally tied to the current work, the workflow can defer it instead of forcing the human to handle it immediately. That keeps the run focused and prevents random tangents from consuming the budget of attention. That triage will sometimes be imperfect. That is acceptable. It is usually better to misjudge some findings than to flood the human with thousands of low-value review comments. The system is optimizing for signal quality, not exhaustive recall. 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. ::: ## Default Agents This page lists the default BMM (Agile suite) agents that install with BMad Method, along with their skill IDs, menu triggers, and primary workflows. Each agent is invoked as a skill. ## Notes - Each agent is available as a skill, generated by the installer. The skill ID (e.g., `bmad-dev`) is used to invoke the agent. - Triggers are the short menu codes (e.g., `CP`) and fuzzy matches shown in each agent menu. - QA test generation is handled by the `bmad-qa-generate-e2e-tests` workflow skill, available through the Developer agent. The full Test Architect (TEA) lives in its own module. | Agent | Skill ID | Triggers | Primary workflows | | --------------------------- | -------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------- | | Analyst (Mary) | `bmad-analyst` | `BP`, `MR`, `DR`, `TR`, `CB`, `WB`, `DP` | Brainstorm, Market Research, Domain Research, Technical Research, Create Brief, PRFAQ Challenge, Document Project | | Product Manager (John) | `bmad-pm` | `CP`, `VP`, `EP`, `CE`, `IR`, `CC` | Create/Validate/Edit PRD, Create Epics and Stories, Implementation Readiness, Correct Course | | Architect (Winston) | `bmad-architect` | `CA`, `IR` | Create Architecture, Implementation Readiness | | Developer (Amelia) | `bmad-agent-dev` | `DS`, `QD`, `QA`, `CR`, `SP`, `CS`, `ER` | Dev Story, Quick Dev, QA Test Generation, Code Review, Sprint Planning, Create Story, Epic Retrospective | | UX Designer (Sally) | `bmad-ux-designer` | `CU` | Create UX Design | | Technical Writer (Paige) | `bmad-tech-writer` | `DP`, `WD`, `US`, `MG`, `VD`, `EC` | Document Project, Write Document, Update Standards, Mermaid Generate, Validate Doc, Explain Concept | ## Trigger Types Agent menu triggers use two different invocation types. Knowing which type a trigger uses helps you provide the right input. ### Workflow triggers (no arguments needed) Most triggers load a structured workflow file. Type the trigger code and the agent starts the workflow, prompting you for input at each step. Examples: `CP` (Create PRD), `DS` (Dev Story), `CA` (Create Architecture), `QD` (Quick Dev) ### Conversational triggers (arguments required) Some triggers start a free-form conversation instead of a structured workflow. These expect you to describe what you need alongside the trigger code. | Agent | Trigger | What to provide | | --- | --- | --- | | Technical Writer (Paige) | `WD` | Description of the document to write | | Technical Writer (Paige) | `US` | Preferences or conventions to add to standards | | Technical Writer (Paige) | `MG` | Diagram description and type (sequence, flowchart, etc.) | | Technical Writer (Paige) | `VD` | Document to validate and focus areas | | Technical Writer (Paige) | `EC` | Concept name to explain | **Example:** ```text WD Write a deployment guide for our Docker setup MG Create a sequence diagram showing the auth flow EC Explain how the module system works ``` Skills are pre-built prompts that load agents, run workflows, or execute tasks inside your IDE. The BMad installer generates them from your installed modules at install time. If you later add, remove, or change modules, re-run the installer to keep skills in sync (see [Troubleshooting](#troubleshooting)). ## Skills vs. Agent Menu Triggers BMad offers two ways to start work, and they serve different purposes. | Mechanism | How you invoke it | What happens | | --- | --- | --- | | **Skill** | Type the skill name (e.g. `bmad-help`) in your IDE | Directly loads an agent, runs a workflow, or executes a task | | **Agent menu trigger** | Load an agent first, then type a short code (e.g. `DS`) | The agent interprets the code and starts the matching workflow while staying in character | Agent menu triggers require an active agent session. Use skills when you know which workflow you want. Use triggers when you are already working with an agent and want to switch tasks without leaving the conversation. ## How Skills Are Generated When you run `npx bmad-method install`, the installer reads the manifests for every selected module and writes one skill per agent, workflow, task, and tool. Each skill is a directory containing a `SKILL.md` file that instructs the AI to load the corresponding source file and follow its instructions. The installer uses templates for each skill type: | Skill type | What the generated file does | | --- | --- | | **Agent launcher** | Loads the agent persona file, activates its menu, and stays in character | | **Workflow skill** | Loads the workflow config and follows its steps | | **Task skill** | Loads a standalone task file and follows its instructions | | **Tool skill** | Loads a standalone tool file and follows its instructions | :::note[Re-running the installer] If you add or remove modules, run the installer again. It regenerates all skill files to match your current module selection. ::: ## Where Skill Files Live The installer writes skill files into an IDE-specific directory inside your project. The exact path depends on which IDE you selected during installation. | IDE / CLI | Skills directory | | --- | --- | | Claude Code | `.claude/skills/` | | Cursor | `.cursor/skills/` | | Windsurf | `.windsurf/skills/` | | Other IDEs | See the installer output for the target path | Each skill is a directory containing a `SKILL.md` file. For example, a Claude Code installation looks like: ```text .claude/skills/ β”œβ”€β”€ bmad-help/ β”‚ └── SKILL.md β”œβ”€β”€ bmad-prd/ β”‚ └── SKILL.md β”œβ”€β”€ bmad-agent-dev/ β”‚ └── SKILL.md └── ... ``` The directory name determines the skill name in your IDE. For example, the directory `bmad-agent-dev/` registers the skill `bmad-agent-dev`. ## How to Discover Your Skills Type the skill name in your IDE to invoke it. Some platforms require you to enable skills in settings before they appear. Run `bmad-help` for context-aware guidance on your next step. :::tip[Quick discovery] The generated skill directories in your project are the canonical list. Open them in your file explorer to see every skill with its description. ::: ## Skill Categories ### Agent Skills Agent skills load a specialized AI persona with a defined role, communication style, and menu of workflows. Once loaded, the agent stays in character and responds to menu triggers. | Example skill | Agent | Role | | --- | --- | --- | | `bmad-agent-dev` | Amelia (Developer) | Implements stories with strict adherence to specs | | `bmad-pm` | John (Product Manager) | Creates and validates PRDs | | `bmad-architect` | Winston (Architect) | Designs system architecture | See [Agents](./agents.md) for the full list of default agents and their triggers. ### Workflow Skills Workflow skills run a structured, multi-step process without loading an agent persona first. They load a workflow configuration and follow its steps. | Example skill | Purpose | | --- | --- | | `bmad-product-brief` | Create or update a product brief β€” guided discovery when your concept is clear | | `bmad-prfaq` | [Working Backwards PRFAQ](../explanation/analysis-phase.md#prfaq-working-backwards) challenge to stress-test your product concept | | `bmad-prd` | Create, update, or validate a Product Requirements Document | | `bmad-create-architecture` | Design system architecture | | `bmad-create-epics-and-stories` | Create epics and stories | | `bmad-dev-story` | Implement a story | | `bmad-code-review` | Run a code review | | `bmad-quick-dev` | Unified quick flow β€” clarify intent, plan, implement, review, present | See [Workflow Map](./workflow-map.md) for the complete workflow reference organized by phase. ### Task and Tool Skills Tasks and tools are standalone operations that do not require an agent or workflow context. **BMad-Help: Your Intelligent Guide** `bmad-help` is your primary interface for discovering what to do next. It inspects your project, understands natural language queries, and recommends the next required or optional step based on your installed modules. :::note[Example] ``` bmad-help bmad-help I have a SaaS idea and know all the features. Where do I start? bmad-help What are my options for UX design? ``` ::: **Other Core Tasks and Tools** The core module includes 11 built-in tools β€” reviews, compression, brainstorming, document management, and more. See [Core Tools](./core-tools.md) for the complete reference. ## Naming Convention All skills use the `bmad-` prefix followed by a descriptive name (e.g., `bmad-agent-dev`, `bmad-prd`, `bmad-help`). See [Modules](./modules.md) for available modules. ## Troubleshooting **Skills not appearing after install.** Some platforms require skills to be explicitly enabled in settings. Check your IDE's documentation or ask your AI assistant how to enable skills. You may also need to restart your IDE or reload the window. **Expected skills are missing.** The installer only generates skills for modules you selected. Run `npx bmad-method install` again and verify your module selection. Check that the skill files exist in the expected directory. **Skills from a removed module still appear.** The installer does not delete old skill files automatically. Remove the stale directories from your IDE's skills directory, or delete the entire skills directory and re-run the installer for a clean set. Every BMad installation includes a set of core skills that can be used in conjunction with any anything you are doing β€” standalone tasks and workflows that work across all projects, all modules, and all phases. These are always available regardless of which optional modules you install. :::tip[Quick Path] Run any core tool by typing its skill name (e.g., `bmad-help`) in your IDE. No agent session required. ::: ## Overview | Tool | Type | Purpose | | --- | --- | --- | | [`bmad-help`](#bmad-help) | Task | Get context-aware guidance on what to do next | | [`bmad-brainstorming`](#bmad-brainstorming) | Workflow | Facilitate interactive brainstorming sessions | | [`bmad-party-mode`](#bmad-party-mode) | Workflow | Orchestrate multi-agent group discussions | | [`bmad-distillator`](#bmad-distillator) | Task | Lossless LLM-optimized compression of documents | | [`bmad-advanced-elicitation`](#bmad-advanced-elicitation) | Task | Push LLM output through iterative refinement methods | | [`bmad-review-adversarial-general`](#bmad-review-adversarial-general) | Task | Cynical review that finds what's missing and what's wrong | | [`bmad-review-edge-case-hunter`](#bmad-review-edge-case-hunter) | Task | Exhaustive branching-path analysis for unhandled edge cases | | [`bmad-editorial-review-prose`](#bmad-editorial-review-prose) | Task | Clinical copy-editing for communication clarity | | [`bmad-editorial-review-structure`](#bmad-editorial-review-structure) | Task | Structural editing β€” cuts, merges, and reorganization | | [`bmad-shard-doc`](#bmad-shard-doc) | Task | Split large markdown files into organized sections | | [`bmad-index-docs`](#bmad-index-docs) | Task | Generate or update an index of all docs in a folder | ## bmad-help **Your intelligent guide to what comes next.** β€” Inspects your project state, detects what's been done, and recommends the next required or optional step. **Use it when:** - You finished a workflow and want to know what's next - You're new to BMad and need orientation - You're stuck and want context-aware advice - You installed new modules and want to see what's available **How it works:** 1. Scans your project for existing artifacts (PRD, architecture, stories, etc.) 2. Detects which modules are installed and their available workflows 3. Recommends next steps in priority order β€” required steps first, then optional 4. Presents each recommendation with the skill command and a brief description **Input:** Optional query in natural language (e.g., `bmad-help I have a SaaS idea, where do I start?`) **Output:** Prioritized list of recommended next steps with skill commands ## bmad-brainstorming **Generate diverse ideas through interactive creative techniques.** β€” A facilitated brainstorming session that loads proven ideation methods from a technique library and guides you toward 100+ ideas before organizing. **Use it when:** - You're starting a new project and need to explore the problem space - You're stuck generating ideas and need structured creativity - You want to use proven ideation frameworks (SCAMPER, reverse brainstorming, etc.) **How it works:** 1. Sets up a brainstorming session with your topic 2. Loads creative techniques from a method library 3. Guides you through technique after technique, generating ideas 4. Applies anti-bias protocol β€” shifts creative domain every 10 ideas to prevent clustering 5. Produces an append-only session document with all ideas organized by technique **Input:** Brainstorming topic or problem statement, optional context file **Output:** `brainstorming-session-{date}.md` with all generated ideas :::note[Quantity Target] The magic happens in ideas 50–100. The workflow encourages generating 100+ ideas before organization. ::: ## bmad-party-mode **Orchestrate multi-agent group discussions.** β€” Loads all installed BMad agents and facilitates a natural conversation where each agent contributes from their unique expertise and personality. **Use it when:** - You need multiple expert perspectives on a decision - You want agents to challenge each other's assumptions - You're exploring a complex topic that spans multiple domains **How it works:** 1. Loads the agent manifest with all installed agent personalities 2. Analyzes your topic to select 2–3 most relevant agents 3. Agents take turns contributing, with natural cross-talk and disagreements 4. Rotates agent participation to ensure diverse perspectives over time 5. Exit with `goodbye`, `end party`, or `quit` **Input:** Discussion topic or question, along with specification of personas you would like to participate (optional) **Output:** Real-time multi-agent conversation with maintained agent personalities ## bmad-distillator **Lossless LLM-optimized compression of source documents.** β€” Produces dense, token-efficient distillates that preserve all information for downstream LLM consumption. Verifiable through round-trip reconstruction. **Use it when:** - A document is too large for an LLM's context window - You need token-efficient versions of research, specs, or planning artifacts - You want to verify no information is lost during compression - Agents will need to frequently reference and find information in it **How it works:** 1. **Analyze** β€” Reads source documents, identifies information density and structure 2. **Compress** β€” Converts prose to dense bullet-point format, strips decorative formatting 3. **Verify** β€” Checks completeness to ensure all original information is preserved 4. **Validate** (optional) β€” Round-trip reconstruction test proves lossless compression **Input:** - `source_documents` (required) β€” File paths, folder paths, or glob patterns - `downstream_consumer` (optional) β€” What consumes this (e.g., "PRD creation") - `token_budget` (optional) β€” Approximate target size - `--validate` (flag) β€” Run round-trip reconstruction test **Output:** Distillate markdown file(s) with compression ratio report (e.g., "3.2:1") ## bmad-advanced-elicitation **Push LLM output through iterative refinement methods.** β€” Selects from a library of elicitation techniques to systematically improve content through multiple passes. **Use it when:** - LLM output feels shallow or generic - You want to explore a topic from multiple analytical angles - You're refining a critical document and want deeper thinking **How it works:** 1. Loads method registry with 5+ elicitation techniques 2. Selects 5 best-fit methods based on content type and complexity 3. Presents an interactive menu β€” pick a method, reshuffle, or list all 4. Applies the selected method to enhance the content 5. Re-presents options for iterative improvement until you select "Proceed" **Input:** Content section to enhance **Output:** Enhanced version of the content with improvements applied ## bmad-review-adversarial-general **Cynical review that assumes problems exist and searches for them.** β€” Takes a skeptical, jaded reviewer perspective with zero patience for sloppy work. Looks for what's missing, not just what's wrong. **Use it when:** - You need quality assurance before finalizing a deliverable - You want to stress-test a spec, story, or document - You want to find gaps in coverage that optimistic reviews miss **How it works:** 1. Reads the content with a cynical, critical perspective 2. Identifies issues across completeness, correctness, and quality 3. Searches specifically for what's missing β€” not just what's present and wrong 4. Must find a minimum of 10 issues or re-analyzes deeper **Input:** - `content` (required) β€” Diff, spec, story, doc, or any artifact - `also_consider` (optional) β€” Additional areas to keep in mind **Output:** Markdown list of 10+ findings with descriptions ## bmad-review-edge-case-hunter **Walk every branching path and boundary condition, report only unhandled cases.** β€” Pure path-tracing methodology that mechanically derives edge classes. Orthogonal to adversarial review β€” method-driven, not attitude-driven. **Use it when:** - You want exhaustive edge case coverage for code or logic - You need a complement to adversarial review (different methodology, different findings) - You're reviewing a diff or function for boundary conditions **How it works:** 1. Enumerates all branching paths in the content 2. Derives edge classes mechanically: missing else/default, unguarded inputs, off-by-one, arithmetic overflow, implicit type coercion, race conditions, timeout gaps 3. Tests each path against existing guards 4. Reports only unhandled paths β€” silently discards handled ones **Input:** - `content` (required) β€” Diff, full file, or function - `also_consider` (optional) β€” Additional areas to keep in mind **Output:** JSON array of findings, each with `location`, `trigger_condition`, `guard_snippet`, and `potential_consequence` :::note[Complementary Reviews] Run both `bmad-review-adversarial-general` and `bmad-review-edge-case-hunter` together for orthogonal coverage. The adversarial review catches quality and completeness issues; the edge case hunter catches unhandled paths. ::: ## bmad-editorial-review-prose **Clinical copy-editing focused on communication clarity.** β€” Reviews text for issues that impede comprehension. Applies Microsoft Writing Style Guide baseline. Preserves author voice. **Use it when:** - You've drafted a document and want to polish the writing - You need to ensure clarity for a specific audience - You want communication fixes without style opinion changes **How it works:** 1. Reads the content, skipping code blocks and frontmatter 2. Identifies communication issues (not style preferences) 3. Deduplicates same issues across multiple locations 4. Produces a three-column fix table **Input:** - `content` (required) β€” Markdown, plain text, or XML - `style_guide` (optional) β€” Project-specific style guide - `reader_type` (optional) β€” `humans` (default) for clarity/flow, or `llm` for precision/consistency **Output:** Three-column markdown table: Original Text | Revised Text | Changes ## bmad-editorial-review-structure **Structural editing β€” proposes cuts, merges, moves, and condensing.** β€” Reviews document organization and proposes substantive changes to improve clarity and flow before copy editing. **Use it when:** - A document was produced from multiple subprocesses and needs structural coherence - You want to reduce document length while preserving comprehension - You need to identify scope violations or buried critical information **How it works:** 1. Analyzes document against 5 structure models (Tutorial, Reference, Explanation, Prompt, Strategic) 2. Identifies redundancies, scope violations, and buried information 3. Produces prioritized recommendations: CUT, MERGE, MOVE, CONDENSE, QUESTION, PRESERVE 4. Estimates total reduction in words and percentage **Input:** - `content` (required) β€” Document to review - `purpose` (optional) β€” Intended purpose (e.g., "quickstart tutorial") - `target_audience` (optional) β€” Who reads this - `reader_type` (optional) β€” `humans` or `llm` - `length_target` (optional) β€” Target reduction (e.g., "30% shorter") **Output:** Document summary, prioritized recommendation list, and estimated reduction ## bmad-shard-doc **Split large markdown files into organized section files.** β€” Uses level-2 headers as split points to create a folder of self-contained section files with an index. **Use it when:** - A markdown document has grown too large to manage effectively (500+ lines) - You want to break a monolithic doc into navigable sections - You need separate files for parallel editing or LLM context management **How it works:** 1. Validates the source file exists and is markdown 2. Splits on level-2 (`##`) headers into numbered section files 3. Creates an `index.md` with section manifest and links 4. Prompts you to delete, archive, or keep the original **Input:** Source markdown file path, optional destination folder **Output:** Folder with `index.md` and `01-{section}.md`, `02-{section}.md`, etc. ## bmad-index-docs **Generate or update an index of all documents in a folder.** β€” Scans a directory, reads each file to understand its purpose, and produces an organized `index.md` with links and descriptions. **Use it when:** - You need a lightweight index for quick LLM scanning of available docs - A documentation folder has grown and needs an organized table of contents - You want an auto-generated overview that stays current **How it works:** 1. Scans the target directory for all non-hidden files 2. Reads each file to understand its actual purpose 3. Groups files by type, purpose, or subdirectory 4. Generates concise descriptions (3–10 words each) **Input:** Target folder path **Output:** `index.md` with organized file listings, relative links, and brief descriptions BMad extends through official modules that you select during installation. These add-on modules provide specialized agents, workflows, and tasks for specific domains beyond the built-in core and BMM (Agile suite). :::tip[Installing Modules] Run `npx bmad-method install` and select the modules you want. The installer handles downloading, configuration, and IDE integration automatically. ::: ## BMad Builder Create custom agents, workflows, and domain-specific modules with guided assistance. BMad Builder is the meta-module for extending the framework itself. - **Code:** `bmb` - **npm:** [`bmad-builder`](https://www.npmjs.com/package/bmad-builder) - **GitHub:** [bmad-code-org/bmad-builder](https://github.com/bmad-code-org/bmad-builder) **Provides:** - Agent Builder -- create specialized AI agents with custom expertise and tool access - Workflow Builder -- design structured processes with steps and decision points - Module Builder -- package agents and workflows into shareable, publishable modules - Interactive setup with YAML configuration and npm publishing support ## Creative Intelligence Suite AI-powered tools for structured creativity, ideation, and innovation during early-stage development. The suite provides multiple agents that facilitate brainstorming, design thinking, and problem-solving using proven frameworks. - **Code:** `cis` - **npm:** [`bmad-creative-intelligence-suite`](https://www.npmjs.com/package/bmad-creative-intelligence-suite) - **GitHub:** [bmad-code-org/bmad-module-creative-intelligence-suite](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite) **Provides:** - Innovation Strategist, Design Thinking Coach, and Brainstorming Coach agents - Problem Solver and Creative Problem Solver for systematic and lateral thinking - Storyteller and Presentation Master for narratives and pitches - Ideation frameworks including SCAMPER, Reverse Brainstorming, and problem reframing ## Game Dev Studio Structured game development workflows adapted for Unity, Unreal, Godot, and custom engines. Supports rapid prototyping through Quick Flow and full-scale production with epic-driven sprints. - **Code:** `gds` - **npm:** [`bmad-game-dev-studio`](https://www.npmjs.com/package/bmad-game-dev-studio) - **GitHub:** [bmad-code-org/bmad-module-game-dev-studio](https://github.com/bmad-code-org/bmad-module-game-dev-studio) **Provides:** - Game Design Document (GDD) generation workflow - Quick Dev mode for rapid prototyping - Narrative design support for characters, dialogue, and world-building - Coverage for 21+ game types with engine-specific architecture guidance ## Test Architect (TEA) Enterprise-grade test strategy, automation guidance, and release gate decisions through an expert agent and nine structured workflows. TEA goes well beyond the built-in QA agent with risk-based prioritization and requirements traceability. - **Code:** `tea` - **npm:** [`bmad-method-test-architecture-enterprise`](https://www.npmjs.com/package/bmad-method-test-architecture-enterprise) - **GitHub:** [bmad-code-org/bmad-method-test-architecture-enterprise](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise) **Provides:** - Murat agent (Master Test Architect and Quality Advisor) - Workflows for test design, ATDD, automation, test review, and traceability - NFR assessment, CI setup, and framework scaffolding - P0-P3 prioritization with optional Playwright Utils and MCP integrations ## Community Modules Community modules and a module marketplace are coming. Check the [BMad GitHub organization](https://github.com/bmad-code-org) for updates. BMad provides two testing paths: a built-in QA workflow for fast test generation and an installable Test Architect module for enterprise-grade test strategy. ## Which Should You Use? | Factor | Built-in QA | TEA Module | | --- | --- | --- | | **Best for** | Small-medium projects, quick coverage | Large projects, regulated or complex domains | | **Setup** | Nothing to install -- included in BMM | Install separately via `npx bmad-method install` | | **Approach** | Generate tests fast, iterate later | Plan first, then generate with traceability | | **Test types** | API and E2E tests | API, E2E, ATDD, NFR, and more | | **Strategy** | Happy path + critical edge cases | Risk-based prioritization (P0-P3) | | **Workflow count** | 1 (Automate) | 9 (design, ATDD, automate, review, trace, and others) | :::tip[Start with built-in QA] Most projects should start with the built-in QA workflow. If you later need test strategy, quality gates, or requirements traceability, install TEA alongside it. ::: ## Built-in QA Workflow The built-in QA workflow (`bmad-qa-generate-e2e-tests`) is part of the BMM (Agile suite) module, available through the Developer agent. It generates working tests quickly using your project's existing test framework -- no configuration or additional installation required. **Trigger:** `QA` (via the Developer agent) or `bmad-qa-generate-e2e-tests` ### What It Does The QA workflow (Automate) walks through five steps: 1. **Detect test framework** -- scans `package.json` and existing test files for your framework (Jest, Vitest, Playwright, Cypress, or any standard runner). If none exists, analyzes the project stack and suggests one. 2. **Identify features** -- asks what to test or auto-discovers features in the codebase. 3. **Generate API tests** -- covers status codes, response structure, happy path, and 1-2 error cases. 4. **Generate E2E tests** -- covers user workflows with semantic locators and visible-outcome assertions. 5. **Run and verify** -- executes the generated tests and fixes failures immediately. The workflow produces a test summary saved to your project's implementation artifacts folder. ### Test Patterns Generated tests follow a "simple and maintainable" philosophy: - **Standard framework APIs only** -- no external utilities or custom abstractions - **Semantic locators** for UI tests (roles, labels, text rather than CSS selectors) - **Independent tests** with no order dependencies - **No hardcoded waits or sleeps** - **Clear descriptions** that read as feature documentation :::note[Scope] The QA workflow generates tests only. For code review and story validation, use the Code Review workflow (`CR`) instead. ::: ### When to Use Built-in QA - Quick test coverage for a new or existing feature - Beginner-friendly test automation without advanced setup - Standard test patterns that any developer can read and maintain - Small-medium projects where comprehensive test strategy is unnecessary ## Test Architect (TEA) Module TEA is a standalone module that provides an expert agent (Murat) and nine structured workflows for enterprise-grade testing. It goes beyond test generation into test strategy, risk-based planning, quality gates, and requirements traceability. - **Documentation:** [TEA Module Docs](https://bmad-code-org.github.io/bmad-method-test-architecture-enterprise/) - **Install:** `npx bmad-method install` and select the TEA module - **npm:** [`bmad-method-test-architecture-enterprise`](https://www.npmjs.com/package/bmad-method-test-architecture-enterprise) ### What TEA Provides | Workflow | Purpose | | --- | --- | | Test Design | Create a comprehensive test strategy tied to requirements | | ATDD | Acceptance-test-driven development with stakeholder criteria | | Automate | Generate tests with advanced patterns and utilities | | Test Review | Validate test quality and coverage against strategy | | Traceability | Map tests back to requirements for audit and compliance | | NFR Assessment | Evaluate non-functional requirements (performance, security) | | CI Setup | Configure test execution in continuous integration pipelines | | Framework Scaffolding | Set up test infrastructure and project structure | | Release Gate | Make data-driven go/no-go release decisions | TEA also supports P0-P3 risk-based prioritization and optional integrations with Playwright Utils and MCP tooling. ### When to Use TEA - Projects that require requirements traceability or compliance documentation - Teams that need risk-based test prioritization across many features - Enterprise environments with formal quality gates before release - Complex domains where test strategy must be planned before tests are written - Projects that have outgrown the built-in QA's single-workflow approach ## How Testing Fits into Workflows The QA Automate workflow appears in Phase 4 (Implementation) of the BMad Method workflow map. It is designed to run **after a full epic is complete** β€” once all stories in an epic have been implemented and code-reviewed. A typical sequence: 1. For each story in the epic: implement with Dev (`DS`), then validate with Code Review (`CR`) 2. After the epic is complete: generate tests with `QA` (via the Developer agent) or TEA's Automate workflow 3. Run retrospective (`bmad-retrospective`) to capture lessons learned The built-in QA workflow works directly from source code without loading planning documents (PRD, architecture). TEA workflows can integrate with upstream planning artifacts for traceability. For more on where testing fits in the overall process, see the [Workflow Map](./workflow-map.md). The BMad Method (BMM) is a module in the BMad Ecosystem, targeted at following the best practices of context engineering and planning. AI agents work best with clear, structured context. The BMM system builds that context progressively across 4 distinct phases - each phase, and multiple workflows optionally within each phase, produce documents that inform the next, so agents always know what to build and why. The rationale and concepts come from agile methodologies that have been used across the industry with great success as a mental framework. If at any time you are unsure what to do, the `bmad-help` skill will help you stay on track or know what to do next. You can always refer to this for reference also - but `bmad-help` is fully interactive and much quicker if you have already installed the BMad Method. Additionally, if you are using different modules that have extended the BMad Method or added other complementary non-extension modules - `bmad-help` evolves to know all that is available to give you the best in-the-moment advice. Final important note: Every workflow below can be run directly with your tool of choice via skill or by loading an agent first and using the entry from the agents menu.

Open diagram in new tab β†—

## Phase 1: Analysis (Optional) Explore the problem space and validate ideas before committing to planning. [**Learn what each tool does and when to use it**](../explanation/analysis-phase.md). | Workflow | Purpose | Produces | |---------------------------------------------------------------------------|----------------------------------------------------------------------------|---------------------------| | `bmad-brainstorming` | Brainstorm Project Ideas with guided facilitation of a brainstorming coach | `brainstorming-report.md` | | `bmad-domain-research`, `bmad-market-research`, `bmad-technical-research` | Validate market, technical, or domain assumptions | Research findings | | `bmad-product-brief` | Capture strategic vision β€” best when your concept is clear | `product-brief.md` | | `bmad-prfaq` | Working Backwards β€” stress-test and forge your product concept | `prfaq-{project}.md` | ## Phase 2: Planning Define what to build and for whom. | Workflow | Purpose | Produces | |-------------------------|-------------------------------------------------------------------------------------|---------------------------------------------------| | `bmad-prd` | Create, update, or validate a PRD β€” facilitated discovery, three intents in one skill | Create/Update: `prd.md`, `addendum.md`, `decision-log.md`; Validate: `validation-report.html` + `.md` | | `bmad-create-ux-design` | Design user experience (when UX matters) | `ux-spec.md` | :::tip[Three intents in one skill] `bmad-prd` handles the full PRD lifecycle. State your intent when invoking or the skill will ask: - **Create** β€” new PRD from scratch via coached discovery; produces `prd.md`, `addendum.md`, and `decision-log.md` - **Update** β€” reconcile an existing PRD with a change signal, surfacing conflicts before applying changes - **Validate** β€” critique a PRD against a configurable checklist and produce a structured HTML findings report ::: :::tip[Upstream: `bmad-product-brief`] `bmad-product-brief` (Phase 1) produces a `product-brief.md` that `bmad-prd` can source-extract during Discovery, reducing re-explanation and keeping the two documents aligned. Neither skill requires the other β€” start with `bmad-prd` directly if you already know what you're building. ::: ## Phase 3: Solutioning Decide how to build it and break work into stories. | Workflow | Purpose | Produces | |---------------------------------------|--------------------------------------------|-----------------------------| | `bmad-create-architecture` | Make technical decisions explicit | `architecture.md` with ADRs | | `bmad-create-epics-and-stories` | Break requirements into implementable work | Epic files with stories | | `bmad-check-implementation-readiness` | Gate check before implementation | PASS/CONCERNS/FAIL decision | ## Phase 4: Implementation Build it, one story at a time. Coming soon, full phase 4 automation! | Workflow | Purpose | Produces | |------------------------|-------------------------------------------------------------------------------|------------------------------------------------------| | `bmad-sprint-planning` | Initialize tracking (once per project to sequence the dev cycle) | `sprint-status.yaml` | | `bmad-create-story` | Prepare next story for implementation | `story-[slug].md` | | `bmad-dev-story` | Implement the story | Working code + tests | | `bmad-code-review` | Validate implementation quality | Approved or changes requested | | `bmad-correct-course` | Handle significant mid-sprint changes | Updated plan or re-routing | | `bmad-sprint-status` | Track sprint progress and story status | Sprint status update | | `bmad-retrospective` | Review after epic completion | Lessons learned | | `bmad-investigate` | Forensic case investigation with evidence-graded findings, calibrated to the input | `{slug}-investigation.md` | ## Quick Flow (Parallel Track) Skip phases 1-3 for small, well-understood work. | Workflow | Purpose | Produces | |------------------|---------------------------------------------------------------------------|--------------------| | `bmad-quick-dev` | Unified quick flow β€” clarify intent, plan, implement, review, and present | `spec-*.md` + code | ## Context Management Each document becomes context for the next phase. The PRD tells the architect what constraints matter. The architecture tells the dev agent which patterns to follow. Story files give focused, complete context for implementation. Without this structure, agents make inconsistent decisions. ### Project Context :::tip[Recommended] Create `project-context.md` to ensure AI agents follow your project's rules and preferences. This file works like a constitution for your project β€” it guides implementation decisions across all workflows. This optional file can be generated at the end of Architecture Creation, or in an existing project it can be generated also to capture whats important to keep aligned with current conventions. ::: **How to create it:** - **Manually** β€” Create `_bmad-output/project-context.md` with your technology stack and implementation rules - **Generate it** β€” Run `bmad-generate-project-context` to auto-generate from your architecture or codebase [**Learn more about project-context.md**](../explanation/project-context.md) The page you're looking for doesn't exist or has been moved. [Return to Home](./index.md)