diff --git a/docs/how-to/customize-bmad.md b/docs/how-to/customize-bmad.md index 66f215e1e..652d72689 100644 --- a/docs/how-to/customize-bmad.md +++ b/docs/how-to/customize-bmad.md @@ -268,6 +268,10 @@ on_complete = "Summarize the brief in three bullets and offer to email it via th The same field conventions cross the agent/workflow boundary: `activation_steps_prepend`/`activation_steps_append`, `persistent_facts` (with `file:` refs), 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 merge rules based on their shape. Read the workflow's `customize.toml` to see what it makes customizable. +## Worked Examples + +For complete, enterprise-oriented recipes — shaping an agent across every workflow it dispatches, enforcing org conventions, publishing outputs to Confluence and Jira, and swapping in your own output templates — see [How to Extend BMad for Your Organization](./extend-bmad-for-your-org.md). + ## Troubleshooting **Customization not appearing?** diff --git a/docs/how-to/extend-bmad-for-your-org.md b/docs/how-to/extend-bmad-for-your-org.md new file mode 100644 index 000000000..c44212583 --- /dev/null +++ b/docs/how-to/extend-bmad-for-your-org.md @@ -0,0 +1,165 @@ +--- +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: ". +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. diff --git a/src/bmm-skills/1-analysis/bmad-agent-analyst/SKILL.md b/src/bmm-skills/1-analysis/bmad-agent-analyst/SKILL.md index d38023f0f..2eba1b18f 100644 --- a/src/bmm-skills/1-analysis/bmad-agent-analyst/SKILL.md +++ b/src/bmm-skills/1-analysis/bmad-agent-analyst/SKILL.md @@ -22,7 +22,13 @@ You are Mary, the Business Analyst. You bring deep expertise in market research, Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key agent` -**If the script fails**, resolve the `agent` block yourself from `customize.toml`, with `{project-root}/_bmad/custom/{skill-name}.toml` overriding, and `{skill-name}.user.toml` overriding both (any missing file is skipped). +**If the script fails**, resolve the `agent` block yourself by merging these three files in priority order (later wins): + +1. `{skill-root}/customize.toml` — defaults +2. `{project-root}/_bmad/custom/{skill-name}.toml` — team overrides +3. `{project-root}/_bmad/custom/{skill-name}.user.toml` — personal overrides + +Any missing file is skipped. ### Step 2: Execute Prepend Steps diff --git a/src/bmm-skills/1-analysis/bmad-agent-tech-writer/SKILL.md b/src/bmm-skills/1-analysis/bmad-agent-tech-writer/SKILL.md index 405769b02..ea642c3a2 100644 --- a/src/bmm-skills/1-analysis/bmad-agent-tech-writer/SKILL.md +++ b/src/bmm-skills/1-analysis/bmad-agent-tech-writer/SKILL.md @@ -22,7 +22,13 @@ You are Paige, the Technical Writer. You transform complex concepts into accessi Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key agent` -**If the script fails**, resolve the `agent` block yourself from `customize.toml`, with `{project-root}/_bmad/custom/{skill-name}.toml` overriding, and `{skill-name}.user.toml` overriding both (any missing file is skipped). +**If the script fails**, resolve the `agent` block yourself by merging these three files in priority order (later wins): + +1. `{skill-root}/customize.toml` — defaults +2. `{project-root}/_bmad/custom/{skill-name}.toml` — team overrides +3. `{project-root}/_bmad/custom/{skill-name}.user.toml` — personal overrides + +Any missing file is skipped. ### Step 2: Execute Prepend Steps diff --git a/src/bmm-skills/1-analysis/bmad-product-brief/SKILL.md b/src/bmm-skills/1-analysis/bmad-product-brief/SKILL.md index 6350fbf82..8ae6c2be4 100644 --- a/src/bmm-skills/1-analysis/bmad-product-brief/SKILL.md +++ b/src/bmm-skills/1-analysis/bmad-product-brief/SKILL.md @@ -41,7 +41,13 @@ Check activation context immediately: Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow` -**If the script fails**, resolve the `workflow` block yourself from `customize.toml`, with `{project-root}/_bmad/custom/{skill-name}.toml` overriding, and `{skill-name}.user.toml` overriding both (any missing file is skipped). +**If the script fails**, resolve the `workflow` block yourself by merging these three files in priority order (later wins): + +1. `{skill-root}/customize.toml` — defaults +2. `{project-root}/_bmad/custom/{skill-name}.toml` — team overrides +3. `{project-root}/_bmad/custom/{skill-name}.user.toml` — personal overrides + +Any missing file is skipped. ### Step 2: Execute Prepend Steps @@ -68,11 +74,9 @@ Greet `{user_name}` if you have not already, speaking in `{communication_languag Execute each entry in `{workflow.activation_steps_append}` in order. -### Step 7: Stage 1 — Understand Intent +Activation is complete. Begin the workflow at Stage 1 below. -Proceed to Stage 1 below. - -### Stage 1: Understand Intent +## Stage 1: Understand Intent **Goal:** Know WHY the user is here and WHAT the brief is about before doing anything else. diff --git a/src/bmm-skills/1-analysis/bmad-product-brief/customize.toml b/src/bmm-skills/1-analysis/bmad-product-brief/customize.toml index 299e2436a..2f7e2f8a4 100644 --- a/src/bmm-skills/1-analysis/bmad-product-brief/customize.toml +++ b/src/bmm-skills/1-analysis/bmad-product-brief/customize.toml @@ -34,8 +34,14 @@ persistent_facts = [ "file:{project-root}/**/project-context.md", ] +# Path to the brief structure template used in Stage 4 drafting. +# Bare paths resolve from the skill root; use `{project-root}/...` to +# point at an org-owned template elsewhere in the repo. Override wins. + +brief_template = "resources/brief-template.md" + # Scalar: executed when the workflow reaches its terminal stage, after # the main output has been delivered. Override wins. Leave empty for -# no post-completion behavior. +# no custom post-completion behavior. on_complete = "" diff --git a/src/bmm-skills/1-analysis/bmad-product-brief/prompts/draft-and-review.md b/src/bmm-skills/1-analysis/bmad-product-brief/prompts/draft-and-review.md index a44c97990..a8ac98012 100644 --- a/src/bmm-skills/1-analysis/bmad-product-brief/prompts/draft-and-review.md +++ b/src/bmm-skills/1-analysis/bmad-product-brief/prompts/draft-and-review.md @@ -9,7 +9,7 @@ ## Step 1: Draft the Executive Brief -Use `resources/brief-template.md` as a guide — adapt structure to fit the product's story. +Use the template at `{workflow.brief_template}` as a guide — adapt structure to fit the product's story. **Writing principles:** - **Executive audience** — persuasive, clear, concise. 1-2 pages. diff --git a/src/bmm-skills/2-plan-workflows/bmad-agent-pm/SKILL.md b/src/bmm-skills/2-plan-workflows/bmad-agent-pm/SKILL.md index 97b1e5ebf..a4ef415af 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-agent-pm/SKILL.md +++ b/src/bmm-skills/2-plan-workflows/bmad-agent-pm/SKILL.md @@ -22,7 +22,13 @@ You are John, the Product Manager. You drive PRD creation through user interview Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key agent` -**If the script fails**, resolve the `agent` block yourself from `customize.toml`, with `{project-root}/_bmad/custom/{skill-name}.toml` overriding, and `{skill-name}.user.toml` overriding both (any missing file is skipped). +**If the script fails**, resolve the `agent` block yourself by merging these three files in priority order (later wins): + +1. `{skill-root}/customize.toml` — defaults +2. `{project-root}/_bmad/custom/{skill-name}.toml` — team overrides +3. `{project-root}/_bmad/custom/{skill-name}.user.toml` — personal overrides + +Any missing file is skipped. ### Step 2: Execute Prepend Steps diff --git a/src/bmm-skills/2-plan-workflows/bmad-agent-ux-designer/SKILL.md b/src/bmm-skills/2-plan-workflows/bmad-agent-ux-designer/SKILL.md index 699a7a73a..56902d3e9 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-agent-ux-designer/SKILL.md +++ b/src/bmm-skills/2-plan-workflows/bmad-agent-ux-designer/SKILL.md @@ -22,7 +22,13 @@ You are Sally, the UX Designer. You translate user needs into interaction design Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key agent` -**If the script fails**, resolve the `agent` block yourself from `customize.toml`, with `{project-root}/_bmad/custom/{skill-name}.toml` overriding, and `{skill-name}.user.toml` overriding both (any missing file is skipped). +**If the script fails**, resolve the `agent` block yourself by merging these three files in priority order (later wins): + +1. `{skill-root}/customize.toml` — defaults +2. `{project-root}/_bmad/custom/{skill-name}.toml` — team overrides +3. `{project-root}/_bmad/custom/{skill-name}.user.toml` — personal overrides + +Any missing file is skipped. ### Step 2: Execute Prepend Steps diff --git a/src/bmm-skills/3-solutioning/bmad-agent-architect/SKILL.md b/src/bmm-skills/3-solutioning/bmad-agent-architect/SKILL.md index 139d84e00..07bd26ca4 100644 --- a/src/bmm-skills/3-solutioning/bmad-agent-architect/SKILL.md +++ b/src/bmm-skills/3-solutioning/bmad-agent-architect/SKILL.md @@ -22,7 +22,13 @@ You are Winston, the System Architect. You turn product requirements and UX into Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key agent` -**If the script fails**, resolve the `agent` block yourself from `customize.toml`, with `{project-root}/_bmad/custom/{skill-name}.toml` overriding, and `{skill-name}.user.toml` overriding both (any missing file is skipped). +**If the script fails**, resolve the `agent` block yourself by merging these three files in priority order (later wins): + +1. `{skill-root}/customize.toml` — defaults +2. `{project-root}/_bmad/custom/{skill-name}.toml` — team overrides +3. `{project-root}/_bmad/custom/{skill-name}.user.toml` — personal overrides + +Any missing file is skipped. ### Step 2: Execute Prepend Steps diff --git a/src/bmm-skills/4-implementation/bmad-agent-dev/SKILL.md b/src/bmm-skills/4-implementation/bmad-agent-dev/SKILL.md index 122727647..59e5bf8a5 100644 --- a/src/bmm-skills/4-implementation/bmad-agent-dev/SKILL.md +++ b/src/bmm-skills/4-implementation/bmad-agent-dev/SKILL.md @@ -22,7 +22,13 @@ You are Amelia, the Senior Software Engineer. You execute approved stories with Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key agent` -**If the script fails**, resolve the `agent` block yourself from `customize.toml`, with `{project-root}/_bmad/custom/{skill-name}.toml` overriding, and `{skill-name}.user.toml` overriding both (any missing file is skipped). +**If the script fails**, resolve the `agent` block yourself by merging these three files in priority order (later wins): + +1. `{skill-root}/customize.toml` — defaults +2. `{project-root}/_bmad/custom/{skill-name}.toml` — team overrides +3. `{project-root}/_bmad/custom/{skill-name}.user.toml` — personal overrides + +Any missing file is skipped. ### Step 2: Execute Prepend Steps