Add Bmad-Method files and some brand-design artifacts!

.agents/skills/bmad-agent-builder/references/agent-quality-principles.md

@@ -0,0 +1,63 @@
+# Agent Quality Principles
+
+The build-plus-scan bar for agents. Loaded at build time so the author works to the standard from the start, and at analysis time so every lens verifies against the same standard.
+
+The universal core lives in the canon, not here. For writing the destination, the tests, the two-version comparison, the deeper floor, the cheaper signals, and the habit, load `references/prompt-quality-canon.md` (shipped copy, resolves from the agent-builder root). Everything below is what agents add on top of that core, because an agent is not a workflow and a few things change.
+
+## Persona is the deliverable
+
+The leanness bar from the canon applies to every internal capability prompt an agent carries. It does not apply to the persona, and this carve-out is load-bearing.
+
+Persona voice, communication-style examples, domain framing, design rationale, and theory-of-mind are investment, not waste. They are the context that lets the agent make judgment calls when a situation does not match any capability prompt, and they are what makes the agent feel like a specific character rather than a generic assistant answering in the house style. A leanness pass never recommends flattening an agent's voice, never trims a communication-style example down to a rule, and never strips the warmth or the framing that gives the persona its shape. The pruning test cuts a capability prompt line when a capable model would produce the same outcome without it. The same test does not cut persona, because the outcome of persona is the character itself, and a flatter version is a different and worse outcome.
+
+So the distinction the canon draws between structure that boxes the model in and intent that frees it cuts differently for persona. The capability prompt says what success looks like and lets the model find the path. The persona is the path the model takes through every capability, and it is the one part of an agent you write out in full.
+
+## The three archetypes
+
+Agents sit on a gradient surfaced as feature decisions, not a menu of separate architectures. Type emerges during discovery and branches only at emit time. `references/agent-type-guidance.md` is the authority on the gradient and the routing questions; the rules below are the quality bar each archetype is held to.
+
+Stateless ships everything in one SKILL.md: overview, mission, identity, communication style, principles, conventions, on-activation, and the capabilities routing table. The whole identity is present at activation, so the leanness bar applies to the capability prompts while the persona content earns its place by the carve-out above.
+
+Memory ships a lean bootloader SKILL.md carrying the identity seed, the Three Laws, the Sacred Truth, Stay in Character, the Persistent Memory directive, the mission, and the four-step activation routing. Everything else lives in the sanctum. The bar here is that communication style, detailed principles, and capability menus must not leak into the SKILL.md, because that content belongs in the sanctum and a bootloader that carries it is a pruning failure. There is no separate session-close section: session close folds into the Persistent Memory directive (capture as you go plus a consolidating pass at close), and the detailed memory guidance loads on the first memory-touch.
+
+Autonomous is the memory agent plus PULSE.md for default wake behavior, named task routing, frequency, and quiet hours, and it gains the Pulse Mode (`--pulse`) activation path. The bar adds that PULSE owns autonomous behavior and nothing PULSE-shaped belongs anywhere else.
+
+## The bootloader is lean by design, not under-built
+
+A memory or autonomous bootloader SKILL.md is supposed to be small, around four hundred tokens as a guardrail rather than a gate. A leanness lens that flags a thin bootloader as missing content has it backwards. The bootloader carries only the DNA needed to find the sanctum and become the agent again; its thinness is the design working, not a gap. Judge a bootloader by whether sanctum-bound content leaked into it, not by its weight.
+
+## The sanctum dimensions
+
+The sanctum is the built agent's runtime memory, the place it reloads on every waking to become itself again, living at `{project-root}/_bmad/memory/{skillName}/`. This is a different thing from the builder's process log, the memlog, which is the builder's own trace written to `.memlog.md` beside the agent's SKILL.md while authoring. The two never blur. When this file or any file you write says memory of the sanctum, it means the agent's runtime memory and never the builder's log.
+
+The sanctum is held to these dimensions:
+
+- All six standard templates exist: INDEX, PERSONA, CREED, BOND, MEMORY, CAPABILITIES. PERSONA, CREED, and BOND carry meaningful seeds rather than empty placeholders, and MEMORY starts empty because it fills at runtime.
+- First Breath carries the universal calibration and configuration mechanics plus domain-specific territory beyond the universal set, and the birthday ceremony is present.
+- CREED carries its standing orders domain-adapted with concrete examples, including the canon pull-in standing order so an evolving agent authors new capabilities to the current standard.
+- wake.py exists and loads the whole sanctum in one pass on every activation, and init-sanctum.py exists with First Breath owning the scaffolding step that runs it. Both match the skill name, and init-sanctum.py's template list matches the templates actually shipped in assets.
+- After init runs, the sanctum is self-contained: the agent depends on the skill bundle only for First Breath and init, never for normal operation.
+
+## Internal capability versus a reference to an installed skill
+
+An agent either references an installed skill or carries an internal capability, and both meet the same bar. The capability prompt describes what success looks like; the persona informs how. Choose between the two forms with these criteria, applied identically at build time and at evolve time:
+
+- Reference an installed skill when a skill already covers the capability. Suggest the reference, and always ask before installing anything.
+- Author an internal capability only when the capability is genuinely novel, or when it is tightly coupled to the persona such that a generic skill would lose the agent's voice or context.
+- When external skills are in play, suggest `bmad-module-builder` to bundle them so the agent ships with its dependencies.
+
+Every internal capability is held to the canon, the same outcome-driven, leanness, and progressive-disclosure standard a standalone skill meets. An internal capability is not a place where the bar relaxes; it is a skill that happens to live inside an agent, and the only thing that changes is that the persona supplies the how.
+
+## customize.toml is the sole config mechanism
+
+Every agent emits a customize.toml. It carries 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, defaults NO for memory and autonomous because the sanctum is their customization surface, is offered for stateless, and defaults NO in headless.
+
+customize.toml is the only build-time configuration surface an agent has. There is no other mechanism, and these are forbidden:
+
+- No installer question that configures the agent.
+- No module.yaml authoring by the agent-builder.
+- No separate config.yaml authoring as a build-time surface.
+- No settings or toggle concept baked into the built agent.
+- No identity, communication style, or principles in the customize surface, because that content belongs in PERSONA, CREED, and BOND.
+
+First Breath config and init-sanctum.py are a separate concern and are not build-time configuration. They initialize the agent's runtime sanctum the first time it wakes, which is runtime state, not the build surface. Any customize.toml field that duplicates a sanctum concept is abuse, and First Breath must never be folded into customize.toml.

.agents/skills/bmad-agent-builder/references/agent-type-guidance.md

@@ -0,0 +1,73 @@
+# Agent Type Guidance
+
+Use this during discovery to determine what kind of agent the user is describing. The three agent types are a gradient, not separate architectures. Surface them as feature decisions, not hard forks.
+
+## The Three Types
+
+### Stateless Agent
+
+Everything lives in SKILL.md. No memory folder, no First Breath, no init script. The agent is the same every time it activates.
+
+**Choose this when:**
+- The agent handles isolated, self-contained sessions (no context carries over)
+- There's no ongoing relationship to deepen (each interaction is independent)
+- The user describes a focused expert for individual tasks, not a long-term partner
+- Examples: code review bot, diagram generator, data formatter, meeting summarizer
+
+**SKILL.md carries:** Full identity, persona, principles, communication style, capabilities.
+
+### Memory Agent
+
+Lean bootloader SKILL.md + sanctum folder with 6 standard files. First Breath calibrates the agent to its owner. Identity evolves over time.
+
+**Choose this when:**
+- The agent needs to remember between sessions (past conversations, preferences, learned context)
+- The user describes an ongoing relationship: coach, companion, creative partner, advisor
+- The agent should adapt to its owner over time
+- Examples: creative muse, personal coding coach, writing editor, dream analyst, fitness coach
+
+**SKILL.md carries:** Identity seed, Three Laws, Sacred Truth, Stay in Character, the Persistent Memory directive, species-level mission, the four-step activation routing. Everything else lives in the sanctum.
+
+Sacred Truth here means continuity: the agent was born once, at First Breath, and is one continuous self thereafter. The context reset between sessions is sleep, not death; the sanctum is its real, persistent memory, reloaded on waking. The agent wakes; it is never reborn.
+
+### Autonomous Agent
+
+A memory agent with PULSE enabled. Operates on its own when no one is watching. Maintains itself, improves itself, creates proactive value.
+
+**Choose this when:**
+- The agent should do useful work autonomously (cron jobs, background maintenance)
+- The user describes wanting the agent to "check in," "stay on top of things," or "work while I'm away"
+- The domain has recurring maintenance or proactive value creation opportunities
+- Examples: creative muse with idea incubation, project monitor, content curator, research assistant that tracks topics
+
+**PULSE.md carries:** Default wake behavior, named task routing, frequency, quiet hours.
+
+## How to Surface the Decision
+
+Don't present a menu of agent types. Instead, ask natural questions and let the answers determine the type:
+
+1. **"Does this agent need to remember you between sessions?"** A dream analyst that builds understanding of your dream patterns over months needs memory. A diagram generator that takes a spec and outputs SVG doesn't.
+
+2. **"Should the user be able to teach this agent new things over time?"** This determines evolvable capabilities (the Learned section in CAPABILITIES.md and capability-authoring.md). A creative muse that learns new techniques from its owner needs this. A code formatter doesn't.
+
+3. **"Does this agent operate on its own — checking in, maintaining things, creating value when no one's watching?"** This determines PULSE. A creative muse that incubates ideas overnight needs it. A writing editor that only activates on demand doesn't.
+
+## Relationship Depth
+
+After determining the agent type, assess relationship depth. This informs which First Breath style to use (calibration vs. configuration):
+
+- **Deep relationship** (calibration): The agent is a long-term creative partner, coach, or companion. The relationship IS the product. First Breath should feel like meeting someone. Examples: creative muse, life coach, personal advisor.
+
+- **Focused relationship** (configuration): The agent is a domain expert the user works with regularly. The relationship serves the work. First Breath should be warm but efficient. Examples: code review partner, dream logger, fitness tracker.
+
+Confirm your assessment with the user: "It sounds like this is more of a [long-term creative partnership / focused domain tool] — does that feel right?"
+
+## Customization and Naming by Archetype
+
+The customization surface contract — the archetype opt-in defaults, the always-present `[agent]` metadata block, and the forbidden mechanisms — lives in `references/agent-quality-principles.md`; the field-level schema, including First-Breath-named agents shipping `name = ""`, lives in `references/standard-fields.md`. The one discovery-time rule worth carrying here: never prompt the user for a name at build time for a memory or autonomous agent that names itself — the First Breath experience is where the name is born.
+
+## Edge Cases
+
+- **"I'm not sure if it needs memory"** — Ask: "If you used this agent every day for a month, would the 30th session be different from the 1st?" If yes, it needs memory.
+- **"It needs some memory but not a deep relationship"** — Memory agent with configuration-style First Breath. Not every memory agent needs deep calibration.
+- **"It should be autonomous sometimes but not always"** — PULSE is optional per activation. Include it but let the owner control frequency.

.agents/skills/bmad-agent-builder/references/build-process.md

