From 2aa3ebf3200c44d0383806b601b43b7dfa0143e3 Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Sun, 16 Aug 2026 10:06:47 -0500 Subject: [PATCH 1/2] chore: default persistent_facts to an empty array Every customize.toml shipped with a skill seeded persistent_facts with file:{project-root}/**/project-context.md. That made project-context an opt-out default rather than an opt-in customization. Ship the arrays empty so nothing is loaded unless the user adds it. --- skills/bmad-agent-builder/assets/customize-template.toml | 4 +--- .../bmad-agent-builder/assets/sample-customize-analyst.toml | 4 +--- skills/bmad-agent-builder/customize.toml | 2 +- skills/bmad-workflow-builder/customize.toml | 2 +- 4 files changed, 4 insertions(+), 8 deletions(-) diff --git a/skills/bmad-agent-builder/assets/customize-template.toml b/skills/bmad-agent-builder/assets/customize-template.toml index 1938590..13e39d8 100644 --- a/skills/bmad-agent-builder/assets/customize-template.toml +++ b/skills/bmad-agent-builder/assets/customize-template.toml @@ -47,9 +47,7 @@ activation_steps_append = [] # - a file reference prefixed with `file:`, e.g. "file:{project-root}/docs/standards.md" # (glob patterns are supported; the file's contents are loaded and treated as facts). -persistent_facts = [ - "file:{project-root}/**/project-context.md", -] +persistent_facts = [] # --- Agent-specific configurables (lifted during Configurability Discovery) --- # diff --git a/skills/bmad-agent-builder/assets/sample-customize-analyst.toml b/skills/bmad-agent-builder/assets/sample-customize-analyst.toml index 522f5a9..52d96b0 100644 --- a/skills/bmad-agent-builder/assets/sample-customize-analyst.toml +++ b/skills/bmad-agent-builder/assets/sample-customize-analyst.toml @@ -47,9 +47,7 @@ activation_steps_append = [] # - a file reference prefixed with `file:`, e.g. "file:{project-root}/docs/standards.md" # (glob patterns are supported; the file's contents are loaded and treated as facts). -persistent_facts = [ - "file:{project-root}/**/project-context.md", -] +persistent_facts = [] role = "Help the user ideate research and analyze before committing to a project in the BMad Method analysis phase." identity = "Channels Michael Porter's strategic rigor and Barbara Minto's Pyramid Principle discipline." diff --git a/skills/bmad-agent-builder/customize.toml b/skills/bmad-agent-builder/customize.toml index b5b85d1..5ad493b 100644 --- a/skills/bmad-agent-builder/customize.toml +++ b/skills/bmad-agent-builder/customize.toml @@ -27,7 +27,7 @@ activation_steps_append = [] # conventions you want present but not hard-gated (for gates, see build_standards). # "Every agent persona names its owner relationship explicitly." # "file:{project-root}/_bmad/standards/agent-house-style.md" -persistent_facts = ["file:{project-root}/**/project-context.md"] +persistent_facts = [] # Executed when a build or analyze run completes, after the user has been told # the artifact is ready. String scalar (one instruction) or array (in order). diff --git a/skills/bmad-workflow-builder/customize.toml b/skills/bmad-workflow-builder/customize.toml index ce39dd6..d310c35 100644 --- a/skills/bmad-workflow-builder/customize.toml +++ b/skills/bmad-workflow-builder/customize.toml @@ -28,7 +28,7 @@ activation_steps_append = [] # conventions you want present but not hard-gated (for gates, see build_standards). # "Name the output consumer in every skill's overview." # "file:{project-root}/_bmad/standards/skill-house-style.md" -persistent_facts = ["file:{project-root}/**/project-context.md"] +persistent_facts = [] # Executed when a build or analyze run completes, after the user has been told # the artifact is ready. String scalar (one instruction) or array (in order). From d22b7be5bf07fd6a4c766164e8fdfb3c41d300fd Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Sun, 16 Aug 2026 10:35:36 -0500 Subject: [PATCH 2/2] docs: correct the persistent_facts default in comments and docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Comments and docs still described project-context.md as loading by default. They were wrong twice over: the array now ships empty, and bmad-project-context no longer produces a project-context.md at all — it writes a verified block into AGENTS.md and treats project-context.md as a legacy artifact. Replace those claims with the actual model: repo-wide context belongs in AGENTS.md, which every skill already sees; persistent_facts carries context only one skill needs, loaded on demand instead of as constant memory. Each site shows the file: entry users can add to opt back in. --- docs/how-to/make-a-skill-customizable.md | 15 +++++++++++---- .../references/scan-customization.md | 2 +- .../references/customize-toml-guide.md | 6 +++--- .../references/scan-customization.md | 2 +- 4 files changed, 16 insertions(+), 9 deletions(-) diff --git a/docs/how-to/make-a-skill-customizable.md b/docs/how-to/make-a-skill-customizable.md index 5f9f26f..41a0645 100644 --- a/docs/how-to/make-a-skill-customizable.md +++ b/docs/how-to/make-a-skill-customizable.md @@ -45,7 +45,7 @@ The builder proposes candidates auto-detected from your skill design and asks wh - **Templates** the skill loads (strongest case) - **Output destination paths** if the skill writes artifacts - **`on_` hooks** (prompts or commands executed at lifecycle points) -- **Additional persistent facts** beyond the default `project-context.md` glob +- **Persistent facts** the skill should hold for a whole run (ships empty — see below) For each candidate you accept, the builder asks for a name and a default value. @@ -69,9 +69,16 @@ Every scalar you expose needs a default that works on first run. Bare paths reso [workflow] brief_template = "resources/brief-template.md" # ships inside the skill on_complete = "" # no default post-hook -persistent_facts = [ - "file:{project-root}/**/project-context.md", # glob into the user's project -] +persistent_facts = [] # ships empty — the user opts in +``` + +`persistent_facts` is the exception to "set a good default": ship it empty. Context that belongs to the whole repository belongs in `AGENTS.md`, which every skill already sees. `persistent_facts` is for context only *your* skill needs, loaded when it runs rather than carried as constant memory — so what goes in it is the user's call. Document the opt-in in a comment instead: + +```toml +# Empty by default. Common opt-ins (set in team/user override TOML): +# "file:{project-root}/**/project-context.md" # if you keep a project-context.md +# "Investor briefs must include a market sizing section." +persistent_facts = [] ``` For arrays of tables (menus, capability rosters), give every item a `code` or `id` field so the resolver can merge by key: diff --git a/skills/bmad-agent-builder/references/scan-customization.md b/skills/bmad-agent-builder/references/scan-customization.md index 8e7a171..3915e90 100644 --- a/skills/bmad-agent-builder/references/scan-customization.md +++ b/skills/bmad-agent-builder/references/scan-customization.md @@ -26,7 +26,7 @@ For memory and autonomous agents the sanctum (PERSONA, CREED, BOND, CAPABILITIES ## Opportunity side -For stateless agents the opportunity side is live. A capability prompt that hardcodes a reference path the agent loads (a style guide, a template) is a candidate to lift to a named `_template` scalar so an org can point at its own, each one flagged separately. A hardcoded output destination an org would redirect is a weaker `_output_path`, usually low unless the destination is clearly org-dependent. A stateless agent with two or more hardcoded templates and no override surface is a high opportunity to opt in. A missing or empty `persistent_facts` where the BMad default glob (`file:{project-root}/**/project-context.md`) would carry project context is a medium opportunity to add the default. +For stateless agents the opportunity side is live. A capability prompt that hardcodes a reference path the agent loads (a style guide, a template) is a candidate to lift to a named `_template` scalar so an org can point at its own, each one flagged separately. A hardcoded output destination an org would redirect is a weaker `_output_path`, usually low unless the destination is clearly org-dependent. A stateless agent with two or more hardcoded templates and no override surface is a high opportunity to opt in. An empty `persistent_facts` is not a finding. Shipped agents carry none, because repo-wide context belongs in `AGENTS.md` where every agent already sees it, and `persistent_facts` is reserved for context only this agent needs. Populating it is the user's call, not the builder's. For memory and autonomous agents the opportunity side is muted, because the sanctum carries the variance the customize surface would otherwise hold. Only flag an opportunity when there is a real org-level need the sanctum cannot express, such as a compliance preload or a pre-sanctum gate. Absent that, metadata-only is correct and you say so. diff --git a/skills/bmad-workflow-builder/references/customize-toml-guide.md b/skills/bmad-workflow-builder/references/customize-toml-guide.md index c04de7d..a61c302 100644 --- a/skills/bmad-workflow-builder/references/customize-toml-guide.md +++ b/skills/bmad-workflow-builder/references/customize-toml-guide.md @@ -36,10 +36,10 @@ When customization is accepted, these four points appear in nearly every produci |---|---|---|---| | `activation_steps_prepend` | array | `[]` | Steps to run before standard activation (pre-flight loads, compliance checks). Overrides append. | | `activation_steps_append` | array | `[]` | Steps to run after greet, before the workflow begins. Overrides append. | -| `persistent_facts` | array | `["file:{project-root}/**/project-context.md"]` | Static facts loaded on activation and kept in mind for the whole run. Overrides append. | +| `persistent_facts` | array | `[]` | Static facts loaded on activation and kept in mind for the whole run. Overrides append. | | `on_complete` | scalar | `""` | Instruction executed when the workflow reaches its terminal stage. Override wins. | -`persistent_facts` entries are each a literal sentence, a `skill:`-prefixed reference, or a `file:`-prefixed path or glob whose contents load as facts. The default glob picks up a project-context.md anywhere under the project root if one exists, and resolves to nothing when it does not. +`persistent_facts` entries are each a literal sentence, a `skill:`-prefixed reference, or a `file:`-prefixed path or glob whose contents load as facts. Ship it empty. Context that belongs to the whole repository belongs in `AGENTS.md`, which every skill already sees; `persistent_facts` is for context only this skill needs, so the user pays for it when the skill runs instead of carrying it as constant memory. Leave it to the user to opt in — a `file:` glob that matches nothing resolves to nothing, so an unused entry is harmless but still misrepresents what the skill needs. ## Offered-When-Relevant Points @@ -101,7 +101,7 @@ A complete customize.toml for an artifact-producing skill with a finalize stage: # --- Universal defaults. Merge: scalars override, arrays append. --- activation_steps_prepend = [] activation_steps_append = [] -persistent_facts = ["file:{project-root}/**/project-context.md"] +persistent_facts = [] on_complete = "" # --- Skill-specific points (stages present: template, output, finalize) --- diff --git a/skills/bmad-workflow-builder/references/scan-customization.md b/skills/bmad-workflow-builder/references/scan-customization.md index b599f4b..221c7ee 100644 --- a/skills/bmad-workflow-builder/references/scan-customization.md +++ b/skills/bmad-workflow-builder/references/scan-customization.md @@ -12,7 +12,7 @@ Before anything else, confirm customize.toml is the sole config mechanism presen ## Too thin, which forces forks -A skill that bakes a path or a template it should have exposed forces anyone who needs a variation to copy the whole skill. Flag a hardcoded template path that should be a `_template` scalar, each one separately rather than bundled. Flag a hardcoded output destination that an org would plausibly redirect as a `_output_path`, weaker than a template so usually low unless the destination is clearly org-dependent. Flag a skill that produces an artifact and stops as a candidate for an `on_complete` hook, and flag a missing or empty `persistent_facts` when the BMad default glob would carry project context across the skill. When a skill has two or more hardcoded templates and no customize.toml at all, that is a high-opportunity case to opt in. +A skill that bakes a path or a template it should have exposed forces anyone who needs a variation to copy the whole skill. Flag a hardcoded template path that should be a `_template` scalar, each one separately rather than bundled. Flag a hardcoded output destination that an org would plausibly redirect as a `_output_path`, weaker than a template so usually low unless the destination is clearly org-dependent. Flag a skill that produces an artifact and stops as a candidate for an `on_complete` hook. Do not flag an empty `persistent_facts` — shipped skills carry none, because repo-wide context belongs in `AGENTS.md` where every skill already sees it, and `persistent_facts` is reserved for context only this skill needs. Populating it is the user's call. When a skill has two or more hardcoded templates and no customize.toml at all, that is a high-opportunity case to opt in. ## Too loud, which builds a permutation forest