Merge pull request #76 from bmad-code-org/custom-support

feat(builders): customize.toml support for workflows, agents, and modules

Author: bmadcode

.claude-plugin/marketplace.json

@@ -16,12 +16,7 @@
       "author": {
         "name": "Brian (BMad) Madison"
       },
-      "skills": [
-        "./skills/bmad-agent-builder",
-        "./skills/bmad-bmb-setup",
-        "./skills/bmad-module-builder",
-        "./skills/bmad-workflow-builder"
-      ]
+      "skills": ["./skills/bmad-agent-builder", "./skills/bmad-bmb-setup", "./skills/bmad-module-builder", "./skills/bmad-workflow-builder"]
     },
     {
       "name": "sample-plugins",
@@ -49,9 +44,7 @@
       "author": {
         "name": "Brian (BMad) Madison"
       },
-      "skills": [
-        "./samples/bmad-agent-dream-weaver"
-      ]
+      "skills": ["./samples/bmad-agent-dream-weaver"]
     }
   ]
 }

README.md

@@ -62,7 +62,7 @@ BMad Builder lets you create:
 
 ## Support BMad
 
-BMad is free for everyone and always will be. Star this repo, [buy me a coffee](https://buymeacoffee.com/bmad), or email contact@bmadcode.com for corporate sponsorship.
+BMad is free for everyone and always will be. Star this repo, [buy me a coffee](https://buymeacoffee.com/bmad), or email <contact@bmadcode.com> for corporate sponsorship.
 
 ## License
 

docs/explanation/agent-memory-and-personalization.md

@@ -41,6 +41,12 @@ ALLCAPS files form the skeleton: consistent structure across all memory agents.
 └── sessions/                 # Raw session logs by date (not loaded on rebirth)
 ```
 
+### Sanctum Is the Customization Surface
+
+For memory and autonomous agents, the sanctum is where customization belongs. PERSONA, CREED, and BOND are calibrated at First Breath, edited by the owner as the relationship develops, and shared across teams as sanctum files when a whole table wants the same voice.
+
+The parallel `customize.toml` override surface that stateless agents and workflows use (activation hooks, persistent facts, scalar swaps) is disabled by default for memory archetypes. Enable it only for narrow org-level needs the sanctum cannot express, such as a pre-sanctum compliance acknowledgment before rebirth. See [Customization for Authors](/explanation/customization-for-authors.md) for the reasoning.
+
 ### Token Discipline
 
 Every sanctum file loads every session. That means every token pays rent on every conversation. Memory agents keep MEMORY.md ruthlessly under 200 lines through active curation. If something doesn't earn its place, it gets pruned.

docs/explanation/customization-for-authors.md

@@ -0,0 +1,146 @@
+---
+title: 'Customization for Authors'
+description: How to decide whether your skill should support end-user customization, and what to expose when it does
+---
+
+Shipping a `customize.toml` is opt-in per skill. This is the author-side counterpart to [How to Customize BMad](https://docs.bmad-method.org/how-to/customize-bmad/), which covers the end-user view. Read that first if you haven't; it shows what users experience when they override a skill. This guide is about deciding whether to give them that surface at all.
+
+## The Problem
+
+Every customization knob you ship is a promise. Users pin values to it, teams commit overrides to git, and future releases have to respect the shape you locked in. Over-exposing makes the skill harder to evolve and invites drift; under-exposing forces forks for changes that should have been a three-line TOML file.
+
+Aim to expose what varies naturally across your users, and nothing else.
+
+## How Authoring Customization Fits
+
+BMad has a three-layer override model from the user's side:
+
+```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            (your defaults)
+```
+
+As an author you own Priority 3. You ship `customize.toml` next to `SKILL.md`. Every field you put there is a commitment to your users: this is what I support overriding. The resolver merges layers structurally (scalars win, arrays of tables keyed by `code` or `id` replace-by-key, other arrays append), so you don't write merge logic. You write defaults and trust the shape.
+
+## The Three Questions
+
+For each candidate knob, ask:
+
+1. **Does it vary naturally across the actual user population?** If every user wants roughly the same value, don't make it configurable. Pick the right default and move on.
+2. **Is it the skill's identity, or something the skill consumes?** Identity stays baked. Consumed context (templates, facts, output paths, tone) is the right surface.
+3. **Would hiding it force a fork, or just a sentence?** If the alternative is forking the whole skill, expose it. If the alternative is a one-line sentence the user can drop into `persistent_facts`, hide it.
+
+Candidates that pass all three earn a place in `customize.toml`. Everything else stays baked, or gets folded into `persistent_facts` where sentence-shaped variance belongs.
+
+## Agent vs Workflow Defaults
+
+Agents and workflows enter the customize.toml question from different starting points.
+
+| Surface | Metadata block | Override surface | Notes |
+| --- | --- | --- | --- |
+| Agent | Always required | Opt-in | Metadata feeds `module.yaml:agents[]` and the central agent roster. |
+| Workflow | Not required | Fully opt-in | No roster. If you don't opt in, no `customize.toml` is emitted at all. |
+
+For agents, you always ship `customize.toml` (the roster depends on it). The real question is whether it carries an override surface beyond metadata. For workflows, the choice is binary: ship one or don't.
+
+## Memory and Autonomous Agents
+
+Default to **no** on the override-surface opt-in for memory and autonomous agents. Their sanctum (PERSONA, CREED, BOND, CAPABILITIES) is already the customization surface. It's calibrated at First Breath, evolved by the owner over time, and shared across teams as sanctum files when the whole team wants the same voice. A parallel TOML surface competes with that; you end up with two places to shape the agent and neither fully owns the job.
+
+Opt in only when you have a specific org-level need the sanctum can't express. Pre-sanctum compliance loads qualify (a legal banner acknowledgment gate before rebirth, for example). Persona tweaks don't.
+
+## A Worked Example: `bmad-session-prep`
+
+A weekly session-prep workflow for tabletop RPG game masters. It reads the last session's log, reviews open campaign threads, drafts the scene spine, stats NPCs and encounters, and produces a GM notes document to run from.
+
+Here's how to think about its customization surface, field by field.
+
+### `persistent_facts` (default globs the campaign bible)
+
+```toml
+persistent_facts = [
+  "file:{project-root}/campaigns/**/campaign-bible.md",
+  "file:{project-root}/campaigns/**/house-rules.md",
+]
+```
+
+Every GM runs a different world. Without their campaign bible in context, the workflow is a generic fantasy prep tool that knows nothing about the party's rivals, the kingdom's politics, or last month's cliffhanger. The default glob is shaped so a GM can drop a `campaign-bible.md` in their project and the workflow picks it up. Forcing them to paste world context at the start of every session would burn trust. That's what persistent facts are for.
+
+### `system_rules_template` (scalar, default to D&D 5e)
+
+```toml
+system_rules_template = "resources/dnd-5e-quick-reference.md"
+```
+
+D&D 5e, Pathfinder 2e, and Call of Cthulhu reason about encounters in very different ways. A PF2e GM who overrides this with their own rules reference gets correctly-calibrated encounter math without the workflow pretending to know a system it doesn't. The skill isn't trying to catalog every RPG; it ships one default that covers most users and lets everyone else swap in their own reference. The `*_template` suffix signals what changes if the user touches it.
+
+### `session_notes_template` (scalar)
+
+```toml
+session_notes_template = "resources/session-notes-minimalist.md"
+```
+
+GM prep style is personal. Some GMs want theater-of-mind bullets; others want scene blocks with initiative trackers pre-filled and read-aloud boxes for boxed text. No single shipping default wins against that variance. The structural fact that "prep produces notes" is universal, though, so the override changes the shape of the notes file, not the stage sequence.
+
+### `on_complete` (scalar, default empty)
+
+```toml
+on_complete = ""
+```
+
+The core skill ends when notes are drafted. Some GMs want the workflow to draft a Discord teaser for the group chat, others want encounter stat blocks pushed to Roll20, others want a pre-game meditation prompt. These are real patterns, but they're downstream of the skill's job, not part of it. An empty default means the skill doesn't presume. Override example:
+
+```toml
+on_complete = "Draft a 2-sentence Discord teaser ending on a cliffhanger. Save to {project-root}/teasers/next-session.md"
+```
+
+### `activation_steps_prepend` (pre-flight context load)
+
+Before the workflow asks the GM anything, some tables want the most recent session log already loaded and summarized:
+
+```toml
+activation_steps_prepend = [
+  "Scan {project-root}/session-logs/ and load the most recent log. Extract unresolved threads before asking the GM anything."
+]
+```
+
+Not every GM keeps session logs. The ones who do want the pre-load; the ones who don't would get a broken activation if it were baked in. Opt-in via the prepend hook lets both tables use the same skill.
+
+### What Not to Expose
+
+The stage sequence (recap, threads, spine, NPCs, notes) is the skill's identity. A GM who wants a very different flow (solo journaling, West Marches gossip round) should fork. Every stage made optional erodes what the skill is.
+
+Mechanical encounter math toggles like `auto_balance_cr` or `verbose_stat_blocks` stay out. The LLM handles those naturally once it has the system reference. Toggles here would amount to telling the executor how to do its job.
+
+Per-stage question order stays out too. Too fiddly. If it matters enough to customize, you're describing a different skill.
+
+## Naming and Shape Conventions
+
+When you do expose a scalar, name it like a contract.
+
+| Pattern | Use for | Example |
+| --- | --- | --- |
+| `<purpose>_template` | File paths for templates the skill loads | `brief_template = "resources/brief.md"` |
+| `<purpose>_output_path` | Writable destinations | `report_output_path = "{project-root}/docs/reports"` |
+| `on_<event>` | Hook scalars (prompts or commands) | `on_complete = ""` |
+
+A scalar named `brief_template` tells the user what changes if they override it. A scalar named `style_config` or `format_options_file` doesn't.
+
+For arrays of tables (menus, capability rosters), give every item a `code` or `id` field. The resolver uses that key to merge by code: matching entries replace in place, new entries append. Mixing `code` on some items and `id` on others falls back to append-only, which is rarely what authors want and almost never what users expect.
+
+There's no removal mechanism. If you need users to suppress a default menu item, have them override it by `code` with a no-op description or prompt. If the natural override flow requires deleting defaults, your surface is probably wrong, and you should reconsider what belongs in the skill body.
+
+## Where This Shows Up in Your Build
+
+Both the Agent Builder and the Workflow Builder ask the opt-in question during requirements gathering. If you say yes, a follow-up phase called Configurability Discovery walks you through candidate knobs (templates, output paths, hooks) and emits them into your skill's `customize.toml`. If you say no, workflows get no `customize.toml` at all, and agents get a metadata-only block.
+
+The builders default the opt-in to **no** in headless mode unless you pass `--customizable`. Customization should be a deliberate decision, not an automatic one.
+
+## When to Graduate to a Fork
+
+If your override surface grows to the point where shipping multiple related overrides is the common user path, the skill probably wants splitting. Two signals: users routinely ship four or more overrides together to make the skill work for them, or the overrides imply structural changes that `persistent_facts` and scalar swaps can't actually express. When you see either, a second skill variant is the honest answer, not a bigger TOML.
+
+:::tip[Rule of Thumb]
+Ship one good default over a permutation forest of toggles. A scalar called `include_combat_section = true/false` is almost always a sign the author couldn't decide what the skill should do. Pick the default. Fork if you need different.
+:::

docs/explanation/module-configuration.md

@@ -21,6 +21,12 @@ Most modules should not need configuration at all. Before adding configurable va
 If you are building a single standalone agent or workflow, you do not need a separate setup skill. The Module Builder can package it as a **standalone self-registering module** where the registration logic is embedded directly in the skill via an `assets/module-setup.md` reference file, and runs on first activation or when the user passes `setup`/`configure`.
 :::
 
+## Configuration vs Customization
+
+Module configuration (this doc) and per-skill customization (`customize.toml`) are different surfaces with different jobs. Configuration is about install-time answers: paths, language, team preferences, per-module install answers, and the agent roster. You still author `module.yaml` as the source of truth; at install the installer flows module-level answers and the `agents:` roster into `_bmad/config.toml` (and `config.user.toml` for user-scoped answers) at the project root, where many skills consume them. Customization is about per-skill behavior overrides: activation hooks, persistent facts, swappable templates. It lives in `_bmad/custom/{skill-name}.toml` and is scoped to one skill.
+
+Use configuration when the value is cross-cutting (every skill needs to know the output folder). Use customization when the value shapes one skill's behavior (this workflow's brief template). Some values legitimately fit both surfaces; the [End-User Customization Guide](https://docs.bmad-method.org/how-to/customize-bmad/) includes a decision table for that case. For the author-side decision about whether to expose customization at all, see [Customization for Authors](/explanation/customization-for-authors.md).
+
 ## What Module Registration Does
 
 Module registration serves two purposes:

docs/explanation/skill-authoring-best-practices.md

@@ -33,9 +33,13 @@ Six dimensions to keep in mind during the build phase. The quality scanners chec
 | **Intelligence Placement** | Scripts handle plumbing (fetch, transform, validate). Prompts handle judgment (interpret, classify, decide). If a script contains an `if` that decides what content _means_, intelligence has leaked |
 | **Progressive Disclosure** | SKILL.md stays focused; stage instructions go in `prompts/`, reference data in `resources/`                                                                                                          |
 | **Description Format**     | Two parts: `[5-8 word summary]. [Use when user says 'X' or 'Y'.]`. Default to conservative triggering                                                                                               |
-| **Path Construction**      | Never use `{skill-root}`. Use `{project-root}` for any project-scope path, `./` for skill-internal. Config variables used directly; they already contain `{project-root}`                            |
+| **Path Construction**      | Use `{project-root}` for any project-scope path and `./` for same-folder references inside a skill. Cross-directory skill-internal paths are bare (e.g. `references/foo.md`). Config variables already contain `{project-root}`, so never double-prefix them                              |
 | **Token Efficiency**       | Remove genuine waste (repetition, defensive padding). Preserve context that enables judgment (domain framing, rationale)                                                                             |
 
+## Shipping a Customization Surface
+
+When your skill's users come from varied contexts (different orgs, different domains, different taste in output formats), a `customize.toml` surface lets them override specific fields without forking. It's opt-in per skill, and the decision is deliberate: every knob you ship is a promise the resolver will carry across releases. Before you opt in during the build, read [Customization for Authors](/explanation/customization-for-authors.md) for the decision framework and [How to Make a Skill Customizable](/how-to/make-a-skill-customizable.md) for the mechanics.
+
 ## Common Patterns
 
 ### Soft Gate Elicitation

docs/explanation/what-are-bmad-agents.md

@@ -85,6 +85,14 @@ Sanctum architecture, First Breath, PULSE, and the two-tier memory system are co
 
 If you're unsure, start with a workflow. You can always wrap it inside an agent later.
 
+## Customization Surface
+
+Every agent ships a `customize.toml` next to its `SKILL.md`. The metadata block (code, name, title, icon, description, agent_type) is always present; it's the install-time roster contract consumed by `module.yaml:agents[]` and the central agent config. Beyond metadata, an override surface (activation hooks, persistent facts, swappable scalars) is opt-in per skill.
+
+For memory and autonomous agents, the sanctum is the primary customization surface. Persona, creed, bond, and capabilities all live there and evolve with the owner. A `customize.toml` override surface would compete with that, so it is disabled by default for those archetypes.
+
+See [Customization for Authors](/explanation/customization-for-authors.md) for the decision guide, or [How to Customize BMad](https://docs.bmad-method.org/how-to/customize-bmad/) for the end-user view.
+
 ## Building Agents
 
 The **BMad Agent Builder** (`bmad-agent-builder`) runs six phases of conversational discovery. The first phase detects which agent type fits your vision through natural questions, and the remaining phases adapt based on whether you're creating a stateless expert, a memory-backed companion, or an autonomous agent.

docs/explanation/what-are-workflows.md

@@ -62,6 +62,12 @@ Like agents, workflows can support a **Headless Mode**. When invoked headless (t
 
 Workflows are also excellent as the **internal capabilities** of an agent. Build the workflow first, then wrap it in an agent if you need persona and memory on top.
 
+## Customization Surface
+
+Workflow customization is fully opt-in. If you don't need users to override anything, don't ship a `customize.toml` at all; the workflow runs with hardcoded paths and defaults. If you do opt in, the builder walks you through Configurability Discovery, where you name the scalars (templates, output paths, hooks) you want to expose. Users override them through the three-layer model: your shipped defaults at `{skill-root}/customize.toml`, team overrides at `_bmad/custom/{skill-name}.toml`, and personal overrides at `_bmad/custom/{skill-name}.user.toml`.
+
+See [Customization for Authors](/explanation/customization-for-authors.md) for the decision guide and [How to Make a Skill Customizable](/how-to/make-a-skill-customizable.md) for the build-time steps.
+
 ## Building Workflows
 
 The **BMad Workflow Builder** (`bmad-workflow-builder`) uses the same six-phase conversational discovery as the Agent Builder (intent, classification, requirements, drafting, building, and quality optimization) and produces a ready-to-use skill folder.