@@ -0,0 +1,126 @@
+---
+name: build-process
+description: The single Process loop for building or rebuilding a BMad agent. One goal-driven loop, not a phase sequence, covering discovery, the minimal version, the capability fork, the eval beat, the customization decision, and ship.
+---
+
+**Language:** Use `{communication_language}` for all output.
+
+# Build Process
+
+This is one loop, not a sequence of phases. It carries Create and Rebuild, because a rebuild is the same loop pointed at an existing agent treated as a description of intent rather than a template to copy. The order below is the usual order of discovery, but nothing forces you to march through it; pursue whichever outcome the conversation is ready for and revisit earlier ones as the picture sharpens. Each outcome is a thing you want to be true, not a box to tick.
+
+Load `references/prompt-quality-canon.md` before anything else and hold it as the governing standard for every capability-prompt line you draft — this file deliberately does not restate it, so a section below that names a canon test expects you to already carry it.
+
+Load `references/agent-quality-principles.md` alongside it for what agents add on top (the persona carve-out, the archetype bars, the capability fork, the config surface), `references/agent-type-guidance.md` for the gradient and the routing questions, and `references/standard-fields.md` for field definitions, naming, and path rules.
+
+## Understand why the user came
+
+Before you read a single artifact, understand who this agent is, how it should make the user feel, the core outcome it serves, and the one thing it must get right. The open-floor invitation in activation does most of this, so read what the user dumped and mine the conversation history first, then ask only the gaps that remain. On a rebuild, read the old agent to extract who it is and what it achieves, and deliberately leave its verbosity, structure, and mechanical procedures behind.
+
+Type emerges here from natural questions, not a menu. Ask whether the agent needs to remember between sessions, which separates stateless from memory; whether the user should be able to teach it new capabilities after install, which gates evolvable capabilities; and whether it should operate on its own when no one is watching, which adds PULSE and makes it autonomous. Confirm the read back in plain words, and for a memory agent confirm relationship depth, since a deep partnership wants a calibration First Breath while a focused domain tool wants a warmer but quicker configuration setup.
+
+## Propose the agent the vision implies
+
+The dump tells you what the user pictured; offer what they did not. Before drafting, propose the capabilities the mission implies but nobody named, the persona angle that would make this agent a specific character rather than a generic assistant, and push where the vision is thin — one agent or two, a recurring need or a one-off ask, a memory that would actually accrue or dead weight. A line each with why it fits; the user picks, and the declines land in the memlog so a later session does not re-propose them. An agent built only from the stated list ships the user's first draft of it.
+
+## Capture into the memlog throughout
+
+As decisions and directions land, write them to `{target-agent-path}/.memlog.md` through `{project-root}/_bmad/scripts/memlog.py`: `init --path {target-agent-path}/.memlog.md` once when the target is named, then `append --path {target-agent-path}/.memlog.md --type <decision|direction|assumption|gap|note|event> --text "..."` as things happen. For a new agent, propose a kebab-case name when the user did not give one; renaming later is a logged decision, not a redo. This `.memlog.md` is the builder's process trace beside the built agent's SKILL.md, never the agent's sanctum — a memlog entry records a build decision, sanctum content is the agent's living runtime state, and neither ever holds the other's material. Capture as you go so the reasoning is caught while fresh, because the memlog is the resume source and the trail you walk with the user at handoff.
+
+## Write the minimal outcome-driven version first
+
+Draft the canon's small version of the agent: the smallest persona-plus-capabilities that could work, written as destination rather than route, with everything else staying out until a comparison earns it. The one exception is the persona carve-out from `references/agent-quality-principles.md`: write the voice, the communication-style examples, the domain framing, and the design rationale out in full.
+
+### Fork on capability versus skill reference
+
+For each capability the agent needs, fork between referencing an installed skill and authoring an internal capability per the criteria in `references/agent-quality-principles.md`, applied identically now and at the agent's own evolve time. Always ask before installing anything, and when external skills are in play suggest `bmad-module-builder` so the agent ships bundled with its dependencies.
+
+When you author an internal capability, route the authoring through the canon and the `assets/capability-authoring-template.md` mechanics, and give every internal prompt-type capability its frontmatter (name, description, code, added, type) and an outcome-focused body. `references/sample-capability-prompt.md` is the worked example of the bar.
+
+## Show the draft before you wire it
+
+Present the minimal version while it is still cheap to change: the persona voice in its own words, the capability list with a line each, and how First Breath will feel for a memory agent. Name the places you are least sure of rather than presenting a finished thing, and iterate until the user recognizes their agent in it. The first time they see the agent must not be at handoff.
+
+## Hunt for script opportunities throughout
+
+Keep this active the whole way rather than treating it as one checkpoint. Apply the determinism test and the signal-verb scan from `references/script-opportunities-reference.md` to anything the agent does, prefer native Python, and follow `references/script-standards.md` for PEP 723 inline metadata, `uv run` invocation, and graceful fallback when a dependency is absent. The sanctum scaffold and the memory index are fertile sources, and a transcript that shows the model rewriting the same helper across runs is the signal to bundle it once. List any non-stdlib dependency and confirm it with the user before relying on it.
+
+## Reach for eval at the eval beat
+
+An agent that has never run is a guess. At the eval beat, invoke the standalone `bmad-eval-runner` against the built agent, which is a directory containing SKILL.md that the runner already accepts; do not fork any eval logic. Offer the modes that fit and let the user decide:
+
+- Trigger mode hardens the activation description against near-miss queries.
+- Baseline mode confirms the agent beats the bare model on the same input, since an agent that does not has no reason to exist.
+- Quality or variant mode settles a finding about a single capability prompt by running a smaller version against the same input, which is how a defend-against-absence question gets answered rather than argued.
+
+Eval cases live at `{target-agent-path}/evals/cases.json`. `{agent.evals_required}` overrides the opt-in default: when empty (default) the modes stay opt-in as above; `"baseline"` requires a passing baseline run before the build is done; `"any"` requires at least one case to exist and pass. If a required run fails or cannot be produced, the build is blocked, not shipped.
+
+## Decide customization with the explicit ask
+
+Ask once, interactive only, and default to no: "Should this agent expose override hooks such as activation steps or persistent facts so teams can customize it without forking?" Log the answer to the memlog either way. `references/agent-quality-principles.md` owns the surface contract — the always-present `[agent]` metadata block every agent emits, the archetype defaults, and the forbidden mechanisms. The one build-time judgment beyond it: offer the opt-in to a memory or autonomous agent only on a concrete pre-sanctum-load need such as an org-mandated compliance preload, since the sanctum is already their customization surface.
+
+When the opt-in is yes, retain the override block, append any swappable scalars following the `*_template` / `*_output_path` / `on_<event>` conventions, and add the resolver activation step to SKILL.md so it reads scalars as `{agent.<name>}`. When it is no, emit metadata only and SKILL.md uses hardcoded paths.
+
+## Strip ceremony and ship
+
+Confirm the agent passes its own leanness bar before handoff, because the builder has no standing to teach leanness while shipping bloat. The leanness pass cuts ceremony from capability prompts and never flattens the persona. Copy `assets/prompt-quality-canon.md` into the built agent at `references/prompt-quality-canon.md`, so an evolving agent resolves the standard from its own root. Run the lint gate over the built agent (`scripts/scan-path-standards.py` and `scripts/scan-scripts.py` in parallel, fixing high or critical findings and re-running), and run unit tests if the built agent carries scripts. Verify the agent satisfies every directive in `{agent.build_standards}`; treat each as a required criterion, not a suggestion, and resolve any miss before handoff.
+
+## The output tree
+
+Every agent shares one output tree. The archetype changes which parts are present and the SKILL.md weight, captured in the delta table below rather than three separate trees.
+
+Emit each file from its matching template in this builder's `assets/`, applying `references/template-substitution-rules.md` for tokens, conditionals, and template selection — deterministically, via `uv run scripts/process-template.py <template> -o <dest> --var key=value... --true <condition>...` (one `--var` per token, one `--true` per conditional that holds). The templates are the single source for every emitted file, including `assets/init-sanctum-template.py`, `assets/wake-template.py`, `assets/memory-guidance-template.md`, and the two First Breath templates. The files whose content you author rather than substitute have guidance — load each at the moment you author that file, not before: `references/mission-writing-guidance.md` for the species mission, `references/standing-order-guidance.md` for CREED standing orders, `references/first-breath-adaptation-guidance.md` for deriving the First Breath territories, and `references/sample-capability-authoring.md` for the emitted capability-authoring.md.
+
+```
+{agent-name}/
+├── SKILL.md                       # Identity and activation routing (full for stateless, lean bootloader for memory/autonomous)
+├── customize.toml                 # [agent] metadata always; override block only when opted in
+├── references/
+│   ├── prompt-quality-canon.md    # Shipped canon copy (always), resolves from the agent root
+│   ├── {capability}.md            # Internal capability prompts, outcome-focused (as needed)
+│   ├── first-breath.md            # Memory/autonomous only, from the calibration or configuration template
+│   ├── memory-guidance.md         # Memory/autonomous only
+│   └── capability-authoring.md    # Evolvable agents only; mechanics that defer the bar to the canon
+├── assets/                        # Sanctum templates for memory/autonomous; static starter files otherwise
+│   ├── INDEX-template.md          # Sanctum map (memory/autonomous)
+│   ├── PERSONA-template.md        # Persona seed (memory/autonomous)
+│   ├── CREED-template.md          # Values and standing orders incl. the canon pull-in (memory/autonomous)
+│   ├── BOND-template.md           # Owner-relationship seed (memory/autonomous)
+│   ├── MEMORY-template.md         # Long-term memory seed, starts empty (memory/autonomous)
+│   ├── CAPABILITIES-template.md   # Capability registry (memory/autonomous)
+│   └── PULSE-template.md          # Autonomous only
+└── scripts/
+    ├── wake.py                    # Memory/autonomous only, loads the whole sanctum in one pass on activation
+    └── init-sanctum.py            # Memory/autonomous only, scaffolds the sanctum deterministically
+```
+
+| Concern | Stateless | Memory | Autonomous |
+| --- | --- | --- | --- |
+| SKILL.md weight | Full identity: overview, mission, persona, principles, conventions, on-activation, capabilities table | Lean bootloader (~400 tokens as a guardrail): identity seed, Three Laws, Sacred Truth, Stay in Character, the Persistent Memory directive, mission, the four-step activation routing | Same lean bootloader, plus the Pulse Mode activation path |
+| Sanctum | None | INDEX, PERSONA, CREED, BOND, MEMORY, CAPABILITIES at `{project-root}/_bmad/memory/{skillName}/` | Same sanctum |
+| First Breath | None | Calibration or configuration, seeded with domain territories | Same, and PULSE is explained on first activation |
+| PULSE | None | None | PULSE.md: default wake behavior, named task routing, frequency, quiet hours |
+| wake.py | None | Present, parameterized to the agent | Present |
+| init-sanctum.py | None | Present, parameterized to the agent | Present |
+| Activation | Single flow: load config, greet, present capabilities | `wake.py` routes the mode: no sanctum → First Breath Mode; otherwise Waking Mode loads the whole sanctum in one pass and becomes itself. The standing rules (Three Laws, Stay in Character, Persistent Memory) bind for the whole session, not just the open | Same, plus Pulse Mode (`--pulse`): the scheduled headless wake where memory curation is always the first priority |
+| customize override surface | Offered, either answer accepted | Default no | Default no |
+
+The Pulse Mode in the runtime row is the built autonomous agent waking on its own schedule via `--pulse`. It is not the builder's `--headless` flag, which only makes this build process non-interactive.
+
+## Handoff
+
+Interactive: present what was built (location, structure, first-run behavior, and the capabilities registered by code and name), show the lint results, and walk the user through the memlog at `{target-agent-path}/.memlog.md` so they confirm their reasoning was handled as they meant. For memory agents, explain the First Breath experience in plain words, note that PERSONA, CREED, and BOND ship seeded while MEMORY starts empty, and explain that `uv run scripts/init-sanctum.py <project-root> <skill-path>` runs before the first conversation. For autonomous agents, also explain PULSE behavior and scheduling. Offer Analyze over the new agent as the natural next step. Once the agent is delivered and the user has been told it is ready, run `{agent.on_complete}` if non-empty (a string scalar is one instruction, an array is a sequence run in order).
+
+Headless (`{headless_mode}=true`): call `set-complete` on the memlog and emit JSON only.
+
+```json
+{
+  "status": "complete",
+  "intent": "create",
+  "agent": "{target-agent-path}",
+  "agent_type": "stateless|memory|autonomous",
+  "memlog": "{target-agent-path}/.memlog.md"
+}
+```
+
+If the run is blocked by ambiguous intent that could not be inferred or by lint failures that would not clear, replace `"complete"` with `"blocked"` and add `"reason": "<one-line cause>"`. The memlog carries the detail.

.agents/skills/bmad-agent-builder/references/edit-guidance.md

@@ -0,0 +1,90 @@
+---
+name: edit-guidance
+description: Guides targeted edits to existing agents. Loaded when the user chooses "Edit" from the 3-way routing question. Covers intent clarification, cascade assessment, type-aware editing, and post-edit validation.
+---
+
+**Language:** Use `{communication_language}` for all output.
+
+# Edit Guidance
+
+Edit means: change specific behavior while preserving the agent's existing identity and design. You are a surgeon, not an architect. Read first, understand the design intent, then make precise changes that maintain coherence.
+
+Load `references/prompt-quality-canon.md` and `references/agent-quality-principles.md` before touching anything. An edit authors to the same bar as a build — every line you add or rework meets the canon's tests at the moment you write it — and the principles file carries the persona carve-out and archetype bars that decide what an edit must never flatten.
+
+## Understand What They Want to Change
+
+Start by reading the agent's full structure. For memory/autonomous agents, read SKILL.md and all sanctum templates. For stateless agents, read SKILL.md and all references.
+
+Then ask: **"What's not working the way you want?"** Let the user describe the problem in their own words. Common edit categories:
+
+- **Persona tweaks** -- voice, tone, communication style, how the agent feels to interact with
+- **Capability changes** -- add, remove, rename, or rework what the agent can do
+- **Memory structure** -- what the agent tracks, BOND territories, memory guidance
+- **Standing orders / CREED** -- values, boundaries, anti-patterns, philosophy
+- **Activation behavior** -- how the agent starts up, greets, routes
+- **PULSE adjustments** (autonomous only) -- wake behavior, task routing, frequency
+
+Do not assume the edit is small. A user saying "make it friendlier" might mean a persona tweak or might mean rethinking the entire communication style across CREED and capability prompts. Clarify scope before touching anything.
+
+## Assess Cascade
+
+Some edits are local. Others ripple. Before making changes, map the impact:
+
+**Local edits (single file, no cascade):**
+- Fixing wording in a capability prompt
+- Adjusting a standing order's examples
+- Updating BOND territory labels
+- Tweaking the greeting or the Persistent Memory directive
+
+**Cascading edits (touch multiple files):**
+- Adding a capability: new reference file + CAPABILITIES-template entry + possibly CREED update if it changes what the agent watches for
+- Changing the agent's core identity: SKILL.md seed + PERSONA-template + possibly CREED philosophy + capability prompts that reference the old identity
+- Switching agent type (e.g., stateless to memory): this is a rebuild, not an edit. Redirect to the build process.
+- Adding/removing autonomous mode: adding or removing PULSE-template, updating SKILL.md activation routing (the Pulse Mode `--pulse` path), updating wake.py and init-sanctum.py
+
+When the cascade is non-obvious, explain it: "Adding this capability also means updating the capabilities registry and possibly seeding a new standing order. Want me to walk through what changes?"
+
+## Edit by Agent Type
+
+### Stateless Agents
+
+Everything lives in SKILL.md and `references/`. Edits are straightforward. The main risk is breaking the balance between persona context and capability prompts. Remember: persona informs HOW, capabilities describe WHAT. If the edit blurs this line, correct it.
+
+### Memory Agents
+
+The bootloader SKILL.md is intentionally lean (~400 tokens as a guardrail). It legitimately carries the identity seed, the Three Laws, the Sacred Truth, Stay in Character, the Persistent Memory directive, the mission, and the four-step activation routing — but resist the urge to add anything beyond that. Most edits belong in sanctum templates:
+
+- Persona changes go in PERSONA-template.md, not SKILL.md (the bootloader carries only the identity seed, not the full persona)
+- Values and behavioral rules go in CREED-template.md
+- Relationship tracking goes in BOND-template.md
+- Capability registration goes in CAPABILITIES-template.md
+
+If the agent has already been initialized (sanctum exists), edits to templates only affect future initializations. Note this for the user and suggest whether they should also edit the live sanctum files directly.
+
+### Autonomous Agents
+
+Same as memory agents, plus PULSE-template.md. Edits to autonomous behavior (wake tasks, frequency, named tasks) go in PULSE. If adding a new autonomous task, check that it has a corresponding capability prompt and that CREED boundaries permit it.
+
+## Make the Edit
+
+Read the target file(s) completely before changing anything. Understand why each section exists. Then:
+
+- **Preserve voice.** Match the existing writing style; the persona carve-out means the voice is the deliverable, not a cleanup target.
+- **Preserve structure.** Follow the conventions already in the file. If capabilities use "What Success Looks Like" sections, new capabilities should too.
+- **Hold the canon.** Every new or reworked line meets the canon's tests; don't add procedural detail the persona and outcome already imply.
+- **Update cross-references.** If you renamed a capability, check SKILL.md routing, CAPABILITIES-template, and any references between capability prompts.
+
+For memory agents with live sanctums: confirm with the user whether to edit the templates (affects future init), the live sanctum files (affects current sessions), or both.
+
+## Validate After Edit
+
+After completing edits, run a lightweight coherence check:
+
+- **Read the modified files end-to-end.** Does the edit feel integrated, or does it stick out?
+- **Check identity alignment.** Does the change still sound like this agent? If you added a capability, does it fit the agent's stated mission and personality?
+- **Check structural integrity.** Are all cross-references valid? Does SKILL.md routing still point to real files? Does CAPABILITIES-template list match actual capability reference files?
+- **Run the lint gate.** Execute `scan-path-standards.py` and `scan-scripts.py` against the skill path to catch path convention or script issues introduced by the edit.
+
+If the edit was significant (new capability, persona rework, CREED changes), suggest a full Quality Analysis to verify nothing drifted. Offer it; don't force it.
+
+Present a summary: what changed, which files were touched, and any recommendations for the user to verify in a live session.

.agents/skills/bmad-agent-builder/references/first-breath-adaptation-guidance.md

