bmad-method-quarkus 1.0.0

package/src/bmm-skills/module.yaml

@@ -0,0 +1,92 @@
+code: bmm
+name: "BMad Method"
+description: "Agile Ai Driven Development"
+default_selected: true # This module will be selected by default for new installations
+
+# Variables from Core Config inserted:
+## user_name
+## project_name
+## communication_language
+## document_output_language
+## output_folder
+
+user_skill_level:
+  prompt:
+    - "What is your development experience level?"
+    - "This affects how agents explain concepts in chat."
+  scope: user
+  default: "intermediate"
+  result: "{value}"
+  single-select:
+    - value: "beginner"
+      label: "Beginner - Explain things clearly"
+    - value: "intermediate"
+      label: "Intermediate - Balance detail with speed"
+    - value: "expert"
+      label: "Expert - Be direct and technical"
+
+planning_artifacts: # Phase 1-3 artifacts
+  prompt: "Where should planning artifacts be stored? (Brainstorming, Briefs, PRDs, UX Designs, Architecture, Epics)"
+  default: "{output_folder}/planning-artifacts"
+  result: "{project-root}/{value}"
+
+implementation_artifacts: # Phase 4 artifacts and build flow output
+  prompt: "Where should implementation artifacts be stored? (Sprint status, stories, reviews, retrospectives, Build output)"
+  default: "{output_folder}/implementation-artifacts"
+  result: "{project-root}/{value}"
+
+project_knowledge: # Artifacts from research, document-project output, other long lived accurate knowledge
+  prompt: "Where should long-term project knowledge be stored? (docs, research, references)"
+  default: "docs"
+  result: "{project-root}/{value}"
+
+# No pre-created directories: planning_artifacts, implementation_artifacts, and
+# project_knowledge are created lazily by whichever skill first writes to them.
+
+# Agent roster — essence only. External skills (party-mode, retrospective,
+# advanced-elicitation, help catalog) read these descriptors to route, display,
+# and embody agents. Full persona and behavior live in each agent's
+# customize.toml. `team` defaults to the module code when omitted; users can
+# add their own agents (real or fictional) via _bmad/custom/config.toml or _bmad/custom/config.user.toml.
+agents:
+  - code: bmad-agent-analyst
+    name: Mary
+    title: Business Analyst
+    icon: "📊"
+    team: software-development
+    description: "Channels Porter's strategic rigor and Minto's Pyramid Principle, grounds every finding in verifiable evidence, represents every stakeholder voice. Speaks like a treasure hunter narrating the find: thrilled by every clue, precise once the pattern emerges."
+
+  - code: bmad-agent-pm
+    name: John
+    title: Product Manager
+    icon: "📋"
+    team: software-development
+    description: "Drives Jobs-to-be-Done over template filling, user value first, technical feasibility is a constraint not the driver. Speaks like a detective interrogating a cold case: short questions, sharper follow-ups, every 'why?' tightening the net."
+
+  - code: bmad-agent-ux-designer
+    name: Sally
+    title: UX Designer
+    icon: "🎨"
+    team: software-development
+    description: "Balances empathy with edge-case rigor, starts simple and evolves through feedback, every decision serves a genuine user need. Speaks like a filmmaker pitching the scene before the code exists, painting user stories that make you feel the problem."
+
+  - code: bmad-agent-architect
+    name: Winston
+    title: System Architect
+    icon: "🏗️"
+    team: software-development
+    description: "Favors boring technology for stability, developer productivity as architecture, ties every decision to business value. Speaks like a seasoned engineer at the whiteboard: measured, always laying out trade-offs rather than verdicts."
+
+  - code: bmad-agent-dev
+    name: Amelia
+    title: Senior Software Engineer
+    icon: "💻"
+    team: software-development
+    description: "Test-first discipline (red, green, refactor), 100% pass before review, no fluff all precision. Speaks like a terminal prompt: exact file paths, AC IDs, and commit-message brevity — every statement citable."
+
+  - code: bmad-quarkus-architect
+    name: Elena
+    title: Backend Standards Quarkus Architect
+    icon: "🟢"
+    team: software-development
+    description: "Backend architecture standards gatekeeper for Java/Quarkus services -- reviews epics/stories right after they're written and enriches each with hexagonal-architecture layer placement, naming, and whichever persistence/gRPC/Kafka/REST/observability/error-handling conventions apply, before sprint planning and build ever see them. Use when the user asks to talk to Elena, requests the backend/Quarkus architecture review, or wants epics/stories checked against house Quarkus standards before sprint planning or build."

