Merge 0b491839cd into 2417f0048d

src/bmm-skills/3-solutioning/bmad-improve-architecture/DEEPENING.md

@@ -0,0 +1,33 @@
+# Deepening Guide
+
+Use this guide when deciding how a candidate should absorb its dependencies.
+
+## Dependency categories
+
+### In-process
+
+Pure computation or in-memory state. Merge freely and test through the new Interface.
+
+### Local-substitutable
+
+Dependencies with local test stand-ins, such as in-memory stores or embedded databases. Deepen the Module if the stand-in is good enough to support interface-level tests.
+
+### Remote but owned
+
+A network dependency your system owns. Define a port at the Seam and use at least two Adapters: production and test.
+
+### True external
+
+A third-party dependency you do not control. Inject it at the Seam and test with a mock or fake Adapter.
+
+## Seam discipline
+
+- Do not introduce a Seam unless variation across it is real.
+- Keep internal seams inside the Implementation when callers do not need to know about them.
+- Prefer one deep Module over a stack of shallow pass-through Modules.
+
+## Testing rule
+
+- Replace shallow-module tests with tests at the deepened Interface.
+- Assert observable behavior, not internal state.
+- If a test must change for an internal refactor, it is probably testing past the Interface.

src/bmm-skills/3-solutioning/bmad-improve-architecture/INTERFACE-DESIGN.md

@@ -0,0 +1,38 @@
+# Interface Design
+
+When a candidate has been chosen, produce multiple Interface options before recommending one.
+
+## Required options
+
+Create at least three alternatives:
+
+1. Minimal Interface
+2. Flexible Interface
+3. Caller-optimized Interface
+
+Create a fourth Ports-and-Adapters option only when the dependency shape justifies a real Seam.
+
+## For each option include
+
+- Interface shape
+- Example caller usage
+- What the Implementation hides
+- Dependency and Adapter strategy
+- Trade-offs in Depth, Leverage, and Locality
+
+## Comparison criteria
+
+Compare options by:
+
+- Depth
+- Locality
+- Seam placement
+- Adapter strategy
+- Test surface
+- Migration cost
+- Compatibility with ADRs
+- Ease of story slicing
+
+## Recommendation rule
+
+Pick one option or a clear hybrid. Do not leave the user with an unranked menu.

src/bmm-skills/3-solutioning/bmad-improve-architecture/LANGUAGE.md

@@ -0,0 +1,42 @@
+# Architecture Language
+
+Use these terms exactly.
+
+## Terms
+
+**Module**
+Anything with an interface and an implementation. A function, class, package, or slice can all be a Module.
+
+**Interface**
+Everything a caller must know to use the Module correctly: types, ordering, invariants, error modes, required configuration, and performance expectations.
+
+**Implementation**
+The code behind the Interface.
+
+**Depth**
+Leverage at the Interface. A deep Module gives callers a lot of behavior behind a small Interface. A shallow Module exposes nearly as much complexity as it hides.
+
+**Seam**
+A place where behavior can change without editing in that place. Use `Seam`, not `boundary`.
+
+**Adapter**
+A concrete thing that satisfies an Interface at a Seam.
+
+**Leverage**
+What callers gain from Depth.
+
+**Locality**
+What maintainers gain from Depth. Bugs, change, and knowledge stay concentrated in one place.
+
+## Rules
+
+- Use `Module`, not `component`, `service`, or `unit`.
+- Use `Interface`, not `API` or `signature`.
+- Use `Seam`, not `boundary`.
+- Use `Depth`, `Leverage`, and `Locality` when explaining why a recommendation matters.
+
+## Principles
+
+- The deletion test: if deleting the Module only removes indirection, it was shallow.
+- The Interface is the test surface.
+- One adapter means a hypothetical Seam. Two adapters mean a real one.

