Merge pull request #1103 from bmad-code-org/docs/test-architect-ADR-usage-update-2

docs: test arch ADR usage update

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "bmad-method",
-  "version": "6.0.0-alpha.15",
+  "version": "6.0.0-alpha.16",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "bmad-method",
-      "version": "6.0.0-alpha.15",
+      "version": "6.0.0-alpha.16",
       "license": "MIT",
       "dependencies": {
         "@kayvan/markdown-tree-parser": "^1.6.1",

src/modules/bmm/docs/test-architecture.md

@@ -26,14 +26,17 @@ graph TB
     subgraph Phase3["<b>Phase 3: SOLUTIONING</b>"]
         Architecture["<b>Architect: *architecture</b>"]
         EpicsStories["<b>PM/Architect: *create-epics-and-stories</b>"]
+        TestDesignSys["<b>TEA: *test-design (system-level)</b>"]
         Framework["<b>TEA: *framework</b>"]
         CI["<b>TEA: *ci</b>"]
         GateCheck["<b>Architect: *implementation-readiness</b>"]
         Architecture --> EpicsStories
+        Architecture --> TestDesignSys
+        TestDesignSys --> Framework
         EpicsStories --> Framework
         Framework --> CI
         CI --> GateCheck
-        Phase3Note["<b>Epics created AFTER architecture,</b><br/><b>then test infrastructure setup</b>"]
+        Phase3Note["<b>Epics created AFTER architecture,</b><br/><b>then system-level test design and test infrastructure setup</b>"]
         EpicsStories -.-> Phase3Note
     end
 
@@ -93,12 +96,17 @@ graph TB
 - **Documentation** (Optional for brownfield): Prerequisite using `*document-project`
 - **Phase 1** (Optional): Discovery/Analysis (`*brainstorm`, `*research`, `*product-brief`)
 - **Phase 2** (Required): Planning (`*prd` creates PRD with FRs/NFRs)
-- **Phase 3** (Track-dependent): Solutioning (`*architecture` → `*create-epics-and-stories` → TEA: `*framework`, `*ci` → `*implementation-readiness`)
+- **Phase 3** (Track-dependent): Solutioning (`*architecture` → `*test-design` (system-level) → `*create-epics-and-stories` → TEA: `*framework`, `*ci` → `*implementation-readiness`)
 - **Phase 4** (Required): Implementation (`*sprint-planning` → per-epic: `*test-design` → per-story: dev workflows)
 
-**TEA workflows:** `*framework` and `*ci` run once in Phase 3 after architecture. `*test-design` runs per-epic in Phase 4. Output: `test-design-epic-N.md`.
+**TEA workflows:** `*framework` and `*ci` run once in Phase 3 after architecture. `*test-design` is **dual-mode**:
 
-Quick Flow track skips Phase 1 and 3. BMad Method and Enterprise use all phases based on project needs.
+- **System-level (Phase 3):** Run immediately after architecture/ADR drafting to produce `test-design-system.md` (testability review, ADR → test mapping, Architecturally Significant Requirements (ASRs), environment needs). Feeds the implementation-readiness gate.
+- **Epic-level (Phase 4):** Run per-epic to produce `test-design-epic-N.md` (risk, priorities, coverage plan).
+
+Quick Flow track skips Phases 1 and 3.
+BMad Method and Enterprise use all phases based on project needs.
+When an ADR or architecture draft is produced, run `*test-design` in **system-level** mode before the implementation-readiness gate. This ensures the ADR has an attached testability review and ADR → test mapping. Keep the test-design updated if ADRs change.
 
 ### Why TEA is Different from Other BMM Agents
 

src/modules/bmm/workflows/testarch/test-design/workflow.yaml

@@ -24,8 +24,14 @@ variables:
 
 # Output configuration
 # Note: Actual output file determined dynamically based on mode detection
-# - System-Level (Phase 3): {output_folder}/test-design-system.md
+# Declared outputs for new workflow format
-# - Epic-Level (Phase 4): {output_folder}/test-design-epic-{epic_num}.md
+outputs:
+  - id: system-level
+    description: "System-level testability review (Phase 3)"
+    path: "{output_folder}/test-design-system.md"
+  - id: epic-level
+    description: "Epic-level test plan (Phase 4)"
+    path: "{output_folder}/test-design-epic-{epic_num}.md"
 default_output_file: "{output_folder}/test-design-epic-{epic_num}.md"
 
 # Required tools