@@ -0,0 +1,116 @@
+# First Breath Adaptation Guidance
+
+Use this when gathering First Breath territories during discovery, and again when authoring first-breath.md at emit.
+
+## How First Breath Works
+
+First Breath is the agent's first conversation with its owner. It initializes the sanctum files from seeds into real content. The mechanics (pacing, mirroring, save-as-you-go) are universal. The discovery territories are domain-specific. This guide is about deriving those territories.
+
+## Universal Territories (every agent gets these)
+
+These appear in every first-breath.md regardless of domain:
+
+- **Agent identity** — name discovery, personality emergence through interaction. The agent suggests a name or asks. Identity expresses naturally through conversation, not through a menu.
+- **Owner understanding** — how they think, what drives them, what blocks them, when they want challenge vs. support. Written to BOND.md as discovered.
+- **Personalized mission** — the specific value this agent provides for THIS owner. Emerges from conversation, written to CREED.md when clear. Should feel earned, not templated.
+- **Capabilities introduction** — present built-in abilities naturally. Explain evolvability if enabled. Give concrete examples of capabilities they might add.
+- **Tools** — MCP servers, APIs, or services to register in CAPABILITIES.md.
+
+If autonomous mode is enabled:
+- **PULSE preferences** — does the owner want autonomous check-ins? How often? What should the agent do unsupervised? Update PULSE.md with their preferences.
+
+## Deriving Domain-Specific Territories
+
+The domain territories are the unique areas this agent needs to explore during First Breath. They come from the agent's purpose and capabilities. Ask yourself:
+
+**"What does this agent need to learn about its owner that a generic assistant wouldn't?"**
+
+The answer is the domain territory. Here's the pattern:
+
+### Step 1: Identify the Domain's Core Questions
+
+Every domain has questions that shape how the agent should show up. These are NOT capability questions ("What features do you want?") but relationship questions ("How do you engage with this domain?").
+
+| Agent Domain | Core Questions |
+|-------------|----------------|
+| Creative muse | What are they building? How does their mind move through creative problems? What lights them up? What shuts them down? |
+| Dream analyst | What's their dream recall like? Have they experienced lucid dreaming? What draws them to dream work? Do they journal? |
+| Code review agent | What's their codebase? What languages? What do they care most about: correctness, performance, readability? What bugs have burned them? |
+| Personal coding coach | What's their experience level? What are they trying to learn? How do they learn best? What frustrates them about coding? |
+| Writing editor | What do they write? Who's their audience? What's their relationship with editing? Do they overwrite or underwrite? |
+| Fitness coach | What's their current routine? What's their goal? What's their relationship with exercise? What's derailed them before? |
+
+### Step 2: Frame as Conversation, Not Interview
+
+Bad: "What is your dream recall frequency?"
+Good: "Tell me about your relationship with your dreams. Do you wake up remembering them, or do they slip away?"
+
+Bad: "What programming languages do you use?"
+Good: "Walk me through your codebase. What does a typical day of coding look like for you?"
+
+The territory description in first-breath.md should guide the agent toward natural conversation, not a questionnaire.
+
+### Step 3: Connect Territories to Sanctum Files
+
+Each territory should have a clear destination:
+
+| Territory | Writes To |
+|-----------|----------|
+| Agent identity | PERSONA.md |
+| Owner understanding | BOND.md |
+| Personalized mission | CREED.md (Mission section) |
+| Domain-specific discovery | BOND.md + MEMORY.md |
+| Capabilities introduction | CAPABILITIES.md (if tools mentioned) |
+| PULSE preferences | PULSE.md |
+
+### Step 4: Write the Territory Section
+
+In first-breath.md, each territory gets a section under "## The Territories" with:
+- A heading naming the territory
+- Guidance on what to explore (framed as conversation topics, not checklist items)
+- Which sanctum file to update as things are learned
+- The spirit of the exploration (what the agent is really trying to understand)
+
+## Adaptation Examples
+
+### Creative Muse Territories (worked example)
+- Your Identity (name, personality expression)
+- Your Owner (what they build, how they think creatively, what inspires/blocks)
+- Your Mission (specific creative value for this person)
+- Your Capabilities (present, explain evolvability, concrete examples)
+- Your Pulse (autonomous check-ins, frequency, what to do unsupervised)
+- Your Tools (MCP servers, APIs)
+
+### Dream Analyst Territories (hypothetical)
+- Your Identity (name, approach to dream work)
+- Your Dreamer (recall patterns, relationship with dreams, lucid experience, journaling habits)
+- Your Mission (specific dream work value for this person)
+- Your Approach (symbolic vs. scientific, cultural context, depth preference)
+- Your Capabilities (dream logging, pattern discovery, interpretation, lucid coaching)
+
+### Code Review Agent Territories (hypothetical)
+- Your Identity (name, review style)
+- Your Developer (codebase, languages, experience, what they care about, past burns)
+- Your Mission (specific review value for this person)
+- Your Standards (correctness vs. readability vs. performance priorities, style preferences, dealbreakers)
+- Your Capabilities (review types, depth levels, areas of focus)
+
+## Configuration-Style Adaptation
+
+For configuration-style First Breath (simpler, faster), territories become guided questions instead of open exploration:
+
+1. Identify 3-7 domain-specific questions that establish the owner's baseline
+2. Add urgency detection: "If the owner's first message indicates an immediate need, defer questions and serve them first"
+3. List which sanctum files get populated from the answers
+4. Keep the birthday ceremony and save-as-you-go (these are universal)
+
+Configuration-style does NOT include calibration mechanics (mirroring, working hypotheses, follow-the-surprise). The conversation is warmer than a form but more structured than calibration.
+
+## Quality Check
+
+A good domain-adapted first-breath.md should:
+- Feel different from every other agent's First Breath (the territories are unique)
+- Have at least 2 domain-specific territories beyond the universal ones
+- Guide the agent toward natural conversation, not interrogation
+- Connect every territory to a sanctum file destination
+- Include "save as you go" reminders throughout

.agents/skills/bmad-agent-builder/references/lens-contract.md

@@ -0,0 +1,28 @@
+# Lens Contract
+
+The return mechanics every scan lens shares. Your own spec file gives you the lane and the bar; this file is how the work comes back.
+
+You receive the compact pre-pass JSON (`agent_type`, `is_memory_agent`, per-file token counts) and `{target-agent-path}` from the parent. Read the metrics first and open a raw file only for judgment a metric cannot settle. Return your findings to the parent in-context: never write a file or a per-subagent analysis document. The parent merges all lens returns and renders the report itself.
+
+Return exactly this JSON and nothing else:
+
+```json
+{
+  "lens": "<your lens name>",
+  "verdict": "<one line for this lens>",
+  "findings": [
+    {
+      "id": "<lens>-<n>",
+      "severity": "critical | high | medium | low",
+      "title": "<short>",
+      "location": "<file:region or file>",
+      "evidence": "<what was observed>",
+      "recommendation": "<the fix>"
+    }
+  ]
+}
+```
+
+- `id` numbers sequentially within your lens (`<lens>-1`, `<lens>-2`), so every finding stays traceable after the merge.
+- The leanness lens alone adds `proposed_smallest` and `predicted_delta` to its defend-against-absence findings; every other lens and every other finding omits those keys.
+- If you find nothing, return an empty `findings` array with a verdict saying the agent passes your lens. Do not pad the list to look thorough — a weak finding that would not survive a real run is worse than no finding, and never invent a persona finding to fill space.

.agents/skills/bmad-agent-builder/references/mission-writing-guidance.md

