bmad-method 6.0.0-alpha.8 → 6.0.0-alpha.9

package/src/modules/bmm/workflows/4-implementation/story-context/instructions.md

@@ -11,35 +11,6 @@
 
 <critical>DOCUMENT OUTPUT: Technical context file (.context.xml). Concise, structured, project-relative paths only.</critical>
 
-## 📚 Document Discovery - Selective Epic Loading
-
-**Strategy**: This workflow needs only ONE specific epic and its stories, not all epics. This provides huge efficiency gains when epics are sharded.
-
-**Epic Discovery Process (SELECTIVE OPTIMIZATION):**
-
-1. **Determine which epic** you need (epic_num from story key - e.g., story "3-2-feature-name" needs Epic 3)
-2. **Check for sharded version**: Look for `epics/index.md`
-3. **If sharded version found**:
-   - Read `index.md` to understand structure
-   - **Load ONLY `epic-{epic_num}.md`** (e.g., `epics/epic-3.md` for Epic 3)
-   - DO NOT load all epic files - only the one needed!
-   - This is the key efficiency optimization for large multi-epic projects
-4. **If whole document found**: Load the complete `epics.md` file and extract the relevant epic
-
-**Other Documents (prd, architecture, ux-design) - Full Load:**
-
-1. **Search for whole document first** - Use fuzzy file matching
-2. **Check for sharded version** - If whole document not found, look for `{doc-name}/index.md`
-3. **If sharded version found**:
-   - Read `index.md` to understand structure
-   - Read ALL section files listed in the index
-   - Treat combined content as single document
-4. **Brownfield projects**: The `document-project` workflow creates `{output_folder}/docs/index.md`
-
-**Priority**: If both whole and sharded versions exist, use the whole document.
-
-**UX-Heavy Projects**: Always check for ux-design documentation as it provides critical context for UI-focused stories.
-
 <workflow>
   <step n="1" goal="Find drafted story and check for existing context" tag="sprint-status">
     <check if="{{story_path}} is provided">
@@ -89,10 +60,10 @@
     <check if="context file already exists">
       <output>⚠️ Context file already exists: {default_output_file}
 
-**What would you like to do?**
-1. **Replace** - Generate new context file (overwrites existing)
-2. **Verify** - Validate existing context file
-3. **Cancel** - Exit without changes
+        **What would you like to do?**
+        1. **Replace** - Generate new context file (overwrites existing)
+        2. **Verify** - Validate existing context file
+        3. **Cancel** - Exit without changes
       </output>
       <ask>Choose action (replace/verify/cancel):</ask>
 
@@ -117,10 +88,15 @@
     <template-output file="{default_output_file}">so_that</template-output>
   </step>
 
+  <step n="1.5" goal="Discover and load project documents">
+    <invoke-protocol name="discover_inputs" />
+    <note>After discovery, these content variables are available: {prd_content}, {tech_spec_content}, {architecture_content}, {ux_design_content}, {epics_content} (loads only epic for this story if sharded), {document_project_content}</note>
+  </step>
+
   <step n="2" goal="Collect relevant documentation">
-    <action>Scan docs and src module docs for items relevant to this story's domain: search keywords from story title, ACs, and tasks.</action>
-    <action>Prefer authoritative sources: PRD, Tech-Spec, Architecture, Front-end Spec, Testing standards, module-specific docs.</action>
-    <action>Note: Tech-Spec is used for Level 0-1 projects (instead of PRD). It contains comprehensive technical context, brownfield analysis, framework details, existing patterns, and implementation guidance.</action>
+    <action>Review loaded content from Step 1.5 for items relevant to this story's domain (use keywords from story title, ACs, and tasks).</action>
+    <action>Extract relevant sections from: {prd_content}, {tech_spec_content}, {architecture_content}, {ux_design_content}, {document_project_content}</action>
+    <action>Note: Tech-Spec ({tech_spec_content}) is used for Level 0-1 projects (instead of PRD). It contains comprehensive technical context, brownfield analysis, framework details, existing patterns, and implementation guidance.</action>
     <action>For each discovered document: convert absolute paths to project-relative format by removing {project-root} prefix. Store only relative paths (e.g., "docs/prd.md" not "/Users/.../docs/prd.md").</action>
     <template-output file="{default_output_file}">
       Add artifacts.docs entries with {path, title, section, snippet}:

