docs(skills): enterprise customization recipes + workflow template variable

Three independent improvements bundled because they share the same
surface (workflow/agent customization) and landed from the same design
discussion:

## Fallback sentence disambiguated (7 SKILL.md files)

The "if the script fails" fallback used to say `{project-root}/_bmad/
custom/{skill-name}.toml` for the team override and then just `{skill-
name}.user.toml` for the user override, leaving the user file's
location implicit. LLMs could reasonably guess skill root or project
root instead. Replaced with an unambiguous numbered list that spells
out the full path for every file in the merge chain.

## Product-brief: stage promotion + brief_template variable

- Promoted `## Stage 1: Understand Intent` from a nested step inside
  "On Activation" to a top-level section. The previous "Step 7: Stage
  1 — Understand Intent → Proceed to Stage 1 below" was mechanical
  numbering pretending to be a step. Activation now ends cleanly at
  Step 6; Stage 1 is a peer section.
- Added `brief_template` as a workflow-level scalar customization
  defaulting to `resources/brief-template.md`. Stage 4 reads
  `{workflow.brief_template}` instead of the hardcoded path, so orgs
  can point at their own template under `{project-root}/...` without
  forking the skill.

## New doc: docs/how-to/extend-bmad-for-your-org.md

Four worked recipes that together cover most enterprise scenarios:

1. Shape an agent across every workflow it dispatches (dev agent +
   Context7 MCP + Linear search — the highest-leverage pattern)
2. Enforce org conventions inside a specific workflow (product-brief
   + compliance-field persistent_facts)
3. Publish completed outputs to external systems (product-brief +
   Confluence + Jira via MCP, gated on user confirmation for Jira)
4. Swap in your own output template (product-brief + brief_template
   variable swap)

Opens with the two-layer mental model (agent spans workflows,
workflow is local) so readers pick the right granularity before
reading any recipe. Closes with a "Combining Recipes" section
showing all four composed. Cross-linked from customize-bmad.md.

## Validation

- Resolver: workflow.brief_template returns the default cleanly.
- validate-file-refs.js: 254 files scanned, 146 refs checked
  (+7 from this commit), 0 broken.

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?**

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: <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.

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
 

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
 

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.
 

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 = ""

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.

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
 

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
 

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
 

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