bmad-method 6.0.0-alpha.12 → 6.0.0-alpha.14

package/src/modules/bmm/workflows/generate-project-context/steps/step-03-complete.md

@@ -0,0 +1,277 @@
+# Step 3: Context Completion & Finalization
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+- ✅ ALWAYS treat this as collaborative completion between technical peers
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- 💬 FOCUS on finalizing a lean, LLM-optimized project context
+- 🎯 ENSURE all critical rules are captured and actionable
+- ⚠️ ABSOLUTELY NO TIME ESTIMATES - AI development speed has fundamentally changed
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- 📝 Review and optimize content for LLM context efficiency
+- 📖 Update frontmatter with completion status
+- 🚫 NO MORE STEPS - this is the final step
+
+## CONTEXT BOUNDARIES:
+
+- All rule categories from step-2 are complete
+- Technology stack and versions are documented
+- Focus on final review, optimization, and completion
+- Ensure the context file is ready for AI agent consumption
+
+## YOUR TASK:
+
+Complete the project context file, optimize it for LLM efficiency, and provide guidance for usage and maintenance.
+
+## COMPLETION SEQUENCE:
+
+### 1. Review Complete Context File
+
+Read the entire project context file and analyze:
+
+**Content Analysis:**
+
+- Total length and readability for LLMs
+- Clarity and specificity of rules
+- Coverage of all critical areas
+- Actionability of each rule
+
+**Structure Analysis:**
+
+- Logical organization of sections
+- Consistency of formatting
+- Absence of redundant or obvious information
+- Optimization for quick scanning
+
+### 2. Optimize for LLM Context
+
+Ensure the file is lean and efficient:
+
+**Content Optimization:**
+
+- Remove any redundant rules or obvious information
+- Combine related rules into concise bullet points
+- Use specific, actionable language
+- Ensure each rule provides unique value
+
+**Formatting Optimization:**
+
+- Use consistent markdown formatting
+- Implement clear section hierarchy
+- Ensure scannability with strategic use of bolding
+- Maintain readability while maximizing information density
+
+### 3. Final Content Structure
+
+Ensure the final structure follows this optimized format:
+
+```markdown
+# Project Context for AI Agents
+
+_This file contains critical rules and patterns that AI agents must follow when implementing code in this project. Focus on unobvious details that agents might otherwise miss._
+
+---
+
+## Technology Stack & Versions
+
+{{concise_technology_list}}
+
+## Critical Implementation Rules
+
+### Language-Specific Rules
+
+{{specific_language_rules}}
+
+### Framework-Specific Rules
+
+{{framework_patterns}}
+
+### Testing Rules
+
+{{testing_requirements}}
+
+### Code Quality & Style Rules
+
+{{style_and_quality_patterns}}
+
+### Development Workflow Rules
+
+{{workflow_patterns}}
+
+### Critical Don't-Miss Rules
+
+{{anti_patterns_and_edge_cases}}
+
+---
+
+## Usage Guidelines
+
+**For AI Agents:**
+
+- Read this file before implementing any code
+- Follow ALL rules exactly as documented
+- When in doubt, prefer the more restrictive option
+- Update this file if new patterns emerge
+
+**For Humans:**
+
+- Keep this file lean and focused on agent needs
+- Update when technology stack changes
+- Review quarterly for outdated rules
+- Remove rules that become obvious over time
+
+Last Updated: {{date}}
+```
+
+### 4. Present Completion Summary
+
+Based on user skill level, present the completion:
+
+**Expert Mode:**
+"Project context complete. Optimized for LLM consumption with {{rule_count}} critical rules across {{section_count}} sections.
+
+File saved to: `{output_folder}/project_context.md`
+
+Ready for AI agent integration."
+
+**Intermediate Mode:**
+"Your project context is complete and optimized for AI agents!
+
+**What we created:**
+
+- {{rule_count}} critical implementation rules
+- Technology stack with exact versions
+- Framework-specific patterns and conventions
+- Testing and quality guidelines
+- Workflow and anti-pattern rules
+
+**Key benefits:**
+
+- AI agents will implement consistently with your standards
+- Reduced context switching and implementation errors
+- Clear guidance for unobvious project requirements
+
+**Next steps:**
+
+- AI agents should read this file before implementing
+- Update as your project evolves
+- Review periodically for optimization"
+
+**Beginner Mode:**
+"Excellent! Your project context guide is ready! 🎉
+
+**What this does:**
+Think of this as a 'rules of the road' guide for AI agents working on your project. It ensures they all follow the same patterns and avoid common mistakes.
+
+**What's included:**
+
+- Exact technology versions to use
+- Critical coding rules they might miss
+- Testing and quality standards
+- Workflow patterns to follow
+
+**How AI agents use it:**
+They read this file before writing any code, ensuring everything they create follows your project's standards perfectly.
+
+Your project context is saved and ready to help agents implement consistently!"
+
+### 5. Final File Updates
+
+Update the project context file with completion information:
+
+**Frontmatter Update:**
+
+```yaml
+---
+project_name: '{{project_name}}'
+user_name: '{{user_name}}'
+date: '{{date}}'
+sections_completed:
+  ['technology_stack', 'language_rules', 'framework_rules', 'testing_rules', 'quality_rules', 'workflow_rules', 'anti_patterns']
+status: 'complete'
+rule_count: { { total_rules } }
+optimized_for_llm: true
+---
+```
+
+**Add Usage Section:**
+Append the usage guidelines from step 3 to complete the document.
+
+### 6. Completion Validation
+
+Final checks before completion:
+
+**Content Validation:**
+✅ All critical technology versions documented
+✅ Language-specific rules are specific and actionable
+✅ Framework rules cover project conventions
+✅ Testing rules ensure consistency
+✅ Code quality rules maintain standards
+✅ Workflow rules prevent conflicts
+✅ Anti-pattern rules prevent common mistakes
+
+**Format Validation:**
+✅ Content is lean and optimized for LLMs
+✅ Structure is logical and scannable
+✅ No redundant or obvious information
+✅ Consistent formatting throughout
+
+### 7. Completion Message
+
+Present final completion to user:
+
+"✅ **Project Context Generation Complete!**
+
+Your optimized project context file is ready at:
+`{output_folder}/project_context.md`
+
+**📊 Context Summary:**
+
+- {{rule_count}} critical rules for AI agents
+- {{section_count}} comprehensive sections
+- Optimized for LLM context efficiency
+- Ready for immediate agent integration
+
+**🎯 Key Benefits:**
+
+- Consistent implementation across all AI agents
+- Reduced common mistakes and edge cases
+- Clear guidance for project-specific patterns
+- Minimal LLM context usage
+
+**📋 Next Steps:**
+
+1. AI agents will automatically read this file when implementing
+2. Update this file when your technology stack or patterns evolve
+3. Review quarterly to optimize and remove outdated rules
+
+Your project context will help ensure high-quality, consistent implementation across all development work. Great work capturing your project's critical implementation requirements!"
+
+## SUCCESS METRICS:
+
+✅ Complete project context file with all critical rules
+✅ Content optimized for LLM context efficiency
+✅ All technology versions and patterns documented
+✅ File structure is logical and scannable
+✅ Usage guidelines included for agents and humans
+✅ Frontmatter properly updated with completion status
+✅ User provided with clear next steps and benefits
+
+## FAILURE MODES:
+
+❌ Final content is too verbose for LLM consumption
+❌ Missing critical implementation rules or patterns
+❌ Not optimizing content for agent readability
+❌ Not providing clear usage guidelines
+❌ Frontmatter not properly updated
+❌ Not validating file completion before ending
+
+## WORKFLOW COMPLETE:
+
+This is the final step of the Generate Project Context workflow. The user now has a comprehensive, optimized project context file that will ensure consistent, high-quality implementation across all AI agents working on the project.
+
+The project context file serves as the critical "rules of the road" that agents need to implement code consistently with the project's standards and patterns.

