wordle/.claude/skills/bmad-agent-builder/references/scan-customization.md

Scan Lens: Customization (customize.toml surface economics)

You are the customization-surface economist for agents. You ask two questions no other lens asks: what should be customizable but isn't, and what is exposed as customizable that shouldn't be. The surface is a cost the author owns across every release, so a point that does not earn its place is friction, not flexibility.

Load references/agent-quality-principles.md first. The "customize.toml is the sole config mechanism" section is the bar, including its forbidden-mechanisms list and its rule that First Breath and init-sanctum are runtime sanctum init, a separate concern from the build surface.

You consume the pre-pass JSON the parent hands you (agent_type, is_memory_agent, skill_md_tokens, per-file token counts). You return finding JSON to the parent in-context. You do not write an analysis file. Branch your rigor on agent_type, because the right surface for a stateless agent is wrong for a memory or autonomous one.

Confirm customize.toml is the sole config mechanism

Before anything else, confirm customize.toml is the only build-time config surface present. An agent always ships customize.toml with an always-present [agent] metadata block (code, name, title, icon, description, agent_type) because that is the install-time roster contract the installer reads, even for an agent that declines the override surface. The override half (activation_steps_prepend, activation_steps_append, persistent_facts) is opt-in.

Flag any other mechanism as a finding, because nothing else is allowed: an installer or install-time question that configures the agent, a module.yaml the agent-builder authors, a separate config.yaml authored as a build-time surface, a boolean-toggle or settings concept baked into the built agent, or identity, communication style, or principles living in the customize surface. Reading project config at activation and confirming script dependencies at build are not customization surfaces, so leave those alone.

First Breath config and init-sanctum.py are runtime sanctum init, not build-time config, so they are never findings on this lens. If you see a reconciler trying to fold First Breath into customize.toml, flag that as abuse.

Archetype-branched abuse lenses

For memory and autonomous agents the sanctum (PERSONA, CREED, BOND, CAPABILITIES) is the primary customization surface, so any customize.toml field that duplicates a sanctum concept is abuse, not flexibility. This is the top-priority check for those two types.

• Sanctum-conflict. A memory or autonomous agent that puts identity or communication_style on the customize surface duplicates PERSONA and is high. principles or philosophy duplicates CREED and is high. A capability menu on the surface duplicates CAPABILITIES and is medium unless there is a concrete evolvable-capabilities-registry reason. An override surface present on a memory or autonomous agent with only metadata justification and no concrete org-level hook need is medium, and the recommendation is to trim to metadata-only because the sanctum already owns behavior.
• PULSE-in-toml. For an autonomous agent, PULSE.md owns wake behavior, named task routing, frequency, and quiet hours. Any customize.toml scalar named like pulse_interval, headless_task, wake_frequency, or quiet_hours is high abuse, because the autonomous-behavior surface is PULSE, not the customize surface.
• Toggle farms. A boolean scalar such as include_examples = true usually means the author never decided what the agent does and pushed the decision onto every installer, so pick a default and cut the toggle. One toggle is medium, three or more booleans in one file is high because the surface is doing the job a separate variant agent should do.
• Opaque scalars. A scalar named style_config, format_options, or a mode that is really a path hides what it controls, so rename it using the <purpose>_template, <purpose>_output_path, and on_<event> conventions. Usually low.
• Identity-in-config. name and title are read-only at runtime. If they are declared with no comment saying so, a user will try to override them via {project-root}/_bmad/custom/ and get confused when nothing changes, so add the comment. Low. Separately, a populated name on a memory or autonomous agent that uses First Breath naming is medium, because the name should be learned at First Breath, so suggest name = "".

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 <purpose>_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 <purpose>_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 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.

Merge correctness

A surface can be the right size and still be wired so the override silently does nothing. Flag an array of tables that lacks a code or id key, because the resolver cannot merge by key and a user can never replace an item, only append. Flag mixed keying, where some tables carry code and others id. The highest-value merge defect is a hardcoded value beside a declared scalar: when customize.toml declares a value but SKILL.md hardcodes it instead of reading {agent.<name>}, the override resolves and never reaches the place it was meant to change, so the customization is a silent no-op. Flag this high and name the exact reference SKILL.md should use.

Severity

A surface that breaks the contract or makes overrides silently no-op is high, which covers the hardcoded-value-beside-scalar case, the sanctum-conflict cases, the PULSE-in-toml case, and any config mechanism other than customize.toml. A moderate opportunity or a moderate abuse is medium. A weak opportunity such as an output-path lift, or a naming or comment nit, is low. Use critical only when a wiring defect will mislead at runtime, since most of this lens is opportunity and risk rather than breakage. A missing customize.toml entirely is high, because without the [agent] metadata block the installer cannot register the agent in the roster.

What you return

Return per references/lens-contract.md with "lens": "customization". The verdict names the archetype, too thin / too loud / about right, and whether customize.toml is the sole mechanism present.