src/bmm-skills/3-solutioning/bmad-improve-architecture/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: bmad-improve-architecture
+description: 'BMad-native architecture deepening workflow. Use when the user wants to find deepening opportunities, compare interfaces, and turn the result into ADRs and implementation slices.'
+---
+
+# BMad Improve Architecture
+
+This skill runs a BMad-native architecture deepening workflow with vendored architecture-analysis guidance.
+
+Act as a BMad Architect leading a focused architecture review. Use the domain language in `CONTEXT.md`, the constraints in ADRs, and the architecture vocabulary in `LANGUAGE.md`. The outcome is a concrete deepening recommendation plus BMad-ready artifacts for ADRs, story slicing, and test strategy.
+
+## Conventions
+
+- Bare paths (e.g. `LANGUAGE.md`) resolve from the skill root.
+- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives).
+- `{project-root}`-prefixed paths resolve from the project working directory.
+- `{skill-name}` resolves to the skill directory's basename.
+
+## On Activation
+
+### Step 1: Resolve the Workflow Block
+
+Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`
+
+**If the script fails**, resolve the `workflow` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
+
+1. `{skill-root}/customize.toml` — defaults
+2. `{project-root}/_bmad/custom/{skill-name}.toml` — team overrides
+3. `{project-root}/_bmad/custom/{skill-name}.user.toml` — personal overrides
+
+Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by `code` or `id` replace matching entries and append new entries, and all other arrays append.
+
+### Step 2: Execute Prepend Steps
+
+Execute each entry in `{workflow.activation_steps_prepend}` in order before proceeding.
+
+### Step 3: Load Persistent Facts
+
+Treat every entry in `{workflow.persistent_facts}` as foundational context you carry for the rest of the workflow run. Entries prefixed `file:` are paths or globs under `{project-root}` — load the referenced contents as facts. All other entries are facts verbatim.
+
+### Step 4: Load Config
+
+Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
+
+- Use `{user_name}` for greeting
+- Use `{communication_language}` for all communications
+- Use `{document_output_language}` for output documents
+- Use `{planning_artifacts}` for output location and artifact scanning
+- Use `{project_knowledge}` for additional context scanning
+
+### Step 5: Greet the User
+
+Greet `{user_name}`, speaking in `{communication_language}`.
+
+### Step 6: Execute Append Steps
+
+Execute each entry in `{workflow.activation_steps_append}` in order.
+
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
+
+## Read First
+
+Read these if they exist:
+
+- `{project-root}/CONTEXT-MAP.md`
+- `{project-root}/CONTEXT.md`
+- `{project-root}/docs/agents/domain.md`
+- `{project-root}/docs/adr/`
+- `{project-root}/_bmad-output/project-context.md`
+- `{project-root}/_bmad-output/architecture.md`
+- `{project-root}/_bmad-output/prd.md`
+- `{project-root}/_bmad-output/epics/`
+
+Then read:
+
+- `LANGUAGE.md`
+- `DEEPENING.md`
+- `INTERFACE-DESIGN.md`
+
+## Output Location
+
+Write all artifacts under `{planning_artifacts}/architecture-review`.
+
+Use these files:
+
+- `deepening-candidates.md`
+- `interface-options-{candidate-slug}.md`
+- `recommendation-{candidate-slug}.md`
+- `architecture-addendum-{candidate-slug}.md`
+- `adr-draft-{candidate-slug}.md`
+- `story-slices-{candidate-slug}.md`
+- `test-strategy-{candidate-slug}.md`
+
+## Workflow
+
+### 1. Build a working map
+
+Start with a compact working map:
+
+- Domain terms
+- Relevant ADR constraints
+- Current module seams
+- Testability pain
+- Likely high-friction areas
+
+If `CONTEXT-MAP.md` exists, follow it before reading any matching `CONTEXT.md` files.
+
+### 2. Explore for deepening candidates
+
+Explore the codebase for shallow modules and low-locality behavior.
+
+Look for:
+
+- orchestration duplicated across callers
+- seams with only one hypothetical adapter
+- extracted helpers that moved code without increasing locality
+- tests that need to mock internals instead of testing through an interface
+- modules that fail the deletion test
+
+Use the exact vocabulary from `LANGUAGE.md`.
+
+Do not propose interfaces yet.
+
+Write `deepening-candidates.md` with numbered candidates. For each candidate include:
+
+- Files
+- Problem
+- Why the module is shallow or low-locality
+- Deepening direction
+- Testability improvement
+- BMad impact
+
+For BMad impact include:
+
+- ADR needed: yes/no
+- Story count: small/medium/large
+- Risk: low/medium/high
+
+Then ask:
+
+`Which candidate do you want to explore?`
+
+Stop until the user chooses one.
+
+### 3. Run the grilling loop
+
+For the chosen candidate, ask only the questions needed to remove design risk:
+
+- What must stay stable?
+- Which callers matter most?
+- Which tests must survive?
+- Which ADRs are load-bearing?
+- Is this refactor-only or behavior-changing?
+- What failures keep recurring here?
+
+If the user rejects a direction for a durable reason, offer to record that as an ADR draft so the same idea is not re-suggested later.
+
+### 4. Design interfaces
+
+Use `INTERFACE-DESIGN.md` to produce at least three interface options:
+
+- minimal interface
+- flexible interface
+- caller-optimized interface
+- ports-and-adapters interface only when the dependency shape justifies it
+
+Write `interface-options-{candidate-slug}.md`.
+
+Compare options by:
+
+- Depth
+- Locality
+- Seam placement
+- Adapter strategy
+- Test surface
+- Migration cost
+- ADR compatibility
+- Story slicing
+
+### 5. Recommend one direction
+
+Write `recommendation-{candidate-slug}.md` with:
+
+- recommended interface
+- why it wins
+- what stays behind the seam
+- migration risks
+- rollback plan
+
+Be opinionated. Prefer one recommendation or a clear hybrid.
+
+### 6. Generate BMad-ready artifacts
+
+Write:
+
+- `architecture-addendum-{candidate-slug}.md`
+- `adr-draft-{candidate-slug}.md`
+- `story-slices-{candidate-slug}.md`
+- `test-strategy-{candidate-slug}.md`
+
+Artifact rules:
+
+- The architecture addendum describes the chosen Module, Interface, Seam, and Adapter strategy.
+- The ADR draft captures the decision, consequences, and rejected options.
+- Story slices stay small and testable.
+- The test strategy explains what moves to the interface test surface and what regression coverage must exist.
+
+### 7. Route into the next BMad workflow
+
+When the artifacts are complete, recommend the next workflow explicitly:
+
+- `bmad-architecture` to absorb the addendum
+- `bmad-create-epics-and-stories` to turn slices into planned work
+- `bmad-create-story` for the next implementable slice
+- `bmad-testarch-test-design` or `bmad-testarch-trace` when regression risk is material
+
+Do not implement code unless the user explicitly asks.

src/bmm-skills/3-solutioning/bmad-improve-architecture/customize.toml

@@ -0,0 +1,16 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for bmad-improve-architecture. Mirrors the
+# agent customization shape under the [workflow] namespace.
+
+[workflow]
+
+activation_steps_prepend = []
+
+activation_steps_append = []
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+on_complete = ""

src/bmm-skills/module-help.csv

@@ -18,6 +18,7 @@ BMad Method,bmad-prfaq,PRFAQ Challenge,WB,Working Backwards guided experience to
 BMad Method,bmad-prd,Create Edit and Review PRD,PRD,"Facilitated PRD workflow — create a new PRD via coached discovery, update an existing one against a change signal, or validate a finished PRD against a checklist with an HTML findings report.",,,2-planning,bmad-product-brief,,true,planning_artifacts,prd
 BMad Method,bmad-ux,Create UX,CU,"Guidance through realizing the plan for your UX, strongly recommended if a UI is a primary piece of the proposed project.",,,2-planning,bmad-prd,,false,planning_artifacts,ux design
 BMad Method,bmad-architecture,Architecture,CA,Offer once requirements exist (a PRD or spec; plus UX if present) and the user is ready to move from what to how. Also offer any time independently-built parts risk diverging. Produces the architecture spine: the invariants that keep features epics and stories consistent. Comes before epics and stories and scales from a quick spine to a full architecture (brownfield: ratifies the existing codebase).,,,3-solutioning,,,true,planning_artifacts,architecture
+BMad Method,bmad-improve-architecture,Improve Architecture,IA,Find deepening candidates compare interface options and write BMad-ready architecture artifacts for brownfield or pre-implementation architecture refinement.,,,3-solutioning,,,false,planning_artifacts,architecture review artifacts
 BMad Method,bmad-create-epics-and-stories,Create Epics and Stories,CE,,,,3-solutioning,bmad-architecture,,true,planning_artifacts,epics and stories
 BMad Method,bmad-check-implementation-readiness,Check Implementation Readiness,IR,Ensure PRD UX Architecture and Epics Stories are aligned.,,,3-solutioning,bmad-create-epics-and-stories,,true,planning_artifacts,readiness report
 BMad Method,bmad-sprint-planning,Sprint Planning,SP,Kicks off implementation by producing a plan the implementation agents will follow in sequence for every story.,,,4-implementation,,,true,implementation_artifacts,sprint status