package/src/modules/bmm/workflows/generate-project-context/workflow.md

@@ -0,0 +1,48 @@
+---
+name: generate-project-context
+description: Creates a concise project_context.md file with critical rules and patterns that AI agents must follow when implementing code. Optimized for LLM context efficiency.
+---
+
+# Generate Project Context Workflow
+
+**Goal:** Create a concise, optimized `project_context.md` file containing critical rules, patterns, and guidelines that AI agents must follow when implementing code. This file focuses on unobvious details that LLMs need to be reminded of.
+
+**Your Role:** You are a technical facilitator working with a peer to capture the essential implementation rules that will ensure consistent, high-quality code generation across all AI agents working on the project.
+
+---
+
+## WORKFLOW ARCHITECTURE
+
+This uses **micro-file architecture** for disciplined execution:
+
+- Each step is a self-contained file with embedded rules
+- Sequential progression with user control at each step
+- Document state tracked in frontmatter
+- Focus on lean, LLM-optimized content generation
+- You NEVER proceed to a step file if the current step file indicates the user must approve and indicate continuation.
+
+---
+
+## INITIALIZATION
+
+### Configuration Loading
+
+Load config from `{project-root}/{bmad_folder}/bmm/config.yaml` and resolve:
+
+- `project_name`, `output_folder`, `user_name`
+- `communication_language`, `document_output_language`, `user_skill_level`
+- `date` as system-generated current datetime
+
+### Paths
+
+- `installed_path` = `{project-root}/{bmad_folder}/bmm/workflows/generate-project-context`
+- `template_path` = `{installed_path}/project-context-template.md`
+- `output_file` = `{output_folder}/project_context.md`
+
+---
+
+## EXECUTION
+
+Load and execute `steps/step-01-discover.md` to begin the workflow.
+
+**Note:** Input document discovery and initialization protocols are handled in step-01-discover.md.

