166 lines
8.6 KiB
Markdown
166 lines
8.6 KiB
Markdown
---
|
|
title: 'How to Extend BMad for Your Organization'
|
|
description: Four customization patterns that reshape BMad without forking — org conventions, agent-wide rules, external publishing, and template swaps
|
|
sidebar:
|
|
order: 9
|
|
---
|
|
|
|
BMad's customization surface is designed so that an organization can reshape behavior without editing installed files or forking skills. This guide walks through four recipes that together 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`)
|
|
:::
|
|
|
|
## The Two-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 |
|
|
|
|
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**.
|
|
|
|
## 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. Highest-leverage 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 is powerful:** Two sentences reshape every dev workflow in the org. No per-workflow duplication, no source changes, no forks. 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 about the required fields and the enterprise conventions document. The shipped default (`file:{project-root}/**/project-context.md`) still loads — 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: <url>".
|
|
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. It'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** — always runs on completion
|
|
- **Jira epic creation is visible to the whole team** and kicks off sprint-planning signals — gate 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
|
|
|
|
## Combining Recipes
|
|
|
|
All four 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 a single file. The agent-level rule (Recipe 1) lives in a separate file under the agent's name and applies 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; 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.
|