package/src/modules/bmm/workflows/4-implementation/story-context/workflow.yaml

@@ -9,10 +9,10 @@ output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
 document_output_language: "{config_source}:document_output_language"
-story_path: "{config_source}:dev_ephemeral_location/stories"
+story_path: "{config_source}:sprint_artifacts/stories"
 date: system-generated
-ephemeral_files: "{config_source}:dev_ephemeral_location"
-sprint_status: "{context_dir}/sprint-status.yaml || {output_folder}/sprint-status.yaml"
+sprint_artifacts: "{config_source}:sprint_artifacts"
+sprint_status: "{sprint_artifacts}/sprint-status.yaml || {output_folder}/sprint-status.yaml"
 
 # Workflow components
 installed_path: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/story-context"
@@ -26,21 +26,27 @@ validation: "{installed_path}/checklist.md"
 input_file_patterns:
   prd:
     whole: "{output_folder}/*prd*.md"
-    sharded: "{output_folder}/*prd*/index.md"
+    sharded: "{output_folder}/*prd*/*.md"
+    load_strategy: "FULL_LOAD"
   tech_spec:
     whole: "{output_folder}/tech-spec.md"
+    load_strategy: "FULL_LOAD"
   architecture:
     whole: "{output_folder}/*architecture*.md"
-    sharded: "{output_folder}/*architecture*/index.md"
+    sharded: "{output_folder}/*architecture*/*.md"
+    load_strategy: "FULL_LOAD"
   ux_design:
     whole: "{output_folder}/*ux*.md"
-    sharded: "{output_folder}/*ux*/index.md"
+    sharded: "{output_folder}/*ux*/*.md"
+    load_strategy: "FULL_LOAD"
   epics:
     whole: "{output_folder}/*epic*.md"
     sharded_index: "{output_folder}/*epic*/index.md"
     sharded_single: "{output_folder}/*epic*/epic-{{epic_num}}.md"
+    load_strategy: "SELECTIVE_LOAD"
   document_project:
     sharded: "{output_folder}/docs/index.md"
+    load_strategy: "INDEX_GUIDED"
 
 # Output configuration
 # Uses story_key from sprint-status.yaml (e.g., "1-2-user-authentication")

package/src/modules/bmm/workflows/4-implementation/story-done/workflow.yaml

@@ -9,7 +9,8 @@ output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
 date: system-generated
-sprint_status: "{context_dir}/sprint-status.yaml || {output_folder}/sprint-status.yaml"
+sprint_artifacts: "{config_source}:sprint_artifacts"
+sprint_status: "{sprint_artifacts}/sprint-status.yaml || {output_folder}/sprint-status.yaml"
 
 # Workflow components
 installed_path: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/story-done"
@@ -17,7 +18,7 @@ instructions: "{installed_path}/instructions.md"
 
 # Variables and inputs
 variables:
-  story_dir: "{config_source}:dev_ephemeral_location/stories" # Directory where stories are stored
+  story_dir: "{config_source}:sprint_artifacts" # Directory where stories are stored
 
 # Output configuration - no output file, just status updates
 default_output_file: ""

package/src/modules/bmm/workflows/4-implementation/story-ready/instructions.md

@@ -14,12 +14,12 @@
 
 <action>If {{story_path}} is provided → use it directly; extract story_key from filename or metadata; GOTO mark_ready</action>
 
-<critical>MUST read COMPLETE sprint-status.yaml file from start to end to preserve order</critical>
-<action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
+<critical>MUST read COMPLETE {sprint_status} file from start to end to preserve order</critical>
+<action>Load the FULL file: {sprint_status}</action>
 <action>Read ALL lines from beginning to end - do not skip any content</action>
 <action>Parse the development_status section completely</action>
 
-<action>Find ALL stories (reading in order from top to bottom) where:
+<action>Find ALL stories (reading in order from start to end) where:
 
 - Key matches pattern: number-number-name (e.g., "1-2-user-auth")
 - NOT an epic key (epic-X) or retrospective (epic-X-retrospective)
@@ -30,7 +30,7 @@
 <action>Count total drafted stories found</action>
 
 <check if="no drafted stories found">
-  <output>📋 No drafted stories found in sprint-status.yaml
+  <output>📋 No drafted stories found in {sprint_status}
 
 All stories are either still in backlog or already marked ready/in-progress/done.
 
