diff --git a/docs/explanation/named-agents.md b/docs/explanation/named-agents.md index 779fd8624..309ce2d7c 100644 --- a/docs/explanation/named-agents.md +++ b/docs/explanation/named-agents.md @@ -53,11 +53,11 @@ When you invoke a named agent, eight steps run in order: 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 the magic lands. "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. +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. You have to know which persona owns which capabilities. That's cognitive overhead the tool is making you carry. +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. @@ -65,17 +65,19 @@ The menu is still there as a fallback — show it when you're exploring, skip it ## Why Not Just a Blank Prompt? -Blank prompts assume you know the magic words. "Help me brainstorm" might work; "let's ideate on my SaaS idea" might not. Results vary based on how you phrase the ask. You become responsible for prompt engineering. +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 bring structure without taking freedom. The persona is consistent, the capabilities are discoverable, the menu is always one `bmad-help` away. You don't have to guess what the agent can do — but you also don't have to consult a manual to do it. +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 why this scales beyond a single developer. +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. -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. No source edits, no forks, no per-workflow duplication. +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` (installer-owned, rebuilt from each module's `module.yaml`) plus `_bmad/custom/config.toml` 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 one override; add fictional voices (Kirk, Spock, a domain expert persona) 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: @@ -84,6 +86,6 @@ For the full customization surface and worked examples, see: ## The Bigger Idea -Most AI assistants today are either menus or prompts. Both shift cognitive load onto the user. Named agents plus customizable skills do something different: they let you talk to a teammate who already knows the work, and let your organization shape that teammate without forking. +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. No slash command. No menu navigation. No awkward reminder of what she can do. That absence is the design. +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. diff --git a/docs/how-to/customize-bmad.md b/docs/how-to/customize-bmad.md index b04fbeb26..830c8266a 100644 --- a/docs/how-to/customize-bmad.md +++ b/docs/how-to/customize-bmad.md @@ -49,9 +49,7 @@ The resolver applies four structural rules. Field names are never special-cased **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. +**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 @@ -106,9 +104,7 @@ This appends the new principle to the defaults (leaving the shipped principles i 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 simply win. You only need to set the fields you're changing: +**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 @@ -119,9 +115,7 @@ 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. +**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] @@ -158,11 +152,9 @@ activation_steps_append = [ ] ``` -**Why two hooks?** 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. +**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. +**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: @@ -186,9 +178,7 @@ 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. +**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 @@ -215,7 +205,7 @@ python3 {project-root}/_bmad/scripts/resolve_customization.py \ --key agent ``` -**Requirements**: Python 3.11+ (earlier versions don't include `tomllib`). No `pip install`, no `uv`, no virtualenv. Check with `python3 --version` — some common platforms (macOS without Homebrew, Ubuntu 22.04) default `python3` to 3.10 or earlier even when 3.11+ is available to install separately. +**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. @@ -241,7 +231,7 @@ Output is always JSON. If the script is unavailable on a given platform, the SKI ## 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]`, keeping the two namespaces cleanly separated: +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 @@ -266,11 +256,96 @@ persistent_facts = [ 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), 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. +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. + +## 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**. You CAN edit `[core]` and `[modules.]` values there; the installer reads them as defaults on next install, so your edits persist. **Do not edit `[agents.]` in those files** — it's rebuilt from `module.yaml` on every install and your changes will be wiped. +- `_bmad/custom/config.toml` and `_bmad/custom/config.user.toml` are **never touched** by the installer. Put custom agents, agent descriptor overrides, and team-enforced settings there. + +### 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 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 Expand BMad for Your Organization](./expand-bmad-for-your-org.md). +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 diff --git a/docs/how-to/expand-bmad-for-your-org.md b/docs/how-to/expand-bmad-for-your-org.md index cbfbd568b..86df72c37 100644 --- a/docs/how-to/expand-bmad-for-your-org.md +++ b/docs/how-to/expand-bmad-for-your-org.md @@ -5,7 +5,7 @@ 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. +BMad's customization surface lets an organization reshape behavior without editing installed files or forking skills. This guide walks through four recipes that cover most enterprise needs. :::note[Prerequisites] @@ -14,7 +14,7 @@ BMad's customization surface is designed so that an organization can reshape beh - Python 3.11+ on PATH (for the resolver — stdlib only, no `pip install`) ::: -## The Two-Layer Mental Model +## The Three-Layer Mental Model Before picking a recipe, know where your override lands: @@ -22,14 +22,15 @@ Before picking a recipe, know where your override lands: |---|---|---| | **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**. +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. Highest-leverage pattern. +**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:** +**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 @@ -44,17 +45,17 @@ persistent_facts = [ ] ``` -**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. +**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 +- `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:** +**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 @@ -68,13 +69,13 @@ persistent_facts = [ ] ``` -**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. +**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:** +**Example: briefs auto-publish to Confluence and offer optional Jira epic creation.** ```toml # _bmad/custom/bmad-product-brief.toml @@ -107,18 +108,18 @@ 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. +**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** — 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 +- **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:** +**Example: point the product-brief workflow at an enterprise-owned template.** ```toml # _bmad/custom/bmad-product-brief.toml @@ -131,19 +132,79 @@ brief_template = "{project-root}/docs/enterprise/brief-template.md" **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 +- 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. But 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. +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:** +**Example: one line in the repo's `CLAUDE.md` reinforcing the dev-agent rule from Recipe 1.** ```markdown ``` -One sentence. Loads every session. 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. No duplication of effort — each layer owns its scope: +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. +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. ## 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. +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 one 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) @@ -181,12 +243,12 @@ on_complete = """ ... """ 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. +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. +**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. +**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.