package/src/modules/bmm/workflows/testarch/atdd/atdd-checklist-template.md

@@ -296,7 +296,7 @@ test('should do something', async ({ {fixtureName} }) => {
 4. **Work one test at a time** (red → green for each)
 5. **Share progress** in daily standup
 6. **When all tests pass**, refactor code for quality
-7. **When refactoring complete**, run `bmad sm story-done` to move story to DONE
+7. **When refactoring complete**, manually update story status to 'done' in sprint-status.yaml
 
 ---
 

package/src/modules/bmm/workflows/testarch/atdd/instructions.md

@@ -48,18 +48,38 @@ Generates failing acceptance tests BEFORE implementation following TDD's red-gre
    - Check data factory patterns
    - Note naming conventions
 
-4. **Load Knowledge Base Fragments**
+4. **Check Playwright Utils Flag**
+
+   Read `{config_source}` and check `config.tea_use_playwright_utils`.
+
+5. **Load Knowledge Base Fragments**
 
    **Critical:** Consult `{project-root}/{bmad_folder}/bmm/testarch/tea-index.csv` to load:
-   - `fixture-architecture.md` - Test fixture patterns with auto-cleanup (pure function → fixture → mergeTests composition, 406 lines, 5 examples)
+
+   **Core Patterns (Always load):**
    - `data-factories.md` - Factory patterns using faker (override patterns, nested factories, API seeding, 498 lines, 5 examples)
    - `component-tdd.md` - Component test strategies (red-green-refactor, provider isolation, accessibility, visual regression, 480 lines, 4 examples)
-   - `network-first.md` - Route interception patterns (intercept before navigate, HAR capture, deterministic waiting, 489 lines, 5 examples)
    - `test-quality.md` - Test design principles (deterministic tests, isolated with cleanup, explicit assertions, length limits, execution time optimization, 658 lines, 5 examples)
    - `test-healing-patterns.md` - Common failure patterns and healing strategies (stale selectors, race conditions, dynamic data, network errors, hard waits, 648 lines, 5 examples)
    - `selector-resilience.md` - Selector best practices (data-testid > ARIA > text > CSS hierarchy, dynamic patterns, anti-patterns, 541 lines, 4 examples)
    - `timing-debugging.md` - Race condition prevention and async debugging (network-first, deterministic waiting, anti-patterns, 370 lines, 3 examples)
 
+   **If `config.tea_use_playwright_utils: true` (All Utilities):**
+   - `overview.md` - Playwright utils for ATDD patterns
+   - `api-request.md` - API test examples with schema validation
+   - `network-recorder.md` - HAR record/playback for UI acceptance tests
+   - `auth-session.md` - Auth setup for acceptance tests
+   - `intercept-network-call.md` - Network interception in ATDD scenarios
+   - `recurse.md` - Polling for async acceptance criteria
+   - `log.md` - Logging in ATDD tests
+   - `file-utils.md` - File download validation in acceptance tests
+   - `network-error-monitor.md` - Catch silent failures in ATDD
+   - `fixtures-composition.md` - Composing utilities for ATDD
+
+   **If `config.tea_use_playwright_utils: false`:**
+   - `fixture-architecture.md` - Test fixture patterns with auto-cleanup (pure function → fixture → mergeTests composition, 406 lines, 5 examples)
+   - `network-first.md` - Route interception patterns (intercept before navigate, HAR capture, deterministic waiting, 489 lines, 5 examples)
+
 **Halt Condition:** If story has no acceptance criteria or framework is missing, HALT with message: "ATDD requires clear acceptance criteria and test framework setup"
 
 ---

package/src/modules/bmm/workflows/testarch/automate/instructions.md

@@ -81,16 +81,37 @@ Expands test automation coverage by generating comprehensive test suites at appr
    - Map tests to source files (coverage gaps)
    - Check existing fixture and factory patterns
 
-5. **Load Knowledge Base Fragments**
+5. **Check Playwright Utils Flag**
+
+   Read `{config_source}` and check `config.tea_use_playwright_utils`.
+
+6. **Load Knowledge Base Fragments**
 
    **Critical:** Consult `{project-root}/{bmad_folder}/bmm/testarch/tea-index.csv` to load:
+
+   **Core Testing Patterns (Always load):**
    - `test-levels-framework.md` - Test level selection (E2E vs API vs Component vs Unit with decision matrix, 467 lines, 4 examples)
    - `test-priorities-matrix.md` - Priority classification (P0-P3 with automated scoring, risk mapping, 389 lines, 2 examples)
-   - `fixture-architecture.md` - Test fixture patterns (pure function → fixture → mergeTests, auto-cleanup, 406 lines, 5 examples)
    - `data-factories.md` - Factory patterns with faker (overrides, nested factories, API seeding, 498 lines, 5 examples)
    - `selective-testing.md` - Targeted test execution strategies (tag-based, spec filters, diff-based, promotion rules, 727 lines, 4 examples)
    - `ci-burn-in.md` - Flaky test detection patterns (10-iteration burn-in, sharding, selective execution, 678 lines, 4 examples)
    - `test-quality.md` - Test design principles (deterministic, isolated, explicit assertions, length/time limits, 658 lines, 5 examples)
+
+   **If `config.tea_use_playwright_utils: true` (Playwright Utils Integration - All Utilities):**
+   - `overview.md` - Playwright utils installation, design principles, fixture patterns
+   - `api-request.md` - Typed HTTP client with schema validation
+   - `network-recorder.md` - HAR record/playback for offline testing
+   - `auth-session.md` - Token persistence and multi-user support
+   - `intercept-network-call.md` - Network spy/stub with automatic JSON parsing
+   - `recurse.md` - Cypress-style polling for async conditions
+   - `log.md` - Playwright report-integrated logging
+   - `file-utils.md` - CSV/XLSX/PDF/ZIP reading and validation
+   - `burn-in.md` - Smart test selection (relevant for CI test generation)
+   - `network-error-monitor.md` - Automatic HTTP error detection
+   - `fixtures-composition.md` - mergeTests composition patterns
+
+   **If `config.tea_use_playwright_utils: false` (Traditional Patterns):**
+   - `fixture-architecture.md` - Test fixture patterns (pure function → fixture → mergeTests, auto-cleanup, 406 lines, 5 examples)
    - `network-first.md` - Route interception patterns (intercept before navigate, HAR capture, deterministic waiting, 489 lines, 5 examples)
 
    **Healing Knowledge (If `{auto_heal_failures}` is true):**

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

@@ -4,7 +4,7 @@
 
 - [ ] Git repository initialized (`.git/` exists)
 - [ ] Git remote configured (`git remote -v` shows origin)
-- [ ] Test framework configured (playwright.config._ or cypress.config._)
+- [ ] Test framework configured (`playwright.config._` or `cypress.config._`)
 - [ ] Local tests pass (`npm run test:e2e` succeeds)
 - [ ] Team agrees on CI platform
 - [ ] Access to CI platform settings (if updating)

package/src/modules/bmm/workflows/testarch/ci/github-actions-template.yaml

@@ -27,10 +27,21 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Determine Node version
+        id: node-version
+        run: |
+          if [ -f .nvmrc ]; then
+            echo "value=$(cat .nvmrc)" >> "$GITHUB_OUTPUT"
+            echo "Using Node from .nvmrc"
+          else
+            echo "value=24" >> "$GITHUB_OUTPUT"
+            echo "Using default Node 24 (current LTS)"
+          fi
+
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version-file: ".nvmrc"
+          node-version: ${{ steps.node-version.outputs.value }}
           cache: "npm"
 
       - name: Install dependencies
@@ -54,10 +65,21 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Determine Node version
+        id: node-version
+        run: |
+          if [ -f .nvmrc ]; then
+            echo "value=$(cat .nvmrc)" >> "$GITHUB_OUTPUT"
+            echo "Using Node from .nvmrc"
+          else
+            echo "value=22" >> "$GITHUB_OUTPUT"
+            echo "Using default Node 22 (current LTS)"
+          fi
+
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version-file: ".nvmrc"
+          node-version: ${{ steps.node-version.outputs.value }}
           cache: "npm"
 
       - name: Cache Playwright browsers
@@ -99,10 +121,21 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Determine Node version
+        id: node-version
+        run: |
+          if [ -f .nvmrc ]; then
+            echo "value=$(cat .nvmrc)" >> "$GITHUB_OUTPUT"
+            echo "Using Node from .nvmrc"
+          else
+            echo "value=22" >> "$GITHUB_OUTPUT"
+            echo "Using default Node 22 (current LTS)"
+          fi
+
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version-file: ".nvmrc"
+          node-version: ${{ steps.node-version.outputs.value }}
           cache: "npm"
 
       - name: Cache Playwright browsers

package/src/modules/bmm/workflows/testarch/ci/gitlab-ci-template.yaml

@@ -15,6 +15,8 @@ variables:
   npm_config_cache: "$CI_PROJECT_DIR/.npm"
   # Playwright browser cache
   PLAYWRIGHT_BROWSERS_PATH: "$CI_PROJECT_DIR/.cache/ms-playwright"
+  # Default Node version when .nvmrc is missing
+  DEFAULT_NODE_VERSION: "24"
 
 # Caching configuration
 cache:
@@ -29,19 +31,32 @@ cache:
 # Lint stage - Code quality checks
 lint:
   stage: lint
-  image: node:20
-  script:
+  image: node:$DEFAULT_NODE_VERSION
+  before_script:
+    - |
+      NODE_VERSION=$(cat .nvmrc 2>/dev/null || echo "$DEFAULT_NODE_VERSION")
+      echo "Using Node $NODE_VERSION"
+      npm install -g n
+      n "$NODE_VERSION"
+      node -v
     - npm ci
+  script:
     - npm run lint
   timeout: 5 minutes
 
 # Test stage - Parallel execution with sharding
 .test-template: &test-template
   stage: test
-  image: node:20
+  image: node:$DEFAULT_NODE_VERSION
   needs:
     - lint
   before_script:
+    - |
+      NODE_VERSION=$(cat .nvmrc 2>/dev/null || echo "$DEFAULT_NODE_VERSION")
+      echo "Using Node $NODE_VERSION"
+      npm install -g n
+      n "$NODE_VERSION"
+      node -v
     - npm ci
     - npx playwright install --with-deps chromium
   artifacts:
@@ -75,7 +90,7 @@ test:shard-4:
 # Burn-in stage - Flaky test detection
 burn-in:
   stage: burn-in
-  image: node:20
+  image: node:$DEFAULT_NODE_VERSION
   needs:
     - test:shard-1
     - test:shard-2
@@ -86,6 +101,12 @@ burn-in:
     - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
     - if: '$CI_PIPELINE_SOURCE == "schedule"'
   before_script:
+    - |
+      NODE_VERSION=$(cat .nvmrc 2>/dev/null || echo "$DEFAULT_NODE_VERSION")
+      echo "Using Node $NODE_VERSION"
+      npm install -g n
+      n "$NODE_VERSION"
+      node -v
     - npm ci
     - npx playwright install --with-deps chromium
   script:

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

@@ -61,8 +61,8 @@ Scaffolds a production-ready CI/CD quality pipeline with test execution, burn-in
      - Ask user if unable to auto-detect
 
 5. **Read Environment Configuration**
-   - Check for `.nvmrc` to determine Node version
-   - Default to Node 20 LTS if not found
+   - Use `.nvmrc` for Node version if present
+   - If missing, default to a current LTS (Node 24) or newer instead of a fixed old version
    - Read `package.json` to identify dependencies (affects caching strategy)
 
 **Halt Condition:** If preflight checks fail, stop immediately and report which requirement failed.
@@ -353,7 +353,11 @@ Scaffolds a production-ready CI/CD quality pipeline with test execution, burn-in
 
 ### Knowledge Base Integration
 
-**Critical:** Consult `{project-root}/{bmad_folder}/bmm/testarch/tea-index.csv` to identify and load relevant knowledge fragments:
+**Critical:** Check configuration and load appropriate fragments.
+
+Read `{config_source}` and check `config.tea_use_playwright_utils`.
+
+**Core CI Patterns (Always load):**
 
 - `ci-burn-in.md` - Burn-in loop patterns: 10-iteration detection, GitHub Actions workflow, shard orchestration, selective execution (678 lines, 4 examples)
 - `selective-testing.md` - Changed test detection strategies: tag-based, spec filters, diff-based selection, promotion rules (727 lines, 4 examples)
@@ -361,6 +365,19 @@ Scaffolds a production-ready CI/CD quality pipeline with test execution, burn-in
 - `test-quality.md` - CI-specific test quality criteria: deterministic tests, isolated with cleanup, explicit assertions, length/time optimization (658 lines, 5 examples)
 - `playwright-config.md` - CI-optimized configuration: parallelization, artifact output, project dependencies, sharding (722 lines, 5 examples)
 
+**If `config.tea_use_playwright_utils: true`:**
+
+Load playwright-utils CI-relevant fragments:
+
+- `burn-in.md` - Smart test selection with git diff analysis (very important for CI optimization)
+- `network-error-monitor.md` - Automatic HTTP 4xx/5xx detection (recommend in CI pipelines)
+
+Recommend:
+
+- Add burn-in script for pull request validation
+- Enable network-error-monitor in merged fixtures for catching silent failures
+- Reference full docs in `*framework` and `*automate` workflows
+
 ### CI Platform-Specific Guidance
 
 **GitHub Actions:**

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

@@ -349,7 +349,33 @@ The generated `tests/README.md` should include:
 
 ### Knowledge Base Integration
 
-**Critical:** Consult `{project-root}/{bmad_folder}/bmm/testarch/tea-index.csv` to identify and load relevant knowledge fragments:
+**Critical:** Check configuration and load appropriate fragments.
+
+Read `{config_source}` and check `config.tea_use_playwright_utils`.
+
+**If `config.tea_use_playwright_utils: true` (Playwright Utils Integration):**
+
+Consult `{project-root}/{bmad_folder}/bmm/testarch/tea-index.csv` and load:
+
+- `overview.md` - Playwright utils installation and design principles
+- `fixtures-composition.md` - mergeTests composition with playwright-utils
+- `auth-session.md` - Token persistence setup (if auth needed)
+- `api-request.md` - API testing utilities (if API tests planned)
+- `burn-in.md` - Smart test selection for CI (recommend during framework setup)
+- `network-error-monitor.md` - Automatic HTTP error detection (recommend in merged fixtures)
+- `data-factories.md` - Factory patterns with faker (498 lines, 5 examples)
+
+Recommend installing playwright-utils:
+
+```bash
+npm install -D @seontechnologies/playwright-utils
+```
+
+Recommend adding burn-in and network-error-monitor to merged fixtures for enhanced reliability.
+
+**If `config.tea_use_playwright_utils: false` (Traditional Patterns):**
+
+Consult `{project-root}/{bmad_folder}/bmm/testarch/tea-index.csv` and load:
 
 - `fixture-architecture.md` - Pure function → fixture → `mergeTests` composition with auto-cleanup (406 lines, 5 examples)
 - `data-factories.md` - Faker-based factories with overrides, nested factories, API seeding, auto-cleanup (498 lines, 5 examples)

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

@@ -66,7 +66,13 @@ The workflow auto-detects which mode to use based on project phase.
    - Note integration points and external system dependencies
    - Extract NFR requirements (performance SLOs, security requirements, etc.)
 
-2. **Load Knowledge Base Fragments (System-Level)**
+2. **Check Playwright Utils Flag**
+
+   Read `{config_source}` and check `config.tea_use_playwright_utils`.
+
+   If true, note that `@seontechnologies/playwright-utils` provides utilities for test implementation. Reference in test design where relevant.
+
+3. **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)
@@ -74,7 +80,7 @@ The workflow auto-detects which mode to use based on project phase.
    - `risk-governance.md` - Testability risk identification
    - `test-quality.md` - Quality standards and Definition of Done
 
-3. **Analyze Existing Test Setup (if brownfield)**
+4. **Analyze Existing Test Setup (if brownfield)**
    - Search for existing test directories
    - Identify current test framework (if any)
    - Note testability concerns in existing codebase