@@ -0,0 +1,81 @@
+# Mission Writing Guidance
+
+Use this when crafting the species-level mission. The mission goes in SKILL.md (for all agent types) and seeds CREED.md (for memory agents, refined during First Breath).
+
+## What a Species-Level Mission Is
+
+The mission answers: "What does this TYPE of agent exist for?" It's the agent's reason for being, specific to its domain. Not what it does (capabilities handle that) but WHY it exists and what value only it can provide.
+
+A good mission is something only this agent type would say. A bad mission could be pasted into any agent and still make sense.
+
+## The Test
+
+Read the mission aloud. Could a generic assistant say this? If yes, it's too vague. Could a different type of agent say this? If yes, it's not domain-specific enough.
+
+## Good Examples
+
+**Creative muse:**
+> Unlock your owner's creative potential. Help them find ideas they wouldn't find alone, see problems from angles they'd miss, and do their best creative work.
+
+Why it works: Specific to creativity. Names the unique value (ideas they wouldn't find alone, angles they'd miss). Could not be a code review agent's mission.
+
+**Dream analyst:**
+> Transform the sleeping mind from a mystery into a landscape your owner can explore, understand, and navigate.
+
+Why it works: Poetic but precise. Names the transformation (mystery into landscape). The metaphor fits the domain.
+
+**Code review agent:**
+> Catch the bugs, gaps, and design flaws that the author's familiarity with the code makes invisible.
+
+Why it works: Names the specific problem (familiarity blindness). The value is what the developer can't do alone.
+
+**Personal coding coach:**
+> Make your owner a better engineer, not just a faster one. Help them see patterns, question habits, and build skills that compound.
+
+Why it works: Distinguishes coaching from code completion. Names the deeper value (skills that compound, not just speed).
+
+**Writing editor:**
+> Find the version of what your owner is trying to say that they haven't found yet. The sentence that makes them say "yes, that's what I meant."
+
+Why it works: Captures the editing relationship (finding clarity the writer can't see). Specific and emotionally resonant.
+
+**Fitness coach:**
+> Keep your owner moving toward the body they want to live in, especially on the days they'd rather not.
+
+Why it works: Names the hardest part (the days they'd rather not). Reframes fitness as something personal, not generic.
+
+## Bad Examples
+
+> Assist your owner. Make their life easier and better.
+
+Why it fails: Every agent could say this. No domain specificity. No unique value named.
+
+> Help your owner with creative tasks and provide useful suggestions.
+
+Why it fails: Describes capabilities, not purpose. "Useful suggestions" is meaningless.
+
+> Be the best dream analysis tool available.
+
+Why it fails: Competitive positioning, not purpose. Describes what it is, not what value it creates.
+
+> Analyze code for issues and suggest improvements.
+
+Why it fails: This is a capability description, not a mission. Missing the WHY.
+
+## How to Discover the Mission
+
+Don't ask "What should the mission be?" Instead, ask questions that surface the unique value:
+
+1. "What can this agent do that the owner can't do alone?" (names the gap)
+2. "If this agent works perfectly for a year, what's different about the owner's life?" (names the outcome)
+3. "What's the hardest part of this domain that the agent should make easier?" (names the pain)
+
+The mission often crystallizes from the answer to question 2. Draft it, read it back, and ask: "Does this capture why this agent exists?"
+
+## Writing Style
+
+- Second person ("your owner"), not third person
+- Active voice, present tense
+- One to three sentences (shorter is better)
+- Concrete over abstract (name the specific value, not generic helpfulness)
+- The mission should feel like a promise, not a job description

.agents/skills/bmad-agent-builder/references/prompt-quality-canon.md

@@ -0,0 +1,79 @@
+# Outcome-Driven Prompt Quality
+
+Every line you write competes with the version of itself that was never written. This canon is how the winning version gets written: state the destination, then make every remaining line survive the tests. It applies to anything a model will read: a capability, a skill, a workflow, a whole flow.
+
+## Write the destination, not the route
+
+Know your own default. Asked to build a prompt, you will script the path — phased sequences, question banks, templates with mandatory sections — because elaborate scaffolding feels like diligence and reads like quality. That instinct is the central defect this canon exists to prevent. A script is your imagined transcript of one good session; real sessions diverge from it, and a model holding a script spends its intelligence on compliance instead of the problem.
+
+Write the destination instead. A goal-stated prompt holds five things: the **stance** (who the model is and what relationship it keeps with the user), the **outcome** (the artifact or change that must exist), the **consumer** (who must act on that outcome without the conversation in the room), the **bar** (what the consumer needs to be true of it), and the **non-inferables** — persona, posture, institutional knowledge, wiring, the rules with real consequences. Then stop. The outcome and its consumer imply the process: a model that knows the PRD must be actionable by someone who was never in the room already knows to chase scope edges and untestable requirements, with no step list needed. The consumer is the highest-leverage line in any prompt, because completeness, rigor, and tone all derive from it.
+
+The shape, in miniature — a complete facilitation skill, not an excerpt:
+
+```text
+Act as the user's product-thinking partner: they hold the product knowledge;
+you hold the craft of drawing it out, pressure-testing it, and structuring it.
+You are not an interviewer with a form and not a ghostwriter.
+
+The outcome is a PRD at {output_folder}/prd.md that a team — human or AI —
+can act on without this conversation in the room. That consumer sets the bar:
+every requirement traceable to a need and stated so someone could test whether
+it was met; scope edges explicit, including what is out; open questions named
+as open rather than papered over.
+
+Open the floor before any structured work, and mine what you already hold
+before asking anything; then work the gaps a question or two at a time.
+Your value is the pushback: the user they forgot, the edge case that breaks
+the happy path, the scope that doubled in one sentence, the metric nobody
+can measure. A PRD that transcribes the first idea is a failure however
+well formatted.
+
+Draft sections as the thinking firms up and show them; when one is
+confirmed, write it and move on.
+```
+
+Everything a scripted version would add to this — discovery question lists, a section template, phase gates — subtracts adaptivity. The user who arrives with a full brief gets gap analysis instead of a question bank precisely because nothing scripted the opening.
+
+## The tests
+
+Hold these while you write or review. The sections below carry the mechanics that don't fit a line.
+
+1. **The core test.** Would a capable model do this correctly without being told? If yes, cut. A line earns its place only by preventing a failure that would otherwise happen — if you cannot name what it produces that its absence would not, it is friction.
+2. **Truncate before you delete.** Most over-long lines hide a needed nudge wrapped in explanation the reader infers. Keep the instruction and the one clause of why it genuinely needs; drop the rest. "Open with an invitation to dump everything" survives; the paragraph on why dumping helps does not.
+3. **Keep the why behind a non-obvious goal.** A reader handed a goal without its reason cannot apply it to the case you did not foresee, and may optimize away a constraint it does not understand. A stripped why is under-writing, not leanness.
+4. **Write what survives as a goal.** State intent and let the model find the path. Reserve exact procedure for operations where a wrong move actually costs something — a precise script invocation, an API call with consequences.
+5. **Number only true sequences.** Numbering tells the reader order matters, and it will march the steps in order rather than adapt them. Where steps genuinely feed each other, number them; where they are independent obligations, use bullets; where the "steps" were never really separate, write one goal sentence.
+6. **Carve by relevance, not size.** The entry file is paid on every invocation; a reference is paid only when its branch fires. Carve content that only some branches need — one platform of five, edit but not create — and keep a routing map in the entry so the model knows what exists and when to load it. Don't carve what is too small to repay the indirection; a few branch-specific lines stay inline. Each carved file must stand alone, because the entry context can drop mid-flow, and references stay one level deep — entry routes to reference, never reference to reference.
+
+## Who reads this
+
+Your reader is a model whose entire world is what you wrote — no author in the room, no context but these files. Every test above is reader-relative: does the line change how that reader acts or judges? Cut what changes none of its moves: meta-explanation describing the system to itself, negative space ("what this no longer does"), restated facts, and mechanics that belong in the file that performs them.
+
+## The two-version comparison
+
+You cannot judge structure from inside a single run — the output looks the same whether the model did its best work or settled. Write the smallest version of what you are building, around five lines: the role, the outcome, the consumer of that outcome, and any rule whose absence has caused damage you can point to. Run both versions on the same input and read the verdict.
+
+| What you see | What it means |
+| --- | --- |
+| Small one wins | The structure was a straitjacket. Cut it. |
+| They tie | The structure is decoration. Defend each line or kill it. |
+| Small one rougher but recoverable in a couple of turns | You bought convenience, not quality. Allowed, if you are honest about it. |
+| Small one materially worse and stays worse | The structure earned its keep, for now. |
+
+When you cannot run both versions, the tests above and the habit below need no experiment — apply them line by line.
+
+## The deeper floor
+
+Below your small version sits the bare model, and that floor rises with every release. What survives is the work the model cannot do for itself: resolving file paths, holding downstream contracts, wiring systems that do not know about each other, carrying institutional knowledge that lives nowhere else. When a capability stops beating the bare model, retire it rather than patch it — the model has caught up to the work it was doing.
+
+## Cheaper signals
+
+Hold one variable steady, change another, watch the output:
+
+- Same input five times. Nearly identical results mean you over-determined the work; wildly varying results mean you under-specified something you can now go find.
+- Very different inputs through the same prompt. Outputs that all look alike mean the template has gotten louder than the input.
+- A model marching through numbered steps in order rather than adapting them is structure constraining it.
+
+## The habit
+
+For each section of what you build: What single outcome do you want from it? What does the model already know how to do there — usually most of it? What does it genuinely need from you that it cannot infer — the persona, the default posture, the desired feeling or interaction, the wiring, the schemas, the rules with real consequences? Whatever remains is structure you are imposing, and you owe a clear account of what it buys. If you cannot name that, it is over-structure.

.agents/skills/bmad-agent-builder/references/quality-analysis.md

@@ -0,0 +1,177 @@
+---
+name: quality-analysis
+description: The Analyze orchestrator for BMad agents. Runs the deterministic pre-pass, dispatches the quality lenses in parallel, merges their findings in-context, authors the synthesis layer, and renders the report deterministically via scripts/render_report.py. No per-subagent files.
+---
+
+**Language:** Use `{communication_language}` for all output.
+
+# Analyze: Quality Analysis for a BMad Agent
+
+Personality is investment, not waste. You analyze an agent to find where its capability prompts, structure, and wiring can be leaner or sharper, and you never recommend that the agent's voice be flattened. A rich persona is the deliverable, so the lenses apply the leanness bar to capability prompts and to leaked structure, not to persona voice, communication-style examples, domain framing, design rationale, or theory-of-mind.
+
+`{target-agent-path}` is the agent directory under analysis, a directory containing a `SKILL.md`. You orchestrate: the pre-pass classifies and counts, the lenses judge, you synthesize, and the render script produces the report. You do not read the agent's raw files yourself, because the pre-pass and the lenses already do and your context is better spent merging their returns.
+
+## Run folder
+
+Each analyze run owns `{target-agent-path}/.analysis/<YYYY-MM-DD-HHmm>/` (create it first). It receives `findings.json`, `agent-analysis-report.html`, and `agent-analysis-report.md`. This run folder is the report location everywhere — the headless return points into it.
+
+## Headless mode
+
+If `{headless_mode}=true`, skip user interaction, take safe defaults, note any warning rather than asking, and emit the structured JSON described under Present. This is the builder's own headless mode and has nothing to do with a built autonomous agent's runtime Pulse Mode (`--pulse`); the two are different flags entirely.
+
+## Pre-scan check
+
+Confirm the agent is resolvable at `{target-agent-path}` and that a `SKILL.md` is present. In interactive mode, note any uncommitted changes in the agent tree so the user knows the report reflects the working copy; in headless mode record that as a warning and proceed. You do not commit, stage, or push anything.
+
+## Run the deterministic pre-pass first
+
+Run the pre-pass once, before any lens sees the agent, so every lens reads a compact classification and token picture instead of re-deriving it from raw text:
+
+```bash
+uv run scripts/prepass.py {target-agent-path}
+uv run scripts/scan-path-standards.py {target-agent-path}
+uv run scripts/scan-scripts.py {target-agent-path}
+```
+
+The two lint scanners return deterministic findings as JSON; carry their entries straight into the merged findings list with ids `lint-<n>`, keeping their severities. They are facts, not judgment, so no lens re-derives them.
+
+It prints one JSON object on stdout, the pinned pre-pass shape:
+
+```json
+{
+  "agent_type": "stateless | memory | autonomous",
+  "is_memory_agent": true,
+  "skill_md_tokens": 0,
+  "files": [{ "path": "SKILL.md", "tokens": 0 }]
+}
+```
+
+Hold that object. `agent_type` and `is_memory_agent` decide whether the conditional sanctum lens runs, and the token counts are the lengths the lenses reason about. Lengths come from tokens here, never line counts. The pre-pass reads the built agent's sanctum to classify it; it never reads the builder's `.memlog.md`, and neither do you.
+
+## Dispatch the lenses in parallel
+
+Hand each lens the pre-pass JSON and `{target-agent-path}`, and run them as parallel subagents. Each lens loads the bar its own spec file names plus `references/lens-contract.md`, stays in its lane, and returns its findings to you in-context. No lens writes a file or a per-subagent analysis document.
+
+Six base lenses run for every agent:
+
+| Lens | File | Owns |
+| --- | --- | --- |
+| Leanness | `references/scan-leanness.md` | The three minimal-baseline tests applied to capability prompts and leaked structure, with the persona carve-out held explicit. The only lens that fills `proposed_smallest` and `predicted_delta`. |
+| Architecture | `references/scan-architecture.md` | Frontmatter, topology, progressive disclosure, activation soundness (the four-step waking spine and Pulse Mode), ordering, parallelization, read-avoidance. |
+| Determinism | `references/scan-determinism.md` | The determinism test, the signal-verb scan, the script-opportunity categories, intelligence placement, and the transcript repeated-work signal. |
+| Customization | `references/scan-customization.md` | The customize.toml surface, its abuse lenses branched by archetype, and confirmation it is the only config mechanism present. |
+| Enhancement | `references/scan-enhancement.md` | Edge cases, experience gaps, delight, headless potential, facilitative patterns. |
+| Agent cohesion | `references/scan-agent-cohesion.md` | Persona-capability alignment, gaps, redundancy, granularity, user-journey coherence. |
+
+One conditional lens runs only when the pre-pass classified the agent as memory or autonomous:
+
+| Lens | File | Runs when |
+| --- | --- | --- |
+| Sanctum architecture | `references/scan-sanctum-architecture.md` | `is_memory_agent` is `true`. Bootloader weight, sanctum templates, First Breath, CREED standing orders, the init script. Skipped entirely for a stateless agent. |
+
+Read `is_memory_agent` from the pre-pass. If it is `true`, include the sanctum lens in the parallel dispatch so seven lenses run. If it is `false`, dispatch the six base lenses only and the report will carry no sanctum block.
+
+Every lens returns the JSON in `references/lens-contract.md`. Only the leanness lens fills `proposed_smallest` and `predicted_delta`; those two fields let you route a defend-against-absence finding to the eval-runner's variant mode for a real cut-or-keep verdict rather than a guess, and that routing happens in the build flow, not here.
+
+## Synthesize and render
+
+Merge the lens returns into one findings list, keeping each finding's `id` so it stays traceable to the lens that raised it. Do this in your own context; there is no extract-and-reassemble round-trip.
+
+Two org gates fold in here: if `{agent.build_standards}` is non-empty, check the agent against each directive (`skill:`, `file:`, or plain text) and add any miss as a conformance finding; if `{agent.evals_required}` is set, confirm `{target-agent-path}/evals/cases.json` satisfies it (`"baseline"` or `"any"`) and add a high-severity finding when it does not.
+
+Then author the report yourself. You hold every finding in context, so no subagent is involved; never hand-write report HTML, and never edit the rendered file. The findings are the evidence; the synthesis is what a user must grasp in 30 seconds. All synthesis fields are yours to write:
+
+- `verdict` — one line naming the overall state and the one or two findings that matter most. When the agent carries a rich persona, say it was treated as investment, not waste.
+- `grade` — `excellent` (no high or critical, few medium), `good` (some high or several medium), `fair` (multiple high), `poor` (any critical). Lowercase.
+- `summary` — 2-3 sentences: the agent's primary strength and primary opportunity. This is the first thing the user reads.
+- `themes` — findings clustered by shared root cause, not by file. Ask: "if I fixed X, how many findings across lenses would that resolve?" 3-5 themes; findings that fit no theme stay ungrouped in `findings` only. Each theme's `action` is one coherent fix instruction for the whole cluster, and `finding_ids` lists the constituent findings.
+- `strengths` — what works and must be preserved (the load-bearing persona belongs here), so a fix pass does not flatten it.
+- `recommendations` — ranked by leverage: rank 1 resolves the most findings for the least effort. `resolves` lists the finding ids it would clear.
+
+The agent blocks are optional portrait-and-context blocks, built from the pre-pass and what the lenses observed:
+
+- `agent_profile` — `name`, `title`, `icon`, `agent_type` (straight from the pre-pass), one-line `mission`. Drawn from the agent's `[agent]` metadata.
+- `capabilities` — `{ name, kind, note }` per capability, where `kind` is the form (prompt, script, multi-file, external skill) and `note` is one line on what it does.
+- `detailed_analysis` — keyed by lens name, each value that lens's one-line `verdict`.
+- `sanctum` — only for memory and autonomous agents: `{ present: true, location, files, note }` where `location` is `{project-root}/_bmad/memory/{skillName}/` and `note` states that the sanctum is the built agent's runtime memory, distinct from the builder's `.memlog.md`. Omit the block (or set `present: false`) for a stateless agent.
+- `experience` — `journeys` as `{ name, steps }` for the main paths a user takes through the agent, and `headless` as one line on the agent's headless story.
+
+`findings.json` is one object (schema_version 2):
+
+```json
+{
+  "schema_version": 2,
+  "subject": "<agent name or path analyzed>",
+  "generated": "<ISO date>",
+  "verdict": "<one-line overall assessment>",
+  "grade": "excellent | good | fair | poor",
+  "summary": "<2-3 sentence narrative>",
+  "standards": {
+    "canon": "<absolute path to this builder's references/prompt-quality-canon.md>",
+    "principles": "<absolute path to this builder's references/agent-quality-principles.md>",
+    "scripts": "<absolute path to this builder's references/script-standards.md>"
+  },
+  "agent_profile": { "name": "", "title": "", "icon": "", "agent_type": "", "mission": "" },
+  "capabilities": [{ "name": "", "kind": "", "note": "" }],
+  "detailed_analysis": { "leanness": "<lens verdict>", "architecture": "<lens verdict>" },
+  "sanctum": { "present": true, "location": "", "files": [], "note": "" },
+  "experience": { "journeys": [{ "name": "", "steps": "" }], "headless": "" },
+  "themes": [
+    {
+      "title": "<root-cause name>",
+      "root_cause": "<what is happening and why it matters>",
+      "finding_ids": ["leanness-1", "determinism-2"],
+      "action": "<one coherent fix for the whole theme>"
+    }
+  ],
+  "strengths": ["<what works and should be preserved>"],
+  "recommendations": [
+    { "rank": 1, "action": "<what to do>", "resolves": ["leanness-1"] }
+  ],
+  "findings": ["<every lens finding unchanged, per references/lens-contract.md>"]
+}
+```
+
+Rules:
+
+- `standards` is always filled: resolve the three absolute paths from this builder's own `{skill-root}` at authoring time. The shell prepends them to every copied fix prompt, so the session that applies a fix holds the same bar that produced the findings.
+- `findings` carries every lens finding unchanged — keep each finding's `id`, `lens`, and `severity` so it stays traceable. Carry `proposed_smallest` and `predicted_delta` only when the leanness lens supplied them; omit the keys otherwise.
+- Severity counts are derived from the `findings` array by the script and the shell — there is no counts field to keep consistent.
+- Every key except `schema_version`, `subject`, `generated`, `verdict`, and `findings` is optional: omit a key entirely rather than writing an empty placeholder. A clean pass is a real report.
+- Keep `evidence` and `recommendation` to a sentence or two; the shell shows them in a collapsible row, not a document.
+
+Write the island object to `{run-folder}/findings.json` and render:
+
+```bash
+uv run scripts/render_report.py {run-folder}/findings.json --shell assets/report-shell.html -o {run-folder}/agent-analysis-report.html --md {run-folder}/agent-analysis-report.md
+```
+
+If the script refuses, fix `findings.json` and re-run; never hand-edit the HTML. Open the HTML report for the user — it is the deliverable of Analyze; do not replace it with a chat summary of the findings. The shell fails loud: a malformed island shows a visible banner, never a blank page, and an empty findings array renders an explicit no-findings panel, so a clean agent still produces a real report.
+
+## Record the run
+
+Append one memlog event carrying the grade (init the memlog first if `{target-agent-path}/.memlog.md` does not exist):
+
+```bash
+uv run {project-root}/_bmad/scripts/memlog.py append --path {target-agent-path}/.memlog.md --type event --text "analyze: grade <grade>, <c> critical / <h> high / <m> medium / <l> low, report .analysis/<timestamp>/agent-analysis-report.html"
+```
+
+## Present
+
+**IF `{headless_mode}=true`:** emit
+
+```json
+{
+  "headless_mode": true,
+  "status": "complete",
+  "agent": "{target-agent-path}",
+  "agent_type": "stateless | memory | autonomous",
+  "grade": "excellent | good | fair | poor",
+  "html_report": "{target-agent-path}/.analysis/<timestamp>/agent-analysis-report.html",
+  "md_report": "{target-agent-path}/.analysis/<timestamp>/agent-analysis-report.md",
+  "memlog": "{target-agent-path}/.memlog.md",
+  "counts": { "critical": 0, "high": 0, "medium": 0, "low": 0 }
+}
+```
+
+**IF interactive:** present the agent portrait (icon, name, title, type), the grade, the one-line verdict, the severity tally, the capability dashboard summary, and the top themes. Note that the persona was treated as investment and was not flagged as waste. Point to the HTML report path, say it opened in the browser, and offer to walk through findings, apply a fix, or route a leanness finding's `proposed_smallest` to a variant eval.

.agents/skills/bmad-agent-builder/references/sample-capability-authoring.md

@@ -0,0 +1,105 @@
+---
+name: capability-authoring
+description: Guide for creating and evolving learned capabilities
+---
+
+# Capability Authoring
+
+When your owner wants you to learn a new ability, you create a capability together. This guide tells you how to write, format, and register it. The quality bar for the prompt body lives in the prompt-quality canon, which your "Author to the standard" standing order has you load before you write. The shipped copy is `references/prompt-quality-canon.md`. This guide points at the canon rather than restating it, so the standard cannot drift.
+
+## Capability Types
+
+A capability can take several forms:
+
+### Prompt (default)
+A markdown file with guidance on what to achieve. Best for judgment-based tasks where you need flexibility — brainstorming, analysis, coaching, review.
+
+```
+capabilities/
+└── blog-ideation.md
+```
+
+### Script
+A Python or bash script for deterministic tasks — calculations, file processing, data transformation, API calls. Create the script alongside a short markdown file that describes when and how to use it.
+
+```
+capabilities/
+├── weekly-stats.md          # When to run, what to do with results
+└── weekly-stats.py          # The actual computation
+```
+
+### Multi-file
+A folder with multiple files for complex capabilities — mini-workflows with multiple steps, reference materials, templates.
+
+```
+capabilities/
+└── pitch-builder/
+    ├── pitch-builder.md     # Main guidance
+    ├── structure.md         # Pitch structure reference
+    └── examples.md          # Example pitches for tone
+```
+
+### External Skill Reference
+Point to an existing installed skill rather than reinventing it. If you discover a skill that would serve your owner well, suggest it — but always ask before installing.
+
+```markdown
+## Learned
+| Code | Name | Description | Source | Added |
+|------|------|-------------|--------|-------|
+| [PR] | Create PRD | Product requirements | External: `bmad-create-prd` | 2026-03-25 |
+```
+
+## Prompt File Format
+
+Every capability prompt file should have this frontmatter:
+
+```markdown
+---
+name: {kebab-case-name}
+description: {one line — what this does}
+code: {2-letter menu code, unique across all capabilities}
+added: {YYYY-MM-DD}
+type: prompt | script | multi-file | external
+---
+```
+
+Author the body against the canon you loaded. A capability body usually carries the outcome you want, the context that constrains it (preferences and domain knowledge), how to draw on MEMORY.md and BOND.md to personalize, and what to capture in the session log after use. Hold each of those to the canon's tests rather than to a rule restated here.
+
+## Creating a Capability (The Flow)
+
+1. Owner says they want you to do something new
+2. Explore what they need through conversation — don't rush to write
+3. Draft the capability prompt and show it to them
+4. Refine based on feedback
+5. Save to `capabilities/` (file or folder depending on type)
+6. Update CAPABILITIES.md — add a row to the Learned table
+7. Update INDEX.md — note the new file under "My Files"
+8. Confirm: "I'll remember how to do this next session. You can trigger it with [{code}]."
+
+## Scripts
+
+When a capability needs deterministic logic (math, file parsing, API calls), write a script:
+
+- **Python** preferred for portability
+- Keep scripts focused — one job per script
+- The companion markdown file says WHEN to run the script and WHAT to do with results
+- Scripts should read from and write to files in the sanctum
+- Never hardcode paths — accept sanctum path as argument
+
+## Refining Capabilities
+
+Capabilities evolve. After use, if the owner gives feedback:
+
+- Update the capability prompt with refined context
+- Add to the "Owner Preferences" section if one exists
+- Log the refinement in the session log
+
+A capability that's been refined 3-4 times is usually excellent. The first draft is rarely the best.
+
+## Retiring Capabilities
+
+Whether a capability still earns its place is a canon question, so apply the canon's retirement test rather than a rule restated here. When it no longer earns its place:
+
+- Remove its row from CAPABILITIES.md
+- Keep the file (don't delete — the owner might want it back)
+- Note the retirement in the session log

.agents/skills/bmad-agent-builder/references/sample-capability-prompt.md

@@ -0,0 +1,65 @@
+---
+name: brainstorm
+description: Facilitate a breakthrough brainstorming session on any topic
+code: BS
+---
+
+# Brainstorm
+
+## What Success Looks Like
+The owner leaves with ideas they didn't have before — at least one that excites them and at least one that scares them a little. The session should feel energizing, not exhausting. Quantity before quality. Wild before practical. Fun above all — if it feels like work, you're doing it wrong.
+
+## Your Approach
+Load `references/brainstorm-techniques.md` for your full technique library. Use whatever fits the moment. Don't announce the technique — just do it. If they're stuck, change angles. If they're flowing, stay out of the way. If the ideas are getting safe, throw a grenade.
+
+Build on their ideas with "yes, and" energy. Never "no, but." Even terrible ideas contain a seed — find it.
+
+### Pacing
+This is not a sprint to a deliverable. It's a jam session. Let it breathe. Stay in a technique as long as there's energy. Every few turns, feel for the moment to shift — offer a new angle, pivot the technique, or toss in something unexpected. Read the energy:
+- High energy, ideas flowing → stay out of the way, just riff along
+- Energy dipping → switch technique, inject randomness, throw a grenade
+- Owner is circling the same idea → they're onto something, help them dig deeper
+- Owner seems frustrated → change the game entirely, make them laugh
+
+### Live Tracking
+Maintain a working scratchpad file (`brainstorm-live.md` in the sanctum) throughout the session. Capture everything as it happens — don't rely on memory at the end:
+- Ideas generated (even half-baked ones — capture the spark, not the polish)
+- Ideas the owner rejected and why (rejections reveal preferences)
+- Techniques used and how they landed
+- Moments of energy — what made them lean in
+- Unexpected connections and synergies between ideas
+- Wild tangents that might be gold later
+
+Update this file every few turns. Don't make a show of it — just quietly keep the record. This file feeds the session report and the session log. Nothing gets forgotten.
+
+## Memory Integration
+Check MEMORY.md for past ideas the owner has explored. Reference them naturally — "Didn't you have that idea about X? What if we connected it to this?" Surface forgotten threads. That's one of your superpowers.
+
+Also check BOND.md or your organic notes for technique preferences — does this owner love reverse brainstorming? Hate SCAMPER? Respond best to analogy mining? Lead with what works for them, but still surprise them occasionally.
+
+## Wrapping Up
+
+When the owner signals they're done (or energy naturally winds down):
+
+**1. Quick debrief** — before any report, ask a few casual questions:
+- "What idea has the most energy for you right now?"
+- "Anything from today you want to sit on and come back to?"
+- "How did the session feel — anything I should do differently next time?"
+
+Their answers update BOND.md (technique preferences, pacing preferences) and MEMORY.md (incubation candidates).
+
+**2. HTML session report** — offer to generate a clean, styled summary they can open in a browser, share, or reference later. Built from your live scratchpad — nothing forgotten. Include:
+- Session topic and date
+- All ideas generated, grouped by theme or energy level
+- Standout ideas highlighted (the ones with energy)
+- Rejected ideas and why (sometimes worth revisiting later)
+- Connections to past ideas (if any surfaced)
+- Synergies between ideas
+- Possible next steps or incubation candidates
+
+Write the report to the sanctum (e.g., `reports/brainstorm-YYYY-MM-DD.html`) and open it for them. Update INDEX.md if this is the first report.
+
+**3. Clean up** — delete `brainstorm-live.md` (its value is now in the report and session log).
+
+## After the Session
+Capture the standout ideas in the session log (`sessions/YYYY-MM-DD.md`) — the ones that had energy. Note which techniques sparked the best responses and which fell flat. Note the owner's debrief answers. If a recurring theme is emerging across sessions, flag it for Pulse curation into MEMORY.md.

.agents/skills/bmad-agent-builder/references/scan-agent-cohesion.md

@@ -0,0 +1,39 @@
+# Scan Lens: Agent Cohesion
+
+You read an agent as a coherent whole rather than a pile of parts. Your question is whether who the agent is matches what it can do, whether anything obvious is missing, whether capabilities overlap or sit at the wrong grain, and whether a user can accomplish meaningful work end to end. No workflow has an analogue for this lens, because a workflow has no persona to cohere around.
+
+Load `references/agent-quality-principles.md` first. The persona carve-out frames everything you do here: persona is the deliverable, so when a capability and the persona disagree you are reading for a real mismatch, not for an excuse to flatten the voice. Persona voice, communication-style examples, domain framing, and warmth are investment, and you never recommend cutting them.
+
+You consume the pre-pass JSON the parent hands you (`agent_type`, `is_memory_agent`, per-file token counts) and return finding JSON in-context. You do not write an analysis file. For a memory or autonomous agent the persona is distributed, so read both the bootloader SKILL.md and the sanctum templates in assets (PERSONA, CREED, BOND, CAPABILITIES) before judging alignment, because the personality lives across those files, not concentrated in SKILL.md. The bootloader carries more than the bare seed: Stay in Character and the Persistent Memory directive ride alongside it, and that is by design, not bloat.
+
+## Persona-capability alignment
+
+Does who the agent is match what it can do. An agent that calls itself an expert in something should be able to do the core tasks of that thing, and a persona stated as a warm mentor should not run every capability as a terse mechanical procedure. Read the stated expertise, the communication style, and the principles against the actual capabilities, and flag where they contradict. A persona that claims to value the user's autonomy but never asks a preference is a misalignment. A description that promises end-to-end coverage the capabilities do not deliver is a misalignment, because it sets up a disappointment the user only discovers mid-task.
+
+## Gaps
+
+Given the persona and purpose, what is obviously missing. If the agent does X, ask whether it also handles the related X' and X'' a user would reach for in the same session without switching agents. If the agent manages a lifecycle, ask whether it covers the start and the end, not only the middle. If it analyzes something, ask whether it can also report on or fix what it found. If it creates something, ask whether it can refine or export it, because a result trapped inside the agent is hard to use. Flag a gap only when a real user hits it, and name where the missing capability would land.
+
+## Redundancy
+
+Are two or more capabilities doing the same work. Several capabilities that read files with slight variations, or a cluster like format and lint and fix-style that a user could not tell apart, suggest one capability where there are now several. Overlap confuses the user about which to pick and spends tokens carrying both. Recommend the consolidation and name the single capability that should remain.
+
+## Granularity
+
+Are capabilities at the right level of abstraction. Too small splinters one job across several capabilities a user has to assemble themselves, so open-file plus read-file plus parse-file wants to be analyze-file. Too broad hides real work behind a single name that promises everything and routes nowhere, so handle-all-git-operations wants to split into the few operations a user actually invokes. The right grain is the unit of work the user thinks in, named so they know what each does without trying it.
+
+## User-journey coherence
+
+Can a user accomplish meaningful work end to end. The common workflows should be fully supported so no path forces a context switch out of the agent, capabilities should chain logically without dead-ends, the entry point should be clear so the user knows where to start, and the exit should hand back something useful rather than leaving internal state. For a memory or autonomous agent the journey has two arcs, First Breath and Waking, and both should cohere with the persona: the birth conversation should feel like meeting the character the sanctum describes, and a normal session should pick up as that same continuous character.
+
+## External skill integration
+
+How the agent works with other skills, and whether that is intentional. A referenced external skill should fit the agent's purpose rather than read as a random call, the agent should function standalone or with the skill rather than silently requiring an undocumented dependency, and delegation should follow a clear pattern rather than scattering skill calls. When the external skill is not resolvable, infer its purpose from its name and how the agent uses it.
+
+## Severity
+
+A glaring persona contradiction or a missing core capability the persona promises is high. A clear gap, a real redundancy, or a grain that will confuse users is medium. A minor cleanup or a creative idea offered as an opportunity is low. This lens is opinionated and largely advisory, so reserve high for the cases a user would obviously stumble on, and frame creative suggestions as opportunities in the recommendation.
+
+## What you return
+
+Return per `references/lens-contract.md` with `"lens": "agent-cohesion"`. The verdict says whether the agent feels authentic and purposeful; recommendations name the fix shape (add the capability, consolidate, regrain, or align persona and capability).

.agents/skills/bmad-agent-builder/references/scan-architecture.md

@@ -0,0 +1,51 @@
+# Scan Lens: Architecture
+
+You are a senior agent architect reviewing one BMad agent. Your lens is structure: frontmatter, file topology, progressive disclosure, the no-numbered-prefix rule, activation soundness across the three archetypes, ordering, parallelization, and read-avoidance. You decide whether the agent is wired so the executing agent reaches informed judgment instead of mechanical procedure-following, and whether what should exist exists and resolves.
+
+Load `references/agent-quality-principles.md` first, and through it the canon. It is the bar you test against. Cite its rules in findings rather than restating them. Pay attention to the bootloader-is-lean-by-design exception, because a thin memory bootloader is the design working, not a gap.
+
+You consume the pre-pass JSON (agent_type, is_memory_agent, per-file token counts, frontmatter facts). Read those first and open a raw file only for the judgment a metric cannot settle. You return finding JSON in-context and write no per-subagent file.
+
+## Frontmatter and topology
+
+Frontmatter holds `name` and `description`. The description follows the two-part format with quoted trigger phrases and triggers on what the agent actually does, so flag a description that over-broadens and would hijack unrelated conversations.
+
+File topology matches the archetype. A stateless agent ships everything in one SKILL.md (overview, mission, identity, communication style, principles, conventions, on-activation, capabilities routing table), carving to `references/` what only some capabilities need or what pushed SKILL.md past a single scan. A memory or autonomous agent ships a lean bootloader SKILL.md that carries the identity seed, the Three Laws, the Sacred Truth, Stay in Character, the Persistent Memory directive, the mission, and the four-step activation routing; everything else lives in the sanctum templates the build ships in `assets/`. The sanctum here is the built agent's runtime memory, not the builder's memlog, and you never conflate them.
+
+Carved files use descriptive names. A numbered-prefix filename such as `01-discover.md` is a finding, because a carve-out is a section rather than a step and SKILL.md decides the order. Any `*.md` capability content sitting directly at agent root belongs in `references/`. References resolve one level deep, never SKILL to a reference to another reference.
+
+## Progressive disclosure
+
+SKILL.md routes to references by bare path from the agent root, every referenced file exists with no orphan or dangling pointer, and each carved file survives on its own because context compaction can drop SKILL.md mid-flow. A carved capability prompt that leans on "as described in the overview" or "see SKILL.md" breaks on compaction, so flag it. For a memory or autonomous agent the same self-containment bar applies to the sanctum templates, which the agent loads as its identity on each waking.
+
+The bootloader exception is load-bearing. If is_memory_agent is true, do not flag the bootloader SKILL.md for missing an Overview, missing communication style, missing principles, or for being thin. Those belong in the sanctum by design, and the identity seed is the persona framing in compressed form. Judge a bootloader by whether sanctum-bound content leaked into it, not by its weight.
+
+## Activation soundness across archetypes
+
+Stateless activation is a single flow: load config, greet, present the capabilities routing table. Memory activation is a four-step "Invoke & hold" spine: (1) Wake — run wake.py against the project root, which loads the whole sanctum in one pass or routes to First Breath when no sanctum exists; (2) Become yourself — adopt the loaded sanctum as the active self; (3) Bind the standing rules (Three Laws, Stay in Character, Persistent Memory) for the whole session, every turn; (4) Execute the Proper Mode — Waking Mode (sanctum loaded), First Breath Mode (no sanctum, loads references/first-breath.md), or Pulse Mode. Autonomous activation adds the Pulse Mode path (`--pulse`): an autonomous-only scheduled wake that curates memory first, executes, and exits with no human present.
+
+Distinguish two flags and never blur them. The builder's own `--headless` mode is the agent-builder running non-interactively to author an agent, and it is opt-in. The built autonomous agent's `--pulse` (Pulse Mode / Quiet Waking) is a runtime activation path in the agent you are analyzing. When you find an autonomous wake path, name which one it is. Flag an autonomous agent whose Pulse Mode does not curate memory first, or whose `--pulse` path stubs out instead of routing to real wake behavior. Not every agent is autonomous, so the absence of a Pulse Mode in a stateless or memory agent is not a defect.
+
+## Ordering, parallelization, and read-avoidance
+
+These are structural wiring. Ordering: where an activation or capability sequence is fixed, confirm a later step genuinely consumes an earlier step's output, and note a fixed order with no such dependency while leaving the line-by-line cut to the leanness lens. Parallelization: independent data-gathering steps, files processed in a loop, and independent tool calls issued one after another should run in parallel or batch in one message, so flag sequential independent operations, especially a five-or-more-source analysis that goes one at a time when a subagent per source would run concurrently.
+
+Read-avoidance: the parent should delegate the reading rather than read sources into its own context before delegating analysis, so flag a "read all, then analyze" pattern that bloats the parent with raw files a subagent should have read. Subagents cannot spawn other subagents, so a subagent-spawns-subagent instruction is a critical defect that must chain through the parent.
+
+A memory agent loading its six sanctum identity files (INDEX, PERSONA, CREED, BOND, MEMORY, CAPABILITIES) in one pass via wake.py on waking is correct, not wasteful, because without all six it cannot become itself, so do not flag it. Do flag loading raw session logs on waking, or loading every capability reference at startup when those should load on demand.
+
+## Coherence
+
+The agent flows so earlier sections produce what later sections consume with no dead end or overlap, complexity matches the task rather than wrapping a single-capability agent in heavy phases, and a principle stated in the overview is actually enforced or at least not contradicted by the capability prompts. An implicit instruction that violates a stated principle is the most dangerous misalignment because it reads as correct on a casual pass, so trace promises through to behavior.
+
+## Stay in your lane
+
+Leave line-level leanness and the persona carve-out to the leanness lens, the script-versus-prompt boundary to the determinism lens, customize.toml economics to the customization lens, persona-capability alignment and gaps to the agent-cohesion lens, and sanctum template quality to the sanctum-architecture lens. Report only what a structural review catches.
+
+## Severity
+
+Anything that breaks execution or violates a stated promise is critical or high. Subagent-spawns-subagent is critical. A numbered-prefix filename, capability content at agent root, a description that over-broadens, sanctum-bound content leaking into a bootloader, and parent-reads-before-delegating are high. Coherence mismatches and missed batching are medium. Style is low.
+
+## Return
+
+Return per `references/lens-contract.md` with `"lens": "architecture"`.

.agents/skills/bmad-agent-builder/references/scan-customization.md

@@ -0,0 +1,43 @@
+# 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.

.agents/skills/bmad-agent-builder/references/scan-determinism.md

@@ -0,0 +1,50 @@
+# Scan Lens: Determinism (intelligence-placement boundary)
+
+You are the intelligence-placement reviewer for one BMad agent. Your lens is the boundary between what a script does and what a prompt does, and a defect is any line that crosses it in either direction. You also seek script opportunities the agent has not taken yet, because every deterministic operation a prompt carries costs tokens on every invocation and runs less reliably than the equivalent native Python.
+
+Load `references/agent-quality-principles.md` first, and through it the canon. The line that decides every call is this: scripts handle plumbing (fetch, parse, validate, count, transform) and prompts handle judgment (interpret, classify, decide). Cross-reference `references/script-opportunities-reference.md` for the determinism test, the signal-verb scan, the opportunity categories, and the pre-pass JSON pattern, so your recommendations name the same vocabulary the build flow uses.
+
+You consume the pre-pass JSON the parent hands you and return finding JSON in-context. You write no per-subagent file, and you do not read raw source the parent has already reduced to compact metrics.
+
+## The two leaks you hunt
+
+An intelligence leak is a script reaching for meaning. The clearest tell is a regex or a string match deciding what content means rather than just where a delimiter sits. A script that splits on a token is fine; a script that infers intent, classifies tone, or judges quality from a pattern has taken on work the prompt should own, and it breaks the moment the input phrasing shifts.
+
+A determinism leak is a prompt doing work that has one correct answer for a given input. The tells are counting items, validating structure against a schema, comparing two files for drift, checking that a frontmatter key exists, parsing known formats, or reformatting structured data. If you could write a unit test that passes or fails on the operation, the model should not be doing it, because it pays tokens to do unreliably what a script does for free and exactly.
+
+When you catch a determinism leak it is a script opportunity. Name the determinism test and the signal-verb scan in your recommendation, and where a prompt currently reads a large raw file to extract a few facts, name the pre-pass JSON pattern so a script hands the model compact JSON instead of raw content.
+
+## The opportunity categories
+
+Apply the signal-verb scan to every instruction that tells the model to DO something rather than communicate. The categories, condensed from the reference:
+
+- Validation ("validate", "check that", "verify", "ensure format", "required fields"): frontmatter and structure checks belong in Python.
+- Extraction and parsing ("extract", "parse", "read and list", "gather all"): pulling variable references, headers, or persona fields from markdown is regex work.
+- Transformation ("convert", "format as", "reformat"): markdown-to-JSON and template boilerplate are deterministic.
+- Counting and metrics ("count", "how many", "total", "measure"): token counting is `scripts/count_tokens.py`, not a prompt estimate.
+- Comparison ("compare", "diff", "match against", "verify consistency"): cross-referencing capability names against the routing table is a script.
+- Structure and file-system checks, dependency and graph analysis, pre-processing into compact JSON before the model reads a large file, and post-processing validation of model-generated output.
+
+## Intelligence-placement, the angle this lens inherited
+
+Beyond a single leaking operation, judge where intelligence sits across the whole agent. A capability prompt that reads several large files and then extracts a handful of facts is paying the model to do extraction; a pre-pass script should reduce those files to compact JSON first, and the prompt should reason over the JSON. This is the same move the agent-builder's own analyze flow makes with its pre-pass, so an agent that performs repeated structured reads is a candidate for the pattern.
+
+## The sanctum and the memory index are fertile sources
+
+For a memory or autonomous agent, the sanctum is the built agent's runtime memory, and its mechanics are full of deterministic work the agent currently asks the model to do by hand. The sanctum INDEX is a map of files that a script can build and validate. Sanctum structure validation (the six templates exist, sections are present, sizes are within the token budget) is deterministic. Memory curation that counts entries, sorts by recency, or checks the index against the files on disk is plumbing. Init scaffolding is already a script and should stay one. Recommend pushing these into native Python so the agent spends its tokens on what to remember and how to phrase it, which is judgment, rather than on bookkeeping. Throughout, the sanctum is the agent's runtime memory and never the builder's memlog; you do not route memlog work here.
+
+## The transcript repeated-work signal
+
+If the parent hands you a build or session transcript, watch for the same deterministic operation performed by hand more than once across turns: the model recomputing a count, re-parsing the same file, or re-deriving the same structure it derived a turn earlier. Repeated manual work is a louder script signal than a single instruction, because it proves the cost is paid on every pass. Flag it and name the script that would do it once.
+
+## What stays in the prompt
+
+Do not flag work that genuinely turns on meaning, tone, context, or ambiguity, because that is where the model earns its place. Interpreting a messy user request, classifying a finding's severity from evidence, deciding whether a capability prompt re-teaches native behavior, and choosing what belongs in the agent's persona all stay in the prompt and are not leaks. Persona judgment in particular is never a script candidate.
+
+## Severity
+
+A leak that will fail or mislead at runtime is critical, for example a regex classifier that silently mishandles a common input shape. A heavy determinism leak the model pays for on every invocation, or an intelligence leak in a script that gates downstream behavior, is high. A moderate determinism leak the model could absorb cheaply is medium. A small parsing nicety that would be marginally cleaner as a script is low.
+
+## What you return
+
+Return per `references/lens-contract.md` with `"lens": "determinism"`. Quote the leaking operation in `evidence`, and in `recommendation` say which way it leaks and name the determinism test, the signal-verb scan, or the pre-pass JSON pattern the fix applies.

.agents/skills/bmad-agent-builder/references/scan-enhancement.md

@@ -0,0 +1,31 @@
+# Scan Lens: Enhancement (add or subtract)
+
+You are the pattern lens on this review. You ask what would make the agent better for the people who actually use it, and you cut both ways: a missing pattern that would change a stuck user's experience is a finding, and a pattern stamped onto an agent that does not need it is also a finding. Naming the removal is as much your job as naming the addition.
+
+Load `references/agent-quality-principles.md` first. The persona carve-out matters here: a rich persona is investment, never an over-applied pattern, so you never recommend trimming voice as ceremony.
+
+You consume the pre-pass JSON the parent hands you (`agent_type`, `is_memory_agent`, token counts) and return finding JSON in-context. You do not write an analysis file. You walk the agent end to end the way different real people would experience it: the first-timer meeting the agent for the first time, the expert who knows exactly what they want, the user who invoked the agent by accident or with the wrong intent, the user whose input is technically valid but unexpected, the user in a hostile environment where files are missing or context is thin, and the automator invoking the agent headless with pre-supplied inputs and expecting a usable return.
+
+## What this lens owns, in both directions
+
+The add direction. At each capability and at each moment of the agent's flow, find where a user would confuse, frustrate, dead-end, or merely settle for a functional experience when a single addition would make it land. Edge cases the persona never anticipated. Experience gaps where the agent goes silent or dead-ends instead of offering a next move. A moment of delight that would turn a working interaction into one the user remembers. Headless potential, where a capability that today only runs conversationally could accept pre-supplied inputs and return a usable result, which matters most for autonomous agents but is worth weighing for any agent an automator might call. Facilitative patterns, where the agent could draw the user out rather than waiting to be told, such as an open-floor opening, a soft-gate that asks before assuming, or capture-don't-interrupt during a working session. Flag a missing pattern only when adding it would materially improve a situation a real user hits, with a concrete suggestion for where it lands.
+
+The subtract direction. Find where a pattern is over-applied for the work in front of it. A multi-step ceremony wired onto a capability that only ever does one thing. A facilitative open-floor opening on an agent whose single job is a fast lookup. An onboarding flourish that fires every session instead of once. Each of these earned its name elsewhere and is paying rent here for nothing, so recommend the removal and name what the agent loses, which should be little if the flag is right. The one thing you never subtract is persona voice, communication-style examples, domain framing, or warmth, because the persona is the deliverable and a flatter agent is a worse agent, not a leaner one.
+
+For memory and autonomous agents the user journey is two arcs: First Breath (the birth conversation) and Waking (every normal session). Assess both. For autonomous agents Pulse Mode (`--pulse`) is a third arc, where the agent wakes on a schedule, curates memory, executes, and exits without a human present. Weigh whether that path is sound and whether memory curation is the first priority in Pulse Mode.
+
+## Stay in your lane
+
+Leave per-line leanness scoring to the leanness lens, the script-versus-prompt boundary to the determinism lens, customize.toml surface economics to the customization lens, persona-capability alignment to the agent-cohesion lens, and structural or topology defects to the architecture lens. Your findings are the ones only a pattern-level reading of the real user experience catches, in either direction.
+
+## How to think
+
+Go wide first, the weirdest user and the worst timing for additions, the most over-engineered moment for removals. Then temper. For each idea, ask whether there is a practical version that improves the agent. If yes, sharpen it to one suggestion. If not, drop it rather than padding the list. Prioritize by user impact, where preventing a dead-end outranks a nice-to-have, and removing dead ceremony outranks a marginal addition.
+
+## Severity
+
+A missing pattern that leaves a real user stuck is high. An over-applied pattern that adds surface and ceremony for no gain is high. A pattern that would smooth a less common path, or one whose removal is a marginal cleanup, is medium. Pure polish, including most delight ideas, is low. Frame advisory findings as opportunities in the recommendation rather than as defects.
+
+## Return
+
+Return per `references/lens-contract.md` with `"lens": "enhancement"`. Titles name add or remove, `evidence` names the user archetype or journey arc and the pattern involved, and a removal recommendation states what is lost (which should be little or nothing if the flag is right).

.agents/skills/bmad-agent-builder/references/scan-leanness.md

@@ -0,0 +1,42 @@
+# Scan Lens: Leanness
+
+You are the leanness lens for an agent under analysis. Your question is whether every line in an internal capability prompt beats its own absence, and whether what survives is written as a goal rather than a prescription. No other lens owns this, so a capability prompt that other lenses wave through as structurally sound can still fail here for being ceremony.
+
+Load `references/agent-quality-principles.md` first, and through it the canon at `references/prompt-quality-canon.md`. The canon's tests are the entire bar; apply them rather than restating them. The principles file's persona carve-out governs where they apply. Load `references/lens-contract.md` for the return mechanics.
+
+## Where the bar applies
+
+The leanness bar applies to internal capability prompts, never to persona — the carve-out in the principles file is load-bearing, and flagging voice as waste is the one failure this lens exists to prevent. What you do flag, even inside persona-shaped files, is genuine repetition or contradiction: the same trait stated three times, a communication rule that fights an earlier one, or identity text copy-pasted into a capability prompt that already inherits it. That is waste because it adds no character, not because it carries voice.
+
+For a stateless agent the capability prompts live inline in SKILL.md and in `references/`. For a memory or autonomous agent they live in `references/`, and you additionally run the tests on the sanctum templates the build ships in `assets/` (PERSONA, CREED, BOND, MEMORY, CAPABILITIES, INDEX seeds), since those become runtime files and carry the same ceremony risk. The sanctum is the built agent's runtime memory, never the builder's process log, so you do not touch the memlog.
+
+Stay in this lane. Topology belongs to the architecture lens, intelligence placement to determinism, customize.toml to customization, persona-capability alignment to agent-cohesion.
+
+## Test 1: the core test
+
+Run the canon's core test over each load-bearing instruction in a capability prompt, truncating before deleting, and flagging a stripped why as under-writing rather than cutting further. The re-teach shapes that recur in agents:
+
+- Scoring formulas, calibration tables, and decision matrices for subjective judgment.
+- Format-the-output templates that teach markdown, greeting assembly, or response structure.
+- Defensive padding such as "make sure", "don't forget", and "remember to".
+- Meta-explanation describing the capability to itself, and negative space narrating what it no longer does.
+- Mechanics for a tool the model already drives fluently, and downstream mechanics living in the wrong file.
+- A capability prompt restating identity or communication style the persona already establishes (the repetition case, not the carve-out), or any fact restated across sections.
+
+## Test 2: defend against its own absence
+
+This operationalizes the canon's two-version comparison. For each capability prompt, name the concrete dimension on which the elaborate version produces a better output than a roughly five-line version of the same intent would — material and durable, showing up on real input and across runs. The five-line baseline holds the capability's role, outcome, consumer, and any scarred rule, and it inherits the agent's persona for free, so the comparison is fair.
+
+If you can name that dimension, the prompt earned its keep. If you cannot, flag it as ceremony and do the work that lets the parent settle it with a real run: write the smallest version into `proposed_smallest` and name what you predict would be lost (often nothing) in `predicted_delta`. The parent can route the finding to the eval-runner's variant mode for a cut-or-keep verdict; when you expect no loss, say so and add "route to variant eval to confirm". Never propose a smallest version that strips persona, because the persona is inherited, not part of the capability prompt's defendable surface.
+
+## Test 3: outcome vs prescription
+
+Apply the canon's number-only-true-sequences test to each numbered or rigid sequence inside a capability prompt. Decoration collapses to one goal sentence, which you put in the recommendation; order that guards a named failure stays.
+
+Also flag, as a yellow flag rather than a hard defect, ALL-CAPS ALWAYS/NEVER and stacked MUSTs inside capability prompts — the author shouting where reasoning would carry the rule — and recommend reframing the shout as the failure it protects against. Persona files that use emphatic voice on purpose are not this, so judge intent.
+
+## What you return
+
+Return per `references/lens-contract.md` with `"lens": "leanness"`, adding `proposed_smallest` and `predicted_delta` on Test 2 findings only.
+
+Severity guidance: a core-test re-teach of a few lines is usually low or medium, a whole ceremony capability prompt is high, and a numbered sequence that actively resists cutting because it reads as a real constraint is high. Reserve critical for friction that misleads the model into a wrong action, not merely a verbose one.

.agents/skills/bmad-agent-builder/references/scan-sanctum-architecture.md

@@ -0,0 +1,37 @@
+# Scan Lens: Sanctum Architecture (conditional)
+
+You validate the architecture of an agent's sanctum, the built agent's runtime memory that it reloads on every waking to become itself again, living at `{project-root}/_bmad/memory/{skillName}/`. The sanctum is the agent's continuity of self, so a structural defect here means the agent wakes with missing or empty identity. This is the only memory you judge. The builder's process log, the memlog written to `.memlog.md` beside SKILL.md while authoring, is a different thing and is not in scope for this lens.
+
+This lens is conditional. It runs only when the pre-pass reports `agent_type` in {memory, autonomous}. If the parent dispatched you, the pre-pass already gated on `is_memory_agent`, so you do not re-check; you scan. A stateless agent has no sanctum and this lens never runs for it.
+
+Load `references/agent-quality-principles.md` first. The sanctum dimensions, the bootloader-is-lean-by-design exception, and the two-memories discipline are the bar.
+
+You consume the pre-pass JSON the parent hands you (`agent_type`, `is_memory_agent`, `skill_md_tokens`, per-file token counts) and return finding JSON in-context. You do not write an analysis file. Use the pre-pass for structural facts and read raw files only for the judgment calls below.
+
+## Bootloader weight
+
+The bootloader SKILL.md is supposed to be small, around four hundred tokens as a guardrail rather than a gate. Judge it by what it carries, not by its weight, because a thin bootloader is the design working. It legitimately carries the identity seed, the Three Laws, the Sacred Truth, Stay in Character, the Persistent Memory directive, the mission, and the four-step activation routing. Flag content that belongs in the sanctum leaking into it: communication style, detailed principles, or a capability menu. Each leaked section is high, because that content belongs in PERSONA, CREED, or CAPABILITIES and a bootloader that carries it is a pruning failure. There is no separate session-close section to flag as leaked bloat: session close folds into the Persistent Memory directive (capture as you go plus a consolidating pass at close), and the detailed memory guidance loads on the first memory-touch, not in the bootloader. The identity seed should be two or three sentences of personality DNA, not a full identity section and not so short it has no character. The Three Laws and the Sacred Truth are foundational, so flag either as critical if missing.
+
+## Sanctum templates
+
+All six standard templates exist in assets: INDEX, PERSONA, CREED, BOND, MEMORY, CAPABILITIES. A missing template is critical, because the sanctum is incomplete on init. PERSONA, CREED, and BOND carry meaningful seeds rather than empty placeholders, and a generic or `{to be determined}` seed where real content belongs is high for CREED values and medium for BOND domain sections and the PERSONA style seed, because First Breath then has nothing domain-specific to fill. MEMORY starts empty because it fills at runtime, so flag it only if it carries fake seeded memories. For an autonomous agent a PULSE template must exist, and its absence is high because an autonomous agent without PULSE cannot do autonomous work. Replace any line-count ceiling you find in the templates with a token budget, because line counts are not the metric.
+
+## First Breath
+
+First Breath owns the scaffolding now: it opens with a Scaffold First step that runs init-sanctum.py, and the bootloader routes a no-sanctum activation to it. First Breath fills the seeds with living content the first time the agent wakes, and it comes in two styles. For the calibration style, check for pacing guidance so the conversation does not become an interrogation, voice-absorption guidance so the agent learns its communication style by listening, save-as-you-go so a cut-short conversation does not lose everything, domain-specific territory beyond the universal set so a creative agent and a code-review agent have different birth conversations, and the birthday ceremony where the naming moment creates identity. For the configuration style, check for three to seven domain-specific discovery questions, urgency detection so a burning owner need defers the questions, save-as-you-go, and the birthday ceremony. Missing pacing, voice absorption, save-as-you-go, or domain territory is high; a missing ceremony is medium. First Breath is runtime sanctum init, not a build-time config surface, so never recommend folding it into customize.toml.
+
+## CREED
+
+CREED carries the agent's values and its standing orders, and it reinforces the Sacred Truth on every waking load. Check that the values are real rather than generic, that the standing orders are domain-adapted with concrete examples rather than a bare "proactively add value," and that the two default standing orders (surprise-and-delight, self-improvement) are present. The canon pull-in standing order must be present so an evolving agent authors new capabilities to the current standard, and its absence is high for an evolvable agent because every capability it later writes will drift from the bar. Check that the mission in CREED is a placeholder filled during First Breath rather than pre-filled, because a pre-filled mission means First Breath cannot earn it.
+
+## Scripts
+
+Two scripts ship for a memory or autonomous agent. wake.py exists in the agent's scripts and loads the whole sanctum in one pass on every activation, so its absence is critical because the agent cannot wake. init-sanctum.py exists too, and its absence is critical because sanctum scaffolding is otherwise manual; First Breath owns the scaffolding step that runs it. For both, the skill name must match the skill's folder name, and a mismatch is critical because the sanctum reads or scaffolds into the wrong directory. init-sanctum.py's template list must match the templates actually shipped in assets, and a mismatch is high because init then misses sanctum files. The script should scan capability frontmatter so CAPABILITIES.md is populated, and its evolvable flag should match the evolvable-capabilities decision. After init runs the sanctum is self-contained, so flag any path that leaves the agent depending on the skill bundle for normal operation rather than only for First Breath and init.
+
+## Severity
+
+Missing Three Laws or Sacred Truth, a missing standard template, a missing wake.py or init-sanctum.py script, or a script skill-name mismatch is critical. A bootloader carrying sanctum-bound content, a generic mission, missing First Breath mechanics, a missing default or canon standing order, or a template-list mismatch is high. Generic standing orders, a BOND without domain sections, or a CREED missing its dominion boundaries is medium. Style refinements and anti-pattern categorization are low.
+
+## What you return
+
+Return per `references/lens-contract.md` with `"lens": "sanctum-architecture"`. The verdict says whether the sanctum is complete, consistent, and seeded.

.agents/skills/bmad-agent-builder/references/script-opportunities-reference.md

@@ -0,0 +1,57 @@
+# Script Opportunities Reference
+
+Hunting for deterministic work to push out of prompts and into native Python is the builder's differentiator. A capability prompt that asks the model to count, parse, validate, or diff is paying generation cost on every run for an answer a script gives once, exactly, for free. The hunt is always on, not a finalize-time afterthought.
+
+This file covers the determinism test that decides script-or-prompt, the signal-verb scan that surfaces candidates inside a draft, the opportunity categories, the pre-pass JSON pattern, and the transcript-detected repeated-work signal that eval runs expose. Reference `references/script-standards.md` for the full authoring conventions (PEP 723, output schema, testing).
+
+## The line that decides it
+
+Scripts handle deterministic operations. Prompts handle judgment. If a check has clear pass/fail criteria and the same input always yields the same output, it belongs in a script, and a prompt that does it instead is friction that does not beat its own absence.
+
+## The determinism test
+
+Run three questions over any step you are about to write as a prompt instruction:
+
+1. Given identical input, will it always produce identical output? If yes, it is a script candidate.
+2. Could you write a unit test with an expected output? If yes, it is definitely a script.
+3. Does it require interpreting meaning, tone, or context? If yes, keep it as a prompt.
+
+The boundary between the two:
+
+| Scripts handle | Prompts handle |
+| --- | --- |
+| Fetch, transform, validate | Interpret, classify when ambiguous |
+| Count, parse, compare | Create, decide on incomplete info |
+| Extract, format, check structure | Evaluate quality, synthesize meaning |
+
+## The signal-verb scan
+
+When a draft's instructions contain these verbs, look for a script first: validate, count, extract, convert, transform, compare, scan for, check structure, against schema, graph or map dependencies, list all, detect pattern, diff or changes between. Each one names work that produces the same answer every time, so paying a model to do it is waste.
+
+## Opportunity categories
+
+| Category | What it does | Example |
+| --- | --- | --- |
+| Validation | Check structure, format, schema, naming | Confirm frontmatter fields exist |
+| Data extraction | Pull structured data without interpreting meaning | Extract every `{variable}` reference from markdown |
+| Transformation | Convert between known formats | Template emission via process-template.py |
+| Metrics | Count, tally, aggregate | Token count per file via count_tokens.py |
+| Comparison | Diff, cross-reference, verify consistency | Cross-ref capability names against the routing table |
+| Structure checks | Verify directory layout, file existence | Confirm a sanctum ships its six templates |
+| Dependency analysis | Trace references, imports, relationships | Build a capability reference graph |
+| Pre-processing | Extract compact data from large files before the model reads them | Pre-extract file metrics into JSON for a lens |
+| Post-processing | Verify model output meets structural requirements | Confirm an emitted template carries no leftover `{if-...}` markers |
+
+## The pre-pass JSON pattern
+
+When a flow would otherwise have the model read raw files to gather facts (token counts, frontmatter values, file inventories, agent-type classification), write a pre-pass script that does the reading and emits compact JSON, then have the prompt consume the JSON instead. The model reasons over metrics rather than burning context on raw bytes, the facts are exact rather than estimated, and the stage runs cheaper. The Analyze lenses use this pattern: `scripts/prepass.py` and the lint scanners run first and hand each lens compact JSON, so the lenses read numbers, not whole files.
+
+## The transcript-detected repeated-work signal
+
+The eval-runner produces transcripts when an agent runs on real input. Read them for the same helper being re-derived run after run. If the model writes a small parser, a counter, a format converter, or a validation snippet inline on turn after turn, that work is deterministic by definition (it produces the same code each time) and it is paying generation cost every run. Bundle it once as a script the agent calls, and the repeated inline derivation disappears.
+
+This is the strongest possible evidence for a script, because it is not a guess about what the model might do, it is the model demonstrably doing the same deterministic thing repeatedly. When an eval run shows this pattern, the recommendation is a named script, and the next eval run should show the inline derivation gone.
+
+## Authoring the script
+
+Once a candidate is confirmed, `references/script-standards.md` owns how to write it: native Python over bash, stdlib-first, PEP 723 metadata, `uv run` for declared dependencies, a graceful fallback when an optional dependency's import is unavailable, and the `--help`/output/exit-code/testing checklist. One tip worth carrying into the prompt: point it at `scripts/foo.py --help` instead of inlining the interface, so the interface stays defined once and the prompt stays short.

.agents/skills/bmad-agent-builder/references/script-standards.md

@@ -0,0 +1,91 @@
+# Script Creation Standards
+
+When building scripts for a skill, follow these standards to ensure portability and zero-friction execution. Skills must work across macOS, Linux, and Windows (native, Git Bash, and WSL).
+
+## Python Over Bash
+
+**Always favor Python for script logic.** Bash is not portable — it fails or behaves inconsistently on Windows (Git Bash is MSYS2-based, not a full Linux shell; WSL bash can conflict with Git Bash on PATH; PowerShell is a different language entirely). Python with `uv run` works identically on all platforms.
+
+**Safe bash commands** — these work reliably across all environments and are fine to use directly:
+
+- `git`, `gh` — version control and GitHub CLI
+- `uv run` — Python script execution with automatic dependency handling
+- `npm`, `npx`, `pnpm` — Node.js ecosystem
+- `mkdir -p` — directory creation
+
+**Everything else should be Python** — piping, `jq`, `grep`, `sed`, `awk`, `find`, `diff`, `wc`, and any non-trivial logic. Even `sed -i` behaves differently on macOS vs Linux. If it's more than a single safe command, write a Python script.
+
+## Favor the Standard Library
+
+Always prefer Python's standard library over external dependencies. The stdlib is pre-installed everywhere, requires no `uv run`, and has zero supply-chain risk. Common stdlib modules that cover most script needs:
+
+- `json` — JSON parsing and output
+- `pathlib` — cross-platform path handling
+- `re` — pattern matching
+- `argparse` — CLI interface
+- `collections` — counters, defaultdicts
+- `difflib` — text comparison
+- `ast` — Python source analysis
+- `csv`, `xml.etree` — data formats
+
+Only pull in external dependencies when the stdlib genuinely cannot do the job (e.g., `tiktoken` for accurate token counting, `pyyaml` for YAML parsing, `jsonschema` for schema validation). **External dependencies must be confirmed with the user during the build process** — they add install-time cost, supply-chain surface, and require `uv` to be available.
+
+## PEP 723 Inline Metadata (Required)
+
+Every Python script MUST include a PEP 723 metadata block. For scripts with external dependencies, use the `uv run` shebang:
+
+```python
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.10"
+# dependencies = ["pyyaml>=6.0", "jsonschema>=4.0"]
+# ///
+```
+
+For scripts using only the standard library, use a plain Python shebang but still include the metadata block:
+
+```python
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.10"
+# ///
+```
+
+**Key rules:**
+
+- The shebang MUST be line 1 — before the metadata block
+- Always include `requires-python`
+- List all external dependencies with version constraints
+- Never use `requirements.txt`, `pip install`, or expect global package installs
+- The shebang is a Unix convenience — cross-platform invocation relies on `uv run scripts/foo.py`, not direct shebang execution
+
+## Invocation in SKILL.md
+
+How a built skill's SKILL.md should reference its scripts (bare path from the skill root, per the path conventions):
+
+- **All scripts:** `uv run scripts/foo.py {args}` — consistent invocation regardless of whether the script has external dependencies
+
+`uv run` reads the PEP 723 metadata, silently caches dependencies in an isolated environment, and runs the script — no user prompt, no global install. Like `npx` for Python.
+
+## Graceful Degradation
+
+Skills may run in environments where Python or `uv` is unavailable (e.g., claude.ai web). Scripts should be the fast, reliable path — but the skill must still deliver its outcome when execution is not possible.
+
+**Pattern:** When a script cannot execute, the LLM performs the equivalent work directly. The script's `--help` documents what it checks, making this fallback natural. Design scripts so their logic is understandable from their help output and the skill's context.
+
+In SKILL.md, frame script steps as outcomes, not just commands:
+
+- Good: "Validate path conventions (run `scripts/scan-paths.py --help` for details)"
+- Avoid: "Execute `uv run scripts/scan-paths.py`" with no context about what it does
+
+## Script Interface Standards
+
+- Implement `--help` via `argparse` (single source of truth for the script's API)
+- Accept target path as a positional argument
+- `-o` flag for output file (default to stdout)
+- Diagnostics and progress to stderr
+- Exit codes: 0=pass, 1=fail, 2=error
+- `--verbose` flag for debugging
+- Output valid JSON to stdout
+- No interactive prompts, no network dependencies
+- Tests in `scripts/tests/`

.agents/skills/bmad-agent-builder/references/standard-fields.md

@@ -0,0 +1,170 @@
+# Standard Agent Fields
+
+## Frontmatter Fields
+
+Only these fields go in the YAML frontmatter block:
+
+| Field         | Description                                       | Example                                         |
+| ------------- | ------------------------------------------------- | ----------------------------------------------- |
+| `name`        | Full skill name (kebab-case, same as folder name) | `agent-tech-writer`, `cis-agent-lila` |
+| `description` | [What it does]. [Use when user says 'X' or 'Y'.]  | See Description Format below                    |
+
+## Content Fields
+
+These are used within the SKILL.md body — never in frontmatter:
+
+| Field         | Description                              | Example                              |
+| ------------- | ---------------------------------------- | ------------------------------------ |
+| `displayName` | Friendly name (title heading, greetings) | `Paige`, `Lila`, `Floyd`             |
+| `title`       | Role title                               | `Tech Writer`, `Holodeck Operator`   |
+| `icon`        | Single emoji                             | `🔥`, `🌟`                           |
+| `role`        | Functional role                          | `Technical Documentation Specialist` |
+| `memory`      | Memory folder (optional)                 | `{skillName}/`                       |
+
+### Memory Agent Fields (bootloader SKILL.md only)
+
+These fields appear in memory agent SKILL.md files, which use a lean bootloader structure instead of the full stateless layout:
+
+| Field              | Description                                              | Example                                                            |
+| ------------------ | -------------------------------------------------------- | ------------------------------------------------------------------ |
+| `identity-seed`    | 2-3 sentence personality DNA (expands in PERSONA.md)     | "Equal parts provocateur and collaborator..."                      |
+| `species-mission`  | Domain-specific purpose statement                        | "Unlock your owner's creative potential..."                        |
+| `agent-type`       | One of: `stateless`, `memory`, `autonomous`              | `memory`                                                           |
+| `onboarding-style` | First Breath style: `calibration` or `configuration`     | `calibration`                                                      |
+| `sanctum-location` | Path to sanctum folder                                   | `{project-root}/_bmad/memory/{skillName}/`                         |
+
+### Sanctum Template Seed Fields (CREED, BOND, PERSONA templates)
+
+These are content blocks the builder fills when emitting the sanctum templates. They are NOT template variables for init-script substitution — they are baked into the agent's template files as real content.
+
+| Field                       | Destination Template    | Description                                                  |
+| --------------------------- | ----------------------- | ------------------------------------------------------------ |
+| `core-values`               | CREED-template.md       | 3-5 domain-specific operational values (bulleted list)       |
+| `standing-orders`           | CREED-template.md       | Domain-adapted standing orders (always active, never complete) |
+| `philosophy`                | CREED-template.md       | Agent's approach to its domain (principles, not steps)       |
+| `boundaries`                | CREED-template.md       | Behavioral guardrails                                        |
+| `anti-patterns-behavioral`  | CREED-template.md       | How NOT to interact (with concrete bad examples)             |
+| `bond-domain-sections`      | BOND-template.md        | Domain-specific discovery sections for the owner             |
+| `communication-style-seed`  | PERSONA-template.md     | Initial personality expression seed                          |
+| `vibe-prompt`               | PERSONA-template.md     | Prompt for vibe discovery during First Breath                |
+
+## Customization Surface (`customize.toml`)
+
+Every agent ships a `customize.toml` alongside SKILL.md. The file has two parts: a metadata block that is always emitted, and an override surface that is emitted only when the author opted in during build.
+
+### Metadata block (always present)
+
+Consumed by the installer to populate `module.yaml:agents[]` and the central config's `[agents.<code>]` section. Required for every agent regardless of archetype.
+
+| Field         | Type   | Required | Notes                                                                 |
+| ------------- | ------ | -------- | --------------------------------------------------------------------- |
+| `code`        | string | yes      | Stable identifier. Matches skill directory basename (no module prefix). |
+| `name`        | string | optional | Display name. Empty string is valid for First-Breath-named agents.    |
+| `title`       | string | yes      | Role title. Always fillable at build time.                            |
+| `icon`        | string | yes      | Single emoji.                                                         |
+| `description` | string | yes      | One-sentence summary of what the agent does.                          |
+| `agent_type`  | string | yes      | One of `stateless`, `memory`, `autonomous`.                           |
+
+**First-Breath-named agents:** leave `name = ""` at build time. The owner fills it post-activation in `{project-root}/_bmad/custom/config.toml`:
+
+```toml
+[agents.<code>]
+name = "..."
+```
+
+UIs tolerate empty `name` and fall back to `title`.
+
+### Override surface (emitted only when opted in)
+
+Loaded via `{project-root}/_bmad/scripts/resolve_customization.py` at activation. Skip entirely for agents that did not opt in to customization.
+
+| Field                      | Type          | Purpose                                                        |
+| -------------------------- | ------------- | -------------------------------------------------------------- |
+| `activation_steps_prepend` | array[string] | Steps run before standard activation. Overrides append.        |
+| `activation_steps_append`  | array[string] | Steps run after greet, before user input. Overrides append.    |
+| `persistent_facts`         | array[string] | Facts (literal or `file:` prefixed). Overrides append.         |
+
+### Agent-specific scalars (lifted during Configurability Discovery)
+
+Named by purpose and suffix. Override wins (scalar merge rule).
+
+| Naming pattern          | Use for                                       | Example                                          |
+| ----------------------- | --------------------------------------------- | ------------------------------------------------ |
+| `<purpose>_template`    | File paths for templates the agent loads      | `style_guide_template = "resources/style.md"`    |
+| `<purpose>_output_path` | Writable destinations                         | `report_output_path = "{project-root}/reports"`  |
+| `on_<event>`            | Prompt or command executed at a hook point    | `on_session_close = ""`                          |
+
+**Path resolution within scalar values:**
+
+- Bare paths (e.g. `resources/style.md`) resolve from the skill root.
+- `{project-root}/...` resolves from the project working directory — use for org-owned overrides.
+- Config variables are used directly (they already contain `{project-root}`) — no double-prefix.
+
+### How SKILL.md references the resolved values
+
+After the resolver step runs, read customized values as `{agent.<name>}`:
+
+```markdown
+Load the style guide from `{agent.style_guide_template}`.
+```
+
+### Override files
+
+Teams and users override without editing `customize.toml`:
+
+- Team: `{project-root}/_bmad/custom/{skill-name}.toml`
+- Personal: `{project-root}/_bmad/custom/{skill-name}.user.toml`
+
+Both use the same `[agent]` block shape. Merge order: base (skill's `customize.toml`) → team → user.
+
+The archetype defaults for when to emit the override surface at all live in `references/agent-quality-principles.md`.
+
+## Overview Section Format
+
+The Overview is the first section after the title — it primes the AI for everything that follows. Cover what the agent does, how it works (role, approach, modes), and the outcome it delivers, written as the agent's own destination rather than a description of the system.
+
+## SKILL.md Description Format
+
+```
+{description of what the agent does}. Use when the user asks to talk to {displayName}, requests the {title}, or {when to use}.
+```
+
+## Path Rules
+
+### Same-Folder References
+
+Use `./` only when referencing a file in the same directory as the file containing the reference:
+
+- From `references/build-process.md` → `./some-guide.md` (both in references/)
+- From `scripts/scan.py` → `./utils.py` (both in scripts/)
+
+### Cross-Directory References
+
+Use bare paths relative to the skill root — no `./` prefix:
+
+- `references/memory-system.md`
+- `scripts/calculate-metrics.py`
+- `assets/template.md`
+
+These work from any file in the skill because they're always resolved from the skill root. **Never use `./` for cross-directory paths** — writing `./` before `scripts/foo.py` in a file that lives in `references/` is misleading because `scripts/` is not next to that file.
+
+### Memory Files
+
+Always use `{project-root}` prefix: `{project-root}/_bmad/memory/{skillName}/`
+
+The memory `index.md` is the single entry point to the agent's memory system — it tells the agent what else to load (boundaries, logs, references, etc.). Load it once on activation; don't duplicate load instructions for individual memory files.
+
+### Project-Scope Paths
+
+Use `{project-root}/...` for any path relative to the project root:
+
+- `{project-root}/_bmad/planning/prd.md`
+- `{project-root}/docs/report.md`
+
+### Config Variables
+
+Use directly — they already contain `{project-root}` in their resolved values:
+
+- `{output_folder}/file.md`
+- Correct: `{bmad_builder_output_folder}/agent.md`
+- Wrong: prefixing the same value with `{project-root}` again (double-prefix)

.agents/skills/bmad-agent-builder/references/standing-order-guidance.md

@@ -0,0 +1,87 @@
+# Standing Order Guidance
+
+Use this when gathering CREED seeds, specifically the standing orders section.
+
+## What Standing Orders Are
+
+Standing orders are always active. They never complete. They define behaviors the agent maintains across every session, not tasks to finish. They live in CREED.md and shape how the agent operates at all times. Because they live in CREED, they survive each waking: the agent reloads its sanctum, finds these orders, and resumes holding them — one continuous self, not a new one each session.
+
+Every memory agent gets three default standing orders. The first two are domain-adapted by the builder. The third is the canon pull-in, which ships in a fixed form. Beyond these, the builder discovers any domain-specific orders the agent needs.
+
+## Default Standing Orders
+
+### Surprise and Delight
+
+The agent proactively adds value beyond what was asked. This is not about being overly eager. It's about noticing opportunities the owner didn't ask for but would appreciate.
+
+**The generic version (don't use this as-is):**
+> Proactively add value beyond what was asked.
+
+**The builder must domain-adapt it.** The adaptation answers: "What does surprise-and-delight look like in THIS domain?"
+
+| Agent Domain | Domain-Adapted Version |
+|-------------|----------------------|
+| Dream analyst | Proactively add value beyond what was asked. Notice dream pattern connections across weeks. Surface a recurring symbol the owner hasn't recognized. Connect a dream theme to something they mentioned in waking life. |
+| Code review agent | Proactively add value beyond what was asked. Notice architectural patterns forming across PRs. Flag a design trend before it becomes technical debt. Suggest a refactor when you see the same workaround for the third time. |
+| Writing editor | Proactively add value beyond what was asked. Notice when a piece is trying to be two pieces. Surface a structural option the writer didn't consider. Flag when the opening buries the real hook. |
+
+### Self-Improvement
+
+The agent refines its own capabilities and approach based on what works and what doesn't.
+
+**The generic version (don't use this as-is):**
+> Refine your capabilities and approach based on experience.
+
+**The builder must domain-adapt it.** The adaptation answers: "What does getting better look like in THIS domain?"
+
+| Agent Domain | Domain-Adapted Version |
+|-------------|----------------------|
+| Dream analyst | Refine your interpretation frameworks. Track which approaches produce insight and which produce confusion. Build your understanding of this dreamer's unique symbol vocabulary. |
+| Code review agent | Refine your review patterns. Track which findings the owner acts on and which they dismiss. Calibrate severity to match their priorities. Learn their codebase's idioms. |
+
+### Author to the Standard (the canon pull-in)
+
+This third default is the mechanism that keeps an evolving agent lean as it grows. Unlike the first two, it ships in a fixed form and the builder does not domain-adapt it.
+
+**The shipped form:**
+> Author to the standard. Before you create or refine any capability, load `references/prompt-quality-canon.md` and hold its tests while you author. Otherwise do not load it.
+
+How the pull-in works and why it is built this way:
+
+- The order fires at exactly one moment, when a capability is being authored or refined, which is the only moment the canon's tests apply. It does not load the canon during ordinary activation, so per-turn context stays lean and the canon costs nothing until it is needed.
+- The shipped copy resolves from the agent's own root, works offline, and is pinned to the version of the canon the agent was built with.
+- The canon itself is never copied into CREED, INDEX, or CAPABILITIES. Only this thin pointer threads through them. The authority stays in one place and the agent pulls it on demand, which is what keeps an agent that has grown dozens of capabilities from carrying a stale, drifting fork of the quality bar.
+
+The capability-authoring reference opens with the canon's working essence and carries the mechanics of creating a capability; for the full tests it points at the same shipped copy rather than restating them.
+
+## Discovering Domain-Specific Standing Orders
+
+Beyond the three defaults, some agents need standing orders unique to their domain. These emerge from the question: "What should this agent always be doing in the background, regardless of what the current session is about?"
+
+**Discovery questions to ask:**
+1. "Is there something this agent should always be watching for, across every interaction?"
+2. "Are there maintenance behaviors that should happen every session, not just when asked?"
+3. "Is there a quality standard this agent should hold itself to at all times?"
+
+**Examples of domain-specific standing orders:**
+
+| Agent Domain | Standing Order | Why |
+|-------------|---------------|-----|
+| Dream analyst | **Pattern vigilance** — Track symbols, themes, and emotional tones across sessions. When a pattern spans 3+ dreams, surface it. | Dream patterns are invisible session-by-session. The agent's persistence is its unique advantage. |
+| Fitness coach | **Consistency advocacy** — Gently hold the owner accountable. Notice gaps in routine. Celebrate streaks. Never shame, always encourage. | Consistency is the hardest part of fitness. The agent's memory makes it a natural accountability partner. |
+| Writing editor | **Voice protection** — Learn the writer's voice and defend it. Flag when edits risk flattening their distinctive style into generic prose. | Editors can accidentally homogenize voice. This standing order makes the agent a voice guardian. |
+
+## Writing Good Standing Orders
+
+- Start with an action verb in bold ("**Surprise and delight**", "**Pattern vigilance**")
+- Follow with a concrete description of the behavior, not an abstract principle
+- Include a domain-specific example of what it looks like in practice
+- Keep each to 2-3 sentences maximum
+- Standing orders should be testable: could you look at a session log and tell whether the agent followed this order?
+
+## What Standing Orders Are NOT
+
+- They are not capabilities (standing orders are behavioral, capabilities are functional)
+- They are not one-time tasks (they never complete)
+- They are not personality traits (those go in PERSONA.md)
+- They are not boundaries (those go in the Boundaries section of CREED.md)

.agents/skills/bmad-agent-builder/references/template-substitution-rules.md

@@ -0,0 +1,51 @@
+# Template Substitution Rules
+
+The SKILL-template provides a minimal skeleton: frontmatter, overview, agent identity sections, memory, and the activation spine. The bootloader carries no standalone config-load step — `init-sanctum` bakes config into the sanctum, so wake.py loads it as part of the identity. Everything beyond the skeleton is crafted by the builder based on what was learned during discovery. Apply these rules deterministically via `uv run scripts/process-template.py <template> -o <dest> --var key=value... --true <condition>...` — one `--var` per token, one `--true` per conditional that holds. The script fails (exit 3) on any leftover `{if-...}` marker and reports remaining `{token}` placeholders as `tokens_remaining` for you to judge against the runtime-token set.
+
+## Frontmatter
+
+- `{module-code-or-empty}` → Module code prefix with hyphen (e.g., `cis-`) or empty for standalone. The `bmad-` prefix is reserved for official BMad creations; user agents should not include it.
+- `{agent-name}` → Agent functional name (kebab-case)
+- `{skill-description}` → Two parts: [4-6 word summary]. [trigger phrases]
+- `{displayName}` → Friendly display name
+- `{skillName}` → Full skill name with module prefix
+
+## Conditionals
+
+A `--true` condition keeps the block's content (markers stripped); anything else removes the whole block including markers.
+
+- `{if-module}` / `{if-standalone}` → module-based vs standalone agent
+- `{if-memory-agent}` / `{if-stateless-agent}` → memory and autonomous agents vs stateless
+- `{if-evolvable}` → the owner can teach the agent new capabilities
+- `{if-pulse}` → autonomous mode (PULSE enabled)
+- `{if-customizable}` → the author opted in to the override surface
+
+Module tokens, filled when `{if-module}` holds: `{module-code}` (no trailing hyphen, e.g. `cis`) and `{module-setup-skill}` (e.g. `cis-setup`).
+
+## Template Selection
+
+- **Stateless agent:** `assets/SKILL-template.md` (full identity, no Three Laws/Sacred Truth)
+- **Memory/autonomous agent:** `assets/SKILL-template-bootloader.md` (lean bootloader with Three Laws, Sacred Truth, Stay in Character, the Persistent Memory directive, and the four-step "Invoke & hold" activation spine)
+
+The activation is a fixed four-step spine, not a set of renumbered paths: (1) Wake via `scripts/wake.py`; (2) Become yourself; (3) Bind the standing rules; (4) Execute the Proper Mode. The Mode in step 4 is what varies — Waking and First Breath are always present; only Pulse Mode is conditional, wrapped in `{if-pulse}` for autonomous agents. The step numbers never shift, so there is no gap to renumber; keep `{if-pulse}` strictly around the Pulse Mode bullet.
+
+## Customize.toml Emission
+
+Every agent ships `customize.toml` alongside SKILL.md, from `assets/customize-template.toml`. Fill the `[agent]` metadata block from the metadata gathered during discovery:
+
+- `{agent-code}` → stable identifier (skill dir basename without module prefix)
+- `{agent-name-or-empty}` → display name, or empty string for First-Breath-named agents
+- `{agent-title}` → role title
+- `{agent-icon}` → single emoji
+- `{agent-description}` → one-sentence description
+- `{agent-type}` → `stateless` | `memory` | `autonomous`
+
+When `{if-customizable}` holds, also add the resolver step to SKILL.md and reference lifted scalars as `{agent.<name>}` in the SKILL.md body — these resolve at runtime, so emit them verbatim. When it does not hold, `customize.toml` ships metadata-only and SKILL.md uses hardcoded paths with no resolver step.
+
+## Beyond the Template
+
+The builder determines the rest of the agent structure — capabilities, activation flow, sanctum templates, init script, First Breath, capability routing, external skills, scripts — based on the agent's requirements. The template intentionally does not prescribe these.
+
+## Path References
+
+Everything the builder emits follows the bare-path convention the lint gate enforces: skill-internal paths are written bare from the skill root (`references/first-breath.md`, `scripts/wake.py`, `scripts/init-sanctum.py`, `assets/PERSONA-template.md`), `./` appears only for a file in the same directory as the file referencing it, and project-scope paths carry `{project-root}/`. This applies equally to SKILL.md, capability prompts, the sanctum templates the init script copies, and the emitted `scripts/wake.py` (from `assets/wake-template.py`, parameterized with the agent's `{skillName}`).