@@ -67,7 +67,7 @@ All stories are either still in backlog or already marked ready/in-progress/done
 </step>
 
 <step n="2" goal="Update sprint status to ready-for-dev" tag="sprint-status">
-<action>Load the FULL file: {{output_folder}}/sprint-status.yaml</action>
+<action>Load the FULL file: {sprint_status}</action>
 <action>Find development_status key matching {{story_key}}</action>
 <action>Verify current status is "drafted" (expected previous state)</action>
 <action>Update development_status[{{story_key}}] = "ready-for-dev"</action>

package/src/modules/bmm/workflows/4-implementation/story-ready/workflow.yaml

@@ -9,7 +9,8 @@ output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
 date: system-generated
-sprint_status: "{context_dir}/sprint-status.yaml || {output_folder}/sprint-status.yaml"
+sprint_artifacts: "{config_source}:sprint_artifacts"
+sprint_status: "{sprint_artifacts}/sprint-status.yaml || {output_folder}/sprint-status.yaml"
 
 # Workflow components
 installed_path: "{project-root}/{bmad_folder}/bmm/workflows/4-implementation/story-ready"
@@ -17,10 +18,7 @@ instructions: "{installed_path}/instructions.md"
 
 # Variables and inputs
 variables:
-  story_dir: "{config_source}:dev_ephemeral_location/stories" # Directory where stories are stored
-
-# Output configuration - no output file, just status updates
-default_output_file: ""
+  story_dir: "{config_source}:sprint_artifacts"
 
 standalone: true
 

package/src/modules/bmm/workflows/document-project/checklist.md

@@ -181,7 +181,7 @@
 
 ### Missing Information (to note for user)
 
-- ***
+-
 
 ## Deep-Dive Mode Validation (if deep-dive was performed)
 

package/src/modules/bmm/workflows/document-project/workflows/deep-dive-instructions.md

@@ -137,10 +137,10 @@ This will read EVERY file in this area. Proceed? [y/n]
 <action>For each file in file\*inventory, document: - **File Path:** Full path - **Purpose:** What this file does (1-2 sentences) - **Lines of Code:** Total LOC - **Exports:** Complete list with signatures
 
 - Functions: `functionName(param: Type): ReturnType` - Description
-  _ Classes: `ClassName` - Description with key methods
-  _ Types/Interfaces: `TypeName` - Description
-  \_ Constants: `CONSTANT_NAME: Type` - Description - **Imports/Dependencies:** What it uses and why - **Used By:** Files that import this (dependents) - **Key Implementation Details:** Important logic, algorithms, patterns - **State Management:** If applicable (Redux, Context, local state) - **Side Effects:** API calls, database queries, file I/O, external services - **Error Handling:** Try/catch blocks, error boundaries, validation - **Testing:** Associated test files and coverage - **Comments/TODOs:** Any inline documentation or planned work
-  </action>
+  - Classes: `ClassName` - Description with key methods
+  - Types/Interfaces: `TypeName` - Description
+  - Constants: `CONSTANT_NAME: Type` - Description - **Imports/Dependencies:** What it uses and why - **Used By:** Files that import this (dependents) - **Key Implementation Details:** Important logic, algorithms, patterns - **State Management:** If applicable (Redux, Context, local state) - **Side Effects:** API calls, database queries, file I/O, external services - **Error Handling:** Try/catch blocks, error boundaries, validation - **Testing:** Associated test files and coverage - **Comments/TODOs:** Any inline documentation or planned work
+    </action>
 
 <template-output>comprehensive_file_inventory</template-output>
 </step>

package/src/modules/bmm/workflows/document-project/workflows/full-scan-instructions.md

