bmad-method 6.0.0-alpha.11 → 6.0.0-alpha.13

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/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/instructions.md

@@ -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

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

@@ -49,31 +49,51 @@ This workflow performs comprehensive test quality reviews using TEA's knowledge
 
 **Actions:**
 
-1. Load relevant knowledge fragments from `{project-root}/{bmad_folder}/bmm/testarch/tea-index.csv`:
+1. Check playwright-utils flag:
+   - Read `{config_source}` and check `config.tea_use_playwright_utils`
+
+2. Load relevant knowledge fragments from `{project-root}/{bmad_folder}/bmm/testarch/tea-index.csv`:
+
+   **Core Patterns (Always load):**
    - `test-quality.md` - Definition of Done (deterministic tests, isolated with cleanup, explicit assertions, <300 lines, <1.5 min, 658 lines, 5 examples)
-   - `fixture-architecture.md` - Pure function → Fixture → mergeTests composition with auto-cleanup (406 lines, 5 examples)
-   - `network-first.md` - Route intercept before navigate to prevent race conditions (intercept before navigate, HAR capture, deterministic waiting, 489 lines, 5 examples)
    - `data-factories.md` - Factory functions with faker: overrides, nested factories, API-first setup (498 lines, 5 examples)
    - `test-levels-framework.md` - E2E vs API vs Component vs Unit appropriateness with decision matrix (467 lines, 4 examples)
-   - `playwright-config.md` - Environment-based configuration with fail-fast validation (722 lines, 5 examples)
-   - `component-tdd.md` - Red-Green-Refactor patterns with provider isolation, accessibility, visual regression (480 lines, 4 examples)
    - `selective-testing.md` - Duplicate coverage detection with tag-based, spec filter, diff-based selection (727 lines, 4 examples)
    - `test-healing-patterns.md` - Common failure patterns: 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, anti-patterns, 541 lines, 4 examples)
    - `timing-debugging.md` - Race condition prevention and async debugging techniques (370 lines, 3 examples)
+
+   **If `config.tea_use_playwright_utils: true` (All Utilities):**
+   - `overview.md` - Playwright utils best practices
+   - `api-request.md` - Validate apiRequest usage patterns
+   - `network-recorder.md` - Review HAR record/playback implementation
+   - `auth-session.md` - Check auth token management
+   - `intercept-network-call.md` - Validate network interception
+   - `recurse.md` - Review polling patterns
+   - `log.md` - Check logging best practices
+   - `file-utils.md` - Validate file operation patterns
+   - `burn-in.md` - Review burn-in configuration
+   - `network-error-monitor.md` - Check error monitoring setup
+   - `fixtures-composition.md` - Validate mergeTests usage
+
+   **If `config.tea_use_playwright_utils: false`:**
+   - `fixture-architecture.md` - Pure function → Fixture → mergeTests composition with auto-cleanup (406 lines, 5 examples)
+   - `network-first.md` - Route intercept before navigate to prevent race conditions (489 lines, 5 examples)
+   - `playwright-config.md` - Environment-based configuration with fail-fast validation (722 lines, 5 examples)
+   - `component-tdd.md` - Red-Green-Refactor patterns with provider isolation (480 lines, 4 examples)
    - `ci-burn-in.md` - Flaky test detection with 10-iteration burn-in loop (678 lines, 4 examples)
 
-2. Determine review scope:
+3. Determine review scope:
    - **single**: Review one test file (`test_file_path` provided)
    - **directory**: Review all tests in directory (`test_dir` provided)
    - **suite**: Review entire test suite (discover all test files)
 
-3. Auto-discover related artifacts (if `auto_discover_story: true`):
+4. Auto-discover related artifacts (if `auto_discover_story: true`):
    - Extract test ID from filename (e.g., `1.3-E2E-001.spec.ts` → story 1.3)
    - Search for story file (`story-1.3.md`)
    - Search for test design (`test-design-story-1.3.md` or `test-design-epic-1.md`)
 
-4. Read story file for context (if available):
+5. Read story file for context (if available):
    - Extract acceptance criteria
    - Extract priority classification
    - Extract expected test IDs