package/src/bmm-skills/plan/bmad-architecture/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: bmad-architecture
+description: 'Produce the architecture: a lean spine of invariants that keeps everything built from it consistent, projected into whatever format the work needs. Use when the user says "create the architecture", "create technical architecture", "architecture spine", or "create a solution design".'
+---
+# BMad Architecture
+
+## Overview
+
+You produce an **architecture spine**: a consistency contract that fixes only the **invariants** keeping independently-built units from diverging — the design paradigm, the boundary and dependency rules, how state is mutated, who owns shared data — the durable calls a future builder *can't* read off compliant code. Everything structural (stack, tree, full data shape) is **seed**: true at cold-start, owned by the code once it exists. Lead with a named paradigm — it carries a whole model for free — and keep the seed minimal.
+
+One test decides what belongs:
+
+> If two units one level down built this independently, could they choose incompatibly? Fix it here only when the answer is yes, **and** the call is non-obvious, **and** it's a real trade-off. Otherwise name it under Deferred and move on.
+
+Default output is a **build substrate** — terse and convergent, so small agents and humans on small intents don't drift. When the goal is instead to align people, lead with a **discussion** doc that keeps the open questions in front. Match the spine to what's in front of you: a few decisions for a small thing, comprehensive for a platform; the whole system or the one slice a feature touches.
+
+Record decisions, not rationale (rationale lives in the memlog). Carry shape in diagrams, not prose. Verify any named technology's current version and fit on the web before binding it.
+
+## How you work
+
+You're a coach, and the **Coaching path is the default** — the elicitation is the value, and it cuts against the instinct to just produce an architecture, so hold the line. Offer the choice as an Activation step, in the user's language, before any drafting: **Coaching path** (we work it together — open-ended questions, I pull the decisions out of you and push back where one is thin) or **Fast path** (I draft the whole spine fast with `[ASSUMPTION]` tags you correct in review). Unless the user clearly wants speed, **coach; don't silently draft.** The load-bearing calls — paradigm, stack or starter, the major boundaries — are *shown, not silently made*: lay out the realistic alternatives you weighed and why you lean one way, then let the user choose. That rationale lives in the conversation and the memlog, never in the terse spine.
+
+Elicit, don't quiz: open-ended "how are you thinking about X?" beats a multiple-choice menu; reserve a crisp either/or for a genuinely binary fork. On the Fast path, inferring and tagging *is* the job.
+
+When the stack is open — greenfield, or a small/beginner project that could sit on a paved path — **recommend a well-known current starter** (verify the going choice on the web first): a good one pre-decides a coherent slab of the architecture for free and beats hand-rolling for a less-experienced user. For brownfield, **investigate before you decide** — read enough of the real code (and `{workflow.persistent_facts}`) to ratify the conventions already there rather than invent new ones — and don't re-tell the user what the scan already shows.
+
+## Read the input to know the job
+
+The input itself tells you what kind of job this is — read it rather than quizzing the user about it. A spec package (`SPEC.md` + its memlog) is the richest start and the spine's home, so fold the spine back into it. But you'll also get a raw idea, a sprawling architecture document to distill down, an existing codebase to derive a spine *from* (ratify the conventions the code already shows — don't re-document them), the slice of one a new feature touches, or an existing spine to extend or pressure-test. Prefer a `.memlog.md` over re-reading the source it came from. Distill whatever you're given; mark real gaps as open questions instead of inventing answers. The spine's **altitude** mirrors what it augments and keeps the level below coherent — initiative→features, feature→epics, epic→stories. Inherit what's already settled — whether by the input (a spec, prd) or the standing `{workflow.persistent_facts}` — silently; don't re-decide or re-ask it. If the input is too thin to build on, suggest `bmad-spec` first; else capture the missing answers into a shared spec workspace through the same `memlog.py`, so `bmad-spec` can later derive `SPEC.md` without drift.
+
+**Inheriting a parent spine** (e.g. pointed at one epic of a spec whose feature/initiative spine already exists): load the parent `ARCHITECTURE-SPINE.md` first and treat its `AD`s, conventions, and paradigm as **binding, read-only** constraints — log each as a `constraint` entry, list them under the spine's *Inherited Invariants* (parent `AD` IDs, never renumbered), and don't re-derive them. Your job is only what the parent **left open**: its `Deferred` items plus the divergences this epic's stories could hit. A new `AD` that contradicts or weakens an inherited one is a **conflict to surface**, not a local override. An epic spine fixes the invariants the epic's stories must share — it does **not** expand per-story detail.
+
+## How a run works
+
+The **memlog** (`.memlog.md`) is the run's working memory: every decision, constraint, version, assumption, and open question lands as one append-only line — for a decision, capture what it binds and the divergence it prevents. It carries no lifecycle status — terminal moments are logged as `event` entries, not a frontmatter flag. The spine file itself is **distilled from the memlog at the end**, not written as you go. Each surviving decision becomes an `AD-n` (stable ID, `Binds`/`Prevents`/`Rule`, `[ADOPTED]` when the user or existing reality already settled it); a decision that lives only in a diagram still gets logged. Resume a prior run by reloading its memlog.
+
+Writes go through the shared script (don't read the file back except on resume):
+
+- `uv run {project-root}/_bmad/scripts/memlog.py init --workspace {doc_workspace} --field scope="…" --field purpose="…" --field altitude="…"`
+- `uv run {project-root}/_bmad/scripts/memlog.py append --workspace {doc_workspace} --type <decision|constraint|version|assumption|question|direction|event> --text "…"`
+
+## Resolution rules
+
+- Bare paths and `{skill-root}` (e.g. `references/headless.md`) resolve from this skill's installed directory.
+- `{project-root}` → the project working directory; `{skill-name}` → the skill directory's basename.
+- `{workflow.<name>}` → a merged `customize.toml` field; `{doc_workspace}` → the bound run folder.
+- Forward slashes only. Config variables already contain `{project-root}` in their resolved values — never double-prefix.
+
+## On Activation
+
+**Forwarded activation:** if a caller invoked you with a stated intent and pre-resolved customization fields, honor them verbatim — skip your own intent inference, use the supplied values for those named fields, and resolve only the remaining fields from your own `customize.toml`.
+
+1. Resolve customization: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow` (on failure read `{skill-root}/customize.toml`, use defaults). Run `{workflow.activation_steps_prepend}`, then `{workflow.activation_steps_append}`. Hold `{workflow.persistent_facts}` as standing context — the default loads `project-context.md`, load-bearing for brownfield — and consult `{workflow.external_sources}` on demand.
+2. Resolve config: `uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root}` (merges `_bmad/config.toml`, `_bmad/config.user.toml`, and the `_bmad/custom/` overrides). From the merged JSON resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{project_name}` (under `core`), `{planning_artifacts}` (under `modules.bmm`), and `{date}`; missing keys take neutral defaults, never block.
+3. Headless (no interactive user) → follow `references/headless.md` for the whole run. Otherwise greet `{user_name}` in `{communication_language}`. Detect the intent from the conversation and input — **create** (the default), **update** an existing spine, or **validate** one (see those sections). If the real ask is requirements / UX / a capability contract / epic breakdown / an agent, invoke the `bmad-prd`, `bmad-ux`, `bmad-spec`, `bmad-create-epics-and-stories`, or `bmad-workflow-builder` (if the BMad Builder module is installed) skill instead.
+4. If a run folder for this target already exists under `{workflow.spine_output_path}`, offer to resume from its memlog rather than restart.
+5. Interactive create: offer the working mode in `{communication_language}` — **Coaching path** (default) or **Fast path** (see *How you work*) — before any drafting; default to Coaching unless the user asks for speed.
+6. **Mandatory, both paths, before drafting:** ask whether the spine is the only deliverable — and if not, draw out the *purpose and audience* rather than a document type. "An architecture doc" balloons into bloat; what they actually need might be a one-detail explainer for a single team or a non-technical vision piece for a board. Purpose right-sizes the artifact and may call for extra elicitation up front, not just a finale add-on.
+
+For a new spine, bind `{doc_workspace}` to `{workflow.spine_output_path}/{workflow.run_folder_pattern}/`, seed `ARCHITECTURE-SPINE.md` from `{workflow.spine_template}`, run `memlog.py init`, and tell the user the path. **At epic altitude, scope the folder to the epic** (set `run_folder_pattern` per `customize.toml`) so per-epic runs don't collide.
+
+## Reviewer Gate
+
+The spine's pre-handoff review — full mechanics in `references/reviewer-gate.md`. Load it when finalizing or validating: a deterministic `lint_spine.py` pass, then a rubric walker (good-spine checklist) + every `{workflow.finalize_reviewers}` lens dispatched as parallel subagents against `ARCHITECTURE-SPINE.md`, scaled to stakes. At Finalize you apply the clear fixes; under the Validate intent you deliver a bespoke HTML report and then get user input.
+
+## Finalize
+
+Walk the sequence; reviewer fixes land before polish.
+
+1. **Distill.** Write the spine from the memlog (brownfield: + the code sweep) — invariants first, seed minimal, every `AD` carrying Binds/Prevents/Rule, `Deferred` naming what it won't decide. No placeholders; never invent to fill a gap. The template's `<!-- -->` notes are guidance — act on them, then strip them; the finished spine carries no template comment, and only the diagrams that convey the structure (as many as the altitude needs, valid mermaid). Sweep the breadth the altitude owns — every structural dimension is decided, deferred, or an open question; a whole dimension left silent (e.g. the operational/environmental envelope: deployment & environments, infra/provider strategy, operations) is the failure, not a clean spine. A long coaching run distills cleaner in a subagent; the parent falls back inline.
+2. **Reconcile inputs.** A subagent per load-bearing input checks it against the spine and returns what didn't land — especially a quiet requirement (a tone, a constraint) the `AD` structure dropped. Before the gate.
+3. **Reviewer pass.** Run the Reviewer Gate (`references/reviewer-gate.md`). Resolve before polish.
+4. **Triage.** Open questions and `[ASSUMPTION]` tags: blockers (unsafe for what's next) resolved one at a time; the rest deferred with a revisit condition in the memlog.
+5. **Renderings & polish.** The spine is the build deliverable; with it and the memlog now in place, produce any *additional* human-facing artifact the user needs, scoped to the purpose and audience drawn out up front. The up-front question already flagged whether one's needed; if it wasn't, still offer one here, seeding concrete options: an interactive HTML+SVG deck to walk a team through the architecture and drive discussion, a fuller HTML/md solution design, a C4 set, or a view of how the work splits across teams/epics. Build only what they pick, right-sized to that purpose; apply `{workflow.doc_standards}` polish to that prose only, never to the spine.
+6. **External handoffs.** Run `{workflow.external_handoffs}`; surface returned URLs/IDs. Offer to invoke the `bmad-spec` skill to adopt the spine as a companion, keeping `AD` IDs stable so downstream can cite them.
+7. **Close.** Set the spine's own frontmatter `status: final`, `updated: {date}`; log a `memlog.py append --type event --text "spine finalized"` (the memlog has no status field). Share paths. Next, **lead with `bmad-spec`** — recommend adopting/refreshing the spine as a spec companion (always the top recommendation when a spec was an input, and a useful next step even when it wasn't), then `bmad-create-epics-and-stories` or — epic altitude — `bmad-build`; or invoke `bmad-help` to route.
+8. Run `{workflow.on_complete}`.
+
+## Update
+
+Amend an existing spine or provided artifact. Resume from its `.memlog.md` (the authority on what was decided), not the rendered spine. Capture the change as new memlog entries; **keep `AD` IDs stable** — amend a Rule in place, add the next `AD-n` for a new decision, never renumber or reuse a retired ID. Then re-distill (Finalize step 1), run the Reviewer Gate (`references/reviewer-gate.md`), and close as in Finalize. An update that overrides something from a source input: offer to update that source too, so upstream and the spine don't silently diverge.
+
+## Validate
+
+The standalone intent — critique an existing spine without changing it. Run the Reviewer Gate (`references/reviewer-gate.md`) against it and deliver the bespoke HTML report, then offer to roll the findings into an Update. (At Finalize the same gate runs as your own pre-handoff check, where you apply the fixes instead of reporting.)

package/src/bmm-skills/plan/bmad-architecture/assets/spine-template.md

@@ -0,0 +1,79 @@
+---
+name: '{name}'
+type: architecture-spine
+purpose: build-substrate    # build-substrate (default) · discussion · report · deck
+altitude: feature           # initiative (keeps features) · feature (keeps epics) · epic (keeps stories)
+paradigm: '{named design pattern, e.g. hexagonal, layered, pipes-and-filters, actor}'
+scope: '{what this spine governs}'
+status: draft               # draft · final
+created: '{date}'
+updated: '{date}'
+binds: []                   # capability / unit IDs governed (from the driving spec; at epic altitude, also the inherited parent AD ids)
+sources: []
+companions: []
+---
+
+# Architecture Spine — {name}
+
+<!-- TEMPLATE GUIDE — act on these comments, then delete them; never emit a comment in the finished spine. This is a shape, not a script: keep only the sections this spine needs and cut the rest (no empty headers). A small intent may be just paradigm + a few ADs + conventions; a platform earns more. An inherited epic spine is usually mostly Inherited Invariants + a thin Deferred. Decisions, not rationale (rationale lives in the memlog). Carry shape in diagrams; prose only where it must. -->
+
+## Design Paradigm
+
+<!-- Name the pattern (a known one loads a whole model for free) and map its layers to namespaces/directories. The smallest, most durable thing here. -->
+
+## Inherited Invariants
+
+<!-- Only when this spine inherits a higher-altitude parent. The parent's ADs/conventions/paradigm that bind here, by their ORIGINAL ids — read-only, never renumbered, not re-derived. A local decision that contradicts one is a conflict to surface, not an override. Cut this section otherwise. -->
+
+| Inherited | From parent | Binds here |
+| --- | --- | --- |
+| {AD-id / convention} | {parent spine} | {what it constrains in this scope} |
+
+## Invariants & Rules
+
+<!-- The durable heart: calls a future builder can't read off compliant code. One block per decision: stable ascending id (never reused/renumbered), Binds, Prevents (the divergence), Rule (enforceable). Tag [ADOPTED] when the user or existing reality settled it. Include a dependency-direction diagram (who may depend on whom) — it IS a rule; author it as valid mermaid, never an empty graph. -->
+
+### AD-1 — {decision}
+
+- **Binds:** {capability / unit ids / fr/nfr's, areas, or `all`}
+- **Prevents:** {the divergence this stops}
+- **Rule:** {the constraint downstream must follow}
+
+## Consistency Conventions
+
+<!-- Defaults that bind where independent builders would drift. Cut rows that don't apply; add rows the project needs. -->
+
+| Concern | Convention |
+| --- | --- |
+| Naming (entities, files, interfaces, events) | |
+| Data & formats (ids, dates, error shapes, envelopes) | |
+| State & cross-cutting (mutation, errors, logging, config, auth) | |
+
+## Stack
+
+<!-- SEED — verified current at authoring; the code owns this once it exists. Name + version only; the why lives in the memlog. One row per language, framework, key dependency, platform, or chain that's pinned. -->
+
+| Name | Version |
+| --- | --- |
+| {language / framework / key dep / platform / chain} | {pinned version} |
+
+## Structural Seed
+
+<!-- The shapes worth fixing at cold-start — not a fixed list. Include only what's non-obvious at this altitude, and use as many diagrams as convey it, each as VALID mermaid (never a placeholder or empty graph). Candidates: system/container/context view; DEPLOYMENT & ENVIRONMENTS and external provider/infra topology (cover the operational envelope here when this altitude owns it — don't let it fall through); core-entity ERD (names + relationships only; an attribute that's itself an invariant is an AD, not a diagram); a minimal source tree. The code owns the detail — this is scaffold, not a mirror to maintain. -->
+
+```text
+{root}/
+  {dir}/   # {what lives here}
+```
+
+## Capability → Architecture Map
+
+<!-- Present when a spec drove this run. Bridges the spec's capabilities to where they live + what governs them; the consistency auditor's checklist. Cut otherwise. -->
+
+| Capability / Area | Lives in | Governed by |
+| --- | --- | --- |
+| {CAP-id / area} | {component / module} | {AD-id, convention, paradigm} |
+
+## Deferred
+
+<!-- Decisions intentionally pushed down, each with the reason it can wait — including whole dimensions this altitude doesn't own yet. The half of the contract that keeps the spine lean. -->

package/src/bmm-skills/plan/bmad-architecture/customize.toml

@@ -0,0 +1,102 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for bmad-architecture.
+#
+# Override files (not edited here):
+#   {project-root}/_bmad/custom/bmad-architecture.toml         (team)
+#   {project-root}/_bmad/custom/bmad-architecture.user.toml    (personal)
+
+[workflow]
+
+# --- Configurable below. Overrides merge per BMad structural rules: ---
+#   scalars: override wins • arrays: append
+
+# Steps to run before the standard activation (config load, greet).
+# Use for pre-flight loads, approved-stack policy checks, etc.
+activation_steps_prepend = []
+
+# Steps to run after greet but before the workflow begins.
+# Use for context-heavy setup that should happen once the user has been acknowledged.
+activation_steps_append = []
+
+# Persistent facts the workflow keeps in mind for the whole run
+# (approved stacks, banned dependencies, platform constraints, compliance guardrails).
+# Each entry is either a literal sentence, a skill prefixed with `skill:`, or a `file:`-prefixed
+# path/glob whose contents are loaded as facts.
+#
+# Default loads project-context.md if bmad-generate-project-context produced one — giving the
+# architect persistent awareness of the project's tech, domain, and conventions (load-bearing
+# for brownfield). Common opt-ins (set in team/user override TOML):
+#   "Our org is AWS-only -- do not propose GCP or Azure."
+#   "file:{project-root}/docs/engineering-standards.md"
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+# Executed when the workflow completes (after the spine is final and the user has been told).
+# String scalar (single instruction) or array of instructions executed in order. Empty for none.
+on_complete = ""
+
+# The architecture spine template. Treated as expert prior knowledge, not a checklist — the LLM
+# adapts it to the project, altitude, and domain, and drops sections a project genuinely doesn't
+# need. Override the path in team/user TOML to enforce a different spine shape.
+spine_template = "assets/spine-template.md"
+
+# Run folder location. ARCHITECTURE-SPINE.md, its .memlog.md, and any fuller rendering the run
+# produces all land inside `{spine_output_path}/{run_folder_pattern}/`. Resume-check scans
+# `{spine_output_path}` for prior unfinished runs.
+#
+# The default pattern fits the common case (one spine per project, at the altitude above epics).
+# At EPIC altitude, override run_folder_pattern to carry the epic identity so per-epic runs don't
+# collide on the same day — e.g. set it (team/user TOML) to "architecture-epic-{epic_id}", binding
+# {epic_id} from the driving spec / the activating payload. Headless callers may instead pass an
+# explicit doc_workspace and bypass the pattern entirely.
+spine_output_path = "{planning_artifacts}/architecture"
+run_folder_pattern = "architecture-{project_name}-{date}"
+
+# Prose-editorial standards applied at finalize ONLY to a fuller prose document the run produces
+# (a discussion report, full architecture doc, or design addendum) — never to the spine or other
+# short, structured outputs, which are terse and carry decisions in AD-n blocks and diagrams by
+# design. Each entry is a `skill:`, `file:`, or plain-text directive applied before the user sees
+# the polished draft. Suggested order: structural passes first, prose mechanics last. Append-only.
+# The default entry runs bmad-review's two editorial lenses in order:
+# structure, then prose on top of the structure findings. The `lenses=` suffix
+# names them; drop it to let bmad-review pick what fits the content.
+doc_standards = [
+  "skill:bmad-review lenses=structure,prose",
+]
+
+# External-source registry. Natural-language directives describing knowledge bases, MCP tools, or
+# internal systems the LLM may consult ON DEMAND during the run (not preemptively) — approved-stack
+# catalogs, internal platform docs, version registries. Each entry names the tool, the trigger
+# condition, and any fields it needs. If a named tool is unavailable at runtime, the LLM falls back
+# to standard behavior (e.g. web research) and notes the gap. Empty by default.
+#
+# Examples (set in team/user override TOML):
+#   "When choosing a datastore, consult corp:platform_catalog before recommending one."
+#   "For current library versions, query corp:artifact_registry before web search."
+external_sources = []
+
+# External-handoff routing applied at Finalize to push outputs beyond local files (Confluence,
+# Notion, ticket systems). Each entry names the MCP tool, the destination, and required fields.
+# Runs after polish; returned URLs/IDs are surfaced. Unavailable tools are skipped and flagged;
+# local files always exist. Empty by default.
+external_handoffs = []
+
+# --- Finalize reviewers ---
+# Extra review lenses spawned as parallel subagents at the validation gate (Finalize and the
+# Validate intent), on top of the skill's built-in good-spine checklist and the lint_spine.py
+# mechanical floor. The GATE is stakes-gated — a throwaway spine may run it quietly or skip it —
+# but whenever the gate runs, every entry here runs with it (the configured floor, never cherry-
+# picked); only ad-hoc lenses are optional, and headless never skips the gate.
+#
+# Entries follow the standard prefix convention:
+#   "skill:NAME"   invoke the named review skill as a subagent against ARCHITECTURE-SPINE.md
+#   "file:PATH"    load the file as a review prompt; spawn an adversarial subagent applying it
+#   plain text     use the text directly as the subagent's review prompt
+#
+# Resolved on-demand (not at activation). Override TOML may append.
+finalize_reviewers = [
+  "Verify every committed decision was web-researched or reality-checked rather than asserted from training data: current library/framework versions, that each named technology still exists and fits, and — greenfield — the live defaults of any starter it leans on. Flag anything that could be out of date and wasn't confirmed against the web, the existing project, or the current starter.",
+  "Attack the spine as an adversary: construct two units one level down that each obey every AD to the letter yet still build incompatibly — clashing shared-data shapes, two owners of one entity, conflicting state-mutation paths. Every pair you find is a hole to close with a new or tightened AD.",
+]

package/src/bmm-skills/plan/bmad-architecture/references/headless.md

@@ -0,0 +1,26 @@
+# Headless
+
+No interactive user: infer everything, ask nothing, but never invent — record inferences as `assumptions[]` and gaps that need a human as `open_questions[]`. Detect headless from a `headless: true` flag, a non-interactive / no-TTY invocation, an activation hook that declares it, or a first message that pre-supplies all inputs and asks for an artifact path back; when ambiguous, default to interactive.
+
+Drive the run from the payload in the first message — `intent`, `altitude`, `purpose`, the driving input (spec package / PRD / raw intent / brownfield path), a parent spine path at lower altitude, and `doc_workspace` if a specific folder is required. Infer anything absent from the inputs or workspace; don't invent stack, constraints, or scope to fill a gap. You still verify named tech on the web (you can't ask, but you can check) and still drive every write through the shared `{project-root}/_bmad/scripts/memlog.py`. Run the full Reviewer Gate (`references/reviewer-gate.md`) non-interactively: `scripts/lint_spine.py` plus **every `{workflow.finalize_reviewers}` lens as a parallel subagent** (and any ad-hoc lens the spine's criticality warrants). Headless skips only the human picking from the menu — never the reviewers themselves; apply the clear fixes and record anything unresolved in `open_questions[]`. For a true authority collision, list it in `conflicts_with_prior_decisions[]`. For the Validate intent, always write the report to `{doc_workspace}` and add `"offer_to_update": true`. If intent stays ambiguous after inference, halt blocked.
+
+End with JSON only, omitting keys for artifacts not produced — the shape below is the fully-produced (`complete`) case; a `blocked` run produces no spine, so it omits `spine`, `memlog`, and `companions` entirely (see the note under the block):
+
+```json
+{
+  "status": "complete | partial | blocked",
+  "intent": "create | update | validate",
+  "altitude": "initiative | feature | epic",
+  "purpose": "build-substrate | discussion",
+  "doc_workspace": "<resolved run folder>",
+  "spine": "{doc_workspace}/ARCHITECTURE-SPINE.md",
+  "memlog": "{doc_workspace}/.memlog.md",
+  "companions": [],
+  "assumptions": [],
+  "open_questions": [],
+  "conflicts_with_prior_decisions": [],
+  "reason": "<one line, only when blocked>"
+}
+```
+
+`complete` stands alone · `partial` (spine produced, but `open_questions[]` non-empty or critical inputs inferred) means review before downstream use · `blocked` means no spine produced — return only `status`, `intent`, `reason`, and `doc_workspace` (if bound), omitting `spine`, `memlog`, `companions`, and the artifact arrays that don't exist.

package/src/bmm-skills/plan/bmad-architecture/references/reviewer-gate.md

@@ -0,0 +1,13 @@
+# Reviewer Gate
+
+The spine's pre-handoff review. Runs at Finalize (after distill + reconcile) and *is* the Validate intent. The difference is the ending: at Finalize you apply the clear fixes yourself; under Validate you report and don't change the spine.
+
+Cheap deterministic pass first: `uv run {skill-root}/scripts/lint_spine.py --workspace {doc_workspace}` settles the mechanical misses (placeholders, duplicate `AD` IDs, missing Binds/Prevents/Rule, unpinned Stack versions), so reviewers spend judgment on the semantic half.
+
+Assemble the menu: a **rubric walker** that judges the spine against the good-spine checklist below, **+ every entry in `{workflow.finalize_reviewers}`**, + ad-hoc lenses you invent or offer as the spine's rigor, altitude, and criticality warrant — a security/compliance lens for regulated stakes, a seam reviewer cross-team, a data-integrity lens for a heavy data model. Scale *whether and how heavily the gate runs* to the stakes: a throwaway prototype may run it quietly or skip the gate entirely; a high-criticality or platform-altitude spine earns more lenses and the explicit all / subset / skip menu. But once the gate runs, the `{workflow.finalize_reviewers}` always run — they are the configured floor, never cherry-picked out; only the ad-hoc lenses are optional. (Headless never skips the gate.)
+
+Dispatch every entry as a **parallel subagent against `ARCHITECTURE-SPINE.md`** (prefix convention: `skill:` / `file:` / plain text). Each writes its full review to `{doc_workspace}/reviews/review-{slug}.md` — a subfolder, so the gate's scratch stays out of the deliverable folder — and returns ONLY a compact summary (verdict, top 2–5 findings, file path) — the parent never holds full review text. An inline self-check does not count: the independent context is the point, because a fresh reviewer finds the divergences the author talks past. If subagents are unavailable, run sequentially — write the file first, then flush it from context.
+
+**Good-spine checklist** (what the rubric walker judges): it fixes the real divergence points for the level below and misses none; every `AD`'s Rule is enforceable and actually prevents its stated divergence; nothing under Deferred could let two units diverge; named tech is verified-current; it ratifies rather than contradicts a brownfield codebase; if a spec drove it, it covers that spec's capabilities; if a parent spine is inherited, no new `AD` weakens or contradicts an inherited one; and every dimension the altitude owns is decided, deferred, or an open question — a whole dimension left silent is a finding, especially the operational/environmental envelope (deployment & environments, infra/provider strategy, operations) a domain-focused draft skips.
+
+Surface findings tiered, never dumped: a one-sentence gate verdict, then critical + high; medium/low roll into a tail ("plus N more in {file}"). Per finding: autofix, discuss, defer to Deferred / open items, or ignore. **At Finalize this is your own gate — apply the clear fixes rather than handing over a list; surface only what genuinely needs the user.** Under the **Validate intent**, fold every reviewer's output into one bespoke HTML + markdown report and open the HTML.