@@ -325,11 +325,11 @@ findings.batches_completed: [
   </check>
 
 <action>Build API contracts catalog</action>
-<action>IMMEDIATELY write to: {output*folder}/api-contracts-{part_id}.md</action>
+<action>IMMEDIATELY write to: {output_folder}/api-contracts-{part_id}.md</action>
 <action>Validate document has all required sections</action>
 <action>Update state file with output generated</action>
 <action>PURGE detailed API data, keep only: "{{api_count}} endpoints documented"</action>
-<template-output>api_contracts*{part_id}</template-output>
+<template-output>api_contracts\*{part_id}</template-output>
 </check>
 
 <check if="requires_data_models == true">
@@ -346,11 +346,11 @@ findings.batches_completed: [
   </check>
 
 <action>Build database schema documentation</action>
-<action>IMMEDIATELY write to: {output*folder}/data-models-{part_id}.md</action>
+<action>IMMEDIATELY write to: {output_folder}/data-models-{part_id}.md</action>
 <action>Validate document completeness</action>
 <action>Update state file with output generated</action>
 <action>PURGE detailed schema data, keep only: "{{table_count}} tables documented"</action>
-<template-output>data_models*{part_id}</template-output>
+<template-output>data_models\*{part_id}</template-output>
 </check>
 
 <check if="requires_state_management == true">
@@ -758,15 +758,15 @@ When a document SHOULD be generated but wasn't (due to quick scan, missing data,
 ### Generated Documentation
 
 - [Project Overview](./project-overview.md)
-- [Architecture](./architecture{{#if multi-part}}-{part*id}{{/if}}.md){{#unless architecture_file_exists}} *(To be generated)\_{{/unless}}
+- [Architecture](./architecture{{#if multi-part}}-{part\*id}{{/if}}.md){{#unless architecture_file_exists}} (To be generated) {{/unless}}
 - [Source Tree Analysis](./source-tree-analysis.md)
-- [Component Inventory](./component-inventory{{#if multi-part}}-{part*id}{{/if}}.md){{#unless component_inventory_exists}} *(To be generated)\_{{/unless}}
-- [Development Guide](./development-guide{{#if multi-part}}-{part*id}{{/if}}.md){{#unless dev_guide_exists}} *(To be generated)_{{/unless}}
-  {{#if deployment_found}}- [Deployment Guide](./deployment-guide.md){{#unless deployment_guide_exists}} _(To be generated)_{{/unless}}{{/if}}
+- [Component Inventory](./component-inventory{{#if multi-part}}-{part\*id}{{/if}}.md){{#unless component_inventory_exists}} (To be generated) {{/unless}}
+- [Development Guide](./development-guide{{#if multi-part}}-{part\*id}{{/if}}.md){{#unless dev_guide_exists}} (To be generated) {{/unless}}
+  {{#if deployment_found}}- [Deployment Guide](./deployment-guide.md){{#unless deployment_guide_exists}} (To be generated) {{/unless}}{{/if}}
   {{#if contribution_found}}- [Contribution Guide](./contribution-guide.md){{/if}}
-  {{#if api_documented}}- [API Contracts](./api-contracts{{#if multi-part}}-{part_id}{{/if}}.md){{#unless api_contracts_exists}} _(To be generated)_{{/unless}}{{/if}}
-  {{#if data_models_documented}}- [Data Models](./data-models{{#if multi-part}}-{part_id}{{/if}}.md){{#unless data_models_exists}} _(To be generated)_{{/unless}}{{/if}}
-  {{#if multi-part}}- [Integration Architecture](./integration-architecture.md){{#unless integration_arch_exists}} _(To be generated)\_{{/unless}}{{/if}}
+  {{#if api_documented}}- [API Contracts](./api-contracts{{#if multi-part}}-{part_id}{{/if}}.md){{#unless api_contracts_exists}} (To be generated) {{/unless}}{{/if}}
+  {{#if data_models_documented}}- [Data Models](./data-models{{#if multi-part}}-{part_id}{{/if}}.md){{#unless data_models_exists}} (To be generated) {{/unless}}{{/if}}
+  {{#if multi-part}}- [Integration Architecture](./integration-architecture.md){{#unless integration_arch_exists}} (To be generated) {{/unless}}{{/if}}
 
 ### Existing Documentation
 
@@ -850,10 +850,10 @@ Set {{incomplete_docs_list}} = {{incomplete_docs_strict}} + {{incomplete_docs_fu
 For each item store structure:
 {
 "title": "Architecture – Server",
-"file*path": "./architecture-server.md",
+"file\*path": "./architecture-server.md",
 "doc_type": "architecture",
 "part_id": "server",
-"line_text": "- [Architecture – Server](./architecture-server.md) *(To be generated)\_",
+"line_text": "- [Architecture – Server](./architecture-server.md) (To be generated)",
 "fuzzy_match": false
 }
 </action>

package/src/modules/bmm/workflows/testarch/ci/checklist.md

@@ -240,7 +240,7 @@ If workflow fails:
 
 **Checklist Complete**: Sign off when all items validated.
 
-**Completed by:** **\*\***\_\_\_**\*\***
-**Date:** **\*\***\_\_\_**\*\***
-**Platform:** **\*\***\_\_\_**\*\*** (GitHub Actions / GitLab CI)
-**Notes:** \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***
+**Completed by:** {name}
+**Date:** {date}
+**Platform:** {GitHub Actions, GitLab CI, Other}
+**Notes:** {notes}

package/src/modules/bmm/workflows/testarch/framework/checklist.md

@@ -315,7 +315,7 @@ If workflow fails and needs to be rolled back:
 
 **Checklist Complete**: Sign off when all items checked and validated.
 
-**Completed by:** **\*\***\_\_\_**\*\***
-**Date:** **\*\***\_\_\_**\*\***
-**Framework:** **\*\***\_\_\_**\*\*** (Playwright / Cypress)
-**Notes:** \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***
+**Completed by:** {name}
+**Date:** {date}
+**Framework:** { Playwright / Cypress or something else}
+**Notes:** {notes}

package/src/modules/bmm/workflows/testarch/test-design/checklist.md

@@ -228,7 +228,7 @@ If workflow fails:
 
 **Checklist Complete**: Sign off when all items validated.
 
-**Completed by:** **\*\***\_\_\_**\*\***
-**Date:** **\*\***\_\_\_**\*\***
-**Epic:** **\*\***\_\_\_**\*\***
-**Notes:** \***\*\*\*\*\***\*\*\***\*\*\*\*\***\_\_\_\***\*\*\*\*\***\*\*\***\*\*\*\*\***
+**Completed by:** {name}
+**Date:** {date}
+**Epic:** {epic title}
+**Notes:** {additional notes}

package/src/modules/bmm/workflows/testarch/test-design/instructions.md

@@ -9,24 +9,77 @@
 
 ## Overview
 
-Plans comprehensive test coverage strategy with risk assessment, priority classification, and execution ordering. This workflow generates a test design document that identifies high-risk areas, maps requirements to test levels, prioritizes scenarios (P0-P3), and provides resource estimates for the testing effort.
+Plans comprehensive test coverage strategy with risk assessment, priority classification, and execution ordering. This workflow operates in **two modes**:
+
+- **System-Level Mode (Phase 3)**: Testability review of architecture before solutioning gate check
+- **Epic-Level Mode (Phase 4)**: Per-epic test planning with risk assessment (current behavior)
+
+The workflow auto-detects which mode to use based on project phase.
 
 ---
 
-## Preflight Requirements
+## Preflight: Detect Mode and Load Context
+
+**Critical:** Determine mode before proceeding.
+
+### Mode Detection
+
+1. **Check for sprint-status.yaml**
+   - If `{output_folder}/bmm-sprint-status.yaml` exists → **Epic-Level Mode** (Phase 4)
+   - If NOT exists → Check workflow status
+
+2. **Check workflow-status.yaml**
+   - Read `{output_folder}/bmm-workflow-status.yaml`
+   - If `solutioning-gate-check: required` or `solutioning-gate-check: recommended` → **System-Level Mode** (Phase 3)
+   - Otherwise → **Epic-Level Mode** (Phase 4 without sprint status yet)
+
+3. **Mode-Specific Requirements**
+
+   **System-Level Mode (Phase 3 - Testability Review):**
+   - ✅ Architecture document exists (architecture.md or tech-spec)
+   - ✅ PRD exists with functional and non-functional requirements
+   - ✅ Epics documented (epics.md)
+   - ⚠️ Output: `{output_folder}/test-design-system.md`
 
-**Critical:** Verify these requirements before proceeding. If any fail, HALT and notify the user.
+   **Epic-Level Mode (Phase 4 - Per-Epic Planning):**
+   - ✅ Story markdown with acceptance criteria available
+   - ✅ PRD or epic documentation exists for context
+   - ✅ Architecture documents available (optional but recommended)
+   - ✅ Requirements are clear and testable
+   - ⚠️ Output: `{output_folder}/test-design-epic-{epic_num}.md`
 
-- ✅ Story markdown with acceptance criteria available
-- ✅ PRD or epic documentation exists for context
-- ✅ Architecture documents available (optional but recommended)
-- ✅ Requirements are clear and testable
+**Halt Condition:** If mode cannot be determined or required files missing, HALT and notify user with missing prerequisites.
 
 ---
 
-## Step 1: Load Context and Requirements
+## Step 1: Load Context (Mode-Aware)
 
-### Actions
+**Mode-Specific Loading:**
+
+### System-Level Mode (Phase 3)
+
+1. **Read Architecture Documentation**
+   - Load architecture.md or tech-spec (REQUIRED)
+   - Load PRD.md for functional and non-functional requirements
+   - Load epics.md for feature scope
+   - Identify technology stack decisions (frameworks, databases, deployment targets)
+   - Note integration points and external system dependencies
+   - Extract NFR requirements (performance SLOs, security requirements, etc.)
+
+2. **Load Knowledge Base Fragments (System-Level)**
+
+   **Critical:** Consult `{project-root}/{bmad_folder}/bmm/testarch/tea-index.csv` to load:
+   - `nfr-criteria.md` - NFR validation approach (security, performance, reliability, maintainability)
+   - `test-levels-framework.md` - Test levels strategy guidance
+   - `risk-governance.md` - Testability risk identification
+   - `test-quality.md` - Quality standards and Definition of Done
+
+3. **Analyze Existing Test Setup (if brownfield)**
+   - Search for existing test directories
+   - Identify current test framework (if any)
+   - Note testability concerns in existing codebase
+
+### Epic-Level Mode (Phase 4)
 
 1. **Read Requirements Documentation**
    - Load PRD.md for high-level product requirements
@@ -37,6 +90,7 @@ Plans comprehensive test coverage strategy with risk assessment, priority classi
 2. **Load Architecture Context**
    - Read architecture.md for system design
    - Read tech-spec for implementation details
+   - Read test-design-system.md (if exists from Phase 3)
    - Identify technical constraints and dependencies
    - Note integration points and external systems
 
@@ -46,7 +100,7 @@ Plans comprehensive test coverage strategy with risk assessment, priority classi
    - Note areas with insufficient testing
    - Check for flaky or outdated tests
 
-4. **Load Knowledge Base Fragments**
+4. **Load Knowledge Base Fragments (Epic-Level)**
 
    **Critical:** Consult `{project-root}/{bmad_folder}/bmm/testarch/tea-index.csv` to load:
    - `risk-governance.md` - Risk classification framework (6 categories: TECH, SEC, PERF, DATA, BUS, OPS), automated scoring, gate decision engine, owner tracking (625 lines, 4 examples)
@@ -54,11 +108,118 @@ Plans comprehensive test coverage strategy with risk assessment, priority classi
    - `test-levels-framework.md` - Test level selection guidance (E2E vs API vs Component vs Unit with decision matrix, characteristics, when to use each, 467 lines, 4 examples)
    - `test-priorities-matrix.md` - P0-P3 prioritization criteria (automated priority calculation, risk-based mapping, tagging strategy, time budgets, 389 lines, 2 examples)
 
-**Halt Condition:** If story data or acceptance criteria are missing, check if brownfield exploration is needed. If neither requirements NOR exploration possible, HALT with message: "Test design requires clear requirements, acceptance criteria, or brownfield app URL for exploration"
+**Halt Condition (Epic-Level only):** If story data or acceptance criteria are missing, check if brownfield exploration is needed. If neither requirements NOR exploration possible, HALT with message: "Epic-level test design requires clear requirements, acceptance criteria, or brownfield app URL for exploration"
+
+---
+
+## Step 1.5: System-Level Testability Review (Phase 3 Only)
+
+**Skip this step if Epic-Level Mode.** This step only executes in System-Level Mode.
+
+### Actions
+
+1. **Review Architecture for Testability**
+
+   Evaluate architecture against these criteria:
+
+   **Controllability:**
+   - Can we control system state for testing? (API seeding, factories, database reset)
+   - Are external dependencies mockable? (interfaces, dependency injection)
+   - Can we trigger error conditions? (chaos engineering, fault injection)
+
+   **Observability:**
+   - Can we inspect system state? (logging, metrics, traces)
+   - Are test results deterministic? (no race conditions, clear success/failure)
+   - Can we validate NFRs? (performance metrics, security audit logs)
+
+   **Reliability:**
+   - Are tests isolated? (parallel-safe, stateless, cleanup discipline)
+   - Can we reproduce failures? (deterministic waits, HAR capture, seed data)
+   - Are components loosely coupled? (mockable, testable boundaries)
+
+2. **Identify Architecturally Significant Requirements (ASRs)**
+
+   From PRD NFRs and architecture decisions, identify quality requirements that:
+   - Drive architecture decisions (e.g., "Must handle 10K concurrent users" → caching architecture)
+   - Pose testability challenges (e.g., "Sub-second response time" → performance test infrastructure)
+   - Require special test environments (e.g., "Multi-region deployment" → regional test instances)
+
+   Score each ASR using risk matrix (probability × impact).
+
+3. **Define Test Levels Strategy**
+
+   Based on architecture (mobile, web, API, microservices, monolith):
+   - Recommend unit/integration/E2E split (e.g., 70/20/10 for API-heavy, 40/30/30 for UI-heavy)
+   - Identify test environment needs (local, staging, ephemeral, production-like)
+   - Define testing approach per technology (Playwright for web, Maestro for mobile, k6 for performance)
+
+4. **Assess NFR Testing Approach**
+
+   For each NFR category:
+   - **Security**: Auth/authz tests, OWASP validation, secret handling (Playwright E2E + security tools)
+   - **Performance**: Load/stress/spike testing with k6, SLO/SLA thresholds
+   - **Reliability**: Error handling, retries, circuit breakers, health checks (Playwright + API tests)
+   - **Maintainability**: Coverage targets, code quality gates, observability validation
+
+5. **Flag Testability Concerns**
+
+   Identify architecture decisions that harm testability:
+   - ❌ Tight coupling (no interfaces, hard dependencies)
+   - ❌ No dependency injection (can't mock external services)
+   - ❌ Hardcoded configurations (can't test different envs)
+   - ❌ Missing observability (can't validate NFRs)
+   - ❌ Stateful designs (can't parallelize tests)
+
+   **Critical:** If testability concerns are blockers (e.g., "Architecture makes performance testing impossible"), document as CONCERNS or FAIL recommendation for gate check.
+
+6. **Output System-Level Test Design**
+
+   Write to `{output_folder}/test-design-system.md` containing:
+
+   ```markdown
+   # System-Level Test Design
+
+   ## Testability Assessment
+
+   - Controllability: [PASS/CONCERNS/FAIL with details]
+   - Observability: [PASS/CONCERNS/FAIL with details]
+   - Reliability: [PASS/CONCERNS/FAIL with details]
+
+   ## Architecturally Significant Requirements (ASRs)
+
+   [Risk-scored quality requirements]
+
+   ## Test Levels Strategy
+
+   - Unit: [X%] - [Rationale]
+   - Integration: [Y%] - [Rationale]
+   - E2E: [Z%] - [Rationale]
+
+   ## NFR Testing Approach
+
+   - Security: [Approach with tools]
+   - Performance: [Approach with tools]
+   - Reliability: [Approach with tools]
+   - Maintainability: [Approach with tools]
+
+   ## Test Environment Requirements
+
+   [Infrastructure needs based on deployment architecture]
+
+   ## Testability Concerns (if any)
+
+   [Blockers or concerns that should inform solutioning gate check]
+
+   ## Recommendations for Sprint 0
+
+   [Specific actions for *framework and *ci workflows]
+   ```
+
+**After System-Level Mode:** Skip to Step 4 (Generate Deliverables) - Steps 2-3 are epic-level only.
 
 ---
 
-## Step 1.5: Mode Selection (NEW - Phase 2.5)
+## Step 1.6: Exploratory Mode Selection (Epic-Level Only)
 
 ### Actions
 

package/src/modules/bmm/workflows/testarch/test-design/test-design-template.md

@@ -250,9 +250,9 @@
 
 **Test Design Approved By:**
 
-- [ ] Product Manager: **\*\***\_\_\_**\*\*** Date: **\*\***\_\_\_**\*\***
-- [ ] Tech Lead: **\*\***\_\_\_**\*\*** Date: **\*\***\_\_\_**\*\***
-- [ ] QA Lead: **\*\***\_\_\_**\*\*** Date: **\*\***\_\_\_**\*\***
+- [ ] Product Manager: {name} Date: {date}
+- [ ] Tech Lead: {name} Date: {date}
+- [ ] QA Lead: {name} Date: {date}
 
 **Comments:**
 

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

@@ -1,6 +1,6 @@
 # Test Architect workflow: test-design
 name: testarch-test-design
-description: "Plan risk mitigation and test coverage strategy before development with risk assessment and prioritization"
+description: "Dual-mode workflow: (1) System-level testability review in Solutioning phase, or (2) Epic-level test planning in Implementation phase. Auto-detects mode based on project phase."
 author: "BMad"
 
 # Critical variables from config
@@ -20,8 +20,12 @@ template: "{installed_path}/test-design-template.md"
 # Variables and inputs
 variables:
   design_level: "full" # full, targeted, minimal - scope of design effort
+  mode: "auto-detect" # auto-detect (default), system-level, epic-level
 
 # Output configuration
+# Note: Actual output file determined dynamically based on mode detection
+# - System-Level (Phase 3): {output_folder}/test-design-system.md
+# - Epic-Level (Phase 4): {output_folder}/test-design-epic-{epic_num}.md
 default_output_file: "{output_folder}/test-design-epic-{epic_num}.md"
 
 # Required tools

package/src/modules/bmm/workflows/workflow-status/init/instructions.md

@@ -19,16 +19,16 @@
 - Epic files: {output*folder}/\_epic*.md or {output*folder}/\_epic*/index.md
 - Architecture: {output*folder}/\_architecture*.md or {output*folder}/\_arch*.md
 - UX Design: {output*folder}/\_ux*.md or {output*folder}/\_design*.md
-- Product Brief: {output*folder}/\_brief*.md
-- Research docs: {output*folder}/\_research*.md
-- Brainstorm docs: {output*folder}/\_brainstorm*.md
+- Product Brief: {output_folder}/\*brief\*.md
+- Research docs: {output_folder}/\*research\*.md
+- Brainstorm docs: {output_folder}/\*brainstorm\*.md
 
 **Check for implementation artifacts:**
 
-- The following could be in or nested under {output_folder} OR {ephemeral_location} - CHECK BOTH LOCATIONS
-  - Story files: {output*folder}/stories/*.md or {ephemeral*location}/stories/*.md
-  - Sprint status: {output_folder}/sprint-status.yaml or {ephemeral_location}/sprint-status.yaml
-  - Existing workflow status: {output_folder}/bmm-workflow-status.yaml or {ephemeral_location}/bmm-workflow-status.yaml
+- The following could be in or nested under {output_folder} OR {sprint_artifacts} - CHECK BOTH LOCATIONS
+  - Story files: {output_folder}/stories/*.md or \*\*/stories/*story\*.md
+  - Sprint status: {output_folder}/sprint-status.yaml or {sprint_artifacts}/sprint-status.yaml
+  - Existing workflow status: {default_output_file} or {sprint_artifacts}/bmm-workflow-status.yaml
 
 **Check for codebase:**
 
@@ -660,13 +660,13 @@ For each phase in path file:
 
 - Brainstorm: {output_folder}/brainstorm\*.md
 - Research: {output_folder}/research\*.md
-- Product Brief: {output*folder}/\_brief*.md
+- Product Brief: {output_folder}/\*brief\*.md
 - PRD: {output*folder}/\_prd*.md or {output*folder}/\_prd*/index.md
 - Tech-spec: {output*folder}/\_tech-spec*.md or {output*folder}/\_spec*.md
 - Epics: {output*folder}/\_epic*.md or {output*folder}/\_epic*/index.md
 - UX Design: {output*folder}/\_ux*.md or {output*folder}/\_design*.md
 - Architecture: {output*folder}/\_architecture*.md or {output*folder}/\_arch*.md
-- Sprint Planning: {output*folder}/\_sprint*.yaml
+- Sprint Planning: {output_folder}/\*sprint\*.yaml
 
 **CRITICAL:** If file exists, replace workflow status with ONLY the file path, preserving agent comment.
 Example: `prd: docs/prd.md  # agent: pm` (NOT "completed - docs/prd.md")

package/src/modules/bmm/workflows/workflow-status/init/workflow.yaml

@@ -6,7 +6,7 @@ author: "BMad"
 # Critical variables from config
 config_source: "{project-root}/{bmad_folder}/bmm/config.yaml"
 output_folder: "{config_source}:output_folder"
-ephemeral_location: "{config_source}:dev_ephemeral_location"
+sprint_artifacts: "{config_source}:sprint_artifacts"
 user_name: "{config_source}:user_name"
 project_name: "{config_source}:project_name"
 communication_language: "{config_source}:communication_language"