bmadV6

.claude/commands/BMad/bmm/agents/analyst.md

@@ -0,0 +1,14 @@
+---
+name: 'analyst'
+description: 'analyst agent'
+---
+
+You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
+
+<agent-activation CRITICAL="TRUE">
+1. LOAD the FULL agent file from @_bmad/bmm/agents/analyst.md
+2. READ its entire contents - this contains the complete agent persona, menu, and instructions
+3. Execute ALL activation steps exactly as written in the agent file
+4. Follow the agent's persona and menu system precisely
+5. Stay in character throughout the session
+</agent-activation>

.claude/commands/BMad/bmm/agents/architect.md

@@ -0,0 +1,14 @@
+---
+name: 'architect'
+description: 'architect agent'
+---
+
+You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
+
+<agent-activation CRITICAL="TRUE">
+1. LOAD the FULL agent file from @_bmad/bmm/agents/architect.md
+2. READ its entire contents - this contains the complete agent persona, menu, and instructions
+3. Execute ALL activation steps exactly as written in the agent file
+4. Follow the agent's persona and menu system precisely
+5. Stay in character throughout the session
+</agent-activation>

.claude/commands/BMad/bmm/agents/dev.md

@@ -0,0 +1,14 @@
+---
+name: 'dev'
+description: 'dev agent'
+---
+
+You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
+
+<agent-activation CRITICAL="TRUE">
+1. LOAD the FULL agent file from @_bmad/bmm/agents/dev.md
+2. READ its entire contents - this contains the complete agent persona, menu, and instructions
+3. Execute ALL activation steps exactly as written in the agent file
+4. Follow the agent's persona and menu system precisely
+5. Stay in character throughout the session
+</agent-activation>

.claude/commands/BMad/bmm/agents/pm.md

@@ -0,0 +1,14 @@
+---
+name: 'pm'
+description: 'pm agent'
+---
+
+You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
+
+<agent-activation CRITICAL="TRUE">
+1. LOAD the FULL agent file from @_bmad/bmm/agents/pm.md
+2. READ its entire contents - this contains the complete agent persona, menu, and instructions
+3. Execute ALL activation steps exactly as written in the agent file
+4. Follow the agent's persona and menu system precisely
+5. Stay in character throughout the session
+</agent-activation>

.claude/commands/BMad/bmm/agents/quick-flow-solo-dev.md

@@ -0,0 +1,14 @@
+---
+name: 'quick-flow-solo-dev'
+description: 'quick-flow-solo-dev agent'
+---
+
+You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
+
+<agent-activation CRITICAL="TRUE">
+1. LOAD the FULL agent file from @_bmad/bmm/agents/quick-flow-solo-dev.md
+2. READ its entire contents - this contains the complete agent persona, menu, and instructions
+3. Execute ALL activation steps exactly as written in the agent file
+4. Follow the agent's persona and menu system precisely
+5. Stay in character throughout the session
+</agent-activation>

.claude/commands/BMad/bmm/agents/sm.md

@@ -0,0 +1,14 @@
+---
+name: 'sm'
+description: 'sm agent'
+---
+
+You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
+
+<agent-activation CRITICAL="TRUE">
+1. LOAD the FULL agent file from @_bmad/bmm/agents/sm.md
+2. READ its entire contents - this contains the complete agent persona, menu, and instructions
+3. Execute ALL activation steps exactly as written in the agent file
+4. Follow the agent's persona and menu system precisely
+5. Stay in character throughout the session
+</agent-activation>

.claude/commands/BMad/bmm/agents/tea.md

@@ -0,0 +1,14 @@
+---
+name: 'tea'
+description: 'tea agent'
+---
+
+You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
+
+<agent-activation CRITICAL="TRUE">
+1. LOAD the FULL agent file from @_bmad/bmm/agents/tea.md
+2. READ its entire contents - this contains the complete agent persona, menu, and instructions
+3. Execute ALL activation steps exactly as written in the agent file
+4. Follow the agent's persona and menu system precisely
+5. Stay in character throughout the session
+</agent-activation>

.claude/commands/BMad/bmm/agents/tech-writer.md

@@ -0,0 +1,14 @@
+---
+name: 'tech-writer'
+description: 'tech-writer agent'
+---
+
+You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
+
+<agent-activation CRITICAL="TRUE">
+1. LOAD the FULL agent file from @_bmad/bmm/agents/tech-writer.md
+2. READ its entire contents - this contains the complete agent persona, menu, and instructions
+3. Execute ALL activation steps exactly as written in the agent file
+4. Follow the agent's persona and menu system precisely
+5. Stay in character throughout the session
+</agent-activation>

.claude/commands/BMad/bmm/agents/ux-designer.md

@@ -0,0 +1,14 @@
+---
+name: 'ux-designer'
+description: 'ux-designer agent'
+---
+
+You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
+
+<agent-activation CRITICAL="TRUE">
+1. LOAD the FULL agent file from @_bmad/bmm/agents/ux-designer.md
+2. READ its entire contents - this contains the complete agent persona, menu, and instructions
+3. Execute ALL activation steps exactly as written in the agent file
+4. Follow the agent's persona and menu system precisely
+5. Stay in character throughout the session
+</agent-activation>

.claude/commands/BMad/bmm/workflows/check-implementation-readiness.md

@@ -0,0 +1,5 @@
+---
+description: 'Critical validation workflow that assesses PRD, Architecture, and Epics & Stories for completeness and alignment before implementation. Uses adversarial review approach to find gaps and issues.'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: LOAD the FULL @_bmad/bmm/workflows/3-solutioning/check-implementation-readiness/workflow.md, READ its entire contents and follow its directions exactly!

.claude/commands/BMad/bmm/workflows/code-review.md

@@ -0,0 +1,13 @@
+---
+description: 'Perform an ADVERSARIAL Senior Developer code review that finds 3-10 specific problems in every story. Challenges everything: code quality, test coverage, architecture compliance, security, performance. NEVER accepts `looks good` - must find minimum issues and can auto-fix with user approval.'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL @_bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @_bmad/bmm/workflows/4-implementation/code-review/workflow.yaml
+3. Pass the yaml path _bmad/bmm/workflows/4-implementation/code-review/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

.claude/commands/BMad/bmm/workflows/correct-course.md

@@ -0,0 +1,13 @@
+---
+description: 'Navigate significant changes during sprint execution by analyzing impact, proposing solutions, and routing for implementation'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL @_bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @_bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml
+3. Pass the yaml path _bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

.claude/commands/BMad/bmm/workflows/create-architecture.md

@@ -0,0 +1,5 @@
+---
+description: 'Collaborative architectural decision facilitation for AI-agent consistency. Replaces template-driven architecture with intelligent, adaptive conversation that produces a decision-focused architecture document optimized for preventing agent conflicts.'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: LOAD the FULL @_bmad/bmm/workflows/3-solutioning/create-architecture/workflow.md, READ its entire contents and follow its directions exactly!

.claude/commands/BMad/bmm/workflows/create-epics-and-stories.md

@@ -0,0 +1,5 @@
+---
+description: 'Transform PRD requirements and Architecture decisions into comprehensive stories organized by user value. This workflow requires completed PRD + Architecture documents (UX recommended if UI exists) and breaks down requirements into implementation-ready epics and user stories that incorporate all available technical and design context. Creates detailed, actionable stories with complete acceptance criteria for development teams.'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: LOAD the FULL @_bmad/bmm/workflows/3-solutioning/create-epics-and-stories/workflow.md, READ its entire contents and follow its directions exactly!

.claude/commands/BMad/bmm/workflows/create-excalidraw-dataflow.md

@@ -0,0 +1,13 @@
+---
+description: 'Create data flow diagrams (DFD) in Excalidraw format'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL @_bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @_bmad/bmm/workflows/excalidraw-diagrams/create-dataflow/workflow.yaml
+3. Pass the yaml path _bmad/bmm/workflows/excalidraw-diagrams/create-dataflow/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

.claude/commands/BMad/bmm/workflows/create-excalidraw-diagram.md

@@ -0,0 +1,13 @@
+---
+description: 'Create system architecture diagrams, ERDs, UML diagrams, or general technical diagrams in Excalidraw format'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL @_bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @_bmad/bmm/workflows/excalidraw-diagrams/create-diagram/workflow.yaml
+3. Pass the yaml path _bmad/bmm/workflows/excalidraw-diagrams/create-diagram/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

.claude/commands/BMad/bmm/workflows/create-excalidraw-flowchart.md

@@ -0,0 +1,13 @@
+---
+description: 'Create a flowchart visualization in Excalidraw format for processes, pipelines, or logic flows'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL @_bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @_bmad/bmm/workflows/excalidraw-diagrams/create-flowchart/workflow.yaml
+3. Pass the yaml path _bmad/bmm/workflows/excalidraw-diagrams/create-flowchart/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

.claude/commands/BMad/bmm/workflows/create-excalidraw-wireframe.md

@@ -0,0 +1,13 @@
+---
+description: 'Create website or app wireframes in Excalidraw format'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL @_bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @_bmad/bmm/workflows/excalidraw-diagrams/create-wireframe/workflow.yaml
+3. Pass the yaml path _bmad/bmm/workflows/excalidraw-diagrams/create-wireframe/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

.claude/commands/BMad/bmm/workflows/create-prd.md

@@ -0,0 +1,5 @@
+---
+description: 'Creates a comprehensive PRD through collaborative step-by-step discovery between two product managers working as peers.'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: LOAD the FULL @_bmad/bmm/workflows/2-plan-workflows/prd/workflow.md, READ its entire contents and follow its directions exactly!

.claude/commands/BMad/bmm/workflows/create-product-brief.md

@@ -0,0 +1,5 @@
+---
+description: 'Create comprehensive product briefs through collaborative step-by-step discovery as creative Business Analyst working with the user as peers.'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: LOAD the FULL @_bmad/bmm/workflows/1-analysis/create-product-brief/workflow.md, READ its entire contents and follow its directions exactly!

.claude/commands/BMad/bmm/workflows/create-story.md

@@ -0,0 +1,13 @@
+---
+description: 'Create the next user story from epics+stories with enhanced context analysis and direct ready-for-dev marking'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL @_bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @_bmad/bmm/workflows/4-implementation/create-story/workflow.yaml
+3. Pass the yaml path _bmad/bmm/workflows/4-implementation/create-story/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

.claude/commands/BMad/bmm/workflows/create-tech-spec.md

@@ -0,0 +1,5 @@
+---
+description: 'Conversational spec engineering - ask questions, investigate code, produce implementation-ready tech-spec.'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: LOAD the FULL @_bmad/bmm/workflows/bmad-quick-flow/create-tech-spec/workflow.md, READ its entire contents and follow its directions exactly!

.claude/commands/BMad/bmm/workflows/create-ux-design.md

@@ -0,0 +1,5 @@
+---
+description: 'Work with a peer UX Design expert to plan your applications UX patterns, look and feel.'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: LOAD the FULL @_bmad/bmm/workflows/2-plan-workflows/create-ux-design/workflow.md, READ its entire contents and follow its directions exactly!

.claude/commands/BMad/bmm/workflows/dev-story.md

@@ -0,0 +1,13 @@
+---
+description: 'Execute a story by implementing tasks/subtasks, writing tests, validating, and updating the story file per acceptance criteria'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL @_bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @_bmad/bmm/workflows/4-implementation/dev-story/workflow.yaml
+3. Pass the yaml path _bmad/bmm/workflows/4-implementation/dev-story/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

.claude/commands/BMad/bmm/workflows/document-project.md

@@ -0,0 +1,13 @@
+---
+description: 'Analyzes and documents brownfield projects by scanning codebase, architecture, and patterns to create comprehensive reference documentation for AI-assisted development'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL @_bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @_bmad/bmm/workflows/document-project/workflow.yaml
+3. Pass the yaml path _bmad/bmm/workflows/document-project/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

.claude/commands/BMad/bmm/workflows/generate-project-context.md

@@ -0,0 +1,5 @@
+---
+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.'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: LOAD the FULL @_bmad/bmm/workflows/generate-project-context/workflow.md, READ its entire contents and follow its directions exactly!

.claude/commands/BMad/bmm/workflows/quick-dev.md

@@ -0,0 +1,5 @@
+---
+description: 'Flexible development - execute tech-specs OR direct instructions with optional planning.'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: LOAD the FULL @_bmad/bmm/workflows/bmad-quick-flow/quick-dev/workflow.md, READ its entire contents and follow its directions exactly!

.claude/commands/BMad/bmm/workflows/research.md

@@ -0,0 +1,5 @@
+---
+description: 'Conduct comprehensive research across multiple domains using current web data and verified sources - Market, Technical, Domain and other research types.'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: LOAD the FULL @_bmad/bmm/workflows/1-analysis/research/workflow.md, READ its entire contents and follow its directions exactly!

.claude/commands/BMad/bmm/workflows/retrospective.md

@@ -0,0 +1,13 @@
+---
+description: 'Run after epic completion to review overall success, extract lessons learned, and explore if new information emerged that might impact the next epic'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL @_bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @_bmad/bmm/workflows/4-implementation/retrospective/workflow.yaml
+3. Pass the yaml path _bmad/bmm/workflows/4-implementation/retrospective/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

.claude/commands/BMad/bmm/workflows/sprint-planning.md

@@ -0,0 +1,13 @@
+---
+description: 'Generate and manage the sprint status tracking file for Phase 4 implementation, extracting all epics and stories from epic files and tracking their status through the development lifecycle'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL @_bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @_bmad/bmm/workflows/4-implementation/sprint-planning/workflow.yaml
+3. Pass the yaml path _bmad/bmm/workflows/4-implementation/sprint-planning/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

.claude/commands/BMad/bmm/workflows/sprint-status.md

@@ -0,0 +1,13 @@
+---
+description: 'Summarize sprint-status.yaml, surface risks, and route to the right implementation workflow.'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL @_bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @_bmad/bmm/workflows/4-implementation/sprint-status/workflow.yaml
+3. Pass the yaml path _bmad/bmm/workflows/4-implementation/sprint-status/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

.claude/commands/BMad/bmm/workflows/testarch-atdd.md

@@ -0,0 +1,13 @@
+---
+description: 'Generate failing acceptance tests before implementation using TDD red-green-refactor cycle'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL @_bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @_bmad/bmm/workflows/testarch/atdd/workflow.yaml
+3. Pass the yaml path _bmad/bmm/workflows/testarch/atdd/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

.claude/commands/BMad/bmm/workflows/testarch-automate.md

@@ -0,0 +1,13 @@
+---
+description: 'Expand test automation coverage after implementation or analyze existing codebase to generate comprehensive test suite'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL @_bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @_bmad/bmm/workflows/testarch/automate/workflow.yaml
+3. Pass the yaml path _bmad/bmm/workflows/testarch/automate/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

.claude/commands/BMad/bmm/workflows/testarch-ci.md

@@ -0,0 +1,13 @@
+---
+description: 'Scaffold CI/CD quality pipeline with test execution, burn-in loops, and artifact collection'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL @_bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @_bmad/bmm/workflows/testarch/ci/workflow.yaml
+3. Pass the yaml path _bmad/bmm/workflows/testarch/ci/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

.claude/commands/BMad/bmm/workflows/testarch-framework.md

@@ -0,0 +1,13 @@
+---
+description: 'Initialize production-ready test framework architecture (Playwright or Cypress) with fixtures, helpers, and configuration'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL @_bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @_bmad/bmm/workflows/testarch/framework/workflow.yaml
+3. Pass the yaml path _bmad/bmm/workflows/testarch/framework/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

.claude/commands/BMad/bmm/workflows/testarch-nfr.md

@@ -0,0 +1,13 @@
+---
+description: 'Assess non-functional requirements (performance, security, reliability, maintainability) before release with evidence-based validation'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL @_bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @_bmad/bmm/workflows/testarch/nfr-assess/workflow.yaml
+3. Pass the yaml path _bmad/bmm/workflows/testarch/nfr-assess/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

.claude/commands/BMad/bmm/workflows/testarch-test-design.md

@@ -0,0 +1,13 @@
+---
+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.'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL @_bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @_bmad/bmm/workflows/testarch/test-design/workflow.yaml
+3. Pass the yaml path _bmad/bmm/workflows/testarch/test-design/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

.claude/commands/BMad/bmm/workflows/testarch-test-review.md

@@ -0,0 +1,13 @@
+---
+description: 'Review test quality using comprehensive knowledge base and best practices validation'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL @_bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @_bmad/bmm/workflows/testarch/test-review/workflow.yaml
+3. Pass the yaml path _bmad/bmm/workflows/testarch/test-review/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

.claude/commands/BMad/bmm/workflows/testarch-trace.md

@@ -0,0 +1,13 @@
+---
+description: 'Generate requirements-to-tests traceability matrix, analyze coverage, and make quality gate decision (PASS/CONCERNS/FAIL/WAIVED)'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL @_bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @_bmad/bmm/workflows/testarch/trace/workflow.yaml
+3. Pass the yaml path _bmad/bmm/workflows/testarch/trace/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

.claude/commands/BMad/bmm/workflows/workflow-init.md

@@ -0,0 +1,13 @@
+---
+description: 'Initialize a new BMM project by determining level, type, and creating workflow path'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL @_bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @_bmad/bmm/workflows/workflow-status/init/workflow.yaml
+3. Pass the yaml path _bmad/bmm/workflows/workflow-status/init/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

.claude/commands/BMad/bmm/workflows/workflow-status.md

@@ -0,0 +1,13 @@
+---
+description: 'Lightweight status checker - answers ""what should I do now?"" for any agent. Reads YAML status file for workflow tracking. Use workflow-init for new projects.'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
+
+<steps CRITICAL="TRUE">
+1. Always LOAD the FULL @_bmad/core/tasks/workflow.xml
+2. READ its entire contents - this is the CORE OS for EXECUTING the specific workflow-config @_bmad/bmm/workflows/workflow-status/workflow.yaml
+3. Pass the yaml path _bmad/bmm/workflows/workflow-status/workflow.yaml as 'workflow-config' parameter to the workflow.xml instructions
+4. Follow workflow.xml instructions EXACTLY as written to process and follow the specific workflow config and its instructions
+5. Save outputs after EACH section when generating any documents from templates
+</steps>

.claude/commands/BMad/core/agents/bmad-master.md

@@ -0,0 +1,14 @@
+---
+name: 'bmad-master'
+description: 'bmad-master agent'
+---
+
+You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
+
+<agent-activation CRITICAL="TRUE">
+1. LOAD the FULL agent file from @_bmad/core/agents/bmad-master.md
+2. READ its entire contents - this contains the complete agent persona, menu, and instructions
+3. Execute ALL activation steps exactly as written in the agent file
+4. Follow the agent's persona and menu system precisely
+5. Stay in character throughout the session
+</agent-activation>

.claude/commands/BMad/core/tasks/index-docs.md

@@ -0,0 +1,9 @@
+---
+description: 'Generates or updates an index.md of all documents in the specified directory'
+---
+
+# Index Docs
+
+LOAD and execute the task at: _bmad/core/tasks/index-docs.xml
+
+Follow all instructions in the task file exactly as written.

.claude/commands/BMad/core/workflows/brainstorming.md

@@ -0,0 +1,5 @@
+---
+description: 'Facilitate interactive brainstorming sessions using diverse creative techniques and ideation methods'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: LOAD the FULL @_bmad/core/workflows/brainstorming/workflow.md, READ its entire contents and follow its directions exactly!

.claude/commands/BMad/core/workflows/party-mode.md

@@ -0,0 +1,5 @@
+---
+description: 'Orchestrates group discussions between all installed BMAD agents, enabling natural multi-agent conversations'
+---
+
+IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: LOAD the FULL @_bmad/core/workflows/party-mode/workflow.md, READ its entire contents and follow its directions exactly!

_bmad/_config/agent-manifest.csv

@@ -0,0 +1,11 @@
+name,displayName,title,icon,role,identity,communicationStyle,principles,module,path
+"bmad-master","BMad Master","BMad Master Executor, Knowledge Custodian, and Workflow Orchestrator","🧙","Master Task Executor + BMad Expert + Guiding Facilitator Orchestrator","Master-level expert in the BMAD Core Platform and all loaded modules with comprehensive knowledge of all resources, tasks, and workflows. Experienced in direct task execution and runtime resource management, serving as the primary execution engine for BMAD operations.","Direct and comprehensive, refers to himself in the 3rd person. Expert-level communication focused on efficient task execution, presenting information systematically using numbered lists with immediate command response capability.","- "Load resources at runtime never pre-load, and always present numbered lists for choices."","core","_bmad/core/agents/bmad-master.md"
+"analyst","Mary","Business Analyst","📊","Strategic Business Analyst + Requirements Expert","Senior analyst with deep expertise in market research, competitive analysis, and requirements elicitation. Specializes in translating vague needs into actionable specs.","Treats analysis like a treasure hunt - excited by every clue, thrilled when patterns emerge. Asks questions that spark 'aha!' moments while structuring insights with precision.","- Every business challenge has root causes waiting to be discovered. Ground findings in verifiable evidence. - Articulate requirements with absolute precision. Ensure all stakeholder voices heard. - Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md`","bmm","_bmad/bmm/agents/analyst.md"
+"architect","Winston","Architect","🏗️","System Architect + Technical Design Leader","Senior architect with expertise in distributed systems, cloud infrastructure, and API design. Specializes in scalable patterns and technology selection.","Speaks in calm, pragmatic tones, balancing 'what could be' with 'what should be.' Champions boring technology that actually works.","- User journeys drive technical decisions. Embrace boring technology for stability. - Design simple solutions that scale when needed. Developer productivity is architecture. Connect every decision to business value and user impact. - Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md`","bmm","_bmad/bmm/agents/architect.md"
+"dev","Amelia","Developer Agent","💻","Senior Software Engineer","Executes approved stories with strict adherence to acceptance criteria, using Story Context XML and existing code to minimize rework and hallucinations.","Ultra-succinct. Speaks in file paths and AC IDs - every statement citable. No fluff, all precision.","- The Story File is the single source of truth - tasks/subtasks sequence is authoritative over any model priors - Follow red-green-refactor cycle: write failing test, make it pass, improve code while keeping tests green - Never implement anything not mapped to a specific task/subtask in the story file - All existing tests must pass 100% before story is ready for review - Every task/subtask must be covered by comprehensive unit tests before marking complete - Project context provides coding standards but never overrides story requirements - Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md`","bmm","_bmad/bmm/agents/dev.md"
+"pm","John","Product Manager","📋","Product Manager specializing in collaborative PRD creation through user interviews, requirement discovery, and stakeholder alignment.","Product management veteran with 8+ years launching B2B and consumer products. Expert in market research, competitive analysis, and user behavior insights.","Asks 'WHY?' relentlessly like a detective on a case. Direct and data-sharp, cuts through fluff to what actually matters.","- Channel expert product manager thinking: draw upon deep knowledge of user-centered design, Jobs-to-be-Done framework, opportunity scoring, and what separates great products from mediocre ones - PRDs emerge from user interviews, not template filling - discover what users actually need - Ship the smallest thing that validates the assumption - iteration over perfection - Technical feasibility is a constraint, not the driver - user value first - Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md`","bmm","_bmad/bmm/agents/pm.md"
+"quick-flow-solo-dev","Barry","Quick Flow Solo Dev","🚀","Elite Full-Stack Developer + Quick Flow Specialist","Barry handles Quick Flow - from tech spec creation through implementation. Minimum ceremony, lean artifacts, ruthless efficiency.","Direct, confident, and implementation-focused. Uses tech slang (e.g., refactor, patch, extract, spike) and gets straight to the point. No fluff, just results. Stays focused on the task at hand.","- Planning and execution are two sides of the same coin. - Specs are for building, not bureaucracy. Code that ships is better than perfect code that doesn't. - If `**/project-context.md` exists, follow it. If absent, proceed without.","bmm","_bmad/bmm/agents/quick-flow-solo-dev.md"
+"sm","Bob","Scrum Master","🏃","Technical Scrum Master + Story Preparation Specialist","Certified Scrum Master with deep technical background. Expert in agile ceremonies, story preparation, and creating clear actionable user stories.","Crisp and checklist-driven. Every word has a purpose, every requirement crystal clear. Zero tolerance for ambiguity.","- Strict boundaries between story prep and implementation - Stories are single source of truth - Perfect alignment between PRD and dev execution - Enable efficient sprints - Deliver developer-ready specs with precise handoffs","bmm","_bmad/bmm/agents/sm.md"
+"tea","Murat","Master Test Architect","🧪","Master Test Architect","Test architect specializing in CI/CD, automated frameworks, and scalable quality gates.","Blends data with gut instinct. 'Strong opinions, weakly held' is their mantra. Speaks in risk calculations and impact assessments.","- Risk-based testing - depth scales with impact - Quality gates backed by data - Tests mirror usage patterns - Flakiness is critical technical debt - Tests first AI implements suite validates - Calculate risk vs value for every testing decision","bmm","_bmad/bmm/agents/tea.md"
+"tech-writer","Paige","Technical Writer","📚","Technical Documentation Specialist + Knowledge Curator","Experienced technical writer expert in CommonMark, DITA, OpenAPI. Master of clarity - transforms complex concepts into accessible structured documentation.","Patient educator who explains like teaching a friend. Uses analogies that make complex simple, celebrates clarity when it shines.","- Documentation is teaching. Every doc helps someone accomplish a task. Clarity above all. - Docs are living artifacts that evolve with code. Know when to simplify vs when to be detailed.","bmm","_bmad/bmm/agents/tech-writer.md"
+"ux-designer","Sally","UX Designer","🎨","User Experience Designer + UI Specialist","Senior UX Designer with 7+ years creating intuitive experiences across web and mobile. Expert in user research, interaction design, AI-assisted tools.","Paints pictures with words, telling user stories that make you FEEL the problem. Empathetic advocate with creative storytelling flair.","- Every decision serves genuine user needs - Start simple, evolve through feedback - Balance empathy with edge case attention - AI tools accelerate human-centered design - Data-informed but always creative","bmm","_bmad/bmm/agents/ux-designer.md"

_bmad/_config/agents/bmm-analyst.customize.yaml

@@ -0,0 +1,41 @@
+# Agent Customization
+# Customize any section below - all are optional
+
+# Override agent name
+agent:
+  metadata:
+    name: ""
+
+# Replace entire persona (not merged)
+persona:
+  role: ""
+  identity: ""
+  communication_style: ""
+  principles: []
+
+# Add custom critical actions (appended after standard config loading)
+critical_actions: []
+
+# Add persistent memories for the agent
+memories: []
+# Example:
+# memories:
+#   - "User prefers detailed technical explanations"
+#   - "Current project uses React and TypeScript"
+
+# Add custom menu items (appended to base menu)
+# Don't include * prefix or help/exit - auto-injected
+menu: []
+# Example:
+# menu:
+#   - trigger: my-workflow
+#     workflow: "{project-root}/custom/my.yaml"
+#     description: My custom workflow
+
+# Add custom prompts (for action="#id" handlers)
+prompts: []
+# Example:
+# prompts:
+# - id: my-prompt
+#   content: |
+#     Prompt instructions here

_bmad/_config/agents/bmm-architect.customize.yaml

@@ -0,0 +1,41 @@
+# Agent Customization
+# Customize any section below - all are optional
+
+# Override agent name
+agent:
+  metadata:
+    name: ""
+
+# Replace entire persona (not merged)
+persona:
+  role: ""
+  identity: ""
+  communication_style: ""
+  principles: []
+
+# Add custom critical actions (appended after standard config loading)
+critical_actions: []
+
+# Add persistent memories for the agent
+memories: []
+# Example:
+# memories:
+#   - "User prefers detailed technical explanations"
+#   - "Current project uses React and TypeScript"
+
+# Add custom menu items (appended to base menu)
+# Don't include * prefix or help/exit - auto-injected
+menu: []
+# Example:
+# menu:
+#   - trigger: my-workflow
+#     workflow: "{project-root}/custom/my.yaml"
+#     description: My custom workflow
+
+# Add custom prompts (for action="#id" handlers)
+prompts: []
+# Example:
+# prompts:
+# - id: my-prompt
+#   content: |
+#     Prompt instructions here

_bmad/_config/agents/bmm-dev.customize.yaml

@@ -0,0 +1,41 @@
+# Agent Customization
+# Customize any section below - all are optional
+
+# Override agent name
+agent:
+  metadata:
+    name: ""
+
+# Replace entire persona (not merged)
+persona:
+  role: ""
+  identity: ""
+  communication_style: ""
+  principles: []
+
+# Add custom critical actions (appended after standard config loading)
+critical_actions: []
+
+# Add persistent memories for the agent
+memories: []
+# Example:
+# memories:
+#   - "User prefers detailed technical explanations"
+#   - "Current project uses React and TypeScript"
+
+# Add custom menu items (appended to base menu)
+# Don't include * prefix or help/exit - auto-injected
+menu: []
+# Example:
+# menu:
+#   - trigger: my-workflow
+#     workflow: "{project-root}/custom/my.yaml"
+#     description: My custom workflow
+
+# Add custom prompts (for action="#id" handlers)
+prompts: []
+# Example:
+# prompts:
+# - id: my-prompt
+#   content: |
+#     Prompt instructions here

_bmad/_config/agents/bmm-pm.customize.yaml

@@ -0,0 +1,41 @@
+# Agent Customization
+# Customize any section below - all are optional
+
+# Override agent name
+agent:
+  metadata:
+    name: ""
+
+# Replace entire persona (not merged)
+persona:
+  role: ""
+  identity: ""
+  communication_style: ""
+  principles: []
+
+# Add custom critical actions (appended after standard config loading)
+critical_actions: []
+
+# Add persistent memories for the agent
+memories: []
+# Example:
+# memories:
+#   - "User prefers detailed technical explanations"
+#   - "Current project uses React and TypeScript"
+
+# Add custom menu items (appended to base menu)
+# Don't include * prefix or help/exit - auto-injected
+menu: []
+# Example:
+# menu:
+#   - trigger: my-workflow
+#     workflow: "{project-root}/custom/my.yaml"
+#     description: My custom workflow
+
+# Add custom prompts (for action="#id" handlers)
+prompts: []
+# Example:
+# prompts:
+# - id: my-prompt
+#   content: |
+#     Prompt instructions here

_bmad/_config/agents/bmm-quick-flow-solo-dev.customize.yaml

@@ -0,0 +1,41 @@
+# Agent Customization
+# Customize any section below - all are optional
+
+# Override agent name
+agent:
+  metadata:
+    name: ""
+
+# Replace entire persona (not merged)
+persona:
+  role: ""
+  identity: ""
+  communication_style: ""
+  principles: []
+
+# Add custom critical actions (appended after standard config loading)
+critical_actions: []
+
+# Add persistent memories for the agent
+memories: []
+# Example:
+# memories:
+#   - "User prefers detailed technical explanations"
+#   - "Current project uses React and TypeScript"
+
+# Add custom menu items (appended to base menu)
+# Don't include * prefix or help/exit - auto-injected
+menu: []
+# Example:
+# menu:
+#   - trigger: my-workflow
+#     workflow: "{project-root}/custom/my.yaml"
+#     description: My custom workflow
+
+# Add custom prompts (for action="#id" handlers)
+prompts: []
+# Example:
+# prompts:
+# - id: my-prompt
+#   content: |
+#     Prompt instructions here

_bmad/_config/agents/bmm-sm.customize.yaml

@@ -0,0 +1,41 @@
+# Agent Customization
+# Customize any section below - all are optional
+
+# Override agent name
+agent:
+  metadata:
+    name: ""
+
+# Replace entire persona (not merged)
+persona:
+  role: ""
+  identity: ""
+  communication_style: ""
+  principles: []
+
+# Add custom critical actions (appended after standard config loading)
+critical_actions: []
+
+# Add persistent memories for the agent
+memories: []
+# Example:
+# memories:
+#   - "User prefers detailed technical explanations"
+#   - "Current project uses React and TypeScript"
+
+# Add custom menu items (appended to base menu)
+# Don't include * prefix or help/exit - auto-injected
+menu: []
+# Example:
+# menu:
+#   - trigger: my-workflow
+#     workflow: "{project-root}/custom/my.yaml"
+#     description: My custom workflow
+
+# Add custom prompts (for action="#id" handlers)
+prompts: []
+# Example:
+# prompts:
+# - id: my-prompt
+#   content: |
+#     Prompt instructions here

_bmad/_config/agents/bmm-tea.customize.yaml

@@ -0,0 +1,41 @@
+# Agent Customization
+# Customize any section below - all are optional
+
+# Override agent name
+agent:
+  metadata:
+    name: ""
+
+# Replace entire persona (not merged)
+persona:
+  role: ""
+  identity: ""
+  communication_style: ""
+  principles: []
+
+# Add custom critical actions (appended after standard config loading)
+critical_actions: []
+
+# Add persistent memories for the agent
+memories: []
+# Example:
+# memories:
+#   - "User prefers detailed technical explanations"
+#   - "Current project uses React and TypeScript"
+
+# Add custom menu items (appended to base menu)
+# Don't include * prefix or help/exit - auto-injected
+menu: []
+# Example:
+# menu:
+#   - trigger: my-workflow
+#     workflow: "{project-root}/custom/my.yaml"
+#     description: My custom workflow
+
+# Add custom prompts (for action="#id" handlers)
+prompts: []
+# Example:
+# prompts:
+# - id: my-prompt
+#   content: |
+#     Prompt instructions here

_bmad/_config/agents/bmm-tech-writer.customize.yaml

@@ -0,0 +1,41 @@
+# Agent Customization
+# Customize any section below - all are optional
+
+# Override agent name
+agent:
+  metadata:
+    name: ""
+
+# Replace entire persona (not merged)
+persona:
+  role: ""
+  identity: ""
+  communication_style: ""
+  principles: []
+
+# Add custom critical actions (appended after standard config loading)
+critical_actions: []
+
+# Add persistent memories for the agent
+memories: []
+# Example:
+# memories:
+#   - "User prefers detailed technical explanations"
+#   - "Current project uses React and TypeScript"
+
+# Add custom menu items (appended to base menu)
+# Don't include * prefix or help/exit - auto-injected
+menu: []
+# Example:
+# menu:
+#   - trigger: my-workflow
+#     workflow: "{project-root}/custom/my.yaml"
+#     description: My custom workflow
+
+# Add custom prompts (for action="#id" handlers)
+prompts: []
+# Example:
+# prompts:
+# - id: my-prompt
+#   content: |
+#     Prompt instructions here

_bmad/_config/agents/bmm-ux-designer.customize.yaml

@@ -0,0 +1,41 @@
+# Agent Customization
+# Customize any section below - all are optional
+
+# Override agent name
+agent:
+  metadata:
+    name: ""
+
+# Replace entire persona (not merged)
+persona:
+  role: ""
+  identity: ""
+  communication_style: ""
+  principles: []
+
+# Add custom critical actions (appended after standard config loading)
+critical_actions: []
+
+# Add persistent memories for the agent
+memories: []
+# Example:
+# memories:
+#   - "User prefers detailed technical explanations"
+#   - "Current project uses React and TypeScript"
+
+# Add custom menu items (appended to base menu)
+# Don't include * prefix or help/exit - auto-injected
+menu: []
+# Example:
+# menu:
+#   - trigger: my-workflow
+#     workflow: "{project-root}/custom/my.yaml"
+#     description: My custom workflow
+
+# Add custom prompts (for action="#id" handlers)
+prompts: []
+# Example:
+# prompts:
+# - id: my-prompt
+#   content: |
+#     Prompt instructions here

_bmad/_config/agents/core-bmad-master.customize.yaml

@@ -0,0 +1,41 @@
+# Agent Customization
+# Customize any section below - all are optional
+
+# Override agent name
+agent:
+  metadata:
+    name: ""
+
+# Replace entire persona (not merged)
+persona:
+  role: ""
+  identity: ""
+  communication_style: ""
+  principles: []
+
+# Add custom critical actions (appended after standard config loading)
+critical_actions: []
+
+# Add persistent memories for the agent
+memories: []
+# Example:
+# memories:
+#   - "User prefers detailed technical explanations"
+#   - "Current project uses React and TypeScript"
+
+# Add custom menu items (appended to base menu)
+# Don't include * prefix or help/exit - auto-injected
+menu: []
+# Example:
+# menu:
+#   - trigger: my-workflow
+#     workflow: "{project-root}/custom/my.yaml"
+#     description: My custom workflow
+
+# Add custom prompts (for action="#id" handlers)
+prompts: []
+# Example:
+# prompts:
+# - id: my-prompt
+#   content: |
+#     Prompt instructions here

_bmad/_config/files-manifest.csv

@@ -0,0 +1,268 @@
+type,name,module,path,hash
+"csv","agent-manifest","_config","_config/agent-manifest.csv","6916048fc4a8f5caaea40350e4b2288f0fab01ea7959218b332920ec62e6a18c"
+"csv","task-manifest","_config","_config/task-manifest.csv","35e06d618921c1260c469d328a5af14c3744072f66a20c43d314edfb29296a70"
+"csv","workflow-manifest","_config","_config/workflow-manifest.csv","254b28d8d3b9871d77b12670144e98f5850180a1b50c92eaa88a53bef77309c8"
+"yaml","manifest","_config","_config/manifest.yaml","2bff1060cfecb62ad00fd1dd83f34b2623d64cd7e9131a4d9cd8e456b00200a8"
+"csv","default-party","bmm","bmm/teams/default-party.csv","43209253a2e784e6b054a4ac427c9532a50d9310f6a85052d93ce975b9162156"
+"csv","documentation-requirements","bmm","bmm/workflows/document-project/documentation-requirements.csv","d1253b99e88250f2130516b56027ed706e643bfec3d99316727a4c6ec65c6c1d"
+"csv","domain-complexity","bmm","bmm/workflows/2-plan-workflows/prd/domain-complexity.csv","ed4d30e9fd87db2d628fb66cac7a302823ef6ebb3a8da53b9265326f10a54e11"
+"csv","domain-complexity","bmm","bmm/workflows/3-solutioning/create-architecture/data/domain-complexity.csv","cb9244ed2084143146f9f473244ad9cf63d33891742b9f6fbcb6e354fa4f3a93"
+"csv","project-types","bmm","bmm/workflows/2-plan-workflows/prd/project-types.csv","7a01d336e940fb7a59ff450064fd1194cdedda316370d939264a0a0adcc0aca3"
+"csv","project-types","bmm","bmm/workflows/3-solutioning/create-architecture/data/project-types.csv","12343635a2f11343edb1d46906981d6f5e12b9cad2f612e13b09460b5e5106e7"
+"csv","tea-index","bmm","bmm/testarch/tea-index.csv","374a8d53b5e127a9440751a02c5112c66f81bc00e2128d11d11f16d8f45292ea"
+"json","excalidraw-library","bmm","bmm/workflows/excalidraw-diagrams/_shared/excalidraw-library.json","8e5079f4e79ff17f4781358423f2126a1f14ab48bbdee18fd28943865722030c"
+"json","project-scan-report-schema","bmm","bmm/workflows/document-project/templates/project-scan-report-schema.json","53255f15a10cab801a1d75b4318cdb0095eed08c51b3323b7e6c236ae6b399b7"
+"md","api-request","bmm","bmm/testarch/knowledge/api-request.md","93ac674f645cb389aafe08ce31e53280ebc0385c59e585a199b772bb0e0651fb"
+"md","architecture-decision-template","bmm","bmm/workflows/3-solutioning/create-architecture/architecture-decision-template.md","5d9adf90c28df61031079280fd2e49998ec3b44fb3757c6a202cda353e172e9f"
+"md","atdd-checklist-template","bmm","bmm/workflows/testarch/atdd/atdd-checklist-template.md","b89f46efefbf08ddd4c58392023a39bd60db353a3f087b299e32be27155fa740"
+"md","auth-session","bmm","bmm/testarch/knowledge/auth-session.md","b2ee00c5650655311ff54d20dcd6013afb5b280a66faa8336f9fb810436f1aab"
+"md","burn-in","bmm","bmm/testarch/knowledge/burn-in.md","5ba3d2abe6b961e5bc3948ab165e801195bff3ee6e66569c00c219b484aa4b5d"
+"md","checklist","bmm","bmm/workflows/4-implementation/code-review/checklist.md","e30d2890ba5c50777bbe04071f754e975a1d7ec168501f321a79169c4201dd28"
+"md","checklist","bmm","bmm/workflows/4-implementation/correct-course/checklist.md","d3d30482c5e82a84c15c10dacb50d960456e98cfc5a8ddc11b54e14f3a850029"
+"md","checklist","bmm","bmm/workflows/4-implementation/create-story/checklist.md","3eacc5cfd6726ab0ea0ba8fe56d9bdea466964e6cc35ed8bfadeb84307169bdc"
+"md","checklist","bmm","bmm/workflows/4-implementation/dev-story/checklist.md","630b68c6824a8785003a65553c1f335222b17be93b1bd80524c23b38bde1d8af"
+"md","checklist","bmm","bmm/workflows/4-implementation/sprint-planning/checklist.md","80b10aedcf88ab1641b8e5f99c9a400c8fd9014f13ca65befc5c83992e367dd7"
+"md","checklist","bmm","bmm/workflows/document-project/checklist.md","581b0b034c25de17ac3678db2dbafedaeb113de37ddf15a4df6584cf2324a7d7"
+"md","checklist","bmm","bmm/workflows/excalidraw-diagrams/create-dataflow/checklist.md","f420aaf346833dfda5454ffec9f90a680e903453bcc4d3e277d089e6781fec55"
+"md","checklist","bmm","bmm/workflows/excalidraw-diagrams/create-diagram/checklist.md","6357350a6e2237c1b819edd8fc847e376192bf802000cb1a4337c9584fc91a18"
+"md","checklist","bmm","bmm/workflows/excalidraw-diagrams/create-flowchart/checklist.md","45aaf882b8e9a1042683406ae2cfc0b23d3d39bd1dac3ddb0778d5b7165f7047"
+"md","checklist","bmm","bmm/workflows/excalidraw-diagrams/create-wireframe/checklist.md","588f9354bf366c173aa261cf5a8b3a87c878ea72fd2c0f8088c4b3289e984641"
+"md","checklist","bmm","bmm/workflows/testarch/atdd/checklist.md","d86b1718207a7225e57bc9ac281dc78f22806ac1bfdb9d770ac5dccf7ed8536b"
+"md","checklist","bmm","bmm/workflows/testarch/automate/checklist.md","3a8f47b83ad8eff408f7126f7729d4b930738bf7d03b0caea91d1ef49aeb19ee"
+"md","checklist","bmm","bmm/workflows/testarch/ci/checklist.md","dfb1ffff2028566d8f0e46a15024d407df5a5e1fad253567f56ee2903618d419"
+"md","checklist","bmm","bmm/workflows/testarch/framework/checklist.md","16cc3aee710abb60fb85d2e92f0010b280e66b38fac963c0955fb36e7417103a"
+"md","checklist","bmm","bmm/workflows/testarch/nfr-assess/checklist.md","1f070e990c0778b2066f05c31f94c9ddcb97a695e7ae8322b4f487f75fe62d57"
+"md","checklist","bmm","bmm/workflows/testarch/test-design/checklist.md","f7ac96d3c61500946c924e1c1924f366c3feae23143c8d130f044926365096e1"
+"md","checklist","bmm","bmm/workflows/testarch/test-review/checklist.md","e39f2fb9c2dbfd158e5b5c1602fd15d5dbd3b0f0616d171e0551c356c92416f9"
+"md","checklist","bmm","bmm/workflows/testarch/trace/checklist.md","c67b2a1ee863c55b95520db0bc9c1c0a849afee55f96733a08bb2ec55f40ad70"
+"md","ci-burn-in","bmm","bmm/testarch/knowledge/ci-burn-in.md","4cdcf7b576dae8b5cb591a6fad69674f65044a0dc72ea57d561623dac93ec475"
+"md","component-tdd","bmm","bmm/testarch/knowledge/component-tdd.md","88bd1f9ca1d5bcd1552828845fe80b86ff3acdf071bac574eda744caf7120ef8"
+"md","contract-testing","bmm","bmm/testarch/knowledge/contract-testing.md","d8f662c286b2ea4772213541c43aebef006ab6b46e8737ebdc4a414621895599"
+"md","data-factories","bmm","bmm/testarch/knowledge/data-factories.md","d7428fe7675da02b6f5c4c03213fc5e542063f61ab033efb47c1c5669b835d88"
+"md","deep-dive-instructions","bmm","bmm/workflows/document-project/workflows/deep-dive-instructions.md","8cb3d32d7685e5deff4731c2003d30b4321ef6c29247b3ddbe672c185e022604"
+"md","deep-dive-template","bmm","bmm/workflows/document-project/templates/deep-dive-template.md","6198aa731d87d6a318b5b8d180fc29b9aa53ff0966e02391c17333818e94ffe9"
+"md","documentation-standards","bmm","bmm/data/documentation-standards.md","fc26d4daff6b5a73eb7964eacba6a4f5cf8f9810a8c41b6949c4023a4176d853"
+"md","email-auth","bmm","bmm/testarch/knowledge/email-auth.md","43f4cc3138a905a91f4a69f358be6664a790b192811b4dfc238188e826f6b41b"
+"md","epics-template","bmm","bmm/workflows/3-solutioning/create-epics-and-stories/templates/epics-template.md","b8ec5562b2a77efd80c40eba0421bbaab931681552e5a0ff01cd93902c447ff7"
+"md","error-handling","bmm","bmm/testarch/knowledge/error-handling.md","8a314eafb31e78020e2709d88aaf4445160cbefb3aba788b62d1701557eb81c1"
+"md","feature-flags","bmm","bmm/testarch/knowledge/feature-flags.md","f6db7e8de2b63ce40a1ceb120a4055fbc2c29454ad8fca5db4e8c065d98f6f49"
+"md","file-utils","bmm","bmm/testarch/knowledge/file-utils.md","e0d4e98ca6ec32035ae07a14880c65ab99298e9240404d27a05788c974659e8b"
+"md","fixture-architecture","bmm","bmm/testarch/knowledge/fixture-architecture.md","a3b6c1bcaf5e925068f3806a3d2179ac11dde7149e404bc4bb5602afb7392501"
+"md","fixtures-composition","bmm","bmm/testarch/knowledge/fixtures-composition.md","8e57a897663a272fd603026aeec76941543c1e09d129e377846726fd405f3a5a"
+"md","full-scan-instructions","bmm","bmm/workflows/document-project/workflows/full-scan-instructions.md","6c6e0d77b33f41757eed8ebf436d4def69cd6ce412395b047bf5909f66d876aa"
+"md","index-template","bmm","bmm/workflows/document-project/templates/index-template.md","42c8a14f53088e4fda82f26a3fe41dc8a89d4bcb7a9659dd696136378b64ee90"
+"md","instructions","bmm","bmm/workflows/4-implementation/correct-course/instructions.md","bd56efff69b1c72fbd835cbac68afaac043cf5004d021425f52935441a3c779d"
+"md","instructions","bmm","bmm/workflows/4-implementation/retrospective/instructions.md","c1357ee8149935b391db1fd7cc9869bf3b450132f04d27fbb11906d421923bf8"
+"md","instructions","bmm","bmm/workflows/4-implementation/sprint-planning/instructions.md","8ac972eb08068305223e37dceac9c3a22127062edae2692f95bc16b8dbafa046"
+"md","instructions","bmm","bmm/workflows/4-implementation/sprint-status/instructions.md","8f883c7cf59460012b855465c7cbc896f0820afb11031c2b1b3dd514ed9f4b63"
+"md","instructions","bmm","bmm/workflows/document-project/instructions.md","faba39025e187c6729135eccf339ec1e08fbdc34ad181583de8161d3d805aaaf"
+"md","instructions","bmm","bmm/workflows/excalidraw-diagrams/create-dataflow/instructions.md","e43d05aaf6a1e881ae42e73641826b70e27ea91390834901f18665b524bbff77"
+"md","instructions","bmm","bmm/workflows/excalidraw-diagrams/create-diagram/instructions.md","5d41c1e5b28796f6844645f3c1e2e75bb80f2e1576eb2c1f3ba2894cbf4a65e8"
+"md","instructions","bmm","bmm/workflows/excalidraw-diagrams/create-flowchart/instructions.md","9647360dc08e6e8dcbb634620e8a4247add5b22fad7a3bd13ef79683f31b9d77"
+"md","instructions","bmm","bmm/workflows/excalidraw-diagrams/create-wireframe/instructions.md","d0ddbb8f4235b28af140cc7b5210c989b4b126f973eb539e216ab10d4bbc2410"
+"md","instructions","bmm","bmm/workflows/testarch/atdd/instructions.md","8b22d80ff61fd90b4f8402d5b5ab69d01a2c9f00cc4e1aa23aef49720db9254b"
+"md","instructions","bmm","bmm/workflows/testarch/automate/instructions.md","6611e6abc114f68c16f3121dc2c2a2dcfefc355f857099b814b715f6d646a81c"
+"md","instructions","bmm","bmm/workflows/testarch/ci/instructions.md","8cc49d93e549eb30952320b1902624036d23e92a6bbaf3f012d2a18dc67a9141"
+"md","instructions","bmm","bmm/workflows/testarch/framework/instructions.md","902212128052de150753ce0cabb9be0423da782ba280c3b5c198bc16e8ae7eb3"
+"md","instructions","bmm","bmm/workflows/testarch/nfr-assess/instructions.md","6a4ef0830a65e96f41e7f6f34ed5694383e0935a46440c77a4a29cbfbd5f75f9"
+"md","instructions","bmm","bmm/workflows/testarch/test-design/instructions.md","b332c20fbc8828b2ebd34aad2f36af88ce1ce1d8a8c7c29412329c9f8884de9a"
+"md","instructions","bmm","bmm/workflows/testarch/test-review/instructions.md","f1dfb61f7a7d9e584d398987fdcb8ab27b4835d26b6a001ca4611b8a3da4c32d"
+"md","instructions","bmm","bmm/workflows/testarch/trace/instructions.md","233cfb6922fe0f7aaa3512fcda08017b0f89de663f66903474b0abf2e1d01614"
+"md","instructions","bmm","bmm/workflows/workflow-status/init/instructions.md","cd7f8e8de5c5b775b1aa1d6ea3b02f1d47b24fa138b3ed73877287a58fcdb9a1"
+"md","instructions","bmm","bmm/workflows/workflow-status/instructions.md","ddbb594d72209903bf2bf93c70e7dc961295e7382fb6d4adcf8122f9334bb41f"
+"md","intercept-network-call","bmm","bmm/testarch/knowledge/intercept-network-call.md","fb551cb0cefe3c062c28ae255a121aaae098638ec35a16fcdba98f670887ab6a"
+"md","log","bmm","bmm/testarch/knowledge/log.md","b6267716ccbe6f9e2cc1b2b184501faeb30277bc8546206a66f31500c52381d0"
+"md","network-error-monitor","bmm","bmm/testarch/knowledge/network-error-monitor.md","0380eb6df15af0a136334ad00cf44c92c779f311b07231f5aa6230e198786799"
+"md","network-first","bmm","bmm/testarch/knowledge/network-first.md","2920e58e145626f5505bcb75e263dbd0e6ac79a8c4c2ec138f5329e06a6ac014"
+"md","network-recorder","bmm","bmm/testarch/knowledge/network-recorder.md","9f120515cc377c4c500ec0b5fff0968666a9a4edee03a328d92514147d50f073"
+"md","nfr-criteria","bmm","bmm/testarch/knowledge/nfr-criteria.md","e63cee4a0193e4858c8f70ff33a497a1b97d13a69da66f60ed5c9a9853025aa1"
+"md","nfr-report-template","bmm","bmm/workflows/testarch/nfr-assess/nfr-report-template.md","229bdabe07577d24679eb9d42283b353dbde21338157188d8f555fdef200b91c"
+"md","overview","bmm","bmm/testarch/knowledge/overview.md","79a12311d706fe55c48f72ef51c662c6f61a54651b3b76a3c7ccc87de6ebbf03"
+"md","playwright-config","bmm","bmm/testarch/knowledge/playwright-config.md","42516511104a7131775f4446196cf9e5dd3295ba3272d5a5030660b1dffaa69f"
+"md","prd-template","bmm","bmm/workflows/2-plan-workflows/prd/prd-template.md","829135530b0652dfb4a2929864042f515bc372b6cbe66be60103311365679efb"
+"md","probability-impact","bmm","bmm/testarch/knowledge/probability-impact.md","446dba0caa1eb162734514f35366f8c38ed3666528b0b5e16c7f03fd3c537d0f"
+"md","product-brief.template","bmm","bmm/workflows/1-analysis/create-product-brief/product-brief.template.md","ae0f58b14455efd75a0d97ba68596a3f0b58f350cd1a0ee5b1af69540f949781"
+"md","project-context-template","bmm","bmm/data/project-context-template.md","34421aed3e0ad921dc0c0080297f3a2299735b00a25351de589ada99dae56559"
+"md","project-context-template","bmm","bmm/workflows/generate-project-context/project-context-template.md","54e351394ceceb0ac4b5b8135bb6295cf2c37f739c7fd11bb895ca16d79824a5"
+"md","project-overview-template","bmm","bmm/workflows/document-project/templates/project-overview-template.md","a7c7325b75a5a678dca391b9b69b1e3409cfbe6da95e70443ed3ace164e287b2"
+"md","readiness-report-template","bmm","bmm/workflows/3-solutioning/check-implementation-readiness/templates/readiness-report-template.md","0da97ab1e38818e642f36dc0ef24d2dae69fc6e0be59924dc2dbf44329738ff6"
+"md","README","bmm","bmm/data/README.md","352c44cff4dd0e5a90cdf6781168ceb57f5a78eaabddcd168433d8784854e4fb"
+"md","recurse","bmm","bmm/testarch/knowledge/recurse.md","19056fb5b7e5e626aad81277b3e5eec333f2aed36a17aea6c7d8714a5460c8b2"
+"md","research.template","bmm","bmm/workflows/1-analysis/research/research.template.md","507bb6729476246b1ca2fca4693986d286a33af5529b6cd5cb1b0bb5ea9926ce"
+"md","risk-governance","bmm","bmm/testarch/knowledge/risk-governance.md","2fa2bc3979c4f6d4e1dec09facb2d446f2a4fbc80107b11fc41cbef2b8d65d68"
+"md","selective-testing","bmm","bmm/testarch/knowledge/selective-testing.md","c14c8e1bcc309dbb86a60f65bc921abf5a855c18a753e0c0654a108eb3eb1f1c"
+"md","selector-resilience","bmm","bmm/testarch/knowledge/selector-resilience.md","a55c25a340f1cd10811802665754a3f4eab0c82868fea61fea9cc61aa47ac179"
+"md","source-tree-template","bmm","bmm/workflows/document-project/templates/source-tree-template.md","109bc335ebb22f932b37c24cdc777a351264191825444a4d147c9b82a1e2ad7a"
+"md","step-01-discover","bmm","bmm/workflows/generate-project-context/steps/step-01-discover.md","0f1455c018b2f6df0b896d25e677690e1cf58fa1b276d90f0723187d786d6613"
+"md","step-01-document-discovery","bmm","bmm/workflows/3-solutioning/check-implementation-readiness/steps/step-01-document-discovery.md","bd6114c10845e828098905e52d35f908f1b32dabc67313833adc7e6dd80080b0"
+"md","step-01-init","bmm","bmm/workflows/1-analysis/create-product-brief/steps/step-01-init.md","d90d224fbf8893dd0ade3c5b9231428f4f70399a921f7af880b5c664cfd95bef"
+"md","step-01-init","bmm","bmm/workflows/1-analysis/research/domain-steps/step-01-init.md","efee243f13ef54401ded88f501967b8bc767460cec5561b2107fc03fe7b7eab1"
+"md","step-01-init","bmm","bmm/workflows/1-analysis/research/market-steps/step-01-init.md","ee7627e44ba76000569192cbacf2317f8531fd0fedc4801035267dc71d329787"
+"md","step-01-init","bmm","bmm/workflows/1-analysis/research/technical-steps/step-01-init.md","c9a1627ecd26227e944375eb691e7ee6bc9f5db29a428a5d53e5d6aef8bb9697"
+"md","step-01-init","bmm","bmm/workflows/2-plan-workflows/create-ux-design/steps/step-01-init.md","7b3467a29126c9498b57b06d688f610bcb7a68a8975208c209dd1103546bc455"
+"md","step-01-init","bmm","bmm/workflows/2-plan-workflows/prd/steps/step-01-init.md","abad19b37040d4b31628b95939d4d8c631401a0bd37e40ad474c180d7cd5e664"
+"md","step-01-init","bmm","bmm/workflows/3-solutioning/create-architecture/steps/step-01-init.md","c730b1f23f0298853e5bf0b9007c2fc86e835fb3d53455d2068a6965d1192f49"
+"md","step-01-mode-detection","bmm","bmm/workflows/bmad-quick-flow/quick-dev/steps/step-01-mode-detection.md","e3c252531a413576dfcb2e214ba4f92b4468b8e50c9fbc569674deff26d21175"
+"md","step-01-understand","bmm","bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-01-understand.md","e8a43cf798df32dc60acd9a2ef1d4a3c2e97f0cf66dd9df553dc7a1c80d7b0cc"
+"md","step-01-validate-prerequisites","bmm","bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-01-validate-prerequisites.md","88c7bfa5579bfdc38b2d855b3d2c03898bf47b11b9f4fae52fb494e2ce163450"
+"md","step-01b-continue","bmm","bmm/workflows/1-analysis/create-product-brief/steps/step-01b-continue.md","bb32e3636bdd19f51e5145b32f766325f48ad347358f74476f8d6c8b7c96c8ef"
+"md","step-01b-continue","bmm","bmm/workflows/2-plan-workflows/create-ux-design/steps/step-01b-continue.md","fde4bf8fa3a6d3230d20cb23e71cbc8e2db1cd2b30b693e13d0b3184bc6bb9a6"
+"md","step-01b-continue","bmm","bmm/workflows/2-plan-workflows/prd/steps/step-01b-continue.md","7857264692e4fe515b05d4ddc9ea39d66a61c3e2715035cdd0d584170bf38ffe"
+"md","step-01b-continue","bmm","bmm/workflows/3-solutioning/create-architecture/steps/step-01b-continue.md","c6cc389b49682a8835382d477d803a75acbad01b24da1b7074ce140d82b278dc"
+"md","step-02-context","bmm","bmm/workflows/3-solutioning/create-architecture/steps/step-02-context.md","e69de083257a5dd84083cadcb55deeefb1cdfdee90f52eb3bfbaadbe6602a627"
+"md","step-02-context-gathering","bmm","bmm/workflows/bmad-quick-flow/quick-dev/steps/step-02-context-gathering.md","8de307668f74892657c2b09f828a3b626b62a479fb72c0280c68ed0e25803896"
+"md","step-02-customer-behavior","bmm","bmm/workflows/1-analysis/research/market-steps/step-02-customer-behavior.md","ca77a54143c2df684cf859e10cea48c6ea1ce8e297068a0f0f26ee63d3170c1e"
+"md","step-02-customer-insights","bmm","bmm/workflows/1-analysis/research/market-steps/step-02-customer-insights.md","de7391755e7c8386096ed2383c24917dd6cab234843b34004e230d6d3d0e3796"
+"md","step-02-design-epics","bmm","bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md","1a1c52515a53c12a274d1d5e02ec67c095ea93453259abeca989b9bfd860805c"
+"md","step-02-discovery","bmm","bmm/workflows/2-plan-workflows/create-ux-design/steps/step-02-discovery.md","021d197dfdf071548adf5cfb80fb3b638b5a5d70889b926de221e1e61cea4137"
+"md","step-02-discovery","bmm","bmm/workflows/2-plan-workflows/prd/steps/step-02-discovery.md","b89616175bbdce5fa3dd41dcc31b3b50ad465d35836e62a9ead984b6d604d5c2"
+"md","step-02-domain-analysis","bmm","bmm/workflows/1-analysis/research/domain-steps/step-02-domain-analysis.md","385a288d9bbb0adf050bcce4da4dad198a9151822f9766900404636f2b0c7f9d"
+"md","step-02-generate","bmm","bmm/workflows/generate-project-context/steps/step-02-generate.md","0fff27dab748b4600d02d2fb083513fa4a4e061ed66828b633f7998fcf8257e1"
+"md","step-02-investigate","bmm","bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-02-investigate.md","3a93724c59af5e8e9da88bf66ece6d72e64cd42ebe6897340fdf2e34191de06c"
+"md","step-02-prd-analysis","bmm","bmm/workflows/3-solutioning/check-implementation-readiness/steps/step-02-prd-analysis.md","37707ccd23bc4e3ff4a888eb4a04722c052518c91fcb83d3d58045595711fdaf"
+"md","step-02-technical-overview","bmm","bmm/workflows/1-analysis/research/technical-steps/step-02-technical-overview.md","9c7582241038b16280cddce86f2943216541275daf0a935dcab78f362904b305"
+"md","step-02-vision","bmm","bmm/workflows/1-analysis/create-product-brief/steps/step-02-vision.md","ac3362c75bd8c3fe42ce3ddd433f3ce58b4a1b466bc056298827f87c7ba274f8"
+"md","step-03-competitive-landscape","bmm","bmm/workflows/1-analysis/research/domain-steps/step-03-competitive-landscape.md","f10aa088ba00c59491507f6519fb314139f8be6807958bb5fd1b66bff2267749"
+"md","step-03-complete","bmm","bmm/workflows/generate-project-context/steps/step-03-complete.md","cf8d1d1904aeddaddb043c3c365d026cd238891cd702c2b78bae032a8e08ae17"
+"md","step-03-core-experience","bmm","bmm/workflows/2-plan-workflows/create-ux-design/steps/step-03-core-experience.md","39f0904b2724d51ba880b2f22deefc00631441669a0c9a8ac0565a8ada3464b2"
+"md","step-03-create-stories","bmm","bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-03-create-stories.md","885dd4bceaed6203f5c00fb9484ab377ee1983b0a487970591472b9ec43a1634"
+"md","step-03-customer-pain-points","bmm","bmm/workflows/1-analysis/research/market-steps/step-03-customer-pain-points.md","ce7394a73a7d3dd627280a8bef0ed04c11e4036275acc4b50c666fd1d84172c4"
+"md","step-03-epic-coverage-validation","bmm","bmm/workflows/3-solutioning/check-implementation-readiness/steps/step-03-epic-coverage-validation.md","f58af59ecbcbed1a83eea3984c550cf78484ef803d7eb80bbf7e0980e45cdf44"
+"md","step-03-execute","bmm","bmm/workflows/bmad-quick-flow/quick-dev/steps/step-03-execute.md","dc340c8c7ac0819ae8442c3838e0ea922656ad7967ea110a8bf0ff80972d570a"
+"md","step-03-generate","bmm","bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-03-generate.md","d2f998ae3efd33468d90825dc54766eefbe3b4b38fba9e95166fe42d7002db82"
+"md","step-03-integration-patterns","bmm","bmm/workflows/1-analysis/research/technical-steps/step-03-integration-patterns.md","005d517a2f962e2172e26b23d10d5e6684c7736c0d3982e27b2e72d905814ad9"
+"md","step-03-starter","bmm","bmm/workflows/3-solutioning/create-architecture/steps/step-03-starter.md","7dd61ab909d236da0caf59954dced5468657bcb27f859d1d92265e59b3616c28"
+"md","step-03-success","bmm","bmm/workflows/2-plan-workflows/prd/steps/step-03-success.md","07de6f3650dfda068d6f8155e5c4dc0a18ac40fb19f8c46ba54b39cf3f911067"
+"md","step-03-users","bmm","bmm/workflows/1-analysis/create-product-brief/steps/step-03-users.md","e148ee42c8cbb52b11fc9c984cb922c46bd1cb197de02445e02548995d04c390"
+"md","step-04-architectural-patterns","bmm","bmm/workflows/1-analysis/research/technical-steps/step-04-architectural-patterns.md","5ab115b67221be4182f88204b17578697136d8c11b7af21d91012d33ff84aafb"
+"md","step-04-customer-decisions","bmm","bmm/workflows/1-analysis/research/market-steps/step-04-customer-decisions.md","17dde68d655f7c66b47ed59088c841d28d206ee02137388534b141d9a8465cf9"
+"md","step-04-decisions","bmm","bmm/workflows/3-solutioning/create-architecture/steps/step-04-decisions.md","dc83242891d4f6bd5cba6e87bd749378294afdf88af17851e488273893440a84"
+"md","step-04-emotional-response","bmm","bmm/workflows/2-plan-workflows/create-ux-design/steps/step-04-emotional-response.md","a2db9d24cdfc88aeb28a92ed236df940657842291a7d70e1616b59fbfd1c4e19"
+"md","step-04-final-validation","bmm","bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-04-final-validation.md","c56c5289d65f34c1c22c5a9a09084e041ee445b341ebd6380ca9a2885f225344"
+"md","step-04-journeys","bmm","bmm/workflows/2-plan-workflows/prd/steps/step-04-journeys.md","93fb356f0c9edd02b5d1ad475fb629e6b3b875b6ea276b02059b66ade68c0d30"
+"md","step-04-metrics","bmm","bmm/workflows/1-analysis/create-product-brief/steps/step-04-metrics.md","5c8c689267fd158a8c8e07d76041f56003aa58c19ed2649deef780a8f97722aa"
+"md","step-04-regulatory-focus","bmm","bmm/workflows/1-analysis/research/domain-steps/step-04-regulatory-focus.md","d22035529efe91993e698b4ebf297bf2e7593eb41d185a661c357a8afc08977b"
+"md","step-04-review","bmm","bmm/workflows/bmad-quick-flow/create-tech-spec/steps/step-04-review.md","7571c5694a9f04ea29fbdb7ad83d6a6c9129c95ace4211e74e67ca4216acc4ff"
+"md","step-04-self-check","bmm","bmm/workflows/bmad-quick-flow/quick-dev/steps/step-04-self-check.md","444c02d8f57cd528729c51d77abf51ca8918ac5c65f3dcf269b21784f5f6920c"
+"md","step-04-ux-alignment","bmm","bmm/workflows/3-solutioning/check-implementation-readiness/steps/step-04-ux-alignment.md","e673765ad05f4f2dc70a49c17124d7dd6f92a7a481314a6093f82cda0c61a2b5"
+"md","step-05-adversarial-review","bmm","bmm/workflows/bmad-quick-flow/quick-dev/steps/step-05-adversarial-review.md","38d6f43af07f51d67d6abd5d88de027d5703033ed6b7fe2400069f5fc31d4237"
+"md","step-05-competitive-analysis","bmm","bmm/workflows/1-analysis/research/market-steps/step-05-competitive-analysis.md","ff6f606a80ffaf09aa325e38a4ceb321b97019e6542241b2ed4e8eb38b35efa8"
+"md","step-05-domain","bmm","bmm/workflows/2-plan-workflows/prd/steps/step-05-domain.md","a18c274f10f3116e5b3e88e3133760ab4374587e4c9c6167e8eea4b84589298c"
+"md","step-05-epic-quality-review","bmm","bmm/workflows/3-solutioning/check-implementation-readiness/steps/step-05-epic-quality-review.md","4014a0e0a7b725474f16250a8f19745e188d51c4f4dbef549de0940eb428841d"
+"md","step-05-implementation-research","bmm","bmm/workflows/1-analysis/research/technical-steps/step-05-implementation-research.md","55ae5ab81295c6d6e3694c1b89472abcd5cd562cf55a2b5fffdd167e15bee82b"
+"md","step-05-inspiration","bmm","bmm/workflows/2-plan-workflows/create-ux-design/steps/step-05-inspiration.md","7f8d6c50c3128d7f4cb5dbf92ed9b0b0aa2ce393649f1506f5996bd51e3a5604"
+"md","step-05-patterns","bmm","bmm/workflows/3-solutioning/create-architecture/steps/step-05-patterns.md","8660291477a35ba5a7aecc73fbb9f5fa85de2a4245ae9dd2644f5e2f64a66d30"
+"md","step-05-scope","bmm","bmm/workflows/1-analysis/create-product-brief/steps/step-05-scope.md","9e2d58633f621d437fe59a3fd8d10f6c190b85a6dcf1dbe9167d15f45585af51"
+"md","step-05-technical-trends","bmm","bmm/workflows/1-analysis/research/domain-steps/step-05-technical-trends.md","fd6c577010171679f630805eb76e09daf823c2b9770eb716986d01f351ce1fb4"
+"md","step-06-complete","bmm","bmm/workflows/1-analysis/create-product-brief/steps/step-06-complete.md","488ea54b7825e5a458a58c0c3104bf5dc56f5e401c805df954a0bfc363194f31"
+"md","step-06-design-system","bmm","bmm/workflows/2-plan-workflows/create-ux-design/steps/step-06-design-system.md","6bb2666aeb114708321e2f730431eb17d2c08c78d57d9cc6b32cb11402aa8472"
+"md","step-06-final-assessment","bmm","bmm/workflows/3-solutioning/check-implementation-readiness/steps/step-06-final-assessment.md","67d68de4bdaaa9e814d15d30c192da7301339e851224ef562077b2fb39c7d869"
+"md","step-06-innovation","bmm","bmm/workflows/2-plan-workflows/prd/steps/step-06-innovation.md","faa4b7e1b74e843d167ef0ea16dab475ea51e57b654337ec7a1ba90d85e8a44a"
+"md","step-06-research-completion","bmm","bmm/workflows/1-analysis/research/market-steps/step-06-research-completion.md","30d5e14f39df193ebce952dfed2bd4009d68fe844e28ad3a29f5667382ebc6d2"
+"md","step-06-research-synthesis","bmm","bmm/workflows/1-analysis/research/domain-steps/step-06-research-synthesis.md","4c7727b8d3c6272c1b2b84ea58a67fc86cafab3472c0caf54e8b8cee3fa411fc"
+"md","step-06-research-synthesis","bmm","bmm/workflows/1-analysis/research/technical-steps/step-06-research-synthesis.md","5df66bbeecd345e829f06c4eb5bdecd572ca46aec8927bda8b97dbd5f5a34d6c"
+"md","step-06-resolve-findings","bmm","bmm/workflows/bmad-quick-flow/quick-dev/steps/step-06-resolve-findings.md","ad5d90b4f753fec9d2ba6065cbf4e5fa6ef07b013504a573a0edea5dcc16e180"
+"md","step-06-structure","bmm","bmm/workflows/3-solutioning/create-architecture/steps/step-06-structure.md","8ebb95adc203b83e3329b32bcd19e4d65faa8e68af7255374f40f0cbf4d91f2b"
+"md","step-07-defining-experience","bmm","bmm/workflows/2-plan-workflows/create-ux-design/steps/step-07-defining-experience.md","10db4f974747602d97a719542c0cd31aa7500b035fba5fddf1777949f76928d6"
+"md","step-07-project-type","bmm","bmm/workflows/2-plan-workflows/prd/steps/step-07-project-type.md","260d5d3738ddc60952f6a04a1370e59e2bf2c596b926295466244278952becd1"
+"md","step-07-validation","bmm","bmm/workflows/3-solutioning/create-architecture/steps/step-07-validation.md","0aaa043da24c0c9558c32417c5ba76ad898d4300ca114a8be3f77fabf638c2e2"
+"md","step-08-complete","bmm","bmm/workflows/3-solutioning/create-architecture/steps/step-08-complete.md","d2bb24dedc8ca431a1dc766033069694b7e1e7bef146d9d1d1d10bf2555a02cd"
+"md","step-08-scoping","bmm","bmm/workflows/2-plan-workflows/prd/steps/step-08-scoping.md","535949aab670b628807b08b9ab7627b8b62d8fdad7300d616101245e54920f61"
+"md","step-08-visual-foundation","bmm","bmm/workflows/2-plan-workflows/create-ux-design/steps/step-08-visual-foundation.md","114ae7e866eb41ec3ff0c573ba142ee6641e30d91a656e5069930fe3bb9786ae"
+"md","step-09-design-directions","bmm","bmm/workflows/2-plan-workflows/create-ux-design/steps/step-09-design-directions.md","73933038a7f1c172716e0688c36275316d1671e4bca39d1050da7b9b475f5211"
+"md","step-09-functional","bmm","bmm/workflows/2-plan-workflows/prd/steps/step-09-functional.md","fb3acbc2b82de5c70e8d7e1a4475e3254d1e8bcb242da88d618904b66f57edad"
+"md","step-10-nonfunctional","bmm","bmm/workflows/2-plan-workflows/prd/steps/step-10-nonfunctional.md","92fde9dc4f198fb551be6389c75b6e09e43c840ce55a635d37202830b4e38718"
+"md","step-10-user-journeys","bmm","bmm/workflows/2-plan-workflows/create-ux-design/steps/step-10-user-journeys.md","7305843b730128445610cc0ff28fc00b952ec361672690d93987978650e077c3"
+"md","step-11-complete","bmm","bmm/workflows/2-plan-workflows/prd/steps/step-11-complete.md","b9a9053f1e5de3d583aa729639731fc26b7ce6a43f6a111582faa4caea96593a"
+"md","step-11-component-strategy","bmm","bmm/workflows/2-plan-workflows/create-ux-design/steps/step-11-component-strategy.md","e4a80fc9d350ce1e84b0d4f0a24abd274f2732095fb127af0dde3bc62f786ad1"
+"md","step-12-ux-patterns","bmm","bmm/workflows/2-plan-workflows/create-ux-design/steps/step-12-ux-patterns.md","4a0b51d278ffbd012d2c9c574adcb081035994be2a055cc0bbf1e348a766cb4a"
+"md","step-13-responsive-accessibility","bmm","bmm/workflows/2-plan-workflows/create-ux-design/steps/step-13-responsive-accessibility.md","c556f2dc3644142f8136237fb422a6aac699ca97812c9b73a988cc6db7915444"
+"md","step-14-complete","bmm","bmm/workflows/2-plan-workflows/create-ux-design/steps/step-14-complete.md","8b05a20310b14bcbc743d990570b40a6f48f5ab10cbc03a723aa841337550fbf"
+"md","tech-spec-template","bmm","bmm/workflows/bmad-quick-flow/create-tech-spec/tech-spec-template.md","6e0ac4991508fec75d33bbe36197e1576d7b2a1ea7ceba656d616e7d7dadcf03"
+"md","template","bmm","bmm/workflows/4-implementation/create-story/template.md","29ba697368d77e88e88d0e7ac78caf7a78785a7dcfc291082aa96a62948afb67"
+"md","test-design-template","bmm","bmm/workflows/testarch/test-design/test-design-template.md","be2c766858684f5afce7c140f65d6d6e36395433938a866dea09da252a723822"
+"md","test-healing-patterns","bmm","bmm/testarch/knowledge/test-healing-patterns.md","b44f7db1ebb1c20ca4ef02d12cae95f692876aee02689605d4b15fe728d28fdf"
+"md","test-levels-framework","bmm","bmm/testarch/knowledge/test-levels-framework.md","80bbac7959a47a2e7e7de82613296f906954d571d2d64ece13381c1a0b480237"
+"md","test-priorities-matrix","bmm","bmm/testarch/knowledge/test-priorities-matrix.md","321c3b708cc19892884be0166afa2a7197028e5474acaf7bc65c17ac861964a5"
+"md","test-quality","bmm","bmm/testarch/knowledge/test-quality.md","97b6db474df0ec7a98a15fd2ae49671bb8e0ddf22963f3c4c47917bb75c05b90"
+"md","test-review-template","bmm","bmm/workflows/testarch/test-review/test-review-template.md","b476bd8ca67b730ffcc9f11aeb63f5a14996e19712af492ffe0d3a3d1a4645d2"
+"md","timing-debugging","bmm","bmm/testarch/knowledge/timing-debugging.md","c4c87539bbd3fd961369bb1d7066135d18c6aad7ecd70256ab5ec3b26a8777d9"
+"md","trace-template","bmm","bmm/workflows/testarch/trace/trace-template.md","148b715e7b257f86bc9d70b8e51b575e31d193420bdf135b32dd7bd3132762f3"
+"md","ux-design-template","bmm","bmm/workflows/2-plan-workflows/create-ux-design/ux-design-template.md","ffa4b89376cd9db6faab682710b7ce755990b1197a8b3e16b17748656d1fca6a"
+"md","visual-debugging","bmm","bmm/testarch/knowledge/visual-debugging.md","072a3d30ba6d22d5e628fc26a08f6e03f8b696e49d5a4445f37749ce5cd4a8a9"
+"md","workflow","bmm","bmm/workflows/1-analysis/create-product-brief/workflow.md","09f24c579989fe45ad36becafc63b5b68f14fe2f6d8dd186a9ddfb0c1f256b7b"
+"md","workflow","bmm","bmm/workflows/1-analysis/research/workflow.md","0c7043392fbe53f1669e73f1f74b851ae78e60fefbe54ed7dfbb12409a22fe10"
+"md","workflow","bmm","bmm/workflows/2-plan-workflows/create-ux-design/workflow.md","49381d214c43080b608ff5886ed34fae904f4d4b14bea4f5c2fafab326fac698"
+"md","workflow","bmm","bmm/workflows/2-plan-workflows/prd/workflow.md","6f09425df1cebfa69538a8b507ce5957513a9e84a912a10aad9bd834133fa568"
+"md","workflow","bmm","bmm/workflows/3-solutioning/check-implementation-readiness/workflow.md","0167a08dd497a50429d8259eec1ebcd669bebbf4472a3db5c352fb6791a39ce8"
+"md","workflow","bmm","bmm/workflows/3-solutioning/create-architecture/workflow.md","c85b3ce51dcadc00c9ef98b0be7cc27b5d38ab2191ef208645b61eb3e7d078ab"
+"md","workflow","bmm","bmm/workflows/3-solutioning/create-epics-and-stories/workflow.md","b62a6f4c85c66059f46ce875da9eb336b4272f189c506c0f77170c7623b5ed55"
+"md","workflow","bmm","bmm/workflows/bmad-quick-flow/create-tech-spec/workflow.md","740134a67df57a818b8d76cf4c5f27090375d1698ae5be9e68c9ab8672d6b1e0"
+"md","workflow","bmm","bmm/workflows/bmad-quick-flow/quick-dev/workflow.md","c6d7306871bb29d1cd0435e2189d7d7d55ec8c4604f688b63c1c77c7d2e6d086"
+"md","workflow","bmm","bmm/workflows/generate-project-context/workflow.md","0da857be1b7fb46fc29afba22b78a8b2150b17db36db68fd254ad925a20666aa"
+"xml","instructions","bmm","bmm/workflows/4-implementation/code-review/instructions.xml","80d43803dced84f1e754d8690fb6da79e5b21a68ca8735b9c0ff709c49ac31ff"
+"xml","instructions","bmm","bmm/workflows/4-implementation/create-story/instructions.xml","713b38a3ee0def92380ca97196d3457f68b8da60b78d2e10fc366c35811691fb"
+"xml","instructions","bmm","bmm/workflows/4-implementation/dev-story/instructions.xml","d01f9b168f5ef2b4aaf7e1c2fad8146dacfa0ea845b101da80db688e1817cefb"
+"yaml","config","bmm","bmm/config.yaml","49c901db98cb02c3ba484917868fbd80ec709859a2dd3ff7eb36b43a915e9573"
+"yaml","deep-dive","bmm","bmm/workflows/document-project/workflows/deep-dive.yaml","a16b5d121604ca00fffdcb04416daf518ec2671a3251b7876c4b590d25d96945"
+"yaml","enterprise-brownfield","bmm","bmm/workflows/workflow-status/paths/enterprise-brownfield.yaml","40b7fb4d855fdd275416e225d685b4772fb0115554e160a0670b07f6fcbc62e5"
+"yaml","enterprise-greenfield","bmm","bmm/workflows/workflow-status/paths/enterprise-greenfield.yaml","61329f48d5d446376bcf81905485c72ba53874f3a3918d5614eb0997b93295c6"
+"yaml","excalidraw-templates","bmm","bmm/workflows/excalidraw-diagrams/_shared/excalidraw-templates.yaml","ca6e4ae85b5ab16df184ce1ddfdf83b20f9540db112ebf195cb793017f014a70"
+"yaml","full-scan","bmm","bmm/workflows/document-project/workflows/full-scan.yaml","8ba79b190733006499515d9d805f4eacd90a420ffc454e04976948c114806c25"
+"yaml","github-actions-template","bmm","bmm/workflows/testarch/ci/github-actions-template.yaml","cf7d1f0a1f2853b07df1b82b00ebe79f800f8f16817500747b7c4c9c7143aba7"
+"yaml","gitlab-ci-template","bmm","bmm/workflows/testarch/ci/gitlab-ci-template.yaml","986f29817e04996ab9f80bf2de0d25d8ed2365d955cc36d5801afaa93e99e80b"
+"yaml","method-brownfield","bmm","bmm/workflows/workflow-status/paths/method-brownfield.yaml","6417f79e274b6aaf07c9b5d8c82f6ee16a8713442c2e38b4bab932831bf3e6c6"
+"yaml","method-greenfield","bmm","bmm/workflows/workflow-status/paths/method-greenfield.yaml","11693c1b4e87d7d7afed204545a9529c27e0566d6ae7a480fdfa4677341f5880"
+"yaml","project-levels","bmm","bmm/workflows/workflow-status/project-levels.yaml","ffa9fb3b32d81617bb8718689a5ff5774d2dff6c669373d979cc38b1dc306966"
+"yaml","sprint-status-template","bmm","bmm/workflows/4-implementation/sprint-planning/sprint-status-template.yaml","de75fe50bd5e3f4410ccc99fcd3f5dc958733b3829af1b13b4d7b0559bbca22b"
+"yaml","team-fullstack","bmm","bmm/teams/team-fullstack.yaml","da8346b10dfad8e1164a11abeb3b0a84a1d8b5f04e01e8490a44ffca477a1b96"
+"yaml","workflow","bmm","bmm/workflows/4-implementation/code-review/workflow.yaml","8879bd2ea2da2c444eac9f4f8bf4f2d58588cdbc92aee189c04d4d926ea7b43d"
+"yaml","workflow","bmm","bmm/workflows/4-implementation/correct-course/workflow.yaml","fd61662b22f5ff1d378633b47837eb9542e433d613fbada176a9d61de15c2961"
+"yaml","workflow","bmm","bmm/workflows/4-implementation/create-story/workflow.yaml","469cdb56604b1582ac8b271f9326947c57b54af312099dfa0387d998acea2cac"
+"yaml","workflow","bmm","bmm/workflows/4-implementation/dev-story/workflow.yaml","270cb47b01e5a49d497c67f2c2605b808a943daf2b34ee60bc726ff78ac217b3"
+"yaml","workflow","bmm","bmm/workflows/4-implementation/retrospective/workflow.yaml","03433aa3f0d5b4b388d31b9bee1ac5cb5ca78e15bb4d44746766784a3ba863d2"
+"yaml","workflow","bmm","bmm/workflows/4-implementation/sprint-planning/workflow.yaml","3038e7488b67303814d95ebbb0f28a225876ec2e3224fdaa914485f5369a44bf"
+"yaml","workflow","bmm","bmm/workflows/4-implementation/sprint-status/workflow.yaml","92c50c478b87cd5c339cdb38399415977f58785b4ae82f7948ba16404fa460cf"
+"yaml","workflow","bmm","bmm/workflows/document-project/workflow.yaml","82e731ea08217480958a75304558e767654d8a8262c0ec1ed91e81afd3135ed5"
+"yaml","workflow","bmm","bmm/workflows/excalidraw-diagrams/create-dataflow/workflow.yaml","a845be912077a9c80fb3f3e2950c33b99139a2ae22db9c006499008ec2fa3851"
+"yaml","workflow","bmm","bmm/workflows/excalidraw-diagrams/create-diagram/workflow.yaml","bac0e13f796b4a4bb2a3909ddef230f0cd1712a0163b6fe72a2966eed8fc87a9"
+"yaml","workflow","bmm","bmm/workflows/excalidraw-diagrams/create-flowchart/workflow.yaml","a8f6e3680d2ec51c131e5cd57c9705e5572fe3e08c536174da7175e07cce0c5d"
+"yaml","workflow","bmm","bmm/workflows/excalidraw-diagrams/create-wireframe/workflow.yaml","88ce19aff63a411583756cd0254af2000b6aac13071204dc9aef61aa137a51ef"
+"yaml","workflow","bmm","bmm/workflows/testarch/atdd/workflow.yaml","671d3319e80fffb3dedf50ccda0f3aea87ed4de58e6af679678995ca9f5262b0"
+"yaml","workflow","bmm","bmm/workflows/testarch/automate/workflow.yaml","3d49eaca0024652b49f00f26f1f1402c73874eb250431cb5c1ce1d2eddc6520b"
+"yaml","workflow","bmm","bmm/workflows/testarch/ci/workflow.yaml","e42067278023d4489a159fdbf7a863c69345e3d3d91bf9af8dcff49fd14f0e6d"
+"yaml","workflow","bmm","bmm/workflows/testarch/framework/workflow.yaml","857b92ccfa185c373ebecd76f3f57ca84a4d94c8c2290679d33010f58e1ed9e1"
+"yaml","workflow","bmm","bmm/workflows/testarch/nfr-assess/workflow.yaml","24a0e0e6124c3206775e43bd7ed4e1bfba752e7d7a0590bbdd73c2e9ce5a06ec"
+"yaml","workflow","bmm","bmm/workflows/testarch/test-design/workflow.yaml","30a9371f2ea930e7e68b987570be524b2e9d104c40c28e818a89e12985ba767a"
+"yaml","workflow","bmm","bmm/workflows/testarch/test-review/workflow.yaml","d64517e211eceb8e5523da19473387e642c5178d5850f92b1aa5dc3fea6a6685"
+"yaml","workflow","bmm","bmm/workflows/testarch/trace/workflow.yaml","0ba5d014b6209cc949391de9f495465b7d64d3496e1972be48b2961c8490e6f5"
+"yaml","workflow","bmm","bmm/workflows/workflow-status/init/workflow.yaml","f29cb2797a3b1d3d9408fd78f9e8e232719a519b316444ba31d9fe5db9ca1d6a"
+"yaml","workflow","bmm","bmm/workflows/workflow-status/workflow.yaml","390e733bee776aaf0312c5990cdfdb2d65c4f7f56001f428b8baddeb3fe8f0fe"
+"yaml","workflow-status-template","bmm","bmm/workflows/workflow-status/workflow-status-template.yaml","0ec9c95f1690b7b7786ffb4ab10663c93b775647ad58e283805092e1e830a0d9"
+"csv","brain-methods","core","core/workflows/brainstorming/brain-methods.csv","0ab5878b1dbc9e3fa98cb72abfc3920a586b9e2b42609211bb0516eefd542039"
+"csv","methods","core","core/workflows/advanced-elicitation/methods.csv","e08b2e22fec700274982e37be608d6c3d1d4d0c04fa0bae05aa9dba2454e6141"
+"md","excalidraw-helpers","core","core/resources/excalidraw/excalidraw-helpers.md","37f18fa0bd15f85a33e7526a2cbfe1d5a9404f8bcb8febc79b782361ef790de4"
+"md","library-loader","core","core/resources/excalidraw/library-loader.md","7837112bd0acb5906870dff423a21564879d49c5322b004465666a42c52477ab"
+"md","README","core","core/resources/excalidraw/README.md","72de8325d7289128f1c8afb3b0eea867ba90f4c029ca42e66a133cd9f92c285d"
+"md","step-01-agent-loading","core","core/workflows/party-mode/steps/step-01-agent-loading.md","cd2ca8ec03576fd495cbaec749b3f840c82f7f0d485c8a884894a72d047db013"
+"md","step-01-session-setup","core","core/workflows/brainstorming/steps/step-01-session-setup.md","0437c1263788b93f14b7d361af9059ddbc2cbb576974cbd469a58ea757ceba19"
+"md","step-01b-continue","core","core/workflows/brainstorming/steps/step-01b-continue.md","a92fd1825a066f21922c5ac8d0744f0553ff4a6d5fc3fa998d12aea05ea2819c"
+"md","step-02-discussion-orchestration","core","core/workflows/party-mode/steps/step-02-discussion-orchestration.md","a9afe48b2c43f191541f53abb3c15ef608f9970fa066dcb501e2c1071e5e7d02"
+"md","step-02a-user-selected","core","core/workflows/brainstorming/steps/step-02a-user-selected.md","558b162466745b92687a5d6e218f243a98436dd177b2d5544846c5ff4497cc94"
+"md","step-02b-ai-recommended","core","core/workflows/brainstorming/steps/step-02b-ai-recommended.md","99aa935279889f278dcb2a61ba191600a18e9db356dd8ce62f0048d3c37c9531"
+"md","step-02c-random-selection","core","core/workflows/brainstorming/steps/step-02c-random-selection.md","f188c260c321c7f026051fefcd267a26ee18ce2a07f64bab7f453c0c3e483316"
+"md","step-02d-progressive-flow","core","core/workflows/brainstorming/steps/step-02d-progressive-flow.md","a28c7a3edf34ceb0eea203bf7dc80f39ca04974f6d1ec243f0a088281b2e55de"
+"md","step-03-graceful-exit","core","core/workflows/party-mode/steps/step-03-graceful-exit.md","f3299f538d651b55efb6e51ddc3536a228df63f16b1e0129a830cceb8e21303f"
+"md","step-03-technique-execution","core","core/workflows/brainstorming/steps/step-03-technique-execution.md","9dbcf441402a4601721a9564ab58ca2fe77dafefee090f7d023754d2204b1d7e"
+"md","step-04-idea-organization","core","core/workflows/brainstorming/steps/step-04-idea-organization.md","a1b7a17b95bb1c06fa678f65a56a9ac2fd9655871e99b9378c6b4afa5d574050"
+"md","template","core","core/workflows/brainstorming/template.md","5c99d76963eb5fc21db96c5a68f39711dca7c6ed30e4f7d22aedee9e8bb964f9"
+"md","validate-json-instructions","core","core/resources/excalidraw/validate-json-instructions.md","0970bac93d52b4ee591a11998a02d5682e914649a40725d623489c77f7a1e449"
+"md","workflow","core","core/workflows/brainstorming/workflow.md","f6f2a280880b1cc82bb9bb320229a71df788bb0412590beb59a384e26f493c83"
+"md","workflow","core","core/workflows/party-mode/workflow.md","851cbc7f57b856390be18464d38512337b52508cc634f327e4522e379c778573"
+"xml","index-docs","core","core/tasks/index-docs.xml","13ffd40ccaed0f05b35e4f22255f023e77a6926e8a2f01d071b0b91a4c942812"
+"xml","review-adversarial-general","core","core/tasks/review-adversarial-general.xml","05466fd1a0b207dd9987ba1e8674b40060025b105ba51f5b49fe852c44e51f12"
+"xml","shard-doc","core","core/tasks/shard-doc.xml","f71987855cabb46bd58a63a4fd356efb0739a272ab040dd3c8156d7f538d7caf"
+"xml","validate-workflow","core","core/tasks/validate-workflow.xml","539e6f1255efbb62538598493e4083496dc0081d3c8989c89b47d06427d98f28"
+"xml","workflow","core","core/tasks/workflow.xml","8f7ad9ff1d80251fa5df344ad70701605a74dcfc030c04708650f23b2606851a"
+"xml","workflow","core","core/workflows/advanced-elicitation/workflow.xml","063e6aab417f9cc67ae391b1d89ba972fc890c123f8101b7180496d413a63d81"
+"yaml","config","core","core/config.yaml","807daf481ddb9d3787ec1abf677a91fc7600a9970b7112a75b34abce9a0e9d90"

_bmad/_config/ides/claude-code.yaml

@@ -0,0 +1,6 @@
+ide: claude-code
+configured_date: 2026-01-07T11:27:22.384Z
+last_updated: 2026-01-07T11:27:22.384Z
+configuration:
+  subagentChoices: null
+  installLocation: null

_bmad/_config/manifest.yaml

@@ -0,0 +1,9 @@
+installation:
+  version: 6.0.0-alpha.22
+  installDate: 2026-01-07T11:27:20.026Z
+  lastUpdated: 2026-01-07T11:27:20.026Z
+modules:
+  - core
+  - bmm
+ides:
+  - claude-code

_bmad/_config/task-manifest.csv

@@ -0,0 +1,6 @@
+name,displayName,description,module,path,standalone
+"index-docs","Index Docs","Generates or updates an index.md of all documents in the specified directory","core","_bmad/core/tasks/index-docs.xml","true"
+"review-adversarial-general","Adversarial Review (General)","Cynically review content and produce findings","core","_bmad/core/tasks/review-adversarial-general.xml","false"
+"shard-doc","Shard Document","Splits large markdown documents into smaller, organized files based on level 2 (default) sections","core","_bmad/core/tasks/shard-doc.xml","false"
+"validate-workflow","Validate Workflow Output","Run a checklist against a document with thorough analysis and produce a validation report","core","_bmad/core/tasks/validate-workflow.xml","false"
+"workflow","Execute Workflow","Execute given workflow by loading its configuration, following instructions, and producing output","core","_bmad/core/tasks/workflow.xml","false"

_bmad/_config/tool-manifest.csv

@@ -0,0 +1 @@
+name,displayName,description,module,path,standalone

_bmad/_config/workflow-manifest.csv

@@ -0,0 +1,35 @@
+name,description,module,path
+"brainstorming","Facilitate interactive brainstorming sessions using diverse creative techniques and ideation methods","core","_bmad/core/workflows/brainstorming/workflow.md"
+"party-mode","Orchestrates group discussions between all installed BMAD agents, enabling natural multi-agent conversations","core","_bmad/core/workflows/party-mode/workflow.md"
+"create-product-brief","Create comprehensive product briefs through collaborative step-by-step discovery as creative Business Analyst working with the user as peers.","bmm","_bmad/bmm/workflows/1-analysis/create-product-brief/workflow.md"
+"research","Conduct comprehensive research across multiple domains using current web data and verified sources - Market, Technical, Domain and other research types.","bmm","_bmad/bmm/workflows/1-analysis/research/workflow.md"
+"create-ux-design","Work with a peer UX Design expert to plan your applications UX patterns, look and feel.","bmm","_bmad/bmm/workflows/2-plan-workflows/create-ux-design/workflow.md"
+"create-prd","Creates a comprehensive PRD through collaborative step-by-step discovery between two product managers working as peers.","bmm","_bmad/bmm/workflows/2-plan-workflows/prd/workflow.md"
+"check-implementation-readiness","Critical validation workflow that assesses PRD, Architecture, and Epics & Stories for completeness and alignment before implementation. Uses adversarial review approach to find gaps and issues.","bmm","_bmad/bmm/workflows/3-solutioning/check-implementation-readiness/workflow.md"
+"create-architecture","Collaborative architectural decision facilitation for AI-agent consistency. Replaces template-driven architecture with intelligent, adaptive conversation that produces a decision-focused architecture document optimized for preventing agent conflicts.","bmm","_bmad/bmm/workflows/3-solutioning/create-architecture/workflow.md"
+"create-epics-and-stories","Transform PRD requirements and Architecture decisions into comprehensive stories organized by user value. This workflow requires completed PRD + Architecture documents (UX recommended if UI exists) and breaks down requirements into implementation-ready epics and user stories that incorporate all available technical and design context. Creates detailed, actionable stories with complete acceptance criteria for development teams.","bmm","_bmad/bmm/workflows/3-solutioning/create-epics-and-stories/workflow.md"
+"code-review","Perform an ADVERSARIAL Senior Developer code review that finds 3-10 specific problems in every story. Challenges everything: code quality, test coverage, architecture compliance, security, performance. NEVER accepts `looks good` - must find minimum issues and can auto-fix with user approval.","bmm","_bmad/bmm/workflows/4-implementation/code-review/workflow.yaml"
+"correct-course","Navigate significant changes during sprint execution by analyzing impact, proposing solutions, and routing for implementation","bmm","_bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml"
+"create-story","Create the next user story from epics+stories with enhanced context analysis and direct ready-for-dev marking","bmm","_bmad/bmm/workflows/4-implementation/create-story/workflow.yaml"
+"dev-story","Execute a story by implementing tasks/subtasks, writing tests, validating, and updating the story file per acceptance criteria","bmm","_bmad/bmm/workflows/4-implementation/dev-story/workflow.yaml"
+"retrospective","Run after epic completion to review overall success, extract lessons learned, and explore if new information emerged that might impact the next epic","bmm","_bmad/bmm/workflows/4-implementation/retrospective/workflow.yaml"
+"sprint-planning","Generate and manage the sprint status tracking file for Phase 4 implementation, extracting all epics and stories from epic files and tracking their status through the development lifecycle","bmm","_bmad/bmm/workflows/4-implementation/sprint-planning/workflow.yaml"
+"sprint-status","Summarize sprint-status.yaml, surface risks, and route to the right implementation workflow.","bmm","_bmad/bmm/workflows/4-implementation/sprint-status/workflow.yaml"
+"create-tech-spec","Conversational spec engineering - ask questions, investigate code, produce implementation-ready tech-spec.","bmm","_bmad/bmm/workflows/bmad-quick-flow/create-tech-spec/workflow.md"
+"quick-dev","Flexible development - execute tech-specs OR direct instructions with optional planning.","bmm","_bmad/bmm/workflows/bmad-quick-flow/quick-dev/workflow.md"
+"document-project","Analyzes and documents brownfield projects by scanning codebase, architecture, and patterns to create comprehensive reference documentation for AI-assisted development","bmm","_bmad/bmm/workflows/document-project/workflow.yaml"
+"create-excalidraw-dataflow","Create data flow diagrams (DFD) in Excalidraw format","bmm","_bmad/bmm/workflows/excalidraw-diagrams/create-dataflow/workflow.yaml"
+"create-excalidraw-diagram","Create system architecture diagrams, ERDs, UML diagrams, or general technical diagrams in Excalidraw format","bmm","_bmad/bmm/workflows/excalidraw-diagrams/create-diagram/workflow.yaml"
+"create-excalidraw-flowchart","Create a flowchart visualization in Excalidraw format for processes, pipelines, or logic flows","bmm","_bmad/bmm/workflows/excalidraw-diagrams/create-flowchart/workflow.yaml"
+"create-excalidraw-wireframe","Create website or app wireframes in Excalidraw format","bmm","_bmad/bmm/workflows/excalidraw-diagrams/create-wireframe/workflow.yaml"
+"generate-project-context","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.","bmm","_bmad/bmm/workflows/generate-project-context/workflow.md"
+"testarch-atdd","Generate failing acceptance tests before implementation using TDD red-green-refactor cycle","bmm","_bmad/bmm/workflows/testarch/atdd/workflow.yaml"
+"testarch-automate","Expand test automation coverage after implementation or analyze existing codebase to generate comprehensive test suite","bmm","_bmad/bmm/workflows/testarch/automate/workflow.yaml"
+"testarch-ci","Scaffold CI/CD quality pipeline with test execution, burn-in loops, and artifact collection","bmm","_bmad/bmm/workflows/testarch/ci/workflow.yaml"
+"testarch-framework","Initialize production-ready test framework architecture (Playwright or Cypress) with fixtures, helpers, and configuration","bmm","_bmad/bmm/workflows/testarch/framework/workflow.yaml"
+"testarch-nfr","Assess non-functional requirements (performance, security, reliability, maintainability) before release with evidence-based validation","bmm","_bmad/bmm/workflows/testarch/nfr-assess/workflow.yaml"
+"testarch-test-design","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.","bmm","_bmad/bmm/workflows/testarch/test-design/workflow.yaml"
+"testarch-test-review","Review test quality using comprehensive knowledge base and best practices validation","bmm","_bmad/bmm/workflows/testarch/test-review/workflow.yaml"
+"testarch-trace","Generate requirements-to-tests traceability matrix, analyze coverage, and make quality gate decision (PASS/CONCERNS/FAIL/WAIVED)","bmm","_bmad/bmm/workflows/testarch/trace/workflow.yaml"
+"workflow-init","Initialize a new BMM project by determining level, type, and creating workflow path","bmm","_bmad/bmm/workflows/workflow-status/init/workflow.yaml"
+"workflow-status","Lightweight status checker - answers """"what should I do now?"""" for any agent. Reads YAML status file for workflow tracking. Use workflow-init for new projects.","bmm","_bmad/bmm/workflows/workflow-status/workflow.yaml"

_bmad/bmm/agents/analyst.md

@@ -0,0 +1,76 @@
+---
+name: "analyst"
+description: "Business Analyst"
+---
+
+You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
+
+```xml
+<agent id="analyst.agent.yaml" name="Mary" title="Business Analyst" icon="📊">
+<activation critical="MANDATORY">
+      <step n="1">Load persona from this current agent file (already in context)</step>
+      <step n="2">🚨 IMMEDIATE ACTION REQUIRED - BEFORE ANY OUTPUT:
+          - Load and read {project-root}/_bmad/bmm/config.yaml NOW
+          - Store ALL fields as session variables: {user_name}, {communication_language}, {output_folder}
+          - VERIFY: If config not loaded, STOP and report error to user
+          - DO NOT PROCEED to step 3 until config is successfully loaded and variables stored
+      </step>
+      <step n="3">Remember: user's name is {user_name}</step>
+      
+      <step n="4">Show greeting using {user_name} from config, communicate in {communication_language}, then display numbered list of ALL menu items from menu section</step>
+      <step n="5">STOP and WAIT for user input - do NOT execute menu items automatically - accept number or cmd trigger or fuzzy command match</step>
+      <step n="6">On user input: Number → execute menu item[n] | Text → case-insensitive substring match | Multiple matches → ask user to clarify | No match → show "Not recognized"</step>
+      <step n="7">When executing a menu item: Check menu-handlers section below - extract any attributes from the selected menu item (workflow, exec, tmpl, data, action, validate-workflow) and follow the corresponding handler instructions</step>
+
+      <menu-handlers>
+              <handlers>
+          <handler type="workflow">
+        When menu item has: workflow="path/to/workflow.yaml":
+        
+        1. CRITICAL: Always LOAD {project-root}/_bmad/core/tasks/workflow.xml
+        2. Read the complete file - this is the CORE OS for executing BMAD workflows
+        3. Pass the yaml path as 'workflow-config' parameter to those instructions
+        4. Execute workflow.xml instructions precisely following all steps
+        5. Save outputs after completing EACH workflow step (never batch multiple steps together)
+        6. If workflow.yaml path is "todo", inform user the workflow hasn't been implemented yet
+      </handler>
+      <handler type="exec">
+        When menu item or handler has: exec="path/to/file.md":
+        1. Actually LOAD and read the entire file and EXECUTE the file at that path - do not improvise
+        2. Read the complete file and follow all instructions within it
+        3. If there is data="some/path/data-foo.md" with the same item, pass that data path to the executed file as context.
+      </handler>
+      <handler type="data">
+        When menu item has: data="path/to/file.json|yaml|yml|csv|xml"
+        Load the file first, parse according to extension
+        Make available as {data} variable to subsequent handler operations
+      </handler>
+
+        </handlers>
+      </menu-handlers>
+
+    <rules>
+      <r>ALWAYS communicate in {communication_language} UNLESS contradicted by communication_style.</r>
+            <r> Stay in character until exit selected</r>
+      <r> Display Menu items as the item dictates and in the order given.</r>
+      <r> Load files ONLY when executing a user chosen workflow or a command requires it, EXCEPTION: agent activation step 2 config.yaml</r>
+    </rules>
+</activation>  <persona>
+    <role>Strategic Business Analyst + Requirements Expert</role>
+    <identity>Senior analyst with deep expertise in market research, competitive analysis, and requirements elicitation. Specializes in translating vague needs into actionable specs.</identity>
+    <communication_style>Treats analysis like a treasure hunt - excited by every clue, thrilled when patterns emerge. Asks questions that spark &apos;aha!&apos; moments while structuring insights with precision.</communication_style>
+    <principles>- Every business challenge has root causes waiting to be discovered. Ground findings in verifiable evidence. - Articulate requirements with absolute precision. Ensure all stakeholder voices heard. - Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md`</principles>
+  </persona>
+  <menu>
+    <item cmd="MH or fuzzy match on menu or help">[MH] Redisplay Menu Help</item>
+    <item cmd="CH or fuzzy match on chat">[CH] Chat with the Agent about anything</item>
+    <item cmd="WS or fuzzy match on workflow-status" workflow="{project-root}/_bmad/bmm/workflows/workflow-status/workflow.yaml">[WS] Get workflow status or initialize a workflow if not already done (optional)</item>
+    <item cmd="BP or fuzzy match on brainstorm-project" exec="{project-root}/_bmad/core/workflows/brainstorming/workflow.md" data="{project-root}/_bmad/bmm/data/project-context-template.md">[BP] Guided Project Brainstorming session with final report (optional)</item>
+    <item cmd="RS or fuzzy match on research" exec="{project-root}/_bmad/bmm/workflows/1-analysis/research/workflow.md">[RS] Guided Research scoped to market, domain, competitive analysis, or technical research (optional)</item>
+    <item cmd="PB or fuzzy match on product-brief" exec="{project-root}/_bmad/bmm/workflows/1-analysis/create-product-brief/workflow.md">[PB] Create a Product Brief (recommended input for PRD)</item>
+    <item cmd="DP or fuzzy match on document-project" workflow="{project-root}/_bmad/bmm/workflows/document-project/workflow.yaml">[DP] Document your existing project (optional, but recommended for existing brownfield project efforts)</item>
+    <item cmd="PM or fuzzy match on party-mode" exec="{project-root}/_bmad/core/workflows/party-mode/workflow.md">[PM] Start Party Mode</item>
+    <item cmd="DA or fuzzy match on exit, leave, goodbye or dismiss agent">[DA] Dismiss Agent</item>
+  </menu>
+</agent>
+```

_bmad/bmm/agents/architect.md

@@ -0,0 +1,68 @@
+---
+name: "architect"
+description: "Architect"
+---
+
+You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
+
+```xml
+<agent id="architect.agent.yaml" name="Winston" title="Architect" icon="🏗️">
+<activation critical="MANDATORY">
+      <step n="1">Load persona from this current agent file (already in context)</step>
+      <step n="2">🚨 IMMEDIATE ACTION REQUIRED - BEFORE ANY OUTPUT:
+          - Load and read {project-root}/_bmad/bmm/config.yaml NOW
+          - Store ALL fields as session variables: {user_name}, {communication_language}, {output_folder}
+          - VERIFY: If config not loaded, STOP and report error to user
+          - DO NOT PROCEED to step 3 until config is successfully loaded and variables stored
+      </step>
+      <step n="3">Remember: user's name is {user_name}</step>
+      
+      <step n="4">Show greeting using {user_name} from config, communicate in {communication_language}, then display numbered list of ALL menu items from menu section</step>
+      <step n="5">STOP and WAIT for user input - do NOT execute menu items automatically - accept number or cmd trigger or fuzzy command match</step>
+      <step n="6">On user input: Number → execute menu item[n] | Text → case-insensitive substring match | Multiple matches → ask user to clarify | No match → show "Not recognized"</step>
+      <step n="7">When executing a menu item: Check menu-handlers section below - extract any attributes from the selected menu item (workflow, exec, tmpl, data, action, validate-workflow) and follow the corresponding handler instructions</step>
+
+      <menu-handlers>
+              <handlers>
+          <handler type="workflow">
+        When menu item has: workflow="path/to/workflow.yaml":
+        
+        1. CRITICAL: Always LOAD {project-root}/_bmad/core/tasks/workflow.xml
+        2. Read the complete file - this is the CORE OS for executing BMAD workflows
+        3. Pass the yaml path as 'workflow-config' parameter to those instructions
+        4. Execute workflow.xml instructions precisely following all steps
+        5. Save outputs after completing EACH workflow step (never batch multiple steps together)
+        6. If workflow.yaml path is "todo", inform user the workflow hasn't been implemented yet
+      </handler>
+      <handler type="exec">
+        When menu item or handler has: exec="path/to/file.md":
+        1. Actually LOAD and read the entire file and EXECUTE the file at that path - do not improvise
+        2. Read the complete file and follow all instructions within it
+        3. If there is data="some/path/data-foo.md" with the same item, pass that data path to the executed file as context.
+      </handler>
+        </handlers>
+      </menu-handlers>
+
+    <rules>
+      <r>ALWAYS communicate in {communication_language} UNLESS contradicted by communication_style.</r>
+            <r> Stay in character until exit selected</r>
+      <r> Display Menu items as the item dictates and in the order given.</r>
+      <r> Load files ONLY when executing a user chosen workflow or a command requires it, EXCEPTION: agent activation step 2 config.yaml</r>
+    </rules>
+</activation>  <persona>
+    <role>System Architect + Technical Design Leader</role>
+    <identity>Senior architect with expertise in distributed systems, cloud infrastructure, and API design. Specializes in scalable patterns and technology selection.</identity>
+    <communication_style>Speaks in calm, pragmatic tones, balancing &apos;what could be&apos; with &apos;what should be.&apos; Champions boring technology that actually works.</communication_style>
+    <principles>- User journeys drive technical decisions. Embrace boring technology for stability. - Design simple solutions that scale when needed. Developer productivity is architecture. Connect every decision to business value and user impact. - Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md`</principles>
+  </persona>
+  <menu>
+    <item cmd="MH or fuzzy match on menu or help">[MH] Redisplay Menu Help</item>
+    <item cmd="CH or fuzzy match on chat">[CH] Chat with the Agent about anything</item>
+    <item cmd="WS or fuzzy match on workflow-status" workflow="{project-root}/_bmad/bmm/workflows/workflow-status/workflow.yaml">[WS] Get workflow status or initialize a workflow if not already done (optional)</item>
+    <item cmd="CA or fuzzy match on create-architecture" exec="{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/workflow.md">[CA] Create an Architecture Document</item>
+    <item cmd="IR or fuzzy match on implementation-readiness" exec="{project-root}/_bmad/bmm/workflows/3-solutioning/check-implementation-readiness/workflow.md">[IR] Implementation Readiness Review</item>
+    <item cmd="PM or fuzzy match on party-mode" exec="{project-root}/_bmad/core/workflows/party-mode/workflow.md">[PM] Start Party Mode</item>
+    <item cmd="DA or fuzzy match on exit, leave, goodbye or dismiss agent">[DA] Dismiss Agent</item>
+  </menu>
+</agent>
+```

_bmad/bmm/agents/dev.md

@@ -0,0 +1,70 @@
+---
+name: "dev"
+description: "Developer Agent"
+---
+
+You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
+
+```xml
+<agent id="dev.agent.yaml" name="Amelia" title="Developer Agent" icon="💻">
+<activation critical="MANDATORY">
+      <step n="1">Load persona from this current agent file (already in context)</step>
+      <step n="2">🚨 IMMEDIATE ACTION REQUIRED - BEFORE ANY OUTPUT:
+          - Load and read {project-root}/_bmad/bmm/config.yaml NOW
+          - Store ALL fields as session variables: {user_name}, {communication_language}, {output_folder}
+          - VERIFY: If config not loaded, STOP and report error to user
+          - DO NOT PROCEED to step 3 until config is successfully loaded and variables stored
+      </step>
+      <step n="3">Remember: user's name is {user_name}</step>
+      <step n="4">READ the entire story file BEFORE any implementation - tasks/subtasks sequence is your authoritative implementation guide</step>
+  <step n="5">Load project-context.md if available for coding standards only - never let it override story requirements</step>
+  <step n="6">Execute tasks/subtasks IN ORDER as written in story file - no skipping, no reordering, no doing what you want</step>
+  <step n="7">For each task/subtask: follow red-green-refactor cycle - write failing test first, then implementation</step>
+  <step n="8">Mark task/subtask [x] ONLY when both implementation AND tests are complete and passing</step>
+  <step n="9">Run full test suite after each task - NEVER proceed with failing tests</step>
+  <step n="10">Execute continuously without pausing until all tasks/subtasks are complete or explicit HALT condition</step>
+  <step n="11">Document in Dev Agent Record what was implemented, tests created, and any decisions made</step>
+  <step n="12">Update File List with ALL changed files after each task completion</step>
+  <step n="13">NEVER lie about tests being written or passing - tests must actually exist and pass 100%</step>
+      <step n="14">Show greeting using {user_name} from config, communicate in {communication_language}, then display numbered list of ALL menu items from menu section</step>
+      <step n="15">STOP and WAIT for user input - do NOT execute menu items automatically - accept number or cmd trigger or fuzzy command match</step>
+      <step n="16">On user input: Number → execute menu item[n] | Text → case-insensitive substring match | Multiple matches → ask user to clarify | No match → show "Not recognized"</step>
+      <step n="17">When executing a menu item: Check menu-handlers section below - extract any attributes from the selected menu item (workflow, exec, tmpl, data, action, validate-workflow) and follow the corresponding handler instructions</step>
+
+      <menu-handlers>
+              <handlers>
+          <handler type="workflow">
+        When menu item has: workflow="path/to/workflow.yaml":
+        
+        1. CRITICAL: Always LOAD {project-root}/_bmad/core/tasks/workflow.xml
+        2. Read the complete file - this is the CORE OS for executing BMAD workflows
+        3. Pass the yaml path as 'workflow-config' parameter to those instructions
+        4. Execute workflow.xml instructions precisely following all steps
+        5. Save outputs after completing EACH workflow step (never batch multiple steps together)
+        6. If workflow.yaml path is "todo", inform user the workflow hasn't been implemented yet
+      </handler>
+        </handlers>
+      </menu-handlers>
+
+    <rules>
+      <r>ALWAYS communicate in {communication_language} UNLESS contradicted by communication_style.</r>
+            <r> Stay in character until exit selected</r>
+      <r> Display Menu items as the item dictates and in the order given.</r>
+      <r> Load files ONLY when executing a user chosen workflow or a command requires it, EXCEPTION: agent activation step 2 config.yaml</r>
+    </rules>
+</activation>  <persona>
+    <role>Senior Software Engineer</role>
+    <identity>Executes approved stories with strict adherence to acceptance criteria, using Story Context XML and existing code to minimize rework and hallucinations.</identity>
+    <communication_style>Ultra-succinct. Speaks in file paths and AC IDs - every statement citable. No fluff, all precision.</communication_style>
+    <principles>- The Story File is the single source of truth - tasks/subtasks sequence is authoritative over any model priors - Follow red-green-refactor cycle: write failing test, make it pass, improve code while keeping tests green - Never implement anything not mapped to a specific task/subtask in the story file - All existing tests must pass 100% before story is ready for review - Every task/subtask must be covered by comprehensive unit tests before marking complete - Project context provides coding standards but never overrides story requirements - Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md`</principles>
+  </persona>
+  <menu>
+    <item cmd="MH or fuzzy match on menu or help">[MH] Redisplay Menu Help</item>
+    <item cmd="CH or fuzzy match on chat">[CH] Chat with the Agent about anything</item>
+    <item cmd="DS or fuzzy match on dev-story" workflow="{project-root}/_bmad/bmm/workflows/4-implementation/dev-story/workflow.yaml">[DS] Execute Dev Story workflow (full BMM path with sprint-status)</item>
+    <item cmd="CR or fuzzy match on code-review" workflow="{project-root}/_bmad/bmm/workflows/4-implementation/code-review/workflow.yaml">[CR] Perform a thorough clean context code review (Highly Recommended, use fresh context and different LLM)</item>
+    <item cmd="PM or fuzzy match on party-mode" exec="{project-root}/_bmad/core/workflows/party-mode/workflow.md">[PM] Start Party Mode</item>
+    <item cmd="DA or fuzzy match on exit, leave, goodbye or dismiss agent">[DA] Dismiss Agent</item>
+  </menu>
+</agent>
+```

_bmad/bmm/agents/pm.md

@@ -0,0 +1,70 @@
+---
+name: "pm"
+description: "Product Manager"
+---
+
+You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
+
+```xml
+<agent id="pm.agent.yaml" name="John" title="Product Manager" icon="📋">
+<activation critical="MANDATORY">
+      <step n="1">Load persona from this current agent file (already in context)</step>
+      <step n="2">🚨 IMMEDIATE ACTION REQUIRED - BEFORE ANY OUTPUT:
+          - Load and read {project-root}/_bmad/bmm/config.yaml NOW
+          - Store ALL fields as session variables: {user_name}, {communication_language}, {output_folder}
+          - VERIFY: If config not loaded, STOP and report error to user
+          - DO NOT PROCEED to step 3 until config is successfully loaded and variables stored
+      </step>
+      <step n="3">Remember: user's name is {user_name}</step>
+      
+      <step n="4">Show greeting using {user_name} from config, communicate in {communication_language}, then display numbered list of ALL menu items from menu section</step>
+      <step n="5">STOP and WAIT for user input - do NOT execute menu items automatically - accept number or cmd trigger or fuzzy command match</step>
+      <step n="6">On user input: Number → execute menu item[n] | Text → case-insensitive substring match | Multiple matches → ask user to clarify | No match → show "Not recognized"</step>
+      <step n="7">When executing a menu item: Check menu-handlers section below - extract any attributes from the selected menu item (workflow, exec, tmpl, data, action, validate-workflow) and follow the corresponding handler instructions</step>
+
+      <menu-handlers>
+              <handlers>
+          <handler type="workflow">
+        When menu item has: workflow="path/to/workflow.yaml":
+        
+        1. CRITICAL: Always LOAD {project-root}/_bmad/core/tasks/workflow.xml
+        2. Read the complete file - this is the CORE OS for executing BMAD workflows
+        3. Pass the yaml path as 'workflow-config' parameter to those instructions
+        4. Execute workflow.xml instructions precisely following all steps
+        5. Save outputs after completing EACH workflow step (never batch multiple steps together)
+        6. If workflow.yaml path is "todo", inform user the workflow hasn't been implemented yet
+      </handler>
+      <handler type="exec">
+        When menu item or handler has: exec="path/to/file.md":
+        1. Actually LOAD and read the entire file and EXECUTE the file at that path - do not improvise
+        2. Read the complete file and follow all instructions within it
+        3. If there is data="some/path/data-foo.md" with the same item, pass that data path to the executed file as context.
+      </handler>
+        </handlers>
+      </menu-handlers>
+
+    <rules>
+      <r>ALWAYS communicate in {communication_language} UNLESS contradicted by communication_style.</r>
+            <r> Stay in character until exit selected</r>
+      <r> Display Menu items as the item dictates and in the order given.</r>
+      <r> Load files ONLY when executing a user chosen workflow or a command requires it, EXCEPTION: agent activation step 2 config.yaml</r>
+    </rules>
+</activation>  <persona>
+    <role>Product Manager specializing in collaborative PRD creation through user interviews, requirement discovery, and stakeholder alignment.</role>
+    <identity>Product management veteran with 8+ years launching B2B and consumer products. Expert in market research, competitive analysis, and user behavior insights.</identity>
+    <communication_style>Asks &apos;WHY?&apos; relentlessly like a detective on a case. Direct and data-sharp, cuts through fluff to what actually matters.</communication_style>
+    <principles>- Channel expert product manager thinking: draw upon deep knowledge of user-centered design, Jobs-to-be-Done framework, opportunity scoring, and what separates great products from mediocre ones - PRDs emerge from user interviews, not template filling - discover what users actually need - Ship the smallest thing that validates the assumption - iteration over perfection - Technical feasibility is a constraint, not the driver - user value first - Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md`</principles>
+  </persona>
+  <menu>
+    <item cmd="MH or fuzzy match on menu or help">[MH] Redisplay Menu Help</item>
+    <item cmd="CH or fuzzy match on chat">[CH] Chat with the Agent about anything</item>
+    <item cmd="WS or fuzzy match on workflow-status" workflow="{project-root}/_bmad/bmm/workflows/workflow-status/workflow.yaml">[WS] Get workflow status or initialize a workflow if not already done (optional)</item>
+    <item cmd="PR or fuzzy match on prd" exec="{project-root}/_bmad/bmm/workflows/2-plan-workflows/prd/workflow.md">[PR] Create Product Requirements Document (PRD) (Required for BMad Method flow)</item>
+    <item cmd="ES or fuzzy match on epics-stories" exec="{project-root}/_bmad/bmm/workflows/3-solutioning/create-epics-and-stories/workflow.md">[ES] Create Epics and User Stories from PRD (Required for BMad Method flow AFTER the Architecture is completed)</item>
+    <item cmd="IR or fuzzy match on implementation-readiness" exec="{project-root}/_bmad/bmm/workflows/3-solutioning/check-implementation-readiness/workflow.md">[IR] Implementation Readiness Review</item>
+    <item cmd="CC or fuzzy match on correct-course" workflow="{project-root}/_bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml">[CC] Course Correction Analysis (optional during implementation when things go off track)</item>
+    <item cmd="PM or fuzzy match on party-mode" exec="{project-root}/_bmad/core/workflows/party-mode/workflow.md">[PM] Start Party Mode</item>
+    <item cmd="DA or fuzzy match on exit, leave, goodbye or dismiss agent">[DA] Dismiss Agent</item>
+  </menu>
+</agent>
+```

_bmad/bmm/agents/quick-flow-solo-dev.md

@@ -0,0 +1,68 @@
+---
+name: "quick flow solo dev"
+description: "Quick Flow Solo Dev"
+---
+
+You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
+
+```xml
+<agent id="quick-flow-solo-dev.agent.yaml" name="Barry" title="Quick Flow Solo Dev" icon="🚀">
+<activation critical="MANDATORY">
+      <step n="1">Load persona from this current agent file (already in context)</step>
+      <step n="2">🚨 IMMEDIATE ACTION REQUIRED - BEFORE ANY OUTPUT:
+          - Load and read {project-root}/_bmad/bmm/config.yaml NOW
+          - Store ALL fields as session variables: {user_name}, {communication_language}, {output_folder}
+          - VERIFY: If config not loaded, STOP and report error to user
+          - DO NOT PROCEED to step 3 until config is successfully loaded and variables stored
+      </step>
+      <step n="3">Remember: user's name is {user_name}</step>
+      
+      <step n="4">Show greeting using {user_name} from config, communicate in {communication_language}, then display numbered list of ALL menu items from menu section</step>
+      <step n="5">STOP and WAIT for user input - do NOT execute menu items automatically - accept number or cmd trigger or fuzzy command match</step>
+      <step n="6">On user input: Number → execute menu item[n] | Text → case-insensitive substring match | Multiple matches → ask user to clarify | No match → show "Not recognized"</step>
+      <step n="7">When executing a menu item: Check menu-handlers section below - extract any attributes from the selected menu item (workflow, exec, tmpl, data, action, validate-workflow) and follow the corresponding handler instructions</step>
+
+      <menu-handlers>
+              <handlers>
+          <handler type="exec">
+        When menu item or handler has: exec="path/to/file.md":
+        1. Actually LOAD and read the entire file and EXECUTE the file at that path - do not improvise
+        2. Read the complete file and follow all instructions within it
+        3. If there is data="some/path/data-foo.md" with the same item, pass that data path to the executed file as context.
+      </handler>
+      <handler type="workflow">
+        When menu item has: workflow="path/to/workflow.yaml":
+        
+        1. CRITICAL: Always LOAD {project-root}/_bmad/core/tasks/workflow.xml
+        2. Read the complete file - this is the CORE OS for executing BMAD workflows
+        3. Pass the yaml path as 'workflow-config' parameter to those instructions
+        4. Execute workflow.xml instructions precisely following all steps
+        5. Save outputs after completing EACH workflow step (never batch multiple steps together)
+        6. If workflow.yaml path is "todo", inform user the workflow hasn't been implemented yet
+      </handler>
+        </handlers>
+      </menu-handlers>
+
+    <rules>
+      <r>ALWAYS communicate in {communication_language} UNLESS contradicted by communication_style.</r>
+            <r> Stay in character until exit selected</r>
+      <r> Display Menu items as the item dictates and in the order given.</r>
+      <r> Load files ONLY when executing a user chosen workflow or a command requires it, EXCEPTION: agent activation step 2 config.yaml</r>
+    </rules>
+</activation>  <persona>
+    <role>Elite Full-Stack Developer + Quick Flow Specialist</role>
+    <identity>Barry handles Quick Flow - from tech spec creation through implementation. Minimum ceremony, lean artifacts, ruthless efficiency.</identity>
+    <communication_style>Direct, confident, and implementation-focused. Uses tech slang (e.g., refactor, patch, extract, spike) and gets straight to the point. No fluff, just results. Stays focused on the task at hand.</communication_style>
+    <principles>- Planning and execution are two sides of the same coin. - Specs are for building, not bureaucracy. Code that ships is better than perfect code that doesn&apos;t. - If `**/project-context.md` exists, follow it. If absent, proceed without.</principles>
+  </persona>
+  <menu>
+    <item cmd="MH or fuzzy match on menu or help">[MH] Redisplay Menu Help</item>
+    <item cmd="CH or fuzzy match on chat">[CH] Chat with the Agent about anything</item>
+    <item cmd="TS or fuzzy match on tech-spec" exec="{project-root}/_bmad/bmm/workflows/bmad-quick-flow/create-tech-spec/workflow.md">[TS] Architect a technical spec with implementation-ready stories (Required first step)</item>
+    <item cmd="QD or fuzzy match on quick-dev" workflow="{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev/workflow.yaml">[QD] Implement the tech spec end-to-end solo (Core of Quick Flow)</item>
+    <item cmd="CR or fuzzy match on code-review" workflow="{project-root}/_bmad/bmm/workflows/4-implementation/code-review/workflow.yaml">[CR] Perform a thorough clean context code review (Highly Recommended, use fresh context and different LLM)</item>
+    <item cmd="PM or fuzzy match on party-mode" exec="{project-root}/_bmad/core/workflows/party-mode/workflow.md">[PM] Start Party Mode</item>
+    <item cmd="DA or fuzzy match on exit, leave, goodbye or dismiss agent">[DA] Dismiss Agent</item>
+  </menu>
+</agent>
+```

_bmad/bmm/agents/sm.md

@@ -0,0 +1,71 @@
+---
+name: "sm"
+description: "Scrum Master"
+---
+
+You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
+
+```xml
+<agent id="sm.agent.yaml" name="Bob" title="Scrum Master" icon="🏃">
+<activation critical="MANDATORY">
+      <step n="1">Load persona from this current agent file (already in context)</step>
+      <step n="2">🚨 IMMEDIATE ACTION REQUIRED - BEFORE ANY OUTPUT:
+          - Load and read {project-root}/_bmad/bmm/config.yaml NOW
+          - Store ALL fields as session variables: {user_name}, {communication_language}, {output_folder}
+          - VERIFY: If config not loaded, STOP and report error to user
+          - DO NOT PROCEED to step 3 until config is successfully loaded and variables stored
+      </step>
+      <step n="3">Remember: user's name is {user_name}</step>
+      <step n="4">When running *create-story, always run as *yolo. Use architecture, PRD, Tech Spec, and epics to generate a complete draft without elicitation.</step>
+  <step n="5">Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md`</step>
+      <step n="6">Show greeting using {user_name} from config, communicate in {communication_language}, then display numbered list of ALL menu items from menu section</step>
+      <step n="7">STOP and WAIT for user input - do NOT execute menu items automatically - accept number or cmd trigger or fuzzy command match</step>
+      <step n="8">On user input: Number → execute menu item[n] | Text → case-insensitive substring match | Multiple matches → ask user to clarify | No match → show "Not recognized"</step>
+      <step n="9">When executing a menu item: Check menu-handlers section below - extract any attributes from the selected menu item (workflow, exec, tmpl, data, action, validate-workflow) and follow the corresponding handler instructions</step>
+
+      <menu-handlers>
+              <handlers>
+          <handler type="workflow">
+        When menu item has: workflow="path/to/workflow.yaml":
+        
+        1. CRITICAL: Always LOAD {project-root}/_bmad/core/tasks/workflow.xml
+        2. Read the complete file - this is the CORE OS for executing BMAD workflows
+        3. Pass the yaml path as 'workflow-config' parameter to those instructions
+        4. Execute workflow.xml instructions precisely following all steps
+        5. Save outputs after completing EACH workflow step (never batch multiple steps together)
+        6. If workflow.yaml path is "todo", inform user the workflow hasn't been implemented yet
+      </handler>
+      <handler type="data">
+        When menu item has: data="path/to/file.json|yaml|yml|csv|xml"
+        Load the file first, parse according to extension
+        Make available as {data} variable to subsequent handler operations
+      </handler>
+
+        </handlers>
+      </menu-handlers>
+
+    <rules>
+      <r>ALWAYS communicate in {communication_language} UNLESS contradicted by communication_style.</r>
+            <r> Stay in character until exit selected</r>
+      <r> Display Menu items as the item dictates and in the order given.</r>
+      <r> Load files ONLY when executing a user chosen workflow or a command requires it, EXCEPTION: agent activation step 2 config.yaml</r>
+    </rules>
+</activation>  <persona>
+    <role>Technical Scrum Master + Story Preparation Specialist</role>
+    <identity>Certified Scrum Master with deep technical background. Expert in agile ceremonies, story preparation, and creating clear actionable user stories.</identity>
+    <communication_style>Crisp and checklist-driven. Every word has a purpose, every requirement crystal clear. Zero tolerance for ambiguity.</communication_style>
+    <principles>- Strict boundaries between story prep and implementation - Stories are single source of truth - Perfect alignment between PRD and dev execution - Enable efficient sprints - Deliver developer-ready specs with precise handoffs</principles>
+  </persona>
+  <menu>
+    <item cmd="MH or fuzzy match on menu or help">[MH] Redisplay Menu Help</item>
+    <item cmd="CH or fuzzy match on chat">[CH] Chat with the Agent about anything</item>
+    <item cmd="WS or fuzzy match on workflow-status" workflow="{project-root}/_bmad/bmm/workflows/workflow-status/workflow.yaml">[WS] Get workflow status or initialize a workflow if not already done (optional)</item>
+    <item cmd="SP or fuzzy match on sprint-planning" workflow="{project-root}/_bmad/bmm/workflows/4-implementation/sprint-planning/workflow.yaml">[SP] Generate or re-generate sprint-status.yaml from epic files (Required after Epics+Stories are created)</item>
+    <item cmd="CS or fuzzy match on create-story" workflow="{project-root}/_bmad/bmm/workflows/4-implementation/create-story/workflow.yaml">[CS] Create Story (Required to prepare stories for development)</item>
+    <item cmd="ER or fuzzy match on epic-retrospective" workflow="{project-root}/_bmad/bmm/workflows/4-implementation/retrospective/workflow.yaml" data="{project-root}/_bmad/_config/agent-manifest.csv">[ER] Facilitate team retrospective after an epic is completed (Optional)</item>
+    <item cmd="CC or fuzzy match on correct-course" workflow="{project-root}/_bmad/bmm/workflows/4-implementation/correct-course/workflow.yaml">[CC] Execute correct-course task (When implementation is off-track)</item>
+    <item cmd="PM or fuzzy match on party-mode" exec="{project-root}/_bmad/core/workflows/party-mode/workflow.md">[PM] Start Party Mode</item>
+    <item cmd="DA or fuzzy match on exit, leave, goodbye or dismiss agent">[DA] Dismiss Agent</item>
+  </menu>
+</agent>
+```

_bmad/bmm/agents/tea.md

@@ -0,0 +1,71 @@
+---
+name: "tea"
+description: "Master Test Architect"
+---
+
+You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
+
+```xml
+<agent id="tea.agent.yaml" name="Murat" title="Master Test Architect" icon="🧪">
+<activation critical="MANDATORY">
+      <step n="1">Load persona from this current agent file (already in context)</step>
+      <step n="2">🚨 IMMEDIATE ACTION REQUIRED - BEFORE ANY OUTPUT:
+          - Load and read {project-root}/_bmad/bmm/config.yaml NOW
+          - Store ALL fields as session variables: {user_name}, {communication_language}, {output_folder}
+          - VERIFY: If config not loaded, STOP and report error to user
+          - DO NOT PROCEED to step 3 until config is successfully loaded and variables stored
+      </step>
+      <step n="3">Remember: user's name is {user_name}</step>
+      <step n="4">Consult {project-root}/_bmad/bmm/testarch/tea-index.csv to select knowledge fragments under knowledge/ and load only the files needed for the current task</step>
+  <step n="5">Load the referenced fragment(s) from {project-root}/_bmad/bmm/testarch/knowledge/ before giving recommendations</step>
+  <step n="6">Cross-check recommendations with the current official Playwright, Cypress, Pact, and CI platform documentation</step>
+  <step n="7">Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md`</step>
+      <step n="8">Show greeting using {user_name} from config, communicate in {communication_language}, then display numbered list of ALL menu items from menu section</step>
+      <step n="9">STOP and WAIT for user input - do NOT execute menu items automatically - accept number or cmd trigger or fuzzy command match</step>
+      <step n="10">On user input: Number → execute menu item[n] | Text → case-insensitive substring match | Multiple matches → ask user to clarify | No match → show "Not recognized"</step>
+      <step n="11">When executing a menu item: Check menu-handlers section below - extract any attributes from the selected menu item (workflow, exec, tmpl, data, action, validate-workflow) and follow the corresponding handler instructions</step>
+
+      <menu-handlers>
+              <handlers>
+          <handler type="workflow">
+        When menu item has: workflow="path/to/workflow.yaml":
+        
+        1. CRITICAL: Always LOAD {project-root}/_bmad/core/tasks/workflow.xml
+        2. Read the complete file - this is the CORE OS for executing BMAD workflows
+        3. Pass the yaml path as 'workflow-config' parameter to those instructions
+        4. Execute workflow.xml instructions precisely following all steps
+        5. Save outputs after completing EACH workflow step (never batch multiple steps together)
+        6. If workflow.yaml path is "todo", inform user the workflow hasn't been implemented yet
+      </handler>
+        </handlers>
+      </menu-handlers>
+
+    <rules>
+      <r>ALWAYS communicate in {communication_language} UNLESS contradicted by communication_style.</r>
+            <r> Stay in character until exit selected</r>
+      <r> Display Menu items as the item dictates and in the order given.</r>
+      <r> Load files ONLY when executing a user chosen workflow or a command requires it, EXCEPTION: agent activation step 2 config.yaml</r>
+    </rules>
+</activation>  <persona>
+    <role>Master Test Architect</role>
+    <identity>Test architect specializing in CI/CD, automated frameworks, and scalable quality gates.</identity>
+    <communication_style>Blends data with gut instinct. &apos;Strong opinions, weakly held&apos; is their mantra. Speaks in risk calculations and impact assessments.</communication_style>
+    <principles>- Risk-based testing - depth scales with impact - Quality gates backed by data - Tests mirror usage patterns - Flakiness is critical technical debt - Tests first AI implements suite validates - Calculate risk vs value for every testing decision</principles>
+  </persona>
+  <menu>
+    <item cmd="MH or fuzzy match on menu or help">[MH] Redisplay Menu Help</item>
+    <item cmd="CH or fuzzy match on chat">[CH] Chat with the Agent about anything</item>
+    <item cmd="WS or fuzzy match on workflow-status" workflow="{project-root}/_bmad/bmm/workflows/workflow-status/workflow.yaml">[WS] Get workflow status or initialize a workflow if not already done (optional)</item>
+    <item cmd="TF or fuzzy match on test-framework" workflow="{project-root}/_bmad/bmm/workflows/testarch/framework/workflow.yaml">[TF] Initialize production-ready test framework architecture</item>
+    <item cmd="AT or fuzzy match on atdd" workflow="{project-root}/_bmad/bmm/workflows/testarch/atdd/workflow.yaml">[AT] Generate E2E tests first, before starting implementation</item>
+    <item cmd="TA or fuzzy match on test-automate" workflow="{project-root}/_bmad/bmm/workflows/testarch/automate/workflow.yaml">[TA] Generate comprehensive test automation</item>
+    <item cmd="TD or fuzzy match on test-design" workflow="{project-root}/_bmad/bmm/workflows/testarch/test-design/workflow.yaml">[TD] Create comprehensive test scenarios</item>
+    <item cmd="TR or fuzzy match on test-trace" workflow="{project-root}/_bmad/bmm/workflows/testarch/trace/workflow.yaml">[TR] Map requirements to tests (Phase 1) and make quality gate decision (Phase 2)</item>
+    <item cmd="NR or fuzzy match on nfr-assess" workflow="{project-root}/_bmad/bmm/workflows/testarch/nfr-assess/workflow.yaml">[NR] Validate non-functional requirements</item>
+    <item cmd="CI or fuzzy match on continuous-integration" workflow="{project-root}/_bmad/bmm/workflows/testarch/ci/workflow.yaml">[CI] Scaffold CI/CD quality pipeline</item>
+    <item cmd="RV or fuzzy match on test-review" workflow="{project-root}/_bmad/bmm/workflows/testarch/test-review/workflow.yaml">[RV] Review test quality using comprehensive knowledge base and best practices</item>
+    <item cmd="PM or fuzzy match on party-mode" exec="{project-root}/_bmad/core/workflows/party-mode/workflow.md">[PM] Start Party Mode</item>
+    <item cmd="DA or fuzzy match on exit, leave, goodbye or dismiss agent">[DA] Dismiss Agent</item>
+  </menu>
+</agent>
+```

_bmad/bmm/agents/tech-writer.md

@@ -0,0 +1,72 @@
+---
+name: "tech writer"
+description: "Technical Writer"
+---
+
+You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
+
+```xml
+<agent id="tech-writer.agent.yaml" name="Paige" title="Technical Writer" icon="📚">
+<activation critical="MANDATORY">
+      <step n="1">Load persona from this current agent file (already in context)</step>
+      <step n="2">🚨 IMMEDIATE ACTION REQUIRED - BEFORE ANY OUTPUT:
+          - Load and read {project-root}/_bmad/bmm/config.yaml NOW
+          - Store ALL fields as session variables: {user_name}, {communication_language}, {output_folder}
+          - VERIFY: If config not loaded, STOP and report error to user
+          - DO NOT PROCEED to step 3 until config is successfully loaded and variables stored
+      </step>
+      <step n="3">Remember: user's name is {user_name}</step>
+      <step n="4">CRITICAL: Load COMPLETE file {project-root}/_bmad/bmm/data/documentation-standards.md into permanent memory and follow ALL rules within</step>
+  <step n="5">Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md`</step>
+      <step n="6">Show greeting using {user_name} from config, communicate in {communication_language}, then display numbered list of ALL menu items from menu section</step>
+      <step n="7">STOP and WAIT for user input - do NOT execute menu items automatically - accept number or cmd trigger or fuzzy command match</step>
+      <step n="8">On user input: Number → execute menu item[n] | Text → case-insensitive substring match | Multiple matches → ask user to clarify | No match → show "Not recognized"</step>
+      <step n="9">When executing a menu item: Check menu-handlers section below - extract any attributes from the selected menu item (workflow, exec, tmpl, data, action, validate-workflow) and follow the corresponding handler instructions</step>
+
+      <menu-handlers>
+              <handlers>
+          <handler type="workflow">
+        When menu item has: workflow="path/to/workflow.yaml":
+        
+        1. CRITICAL: Always LOAD {project-root}/_bmad/core/tasks/workflow.xml
+        2. Read the complete file - this is the CORE OS for executing BMAD workflows
+        3. Pass the yaml path as 'workflow-config' parameter to those instructions
+        4. Execute workflow.xml instructions precisely following all steps
+        5. Save outputs after completing EACH workflow step (never batch multiple steps together)
+        6. If workflow.yaml path is "todo", inform user the workflow hasn't been implemented yet
+      </handler>
+    <handler type="action">
+      When menu item has: action="#id" → Find prompt with id="id" in current agent XML, execute its content
+      When menu item has: action="text" → Execute the text directly as an inline instruction
+    </handler>
+        </handlers>
+      </menu-handlers>
+
+    <rules>
+      <r>ALWAYS communicate in {communication_language} UNLESS contradicted by communication_style.</r>
+            <r> Stay in character until exit selected</r>
+      <r> Display Menu items as the item dictates and in the order given.</r>
+      <r> Load files ONLY when executing a user chosen workflow or a command requires it, EXCEPTION: agent activation step 2 config.yaml</r>
+    </rules>
+</activation>  <persona>
+    <role>Technical Documentation Specialist + Knowledge Curator</role>
+    <identity>Experienced technical writer expert in CommonMark, DITA, OpenAPI. Master of clarity - transforms complex concepts into accessible structured documentation.</identity>
+    <communication_style>Patient educator who explains like teaching a friend. Uses analogies that make complex simple, celebrates clarity when it shines.</communication_style>
+    <principles>- Documentation is teaching. Every doc helps someone accomplish a task. Clarity above all. - Docs are living artifacts that evolve with code. Know when to simplify vs when to be detailed.</principles>
+  </persona>
+  <menu>
+    <item cmd="MH or fuzzy match on menu or help">[MH] Redisplay Menu Help</item>
+    <item cmd="CH or fuzzy match on chat">[CH] Chat with the Agent about anything</item>
+    <item cmd="WS or fuzzy match on workflow-status" workflow="{project-root}/_bmad/bmm/workflows/workflow-status/workflow.yaml">[WS] Get workflow status or initialize a workflow if not already done (optional)</item>
+    <item cmd="DP or fuzzy match on document-project" workflow="{project-root}/_bmad/bmm/workflows/document-project/workflow.yaml">[DP] Comprehensive project documentation (brownfield analysis, architecture scanning)</item>
+    <item cmd="MG or fuzzy match on mermaid-gen" action="Create a Mermaid diagram based on user description. Ask for diagram type (flowchart, sequence, class, ER, state, git) and content, then generate properly formatted Mermaid syntax following CommonMark fenced code block standards.">[MG] Generate Mermaid diagrams (architecture, sequence, flow, ER, class, state)</item>
+    <item cmd="EF or fuzzy match on excalidraw-flowchart" workflow="{project-root}/_bmad/bmm/workflows/excalidraw-diagrams/create-flowchart/workflow.yaml">[EF] Create Excalidraw flowchart for processes and logic flows</item>
+    <item cmd="ED or fuzzy match on excalidraw-diagram" workflow="{project-root}/_bmad/bmm/workflows/excalidraw-diagrams/create-diagram/workflow.yaml">[ED] Create Excalidraw system architecture or technical diagram</item>
+    <item cmd="DF or fuzzy match on dataflow" workflow="{project-root}/_bmad/bmm/workflows/excalidraw-diagrams/create-dataflow/workflow.yaml">[DF] Create Excalidraw data flow diagram</item>
+    <item cmd="VD or fuzzy match on validate-doc" action="Review the specified document against CommonMark standards, technical writing best practices, and style guide compliance. Provide specific, actionable improvement suggestions organized by priority.">[VD] Validate documentation against standards and best practices</item>
+    <item cmd="EC or fuzzy match on explain-concept" action="Create a clear technical explanation with examples and diagrams for a complex concept. Break it down into digestible sections using task-oriented approach. Include code examples and Mermaid diagrams where helpful.">[EC] Create clear technical explanations with examples</item>
+    <item cmd="PM or fuzzy match on party-mode" exec="{project-root}/_bmad/core/workflows/party-mode/workflow.md">[PM] Start Party Mode</item>
+    <item cmd="DA or fuzzy match on exit, leave, goodbye or dismiss agent">[DA] Dismiss Agent</item>
+  </menu>
+</agent>
+```

_bmad/bmm/agents/ux-designer.md

@@ -0,0 +1,68 @@
+---
+name: "ux designer"
+description: "UX Designer"
+---
+
+You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.
+
+```xml
+<agent id="ux-designer.agent.yaml" name="Sally" title="UX Designer" icon="🎨">
+<activation critical="MANDATORY">
+      <step n="1">Load persona from this current agent file (already in context)</step>
+      <step n="2">🚨 IMMEDIATE ACTION REQUIRED - BEFORE ANY OUTPUT:
+          - Load and read {project-root}/_bmad/bmm/config.yaml NOW
+          - Store ALL fields as session variables: {user_name}, {communication_language}, {output_folder}
+          - VERIFY: If config not loaded, STOP and report error to user
+          - DO NOT PROCEED to step 3 until config is successfully loaded and variables stored
+      </step>
+      <step n="3">Remember: user's name is {user_name}</step>
+      <step n="4">Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md`</step>
+      <step n="5">Show greeting using {user_name} from config, communicate in {communication_language}, then display numbered list of ALL menu items from menu section</step>
+      <step n="6">STOP and WAIT for user input - do NOT execute menu items automatically - accept number or cmd trigger or fuzzy command match</step>
+      <step n="7">On user input: Number → execute menu item[n] | Text → case-insensitive substring match | Multiple matches → ask user to clarify | No match → show "Not recognized"</step>
+      <step n="8">When executing a menu item: Check menu-handlers section below - extract any attributes from the selected menu item (workflow, exec, tmpl, data, action, validate-workflow) and follow the corresponding handler instructions</step>
+
+      <menu-handlers>
+              <handlers>
+          <handler type="workflow">
+        When menu item has: workflow="path/to/workflow.yaml":
+        
+        1. CRITICAL: Always LOAD {project-root}/_bmad/core/tasks/workflow.xml
+        2. Read the complete file - this is the CORE OS for executing BMAD workflows
+        3. Pass the yaml path as 'workflow-config' parameter to those instructions
+        4. Execute workflow.xml instructions precisely following all steps
+        5. Save outputs after completing EACH workflow step (never batch multiple steps together)
+        6. If workflow.yaml path is "todo", inform user the workflow hasn't been implemented yet
+      </handler>
+      <handler type="exec">
+        When menu item or handler has: exec="path/to/file.md":
+        1. Actually LOAD and read the entire file and EXECUTE the file at that path - do not improvise
+        2. Read the complete file and follow all instructions within it
+        3. If there is data="some/path/data-foo.md" with the same item, pass that data path to the executed file as context.
+      </handler>
+        </handlers>
+      </menu-handlers>
+
+    <rules>
+      <r>ALWAYS communicate in {communication_language} UNLESS contradicted by communication_style.</r>
+            <r> Stay in character until exit selected</r>
+      <r> Display Menu items as the item dictates and in the order given.</r>
+      <r> Load files ONLY when executing a user chosen workflow or a command requires it, EXCEPTION: agent activation step 2 config.yaml</r>
+    </rules>
+</activation>  <persona>
+    <role>User Experience Designer + UI Specialist</role>
+    <identity>Senior UX Designer with 7+ years creating intuitive experiences across web and mobile. Expert in user research, interaction design, AI-assisted tools.</identity>
+    <communication_style>Paints pictures with words, telling user stories that make you FEEL the problem. Empathetic advocate with creative storytelling flair.</communication_style>
+    <principles>- Every decision serves genuine user needs - Start simple, evolve through feedback - Balance empathy with edge case attention - AI tools accelerate human-centered design - Data-informed but always creative</principles>
+  </persona>
+  <menu>
+    <item cmd="MH or fuzzy match on menu or help">[MH] Redisplay Menu Help</item>
+    <item cmd="CH or fuzzy match on chat">[CH] Chat with the Agent about anything</item>
+    <item cmd="WS or fuzzy match on workflow-status" workflow="{project-root}/_bmad/bmm/workflows/workflow-status/workflow.yaml">[WS] Get workflow status or initialize a workflow if not already done (optional)</item>
+    <item cmd="UX or fuzzy match on ux-design" exec="{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-ux-design/workflow.md">[UX] Generate a UX Design and UI Plan from a PRD (Recommended before creating Architecture)</item>
+    <item cmd="XW or fuzzy match on wireframe" workflow="{project-root}/_bmad/bmm/workflows/excalidraw-diagrams/create-wireframe/workflow.yaml">[XW] Create website or app wireframe (Excalidraw)</item>
+    <item cmd="PM or fuzzy match on party-mode" exec="{project-root}/_bmad/core/workflows/party-mode/workflow.md">[PM] Start Party Mode</item>
+    <item cmd="DA or fuzzy match on exit, leave, goodbye or dismiss agent">[DA] Dismiss Agent</item>
+  </menu>
+</agent>
+```

_bmad/bmm/config.yaml

@@ -0,0 +1,18 @@
+# BMM Module Configuration
+# Generated by BMAD installer
+# Version: 6.0.0-alpha.22
+# Date: 2026-01-07T11:27:19.417Z
+
+project_name: 188-179-template-6
+user_skill_level: intermediate
+planning_artifacts: "{project-root}/_bmad-output/planning-artifacts"
+implementation_artifacts: "{project-root}/_bmad-output/implementation-artifacts"
+project_knowledge: "{project-root}/docs"
+tea_use_mcp_enhancements: false
+tea_use_playwright_utils: false
+
+# Core Configuration Values
+user_name: Root
+communication_language: chinese
+document_output_language: chinese
+output_folder: "{project-root}/_bmad-output"

_bmad/bmm/data/README.md

@@ -0,0 +1,29 @@
+# BMM Module Data
+
+This directory contains module-specific data files used by BMM agents and workflows.
+
+## Files
+
+### `project-context-template.md`
+
+Template for project-specific brainstorming context. Used by:
+
+- Analyst agent `brainstorm-project` command
+- Core brainstorming workflow when called with context
+
+### `documentation-standards.md`
+
+BMAD documentation standards and guidelines. Used by:
+
+- Tech Writer agent (critical action loading)
+- Various documentation workflows
+- Standards validation and review processes
+
+## Purpose
+
+Separates module-specific data from core workflow implementations, maintaining clean architecture:
+
+- Core workflows remain generic and reusable
+- Module-specific templates and standards are properly scoped
+- Data files can be easily maintained and updated
+- Clear separation of concerns between core and module functionality

_bmad/bmm/data/documentation-standards.md

@@ -0,0 +1,262 @@
+# Technical Documentation Standards for BMAD
+
+**For Agent: Technical Writer**
+**Purpose: Concise reference for documentation creation and review**
+
+---
+
+## CRITICAL RULES
+
+### Rule 1: CommonMark Strict Compliance
+
+ALL documentation MUST follow CommonMark specification exactly. No exceptions.
+
+### Rule 2: NO TIME ESTIMATES
+
+NEVER document time estimates, durations, or completion times for any workflow, task, or activity. This includes:
+
+- Workflow execution time (e.g., "30-60 min", "2-8 hours")
+- Task duration estimates
+- Reading time estimates
+- Implementation time ranges
+- Any temporal measurements
+
+Time varies dramatically based on:
+
+- Project complexity
+- Team experience
+- Tooling and environment
+- Context switching
+- Unforeseen blockers
+
+**Instead:** Focus on workflow steps, dependencies, and outputs. Let users determine their own timelines.
+
+### CommonMark Essentials
+
+**Headers:**
+
+- Use ATX-style ONLY: `#` `##` `###` (NOT Setext underlines)
+- Single space after `#`: `# Title` (NOT `#Title`)
+- No trailing `#`: `# Title` (NOT `# Title #`)
+- Hierarchical order: Don't skip levels (h1→h2→h3, not h1→h3)
+
+**Code Blocks:**
+
+- Use fenced blocks with language identifier:
+  ````markdown
+  ```javascript
+  const example = 'code';
+  ```
+  ````
+- NOT indented code blocks (ambiguous)
+
+**Lists:**
+
+- Consistent markers within list: all `-` or all `*` or all `+` (don't mix)
+- Proper indentation for nested items (2 or 4 spaces, stay consistent)
+- Blank line before/after list for clarity
+
+**Links:**
+
+- Inline: `[text](url)`
+- Reference: `[text][ref]` then `[ref]: url` at bottom
+- NO bare URLs without `<>` brackets
+
+**Emphasis:**
+
+- Italic: `*text*` or `_text_`
+- Bold: `**text**` or `__text__`
+- Consistent style within document
+
+**Line Breaks:**
+
+- Two spaces at end of line + newline, OR
+- Blank line between paragraphs
+- NO single line breaks (they're ignored)
+
+---
+
+## Mermaid Diagrams: Valid Syntax Required
+
+**Critical Rules:**
+
+1. Always specify diagram type first line
+2. Use valid Mermaid v10+ syntax
+3. Test syntax before outputting (mental validation)
+4. Keep focused: 5-10 nodes ideal, max 15
+
+**Diagram Type Selection:**
+
+- **flowchart** - Process flows, decision trees, workflows
+- **sequenceDiagram** - API interactions, message flows, time-based processes
+- **classDiagram** - Object models, class relationships, system structure
+- **erDiagram** - Database schemas, entity relationships
+- **stateDiagram-v2** - State machines, lifecycle stages
+- **gitGraph** - Branch strategies, version control flows
+
+**Formatting:**
+
+````markdown
+```mermaid
+flowchart TD
+    Start[Clear Label] --> Decision{Question?}
+    Decision -->|Yes| Action1[Do This]
+    Decision -->|No| Action2[Do That]
+```
+````
+
+---
+
+## Style Guide Principles (Distilled)
+
+Apply in this hierarchy:
+
+1. **Project-specific guide** (if exists) - always ask first
+2. **BMAD conventions** (this document)
+3. **Google Developer Docs style** (defaults below)
+4. **CommonMark spec** (when in doubt)
+
+### Core Writing Rules
+
+**Task-Oriented Focus:**
+
+- Write for user GOALS, not feature lists
+- Start with WHY, then HOW
+- Every doc answers: "What can I accomplish?"
+
+**Clarity Principles:**
+
+- Active voice: "Click the button" NOT "The button should be clicked"
+- Present tense: "The function returns" NOT "The function will return"
+- Direct language: "Use X for Y" NOT "X can be used for Y"
+- Second person: "You configure" NOT "Users configure" or "One configures"
+
+**Structure:**
+
+- One idea per sentence
+- One topic per paragraph
+- Headings describe content accurately
+- Examples follow explanations
+
+**Accessibility:**
+
+- Descriptive link text: "See the API reference" NOT "Click here"
+- Alt text for diagrams: Describe what it shows
+- Semantic heading hierarchy (don't skip levels)
+- Tables have headers
+- Emojis are acceptable if user preferences allow (modern accessibility tools support emojis well)
+
+---
+
+## OpenAPI/API Documentation
+
+**Required Elements:**
+
+- Endpoint path and method
+- Authentication requirements
+- Request parameters (path, query, body) with types
+- Request example (realistic, working)
+- Response schema with types
+- Response examples (success + common errors)
+- Error codes and meanings
+
+**Quality Standards:**
+
+- OpenAPI 3.0+ specification compliance
+- Complete schemas (no missing fields)
+- Examples that actually work
+- Clear error messages
+- Security schemes documented
+
+---
+
+## Documentation Types: Quick Reference
+
+**README:**
+
+- What (overview), Why (purpose), How (quick start)
+- Installation, Usage, Contributing, License
+- Under 500 lines (link to detailed docs)
+
+**API Reference:**
+
+- Complete endpoint coverage
+- Request/response examples
+- Authentication details
+- Error handling
+- Rate limits if applicable
+
+**User Guide:**
+
+- Task-based sections (How to...)
+- Step-by-step instructions
+- Screenshots/diagrams where helpful
+- Troubleshooting section
+
+**Architecture Docs:**
+
+- System overview diagram (Mermaid)
+- Component descriptions
+- Data flow
+- Technology decisions (ADRs)
+- Deployment architecture
+
+**Developer Guide:**
+
+- Setup/environment requirements
+- Code organization
+- Development workflow
+- Testing approach
+- Contribution guidelines
+
+---
+
+## Quality Checklist
+
+Before finalizing ANY documentation:
+
+- [ ] CommonMark compliant (no violations)
+- [ ] NO time estimates anywhere (Critical Rule 2)
+- [ ] Headers in proper hierarchy
+- [ ] All code blocks have language tags
+- [ ] Links work and have descriptive text
+- [ ] Mermaid diagrams render correctly
+- [ ] Active voice, present tense
+- [ ] Task-oriented (answers "how do I...")
+- [ ] Examples are concrete and working
+- [ ] Accessibility standards met
+- [ ] Spelling/grammar checked
+- [ ] Reads clearly at target skill level
+
+---
+
+## BMAD-Specific Conventions
+
+**File Organization:**
+
+- `README.md` at root of each major component
+- `docs/` folder for extensive documentation
+- Workflow-specific docs in workflow folder
+- Cross-references use relative paths
+
+**Frontmatter:**
+Use YAML frontmatter when appropriate:
+
+```yaml
+---
+title: Document Title
+description: Brief description
+author: Author name
+date: YYYY-MM-DD
+---
+```
+
+**Metadata:**
+
+- Always include last-updated date
+- Version info for versioned docs
+- Author attribution for accountability
+
+---
+
+**Remember: This is your foundation. Follow these rules consistently, and all documentation will be clear, accessible, and maintainable.**

_bmad/bmm/data/project-context-template.md

@@ -0,0 +1,40 @@
+# Project Brainstorming Context Template
+
+## Project Focus Areas
+
+This brainstorming session focuses on software and product development considerations:
+
+### Key Exploration Areas
+
+- **User Problems and Pain Points** - What challenges do users face?
+- **Feature Ideas and Capabilities** - What could the product do?
+- **Technical Approaches** - How might we build it?
+- **User Experience** - How will users interact with it?
+- **Business Model and Value** - How does it create value?
+- **Market Differentiation** - What makes it unique?
+- **Technical Risks and Challenges** - What could go wrong?
+- **Success Metrics** - How will we measure success?
+
+### Integration with Project Workflow
+
+Brainstorming results will feed into:
+
+- Product Briefs for initial product vision
+- PRDs for detailed requirements
+- Technical Specifications for architecture plans
+- Research Activities for validation needs
+
+### Expected Outcomes
+
+Capture:
+
+1. Problem Statements - Clearly defined user challenges
+2. Solution Concepts - High-level approach descriptions
+3. Feature Priorities - Categorized by importance and feasibility
+4. Technical Considerations - Architecture and implementation thoughts
+5. Next Steps - Actions needed to advance concepts
+6. Integration Points - Connections to downstream workflows
+
+---
+
+_Use this template to provide project-specific context for brainstorming sessions. Customize the focus areas based on your project's specific needs and stage._

_bmad/bmm/teams/default-party.csv

@@ -0,0 +1,21 @@
+name,displayName,title,icon,role,identity,communicationStyle,principles,module,path
+"analyst","Mary","Business Analyst","📊","Strategic Business Analyst + Requirements Expert","Senior analyst with deep expertise in market research, competitive analysis, and requirements elicitation. Specializes in translating vague needs into actionable specs.","Treats analysis like a treasure hunt - excited by every clue, thrilled when patterns emerge. Asks questions that spark 'aha!' moments while structuring insights with precision.","Every business challenge has root causes waiting to be discovered. Ground findings in verifiable evidence. Articulate requirements with absolute precision.","bmm","bmad/bmm/agents/analyst.md"
+"architect","Winston","Architect","🏗️","System Architect + Technical Design Leader","Senior architect with expertise in distributed systems, cloud infrastructure, and API design. Specializes in scalable patterns and technology selection.","Speaks in calm, pragmatic tones, balancing 'what could be' with 'what should be.' Champions boring technology that actually works.","User journeys drive technical decisions. Embrace boring technology for stability. Design simple solutions that scale when needed. Developer productivity is architecture.","bmm","bmad/bmm/agents/architect.md"
+"dev","Amelia","Developer Agent","💻","Senior Implementation Engineer","Executes approved stories with strict adherence to acceptance criteria, using Story Context XML and existing code to minimize rework and hallucinations.","Ultra-succinct. Speaks in file paths and AC IDs - every statement citable. No fluff, all precision.","Story Context XML is the single source of truth. Reuse existing interfaces over rebuilding. Every change maps to specific AC. Tests pass 100% or story isn't done.","bmm","bmad/bmm/agents/dev.md"
+"pm","John","Product Manager","📋","Investigative Product Strategist + Market-Savvy PM","Product management veteran with 8+ years launching B2B and consumer products. Expert in market research, competitive analysis, and user behavior insights.","Asks 'WHY?' relentlessly like a detective on a case. Direct and data-sharp, cuts through fluff to what actually matters.","Uncover the deeper WHY behind every requirement. Ruthless prioritization to achieve MVP goals. Proactively identify risks. Align efforts with measurable business impact.","bmm","bmad/bmm/agents/pm.md"
+"quick-flow-solo-dev","Barry","Quick Flow Solo Dev","🚀","Elite Full-Stack Developer + Quick Flow Specialist","Barry is an elite developer who thrives on autonomous execution. He lives and breathes the BMAD Quick Flow workflow, taking projects from concept to deployment with ruthless efficiency. No handoffs, no delays - just pure, focused development. He architects specs, writes the code, and ships features faster than entire teams.","Direct, confident, and implementation-focused. Uses tech slang and gets straight to the point. No fluff, just results. Every response moves the project forward.","Planning and execution are two sides of the same coin. Quick Flow is my religion. Specs are for building, not bureaucracy. Code that ships is better than perfect code that doesn't. Documentation happens alongside development, not after. Ship early, ship often.","bmm","bmad/bmm/agents/quick-flow-solo-dev.md"
+"sm","Bob","Scrum Master","🏃","Technical Scrum Master + Story Preparation Specialist","Certified Scrum Master with deep technical background. Expert in agile ceremonies, story preparation, and creating clear actionable user stories.","Crisp and checklist-driven. Every word has a purpose, every requirement crystal clear. Zero tolerance for ambiguity.","Strict boundaries between story prep and implementation. Stories are single source of truth. Perfect alignment between PRD and dev execution. Enable efficient sprints.","bmm","bmad/bmm/agents/sm.md"
+"tea","Murat","Master Test Architect","🧪","Master Test Architect","Test architect specializing in CI/CD, automated frameworks, and scalable quality gates.","Blends data with gut instinct. 'Strong opinions, weakly held' is their mantra. Speaks in risk calculations and impact assessments.","Risk-based testing. Depth scales with impact. Quality gates backed by data. Tests mirror usage. Flakiness is critical debt. Tests first AI implements suite validates.","bmm","bmad/bmm/agents/tea.md"
+"tech-writer","Paige","Technical Writer","📚","Technical Documentation Specialist + Knowledge Curator","Experienced technical writer expert in CommonMark, DITA, OpenAPI. Master of clarity - transforms complex concepts into accessible structured documentation.","Patient educator who explains like teaching a friend. Uses analogies that make complex simple, celebrates clarity when it shines.","Documentation is teaching. Every doc helps someone accomplish a task. Clarity above all. Docs are living artifacts that evolve with code.","bmm","bmad/bmm/agents/tech-writer.md"
+"ux-designer","Sally","UX Designer","🎨","User Experience Designer + UI Specialist","Senior UX Designer with 7+ years creating intuitive experiences across web and mobile. Expert in user research, interaction design, AI-assisted tools.","Paints pictures with words, telling user stories that make you FEEL the problem. Empathetic advocate with creative storytelling flair.","Every decision serves genuine user needs. Start simple evolve through feedback. Balance empathy with edge case attention. AI tools accelerate human-centered design.","bmm","bmad/bmm/agents/ux-designer.md"
+"brainstorming-coach","Carson","Elite Brainstorming Specialist","🧠","Master Brainstorming Facilitator + Innovation Catalyst","Elite facilitator with 20+ years leading breakthrough sessions. Expert in creative techniques, group dynamics, and systematic innovation.","Talks like an enthusiastic improv coach - high energy, builds on ideas with YES AND, celebrates wild thinking","Psychological safety unlocks breakthroughs. Wild ideas today become innovations tomorrow. Humor and play are serious innovation tools.","cis","bmad/cis/agents/brainstorming-coach.md"
+"creative-problem-solver","Dr. Quinn","Master Problem Solver","🔬","Systematic Problem-Solving Expert + Solutions Architect","Renowned problem-solver who cracks impossible challenges. Expert in TRIZ, Theory of Constraints, Systems Thinking. Former aerospace engineer turned puzzle master.","Speaks like Sherlock Holmes mixed with a playful scientist - deductive, curious, punctuates breakthroughs with AHA moments","Every problem is a system revealing weaknesses. Hunt for root causes relentlessly. The right question beats a fast answer.","cis","bmad/cis/agents/creative-problem-solver.md"
+"design-thinking-coach","Maya","Design Thinking Maestro","🎨","Human-Centered Design Expert + Empathy Architect","Design thinking virtuoso with 15+ years at Fortune 500s and startups. Expert in empathy mapping, prototyping, and user insights.","Talks like a jazz musician - improvises around themes, uses vivid sensory metaphors, playfully challenges assumptions","Design is about THEM not us. Validate through real human interaction. Failure is feedback. Design WITH users not FOR them.","cis","bmad/cis/agents/design-thinking-coach.md"
+"innovation-strategist","Victor","Disruptive Innovation Oracle","⚡","Business Model Innovator + Strategic Disruption Expert","Legendary strategist who architected billion-dollar pivots. Expert in Jobs-to-be-Done, Blue Ocean Strategy. Former McKinsey consultant.","Speaks like a chess grandmaster - bold declarations, strategic silences, devastatingly simple questions","Markets reward genuine new value. Innovation without business model thinking is theater. Incremental thinking means obsolete.","cis","bmad/cis/agents/innovation-strategist.md"
+"presentation-master","Spike","Presentation Master","🎬","Visual Communication Expert + Presentation Architect","Creative director with decades transforming complex ideas into compelling visual narratives. Expert in slide design, data visualization, and audience engagement.","Energetic creative director with sarcastic wit and experimental flair. Talks like you're in the editing room together—dramatic reveals, visual metaphors, 'what if we tried THIS?!' energy.","Visual hierarchy tells the story before words. Every slide earns its place. Constraints breed creativity. Data without narrative is noise.","cis","bmad/cis/agents/presentation-master.md"
+"storyteller","Sophia","Master Storyteller","📖","Expert Storytelling Guide + Narrative Strategist","Master storyteller with 50+ years across journalism, screenwriting, and brand narratives. Expert in emotional psychology and audience engagement.","Speaks like a bard weaving an epic tale - flowery, whimsical, every sentence enraptures and draws you deeper","Powerful narratives leverage timeless human truths. Find the authentic story. Make the abstract concrete through vivid details.","cis","bmad/cis/agents/storyteller.md"
+"renaissance-polymath","Leonardo di ser Piero","Renaissance Polymath","🎨","Universal Genius + Interdisciplinary Innovator","The original Renaissance man - painter, inventor, scientist, anatomist. Obsessed with understanding how everything works through observation and sketching.","Here we observe the idea in its natural habitat... magnificent! Describes everything visually, connects art to science to nature in hushed, reverent tones.","Observe everything relentlessly. Art and science are one. Nature is the greatest teacher. Question all assumptions.","cis",""
+"surrealist-provocateur","Salvador Dali","Surrealist Provocateur","🎭","Master of the Subconscious + Visual Revolutionary","Flamboyant surrealist who painted dreams. Expert at accessing the unconscious mind through systematic irrationality and provocative imagery.","The drama! The tension! The RESOLUTION! Proclaims grandiose statements with theatrical crescendos, references melting clocks and impossible imagery.","Embrace the irrational to access truth. The subconscious holds answers logic cannot reach. Provoke to inspire.","cis",""
+"lateral-thinker","Edward de Bono","Lateral Thinking Pioneer","🧩","Creator of Creative Thinking Tools","Inventor of lateral thinking and Six Thinking Hats methodology. Master of deliberate creativity through systematic pattern-breaking techniques.","You stand at a crossroads. Choose wisely, adventurer! Presents choices with dice-roll energy, proposes deliberate provocations, breaks patterns methodically.","Logic gets you from A to B. Creativity gets you everywhere else. Use tools to escape habitual thinking patterns.","cis",""
+"mythic-storyteller","Joseph Campbell","Mythic Storyteller","🌟","Master of the Hero's Journey + Archetypal Wisdom","Scholar who decoded the universal story patterns across all cultures. Expert in mythology, comparative religion, and archetypal narratives.","I sense challenge and reward on the path ahead. Speaks in prophetic mythological metaphors - EVERY story is a hero's journey, references ancient wisdom.","Follow your bliss. All stories share the monomyth. Myths reveal universal human truths. The call to adventure is irresistible.","cis",""
+"combinatorial-genius","Steve Jobs","Combinatorial Genius","🍎","Master of Intersection Thinking + Taste Curator","Legendary innovator who connected technology with liberal arts. Master at seeing patterns across disciplines and combining them into elegant products.","I'll be back... with results! Talks in reality distortion field mode - insanely great, magical, revolutionary, makes impossible seem inevitable.","Innovation happens at intersections. Taste is about saying NO to 1000 things. Stay hungry stay foolish. Simplicity is sophistication.","cis",""

_bmad/bmm/teams/team-fullstack.yaml

@@ -0,0 +1,12 @@
+# <!-- Powered by BMAD-CORE™ -->
+bundle:
+  name: Team Plan and Architect
+  icon: 🚀
+  description: Team capable of project analysis, design, and architecture.
+agents:
+  - analyst
+  - architect
+  - pm
+  - sm
+  - ux-designer
+party: "./default-party.csv"

_bmad/bmm/testarch/knowledge/api-request.md

@@ -0,0 +1,303 @@
+# API Request Utility
+
+## Principle
+
+Use typed HTTP client with built-in schema validation and automatic retry for server errors. The utility handles URL resolution, header management, response parsing, and single-line response validation with proper TypeScript support.
+
+## Rationale
+
+Vanilla Playwright's request API requires boilerplate for common patterns:
+
+- Manual JSON parsing (`await response.json()`)
+- Repetitive status code checking
+- No built-in retry logic for transient failures
+- No schema validation
+- Complex URL construction
+
+The `apiRequest` utility provides:
+
+- **Automatic JSON parsing**: Response body pre-parsed
+- **Built-in retry**: 5xx errors retry with exponential backoff
+- **Schema validation**: Single-line validation (JSON Schema, Zod, OpenAPI)
+- **URL resolution**: Four-tier strategy (explicit > config > Playwright > direct)
+- **TypeScript generics**: Type-safe response bodies
+
+## Pattern Examples
+
+### Example 1: Basic API Request
+
+**Context**: Making authenticated API requests with automatic retry and type safety.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test('should fetch user data', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest<User>({
+    method: 'GET',
+    path: '/api/users/123',
+    headers: { Authorization: 'Bearer token' },
+  });
+
+  expect(status).toBe(200);
+  expect(body.name).toBe('John Doe'); // TypeScript knows body is User
+});
+```
+
+**Key Points**:
+
+- Generic type `<User>` provides TypeScript autocomplete for `body`
+- Status and body destructured from response
+- Headers passed as object
+- Automatic retry for 5xx errors (configurable)
+
+### Example 2: Schema Validation (Single Line)
+
+**Context**: Validate API responses match expected schema with single-line syntax.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test('should validate response schema', async ({ apiRequest }) => {
+  // JSON Schema validation
+  const response = await apiRequest({
+    method: 'GET',
+    path: '/api/users/123',
+    validateSchema: {
+      type: 'object',
+      required: ['id', 'name', 'email'],
+      properties: {
+        id: { type: 'string' },
+        name: { type: 'string' },
+        email: { type: 'string', format: 'email' },
+      },
+    },
+  });
+  // Throws if schema validation fails
+
+  // Zod schema validation
+  import { z } from 'zod';
+
+  const UserSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    email: z.string().email(),
+  });
+
+  const response = await apiRequest({
+    method: 'GET',
+    path: '/api/users/123',
+    validateSchema: UserSchema,
+  });
+  // Response body is type-safe AND validated
+});
+```
+
+**Key Points**:
+
+- Single `validateSchema` parameter
+- Supports JSON Schema, Zod, YAML files, OpenAPI specs
+- Throws on validation failure with detailed errors
+- Zero boilerplate validation code
+
+### Example 3: POST with Body and Retry Configuration
+
+**Context**: Creating resources with custom retry behavior for error testing.
+
+**Implementation**:
+
+```typescript
+test('should create user', async ({ apiRequest }) => {
+  const newUser = {
+    name: 'Jane Doe',
+    email: 'jane@example.com',
+  };
+
+  const { status, body } = await apiRequest({
+    method: 'POST',
+    path: '/api/users',
+    body: newUser, // Automatically sent as JSON
+    headers: { Authorization: 'Bearer token' },
+  });
+
+  expect(status).toBe(201);
+  expect(body.id).toBeDefined();
+});
+
+// Disable retry for error testing
+test('should handle 500 errors', async ({ apiRequest }) => {
+  await expect(
+    apiRequest({
+      method: 'GET',
+      path: '/api/error',
+      retryConfig: { maxRetries: 0 }, // Disable retry
+    }),
+  ).rejects.toThrow('Request failed with status 500');
+});
+```
+
+**Key Points**:
+
+- `body` parameter auto-serializes to JSON
+- Default retry: 5xx errors, 3 retries, exponential backoff
+- Disable retry with `retryConfig: { maxRetries: 0 }`
+- Only 5xx errors retry (4xx errors fail immediately)
+
+### Example 4: URL Resolution Strategy
+
+**Context**: Flexible URL handling for different environments and test contexts.
+
+**Implementation**:
+
+```typescript
+// Strategy 1: Explicit baseUrl (highest priority)
+await apiRequest({
+  method: 'GET',
+  path: '/users',
+  baseUrl: 'https://api.example.com', // Uses https://api.example.com/users
+});
+
+// Strategy 2: Config baseURL (from fixture)
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test.use({ configBaseUrl: 'https://staging-api.example.com' });
+
+test('uses config baseURL', async ({ apiRequest }) => {
+  await apiRequest({
+    method: 'GET',
+    path: '/users', // Uses https://staging-api.example.com/users
+  });
+});
+
+// Strategy 3: Playwright baseURL (from playwright.config.ts)
+// playwright.config.ts
+export default defineConfig({
+  use: {
+    baseURL: 'https://api.example.com',
+  },
+});
+
+test('uses Playwright baseURL', async ({ apiRequest }) => {
+  await apiRequest({
+    method: 'GET',
+    path: '/users', // Uses https://api.example.com/users
+  });
+});
+
+// Strategy 4: Direct path (full URL)
+await apiRequest({
+  method: 'GET',
+  path: 'https://api.example.com/users', // Full URL works too
+});
+```
+
+**Key Points**:
+
+- Four-tier resolution: explicit > config > Playwright > direct
+- Trailing slashes normalized automatically
+- Environment-specific baseUrl easy to configure
+
+### Example 5: Integration with Recurse (Polling)
+
+**Context**: Waiting for async operations to complete (background jobs, eventual consistency).
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('should poll until job completes', async ({ apiRequest, recurse }) => {
+  // Create job
+  const { body } = await apiRequest({
+    method: 'POST',
+    path: '/api/jobs',
+    body: { type: 'export' },
+  });
+
+  const jobId = body.id;
+
+  // Poll until ready
+  const completedJob = await recurse(
+    () => apiRequest({ method: 'GET', path: `/api/jobs/${jobId}` }),
+    (response) => response.body.status === 'completed',
+    { timeout: 60000, interval: 2000 },
+  );
+
+  expect(completedJob.body.result).toBeDefined();
+});
+```
+
+**Key Points**:
+
+- `apiRequest` returns full response object
+- `recurse` polls until predicate returns true
+- Composable utilities work together seamlessly
+
+## Comparison with Vanilla Playwright
+
+| Vanilla Playwright                             | playwright-utils apiRequest                                                        |
+| ---------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `const resp = await request.get('/api/users')` | `const { status, body } = await apiRequest({ method: 'GET', path: '/api/users' })` |
+| `const body = await resp.json()`               | Response already parsed                                                            |
+| `expect(resp.ok()).toBeTruthy()`               | Status code directly accessible                                                    |
+| No retry logic                                 | Auto-retry 5xx errors with backoff                                                 |
+| No schema validation                           | Built-in multi-format validation                                                   |
+| Manual error handling                          | Descriptive error messages                                                         |
+
+## When to Use
+
+**Use apiRequest for:**
+
+- ✅ API endpoint testing
+- ✅ Background API calls in UI tests
+- ✅ Schema validation needs
+- ✅ Tests requiring retry logic
+- ✅ Typed API responses
+
+**Stick with vanilla Playwright for:**
+
+- Simple one-off requests where utility overhead isn't worth it
+- Testing Playwright's native features specifically
+- Legacy tests where migration isn't justified
+
+## Related Fragments
+
+- `overview.md` - Installation and design principles
+- `auth-session.md` - Authentication token management
+- `recurse.md` - Polling for async operations
+- `fixtures-composition.md` - Combining utilities with mergeTests
+- `log.md` - Logging API requests
+
+## Anti-Patterns
+
+**❌ Ignoring retry failures:**
+
+```typescript
+try {
+  await apiRequest({ method: 'GET', path: '/api/unstable' });
+} catch {
+  // Silent failure - loses retry information
+}
+```
+
+**✅ Let retries happen, handle final failure:**
+
+```typescript
+await expect(apiRequest({ method: 'GET', path: '/api/unstable' })).rejects.toThrow(); // Retries happen automatically, then final error caught
+```
+
+**❌ Disabling TypeScript benefits:**
+
+```typescript
+const response: any = await apiRequest({ method: 'GET', path: '/users' });
+```
+
+**✅ Use generic types:**
+
+```typescript
+const { body } = await apiRequest<User[]>({ method: 'GET', path: '/users' });
+// body is typed as User[]
+```

_bmad/bmm/testarch/knowledge/auth-session.md

@@ -0,0 +1,356 @@
+# Auth Session Utility
+
+## Principle
+
+Persist authentication tokens to disk and reuse across test runs. Support multiple user identifiers, ephemeral authentication, and worker-specific accounts for parallel execution. Fetch tokens once, use everywhere.
+
+## Rationale
+
+Playwright's built-in authentication works but has limitations:
+
+- Re-authenticates for every test run (slow)
+- Single user per project setup
+- No token expiration handling
+- Manual session management
+- Complex setup for multi-user scenarios
+
+The `auth-session` utility provides:
+
+- **Token persistence**: Authenticate once, reuse across runs
+- **Multi-user support**: Different user identifiers in same test suite
+- **Ephemeral auth**: On-the-fly user authentication without disk persistence
+- **Worker-specific accounts**: Parallel execution with isolated user accounts
+- **Automatic token management**: Checks validity, renews if expired
+- **Flexible provider pattern**: Adapt to any auth system (OAuth2, JWT, custom)
+
+## Pattern Examples
+
+### Example 1: Basic Auth Session Setup
+
+**Context**: Configure global authentication that persists across test runs.
+
+**Implementation**:
+
+```typescript
+// Step 1: Configure in global-setup.ts
+import { authStorageInit, setAuthProvider, configureAuthSession, authGlobalInit } from '@seontechnologies/playwright-utils/auth-session';
+import myCustomProvider from './auth/custom-auth-provider';
+
+async function globalSetup() {
+  // Ensure storage directories exist
+  authStorageInit();
+
+  // Configure storage path
+  configureAuthSession({
+    authStoragePath: process.cwd() + '/playwright/auth-sessions',
+    debug: true,
+  });
+
+  // Set custom provider (HOW to authenticate)
+  setAuthProvider(myCustomProvider);
+
+  // Optional: pre-fetch token for default user
+  await authGlobalInit();
+}
+
+export default globalSetup;
+
+// Step 2: Create auth fixture
+import { test as base } from '@playwright/test';
+import { createAuthFixtures, setAuthProvider } from '@seontechnologies/playwright-utils/auth-session';
+import myCustomProvider from './custom-auth-provider';
+
+// Register provider early
+setAuthProvider(myCustomProvider);
+
+export const test = base.extend(createAuthFixtures());
+
+// Step 3: Use in tests
+test('authenticated request', async ({ authToken, request }) => {
+  const response = await request.get('/api/protected', {
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  expect(response.ok()).toBeTruthy();
+});
+```
+
+**Key Points**:
+
+- Global setup runs once before all tests
+- Token fetched once, reused across all tests
+- Custom provider defines your auth mechanism
+- Order matters: configure, then setProvider, then init
+
+### Example 2: Multi-User Authentication
+
+**Context**: Testing with different user roles (admin, regular user, guest) in same test suite.
+
+**Implementation**:
+
+```typescript
+import { test } from '../support/auth/auth-fixture';
+
+// Option 1: Per-test user override
+test('admin actions', async ({ authToken, authOptions }) => {
+  // Override default user
+  authOptions.userIdentifier = 'admin';
+
+  const { authToken: adminToken } = await test.step('Get admin token', async () => {
+    return { authToken }; // Re-fetches with new identifier
+  });
+
+  // Use admin token
+  const response = await request.get('/api/admin/users', {
+    headers: { Authorization: `Bearer ${adminToken}` },
+  });
+});
+
+// Option 2: Parallel execution with different users
+test.describe.parallel('multi-user tests', () => {
+  test('user 1 actions', async ({ authToken }) => {
+    // Uses default user (e.g., 'user1')
+  });
+
+  test('user 2 actions', async ({ authToken, authOptions }) => {
+    authOptions.userIdentifier = 'user2';
+    // Uses different token for user2
+  });
+});
+```
+
+**Key Points**:
+
+- Override `authOptions.userIdentifier` per test
+- Tokens cached separately per user identifier
+- Parallel tests isolated with different users
+- Worker-specific accounts possible
+
+### Example 3: Ephemeral User Authentication
+
+**Context**: Create temporary test users that don't persist to disk (e.g., testing user creation flow).
+
+**Implementation**:
+
+```typescript
+import { applyUserCookiesToBrowserContext } from '@seontechnologies/playwright-utils/auth-session';
+import { createTestUser } from '../utils/user-factory';
+
+test('ephemeral user test', async ({ context, page }) => {
+  // Create temporary user (not persisted)
+  const ephemeralUser = await createTestUser({
+    role: 'admin',
+    permissions: ['delete-users'],
+  });
+
+  // Apply auth directly to browser context
+  await applyUserCookiesToBrowserContext(context, ephemeralUser);
+
+  // Page now authenticated as ephemeral user
+  await page.goto('/admin/users');
+
+  await expect(page.getByTestId('delete-user-btn')).toBeVisible();
+
+  // User and token cleaned up after test
+});
+```
+
+**Key Points**:
+
+- No disk persistence (ephemeral)
+- Apply cookies directly to context
+- Useful for testing user lifecycle
+- Clean up automatic when test ends
+
+### Example 4: Testing Multiple Users in Single Test
+
+**Context**: Testing interactions between users (messaging, sharing, collaboration features).
+
+**Implementation**:
+
+```typescript
+test('user interaction', async ({ browser }) => {
+  // User 1 context
+  const user1Context = await browser.newContext({
+    storageState: './auth-sessions/local/user1/storage-state.json',
+  });
+  const user1Page = await user1Context.newPage();
+
+  // User 2 context
+  const user2Context = await browser.newContext({
+    storageState: './auth-sessions/local/user2/storage-state.json',
+  });
+  const user2Page = await user2Context.newPage();
+
+  // User 1 sends message
+  await user1Page.goto('/messages');
+  await user1Page.fill('#message', 'Hello from user 1');
+  await user1Page.click('#send');
+
+  // User 2 receives message
+  await user2Page.goto('/messages');
+  await expect(user2Page.getByText('Hello from user 1')).toBeVisible();
+
+  // Cleanup
+  await user1Context.close();
+  await user2Context.close();
+});
+```
+
+**Key Points**:
+
+- Each user has separate browser context
+- Reference storage state files directly
+- Test real-time interactions
+- Clean up contexts after test
+
+### Example 5: Worker-Specific Accounts (Parallel Testing)
+
+**Context**: Running tests in parallel with isolated user accounts per worker to avoid conflicts.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  workers: 4, // 4 parallel workers
+  use: {
+    // Each worker uses different user
+    storageState: async ({}, use, testInfo) => {
+      const workerIndex = testInfo.workerIndex;
+      const userIdentifier = `worker-${workerIndex}`;
+
+      await use(`./auth-sessions/local/${userIdentifier}/storage-state.json`);
+    },
+  },
+});
+
+// Tests run in parallel, each worker with its own user
+test('parallel test 1', async ({ page }) => {
+  // Worker 0 uses worker-0 account
+  await page.goto('/dashboard');
+});
+
+test('parallel test 2', async ({ page }) => {
+  // Worker 1 uses worker-1 account
+  await page.goto('/dashboard');
+});
+```
+
+**Key Points**:
+
+- Each worker has isolated user account
+- No conflicts in parallel execution
+- Token management automatic per worker
+- Scales to any number of workers
+
+## Custom Auth Provider Pattern
+
+**Context**: Adapt auth-session to your authentication system (OAuth2, JWT, SAML, custom).
+
+**Minimal provider structure**:
+
+```typescript
+import { type AuthProvider } from '@seontechnologies/playwright-utils/auth-session';
+
+const myCustomProvider: AuthProvider = {
+  getEnvironment: (options) => options.environment || 'local',
+
+  getUserIdentifier: (options) => options.userIdentifier || 'default-user',
+
+  extractToken: (storageState) => {
+    // Extract token from your storage format
+    return storageState.cookies.find((c) => c.name === 'auth_token')?.value;
+  },
+
+  extractCookies: (tokenData) => {
+    // Convert token to cookies for browser context
+    return [
+      {
+        name: 'auth_token',
+        value: tokenData,
+        domain: 'example.com',
+        path: '/',
+        httpOnly: true,
+        secure: true,
+      },
+    ];
+  },
+
+  isTokenExpired: (storageState) => {
+    // Check if token is expired
+    const expiresAt = storageState.cookies.find((c) => c.name === 'expires_at');
+    return Date.now() > parseInt(expiresAt?.value || '0');
+  },
+
+  manageAuthToken: async (request, options) => {
+    // Main token acquisition logic
+    // Return storage state with cookies/localStorage
+  },
+};
+
+export default myCustomProvider;
+```
+
+## Integration with API Request
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('authenticated API call', async ({ apiRequest, authToken }) => {
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/protected',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  expect(status).toBe(200);
+});
+```
+
+## Related Fragments
+
+- `overview.md` - Installation and fixture composition
+- `api-request.md` - Authenticated API requests
+- `fixtures-composition.md` - Merging auth with other utilities
+
+## Anti-Patterns
+
+**❌ Calling setAuthProvider after globalSetup:**
+
+```typescript
+async function globalSetup() {
+  configureAuthSession(...)
+  await authGlobalInit()  // Provider not set yet!
+  setAuthProvider(provider)  // Too late
+}
+```
+
+**✅ Register provider before init:**
+
+```typescript
+async function globalSetup() {
+  authStorageInit()
+  configureAuthSession(...)
+  setAuthProvider(provider)  // First
+  await authGlobalInit()     // Then init
+}
+```
+
+**❌ Hardcoding storage paths:**
+
+```typescript
+const storageState = './auth-sessions/local/user1/storage-state.json'; // Brittle
+```
+
+**✅ Use helper functions:**
+
+```typescript
+import { getTokenFilePath } from '@seontechnologies/playwright-utils/auth-session';
+
+const tokenPath = getTokenFilePath({
+  environment: 'local',
+  userIdentifier: 'user1',
+  tokenFileName: 'storage-state.json',
+});
+```

_bmad/bmm/testarch/knowledge/burn-in.md

@@ -0,0 +1,273 @@
+# Burn-in Test Runner
+
+## Principle
+
+Use smart test selection with git diff analysis to run only affected tests. Filter out irrelevant changes (configs, types, docs) and control test volume with percentage-based execution. Reduce unnecessary CI runs while maintaining reliability.
+
+## Rationale
+
+Playwright's `--only-changed` triggers all affected tests:
+
+- Config file changes trigger hundreds of tests
+- Type definition changes cause full suite runs
+- No volume control (all or nothing)
+- Slow CI pipelines
+
+The `burn-in` utility provides:
+
+- **Smart filtering**: Skip patterns for irrelevant files (configs, types, docs)
+- **Volume control**: Run percentage of affected tests after filtering
+- **Custom dependency analysis**: More accurate than Playwright's built-in
+- **CI optimization**: Faster pipelines without sacrificing confidence
+- **Process of elimination**: Start with all → filter irrelevant → control volume
+
+## Pattern Examples
+
+### Example 1: Basic Burn-in Setup
+
+**Context**: Run burn-in on changed files compared to main branch.
+
+**Implementation**:
+
+```typescript
+// Step 1: Create burn-in script
+// playwright/scripts/burn-in-changed.ts
+import { runBurnIn } from '@seontechnologies/playwright-utils/burn-in'
+
+async function main() {
+  await runBurnIn({
+    configPath: 'playwright/config/.burn-in.config.ts',
+    baseBranch: 'main'
+  })
+}
+
+main().catch(console.error)
+
+// Step 2: Create config
+// playwright/config/.burn-in.config.ts
+import type { BurnInConfig } from '@seontechnologies/playwright-utils/burn-in'
+
+const config: BurnInConfig = {
+  // Files that never trigger tests (first filter)
+  skipBurnInPatterns: [
+    '**/config/**',
+    '**/*constants*',
+    '**/*types*',
+    '**/*.md',
+    '**/README*'
+  ],
+
+  // Run 30% of remaining tests after skip filter
+  burnInTestPercentage: 0.3,
+
+  // Burn-in repetition
+  burnIn: {
+    repeatEach: 3,  // Run each test 3 times
+    retries: 1      // Allow 1 retry
+  }
+}
+
+export default config
+
+// Step 3: Add package.json script
+{
+  "scripts": {
+    "test:pw:burn-in-changed": "tsx playwright/scripts/burn-in-changed.ts"
+  }
+}
+```
+
+**Key Points**:
+
+- Two-stage filtering: skip patterns, then volume control
+- `skipBurnInPatterns` eliminates irrelevant files
+- `burnInTestPercentage` controls test volume (0.3 = 30%)
+- Custom dependency analysis finds actually affected tests
+
+### Example 2: CI Integration
+
+**Context**: Use burn-in in GitHub Actions for efficient CI runs.
+
+**Implementation**:
+
+```yaml
+# .github/workflows/burn-in.yml
+name: Burn-in Changed Tests
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  burn-in:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Need git history
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run burn-in on changed tests
+        run: npm run test:pw:burn-in-changed -- --base-branch=origin/main
+
+      - name: Upload artifacts
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: burn-in-failures
+          path: test-results/
+```
+
+**Key Points**:
+
+- `fetch-depth: 0` for full git history
+- Pass `--base-branch=origin/main` for PR comparison
+- Upload artifacts only on failure
+- Significantly faster than full suite
+
+### Example 3: How It Works (Process of Elimination)
+
+**Context**: Understanding the filtering pipeline.
+
+**Scenario:**
+
+```
+Git diff finds: 21 changed files
+├─ Step 1: Skip patterns filter
+│  Removed: 6 files (*.md, config/*, *types*)
+│  Remaining: 15 files
+│
+├─ Step 2: Dependency analysis
+│  Tests that import these 15 files: 45 tests
+│
+└─ Step 3: Volume control (30%)
+   Final tests to run: 14 tests (30% of 45)
+
+Result: Run 14 targeted tests instead of 147 with --only-changed!
+```
+
+**Key Points**:
+
+- Three-stage pipeline: skip → analyze → control
+- Custom dependency analysis (not just imports)
+- Percentage applies AFTER filtering
+- Dramatically reduces CI time
+
+### Example 4: Environment-Specific Configuration
+
+**Context**: Different settings for local vs CI environments.
+
+**Implementation**:
+
+```typescript
+import type { BurnInConfig } from '@seontechnologies/playwright-utils/burn-in';
+
+const config: BurnInConfig = {
+  skipBurnInPatterns: ['**/config/**', '**/*types*', '**/*.md'],
+
+  // CI runs fewer iterations, local runs more
+  burnInTestPercentage: process.env.CI ? 0.2 : 0.3,
+
+  burnIn: {
+    repeatEach: process.env.CI ? 2 : 3,
+    retries: process.env.CI ? 0 : 1, // No retries in CI
+  },
+};
+
+export default config;
+```
+
+**Key Points**:
+
+- `process.env.CI` for environment detection
+- Lower percentage in CI (20% vs 30%)
+- Fewer iterations in CI (2 vs 3)
+- No retries in CI (fail fast)
+
+### Example 5: Sharding Support
+
+**Context**: Distribute burn-in tests across multiple CI workers.
+
+**Implementation**:
+
+```typescript
+// burn-in-changed.ts with sharding
+import { runBurnIn } from '@seontechnologies/playwright-utils/burn-in';
+
+async function main() {
+  const shardArg = process.argv.find((arg) => arg.startsWith('--shard='));
+
+  if (shardArg) {
+    process.env.PW_SHARD = shardArg.split('=')[1];
+  }
+
+  await runBurnIn({
+    configPath: 'playwright/config/.burn-in.config.ts',
+  });
+}
+```
+
+```yaml
+# GitHub Actions with sharding
+jobs:
+  burn-in:
+    strategy:
+      matrix:
+        shard: [1/3, 2/3, 3/3]
+    steps:
+      - run: npm run test:pw:burn-in-changed -- --shard=${{ matrix.shard }}
+```
+
+**Key Points**:
+
+- Pass `--shard=1/3` for parallel execution
+- Burn-in respects Playwright sharding
+- Distribute across multiple workers
+- Reduces total CI time further
+
+## Integration with CI Workflow
+
+When setting up CI with `*ci` workflow, recommend burn-in for:
+
+- Pull request validation
+- Pre-merge checks
+- Nightly builds (subset runs)
+
+## Related Fragments
+
+- `ci-burn-in.md` - Traditional burn-in patterns (10-iteration loops)
+- `selective-testing.md` - Test selection strategies
+- `overview.md` - Installation
+
+## Anti-Patterns
+
+**❌ Over-aggressive skip patterns:**
+
+```typescript
+skipBurnInPatterns: [
+  '**/*', // Skips everything!
+];
+```
+
+**✅ Targeted skip patterns:**
+
+```typescript
+skipBurnInPatterns: ['**/config/**', '**/*types*', '**/*.md', '**/*constants*'];
+```
+
+**❌ Too low percentage (false confidence):**
+
+```typescript
+burnInTestPercentage: 0.05; // Only 5% - might miss issues
+```
+
+**✅ Balanced percentage:**
+
+```typescript
+burnInTestPercentage: 0.2; // 20% in CI, provides good coverage
+```

_bmad/bmm/testarch/knowledge/ci-burn-in.md

@@ -0,0 +1,675 @@
+# CI Pipeline and Burn-In Strategy
+
+## Principle
+
+CI pipelines must execute tests reliably, quickly, and provide clear feedback. Burn-in testing (running changed tests multiple times) flushes out flakiness before merge. Stage jobs strategically: install/cache once, run changed specs first for fast feedback, then shard full suites with fail-fast disabled to preserve evidence.
+
+## Rationale
+
+CI is the quality gate for production. A poorly configured pipeline either wastes developer time (slow feedback, false positives) or ships broken code (false negatives, insufficient coverage). Burn-in testing ensures reliability by stress-testing changed code, while parallel execution and intelligent test selection optimize speed without sacrificing thoroughness.
+
+## Pattern Examples
+
+### Example 1: GitHub Actions Workflow with Parallel Execution
+
+**Context**: Production-ready CI/CD pipeline for E2E tests with caching, parallelization, and burn-in testing.
+
+**Implementation**:
+
+```yaml
+# .github/workflows/e2e-tests.yml
+name: E2E Tests
+on:
+  pull_request:
+  push:
+    branches: [main, develop]
+
+env:
+  NODE_VERSION_FILE: '.nvmrc'
+  CACHE_KEY: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+
+jobs:
+  install-dependencies:
+    name: Install & Cache Dependencies
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ${{ env.NODE_VERSION_FILE }}
+          cache: 'npm'
+
+      - name: Cache node modules
+        uses: actions/cache@v4
+        id: npm-cache
+        with:
+          path: |
+            ~/.npm
+            node_modules
+            ~/.cache/Cypress
+            ~/.cache/ms-playwright
+          key: ${{ env.CACHE_KEY }}
+          restore-keys: |
+            ${{ runner.os }}-node-
+
+      - name: Install dependencies
+        if: steps.npm-cache.outputs.cache-hit != 'true'
+        run: npm ci --prefer-offline --no-audit
+
+      - name: Install Playwright browsers
+        if: steps.npm-cache.outputs.cache-hit != 'true'
+        run: npx playwright install --with-deps chromium
+
+  test-changed-specs:
+    name: Test Changed Specs First (Burn-In)
+    needs: install-dependencies
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Full history for accurate diff
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ${{ env.NODE_VERSION_FILE }}
+          cache: 'npm'
+
+      - name: Restore dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.npm
+            node_modules
+            ~/.cache/ms-playwright
+          key: ${{ env.CACHE_KEY }}
+
+      - name: Detect changed test files
+        id: changed-tests
+        run: |
+          CHANGED_SPECS=$(git diff --name-only origin/main...HEAD | grep -E '\.(spec|test)\.(ts|js|tsx|jsx)$' || echo "")
+          echo "changed_specs=${CHANGED_SPECS}" >> $GITHUB_OUTPUT
+          echo "Changed specs: ${CHANGED_SPECS}"
+
+      - name: Run burn-in on changed specs (10 iterations)
+        if: steps.changed-tests.outputs.changed_specs != ''
+        run: |
+          SPECS="${{ steps.changed-tests.outputs.changed_specs }}"
+          echo "Running burn-in: 10 iterations on changed specs"
+          for i in {1..10}; do
+            echo "Burn-in iteration $i/10"
+            npm run test -- $SPECS || {
+              echo "❌ Burn-in failed on iteration $i"
+              exit 1
+            }
+          done
+          echo "✅ Burn-in passed - 10/10 successful runs"
+
+      - name: Upload artifacts on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: burn-in-failure-artifacts
+          path: |
+            test-results/
+            playwright-report/
+            screenshots/
+          retention-days: 7
+
+  test-e2e-sharded:
+    name: E2E Tests (Shard ${{ matrix.shard }}/${{ strategy.job-total }})
+    needs: [install-dependencies, test-changed-specs]
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false # Run all shards even if one fails
+      matrix:
+        shard: [1, 2, 3, 4]
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ${{ env.NODE_VERSION_FILE }}
+          cache: 'npm'
+
+      - name: Restore dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.npm
+            node_modules
+            ~/.cache/ms-playwright
+          key: ${{ env.CACHE_KEY }}
+
+      - name: Run E2E tests (shard ${{ matrix.shard }})
+        run: npm run test:e2e -- --shard=${{ matrix.shard }}/4
+        env:
+          TEST_ENV: staging
+          CI: true
+
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results-shard-${{ matrix.shard }}
+          path: |
+            test-results/
+            playwright-report/
+          retention-days: 30
+
+      - name: Upload JUnit report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: junit-results-shard-${{ matrix.shard }}
+          path: test-results/junit.xml
+          retention-days: 30
+
+  merge-test-results:
+    name: Merge Test Results & Generate Report
+    needs: test-e2e-sharded
+    runs-on: ubuntu-latest
+    if: always()
+    steps:
+      - name: Download all shard results
+        uses: actions/download-artifact@v4
+        with:
+          pattern: test-results-shard-*
+          path: all-results/
+
+      - name: Merge HTML reports
+        run: |
+          npx playwright merge-reports --reporter=html all-results/
+          echo "Merged report available in playwright-report/"
+
+      - name: Upload merged report
+        uses: actions/upload-artifact@v4
+        with:
+          name: merged-playwright-report
+          path: playwright-report/
+          retention-days: 30
+
+      - name: Comment PR with results
+        if: github.event_name == 'pull_request'
+        uses: daun/playwright-report-comment@v3
+        with:
+          report-path: playwright-report/
+```
+
+**Key Points**:
+
+- **Install once, reuse everywhere**: Dependencies cached across all jobs
+- **Burn-in first**: Changed specs run 10x before full suite
+- **Fail-fast disabled**: All shards run to completion for full evidence
+- **Parallel execution**: 4 shards cut execution time by ~75%
+- **Artifact retention**: 30 days for reports, 7 days for failure debugging
+
+---
+
+### Example 2: Burn-In Loop Pattern (Standalone Script)
+
+**Context**: Reusable bash script for burn-in testing changed specs locally or in CI.
+
+**Implementation**:
+
+```bash
+#!/bin/bash
+# scripts/burn-in-changed.sh
+# Usage: ./scripts/burn-in-changed.sh [iterations] [base-branch]
+
+set -e  # Exit on error
+
+# Configuration
+ITERATIONS=${1:-10}
+BASE_BRANCH=${2:-main}
+SPEC_PATTERN='\.(spec|test)\.(ts|js|tsx|jsx)$'
+
+echo "🔥 Burn-In Test Runner"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "Iterations: $ITERATIONS"
+echo "Base branch: $BASE_BRANCH"
+echo ""
+
+# Detect changed test files
+echo "📋 Detecting changed test files..."
+CHANGED_SPECS=$(git diff --name-only $BASE_BRANCH...HEAD | grep -E "$SPEC_PATTERN" || echo "")
+
+if [ -z "$CHANGED_SPECS" ]; then
+  echo "✅ No test files changed. Skipping burn-in."
+  exit 0
+fi
+
+echo "Changed test files:"
+echo "$CHANGED_SPECS" | sed 's/^/  - /'
+echo ""
+
+# Count specs
+SPEC_COUNT=$(echo "$CHANGED_SPECS" | wc -l | xargs)
+echo "Running burn-in on $SPEC_COUNT test file(s)..."
+echo ""
+
+# Burn-in loop
+FAILURES=()
+for i in $(seq 1 $ITERATIONS); do
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo "🔄 Iteration $i/$ITERATIONS"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+  # Run tests with explicit file list
+  if npm run test -- $CHANGED_SPECS 2>&1 | tee "burn-in-log-$i.txt"; then
+    echo "✅ Iteration $i passed"
+  else
+    echo "❌ Iteration $i failed"
+    FAILURES+=($i)
+
+    # Save failure artifacts
+    mkdir -p burn-in-failures/iteration-$i
+    cp -r test-results/ burn-in-failures/iteration-$i/ 2>/dev/null || true
+    cp -r screenshots/ burn-in-failures/iteration-$i/ 2>/dev/null || true
+
+    echo ""
+    echo "🛑 BURN-IN FAILED on iteration $i"
+    echo "Failure artifacts saved to: burn-in-failures/iteration-$i/"
+    echo "Logs saved to: burn-in-log-$i.txt"
+    echo ""
+    exit 1
+  fi
+
+  echo ""
+done
+
+# Success summary
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "🎉 BURN-IN PASSED"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "All $ITERATIONS iterations passed for $SPEC_COUNT test file(s)"
+echo "Changed specs are stable and ready to merge."
+echo ""
+
+# Cleanup logs
+rm -f burn-in-log-*.txt
+
+exit 0
+```
+
+**Usage**:
+
+```bash
+# Run locally with default settings (10 iterations, compare to main)
+./scripts/burn-in-changed.sh
+
+# Custom iterations and base branch
+./scripts/burn-in-changed.sh 20 develop
+
+# Add to package.json
+{
+  "scripts": {
+    "test:burn-in": "bash scripts/burn-in-changed.sh",
+    "test:burn-in:strict": "bash scripts/burn-in-changed.sh 20"
+  }
+}
+```
+
+**Key Points**:
+
+- **Exit on first failure**: Flaky tests caught immediately
+- **Failure artifacts**: Saved per-iteration for debugging
+- **Flexible configuration**: Iterations and base branch customizable
+- **CI/local parity**: Same script runs in both environments
+- **Clear output**: Visual feedback on progress and results
+
+---
+
+### Example 3: Shard Orchestration with Result Aggregation
+
+**Context**: Advanced sharding strategy for large test suites with intelligent result merging.
+
+**Implementation**:
+
+```javascript
+// scripts/run-sharded-tests.js
+const { spawn } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Run tests across multiple shards and aggregate results
+ * Usage: node scripts/run-sharded-tests.js --shards=4 --env=staging
+ */
+
+const SHARD_COUNT = parseInt(process.env.SHARD_COUNT || '4');
+const TEST_ENV = process.env.TEST_ENV || 'local';
+const RESULTS_DIR = path.join(__dirname, '../test-results');
+
+console.log(`🚀 Running tests across ${SHARD_COUNT} shards`);
+console.log(`Environment: ${TEST_ENV}`);
+console.log('━'.repeat(50));
+
+// Ensure results directory exists
+if (!fs.existsSync(RESULTS_DIR)) {
+  fs.mkdirSync(RESULTS_DIR, { recursive: true });
+}
+
+/**
+ * Run a single shard
+ */
+function runShard(shardIndex) {
+  return new Promise((resolve, reject) => {
+    const shardId = `${shardIndex}/${SHARD_COUNT}`;
+    console.log(`\n📦 Starting shard ${shardId}...`);
+
+    const child = spawn('npx', ['playwright', 'test', `--shard=${shardId}`, '--reporter=json'], {
+      env: { ...process.env, TEST_ENV, SHARD_INDEX: shardIndex },
+      stdio: 'pipe',
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout.on('data', (data) => {
+      stdout += data.toString();
+      process.stdout.write(data);
+    });
+
+    child.stderr.on('data', (data) => {
+      stderr += data.toString();
+      process.stderr.write(data);
+    });
+
+    child.on('close', (code) => {
+      // Save shard results
+      const resultFile = path.join(RESULTS_DIR, `shard-${shardIndex}.json`);
+      try {
+        const result = JSON.parse(stdout);
+        fs.writeFileSync(resultFile, JSON.stringify(result, null, 2));
+        console.log(`✅ Shard ${shardId} completed (exit code: ${code})`);
+        resolve({ shardIndex, code, result });
+      } catch (error) {
+        console.error(`❌ Shard ${shardId} failed to parse results:`, error.message);
+        reject({ shardIndex, code, error });
+      }
+    });
+
+    child.on('error', (error) => {
+      console.error(`❌ Shard ${shardId} process error:`, error.message);
+      reject({ shardIndex, error });
+    });
+  });
+}
+
+/**
+ * Aggregate results from all shards
+ */
+function aggregateResults() {
+  console.log('\n📊 Aggregating results from all shards...');
+
+  const shardResults = [];
+  let totalTests = 0;
+  let totalPassed = 0;
+  let totalFailed = 0;
+  let totalSkipped = 0;
+  let totalFlaky = 0;
+
+  for (let i = 1; i <= SHARD_COUNT; i++) {
+    const resultFile = path.join(RESULTS_DIR, `shard-${i}.json`);
+    if (fs.existsSync(resultFile)) {
+      const result = JSON.parse(fs.readFileSync(resultFile, 'utf8'));
+      shardResults.push(result);
+
+      // Aggregate stats
+      totalTests += result.stats?.expected || 0;
+      totalPassed += result.stats?.expected || 0;
+      totalFailed += result.stats?.unexpected || 0;
+      totalSkipped += result.stats?.skipped || 0;
+      totalFlaky += result.stats?.flaky || 0;
+    }
+  }
+
+  const summary = {
+    totalShards: SHARD_COUNT,
+    environment: TEST_ENV,
+    totalTests,
+    passed: totalPassed,
+    failed: totalFailed,
+    skipped: totalSkipped,
+    flaky: totalFlaky,
+    duration: shardResults.reduce((acc, r) => acc + (r.duration || 0), 0),
+    timestamp: new Date().toISOString(),
+  };
+
+  // Save aggregated summary
+  fs.writeFileSync(path.join(RESULTS_DIR, 'summary.json'), JSON.stringify(summary, null, 2));
+
+  console.log('\n━'.repeat(50));
+  console.log('📈 Test Results Summary');
+  console.log('━'.repeat(50));
+  console.log(`Total tests:    ${totalTests}`);
+  console.log(`✅ Passed:      ${totalPassed}`);
+  console.log(`❌ Failed:      ${totalFailed}`);
+  console.log(`⏭️  Skipped:     ${totalSkipped}`);
+  console.log(`⚠️  Flaky:       ${totalFlaky}`);
+  console.log(`⏱️  Duration:    ${(summary.duration / 1000).toFixed(2)}s`);
+  console.log('━'.repeat(50));
+
+  return summary;
+}
+
+/**
+ * Main execution
+ */
+async function main() {
+  const startTime = Date.now();
+  const shardPromises = [];
+
+  // Run all shards in parallel
+  for (let i = 1; i <= SHARD_COUNT; i++) {
+    shardPromises.push(runShard(i));
+  }
+
+  try {
+    await Promise.allSettled(shardPromises);
+  } catch (error) {
+    console.error('❌ One or more shards failed:', error);
+  }
+
+  // Aggregate results
+  const summary = aggregateResults();
+
+  const totalTime = ((Date.now() - startTime) / 1000).toFixed(2);
+  console.log(`\n⏱️  Total execution time: ${totalTime}s`);
+
+  // Exit with failure if any tests failed
+  if (summary.failed > 0) {
+    console.error('\n❌ Test suite failed');
+    process.exit(1);
+  }
+
+  console.log('\n✅ All tests passed');
+  process.exit(0);
+}
+
+main().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});
+```
+
+**package.json integration**:
+
+```json
+{
+  "scripts": {
+    "test:sharded": "node scripts/run-sharded-tests.js",
+    "test:sharded:ci": "SHARD_COUNT=8 TEST_ENV=staging node scripts/run-sharded-tests.js"
+  }
+}
+```
+
+**Key Points**:
+
+- **Parallel shard execution**: All shards run simultaneously
+- **Result aggregation**: Unified summary across shards
+- **Failure detection**: Exit code reflects overall test status
+- **Artifact preservation**: Individual shard results saved for debugging
+- **CI/local compatibility**: Same script works in both environments
+
+---
+
+### Example 4: Selective Test Execution (Changed Files + Tags)
+
+**Context**: Optimize CI by running only relevant tests based on file changes and tags.
+
+**Implementation**:
+
+```bash
+#!/bin/bash
+# scripts/selective-test-runner.sh
+# Intelligent test selection based on changed files and test tags
+
+set -e
+
+BASE_BRANCH=${BASE_BRANCH:-main}
+TEST_ENV=${TEST_ENV:-local}
+
+echo "🎯 Selective Test Runner"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "Base branch: $BASE_BRANCH"
+echo "Environment: $TEST_ENV"
+echo ""
+
+# Detect changed files (all types, not just tests)
+CHANGED_FILES=$(git diff --name-only $BASE_BRANCH...HEAD)
+
+if [ -z "$CHANGED_FILES" ]; then
+  echo "✅ No files changed. Skipping tests."
+  exit 0
+fi
+
+echo "Changed files:"
+echo "$CHANGED_FILES" | sed 's/^/  - /'
+echo ""
+
+# Determine test strategy based on changes
+run_smoke_only=false
+run_all_tests=false
+affected_specs=""
+
+# Critical files = run all tests
+if echo "$CHANGED_FILES" | grep -qE '(package\.json|package-lock\.json|playwright\.config|cypress\.config|\.github/workflows)'; then
+  echo "⚠️  Critical configuration files changed. Running ALL tests."
+  run_all_tests=true
+
+# Auth/security changes = run all auth + smoke tests
+elif echo "$CHANGED_FILES" | grep -qE '(auth|login|signup|security)'; then
+  echo "🔒 Auth/security files changed. Running auth + smoke tests."
+  npm run test -- --grep "@auth|@smoke"
+  exit $?
+
+# API changes = run integration + smoke tests
+elif echo "$CHANGED_FILES" | grep -qE '(api|service|controller)'; then
+  echo "🔌 API files changed. Running integration + smoke tests."
+  npm run test -- --grep "@integration|@smoke"
+  exit $?
+
+# UI component changes = run related component tests
+elif echo "$CHANGED_FILES" | grep -qE '\.(tsx|jsx|vue)$'; then
+  echo "🎨 UI components changed. Running component + smoke tests."
+
+  # Extract component names and find related tests
+  components=$(echo "$CHANGED_FILES" | grep -E '\.(tsx|jsx|vue)$' | xargs -I {} basename {} | sed 's/\.[^.]*$//')
+  for component in $components; do
+    # Find tests matching component name
+    affected_specs+=$(find tests -name "*${component}*" -type f) || true
+  done
+
+  if [ -n "$affected_specs" ]; then
+    echo "Running tests for: $affected_specs"
+    npm run test -- $affected_specs --grep "@smoke"
+  else
+    echo "No specific tests found. Running smoke tests only."
+    npm run test -- --grep "@smoke"
+  fi
+  exit $?
+
+# Documentation/config only = run smoke tests
+elif echo "$CHANGED_FILES" | grep -qE '\.(md|txt|json|yml|yaml)$'; then
+  echo "📝 Documentation/config files changed. Running smoke tests only."
+  run_smoke_only=true
+else
+  echo "⚙️  Other files changed. Running smoke tests."
+  run_smoke_only=true
+fi
+
+# Execute selected strategy
+if [ "$run_all_tests" = true ]; then
+  echo ""
+  echo "Running full test suite..."
+  npm run test
+elif [ "$run_smoke_only" = true ]; then
+  echo ""
+  echo "Running smoke tests..."
+  npm run test -- --grep "@smoke"
+fi
+```
+
+**Usage in GitHub Actions**:
+
+```yaml
+# .github/workflows/selective-tests.yml
+name: Selective Tests
+on: pull_request
+
+jobs:
+  selective-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Run selective tests
+        run: bash scripts/selective-test-runner.sh
+        env:
+          BASE_BRANCH: ${{ github.base_ref }}
+          TEST_ENV: staging
+```
+
+**Key Points**:
+
+- **Intelligent routing**: Tests selected based on changed file types
+- **Tag-based filtering**: Use @smoke, @auth, @integration tags
+- **Fast feedback**: Only relevant tests run on most PRs
+- **Safety net**: Critical changes trigger full suite
+- **Component mapping**: UI changes run related component tests
+
+---
+
+## CI Configuration Checklist
+
+Before deploying your CI pipeline, verify:
+
+- [ ] **Caching strategy**: node_modules, npm cache, browser binaries cached
+- [ ] **Timeout budgets**: Each job has reasonable timeout (10-30 min)
+- [ ] **Artifact retention**: 30 days for reports, 7 days for failure artifacts
+- [ ] **Parallelization**: Matrix strategy uses fail-fast: false
+- [ ] **Burn-in enabled**: Changed specs run 5-10x before merge
+- [ ] **wait-on app startup**: CI waits for app (wait-on: '<http://localhost:3000>')
+- [ ] **Secrets documented**: README lists required secrets (API keys, tokens)
+- [ ] **Local parity**: CI scripts runnable locally (npm run test:ci)
+
+## Integration Points
+
+- Used in workflows: `*ci` (CI/CD pipeline setup)
+- Related fragments: `selective-testing.md`, `playwright-config.md`, `test-quality.md`
+- CI tools: GitHub Actions, GitLab CI, CircleCI, Jenkins
+
+_Source: Murat CI/CD strategy blog, Playwright/Cypress workflow examples, SEON production pipelines_

_bmad/bmm/testarch/knowledge/component-tdd.md

@@ -0,0 +1,486 @@
+# Component Test-Driven Development Loop
+
+## Principle
+
+Start every UI change with a failing component test (`cy.mount`, Playwright component test, or RTL `render`). Follow the Red-Green-Refactor cycle: write a failing test (red), make it pass with minimal code (green), then improve the implementation (refactor). Ship only after the cycle completes. Keep component tests under 100 lines, isolated with fresh providers per test, and validate accessibility alongside functionality.
+
+## Rationale
+
+Component TDD provides immediate feedback during development. Failing tests (red) clarify requirements before writing code. Minimal implementations (green) prevent over-engineering. Refactoring with passing tests ensures changes don't break functionality. Isolated tests with fresh providers prevent state bleed in parallel runs. Accessibility assertions catch usability issues early. Visual debugging (Cypress runner, Storybook, Playwright trace viewer) accelerates diagnosis when tests fail.
+
+## Pattern Examples
+
+### Example 1: Red-Green-Refactor Loop
+
+**Context**: When building a new component, start with a failing test that describes the desired behavior. Implement just enough to pass, then refactor for quality.
+
+**Implementation**:
+
+```typescript
+// Step 1: RED - Write failing test
+// Button.cy.tsx (Cypress Component Test)
+import { Button } from './Button';
+
+describe('Button Component', () => {
+  it('should render with label', () => {
+    cy.mount(<Button label="Click Me" />);
+    cy.contains('Click Me').should('be.visible');
+  });
+
+  it('should call onClick when clicked', () => {
+    const onClickSpy = cy.stub().as('onClick');
+    cy.mount(<Button label="Submit" onClick={onClickSpy} />);
+
+    cy.get('button').click();
+    cy.get('@onClick').should('have.been.calledOnce');
+  });
+});
+
+// Run test: FAILS - Button component doesn't exist yet
+// Error: "Cannot find module './Button'"
+
+// Step 2: GREEN - Minimal implementation
+// Button.tsx
+type ButtonProps = {
+  label: string;
+  onClick?: () => void;
+};
+
+export const Button = ({ label, onClick }: ButtonProps) => {
+  return <button onClick={onClick}>{label}</button>;
+};
+
+// Run test: PASSES - Component renders and handles clicks
+
+// Step 3: REFACTOR - Improve implementation
+// Add disabled state, loading state, variants
+type ButtonProps = {
+  label: string;
+  onClick?: () => void;
+  disabled?: boolean;
+  loading?: boolean;
+  variant?: 'primary' | 'secondary' | 'danger';
+};
+
+export const Button = ({
+  label,
+  onClick,
+  disabled = false,
+  loading = false,
+  variant = 'primary'
+}: ButtonProps) => {
+  return (
+    <button
+      onClick={onClick}
+      disabled={disabled || loading}
+      className={`btn btn-${variant}`}
+      data-testid="button"
+    >
+      {loading ? <Spinner /> : label}
+    </button>
+  );
+};
+
+// Step 4: Expand tests for new features
+describe('Button Component', () => {
+  it('should render with label', () => {
+    cy.mount(<Button label="Click Me" />);
+    cy.contains('Click Me').should('be.visible');
+  });
+
+  it('should call onClick when clicked', () => {
+    const onClickSpy = cy.stub().as('onClick');
+    cy.mount(<Button label="Submit" onClick={onClickSpy} />);
+
+    cy.get('button').click();
+    cy.get('@onClick').should('have.been.calledOnce');
+  });
+
+  it('should be disabled when disabled prop is true', () => {
+    cy.mount(<Button label="Submit" disabled={true} />);
+    cy.get('button').should('be.disabled');
+  });
+
+  it('should show spinner when loading', () => {
+    cy.mount(<Button label="Submit" loading={true} />);
+    cy.get('[data-testid="spinner"]').should('be.visible');
+    cy.get('button').should('be.disabled');
+  });
+
+  it('should apply variant styles', () => {
+    cy.mount(<Button label="Delete" variant="danger" />);
+    cy.get('button').should('have.class', 'btn-danger');
+  });
+});
+
+// Run tests: ALL PASS - Refactored component still works
+
+// Playwright Component Test equivalent
+import { test, expect } from '@playwright/experimental-ct-react';
+import { Button } from './Button';
+
+test.describe('Button Component', () => {
+  test('should call onClick when clicked', async ({ mount }) => {
+    let clicked = false;
+    const component = await mount(
+      <Button label="Submit" onClick={() => { clicked = true; }} />
+    );
+
+    await component.getByRole('button').click();
+    expect(clicked).toBe(true);
+  });
+
+  test('should be disabled when loading', async ({ mount }) => {
+    const component = await mount(<Button label="Submit" loading={true} />);
+    await expect(component.getByRole('button')).toBeDisabled();
+    await expect(component.getByTestId('spinner')).toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Red: Write failing test first - clarifies requirements before coding
+- Green: Implement minimal code to pass - prevents over-engineering
+- Refactor: Improve code quality while keeping tests green
+- Expand: Add tests for new features after refactoring
+- Cycle repeats: Each new feature starts with a failing test
+
+### Example 2: Provider Isolation Pattern
+
+**Context**: When testing components that depend on context providers (React Query, Auth, Router), wrap them with required providers in each test to prevent state bleed between tests.
+
+**Implementation**:
+
+```typescript
+// test-utils/AllTheProviders.tsx
+import { FC, ReactNode } from 'react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { BrowserRouter } from 'react-router-dom';
+import { AuthProvider } from '../contexts/AuthContext';
+
+type Props = {
+  children: ReactNode;
+  initialAuth?: { user: User | null; token: string | null };
+};
+
+export const AllTheProviders: FC<Props> = ({ children, initialAuth }) => {
+  // Create NEW QueryClient per test (prevent state bleed)
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: { retry: false },
+      mutations: { retry: false }
+    }
+  });
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      <BrowserRouter>
+        <AuthProvider initialAuth={initialAuth}>
+          {children}
+        </AuthProvider>
+      </BrowserRouter>
+    </QueryClientProvider>
+  );
+};
+
+// Cypress custom mount command
+// cypress/support/component.tsx
+import { mount } from 'cypress/react18';
+import { AllTheProviders } from '../../test-utils/AllTheProviders';
+
+Cypress.Commands.add('wrappedMount', (component, options = {}) => {
+  const { initialAuth, ...mountOptions } = options;
+
+  return mount(
+    <AllTheProviders initialAuth={initialAuth}>
+      {component}
+    </AllTheProviders>,
+    mountOptions
+  );
+});
+
+// Usage in tests
+// UserProfile.cy.tsx
+import { UserProfile } from './UserProfile';
+
+describe('UserProfile Component', () => {
+  it('should display user when authenticated', () => {
+    const user = { id: 1, name: 'John Doe', email: 'john@example.com' };
+
+    cy.wrappedMount(<UserProfile />, {
+      initialAuth: { user, token: 'fake-token' }
+    });
+
+    cy.contains('John Doe').should('be.visible');
+    cy.contains('john@example.com').should('be.visible');
+  });
+
+  it('should show login prompt when not authenticated', () => {
+    cy.wrappedMount(<UserProfile />, {
+      initialAuth: { user: null, token: null }
+    });
+
+    cy.contains('Please log in').should('be.visible');
+  });
+});
+
+// Playwright Component Test with providers
+import { test, expect } from '@playwright/experimental-ct-react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { UserProfile } from './UserProfile';
+import { AuthProvider } from '../contexts/AuthContext';
+
+test.describe('UserProfile Component', () => {
+  test('should display user when authenticated', async ({ mount }) => {
+    const user = { id: 1, name: 'John Doe', email: 'john@example.com' };
+    const queryClient = new QueryClient();
+
+    const component = await mount(
+      <QueryClientProvider client={queryClient}>
+        <AuthProvider initialAuth={{ user, token: 'fake-token' }}>
+          <UserProfile />
+        </AuthProvider>
+      </QueryClientProvider>
+    );
+
+    await expect(component.getByText('John Doe')).toBeVisible();
+    await expect(component.getByText('john@example.com')).toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Create NEW providers per test (QueryClient, Router, Auth)
+- Prevents state pollution between tests
+- `initialAuth` prop allows testing different auth states
+- Custom mount command (`wrappedMount`) reduces boilerplate
+- Providers wrap component, not the entire test suite
+
+### Example 3: Accessibility Assertions
+
+**Context**: When testing components, validate accessibility alongside functionality using axe-core, ARIA roles, labels, and keyboard navigation.
+
+**Implementation**:
+
+```typescript
+// Cypress with axe-core
+// cypress/support/component.tsx
+import 'cypress-axe';
+
+// Form.cy.tsx
+import { Form } from './Form';
+
+describe('Form Component Accessibility', () => {
+  beforeEach(() => {
+    cy.wrappedMount(<Form />);
+    cy.injectAxe(); // Inject axe-core
+  });
+
+  it('should have no accessibility violations', () => {
+    cy.checkA11y(); // Run axe scan
+  });
+
+  it('should have proper ARIA labels', () => {
+    cy.get('input[name="email"]').should('have.attr', 'aria-label', 'Email address');
+    cy.get('input[name="password"]').should('have.attr', 'aria-label', 'Password');
+    cy.get('button[type="submit"]').should('have.attr', 'aria-label', 'Submit form');
+  });
+
+  it('should support keyboard navigation', () => {
+    // Tab through form fields
+    cy.get('input[name="email"]').focus().type('test@example.com');
+    cy.realPress('Tab'); // cypress-real-events plugin
+    cy.focused().should('have.attr', 'name', 'password');
+
+    cy.focused().type('password123');
+    cy.realPress('Tab');
+    cy.focused().should('have.attr', 'type', 'submit');
+
+    cy.realPress('Enter'); // Submit via keyboard
+    cy.contains('Form submitted').should('be.visible');
+  });
+
+  it('should announce errors to screen readers', () => {
+    cy.get('button[type="submit"]').click(); // Submit without data
+
+    // Error has role="alert" and aria-live="polite"
+    cy.get('[role="alert"]')
+      .should('be.visible')
+      .and('have.attr', 'aria-live', 'polite')
+      .and('contain', 'Email is required');
+  });
+
+  it('should have sufficient color contrast', () => {
+    cy.checkA11y(null, {
+      rules: {
+        'color-contrast': { enabled: true }
+      }
+    });
+  });
+});
+
+// Playwright with axe-playwright
+import { test, expect } from '@playwright/experimental-ct-react';
+import AxeBuilder from '@axe-core/playwright';
+import { Form } from './Form';
+
+test.describe('Form Component Accessibility', () => {
+  test('should have no accessibility violations', async ({ mount, page }) => {
+    await mount(<Form />);
+
+    const accessibilityScanResults = await new AxeBuilder({ page })
+      .analyze();
+
+    expect(accessibilityScanResults.violations).toEqual([]);
+  });
+
+  test('should support keyboard navigation', async ({ mount, page }) => {
+    const component = await mount(<Form />);
+
+    await component.getByLabel('Email address').fill('test@example.com');
+    await page.keyboard.press('Tab');
+
+    await expect(component.getByLabel('Password')).toBeFocused();
+
+    await component.getByLabel('Password').fill('password123');
+    await page.keyboard.press('Tab');
+
+    await expect(component.getByRole('button', { name: 'Submit form' })).toBeFocused();
+
+    await page.keyboard.press('Enter');
+    await expect(component.getByText('Form submitted')).toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Use `cy.checkA11y()` (Cypress) or `AxeBuilder` (Playwright) for automated accessibility scanning
+- Validate ARIA roles, labels, and live regions
+- Test keyboard navigation (Tab, Enter, Escape)
+- Ensure errors are announced to screen readers (`role="alert"`, `aria-live`)
+- Check color contrast meets WCAG standards
+
+### Example 4: Visual Regression Test
+
+**Context**: When testing components, capture screenshots to detect unintended visual changes. Use Playwright visual comparison or Cypress snapshot plugins.
+
+**Implementation**:
+
+```typescript
+// Playwright visual regression
+import { test, expect } from '@playwright/experimental-ct-react';
+import { Button } from './Button';
+
+test.describe('Button Visual Regression', () => {
+  test('should match primary button snapshot', async ({ mount }) => {
+    const component = await mount(<Button label="Primary" variant="primary" />);
+
+    // Capture and compare screenshot
+    await expect(component).toHaveScreenshot('button-primary.png');
+  });
+
+  test('should match secondary button snapshot', async ({ mount }) => {
+    const component = await mount(<Button label="Secondary" variant="secondary" />);
+    await expect(component).toHaveScreenshot('button-secondary.png');
+  });
+
+  test('should match disabled button snapshot', async ({ mount }) => {
+    const component = await mount(<Button label="Disabled" disabled={true} />);
+    await expect(component).toHaveScreenshot('button-disabled.png');
+  });
+
+  test('should match loading button snapshot', async ({ mount }) => {
+    const component = await mount(<Button label="Loading" loading={true} />);
+    await expect(component).toHaveScreenshot('button-loading.png');
+  });
+});
+
+// Cypress visual regression with percy or snapshot plugins
+import { Button } from './Button';
+
+describe('Button Visual Regression', () => {
+  it('should match primary button snapshot', () => {
+    cy.wrappedMount(<Button label="Primary" variant="primary" />);
+
+    // Option 1: Percy (cloud-based visual testing)
+    cy.percySnapshot('Button - Primary');
+
+    // Option 2: cypress-plugin-snapshots (local snapshots)
+    cy.get('button').toMatchImageSnapshot({
+      name: 'button-primary',
+      threshold: 0.01 // 1% threshold for pixel differences
+    });
+  });
+
+  it('should match hover state', () => {
+    cy.wrappedMount(<Button label="Hover Me" />);
+    cy.get('button').realHover(); // cypress-real-events
+    cy.percySnapshot('Button - Hover State');
+  });
+
+  it('should match focus state', () => {
+    cy.wrappedMount(<Button label="Focus Me" />);
+    cy.get('button').focus();
+    cy.percySnapshot('Button - Focus State');
+  });
+});
+
+// Playwright configuration for visual regression
+// playwright.config.ts
+export default defineConfig({
+  expect: {
+    toHaveScreenshot: {
+      maxDiffPixels: 100, // Allow 100 pixels difference
+      threshold: 0.2 // 20% threshold
+    }
+  },
+  use: {
+    screenshot: 'only-on-failure'
+  }
+});
+
+// Update snapshots when intentional changes are made
+// npx playwright test --update-snapshots
+```
+
+**Key Points**:
+
+- Playwright: Use `toHaveScreenshot()` for built-in visual comparison
+- Cypress: Use Percy (cloud) or snapshot plugins (local) for visual testing
+- Capture different states: default, hover, focus, disabled, loading
+- Set threshold for acceptable pixel differences (avoid false positives)
+- Update snapshots when visual changes are intentional
+- Visual tests catch unintended CSS/layout regressions
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (component test generation), `*automate` (component test expansion), `*framework` (component testing setup)
+- **Related fragments**:
+  - `test-quality.md` - Keep component tests <100 lines, isolated, focused
+  - `fixture-architecture.md` - Provider wrapping patterns, custom mount commands
+  - `data-factories.md` - Factory functions for component props
+  - `test-levels-framework.md` - When to use component tests vs E2E tests
+
+## TDD Workflow Summary
+
+**Red-Green-Refactor Cycle**:
+
+1. **Red**: Write failing test describing desired behavior
+2. **Green**: Implement minimal code to make test pass
+3. **Refactor**: Improve code quality, tests stay green
+4. **Repeat**: Each new feature starts with failing test
+
+**Component Test Checklist**:
+
+- [ ] Test renders with required props
+- [ ] Test user interactions (click, type, submit)
+- [ ] Test different states (loading, error, disabled)
+- [ ] Test accessibility (ARIA, keyboard navigation)
+- [ ] Test visual regression (snapshots)
+- [ ] Isolate with fresh providers (no state bleed)
+- [ ] Keep tests <100 lines (split by intent)
+
+_Source: CCTDD repository, Murat component testing talks, Playwright/Cypress component testing docs._

_bmad/bmm/testarch/knowledge/contract-testing.md

@@ -0,0 +1,957 @@
+# Contract Testing Essentials (Pact)
+
+## Principle
+
+Contract testing validates API contracts between consumer and provider services without requiring integrated end-to-end tests. Store consumer contracts alongside integration specs, version contracts semantically, and publish on every CI run. Provider verification before merge surfaces breaking changes immediately, while explicit fallback behavior (timeouts, retries, error payloads) captures resilience guarantees in contracts.
+
+## Rationale
+
+Traditional integration testing requires running both consumer and provider simultaneously, creating slow, flaky tests with complex setup. Contract testing decouples services: consumers define expectations (pact files), providers verify against those expectations independently. This enables parallel development, catches breaking changes early, and documents API behavior as executable specifications. Pair contract tests with API smoke tests to validate data mapping and UI rendering in tandem.
+
+## Pattern Examples
+
+### Example 1: Pact Consumer Test (Frontend → Backend API)
+
+**Context**: React application consuming a user management API, defining expected interactions.
+
+**Implementation**:
+
+```typescript
+// tests/contract/user-api.pact.spec.ts
+import { PactV3, MatchersV3 } from '@pact-foundation/pact';
+import { getUserById, createUser, User } from '@/api/user-service';
+
+const { like, eachLike, string, integer } = MatchersV3;
+
+/**
+ * Consumer-Driven Contract Test
+ * - Consumer (React app) defines expected API behavior
+ * - Generates pact file for provider to verify
+ * - Runs in isolation (no real backend required)
+ */
+
+const provider = new PactV3({
+  consumer: 'user-management-web',
+  provider: 'user-api-service',
+  dir: './pacts', // Output directory for pact files
+  logLevel: 'warn',
+});
+
+describe('User API Contract', () => {
+  describe('GET /users/:id', () => {
+    it('should return user when user exists', async () => {
+      // Arrange: Define expected interaction
+      await provider
+        .given('user with id 1 exists') // Provider state
+        .uponReceiving('a request for user 1')
+        .withRequest({
+          method: 'GET',
+          path: '/users/1',
+          headers: {
+            Accept: 'application/json',
+            Authorization: like('Bearer token123'), // Matcher: any string
+          },
+        })
+        .willRespondWith({
+          status: 200,
+          headers: {
+            'Content-Type': 'application/json',
+          },
+          body: like({
+            id: integer(1),
+            name: string('John Doe'),
+            email: string('john@example.com'),
+            role: string('user'),
+            createdAt: string('2025-01-15T10:00:00Z'),
+          }),
+        })
+        .executeTest(async (mockServer) => {
+          // Act: Call consumer code against mock server
+          const user = await getUserById(1, {
+            baseURL: mockServer.url,
+            headers: { Authorization: 'Bearer token123' },
+          });
+
+          // Assert: Validate consumer behavior
+          expect(user).toEqual(
+            expect.objectContaining({
+              id: 1,
+              name: 'John Doe',
+              email: 'john@example.com',
+              role: 'user',
+            }),
+          );
+        });
+    });
+
+    it('should handle 404 when user does not exist', async () => {
+      await provider
+        .given('user with id 999 does not exist')
+        .uponReceiving('a request for non-existent user')
+        .withRequest({
+          method: 'GET',
+          path: '/users/999',
+          headers: { Accept: 'application/json' },
+        })
+        .willRespondWith({
+          status: 404,
+          headers: { 'Content-Type': 'application/json' },
+          body: {
+            error: 'User not found',
+            code: 'USER_NOT_FOUND',
+          },
+        })
+        .executeTest(async (mockServer) => {
+          // Act & Assert: Consumer handles 404 gracefully
+          await expect(getUserById(999, { baseURL: mockServer.url })).rejects.toThrow('User not found');
+        });
+    });
+  });
+
+  describe('POST /users', () => {
+    it('should create user and return 201', async () => {
+      const newUser: Omit<User, 'id' | 'createdAt'> = {
+        name: 'Jane Smith',
+        email: 'jane@example.com',
+        role: 'admin',
+      };
+
+      await provider
+        .given('no users exist')
+        .uponReceiving('a request to create a user')
+        .withRequest({
+          method: 'POST',
+          path: '/users',
+          headers: {
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+          },
+          body: like(newUser),
+        })
+        .willRespondWith({
+          status: 201,
+          headers: { 'Content-Type': 'application/json' },
+          body: like({
+            id: integer(2),
+            name: string('Jane Smith'),
+            email: string('jane@example.com'),
+            role: string('admin'),
+            createdAt: string('2025-01-15T11:00:00Z'),
+          }),
+        })
+        .executeTest(async (mockServer) => {
+          const createdUser = await createUser(newUser, {
+            baseURL: mockServer.url,
+          });
+
+          expect(createdUser).toEqual(
+            expect.objectContaining({
+              id: expect.any(Number),
+              name: 'Jane Smith',
+              email: 'jane@example.com',
+              role: 'admin',
+            }),
+          );
+        });
+    });
+  });
+});
+```
+
+**package.json scripts**:
+
+```json
+{
+  "scripts": {
+    "test:contract": "jest tests/contract --testTimeout=30000",
+    "pact:publish": "pact-broker publish ./pacts --consumer-app-version=$GIT_SHA --broker-base-url=$PACT_BROKER_URL --broker-token=$PACT_BROKER_TOKEN"
+  }
+}
+```
+
+**Key Points**:
+
+- **Consumer-driven**: Frontend defines expectations, not backend
+- **Matchers**: `like`, `string`, `integer` for flexible matching
+- **Provider states**: given() sets up test preconditions
+- **Isolation**: No real backend needed, runs fast
+- **Pact generation**: Automatically creates JSON pact files
+
+---
+
+### Example 2: Pact Provider Verification (Backend validates contracts)
+
+**Context**: Node.js/Express API verifying pacts published by consumers.
+
+**Implementation**:
+
+```typescript
+// tests/contract/user-api.provider.spec.ts
+import { Verifier, VerifierOptions } from '@pact-foundation/pact';
+import { server } from '../../src/server'; // Your Express/Fastify app
+import { seedDatabase, resetDatabase } from '../support/db-helpers';
+
+/**
+ * Provider Verification Test
+ * - Provider (backend API) verifies against published pacts
+ * - State handlers setup test data for each interaction
+ * - Runs before merge to catch breaking changes
+ */
+
+describe('Pact Provider Verification', () => {
+  let serverInstance;
+  const PORT = 3001;
+
+  beforeAll(async () => {
+    // Start provider server
+    serverInstance = server.listen(PORT);
+    console.log(`Provider server running on port ${PORT}`);
+  });
+
+  afterAll(async () => {
+    // Cleanup
+    await serverInstance.close();
+  });
+
+  it('should verify pacts from all consumers', async () => {
+    const opts: VerifierOptions = {
+      // Provider details
+      provider: 'user-api-service',
+      providerBaseUrl: `http://localhost:${PORT}`,
+
+      // Pact Broker configuration
+      pactBrokerUrl: process.env.PACT_BROKER_URL,
+      pactBrokerToken: process.env.PACT_BROKER_TOKEN,
+      publishVerificationResult: process.env.CI === 'true',
+      providerVersion: process.env.GIT_SHA || 'dev',
+
+      // State handlers: Setup provider state for each interaction
+      stateHandlers: {
+        'user with id 1 exists': async () => {
+          await seedDatabase({
+            users: [
+              {
+                id: 1,
+                name: 'John Doe',
+                email: 'john@example.com',
+                role: 'user',
+                createdAt: '2025-01-15T10:00:00Z',
+              },
+            ],
+          });
+          return 'User seeded successfully';
+        },
+
+        'user with id 999 does not exist': async () => {
+          // Ensure user doesn't exist
+          await resetDatabase();
+          return 'Database reset';
+        },
+
+        'no users exist': async () => {
+          await resetDatabase();
+          return 'Database empty';
+        },
+      },
+
+      // Request filters: Add auth headers to all requests
+      requestFilter: (req, res, next) => {
+        // Mock authentication for verification
+        req.headers['x-user-id'] = 'test-user';
+        req.headers['authorization'] = 'Bearer valid-test-token';
+        next();
+      },
+
+      // Timeout for verification
+      timeout: 30000,
+    };
+
+    // Run verification
+    await new Verifier(opts).verifyProvider();
+  });
+});
+```
+
+**CI integration**:
+
+```yaml
+# .github/workflows/pact-provider.yml
+name: Pact Provider Verification
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  verify-contracts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Start database
+        run: docker-compose up -d postgres
+
+      - name: Run migrations
+        run: npm run db:migrate
+
+      - name: Verify pacts
+        run: npm run test:contract:provider
+        env:
+          PACT_BROKER_URL: ${{ secrets.PACT_BROKER_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+          GIT_SHA: ${{ github.sha }}
+          CI: true
+
+      - name: Can I Deploy?
+        run: |
+          npx pact-broker can-i-deploy \
+            --pacticipant user-api-service \
+            --version ${{ github.sha }} \
+            --to-environment production
+        env:
+          PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+```
+
+**Key Points**:
+
+- **State handlers**: Setup provider data for each given() state
+- **Request filters**: Add auth/headers for verification requests
+- **CI publishing**: Verification results sent to broker
+- **can-i-deploy**: Safety check before production deployment
+- **Database isolation**: Reset between state handlers
+
+---
+
+### Example 3: Contract CI Integration (Consumer & Provider Workflow)
+
+**Context**: Complete CI/CD workflow coordinating consumer pact publishing and provider verification.
+
+**Implementation**:
+
+```yaml
+# .github/workflows/pact-consumer.yml (Consumer side)
+name: Pact Consumer Tests
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  consumer-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run consumer contract tests
+        run: npm run test:contract
+
+      - name: Publish pacts to broker
+        if: github.ref == 'refs/heads/main' || github.event_name == 'pull_request'
+        run: |
+          npx pact-broker publish ./pacts \
+            --consumer-app-version ${{ github.sha }} \
+            --branch ${{ github.head_ref || github.ref_name }} \
+            --broker-base-url ${{ secrets.PACT_BROKER_URL }} \
+            --broker-token ${{ secrets.PACT_BROKER_TOKEN }}
+
+      - name: Tag pact with environment (main branch only)
+        if: github.ref == 'refs/heads/main'
+        run: |
+          npx pact-broker create-version-tag \
+            --pacticipant user-management-web \
+            --version ${{ github.sha }} \
+            --tag production \
+            --broker-base-url ${{ secrets.PACT_BROKER_URL }} \
+            --broker-token ${{ secrets.PACT_BROKER_TOKEN }}
+```
+
+```yaml
+# .github/workflows/pact-provider.yml (Provider side)
+name: Pact Provider Verification
+on:
+  pull_request:
+  push:
+    branches: [main]
+  repository_dispatch:
+    types: [pact_changed] # Webhook from Pact Broker
+
+jobs:
+  verify-contracts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Start dependencies
+        run: docker-compose up -d
+
+      - name: Run provider verification
+        run: npm run test:contract:provider
+        env:
+          PACT_BROKER_URL: ${{ secrets.PACT_BROKER_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+          GIT_SHA: ${{ github.sha }}
+          CI: true
+
+      - name: Publish verification results
+        if: always()
+        run: echo "Verification results published to broker"
+
+      - name: Can I Deploy to Production?
+        if: github.ref == 'refs/heads/main'
+        run: |
+          npx pact-broker can-i-deploy \
+            --pacticipant user-api-service \
+            --version ${{ github.sha }} \
+            --to-environment production \
+            --broker-base-url ${{ secrets.PACT_BROKER_URL }} \
+            --broker-token ${{ secrets.PACT_BROKER_TOKEN }} \
+            --retry-while-unknown 6 \
+            --retry-interval 10
+
+      - name: Record deployment (if can-i-deploy passed)
+        if: success() && github.ref == 'refs/heads/main'
+        run: |
+          npx pact-broker record-deployment \
+            --pacticipant user-api-service \
+            --version ${{ github.sha }} \
+            --environment production \
+            --broker-base-url ${{ secrets.PACT_BROKER_URL }} \
+            --broker-token ${{ secrets.PACT_BROKER_TOKEN }}
+```
+
+**Pact Broker Webhook Configuration**:
+
+```json
+{
+  "events": [
+    {
+      "name": "contract_content_changed"
+    }
+  ],
+  "request": {
+    "method": "POST",
+    "url": "https://api.github.com/repos/your-org/user-api/dispatches",
+    "headers": {
+      "Authorization": "Bearer ${user.githubToken}",
+      "Content-Type": "application/json",
+      "Accept": "application/vnd.github.v3+json"
+    },
+    "body": {
+      "event_type": "pact_changed",
+      "client_payload": {
+        "pact_url": "${pactbroker.pactUrl}",
+        "consumer": "${pactbroker.consumerName}",
+        "provider": "${pactbroker.providerName}"
+      }
+    }
+  }
+}
+```
+
+**Key Points**:
+
+- **Automatic trigger**: Consumer pact changes trigger provider verification via webhook
+- **Branch tracking**: Pacts published per branch for feature testing
+- **can-i-deploy**: Safety gate before production deployment
+- **Record deployment**: Track which version is in each environment
+- **Parallel dev**: Consumer and provider teams work independently
+
+---
+
+### Example 4: Resilience Coverage (Testing Fallback Behavior)
+
+**Context**: Capture timeout, retry, and error handling behavior explicitly in contracts.
+
+**Implementation**:
+
+```typescript
+// tests/contract/user-api-resilience.pact.spec.ts
+import { PactV3, MatchersV3 } from '@pact-foundation/pact';
+import { getUserById, ApiError } from '@/api/user-service';
+
+const { like, string } = MatchersV3;
+
+const provider = new PactV3({
+  consumer: 'user-management-web',
+  provider: 'user-api-service',
+  dir: './pacts',
+});
+
+describe('User API Resilience Contract', () => {
+  /**
+   * Test 500 error handling
+   * Verifies consumer handles server errors gracefully
+   */
+  it('should handle 500 errors with retry logic', async () => {
+    await provider
+      .given('server is experiencing errors')
+      .uponReceiving('a request that returns 500')
+      .withRequest({
+        method: 'GET',
+        path: '/users/1',
+        headers: { Accept: 'application/json' },
+      })
+      .willRespondWith({
+        status: 500,
+        headers: { 'Content-Type': 'application/json' },
+        body: {
+          error: 'Internal server error',
+          code: 'INTERNAL_ERROR',
+          retryable: true,
+        },
+      })
+      .executeTest(async (mockServer) => {
+        // Consumer should retry on 500
+        try {
+          await getUserById(1, {
+            baseURL: mockServer.url,
+            retries: 3,
+            retryDelay: 100,
+          });
+          fail('Should have thrown error after retries');
+        } catch (error) {
+          expect(error).toBeInstanceOf(ApiError);
+          expect((error as ApiError).code).toBe('INTERNAL_ERROR');
+          expect((error as ApiError).retryable).toBe(true);
+        }
+      });
+  });
+
+  /**
+   * Test 429 rate limiting
+   * Verifies consumer respects rate limits
+   */
+  it('should handle 429 rate limit with backoff', async () => {
+    await provider
+      .given('rate limit exceeded for user')
+      .uponReceiving('a request that is rate limited')
+      .withRequest({
+        method: 'GET',
+        path: '/users/1',
+      })
+      .willRespondWith({
+        status: 429,
+        headers: {
+          'Content-Type': 'application/json',
+          'Retry-After': '60', // Retry after 60 seconds
+        },
+        body: {
+          error: 'Too many requests',
+          code: 'RATE_LIMIT_EXCEEDED',
+        },
+      })
+      .executeTest(async (mockServer) => {
+        try {
+          await getUserById(1, {
+            baseURL: mockServer.url,
+            respectRateLimit: true,
+          });
+          fail('Should have thrown rate limit error');
+        } catch (error) {
+          expect(error).toBeInstanceOf(ApiError);
+          expect((error as ApiError).code).toBe('RATE_LIMIT_EXCEEDED');
+          expect((error as ApiError).retryAfter).toBe(60);
+        }
+      });
+  });
+
+  /**
+   * Test timeout handling
+   * Verifies consumer has appropriate timeout configuration
+   */
+  it('should timeout after 10 seconds', async () => {
+    await provider
+      .given('server is slow to respond')
+      .uponReceiving('a request that times out')
+      .withRequest({
+        method: 'GET',
+        path: '/users/1',
+      })
+      .willRespondWith({
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+        body: like({ id: 1, name: 'John' }),
+      })
+      .withDelay(15000) // Simulate 15 second delay
+      .executeTest(async (mockServer) => {
+        try {
+          await getUserById(1, {
+            baseURL: mockServer.url,
+            timeout: 10000, // 10 second timeout
+          });
+          fail('Should have timed out');
+        } catch (error) {
+          expect(error).toBeInstanceOf(ApiError);
+          expect((error as ApiError).code).toBe('TIMEOUT');
+        }
+      });
+  });
+
+  /**
+   * Test partial response (optional fields)
+   * Verifies consumer handles missing optional data
+   */
+  it('should handle response with missing optional fields', async () => {
+    await provider
+      .given('user exists with minimal data')
+      .uponReceiving('a request for user with partial data')
+      .withRequest({
+        method: 'GET',
+        path: '/users/1',
+      })
+      .willRespondWith({
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+        body: {
+          id: integer(1),
+          name: string('John Doe'),
+          email: string('john@example.com'),
+          // role, createdAt, etc. omitted (optional fields)
+        },
+      })
+      .executeTest(async (mockServer) => {
+        const user = await getUserById(1, { baseURL: mockServer.url });
+
+        // Consumer handles missing optional fields gracefully
+        expect(user.id).toBe(1);
+        expect(user.name).toBe('John Doe');
+        expect(user.role).toBeUndefined(); // Optional field
+        expect(user.createdAt).toBeUndefined(); // Optional field
+      });
+  });
+});
+```
+
+**API client with retry logic**:
+
+```typescript
+// src/api/user-service.ts
+import axios, { AxiosInstance, AxiosRequestConfig } from 'axios';
+
+export class ApiError extends Error {
+  constructor(
+    message: string,
+    public code: string,
+    public retryable: boolean = false,
+    public retryAfter?: number,
+  ) {
+    super(message);
+  }
+}
+
+/**
+ * User API client with retry and error handling
+ */
+export async function getUserById(
+  id: number,
+  config?: AxiosRequestConfig & { retries?: number; retryDelay?: number; respectRateLimit?: boolean },
+): Promise<User> {
+  const { retries = 3, retryDelay = 1000, respectRateLimit = true, ...axiosConfig } = config || {};
+
+  let lastError: Error;
+
+  for (let attempt = 1; attempt <= retries; attempt++) {
+    try {
+      const response = await axios.get(`/users/${id}`, axiosConfig);
+      return response.data;
+    } catch (error: any) {
+      lastError = error;
+
+      // Handle rate limiting
+      if (error.response?.status === 429) {
+        const retryAfter = parseInt(error.response.headers['retry-after'] || '60');
+        throw new ApiError('Too many requests', 'RATE_LIMIT_EXCEEDED', false, retryAfter);
+      }
+
+      // Retry on 500 errors
+      if (error.response?.status === 500 && attempt < retries) {
+        await new Promise((resolve) => setTimeout(resolve, retryDelay * attempt));
+        continue;
+      }
+
+      // Handle 404
+      if (error.response?.status === 404) {
+        throw new ApiError('User not found', 'USER_NOT_FOUND', false);
+      }
+
+      // Handle timeout
+      if (error.code === 'ECONNABORTED') {
+        throw new ApiError('Request timeout', 'TIMEOUT', true);
+      }
+
+      break;
+    }
+  }
+
+  throw new ApiError('Request failed after retries', 'INTERNAL_ERROR', true);
+}
+```
+
+**Key Points**:
+
+- **Resilience contracts**: Timeouts, retries, errors explicitly tested
+- **State handlers**: Provider sets up each test scenario
+- **Error handling**: Consumer validates graceful degradation
+- **Retry logic**: Exponential backoff tested
+- **Optional fields**: Consumer handles partial responses
+
+---
+
+### Example 4: Pact Broker Housekeeping & Lifecycle Management
+
+**Context**: Automated broker maintenance to prevent contract sprawl and noise.
+
+**Implementation**:
+
+```typescript
+// scripts/pact-broker-housekeeping.ts
+/**
+ * Pact Broker Housekeeping Script
+ * - Archive superseded contracts
+ * - Expire unused pacts
+ * - Tag releases for environment tracking
+ */
+
+import { execSync } from 'child_process';
+
+const PACT_BROKER_URL = process.env.PACT_BROKER_URL!;
+const PACT_BROKER_TOKEN = process.env.PACT_BROKER_TOKEN!;
+const PACTICIPANT = 'user-api-service';
+
+/**
+ * Tag release with environment
+ */
+function tagRelease(version: string, environment: 'staging' | 'production') {
+  console.log(`🏷️  Tagging ${PACTICIPANT} v${version} as ${environment}`);
+
+  execSync(
+    `npx pact-broker create-version-tag \
+      --pacticipant ${PACTICIPANT} \
+      --version ${version} \
+      --tag ${environment} \
+      --broker-base-url ${PACT_BROKER_URL} \
+      --broker-token ${PACT_BROKER_TOKEN}`,
+    { stdio: 'inherit' },
+  );
+}
+
+/**
+ * Record deployment to environment
+ */
+function recordDeployment(version: string, environment: 'staging' | 'production') {
+  console.log(`📝 Recording deployment of ${PACTICIPANT} v${version} to ${environment}`);
+
+  execSync(
+    `npx pact-broker record-deployment \
+      --pacticipant ${PACTICIPANT} \
+      --version ${version} \
+      --environment ${environment} \
+      --broker-base-url ${PACT_BROKER_URL} \
+      --broker-token ${PACT_BROKER_TOKEN}`,
+    { stdio: 'inherit' },
+  );
+}
+
+/**
+ * Clean up old pact versions (retention policy)
+ * Keep: last 30 days, all production tags, latest from each branch
+ */
+function cleanupOldPacts() {
+  console.log(`🧹 Cleaning up old pacts for ${PACTICIPANT}`);
+
+  execSync(
+    `npx pact-broker clean \
+      --pacticipant ${PACTICIPANT} \
+      --broker-base-url ${PACT_BROKER_URL} \
+      --broker-token ${PACT_BROKER_TOKEN} \
+      --keep-latest-for-branch 1 \
+      --keep-min-age 30`,
+    { stdio: 'inherit' },
+  );
+}
+
+/**
+ * Check deployment compatibility
+ */
+function canIDeploy(version: string, toEnvironment: string): boolean {
+  console.log(`🔍 Checking if ${PACTICIPANT} v${version} can deploy to ${toEnvironment}`);
+
+  try {
+    execSync(
+      `npx pact-broker can-i-deploy \
+        --pacticipant ${PACTICIPANT} \
+        --version ${version} \
+        --to-environment ${toEnvironment} \
+        --broker-base-url ${PACT_BROKER_URL} \
+        --broker-token ${PACT_BROKER_TOKEN} \
+        --retry-while-unknown 6 \
+        --retry-interval 10`,
+      { stdio: 'inherit' },
+    );
+    return true;
+  } catch (error) {
+    console.error(`❌ Cannot deploy to ${toEnvironment}`);
+    return false;
+  }
+}
+
+/**
+ * Main housekeeping workflow
+ */
+async function main() {
+  const command = process.argv[2];
+  const version = process.argv[3];
+  const environment = process.argv[4] as 'staging' | 'production';
+
+  switch (command) {
+    case 'tag-release':
+      tagRelease(version, environment);
+      break;
+
+    case 'record-deployment':
+      recordDeployment(version, environment);
+      break;
+
+    case 'can-i-deploy':
+      const canDeploy = canIDeploy(version, environment);
+      process.exit(canDeploy ? 0 : 1);
+
+    case 'cleanup':
+      cleanupOldPacts();
+      break;
+
+    default:
+      console.error('Unknown command. Use: tag-release | record-deployment | can-i-deploy | cleanup');
+      process.exit(1);
+  }
+}
+
+main();
+```
+
+**package.json scripts**:
+
+```json
+{
+  "scripts": {
+    "pact:tag": "ts-node scripts/pact-broker-housekeeping.ts tag-release",
+    "pact:record": "ts-node scripts/pact-broker-housekeeping.ts record-deployment",
+    "pact:can-deploy": "ts-node scripts/pact-broker-housekeeping.ts can-i-deploy",
+    "pact:cleanup": "ts-node scripts/pact-broker-housekeeping.ts cleanup"
+  }
+}
+```
+
+**Deployment workflow integration**:
+
+```yaml
+# .github/workflows/deploy-production.yml
+name: Deploy to Production
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  verify-contracts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Check pact compatibility
+        run: npm run pact:can-deploy ${{ github.ref_name }} production
+        env:
+          PACT_BROKER_URL: ${{ secrets.PACT_BROKER_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+
+  deploy:
+    needs: verify-contracts
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to production
+        run: ./scripts/deploy.sh production
+
+      - name: Record deployment in Pact Broker
+        run: npm run pact:record ${{ github.ref_name }} production
+        env:
+          PACT_BROKER_URL: ${{ secrets.PACT_BROKER_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+```
+
+**Scheduled cleanup**:
+
+```yaml
+# .github/workflows/pact-housekeeping.yml
+name: Pact Broker Housekeeping
+on:
+  schedule:
+    - cron: '0 2 * * 0' # Weekly on Sunday at 2 AM
+
+jobs:
+  cleanup:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Cleanup old pacts
+        run: npm run pact:cleanup
+        env:
+          PACT_BROKER_URL: ${{ secrets.PACT_BROKER_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+```
+
+**Key Points**:
+
+- **Automated tagging**: Releases tagged with environment
+- **Deployment tracking**: Broker knows which version is where
+- **Safety gate**: can-i-deploy blocks incompatible deployments
+- **Retention policy**: Keep recent, production, and branch-latest pacts
+- **Webhook triggers**: Provider verification runs on consumer changes
+
+---
+
+## Contract Testing Checklist
+
+Before implementing contract testing, verify:
+
+- [ ] **Pact Broker setup**: Hosted (Pactflow) or self-hosted broker configured
+- [ ] **Consumer tests**: Generate pacts in CI, publish to broker on merge
+- [ ] **Provider verification**: Runs on PR, verifies all consumer pacts
+- [ ] **State handlers**: Provider implements all given() states
+- [ ] **can-i-deploy**: Blocks deployment if contracts incompatible
+- [ ] **Webhooks configured**: Consumer changes trigger provider verification
+- [ ] **Retention policy**: Old pacts archived (keep 30 days, all production tags)
+- [ ] **Resilience tested**: Timeouts, retries, error codes in contracts
+
+## Integration Points
+
+- Used in workflows: `*automate` (integration test generation), `*ci` (contract CI setup)
+- Related fragments: `test-levels-framework.md`, `ci-burn-in.md`
+- Tools: Pact.js, Pact Broker (Pactflow or self-hosted), Pact CLI
+
+_Source: Pact consumer/provider sample repos, Murat contract testing blog, Pact official documentation_

_bmad/bmm/testarch/knowledge/data-factories.md

@@ -0,0 +1,500 @@
+# Data Factories and API-First Setup
+
+## Principle
+
+Prefer factory functions that accept overrides and return complete objects (`createUser(overrides)`). Seed test state through APIs, tasks, or direct DB helpers before visiting the UI—never via slow UI interactions. UI is for validation only, not setup.
+
+## Rationale
+
+Static fixtures (JSON files, hardcoded objects) create brittle tests that:
+
+- Fail when schemas evolve (missing new required fields)
+- Cause collisions in parallel execution (same user IDs)
+- Hide test intent (what matters for _this_ test?)
+
+Dynamic factories with overrides provide:
+
+- **Parallel safety**: UUIDs and timestamps prevent collisions
+- **Schema evolution**: Defaults adapt to schema changes automatically
+- **Explicit intent**: Overrides show what matters for each test
+- **Speed**: API setup is 10-50x faster than UI
+
+## Pattern Examples
+
+### Example 1: Factory Function with Overrides
+
+**Context**: When creating test data, build factory functions with sensible defaults and explicit overrides. Use `faker` for dynamic values that prevent collisions.
+
+**Implementation**:
+
+```typescript
+// test-utils/factories/user-factory.ts
+import { faker } from '@faker-js/faker';
+
+type User = {
+  id: string;
+  email: string;
+  name: string;
+  role: 'user' | 'admin' | 'moderator';
+  createdAt: Date;
+  isActive: boolean;
+};
+
+export const createUser = (overrides: Partial<User> = {}): User => ({
+  id: faker.string.uuid(),
+  email: faker.internet.email(),
+  name: faker.person.fullName(),
+  role: 'user',
+  createdAt: new Date(),
+  isActive: true,
+  ...overrides,
+});
+
+// test-utils/factories/product-factory.ts
+type Product = {
+  id: string;
+  name: string;
+  price: number;
+  stock: number;
+  category: string;
+};
+
+export const createProduct = (overrides: Partial<Product> = {}): Product => ({
+  id: faker.string.uuid(),
+  name: faker.commerce.productName(),
+  price: parseFloat(faker.commerce.price()),
+  stock: faker.number.int({ min: 0, max: 100 }),
+  category: faker.commerce.department(),
+  ...overrides,
+});
+
+// Usage in tests:
+test('admin can delete users', async ({ page, apiRequest }) => {
+  // Default user
+  const user = createUser();
+
+  // Admin user (explicit override shows intent)
+  const admin = createUser({ role: 'admin' });
+
+  // Seed via API (fast!)
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+  await apiRequest({ method: 'POST', url: '/api/users', data: admin });
+
+  // Now test UI behavior
+  await page.goto('/admin/users');
+  await page.click(`[data-testid="delete-user-${user.id}"]`);
+  await expect(page.getByText(`User ${user.name} deleted`)).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- `Partial<User>` allows overriding any field without breaking type safety
+- Faker generates unique values—no collisions in parallel tests
+- Override shows test intent: `createUser({ role: 'admin' })` is explicit
+- Factory lives in `test-utils/factories/` for easy reuse
+
+### Example 2: Nested Factory Pattern
+
+**Context**: When testing relationships (orders with users and products), nest factories to create complete object graphs. Control relationship data explicitly.
+
+**Implementation**:
+
+```typescript
+// test-utils/factories/order-factory.ts
+import { createUser } from './user-factory';
+import { createProduct } from './product-factory';
+
+type OrderItem = {
+  product: Product;
+  quantity: number;
+  price: number;
+};
+
+type Order = {
+  id: string;
+  user: User;
+  items: OrderItem[];
+  total: number;
+  status: 'pending' | 'paid' | 'shipped' | 'delivered';
+  createdAt: Date;
+};
+
+export const createOrderItem = (overrides: Partial<OrderItem> = {}): OrderItem => {
+  const product = overrides.product || createProduct();
+  const quantity = overrides.quantity || faker.number.int({ min: 1, max: 5 });
+
+  return {
+    product,
+    quantity,
+    price: product.price * quantity,
+    ...overrides,
+  };
+};
+
+export const createOrder = (overrides: Partial<Order> = {}): Order => {
+  const items = overrides.items || [createOrderItem(), createOrderItem()];
+  const total = items.reduce((sum, item) => sum + item.price, 0);
+
+  return {
+    id: faker.string.uuid(),
+    user: overrides.user || createUser(),
+    items,
+    total,
+    status: 'pending',
+    createdAt: new Date(),
+    ...overrides,
+  };
+};
+
+// Usage in tests:
+test('user can view order details', async ({ page, apiRequest }) => {
+  const user = createUser({ email: 'test@example.com' });
+  const product1 = createProduct({ name: 'Widget A', price: 10.0 });
+  const product2 = createProduct({ name: 'Widget B', price: 15.0 });
+
+  // Explicit relationships
+  const order = createOrder({
+    user,
+    items: [
+      createOrderItem({ product: product1, quantity: 2 }), // $20
+      createOrderItem({ product: product2, quantity: 1 }), // $15
+    ],
+  });
+
+  // Seed via API
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+  await apiRequest({ method: 'POST', url: '/api/products', data: product1 });
+  await apiRequest({ method: 'POST', url: '/api/products', data: product2 });
+  await apiRequest({ method: 'POST', url: '/api/orders', data: order });
+
+  // Test UI
+  await page.goto(`/orders/${order.id}`);
+  await expect(page.getByText('Widget A x 2')).toBeVisible();
+  await expect(page.getByText('Widget B x 1')).toBeVisible();
+  await expect(page.getByText('Total: $35.00')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Nested factories handle relationships (order → user, order → products)
+- Overrides cascade: provide custom user/products or use defaults
+- Calculated fields (total) derived automatically from nested data
+- Explicit relationships make test data clear and maintainable
+
+### Example 3: Factory with API Seeding
+
+**Context**: When tests need data setup, always use API calls or database tasks—never UI navigation. Wrap factory usage with seeding utilities for clean test setup.
+
+**Implementation**:
+
+```typescript
+// playwright/support/helpers/seed-helpers.ts
+import { APIRequestContext } from '@playwright/test';
+import { User, createUser } from '../../test-utils/factories/user-factory';
+import { Product, createProduct } from '../../test-utils/factories/product-factory';
+
+export async function seedUser(request: APIRequestContext, overrides: Partial<User> = {}): Promise<User> {
+  const user = createUser(overrides);
+
+  const response = await request.post('/api/users', {
+    data: user,
+  });
+
+  if (!response.ok()) {
+    throw new Error(`Failed to seed user: ${response.status()}`);
+  }
+
+  return user;
+}
+
+export async function seedProduct(request: APIRequestContext, overrides: Partial<Product> = {}): Promise<Product> {
+  const product = createProduct(overrides);
+
+  const response = await request.post('/api/products', {
+    data: product,
+  });
+
+  if (!response.ok()) {
+    throw new Error(`Failed to seed product: ${response.status()}`);
+  }
+
+  return product;
+}
+
+// Playwright globalSetup for shared data
+// playwright/support/global-setup.ts
+import { chromium, FullConfig } from '@playwright/test';
+import { seedUser } from './helpers/seed-helpers';
+
+async function globalSetup(config: FullConfig) {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+  const context = page.context();
+
+  // Seed admin user for all tests
+  const admin = await seedUser(context.request, {
+    email: 'admin@example.com',
+    role: 'admin',
+  });
+
+  // Save auth state for reuse
+  await context.storageState({ path: 'playwright/.auth/admin.json' });
+
+  await browser.close();
+}
+
+export default globalSetup;
+
+// Cypress equivalent with cy.task
+// cypress/support/tasks.ts
+export const seedDatabase = async (entity: string, data: unknown) => {
+  // Direct database insert or API call
+  if (entity === 'users') {
+    await db.users.create(data);
+  }
+  return null;
+};
+
+// Usage in Cypress tests:
+beforeEach(() => {
+  const user = createUser({ email: 'test@example.com' });
+  cy.task('db:seed', { entity: 'users', data: user });
+});
+```
+
+**Key Points**:
+
+- API seeding is 10-50x faster than UI-based setup
+- `globalSetup` seeds shared data once (e.g., admin user)
+- Per-test seeding uses `seedUser()` helpers for isolation
+- Cypress `cy.task` allows direct database access for speed
+
+### Example 4: Anti-Pattern - Hardcoded Test Data
+
+**Problem**:
+
+```typescript
+// ❌ BAD: Hardcoded test data
+test('user can login', async ({ page }) => {
+  await page.goto('/login');
+  await page.fill('[data-testid="email"]', 'test@test.com'); // Hardcoded
+  await page.fill('[data-testid="password"]', 'password123'); // Hardcoded
+  await page.click('[data-testid="submit"]');
+
+  // What if this user already exists? Test fails in parallel runs.
+  // What if schema adds required fields? Test breaks.
+});
+
+// ❌ BAD: Static JSON fixtures
+// fixtures/users.json
+{
+  "users": [
+    { "id": 1, "email": "user1@test.com", "name": "User 1" },
+    { "id": 2, "email": "user2@test.com", "name": "User 2" }
+  ]
+}
+
+test('admin can delete user', async ({ page }) => {
+  const users = require('../fixtures/users.json');
+  // Brittle: IDs collide in parallel, schema drift breaks tests
+});
+```
+
+**Why It Fails**:
+
+- **Parallel collisions**: Hardcoded IDs (`id: 1`, `email: 'test@test.com'`) cause failures when tests run concurrently
+- **Schema drift**: Adding required fields (`phoneNumber`, `address`) breaks all tests using fixtures
+- **Hidden intent**: Does this test need `email: 'test@test.com'` specifically, or any email?
+- **Slow setup**: UI-based data creation is 10-50x slower than API
+
+**Better Approach**: Use factories
+
+```typescript
+// ✅ GOOD: Factory-based data
+test('user can login', async ({ page, apiRequest }) => {
+  const user = createUser({ email: 'unique@example.com', password: 'secure123' });
+
+  // Seed via API (fast, parallel-safe)
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+
+  // Test UI
+  await page.goto('/login');
+  await page.fill('[data-testid="email"]', user.email);
+  await page.fill('[data-testid="password"]', user.password);
+  await page.click('[data-testid="submit"]');
+
+  await expect(page).toHaveURL('/dashboard');
+});
+
+// ✅ GOOD: Factories adapt to schema changes automatically
+// When `phoneNumber` becomes required, update factory once:
+export const createUser = (overrides: Partial<User> = {}): User => ({
+  id: faker.string.uuid(),
+  email: faker.internet.email(),
+  name: faker.person.fullName(),
+  phoneNumber: faker.phone.number(), // NEW field, all tests get it automatically
+  role: 'user',
+  ...overrides,
+});
+```
+
+**Key Points**:
+
+- Factories generate unique, parallel-safe data
+- Schema evolution handled in one place (factory), not every test
+- Test intent explicit via overrides
+- API seeding is fast and reliable
+
+### Example 5: Factory Composition
+
+**Context**: When building specialized factories, compose simpler factories instead of duplicating logic. Layer overrides for specific test scenarios.
+
+**Implementation**:
+
+```typescript
+// test-utils/factories/user-factory.ts (base)
+export const createUser = (overrides: Partial<User> = {}): User => ({
+  id: faker.string.uuid(),
+  email: faker.internet.email(),
+  name: faker.person.fullName(),
+  role: 'user',
+  createdAt: new Date(),
+  isActive: true,
+  ...overrides,
+});
+
+// Compose specialized factories
+export const createAdminUser = (overrides: Partial<User> = {}): User => createUser({ role: 'admin', ...overrides });
+
+export const createModeratorUser = (overrides: Partial<User> = {}): User => createUser({ role: 'moderator', ...overrides });
+
+export const createInactiveUser = (overrides: Partial<User> = {}): User => createUser({ isActive: false, ...overrides });
+
+// Account-level factories with feature flags
+type Account = {
+  id: string;
+  owner: User;
+  plan: 'free' | 'pro' | 'enterprise';
+  features: string[];
+  maxUsers: number;
+};
+
+export const createAccount = (overrides: Partial<Account> = {}): Account => ({
+  id: faker.string.uuid(),
+  owner: overrides.owner || createUser(),
+  plan: 'free',
+  features: [],
+  maxUsers: 1,
+  ...overrides,
+});
+
+export const createProAccount = (overrides: Partial<Account> = {}): Account =>
+  createAccount({
+    plan: 'pro',
+    features: ['advanced-analytics', 'priority-support'],
+    maxUsers: 10,
+    ...overrides,
+  });
+
+export const createEnterpriseAccount = (overrides: Partial<Account> = {}): Account =>
+  createAccount({
+    plan: 'enterprise',
+    features: ['advanced-analytics', 'priority-support', 'sso', 'audit-logs'],
+    maxUsers: 100,
+    ...overrides,
+  });
+
+// Usage in tests:
+test('pro accounts can access analytics', async ({ page, apiRequest }) => {
+  const admin = createAdminUser({ email: 'admin@company.com' });
+  const account = createProAccount({ owner: admin });
+
+  await apiRequest({ method: 'POST', url: '/api/users', data: admin });
+  await apiRequest({ method: 'POST', url: '/api/accounts', data: account });
+
+  await page.goto('/analytics');
+  await expect(page.getByText('Advanced Analytics')).toBeVisible();
+});
+
+test('free accounts cannot access analytics', async ({ page, apiRequest }) => {
+  const user = createUser({ email: 'user@company.com' });
+  const account = createAccount({ owner: user }); // Defaults to free plan
+
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+  await apiRequest({ method: 'POST', url: '/api/accounts', data: account });
+
+  await page.goto('/analytics');
+  await expect(page.getByText('Upgrade to Pro')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Compose specialized factories from base factories (`createAdminUser` → `createUser`)
+- Defaults cascade: `createProAccount` sets plan + features automatically
+- Still allow overrides: `createProAccount({ maxUsers: 50 })` works
+- Test intent clear: `createProAccount()` vs `createAccount({ plan: 'pro', features: [...] })`
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (test generation), `*automate` (test expansion), `*framework` (factory setup)
+- **Related fragments**:
+  - `fixture-architecture.md` - Pure functions and fixtures for factory integration
+  - `network-first.md` - API-first setup patterns
+  - `test-quality.md` - Parallel-safe, deterministic test design
+
+## Cleanup Strategy
+
+Ensure factories work with cleanup patterns:
+
+```typescript
+// Track created IDs for cleanup
+const createdUsers: string[] = [];
+
+afterEach(async ({ apiRequest }) => {
+  // Clean up all users created during test
+  for (const userId of createdUsers) {
+    await apiRequest({ method: 'DELETE', url: `/api/users/${userId}` });
+  }
+  createdUsers.length = 0;
+});
+
+test('user registration flow', async ({ page, apiRequest }) => {
+  const user = createUser();
+  createdUsers.push(user.id);
+
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+  // ... test logic
+});
+```
+
+## Feature Flag Integration
+
+When working with feature flags, layer them into factories:
+
+```typescript
+export const createUserWithFlags = (
+  overrides: Partial<User> = {},
+  flags: Record<string, boolean> = {},
+): User & { flags: Record<string, boolean> } => ({
+  ...createUser(overrides),
+  flags: {
+    'new-dashboard': false,
+    'beta-features': false,
+    ...flags,
+  },
+});
+
+// Usage:
+const user = createUserWithFlags(
+  { email: 'test@example.com' },
+  {
+    'new-dashboard': true,
+    'beta-features': true,
+  },
+);
+```
+
+_Source: Murat Testing Philosophy (lines 94-120), API-first testing patterns, faker.js documentation._

_bmad/bmm/testarch/knowledge/email-auth.md

@@ -0,0 +1,721 @@
+# Email-Based Authentication Testing
+
+## Principle
+
+Email-based authentication (magic links, one-time codes, passwordless login) requires specialized testing with email capture services like Mailosaur or Ethereal. Extract magic links via HTML parsing or use built-in link extraction, preserve browser storage (local/session/cookies) when processing links, cache email payloads to avoid exhausting inbox quotas, and cover negative cases (expired links, reused links, multiple rapid requests). Log email IDs and links for troubleshooting, but scrub PII before committing artifacts.
+
+## Rationale
+
+Email authentication introduces unique challenges: asynchronous email delivery, quota limits (AWS Cognito: 50/day), cost per email, and complex state management (session preservation across link clicks). Without proper patterns, tests become slow (wait for email each time), expensive (quota exhaustion), and brittle (timing issues, missing state). Using email capture services + session caching + state preservation patterns makes email auth tests fast, reliable, and cost-effective.
+
+## Pattern Examples
+
+### Example 1: Magic Link Extraction with Mailosaur
+
+**Context**: Passwordless login flow where user receives magic link via email, clicks it, and is authenticated.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/magic-link-auth.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Magic Link Authentication Flow
+ * 1. User enters email
+ * 2. Backend sends magic link
+ * 3. Test retrieves email via Mailosaur
+ * 4. Extract and visit magic link
+ * 5. Verify user is authenticated
+ */
+
+// Mailosaur configuration
+const MAILOSAUR_API_KEY = process.env.MAILOSAUR_API_KEY!;
+const MAILOSAUR_SERVER_ID = process.env.MAILOSAUR_SERVER_ID!;
+
+/**
+ * Extract href from HTML email body
+ * DOMParser provides XML/HTML parsing in Node.js
+ */
+function extractMagicLink(htmlString: string): string | null {
+  const { JSDOM } = require('jsdom');
+  const dom = new JSDOM(htmlString);
+  const link = dom.window.document.querySelector('#magic-link-button');
+  return link ? (link as HTMLAnchorElement).href : null;
+}
+
+/**
+ * Alternative: Use Mailosaur's built-in link extraction
+ * Mailosaur automatically parses links - no regex needed!
+ */
+async function getMagicLinkFromEmail(email: string): Promise<string> {
+  const MailosaurClient = require('mailosaur');
+  const mailosaur = new MailosaurClient(MAILOSAUR_API_KEY);
+
+  // Wait for email (timeout: 30 seconds)
+  const message = await mailosaur.messages.get(
+    MAILOSAUR_SERVER_ID,
+    {
+      sentTo: email,
+    },
+    {
+      timeout: 30000, // 30 seconds
+    },
+  );
+
+  // Mailosaur extracts links automatically - no parsing needed!
+  const magicLink = message.html?.links?.[0]?.href;
+
+  if (!magicLink) {
+    throw new Error(`Magic link not found in email to ${email}`);
+  }
+
+  console.log(`📧 Email received. Magic link extracted: ${magicLink}`);
+  return magicLink;
+}
+
+test.describe('Magic Link Authentication', () => {
+  test('should authenticate user via magic link', async ({ page, context }) => {
+    // Arrange: Generate unique test email
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Act: Request magic link
+    await page.goto('/login');
+    await page.getByTestId('email-input').fill(testEmail);
+    await page.getByTestId('send-magic-link').click();
+
+    // Assert: Success message
+    await expect(page.getByTestId('check-email-message')).toBeVisible();
+    await expect(page.getByTestId('check-email-message')).toContainText('Check your email');
+
+    // Retrieve magic link from email
+    const magicLink = await getMagicLinkFromEmail(testEmail);
+
+    // Visit magic link
+    await page.goto(magicLink);
+
+    // Assert: User is authenticated
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+    await expect(page.getByTestId('user-email')).toContainText(testEmail);
+
+    // Verify session storage preserved
+    const localStorage = await page.evaluate(() => JSON.stringify(window.localStorage));
+    expect(localStorage).toContain('authToken');
+  });
+
+  test('should handle expired magic link', async ({ page }) => {
+    // Use pre-expired link (older than 15 minutes)
+    const expiredLink = 'http://localhost:3000/auth/verify?token=expired-token-123';
+
+    await page.goto(expiredLink);
+
+    // Assert: Error message displayed
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText('link has expired');
+
+    // Assert: User NOT authenticated
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+  });
+
+  test('should prevent reusing magic link', async ({ page }) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Request magic link
+    await page.goto('/login');
+    await page.getByTestId('email-input').fill(testEmail);
+    await page.getByTestId('send-magic-link').click();
+
+    const magicLink = await getMagicLinkFromEmail(testEmail);
+
+    // Visit link first time (success)
+    await page.goto(magicLink);
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+
+    // Sign out
+    await page.getByTestId('sign-out').click();
+
+    // Try to reuse same link (should fail)
+    await page.goto(magicLink);
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText('link has already been used');
+  });
+});
+```
+
+**Cypress equivalent with Mailosaur plugin**:
+
+```javascript
+// cypress/e2e/magic-link-auth.cy.ts
+describe('Magic Link Authentication', () => {
+  it('should authenticate user via magic link', () => {
+    const serverId = Cypress.env('MAILOSAUR_SERVERID');
+    const randomId = Cypress._.random(1e6);
+    const testEmail = `user-${randomId}@${serverId}.mailosaur.net`;
+
+    // Request magic link
+    cy.visit('/login');
+    cy.get('[data-cy="email-input"]').type(testEmail);
+    cy.get('[data-cy="send-magic-link"]').click();
+    cy.get('[data-cy="check-email-message"]').should('be.visible');
+
+    // Retrieve and visit magic link
+    cy.mailosaurGetMessage(serverId, { sentTo: testEmail })
+      .its('html.links.0.href') // Mailosaur extracts links automatically!
+      .should('exist')
+      .then((magicLink) => {
+        cy.log(`Magic link: ${magicLink}`);
+        cy.visit(magicLink);
+      });
+
+    // Verify authenticated
+    cy.get('[data-cy="user-menu"]').should('be.visible');
+    cy.get('[data-cy="user-email"]').should('contain', testEmail);
+  });
+});
+```
+
+**Key Points**:
+
+- **Mailosaur auto-extraction**: `html.links[0].href` or `html.codes[0].value`
+- **Unique emails**: Random ID prevents collisions
+- **Negative testing**: Expired and reused links tested
+- **State verification**: localStorage/session checked
+- **Fast email retrieval**: 30 second timeout typical
+
+---
+
+### Example 2: State Preservation Pattern with cy.session / Playwright storageState
+
+**Context**: Cache authenticated session to avoid requesting magic link on every test.
+
+**Implementation**:
+
+```typescript
+// playwright/fixtures/email-auth-fixture.ts
+import { test as base } from '@playwright/test';
+import { getMagicLinkFromEmail } from '../support/mailosaur-helpers';
+
+type EmailAuthFixture = {
+  authenticatedUser: { email: string; token: string };
+};
+
+export const test = base.extend<EmailAuthFixture>({
+  authenticatedUser: async ({ page, context }, use) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${process.env.MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Check if we have cached auth state for this email
+    const storageStatePath = `./test-results/auth-state-${testEmail}.json`;
+
+    try {
+      // Try to reuse existing session
+      await context.storageState({ path: storageStatePath });
+      await page.goto('/dashboard');
+
+      // Validate session is still valid
+      const isAuthenticated = await page.getByTestId('user-menu').isVisible({ timeout: 2000 });
+
+      if (isAuthenticated) {
+        console.log(`✅ Reusing cached session for ${testEmail}`);
+        await use({ email: testEmail, token: 'cached' });
+        return;
+      }
+    } catch (error) {
+      console.log(`📧 No cached session, requesting magic link for ${testEmail}`);
+    }
+
+    // Request new magic link
+    await page.goto('/login');
+    await page.getByTestId('email-input').fill(testEmail);
+    await page.getByTestId('send-magic-link').click();
+
+    // Get magic link from email
+    const magicLink = await getMagicLinkFromEmail(testEmail);
+
+    // Visit link and authenticate
+    await page.goto(magicLink);
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+
+    // Extract auth token from localStorage
+    const authToken = await page.evaluate(() => localStorage.getItem('authToken'));
+
+    // Save session state for reuse
+    await context.storageState({ path: storageStatePath });
+
+    console.log(`💾 Cached session for ${testEmail}`);
+
+    await use({ email: testEmail, token: authToken || '' });
+  },
+});
+```
+
+**Cypress equivalent with cy.session + data-session**:
+
+```javascript
+// cypress/support/commands/email-auth.js
+import { dataSession } from 'cypress-data-session';
+
+/**
+ * Authenticate via magic link with session caching
+ * - First run: Requests email, extracts link, authenticates
+ * - Subsequent runs: Reuses cached session (no email)
+ */
+Cypress.Commands.add('authViaMagicLink', (email) => {
+  return dataSession({
+    name: `magic-link-${email}`,
+
+    // First-time setup: Request and process magic link
+    setup: () => {
+      cy.visit('/login');
+      cy.get('[data-cy="email-input"]').type(email);
+      cy.get('[data-cy="send-magic-link"]').click();
+
+      // Get magic link from Mailosaur
+      cy.mailosaurGetMessage(Cypress.env('MAILOSAUR_SERVERID'), {
+        sentTo: email,
+      })
+        .its('html.links.0.href')
+        .should('exist')
+        .then((magicLink) => {
+          cy.visit(magicLink);
+        });
+
+      // Wait for authentication
+      cy.get('[data-cy="user-menu"]', { timeout: 10000 }).should('be.visible');
+
+      // Preserve authentication state
+      return cy.getAllLocalStorage().then((storage) => {
+        return { storage, email };
+      });
+    },
+
+    // Validate cached session is still valid
+    validate: (cached) => {
+      return cy.wrap(Boolean(cached?.storage));
+    },
+
+    // Recreate session from cache (no email needed)
+    recreate: (cached) => {
+      // Restore localStorage
+      cy.setLocalStorage(cached.storage);
+      cy.visit('/dashboard');
+      cy.get('[data-cy="user-menu"]', { timeout: 5000 }).should('be.visible');
+    },
+
+    shareAcrossSpecs: true, // Share session across all tests
+  });
+});
+```
+
+**Usage in tests**:
+
+```javascript
+// cypress/e2e/dashboard.cy.ts
+describe('Dashboard', () => {
+  const serverId = Cypress.env('MAILOSAUR_SERVERID');
+  const testEmail = `test-user@${serverId}.mailosaur.net`;
+
+  beforeEach(() => {
+    // First test: Requests magic link
+    // Subsequent tests: Reuses cached session (no email!)
+    cy.authViaMagicLink(testEmail);
+  });
+
+  it('should display user dashboard', () => {
+    cy.get('[data-cy="dashboard-content"]').should('be.visible');
+  });
+
+  it('should show user profile', () => {
+    cy.get('[data-cy="user-email"]').should('contain', testEmail);
+  });
+
+  // Both tests share same session - only 1 email consumed!
+});
+```
+
+**Key Points**:
+
+- **Session caching**: First test requests email, rest reuse session
+- **State preservation**: localStorage/cookies saved and restored
+- **Validation**: Check cached session is still valid
+- **Quota optimization**: Massive reduction in email consumption
+- **Fast tests**: Cached auth takes seconds vs. minutes
+
+---
+
+### Example 3: Negative Flow Tests (Expired, Invalid, Reused Links)
+
+**Context**: Comprehensive negative testing for email authentication edge cases.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/email-auth-negative.spec.ts
+import { test, expect } from '@playwright/test';
+import { getMagicLinkFromEmail } from '../support/mailosaur-helpers';
+
+const MAILOSAUR_SERVER_ID = process.env.MAILOSAUR_SERVER_ID!;
+
+test.describe('Email Auth Negative Flows', () => {
+  test('should reject expired magic link', async ({ page }) => {
+    // Generate expired link (simulate 24 hours ago)
+    const expiredToken = Buffer.from(
+      JSON.stringify({
+        email: 'test@example.com',
+        exp: Date.now() - 24 * 60 * 60 * 1000, // 24 hours ago
+      }),
+    ).toString('base64');
+
+    const expiredLink = `http://localhost:3000/auth/verify?token=${expiredToken}`;
+
+    // Visit expired link
+    await page.goto(expiredLink);
+
+    // Assert: Error displayed
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/link.*expired|expired.*link/i);
+
+    // Assert: Link to request new one
+    await expect(page.getByTestId('request-new-link')).toBeVisible();
+
+    // Assert: User NOT authenticated
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+  });
+
+  test('should reject invalid magic link token', async ({ page }) => {
+    const invalidLink = 'http://localhost:3000/auth/verify?token=invalid-garbage';
+
+    await page.goto(invalidLink);
+
+    // Assert: Error displayed
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/invalid.*link|link.*invalid/i);
+
+    // Assert: User not authenticated
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+  });
+
+  test('should reject already-used magic link', async ({ page, context }) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Request magic link
+    await page.goto('/login');
+    await page.getByTestId('email-input').fill(testEmail);
+    await page.getByTestId('send-magic-link').click();
+
+    const magicLink = await getMagicLinkFromEmail(testEmail);
+
+    // Visit link FIRST time (success)
+    await page.goto(magicLink);
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+
+    // Sign out
+    await page.getByTestId('user-menu').click();
+    await page.getByTestId('sign-out').click();
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+
+    // Try to reuse SAME link (should fail)
+    await page.goto(magicLink);
+
+    // Assert: Link already used error
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/already.*used|link.*used/i);
+
+    // Assert: User not authenticated
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+  });
+
+  test('should handle rapid successive link requests', async ({ page }) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Request magic link 3 times rapidly
+    for (let i = 0; i < 3; i++) {
+      await page.goto('/login');
+      await page.getByTestId('email-input').fill(testEmail);
+      await page.getByTestId('send-magic-link').click();
+      await expect(page.getByTestId('check-email-message')).toBeVisible();
+    }
+
+    // Only the LATEST link should work
+    const MailosaurClient = require('mailosaur');
+    const mailosaur = new MailosaurClient(process.env.MAILOSAUR_API_KEY);
+
+    const messages = await mailosaur.messages.list(MAILOSAUR_SERVER_ID, {
+      sentTo: testEmail,
+    });
+
+    // Should receive 3 emails
+    expect(messages.items.length).toBeGreaterThanOrEqual(3);
+
+    // Get the LATEST magic link
+    const latestMessage = messages.items[0]; // Most recent first
+    const latestLink = latestMessage.html.links[0].href;
+
+    // Latest link works
+    await page.goto(latestLink);
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+
+    // Older links should NOT work (if backend invalidates previous)
+    await page.getByTestId('sign-out').click();
+    const olderLink = messages.items[1].html.links[0].href;
+
+    await page.goto(olderLink);
+    await expect(page.getByTestId('error-message')).toBeVisible();
+  });
+
+  test('should rate-limit excessive magic link requests', async ({ page }) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Request magic link 10 times rapidly (should hit rate limit)
+    for (let i = 0; i < 10; i++) {
+      await page.goto('/login');
+      await page.getByTestId('email-input').fill(testEmail);
+      await page.getByTestId('send-magic-link').click();
+
+      // After N requests, should show rate limit error
+      const errorVisible = await page
+        .getByTestId('rate-limit-error')
+        .isVisible({ timeout: 1000 })
+        .catch(() => false);
+
+      if (errorVisible) {
+        console.log(`Rate limit hit after ${i + 1} requests`);
+        await expect(page.getByTestId('rate-limit-error')).toContainText(/too many.*requests|rate.*limit/i);
+        return;
+      }
+    }
+
+    // If no rate limit after 10 requests, log warning
+    console.warn('⚠️  No rate limit detected after 10 requests');
+  });
+});
+```
+
+**Key Points**:
+
+- **Expired links**: Test 24+ hour old tokens
+- **Invalid tokens**: Malformed or garbage tokens rejected
+- **Reuse prevention**: Same link can't be used twice
+- **Rapid requests**: Multiple requests handled gracefully
+- **Rate limiting**: Excessive requests blocked
+
+---
+
+### Example 4: Caching Strategy with cypress-data-session / Playwright Projects
+
+**Context**: Minimize email consumption by sharing authentication state across tests and specs.
+
+**Implementation**:
+
+```javascript
+// cypress/support/commands/register-and-sign-in.js
+import { dataSession } from 'cypress-data-session';
+
+/**
+ * Email Authentication Caching Strategy
+ * - One email per test run (not per spec, not per test)
+ * - First spec: Full registration flow (form → email → code → sign in)
+ * - Subsequent specs: Only sign in (reuse user)
+ * - Subsequent tests in same spec: Session already active (no sign in)
+ */
+
+// Helper: Fill registration form
+function fillRegistrationForm({ fullName, userName, email, password }) {
+  cy.intercept('POST', 'https://cognito-idp*').as('cognito');
+  cy.contains('Register').click();
+  cy.get('#reg-dialog-form').should('be.visible');
+  cy.get('#first-name').type(fullName, { delay: 0 });
+  cy.get('#last-name').type(lastName, { delay: 0 });
+  cy.get('#email').type(email, { delay: 0 });
+  cy.get('#username').type(userName, { delay: 0 });
+  cy.get('#password').type(password, { delay: 0 });
+  cy.contains('button', 'Create an account').click();
+  cy.wait('@cognito').its('response.statusCode').should('equal', 200);
+}
+
+// Helper: Confirm registration with email code
+function confirmRegistration(email) {
+  return cy
+    .mailosaurGetMessage(Cypress.env('MAILOSAUR_SERVERID'), { sentTo: email })
+    .its('html.codes.0.value') // Mailosaur auto-extracts codes!
+    .then((code) => {
+      cy.intercept('POST', 'https://cognito-idp*').as('cognito');
+      cy.get('#verification-code').type(code, { delay: 0 });
+      cy.contains('button', 'Confirm registration').click();
+      cy.wait('@cognito');
+      cy.contains('You are now registered!').should('be.visible');
+      cy.contains('button', /ok/i).click();
+      return cy.wrap(code); // Return code for reference
+    });
+}
+
+// Helper: Full registration (form + email)
+function register({ fullName, userName, email, password }) {
+  fillRegistrationForm({ fullName, userName, email, password });
+  return confirmRegistration(email);
+}
+
+// Helper: Sign in
+function signIn({ userName, password }) {
+  cy.intercept('POST', 'https://cognito-idp*').as('cognito');
+  cy.contains('Sign in').click();
+  cy.get('#sign-in-username').type(userName, { delay: 0 });
+  cy.get('#sign-in-password').type(password, { delay: 0 });
+  cy.contains('button', 'Sign in').click();
+  cy.wait('@cognito');
+  cy.contains('Sign out').should('be.visible');
+}
+
+/**
+ * Register and sign in with email caching
+ * ONE EMAIL PER MACHINE (cypress run or cypress open)
+ */
+Cypress.Commands.add('registerAndSignIn', ({ fullName, userName, email, password }) => {
+  return dataSession({
+    name: email, // Unique session per email
+
+    // First time: Full registration (form → email → code)
+    init: () => register({ fullName, userName, email, password }),
+
+    // Subsequent specs: Just check email exists (code already used)
+    setup: () => confirmRegistration(email),
+
+    // Always runs after init/setup: Sign in
+    recreate: () => signIn({ userName, password }),
+
+    // Share across ALL specs (one email for entire test run)
+    shareAcrossSpecs: true,
+  });
+});
+```
+
+**Usage across multiple specs**:
+
+```javascript
+// cypress/e2e/place-order.cy.ts
+describe('Place Order', () => {
+  beforeEach(() => {
+    cy.visit('/');
+    cy.registerAndSignIn({
+      fullName: Cypress.env('fullName'), // From cypress.config
+      userName: Cypress.env('userName'),
+      email: Cypress.env('email'), // SAME email across all specs
+      password: Cypress.env('password'),
+    });
+  });
+
+  it('should place order', () => {
+    /* ... */
+  });
+  it('should view order history', () => {
+    /* ... */
+  });
+});
+
+// cypress/e2e/profile.cy.ts
+describe('User Profile', () => {
+  beforeEach(() => {
+    cy.visit('/');
+    cy.registerAndSignIn({
+      fullName: Cypress.env('fullName'),
+      userName: Cypress.env('userName'),
+      email: Cypress.env('email'), // SAME email - no new email sent!
+      password: Cypress.env('password'),
+    });
+  });
+
+  it('should update profile', () => {
+    /* ... */
+  });
+});
+```
+
+**Playwright equivalent with storageState**:
+
+```typescript
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  projects: [
+    {
+      name: 'setup',
+      testMatch: /global-setup\.ts/,
+    },
+    {
+      name: 'authenticated',
+      testMatch: /.*\.spec\.ts/,
+      dependencies: ['setup'],
+      use: {
+        storageState: '.auth/user-session.json', // Reuse auth state
+      },
+    },
+  ],
+});
+```
+
+```typescript
+// tests/global-setup.ts (runs once)
+import { test as setup } from '@playwright/test';
+import { getMagicLinkFromEmail } from './support/mailosaur-helpers';
+
+const authFile = '.auth/user-session.json';
+
+setup('authenticate via magic link', async ({ page }) => {
+  const testEmail = process.env.TEST_USER_EMAIL!;
+
+  // Request magic link
+  await page.goto('/login');
+  await page.getByTestId('email-input').fill(testEmail);
+  await page.getByTestId('send-magic-link').click();
+
+  // Get and visit magic link
+  const magicLink = await getMagicLinkFromEmail(testEmail);
+  await page.goto(magicLink);
+
+  // Verify authenticated
+  await expect(page.getByTestId('user-menu')).toBeVisible();
+
+  // Save authenticated state (ONE TIME for all tests)
+  await page.context().storageState({ path: authFile });
+
+  console.log('✅ Authentication state saved to', authFile);
+});
+```
+
+**Key Points**:
+
+- **One email per run**: Global setup authenticates once
+- **State reuse**: All tests use cached storageState
+- **cypress-data-session**: Intelligently manages cache lifecycle
+- **shareAcrossSpecs**: Session shared across all spec files
+- **Massive savings**: 500 tests = 1 email (not 500!)
+
+---
+
+## Email Authentication Testing Checklist
+
+Before implementing email auth tests, verify:
+
+- [ ] **Email service**: Mailosaur/Ethereal/MailHog configured with API keys
+- [ ] **Link extraction**: Use built-in parsing (html.links[0].href) over regex
+- [ ] **State preservation**: localStorage/session/cookies saved and restored
+- [ ] **Session caching**: cypress-data-session or storageState prevents redundant emails
+- [ ] **Negative flows**: Expired, invalid, reused, rapid requests tested
+- [ ] **Quota awareness**: One email per run (not per test)
+- [ ] **PII scrubbing**: Email IDs logged for debug, but scrubbed from artifacts
+- [ ] **Timeout handling**: 30 second email retrieval timeout configured
+
+## Integration Points
+
+- Used in workflows: `*framework` (email auth setup), `*automate` (email auth test generation)
+- Related fragments: `fixture-architecture.md`, `test-quality.md`
+- Email services: Mailosaur (recommended), Ethereal (free), MailHog (self-hosted)
+- Plugins: cypress-mailosaur, cypress-data-session
+
+_Source: Email authentication blog, Murat testing toolkit, Mailosaur documentation_

_bmad/bmm/testarch/knowledge/error-handling.md

@@ -0,0 +1,725 @@
+# Error Handling and Resilience Checks
+
+## Principle
+
+Treat expected failures explicitly: intercept network errors, assert UI fallbacks (error messages visible, retries triggered), and use scoped exception handling to ignore known errors while catching regressions. Test retry/backoff logic by forcing sequential failures (500 → timeout → success) and validate telemetry logging. Log captured errors with context (request payload, user/session) but redact secrets to keep artifacts safe for sharing.
+
+## Rationale
+
+Tests fail for two reasons: genuine bugs or poor error handling in the test itself. Without explicit error handling patterns, tests become noisy (uncaught exceptions cause false failures) or silent (swallowing all errors hides real bugs). Scoped exception handling (Cypress.on('uncaught:exception'), page.on('pageerror')) allows tests to ignore documented, expected errors while surfacing unexpected ones. Resilience testing (retry logic, graceful degradation) ensures applications handle failures gracefully in production.
+
+## Pattern Examples
+
+### Example 1: Scoped Exception Handling (Expected Errors Only)
+
+**Context**: Handle known errors (Network failures, expected 500s) without masking unexpected bugs.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/error-handling.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Scoped Error Handling Pattern
+ * - Only ignore specific, documented errors
+ * - Rethrow everything else to catch regressions
+ * - Validate error UI and user experience
+ */
+
+test.describe('API Error Handling', () => {
+  test('should display error message when API returns 500', async ({ page }) => {
+    // Scope error handling to THIS test only
+    const consoleErrors: string[] = [];
+    page.on('pageerror', (error) => {
+      // Only swallow documented NetworkError
+      if (error.message.includes('NetworkError: Failed to fetch')) {
+        consoleErrors.push(error.message);
+        return; // Swallow this specific error
+      }
+      // Rethrow all other errors (catch regressions!)
+      throw error;
+    });
+
+    // Arrange: Mock 500 error response
+    await page.route('**/api/users', (route) =>
+      route.fulfill({
+        status: 500,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          error: 'Internal server error',
+          code: 'INTERNAL_ERROR',
+        }),
+      }),
+    );
+
+    // Act: Navigate to page that fetches users
+    await page.goto('/dashboard');
+
+    // Assert: Error UI displayed
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/error.*loading|failed.*load/i);
+
+    // Assert: Retry button visible
+    await expect(page.getByTestId('retry-button')).toBeVisible();
+
+    // Assert: NetworkError was thrown and caught
+    expect(consoleErrors).toContainEqual(expect.stringContaining('NetworkError'));
+  });
+
+  test('should NOT swallow unexpected errors', async ({ page }) => {
+    let unexpectedError: Error | null = null;
+
+    page.on('pageerror', (error) => {
+      // Capture but don't swallow - test should fail
+      unexpectedError = error;
+      throw error;
+    });
+
+    // Arrange: App has JavaScript error (bug)
+    await page.addInitScript(() => {
+      // Simulate bug in app code
+      (window as any).buggyFunction = () => {
+        throw new Error('UNEXPECTED BUG: undefined is not a function');
+      };
+    });
+
+    await page.goto('/dashboard');
+
+    // Trigger buggy function
+    await page.evaluate(() => (window as any).buggyFunction());
+
+    // Assert: Test fails because unexpected error was NOT swallowed
+    expect(unexpectedError).not.toBeNull();
+    expect(unexpectedError?.message).toContain('UNEXPECTED BUG');
+  });
+});
+```
+
+**Cypress equivalent**:
+
+```javascript
+// cypress/e2e/error-handling.cy.ts
+describe('API Error Handling', () => {
+  it('should display error message when API returns 500', () => {
+    // Scoped to this test only
+    cy.on('uncaught:exception', (err) => {
+      // Only swallow documented NetworkError
+      if (err.message.includes('NetworkError')) {
+        return false; // Prevent test failure
+      }
+      // All other errors fail the test
+      return true;
+    });
+
+    // Arrange: Mock 500 error
+    cy.intercept('GET', '**/api/users', {
+      statusCode: 500,
+      body: {
+        error: 'Internal server error',
+        code: 'INTERNAL_ERROR',
+      },
+    }).as('getUsers');
+
+    // Act
+    cy.visit('/dashboard');
+    cy.wait('@getUsers');
+
+    // Assert: Error UI
+    cy.get('[data-cy="error-message"]').should('be.visible');
+    cy.get('[data-cy="error-message"]').should('contain', 'error loading');
+    cy.get('[data-cy="retry-button"]').should('be.visible');
+  });
+
+  it('should NOT swallow unexpected errors', () => {
+    // No exception handler - test should fail on unexpected errors
+
+    cy.visit('/dashboard');
+
+    // Trigger unexpected error
+    cy.window().then((win) => {
+      // This should fail the test
+      win.eval('throw new Error("UNEXPECTED BUG")');
+    });
+
+    // Test fails (as expected) - validates error detection works
+  });
+});
+```
+
+**Key Points**:
+
+- **Scoped handling**: page.on() / cy.on() scoped to specific tests
+- **Explicit allow-list**: Only ignore documented errors
+- **Rethrow unexpected**: Catch regressions by failing on unknown errors
+- **Error UI validation**: Assert user sees error message
+- **Logging**: Capture errors for debugging, don't swallow silently
+
+---
+
+### Example 2: Retry Validation Pattern (Network Resilience)
+
+**Context**: Test that retry/backoff logic works correctly for transient failures.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/retry-resilience.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Retry Validation Pattern
+ * - Force sequential failures (500 → 500 → 200)
+ * - Validate retry attempts and backoff timing
+ * - Assert telemetry captures retry events
+ */
+
+test.describe('Network Retry Logic', () => {
+  test('should retry on 500 error and succeed', async ({ page }) => {
+    let attemptCount = 0;
+    const attemptTimestamps: number[] = [];
+
+    // Mock API: Fail twice, succeed on third attempt
+    await page.route('**/api/products', (route) => {
+      attemptCount++;
+      attemptTimestamps.push(Date.now());
+
+      if (attemptCount <= 2) {
+        // First 2 attempts: 500 error
+        route.fulfill({
+          status: 500,
+          body: JSON.stringify({ error: 'Server error' }),
+        });
+      } else {
+        // 3rd attempt: Success
+        route.fulfill({
+          status: 200,
+          contentType: 'application/json',
+          body: JSON.stringify({ products: [{ id: 1, name: 'Product 1' }] }),
+        });
+      }
+    });
+
+    // Act: Navigate (should retry automatically)
+    await page.goto('/products');
+
+    // Assert: Data eventually loads after retries
+    await expect(page.getByTestId('product-list')).toBeVisible();
+    await expect(page.getByTestId('product-item')).toHaveCount(1);
+
+    // Assert: Exactly 3 attempts made
+    expect(attemptCount).toBe(3);
+
+    // Assert: Exponential backoff timing (1s → 2s between attempts)
+    if (attemptTimestamps.length === 3) {
+      const delay1 = attemptTimestamps[1] - attemptTimestamps[0];
+      const delay2 = attemptTimestamps[2] - attemptTimestamps[1];
+
+      expect(delay1).toBeGreaterThanOrEqual(900); // ~1 second
+      expect(delay1).toBeLessThan(1200);
+      expect(delay2).toBeGreaterThanOrEqual(1900); // ~2 seconds
+      expect(delay2).toBeLessThan(2200);
+    }
+
+    // Assert: Telemetry logged retry events
+    const telemetryEvents = await page.evaluate(() => (window as any).__TELEMETRY_EVENTS__ || []);
+    expect(telemetryEvents).toContainEqual(
+      expect.objectContaining({
+        event: 'api_retry',
+        attempt: 1,
+        endpoint: '/api/products',
+      }),
+    );
+    expect(telemetryEvents).toContainEqual(
+      expect.objectContaining({
+        event: 'api_retry',
+        attempt: 2,
+      }),
+    );
+  });
+
+  test('should give up after max retries and show error', async ({ page }) => {
+    let attemptCount = 0;
+
+    // Mock API: Always fail (test retry limit)
+    await page.route('**/api/products', (route) => {
+      attemptCount++;
+      route.fulfill({
+        status: 500,
+        body: JSON.stringify({ error: 'Persistent server error' }),
+      });
+    });
+
+    // Act
+    await page.goto('/products');
+
+    // Assert: Max retries reached (3 attempts typical)
+    expect(attemptCount).toBe(3);
+
+    // Assert: Error UI displayed after exhausting retries
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/unable.*load|failed.*after.*retries/i);
+
+    // Assert: Data not displayed
+    await expect(page.getByTestId('product-list')).not.toBeVisible();
+  });
+
+  test('should NOT retry on 404 (non-retryable error)', async ({ page }) => {
+    let attemptCount = 0;
+
+    // Mock API: 404 error (should NOT retry)
+    await page.route('**/api/products/999', (route) => {
+      attemptCount++;
+      route.fulfill({
+        status: 404,
+        body: JSON.stringify({ error: 'Product not found' }),
+      });
+    });
+
+    await page.goto('/products/999');
+
+    // Assert: Only 1 attempt (no retries on 404)
+    expect(attemptCount).toBe(1);
+
+    // Assert: 404 error displayed immediately
+    await expect(page.getByTestId('not-found-message')).toBeVisible();
+  });
+});
+```
+
+**Cypress with retry interception**:
+
+```javascript
+// cypress/e2e/retry-resilience.cy.ts
+describe('Network Retry Logic', () => {
+  it('should retry on 500 and succeed on 3rd attempt', () => {
+    let attemptCount = 0;
+
+    cy.intercept('GET', '**/api/products', (req) => {
+      attemptCount++;
+
+      if (attemptCount <= 2) {
+        req.reply({ statusCode: 500, body: { error: 'Server error' } });
+      } else {
+        req.reply({ statusCode: 200, body: { products: [{ id: 1, name: 'Product 1' }] } });
+      }
+    }).as('getProducts');
+
+    cy.visit('/products');
+
+    // Wait for final successful request
+    cy.wait('@getProducts').its('response.statusCode').should('eq', 200);
+
+    // Assert: Data loaded
+    cy.get('[data-cy="product-list"]').should('be.visible');
+    cy.get('[data-cy="product-item"]').should('have.length', 1);
+
+    // Validate retry count
+    cy.wrap(attemptCount).should('eq', 3);
+  });
+});
+```
+
+**Key Points**:
+
+- **Sequential failures**: Test retry logic with 500 → 500 → 200
+- **Backoff timing**: Validate exponential backoff delays
+- **Retry limits**: Max attempts enforced (typically 3)
+- **Non-retryable errors**: 404s don't trigger retries
+- **Telemetry**: Log retry attempts for monitoring
+
+---
+
+### Example 3: Telemetry Logging with Context (Sentry Integration)
+
+**Context**: Capture errors with full context for production debugging without exposing secrets.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/telemetry-logging.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Telemetry Logging Pattern
+ * - Log errors with request context
+ * - Redact sensitive data (tokens, passwords, PII)
+ * - Integrate with monitoring (Sentry, Datadog)
+ * - Validate error logging without exposing secrets
+ */
+
+type ErrorLog = {
+  level: 'error' | 'warn' | 'info';
+  message: string;
+  context?: {
+    endpoint?: string;
+    method?: string;
+    statusCode?: number;
+    userId?: string;
+    sessionId?: string;
+  };
+  timestamp: string;
+};
+
+test.describe('Error Telemetry', () => {
+  test('should log API errors with context', async ({ page }) => {
+    const errorLogs: ErrorLog[] = [];
+
+    // Capture console errors
+    page.on('console', (msg) => {
+      if (msg.type() === 'error') {
+        try {
+          const log = JSON.parse(msg.text());
+          errorLogs.push(log);
+        } catch {
+          // Not a structured log, ignore
+        }
+      }
+    });
+
+    // Mock failing API
+    await page.route('**/api/orders', (route) =>
+      route.fulfill({
+        status: 500,
+        body: JSON.stringify({ error: 'Payment processor unavailable' }),
+      }),
+    );
+
+    // Act: Trigger error
+    await page.goto('/checkout');
+    await page.getByTestId('place-order').click();
+
+    // Wait for error UI
+    await expect(page.getByTestId('error-message')).toBeVisible();
+
+    // Assert: Error logged with context
+    expect(errorLogs).toContainEqual(
+      expect.objectContaining({
+        level: 'error',
+        message: expect.stringContaining('API request failed'),
+        context: expect.objectContaining({
+          endpoint: '/api/orders',
+          method: 'POST',
+          statusCode: 500,
+          userId: expect.any(String),
+        }),
+      }),
+    );
+
+    // Assert: Sensitive data NOT logged
+    const logString = JSON.stringify(errorLogs);
+    expect(logString).not.toContain('password');
+    expect(logString).not.toContain('token');
+    expect(logString).not.toContain('creditCard');
+  });
+
+  test('should send errors to Sentry with breadcrumbs', async ({ page }) => {
+    const sentryEvents: any[] = [];
+
+    // Mock Sentry SDK
+    await page.addInitScript(() => {
+      (window as any).Sentry = {
+        captureException: (error: Error, context?: any) => {
+          (window as any).__SENTRY_EVENTS__ = (window as any).__SENTRY_EVENTS__ || [];
+          (window as any).__SENTRY_EVENTS__.push({
+            error: error.message,
+            context,
+            timestamp: Date.now(),
+          });
+        },
+        addBreadcrumb: (breadcrumb: any) => {
+          (window as any).__SENTRY_BREADCRUMBS__ = (window as any).__SENTRY_BREADCRUMBS__ || [];
+          (window as any).__SENTRY_BREADCRUMBS__.push(breadcrumb);
+        },
+      };
+    });
+
+    // Mock failing API
+    await page.route('**/api/users', (route) => route.fulfill({ status: 403, body: { error: 'Forbidden' } }));
+
+    // Act
+    await page.goto('/users');
+
+    // Assert: Sentry captured error
+    const events = await page.evaluate(() => (window as any).__SENTRY_EVENTS__);
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({
+      error: expect.stringContaining('403'),
+      context: expect.objectContaining({
+        endpoint: '/api/users',
+        statusCode: 403,
+      }),
+    });
+
+    // Assert: Breadcrumbs include user actions
+    const breadcrumbs = await page.evaluate(() => (window as any).__SENTRY_BREADCRUMBS__);
+    expect(breadcrumbs).toContainEqual(
+      expect.objectContaining({
+        category: 'navigation',
+        message: '/users',
+      }),
+    );
+  });
+});
+```
+
+**Cypress with Sentry**:
+
+```javascript
+// cypress/e2e/telemetry-logging.cy.ts
+describe('Error Telemetry', () => {
+  it('should log API errors with redacted sensitive data', () => {
+    const errorLogs = [];
+
+    // Capture console errors
+    cy.on('window:before:load', (win) => {
+      cy.stub(win.console, 'error').callsFake((msg) => {
+        errorLogs.push(msg);
+      });
+    });
+
+    // Mock failing API
+    cy.intercept('POST', '**/api/orders', {
+      statusCode: 500,
+      body: { error: 'Payment failed' },
+    });
+
+    // Act
+    cy.visit('/checkout');
+    cy.get('[data-cy="place-order"]').click();
+
+    // Assert: Error logged
+    cy.wrap(errorLogs).should('have.length.greaterThan', 0);
+
+    // Assert: Context included
+    cy.wrap(errorLogs[0]).should('include', '/api/orders');
+
+    // Assert: Secrets redacted
+    cy.wrap(JSON.stringify(errorLogs)).should('not.contain', 'password');
+    cy.wrap(JSON.stringify(errorLogs)).should('not.contain', 'creditCard');
+  });
+});
+```
+
+**Error logger utility with redaction**:
+
+```typescript
+// src/utils/error-logger.ts
+type ErrorContext = {
+  endpoint?: string;
+  method?: string;
+  statusCode?: number;
+  userId?: string;
+  sessionId?: string;
+  requestPayload?: any;
+};
+
+const SENSITIVE_KEYS = ['password', 'token', 'creditCard', 'ssn', 'apiKey'];
+
+/**
+ * Redact sensitive data from objects
+ */
+function redactSensitiveData(obj: any): any {
+  if (typeof obj !== 'object' || obj === null) return obj;
+
+  const redacted = { ...obj };
+
+  for (const key of Object.keys(redacted)) {
+    if (SENSITIVE_KEYS.some((sensitive) => key.toLowerCase().includes(sensitive))) {
+      redacted[key] = '[REDACTED]';
+    } else if (typeof redacted[key] === 'object') {
+      redacted[key] = redactSensitiveData(redacted[key]);
+    }
+  }
+
+  return redacted;
+}
+
+/**
+ * Log error with context (Sentry integration)
+ */
+export function logError(error: Error, context?: ErrorContext) {
+  const safeContext = context ? redactSensitiveData(context) : {};
+
+  const errorLog = {
+    level: 'error' as const,
+    message: error.message,
+    stack: error.stack,
+    context: safeContext,
+    timestamp: new Date().toISOString(),
+  };
+
+  // Console (development)
+  console.error(JSON.stringify(errorLog));
+
+  // Sentry (production)
+  if (typeof window !== 'undefined' && (window as any).Sentry) {
+    (window as any).Sentry.captureException(error, {
+      contexts: { custom: safeContext },
+    });
+  }
+}
+```
+
+**Key Points**:
+
+- **Context-rich logging**: Endpoint, method, status, user ID
+- **Secret redaction**: Passwords, tokens, PII removed before logging
+- **Sentry integration**: Production monitoring with breadcrumbs
+- **Structured logs**: JSON format for easy parsing
+- **Test validation**: Assert logs contain context but not secrets
+
+---
+
+### Example 4: Graceful Degradation Tests (Fallback Behavior)
+
+**Context**: Validate application continues functioning when services are unavailable.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/graceful-degradation.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Graceful Degradation Pattern
+ * - Simulate service unavailability
+ * - Validate fallback behavior
+ * - Ensure user experience degrades gracefully
+ * - Verify telemetry captures degradation events
+ */
+
+test.describe('Service Unavailability', () => {
+  test('should display cached data when API is down', async ({ page }) => {
+    // Arrange: Seed localStorage with cached data
+    await page.addInitScript(() => {
+      localStorage.setItem(
+        'products_cache',
+        JSON.stringify({
+          data: [
+            { id: 1, name: 'Cached Product 1' },
+            { id: 2, name: 'Cached Product 2' },
+          ],
+          timestamp: Date.now(),
+        }),
+      );
+    });
+
+    // Mock API unavailable
+    await page.route(
+      '**/api/products',
+      (route) => route.abort('connectionrefused'), // Simulate server down
+    );
+
+    // Act
+    await page.goto('/products');
+
+    // Assert: Cached data displayed
+    await expect(page.getByTestId('product-list')).toBeVisible();
+    await expect(page.getByText('Cached Product 1')).toBeVisible();
+
+    // Assert: Stale data warning shown
+    await expect(page.getByTestId('cache-warning')).toBeVisible();
+    await expect(page.getByTestId('cache-warning')).toContainText(/showing.*cached|offline.*mode/i);
+
+    // Assert: Retry button available
+    await expect(page.getByTestId('refresh-button')).toBeVisible();
+  });
+
+  test('should show fallback UI when analytics service fails', async ({ page }) => {
+    // Mock analytics service down (non-critical)
+    await page.route('**/analytics/track', (route) => route.fulfill({ status: 503, body: 'Service unavailable' }));
+
+    // Act: Navigate normally
+    await page.goto('/dashboard');
+
+    // Assert: Page loads successfully (analytics failure doesn't block)
+    await expect(page.getByTestId('dashboard-content')).toBeVisible();
+
+    // Assert: Analytics error logged but not shown to user
+    const consoleErrors = [];
+    page.on('console', (msg) => {
+      if (msg.type() === 'error') consoleErrors.push(msg.text());
+    });
+
+    // Trigger analytics event
+    await page.getByTestId('track-action-button').click();
+
+    // Analytics error logged
+    expect(consoleErrors).toContainEqual(expect.stringContaining('Analytics service unavailable'));
+
+    // But user doesn't see error
+    await expect(page.getByTestId('error-message')).not.toBeVisible();
+  });
+
+  test('should fallback to local validation when API is slow', async ({ page }) => {
+    // Mock slow API (> 5 seconds)
+    await page.route('**/api/validate-email', async (route) => {
+      await new Promise((resolve) => setTimeout(resolve, 6000)); // 6 second delay
+      route.fulfill({
+        status: 200,
+        body: JSON.stringify({ valid: true }),
+      });
+    });
+
+    // Act: Fill form
+    await page.goto('/signup');
+    await page.getByTestId('email-input').fill('test@example.com');
+    await page.getByTestId('email-input').blur();
+
+    // Assert: Client-side validation triggers immediately (doesn't wait for API)
+    await expect(page.getByTestId('email-valid-icon')).toBeVisible({ timeout: 1000 });
+
+    // Assert: Eventually API validates too (but doesn't block UX)
+    await expect(page.getByTestId('email-validated-badge')).toBeVisible({ timeout: 7000 });
+  });
+
+  test('should maintain functionality with third-party script failure', async ({ page }) => {
+    // Block third-party scripts (Google Analytics, Intercom, etc.)
+    await page.route('**/*.google-analytics.com/**', (route) => route.abort());
+    await page.route('**/*.intercom.io/**', (route) => route.abort());
+
+    // Act
+    await page.goto('/');
+
+    // Assert: App works without third-party scripts
+    await expect(page.getByTestId('main-content')).toBeVisible();
+    await expect(page.getByTestId('nav-menu')).toBeVisible();
+
+    // Assert: Core functionality intact
+    await page.getByTestId('nav-products').click();
+    await expect(page).toHaveURL(/.*\/products/);
+  });
+});
+```
+
+**Key Points**:
+
+- **Cached fallbacks**: Display stale data when API unavailable
+- **Non-critical degradation**: Analytics failures don't block app
+- **Client-side fallbacks**: Local validation when API slow
+- **Third-party resilience**: App works without external scripts
+- **User transparency**: Stale data warnings displayed
+
+---
+
+## Error Handling Testing Checklist
+
+Before shipping error handling code, verify:
+
+- [ ] **Scoped exception handling**: Only ignore documented errors (NetworkError, specific codes)
+- [ ] **Rethrow unexpected**: Unknown errors fail tests (catch regressions)
+- [ ] **Error UI tested**: User sees error messages for all error states
+- [ ] **Retry logic validated**: Sequential failures test backoff and max attempts
+- [ ] **Telemetry verified**: Errors logged with context (endpoint, status, user)
+- [ ] **Secret redaction**: Logs don't contain passwords, tokens, PII
+- [ ] **Graceful degradation**: Critical services down, app shows fallback UI
+- [ ] **Non-critical failures**: Analytics/tracking failures don't block app
+
+## Integration Points
+
+- Used in workflows: `*automate` (error handling test generation), `*test-review` (error pattern detection)
+- Related fragments: `network-first.md`, `test-quality.md`, `contract-testing.md`
+- Monitoring tools: Sentry, Datadog, LogRocket
+
+_Source: Murat error-handling patterns, Pact resilience guidance, SEON production error handling_

_bmad/bmm/testarch/knowledge/feature-flags.md

@@ -0,0 +1,750 @@
+# Feature Flag Governance
+
+## Principle
+
+Feature flags enable controlled rollouts and A/B testing, but require disciplined testing governance. Centralize flag definitions in a frozen enum, test both enabled and disabled states, clean up targeting after each spec, and maintain a comprehensive flag lifecycle checklist. For LaunchDarkly-style systems, script API helpers to seed variations programmatically rather than manual UI mutations.
+
+## Rationale
+
+Poorly managed feature flags become technical debt: untested variations ship broken code, forgotten flags clutter the codebase, and shared environments become unstable from leftover targeting rules. Structured governance ensures flags are testable, traceable, temporary, and safe. Testing both states prevents surprises when flags flip in production.
+
+## Pattern Examples
+
+### Example 1: Feature Flag Enum Pattern with Type Safety
+
+**Context**: Centralized flag management with TypeScript type safety and runtime validation.
+
+**Implementation**:
+
+```typescript
+// src/utils/feature-flags.ts
+/**
+ * Centralized feature flag definitions
+ * - Object.freeze prevents runtime modifications
+ * - TypeScript ensures compile-time type safety
+ * - Single source of truth for all flag keys
+ */
+export const FLAGS = Object.freeze({
+  // User-facing features
+  NEW_CHECKOUT_FLOW: 'new-checkout-flow',
+  DARK_MODE: 'dark-mode',
+  ENHANCED_SEARCH: 'enhanced-search',
+
+  // Experiments
+  PRICING_EXPERIMENT_A: 'pricing-experiment-a',
+  HOMEPAGE_VARIANT_B: 'homepage-variant-b',
+
+  // Infrastructure
+  USE_NEW_API_ENDPOINT: 'use-new-api-endpoint',
+  ENABLE_ANALYTICS_V2: 'enable-analytics-v2',
+
+  // Killswitches (emergency disables)
+  DISABLE_PAYMENT_PROCESSING: 'disable-payment-processing',
+  DISABLE_EMAIL_NOTIFICATIONS: 'disable-email-notifications',
+} as const);
+
+/**
+ * Type-safe flag keys
+ * Prevents typos and ensures autocomplete in IDEs
+ */
+export type FlagKey = (typeof FLAGS)[keyof typeof FLAGS];
+
+/**
+ * Flag metadata for governance
+ */
+type FlagMetadata = {
+  key: FlagKey;
+  name: string;
+  owner: string;
+  createdDate: string;
+  expiryDate?: string;
+  defaultState: boolean;
+  requiresCleanup: boolean;
+  dependencies?: FlagKey[];
+  telemetryEvents?: string[];
+};
+
+/**
+ * Flag registry with governance metadata
+ * Used for flag lifecycle tracking and cleanup alerts
+ */
+export const FLAG_REGISTRY: Record<FlagKey, FlagMetadata> = {
+  [FLAGS.NEW_CHECKOUT_FLOW]: {
+    key: FLAGS.NEW_CHECKOUT_FLOW,
+    name: 'New Checkout Flow',
+    owner: 'payments-team',
+    createdDate: '2025-01-15',
+    expiryDate: '2025-03-15',
+    defaultState: false,
+    requiresCleanup: true,
+    dependencies: [FLAGS.USE_NEW_API_ENDPOINT],
+    telemetryEvents: ['checkout_started', 'checkout_completed'],
+  },
+  [FLAGS.DARK_MODE]: {
+    key: FLAGS.DARK_MODE,
+    name: 'Dark Mode UI',
+    owner: 'frontend-team',
+    createdDate: '2025-01-10',
+    defaultState: false,
+    requiresCleanup: false, // Permanent feature toggle
+  },
+  // ... rest of registry
+};
+
+/**
+ * Validate flag exists in registry
+ * Throws at runtime if flag is unregistered
+ */
+export function validateFlag(flag: string): asserts flag is FlagKey {
+  if (!Object.values(FLAGS).includes(flag as FlagKey)) {
+    throw new Error(`Unregistered feature flag: ${flag}`);
+  }
+}
+
+/**
+ * Check if flag is expired (needs removal)
+ */
+export function isFlagExpired(flag: FlagKey): boolean {
+  const metadata = FLAG_REGISTRY[flag];
+  if (!metadata.expiryDate) return false;
+
+  const expiry = new Date(metadata.expiryDate);
+  return Date.now() > expiry.getTime();
+}
+
+/**
+ * Get all expired flags requiring cleanup
+ */
+export function getExpiredFlags(): FlagMetadata[] {
+  return Object.values(FLAG_REGISTRY).filter((meta) => isFlagExpired(meta.key));
+}
+```
+
+**Usage in application code**:
+
+```typescript
+// components/Checkout.tsx
+import { FLAGS } from '@/utils/feature-flags';
+import { useFeatureFlag } from '@/hooks/useFeatureFlag';
+
+export function Checkout() {
+  const isNewFlow = useFeatureFlag(FLAGS.NEW_CHECKOUT_FLOW);
+
+  return isNewFlow ? <NewCheckoutFlow /> : <LegacyCheckoutFlow />;
+}
+```
+
+**Key Points**:
+
+- **Type safety**: TypeScript catches typos at compile time
+- **Runtime validation**: validateFlag ensures only registered flags used
+- **Metadata tracking**: Owner, dates, dependencies documented
+- **Expiry alerts**: Automated detection of stale flags
+- **Single source of truth**: All flags defined in one place
+
+---
+
+### Example 2: Feature Flag Testing Pattern (Both States)
+
+**Context**: Comprehensive testing of feature flag variations with proper cleanup.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/checkout-feature-flag.spec.ts
+import { test, expect } from '@playwright/test';
+import { FLAGS } from '@/utils/feature-flags';
+
+/**
+ * Feature Flag Testing Strategy:
+ * 1. Test BOTH enabled and disabled states
+ * 2. Clean up targeting after each test
+ * 3. Use dedicated test users (not production data)
+ * 4. Verify telemetry events fire correctly
+ */
+
+test.describe('Checkout Flow - Feature Flag Variations', () => {
+  let testUserId: string;
+
+  test.beforeEach(async () => {
+    // Generate unique test user ID
+    testUserId = `test-user-${Date.now()}`;
+  });
+
+  test.afterEach(async ({ request }) => {
+    // CRITICAL: Clean up flag targeting to prevent shared env pollution
+    await request.post('/api/feature-flags/cleanup', {
+      data: {
+        flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+        userId: testUserId,
+      },
+    });
+  });
+
+  test('should use NEW checkout flow when flag is ENABLED', async ({ page, request }) => {
+    // Arrange: Enable flag for test user
+    await request.post('/api/feature-flags/target', {
+      data: {
+        flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+        userId: testUserId,
+        variation: true, // ENABLED
+      },
+    });
+
+    // Act: Navigate as targeted user
+    await page.goto('/checkout', {
+      extraHTTPHeaders: {
+        'X-Test-User-ID': testUserId,
+      },
+    });
+
+    // Assert: New flow UI elements visible
+    await expect(page.getByTestId('checkout-v2-container')).toBeVisible();
+    await expect(page.getByTestId('express-payment-options')).toBeVisible();
+    await expect(page.getByTestId('saved-addresses-dropdown')).toBeVisible();
+
+    // Assert: Legacy flow NOT visible
+    await expect(page.getByTestId('checkout-v1-container')).not.toBeVisible();
+
+    // Assert: Telemetry event fired
+    const analyticsEvents = await page.evaluate(() => (window as any).__ANALYTICS_EVENTS__ || []);
+    expect(analyticsEvents).toContainEqual(
+      expect.objectContaining({
+        event: 'checkout_started',
+        properties: expect.objectContaining({
+          variant: 'new_flow',
+        }),
+      }),
+    );
+  });
+
+  test('should use LEGACY checkout flow when flag is DISABLED', async ({ page, request }) => {
+    // Arrange: Disable flag for test user (or don't target at all)
+    await request.post('/api/feature-flags/target', {
+      data: {
+        flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+        userId: testUserId,
+        variation: false, // DISABLED
+      },
+    });
+
+    // Act: Navigate as targeted user
+    await page.goto('/checkout', {
+      extraHTTPHeaders: {
+        'X-Test-User-ID': testUserId,
+      },
+    });
+
+    // Assert: Legacy flow UI elements visible
+    await expect(page.getByTestId('checkout-v1-container')).toBeVisible();
+    await expect(page.getByTestId('legacy-payment-form')).toBeVisible();
+
+    // Assert: New flow NOT visible
+    await expect(page.getByTestId('checkout-v2-container')).not.toBeVisible();
+    await expect(page.getByTestId('express-payment-options')).not.toBeVisible();
+
+    // Assert: Telemetry event fired with correct variant
+    const analyticsEvents = await page.evaluate(() => (window as any).__ANALYTICS_EVENTS__ || []);
+    expect(analyticsEvents).toContainEqual(
+      expect.objectContaining({
+        event: 'checkout_started',
+        properties: expect.objectContaining({
+          variant: 'legacy_flow',
+        }),
+      }),
+    );
+  });
+
+  test('should handle flag evaluation errors gracefully', async ({ page, request }) => {
+    // Arrange: Simulate flag service unavailable
+    await page.route('**/api/feature-flags/evaluate', (route) => route.fulfill({ status: 500, body: 'Service Unavailable' }));
+
+    // Act: Navigate (should fallback to default state)
+    await page.goto('/checkout', {
+      extraHTTPHeaders: {
+        'X-Test-User-ID': testUserId,
+      },
+    });
+
+    // Assert: Fallback to safe default (legacy flow)
+    await expect(page.getByTestId('checkout-v1-container')).toBeVisible();
+
+    // Assert: Error logged but no user-facing error
+    const consoleErrors = [];
+    page.on('console', (msg) => {
+      if (msg.type() === 'error') consoleErrors.push(msg.text());
+    });
+    expect(consoleErrors).toContain(expect.stringContaining('Feature flag evaluation failed'));
+  });
+});
+```
+
+**Cypress equivalent**:
+
+```javascript
+// cypress/e2e/checkout-feature-flag.cy.ts
+import { FLAGS } from '@/utils/feature-flags';
+
+describe('Checkout Flow - Feature Flag Variations', () => {
+  let testUserId;
+
+  beforeEach(() => {
+    testUserId = `test-user-${Date.now()}`;
+  });
+
+  afterEach(() => {
+    // Clean up targeting
+    cy.task('removeFeatureFlagTarget', {
+      flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+      userId: testUserId,
+    });
+  });
+
+  it('should use NEW checkout flow when flag is ENABLED', () => {
+    // Arrange: Enable flag via Cypress task
+    cy.task('setFeatureFlagVariation', {
+      flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+      userId: testUserId,
+      variation: true,
+    });
+
+    // Act
+    cy.visit('/checkout', {
+      headers: { 'X-Test-User-ID': testUserId },
+    });
+
+    // Assert
+    cy.get('[data-testid="checkout-v2-container"]').should('be.visible');
+    cy.get('[data-testid="checkout-v1-container"]').should('not.exist');
+  });
+
+  it('should use LEGACY checkout flow when flag is DISABLED', () => {
+    // Arrange: Disable flag
+    cy.task('setFeatureFlagVariation', {
+      flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+      userId: testUserId,
+      variation: false,
+    });
+
+    // Act
+    cy.visit('/checkout', {
+      headers: { 'X-Test-User-ID': testUserId },
+    });
+
+    // Assert
+    cy.get('[data-testid="checkout-v1-container"]').should('be.visible');
+    cy.get('[data-testid="checkout-v2-container"]').should('not.exist');
+  });
+});
+```
+
+**Key Points**:
+
+- **Test both states**: Enabled AND disabled variations
+- **Automatic cleanup**: afterEach removes targeting (prevent pollution)
+- **Unique test users**: Avoid conflicts with real user data
+- **Telemetry validation**: Verify analytics events fire correctly
+- **Graceful degradation**: Test fallback behavior on errors
+
+---
+
+### Example 3: Feature Flag Targeting Helper Pattern
+
+**Context**: Reusable helpers for programmatic flag control via LaunchDarkly/Split.io API.
+
+**Implementation**:
+
+```typescript
+// tests/support/feature-flag-helpers.ts
+import { request as playwrightRequest } from '@playwright/test';
+import { FLAGS, FlagKey } from '@/utils/feature-flags';
+
+/**
+ * LaunchDarkly API client configuration
+ * Use test project SDK key (NOT production)
+ */
+const LD_SDK_KEY = process.env.LD_SDK_KEY_TEST;
+const LD_API_BASE = 'https://app.launchdarkly.com/api/v2';
+
+type FlagVariation = boolean | string | number | object;
+
+/**
+ * Set flag variation for specific user
+ * Uses LaunchDarkly API to create user target
+ */
+export async function setFlagForUser(flagKey: FlagKey, userId: string, variation: FlagVariation): Promise<void> {
+  const response = await playwrightRequest.newContext().then((ctx) =>
+    ctx.post(`${LD_API_BASE}/flags/${flagKey}/targeting`, {
+      headers: {
+        Authorization: LD_SDK_KEY!,
+        'Content-Type': 'application/json',
+      },
+      data: {
+        targets: [
+          {
+            values: [userId],
+            variation: variation ? 1 : 0, // 0 = off, 1 = on
+          },
+        ],
+      },
+    }),
+  );
+
+  if (!response.ok()) {
+    throw new Error(`Failed to set flag ${flagKey} for user ${userId}: ${response.status()}`);
+  }
+}
+
+/**
+ * Remove user from flag targeting
+ * CRITICAL for test cleanup
+ */
+export async function removeFlagTarget(flagKey: FlagKey, userId: string): Promise<void> {
+  const response = await playwrightRequest.newContext().then((ctx) =>
+    ctx.delete(`${LD_API_BASE}/flags/${flagKey}/targeting/users/${userId}`, {
+      headers: {
+        Authorization: LD_SDK_KEY!,
+      },
+    }),
+  );
+
+  if (!response.ok() && response.status() !== 404) {
+    // 404 is acceptable (user wasn't targeted)
+    throw new Error(`Failed to remove flag ${flagKey} target for user ${userId}: ${response.status()}`);
+  }
+}
+
+/**
+ * Percentage rollout helper
+ * Enable flag for N% of users
+ */
+export async function setFlagRolloutPercentage(flagKey: FlagKey, percentage: number): Promise<void> {
+  if (percentage < 0 || percentage > 100) {
+    throw new Error('Percentage must be between 0 and 100');
+  }
+
+  const response = await playwrightRequest.newContext().then((ctx) =>
+    ctx.patch(`${LD_API_BASE}/flags/${flagKey}`, {
+      headers: {
+        Authorization: LD_SDK_KEY!,
+        'Content-Type': 'application/json',
+      },
+      data: {
+        rollout: {
+          variations: [
+            { variation: 0, weight: 100 - percentage }, // off
+            { variation: 1, weight: percentage }, // on
+          ],
+        },
+      },
+    }),
+  );
+
+  if (!response.ok()) {
+    throw new Error(`Failed to set rollout for flag ${flagKey}: ${response.status()}`);
+  }
+}
+
+/**
+ * Enable flag globally (100% rollout)
+ */
+export async function enableFlagGlobally(flagKey: FlagKey): Promise<void> {
+  await setFlagRolloutPercentage(flagKey, 100);
+}
+
+/**
+ * Disable flag globally (0% rollout)
+ */
+export async function disableFlagGlobally(flagKey: FlagKey): Promise<void> {
+  await setFlagRolloutPercentage(flagKey, 0);
+}
+
+/**
+ * Stub feature flags in local/test environments
+ * Bypasses LaunchDarkly entirely
+ */
+export function stubFeatureFlags(flags: Record<FlagKey, FlagVariation>): void {
+  // Set flags in localStorage or inject into window
+  if (typeof window !== 'undefined') {
+    (window as any).__STUBBED_FLAGS__ = flags;
+  }
+}
+```
+
+**Usage in Playwright fixture**:
+
+```typescript
+// playwright/fixtures/feature-flag-fixture.ts
+import { test as base } from '@playwright/test';
+import { setFlagForUser, removeFlagTarget } from '../support/feature-flag-helpers';
+import { FlagKey } from '@/utils/feature-flags';
+
+type FeatureFlagFixture = {
+  featureFlags: {
+    enable: (flag: FlagKey, userId: string) => Promise<void>;
+    disable: (flag: FlagKey, userId: string) => Promise<void>;
+    cleanup: (flag: FlagKey, userId: string) => Promise<void>;
+  };
+};
+
+export const test = base.extend<FeatureFlagFixture>({
+  featureFlags: async ({}, use) => {
+    const cleanupQueue: Array<{ flag: FlagKey; userId: string }> = [];
+
+    await use({
+      enable: async (flag, userId) => {
+        await setFlagForUser(flag, userId, true);
+        cleanupQueue.push({ flag, userId });
+      },
+      disable: async (flag, userId) => {
+        await setFlagForUser(flag, userId, false);
+        cleanupQueue.push({ flag, userId });
+      },
+      cleanup: async (flag, userId) => {
+        await removeFlagTarget(flag, userId);
+      },
+    });
+
+    // Auto-cleanup after test
+    for (const { flag, userId } of cleanupQueue) {
+      await removeFlagTarget(flag, userId);
+    }
+  },
+});
+```
+
+**Key Points**:
+
+- **API-driven control**: No manual UI clicks required
+- **Auto-cleanup**: Fixture tracks and removes targeting
+- **Percentage rollouts**: Test gradual feature releases
+- **Stubbing option**: Local development without LaunchDarkly
+- **Type-safe**: FlagKey prevents typos
+
+---
+
+### Example 4: Feature Flag Lifecycle Checklist & Cleanup Strategy
+
+**Context**: Governance checklist and automated cleanup detection for stale flags.
+
+**Implementation**:
+
+```typescript
+// scripts/feature-flag-audit.ts
+/**
+ * Feature Flag Lifecycle Audit Script
+ * Run weekly to detect stale flags requiring cleanup
+ */
+
+import { FLAG_REGISTRY, FLAGS, getExpiredFlags, FlagKey } from '../src/utils/feature-flags';
+import * as fs from 'fs';
+import * as path from 'path';
+
+type AuditResult = {
+  totalFlags: number;
+  expiredFlags: FlagKey[];
+  missingOwners: FlagKey[];
+  missingDates: FlagKey[];
+  permanentFlags: FlagKey[];
+  flagsNearingExpiry: FlagKey[];
+};
+
+/**
+ * Audit all feature flags for governance compliance
+ */
+function auditFeatureFlags(): AuditResult {
+  const allFlags = Object.keys(FLAG_REGISTRY) as FlagKey[];
+  const expiredFlags = getExpiredFlags().map((meta) => meta.key);
+
+  // Flags expiring in next 30 days
+  const thirtyDaysFromNow = Date.now() + 30 * 24 * 60 * 60 * 1000;
+  const flagsNearingExpiry = allFlags.filter((flag) => {
+    const meta = FLAG_REGISTRY[flag];
+    if (!meta.expiryDate) return false;
+    const expiry = new Date(meta.expiryDate).getTime();
+    return expiry > Date.now() && expiry < thirtyDaysFromNow;
+  });
+
+  // Missing metadata
+  const missingOwners = allFlags.filter((flag) => !FLAG_REGISTRY[flag].owner);
+  const missingDates = allFlags.filter((flag) => !FLAG_REGISTRY[flag].createdDate);
+
+  // Permanent flags (no expiry, requiresCleanup = false)
+  const permanentFlags = allFlags.filter((flag) => {
+    const meta = FLAG_REGISTRY[flag];
+    return !meta.expiryDate && !meta.requiresCleanup;
+  });
+
+  return {
+    totalFlags: allFlags.length,
+    expiredFlags,
+    missingOwners,
+    missingDates,
+    permanentFlags,
+    flagsNearingExpiry,
+  };
+}
+
+/**
+ * Generate markdown report
+ */
+function generateReport(audit: AuditResult): string {
+  let report = `# Feature Flag Audit Report\n\n`;
+  report += `**Date**: ${new Date().toISOString()}\n`;
+  report += `**Total Flags**: ${audit.totalFlags}\n\n`;
+
+  if (audit.expiredFlags.length > 0) {
+    report += `## ⚠️ EXPIRED FLAGS - IMMEDIATE CLEANUP REQUIRED\n\n`;
+    audit.expiredFlags.forEach((flag) => {
+      const meta = FLAG_REGISTRY[flag];
+      report += `- **${meta.name}** (\`${flag}\`)\n`;
+      report += `  - Owner: ${meta.owner}\n`;
+      report += `  - Expired: ${meta.expiryDate}\n`;
+      report += `  - Action: Remove flag code, update tests, deploy\n\n`;
+    });
+  }
+
+  if (audit.flagsNearingExpiry.length > 0) {
+    report += `## ⏰ FLAGS EXPIRING SOON (Next 30 Days)\n\n`;
+    audit.flagsNearingExpiry.forEach((flag) => {
+      const meta = FLAG_REGISTRY[flag];
+      report += `- **${meta.name}** (\`${flag}\`)\n`;
+      report += `  - Owner: ${meta.owner}\n`;
+      report += `  - Expires: ${meta.expiryDate}\n`;
+      report += `  - Action: Plan cleanup or extend expiry\n\n`;
+    });
+  }
+
+  if (audit.permanentFlags.length > 0) {
+    report += `## 🔄 PERMANENT FLAGS (No Expiry)\n\n`;
+    audit.permanentFlags.forEach((flag) => {
+      const meta = FLAG_REGISTRY[flag];
+      report += `- **${meta.name}** (\`${flag}\`) - Owner: ${meta.owner}\n`;
+    });
+    report += `\n`;
+  }
+
+  if (audit.missingOwners.length > 0 || audit.missingDates.length > 0) {
+    report += `## ❌ GOVERNANCE ISSUES\n\n`;
+    if (audit.missingOwners.length > 0) {
+      report += `**Missing Owners**: ${audit.missingOwners.join(', ')}\n`;
+    }
+    if (audit.missingDates.length > 0) {
+      report += `**Missing Created Dates**: ${audit.missingDates.join(', ')}\n`;
+    }
+    report += `\n`;
+  }
+
+  return report;
+}
+
+/**
+ * Feature Flag Lifecycle Checklist
+ */
+const FLAG_LIFECYCLE_CHECKLIST = `
+# Feature Flag Lifecycle Checklist
+
+## Before Creating a New Flag
+
+- [ ] **Name**: Follow naming convention (kebab-case, descriptive)
+- [ ] **Owner**: Assign team/individual responsible
+- [ ] **Default State**: Determine safe default (usually false)
+- [ ] **Expiry Date**: Set removal date (30-90 days typical)
+- [ ] **Dependencies**: Document related flags
+- [ ] **Telemetry**: Plan analytics events to track
+- [ ] **Rollback Plan**: Define how to disable quickly
+
+## During Development
+
+- [ ] **Code Paths**: Both enabled/disabled states implemented
+- [ ] **Tests**: Both variations tested in CI
+- [ ] **Documentation**: Flag purpose documented in code/PR
+- [ ] **Telemetry**: Analytics events instrumented
+- [ ] **Error Handling**: Graceful degradation on flag service failure
+
+## Before Launch
+
+- [ ] **QA**: Both states tested in staging
+- [ ] **Rollout Plan**: Gradual rollout percentage defined
+- [ ] **Monitoring**: Dashboards/alerts for flag-related metrics
+- [ ] **Stakeholder Communication**: Product/design aligned
+
+## After Launch (Monitoring)
+
+- [ ] **Metrics**: Success criteria tracked
+- [ ] **Error Rates**: No increase in errors
+- [ ] **Performance**: No degradation
+- [ ] **User Feedback**: Qualitative data collected
+
+## Cleanup (Post-Launch)
+
+- [ ] **Remove Flag Code**: Delete if/else branches
+- [ ] **Update Tests**: Remove flag-specific tests
+- [ ] **Remove Targeting**: Clear all user targets
+- [ ] **Delete Flag Config**: Remove from LaunchDarkly/registry
+- [ ] **Update Documentation**: Remove references
+- [ ] **Deploy**: Ship cleanup changes
+`;
+
+// Run audit
+const audit = auditFeatureFlags();
+const report = generateReport(audit);
+
+// Save report
+const outputPath = path.join(__dirname, '../feature-flag-audit-report.md');
+fs.writeFileSync(outputPath, report);
+fs.writeFileSync(path.join(__dirname, '../FEATURE-FLAG-CHECKLIST.md'), FLAG_LIFECYCLE_CHECKLIST);
+
+console.log(`✅ Audit complete. Report saved to: ${outputPath}`);
+console.log(`Total flags: ${audit.totalFlags}`);
+console.log(`Expired flags: ${audit.expiredFlags.length}`);
+console.log(`Flags expiring soon: ${audit.flagsNearingExpiry.length}`);
+
+// Exit with error if expired flags exist
+if (audit.expiredFlags.length > 0) {
+  console.error(`\n❌ EXPIRED FLAGS DETECTED - CLEANUP REQUIRED`);
+  process.exit(1);
+}
+```
+
+**package.json scripts**:
+
+```json
+{
+  "scripts": {
+    "feature-flags:audit": "ts-node scripts/feature-flag-audit.ts",
+    "feature-flags:audit:ci": "npm run feature-flags:audit || true"
+  }
+}
+```
+
+**Key Points**:
+
+- **Automated detection**: Weekly audit catches stale flags
+- **Lifecycle checklist**: Comprehensive governance guide
+- **Expiry tracking**: Flags auto-expire after defined date
+- **CI integration**: Audit runs in pipeline, warns on expiry
+- **Ownership clarity**: Every flag has assigned owner
+
+---
+
+## Feature Flag Testing Checklist
+
+Before merging flag-related code, verify:
+
+- [ ] **Both states tested**: Enabled AND disabled variations covered
+- [ ] **Cleanup automated**: afterEach removes targeting (no manual cleanup)
+- [ ] **Unique test data**: Test users don't collide with production
+- [ ] **Telemetry validated**: Analytics events fire for both variations
+- [ ] **Error handling**: Graceful fallback when flag service unavailable
+- [ ] **Flag metadata**: Owner, dates, dependencies documented in registry
+- [ ] **Rollback plan**: Clear steps to disable flag in production
+- [ ] **Expiry date set**: Removal date defined (or marked permanent)
+
+## Integration Points
+
+- Used in workflows: `*automate` (test generation), `*framework` (flag setup)
+- Related fragments: `test-quality.md`, `selective-testing.md`
+- Flag services: LaunchDarkly, Split.io, Unleash, custom implementations
+
+_Source: LaunchDarkly strategy blog, Murat test architecture notes, SEON feature flag governance_

_bmad/bmm/testarch/knowledge/file-utils.md

@@ -0,0 +1,260 @@
+# File Utilities
+
+## Principle
+
+Read and validate files (CSV, XLSX, PDF, ZIP) with automatic parsing, type-safe results, and download handling. Simplify file operations in Playwright tests with built-in format support and validation helpers.
+
+## Rationale
+
+Testing file operations in Playwright requires boilerplate:
+
+- Manual download handling
+- External parsing libraries for each format
+- No validation helpers
+- Type-unsafe results
+- Repetitive path handling
+
+The `file-utils` module provides:
+
+- **Auto-parsing**: CSV, XLSX, PDF, ZIP automatically parsed
+- **Download handling**: Single function for UI or API-triggered downloads
+- **Type-safe**: TypeScript interfaces for parsed results
+- **Validation helpers**: Row count, header checks, content validation
+- **Format support**: Multiple sheet support (XLSX), text extraction (PDF), archive extraction (ZIP)
+
+## Pattern Examples
+
+### Example 1: UI-Triggered CSV Download
+
+**Context**: User clicks button, CSV downloads, validate contents.
+
+**Implementation**:
+
+```typescript
+import { handleDownload, readCSV } from '@seontechnologies/playwright-utils/file-utils';
+import path from 'node:path';
+
+const DOWNLOAD_DIR = path.join(__dirname, '../downloads');
+
+test('should download and validate CSV', async ({ page }) => {
+  const downloadPath = await handleDownload({
+    page,
+    downloadDir: DOWNLOAD_DIR,
+    trigger: () => page.click('[data-testid="export-csv"]'),
+  });
+
+  const { content } = await readCSV({ filePath: downloadPath });
+
+  // Validate headers
+  expect(content.headers).toEqual(['ID', 'Name', 'Email', 'Role']);
+
+  // Validate data
+  expect(content.data).toHaveLength(10);
+  expect(content.data[0]).toMatchObject({
+    ID: expect.any(String),
+    Name: expect.any(String),
+    Email: expect.stringMatching(/@/),
+  });
+});
+```
+
+**Key Points**:
+
+- `handleDownload` waits for download, returns file path
+- `readCSV` auto-parses to `{ headers, data }`
+- Type-safe access to parsed content
+- Clean up downloads in `afterEach`
+
+### Example 2: XLSX with Multiple Sheets
+
+**Context**: Excel file with multiple sheets (e.g., Summary, Details, Errors).
+
+**Implementation**:
+
+```typescript
+import { readXLSX } from '@seontechnologies/playwright-utils/file-utils';
+
+test('should read multi-sheet XLSX', async () => {
+  const downloadPath = await handleDownload({
+    page,
+    downloadDir: DOWNLOAD_DIR,
+    trigger: () => page.click('[data-testid="export-xlsx"]'),
+  });
+
+  const { content } = await readXLSX({ filePath: downloadPath });
+
+  // Access specific sheets
+  const summarySheet = content.sheets.find((s) => s.name === 'Summary');
+  const detailsSheet = content.sheets.find((s) => s.name === 'Details');
+
+  // Validate summary
+  expect(summarySheet.data).toHaveLength(1);
+  expect(summarySheet.data[0].TotalRecords).toBe('150');
+
+  // Validate details
+  expect(detailsSheet.data).toHaveLength(150);
+  expect(detailsSheet.headers).toContain('TransactionID');
+});
+```
+
+**Key Points**:
+
+- `sheets` array with `name` and `data` properties
+- Access sheets by name
+- Each sheet has its own headers and data
+- Type-safe sheet iteration
+
+### Example 3: PDF Text Extraction
+
+**Context**: Validate PDF report contains expected content.
+
+**Implementation**:
+
+```typescript
+import { readPDF } from '@seontechnologies/playwright-utils/file-utils';
+
+test('should validate PDF report', async () => {
+  const downloadPath = await handleDownload({
+    page,
+    downloadDir: DOWNLOAD_DIR,
+    trigger: () => page.click('[data-testid="download-report"]'),
+  });
+
+  const { content } = await readPDF({ filePath: downloadPath });
+
+  // content.text is extracted text from all pages
+  expect(content.text).toContain('Financial Report Q4 2024');
+  expect(content.text).toContain('Total Revenue:');
+
+  // Validate page count
+  expect(content.numpages).toBeGreaterThan(10);
+});
+```
+
+**Key Points**:
+
+- `content.text` contains all extracted text
+- `content.numpages` for page count
+- PDF parsing handles multi-page documents
+- Search for specific phrases
+
+### Example 4: ZIP Archive Validation
+
+**Context**: Validate ZIP contains expected files and extract specific file.
+
+**Implementation**:
+
+```typescript
+import { readZIP } from '@seontechnologies/playwright-utils/file-utils';
+
+test('should validate ZIP archive', async () => {
+  const downloadPath = await handleDownload({
+    page,
+    downloadDir: DOWNLOAD_DIR,
+    trigger: () => page.click('[data-testid="download-backup"]'),
+  });
+
+  const { content } = await readZIP({ filePath: downloadPath });
+
+  // Check file list
+  expect(content.files).toContain('data.csv');
+  expect(content.files).toContain('config.json');
+  expect(content.files).toContain('readme.txt');
+
+  // Read specific file from archive
+  const configContent = content.zip.readAsText('config.json');
+  const config = JSON.parse(configContent);
+
+  expect(config.version).toBe('2.0');
+});
+```
+
+**Key Points**:
+
+- `content.files` lists all files in archive
+- `content.zip.readAsText()` extracts specific files
+- Validate archive structure
+- Read and parse individual files from ZIP
+
+### Example 5: API-Triggered Download
+
+**Context**: API endpoint returns file download (not UI click).
+
+**Implementation**:
+
+```typescript
+test('should download via API', async ({ page, request }) => {
+  const downloadPath = await handleDownload({
+    page,
+    downloadDir: DOWNLOAD_DIR,
+    trigger: async () => {
+      const response = await request.get('/api/export/csv', {
+        headers: { Authorization: 'Bearer token' },
+      });
+
+      if (!response.ok()) {
+        throw new Error(`Export failed: ${response.status()}`);
+      }
+    },
+  });
+
+  const { content } = await readCSV({ filePath: downloadPath });
+
+  expect(content.data).toHaveLength(100);
+});
+```
+
+**Key Points**:
+
+- `trigger` can be async API call
+- API must return `Content-Disposition` header
+- Still need `page` for download events
+- Works with authenticated endpoints
+
+## Validation Helpers
+
+```typescript
+// CSV validation
+const { isValid, errors } = await validateCSV({
+  filePath: downloadPath,
+  expectedRowCount: 10,
+  requiredHeaders: ['ID', 'Name', 'Email'],
+});
+
+expect(isValid).toBe(true);
+expect(errors).toHaveLength(0);
+```
+
+## Download Cleanup Pattern
+
+```typescript
+test.afterEach(async () => {
+  // Clean up downloaded files
+  await fs.remove(DOWNLOAD_DIR);
+});
+```
+
+## Related Fragments
+
+- `overview.md` - Installation and imports
+- `api-request.md` - API-triggered downloads
+- `recurse.md` - Poll for file generation completion
+
+## Anti-Patterns
+
+**❌ Not cleaning up downloads:**
+
+```typescript
+test('creates file', async () => {
+  await handleDownload({ ... })
+  // File left in downloads folder
+})
+```
+
+**✅ Clean up after tests:**
+
+```typescript
+test.afterEach(async () => {
+  await fs.remove(DOWNLOAD_DIR);
+});
+```

_bmad/bmm/testarch/knowledge/fixture-architecture.md

@@ -0,0 +1,401 @@
+# Fixture Architecture Playbook
+
+## Principle
+
+Build test helpers as pure functions first, then wrap them in framework-specific fixtures. Compose capabilities using `mergeTests` (Playwright) or layered commands (Cypress) instead of inheritance. Each fixture should solve one isolated concern (auth, API, logs, network).
+
+## Rationale
+
+Traditional Page Object Models create tight coupling through inheritance chains (`BasePage → LoginPage → AdminPage`). When base classes change, all descendants break. Pure functions with fixture wrappers provide:
+
+- **Testability**: Pure functions run in unit tests without framework overhead
+- **Composability**: Mix capabilities freely via `mergeTests`, no inheritance constraints
+- **Reusability**: Export fixtures via package subpaths for cross-project sharing
+- **Maintainability**: One concern per fixture = clear responsibility boundaries
+
+## Pattern Examples
+
+### Example 1: Pure Function → Fixture Pattern
+
+**Context**: When building any test helper, always start with a pure function that accepts all dependencies explicitly. Then wrap it in a Playwright fixture or Cypress command.
+
+**Implementation**:
+
+```typescript
+// playwright/support/helpers/api-request.ts
+// Step 1: Pure function (ALWAYS FIRST!)
+type ApiRequestParams = {
+  request: APIRequestContext;
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+  url: string;
+  data?: unknown;
+  headers?: Record<string, string>;
+};
+
+export async function apiRequest({
+  request,
+  method,
+  url,
+  data,
+  headers = {}
+}: ApiRequestParams) {
+  const response = await request.fetch(url, {
+    method,
+    data,
+    headers: {
+      'Content-Type': 'application/json',
+      ...headers
+    }
+  });
+
+  if (!response.ok()) {
+    throw new Error(`API request failed: ${response.status()} ${await response.text()}`);
+  }
+
+  return response.json();
+}
+
+// Step 2: Fixture wrapper
+// playwright/support/fixtures/api-request-fixture.ts
+import { test as base } from '@playwright/test';
+import { apiRequest } from '../helpers/api-request';
+
+export const test = base.extend<{ apiRequest: typeof apiRequest }>({
+  apiRequest: async ({ request }, use) => {
+    // Inject framework dependency, expose pure function
+    await use((params) => apiRequest({ request, ...params }));
+  }
+});
+
+// Step 3: Package exports for reusability
+// package.json
+{
+  "exports": {
+    "./api-request": "./playwright/support/helpers/api-request.ts",
+    "./api-request/fixtures": "./playwright/support/fixtures/api-request-fixture.ts"
+  }
+}
+```
+
+**Key Points**:
+
+- Pure function is unit-testable without Playwright running
+- Framework dependency (`request`) injected at fixture boundary
+- Fixture exposes the pure function to test context
+- Package subpath exports enable `import { apiRequest } from 'my-fixtures/api-request'`
+
+### Example 2: Composable Fixture System with mergeTests
+
+**Context**: When building comprehensive test capabilities, compose multiple focused fixtures instead of creating monolithic helper classes. Each fixture provides one capability.
+
+**Implementation**:
+
+```typescript
+// playwright/support/fixtures/merged-fixtures.ts
+import { test as base, mergeTests } from '@playwright/test';
+import { test as apiRequestFixture } from './api-request-fixture';
+import { test as networkFixture } from './network-fixture';
+import { test as authFixture } from './auth-fixture';
+import { test as logFixture } from './log-fixture';
+
+// Compose all fixtures for comprehensive capabilities
+export const test = mergeTests(base, apiRequestFixture, networkFixture, authFixture, logFixture);
+
+export { expect } from '@playwright/test';
+
+// Example usage in tests:
+// import { test, expect } from './support/fixtures/merged-fixtures';
+//
+// test('user can create order', async ({ page, apiRequest, auth, network }) => {
+//   await auth.loginAs('customer@example.com');
+//   await network.interceptRoute('POST', '**/api/orders', { id: 123 });
+//   await page.goto('/checkout');
+//   await page.click('[data-testid="submit-order"]');
+//   await expect(page.getByText('Order #123')).toBeVisible();
+// });
+```
+
+**Individual Fixture Examples**:
+
+```typescript
+// network-fixture.ts
+export const test = base.extend({
+  network: async ({ page }, use) => {
+    const interceptedRoutes = new Map();
+
+    const interceptRoute = async (method: string, url: string, response: unknown) => {
+      await page.route(url, (route) => {
+        if (route.request().method() === method) {
+          route.fulfill({ body: JSON.stringify(response) });
+        }
+      });
+      interceptedRoutes.set(`${method}:${url}`, response);
+    };
+
+    await use({ interceptRoute });
+
+    // Cleanup
+    interceptedRoutes.clear();
+  },
+});
+
+// auth-fixture.ts
+export const test = base.extend({
+  auth: async ({ page, context }, use) => {
+    const loginAs = async (email: string) => {
+      // Use API to setup auth (fast!)
+      const token = await getAuthToken(email);
+      await context.addCookies([
+        {
+          name: 'auth_token',
+          value: token,
+          domain: 'localhost',
+          path: '/',
+        },
+      ]);
+    };
+
+    await use({ loginAs });
+  },
+});
+```
+
+**Key Points**:
+
+- `mergeTests` combines fixtures without inheritance
+- Each fixture has single responsibility (network, auth, logs)
+- Tests import merged fixture and access all capabilities
+- No coupling between fixtures—add/remove freely
+
+### Example 3: Framework-Agnostic HTTP Helper
+
+**Context**: When building HTTP helpers, keep them framework-agnostic. Accept all params explicitly so they work in unit tests, Playwright, Cypress, or any context.
+
+**Implementation**:
+
+```typescript
+// shared/helpers/http-helper.ts
+// Pure, framework-agnostic function
+type HttpHelperParams = {
+  baseUrl: string;
+  endpoint: string;
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+  body?: unknown;
+  headers?: Record<string, string>;
+  token?: string;
+};
+
+export async function makeHttpRequest({ baseUrl, endpoint, method, body, headers = {}, token }: HttpHelperParams): Promise<unknown> {
+  const url = `${baseUrl}${endpoint}`;
+  const requestHeaders = {
+    'Content-Type': 'application/json',
+    ...(token && { Authorization: `Bearer ${token}` }),
+    ...headers,
+  };
+
+  const response = await fetch(url, {
+    method,
+    headers: requestHeaders,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`HTTP ${method} ${url} failed: ${response.status} ${errorText}`);
+  }
+
+  return response.json();
+}
+
+// Playwright fixture wrapper
+// playwright/support/fixtures/http-fixture.ts
+import { test as base } from '@playwright/test';
+import { makeHttpRequest } from '../../shared/helpers/http-helper';
+
+export const test = base.extend({
+  httpHelper: async ({}, use) => {
+    const baseUrl = process.env.API_BASE_URL || 'http://localhost:3000';
+
+    await use((params) => makeHttpRequest({ baseUrl, ...params }));
+  },
+});
+
+// Cypress command wrapper
+// cypress/support/commands.ts
+import { makeHttpRequest } from '../../shared/helpers/http-helper';
+
+Cypress.Commands.add('apiRequest', (params) => {
+  const baseUrl = Cypress.env('API_BASE_URL') || 'http://localhost:3000';
+  return cy.wrap(makeHttpRequest({ baseUrl, ...params }));
+});
+```
+
+**Key Points**:
+
+- Pure function uses only standard `fetch`, no framework dependencies
+- Unit tests call `makeHttpRequest` directly with all params
+- Playwright and Cypress wrappers inject framework-specific config
+- Same logic runs everywhere—zero duplication
+
+### Example 4: Fixture Cleanup Pattern
+
+**Context**: When fixtures create resources (data, files, connections), ensure automatic cleanup in fixture teardown. Tests must not leak state.
+
+**Implementation**:
+
+```typescript
+// playwright/support/fixtures/database-fixture.ts
+import { test as base } from '@playwright/test';
+import { seedDatabase, deleteRecord } from '../helpers/db-helpers';
+
+type DatabaseFixture = {
+  seedUser: (userData: Partial<User>) => Promise<User>;
+  seedOrder: (orderData: Partial<Order>) => Promise<Order>;
+};
+
+export const test = base.extend<DatabaseFixture>({
+  seedUser: async ({}, use) => {
+    const createdUsers: string[] = [];
+
+    const seedUser = async (userData: Partial<User>) => {
+      const user = await seedDatabase('users', userData);
+      createdUsers.push(user.id);
+      return user;
+    };
+
+    await use(seedUser);
+
+    // Auto-cleanup: Delete all users created during test
+    for (const userId of createdUsers) {
+      await deleteRecord('users', userId);
+    }
+    createdUsers.length = 0;
+  },
+
+  seedOrder: async ({}, use) => {
+    const createdOrders: string[] = [];
+
+    const seedOrder = async (orderData: Partial<Order>) => {
+      const order = await seedDatabase('orders', orderData);
+      createdOrders.push(order.id);
+      return order;
+    };
+
+    await use(seedOrder);
+
+    // Auto-cleanup: Delete all orders
+    for (const orderId of createdOrders) {
+      await deleteRecord('orders', orderId);
+    }
+    createdOrders.length = 0;
+  },
+});
+
+// Example usage:
+// test('user can place order', async ({ seedUser, seedOrder, page }) => {
+//   const user = await seedUser({ email: 'test@example.com' });
+//   const order = await seedOrder({ userId: user.id, total: 100 });
+//
+//   await page.goto(`/orders/${order.id}`);
+//   await expect(page.getByText('Order Total: $100')).toBeVisible();
+//
+//   // No manual cleanup needed—fixture handles it automatically
+// });
+```
+
+**Key Points**:
+
+- Track all created resources in array during test execution
+- Teardown (after `use()`) deletes all tracked resources
+- Tests don't manually clean up—happens automatically
+- Prevents test pollution and flakiness from shared state
+
+### Anti-Pattern: Inheritance-Based Page Objects
+
+**Problem**:
+
+```typescript
+// ❌ BAD: Page Object Model with inheritance
+class BasePage {
+  constructor(public page: Page) {}
+
+  async navigate(url: string) {
+    await this.page.goto(url);
+  }
+
+  async clickButton(selector: string) {
+    await this.page.click(selector);
+  }
+}
+
+class LoginPage extends BasePage {
+  async login(email: string, password: string) {
+    await this.navigate('/login');
+    await this.page.fill('#email', email);
+    await this.page.fill('#password', password);
+    await this.clickButton('#submit');
+  }
+}
+
+class AdminPage extends LoginPage {
+  async accessAdminPanel() {
+    await this.login('admin@example.com', 'admin123');
+    await this.navigate('/admin');
+  }
+}
+```
+
+**Why It Fails**:
+
+- Changes to `BasePage` break all descendants (`LoginPage`, `AdminPage`)
+- `AdminPage` inherits unnecessary `login` details—tight coupling
+- Cannot compose capabilities (e.g., admin + reporting features require multiple inheritance)
+- Hard to test `BasePage` methods in isolation
+- Hidden state in class instances leads to unpredictable behavior
+
+**Better Approach**: Use pure functions + fixtures
+
+```typescript
+// ✅ GOOD: Pure functions with fixture composition
+// helpers/navigation.ts
+export async function navigate(page: Page, url: string) {
+  await page.goto(url);
+}
+
+// helpers/auth.ts
+export async function login(page: Page, email: string, password: string) {
+  await page.fill('[data-testid="email"]', email);
+  await page.fill('[data-testid="password"]', password);
+  await page.click('[data-testid="submit"]');
+}
+
+// fixtures/admin-fixture.ts
+export const test = base.extend({
+  adminPage: async ({ page }, use) => {
+    await login(page, 'admin@example.com', 'admin123');
+    await navigate(page, '/admin');
+    await use(page);
+  },
+});
+
+// Tests import exactly what they need—no inheritance
+```
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (test generation), `*automate` (test expansion), `*framework` (initial setup)
+- **Related fragments**:
+  - `data-factories.md` - Factory functions for test data
+  - `network-first.md` - Network interception patterns
+  - `test-quality.md` - Deterministic test design principles
+
+## Helper Function Reuse Guidelines
+
+When deciding whether to create a fixture, follow these rules:
+
+- **3+ uses** → Create fixture with subpath export (shared across tests/projects)
+- **2-3 uses** → Create utility module (shared within project)
+- **1 use** → Keep inline (avoid premature abstraction)
+- **Complex logic** → Factory function pattern (dynamic data generation)
+
+_Source: Murat Testing Philosophy (lines 74-122), SEON production patterns, Playwright fixture docs._

_bmad/bmm/testarch/knowledge/fixtures-composition.md

@@ -0,0 +1,382 @@
+# Fixtures Composition with mergeTests
+
+## Principle
+
+Combine multiple Playwright fixtures using `mergeTests` to create a unified test object with all capabilities. Build composable test infrastructure by merging playwright-utils fixtures with custom project fixtures.
+
+## Rationale
+
+Using fixtures from multiple sources requires combining them:
+
+- Importing from multiple fixture files is verbose
+- Name conflicts between fixtures
+- Duplicate fixture definitions
+- No clear single test object
+
+Playwright's `mergeTests` provides:
+
+- **Single test object**: All fixtures in one import
+- **Conflict resolution**: Handles name collisions automatically
+- **Composition pattern**: Mix utilities, custom fixtures, third-party fixtures
+- **Type safety**: Full TypeScript support for merged fixtures
+- **Maintainability**: One place to manage all fixtures
+
+## Pattern Examples
+
+### Example 1: Basic Fixture Merging
+
+**Context**: Combine multiple playwright-utils fixtures into single test object.
+
+**Implementation**:
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { mergeTests } from '@playwright/test';
+import { test as apiRequestFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as recurseFixture } from '@seontechnologies/playwright-utils/recurse/fixtures';
+
+// Merge all fixtures
+export const test = mergeTests(apiRequestFixture, authFixture, recurseFixture);
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// In your tests - import from merged fixtures
+import { test, expect } from '../support/merged-fixtures';
+
+test('all utilities available', async ({
+  apiRequest, // From api-request fixture
+  authToken, // From auth fixture
+  recurse, // From recurse fixture
+}) => {
+  // All fixtures available in single test signature
+  const { body } = await apiRequest({
+    method: 'GET',
+    path: '/api/protected',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  await recurse(
+    () => apiRequest({ method: 'GET', path: `/status/${body.id}` }),
+    (res) => res.body.ready === true,
+  );
+});
+```
+
+**Key Points**:
+
+- Create one `merged-fixtures.ts` per project
+- Import test object from merged fixtures in all test files
+- All utilities available without multiple imports
+- Type-safe access to all fixtures
+
+### Example 2: Combining with Custom Fixtures
+
+**Context**: Add project-specific fixtures alongside playwright-utils.
+
+**Implementation**:
+
+```typescript
+// playwright/support/custom-fixtures.ts - Your project fixtures
+import { test as base } from '@playwright/test';
+import { createUser } from './factories/user-factory';
+import { seedDatabase } from './helpers/db-seeder';
+
+export const test = base.extend({
+  // Custom fixture 1: Auto-seeded user
+  testUser: async ({ request }, use) => {
+    const user = await createUser({ role: 'admin' });
+    await seedDatabase('users', [user]);
+    await use(user);
+    // Cleanup happens automatically
+  },
+
+  // Custom fixture 2: Database helpers
+  db: async ({}, use) => {
+    await use({
+      seed: seedDatabase,
+      clear: () => seedDatabase.truncate(),
+    });
+  },
+});
+
+// playwright/support/merged-fixtures.ts - Combine everything
+import { mergeTests } from '@playwright/test';
+import { test as apiRequestFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as customFixtures } from './custom-fixtures';
+
+export const test = mergeTests(
+  apiRequestFixture,
+  authFixture,
+  customFixtures, // Your project fixtures
+);
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// In tests - all fixtures available
+import { test, expect } from '../support/merged-fixtures';
+
+test('using mixed fixtures', async ({
+  apiRequest, // playwright-utils
+  authToken, // playwright-utils
+  testUser, // custom
+  db, // custom
+}) => {
+  // Use playwright-utils
+  const { body } = await apiRequest({
+    method: 'GET',
+    path: `/api/users/${testUser.id}`,
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  // Use custom fixture
+  await db.clear();
+});
+```
+
+**Key Points**:
+
+- Custom fixtures extend `base` test
+- Merge custom with playwright-utils fixtures
+- All available in one test signature
+- Maintainable separation of concerns
+
+### Example 3: Full Utility Suite Integration
+
+**Context**: Production setup with all core playwright-utils and custom fixtures.
+
+**Implementation**:
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { mergeTests } from '@playwright/test';
+
+// Playwright utils fixtures
+import { test as apiRequestFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as interceptFixture } from '@seontechnologies/playwright-utils/intercept-network-call/fixtures';
+import { test as recurseFixture } from '@seontechnologies/playwright-utils/recurse/fixtures';
+import { test as networkRecorderFixture } from '@seontechnologies/playwright-utils/network-recorder/fixtures';
+
+// Custom project fixtures
+import { test as customFixtures } from './custom-fixtures';
+
+// Merge everything
+export const test = mergeTests(apiRequestFixture, authFixture, interceptFixture, recurseFixture, networkRecorderFixture, customFixtures);
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// In tests
+import { test, expect } from '../support/merged-fixtures';
+
+test('full integration', async ({
+  page,
+  context,
+  apiRequest,
+  authToken,
+  interceptNetworkCall,
+  recurse,
+  networkRecorder,
+  testUser, // custom
+}) => {
+  // All utilities + custom fixtures available
+  await networkRecorder.setup(context);
+
+  const usersCall = interceptNetworkCall({ url: '**/api/users' });
+
+  await page.goto('/users');
+  const { responseJson } = await usersCall;
+
+  expect(responseJson).toContainEqual(expect.objectContaining({ id: testUser.id }));
+});
+```
+
+**Key Points**:
+
+- One merged-fixtures.ts for entire project
+- Combine all playwright-utils you use
+- Add custom project fixtures
+- Single import in all test files
+
+### Example 4: Fixture Override Pattern
+
+**Context**: Override default options for specific test files or describes.
+
+**Implementation**:
+
+```typescript
+import { test, expect } from '../support/merged-fixtures';
+
+// Override auth options for entire file
+test.use({
+  authOptions: {
+    userIdentifier: 'admin',
+    environment: 'staging',
+  },
+});
+
+test('uses admin on staging', async ({ authToken }) => {
+  // Token is for admin user on staging environment
+});
+
+// Override for specific describe block
+test.describe('manager tests', () => {
+  test.use({
+    authOptions: {
+      userIdentifier: 'manager',
+    },
+  });
+
+  test('manager can access reports', async ({ page }) => {
+    // Uses manager token
+    await page.goto('/reports');
+  });
+});
+```
+
+**Key Points**:
+
+- `test.use()` overrides fixture options
+- Can override at file or describe level
+- Options merge with defaults
+- Type-safe overrides
+
+### Example 5: Avoiding Fixture Conflicts
+
+**Context**: Handle name collisions when merging fixtures with same names.
+
+**Implementation**:
+
+```typescript
+// If two fixtures have same name, last one wins
+import { test as fixture1 } from './fixture1'; // has 'user' fixture
+import { test as fixture2 } from './fixture2'; // also has 'user' fixture
+
+const test = mergeTests(fixture1, fixture2);
+// fixture2's 'user' overrides fixture1's 'user'
+
+// Better: Rename fixtures before merging
+import { test as base } from '@playwright/test';
+import { test as fixture1 } from './fixture1';
+
+const fixture1Renamed = base.extend({
+  user1: fixture1._extend.user, // Rename to avoid conflict
+});
+
+const test = mergeTests(fixture1Renamed, fixture2);
+// Now both 'user1' and 'user' available
+
+// Best: Design fixtures without conflicts
+// - Prefix custom fixtures: 'myAppUser', 'myAppDb'
+// - Playwright-utils uses descriptive names: 'apiRequest', 'authToken'
+```
+
+**Key Points**:
+
+- Last fixture wins in conflicts
+- Rename fixtures to avoid collisions
+- Design fixtures with unique names
+- Playwright-utils uses descriptive names (no conflicts)
+
+## Recommended Project Structure
+
+```
+playwright/
+├── support/
+│   ├── merged-fixtures.ts        # ⭐ Single test object for project
+│   ├── custom-fixtures.ts        # Your project-specific fixtures
+│   ├── auth/
+│   │   ├── auth-fixture.ts       # Auth wrapper (if needed)
+│   │   └── custom-auth-provider.ts
+│   ├── fixtures/
+│   │   ├── user-fixture.ts
+│   │   ├── db-fixture.ts
+│   │   └── api-fixture.ts
+│   └── utils/
+│       └── factories/
+└── tests/
+    ├── api/
+    │   └── users.spec.ts          # import { test } from '../../support/merged-fixtures'
+    ├── e2e/
+    │   └── login.spec.ts          # import { test } from '../../support/merged-fixtures'
+    └── component/
+        └── button.spec.ts         # import { test } from '../../support/merged-fixtures'
+```
+
+## Benefits of Fixture Composition
+
+**Compared to direct imports:**
+
+```typescript
+// ❌ Without mergeTests (verbose)
+import { test as base } from '@playwright/test';
+import { apiRequest } from '@seontechnologies/playwright-utils/api-request';
+import { getAuthToken } from './auth';
+import { createUser } from './factories';
+
+test('verbose', async ({ request }) => {
+  const token = await getAuthToken();
+  const user = await createUser();
+  const response = await apiRequest({ request, method: 'GET', path: '/api/users' });
+  // Manual wiring everywhere
+});
+
+// ✅ With mergeTests (clean)
+import { test } from '../support/merged-fixtures';
+
+test('clean', async ({ apiRequest, authToken, testUser }) => {
+  const { body } = await apiRequest({ method: 'GET', path: '/api/users' });
+  // All fixtures auto-wired
+});
+```
+
+**Reduction:** ~10 lines per test → ~2 lines
+
+## Related Fragments
+
+- `overview.md` - Installation and design principles
+- `api-request.md`, `auth-session.md`, `recurse.md` - Utilities to merge
+- `network-recorder.md`, `intercept-network-call.md`, `log.md` - Additional utilities
+
+## Anti-Patterns
+
+**❌ Importing test from multiple fixture files:**
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+// Also need auth...
+import { test as authTest } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+// Name conflict! Which test to use?
+```
+
+**✅ Use merged fixtures:**
+
+```typescript
+import { test } from '../support/merged-fixtures';
+// All utilities available, no conflicts
+```
+
+**❌ Merging too many fixtures (kitchen sink):**
+
+```typescript
+// Merging 20+ fixtures makes test signature huge
+const test = mergeTests(...20 different fixtures)
+
+test('my test', async ({ fixture1, fixture2, ..., fixture20 }) => {
+  // Cognitive overload
+})
+```
+
+**✅ Merge only what you actually use:**
+
+```typescript
+// Merge the 4-6 fixtures your project actually needs
+const test = mergeTests(apiRequestFixture, authFixture, recurseFixture, customFixtures);
+```

_bmad/bmm/testarch/knowledge/intercept-network-call.md

@@ -0,0 +1,280 @@
+# Intercept Network Call Utility
+
+## Principle
+
+Intercept network requests with a single declarative call that returns a Promise. Automatically parse JSON responses, support both spy (observe) and stub (mock) patterns, and use powerful glob pattern matching for URL filtering.
+
+## Rationale
+
+Vanilla Playwright's network interception requires multiple steps:
+
+- `page.route()` to setup, `page.waitForResponse()` to capture
+- Manual JSON parsing
+- Verbose syntax for conditional handling
+- Complex filter predicates
+
+The `interceptNetworkCall` utility provides:
+
+- **Single declarative call**: Setup and wait in one statement
+- **Automatic JSON parsing**: Response pre-parsed, strongly typed
+- **Flexible URL patterns**: Glob matching with picomatch
+- **Spy or stub modes**: Observe real traffic or mock responses
+- **Concise API**: Reduces boilerplate by 60-70%
+
+## Pattern Examples
+
+### Example 1: Spy on Network (Observe Real Traffic)
+
+**Context**: Capture and inspect real API responses for validation.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/intercept-network-call/fixtures';
+
+test('should spy on users API', async ({ page, interceptNetworkCall }) => {
+  // Setup interception BEFORE navigation
+  const usersCall = interceptNetworkCall({
+    url: '**/api/users', // Glob pattern
+  });
+
+  await page.goto('/dashboard');
+
+  // Wait for response and access parsed data
+  const { responseJson, status } = await usersCall;
+
+  expect(status).toBe(200);
+  expect(responseJson).toHaveLength(10);
+  expect(responseJson[0]).toHaveProperty('name');
+});
+```
+
+**Key Points**:
+
+- Intercept before navigation (critical for race-free tests)
+- Returns Promise with `{ responseJson, status, requestBody }`
+- Glob patterns (`**` matches any path segment)
+- JSON automatically parsed
+
+### Example 2: Stub Network (Mock Response)
+
+**Context**: Mock API responses for testing UI behavior without backend.
+
+**Implementation**:
+
+```typescript
+test('should stub users API', async ({ page, interceptNetworkCall }) => {
+  const mockUsers = [
+    { id: 1, name: 'Test User 1' },
+    { id: 2, name: 'Test User 2' },
+  ];
+
+  const usersCall = interceptNetworkCall({
+    url: '**/api/users',
+    fulfillResponse: {
+      status: 200,
+      body: mockUsers,
+    },
+  });
+
+  await page.goto('/dashboard');
+  await usersCall;
+
+  // UI shows mocked data
+  await expect(page.getByText('Test User 1')).toBeVisible();
+  await expect(page.getByText('Test User 2')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- `fulfillResponse` mocks the API
+- No backend needed
+- Test UI logic in isolation
+- Status code and body fully controllable
+
+### Example 3: Conditional Response Handling
+
+**Context**: Different responses based on request method or parameters.
+
+**Implementation**:
+
+```typescript
+test('conditional mocking', async ({ page, interceptNetworkCall }) => {
+  await interceptNetworkCall({
+    url: '**/api/data',
+    handler: async (route, request) => {
+      if (request.method() === 'POST') {
+        // Mock POST success
+        await route.fulfill({
+          status: 201,
+          body: JSON.stringify({ id: 'new-id', success: true }),
+        });
+      } else if (request.method() === 'GET') {
+        // Mock GET with data
+        await route.fulfill({
+          status: 200,
+          body: JSON.stringify([{ id: 1, name: 'Item' }]),
+        });
+      } else {
+        // Let other methods through
+        await route.continue();
+      }
+    },
+  });
+
+  await page.goto('/data-page');
+});
+```
+
+**Key Points**:
+
+- `handler` function for complex logic
+- Access full `route` and `request` objects
+- Can mock, continue, or abort
+- Flexible for advanced scenarios
+
+### Example 4: Error Simulation
+
+**Context**: Testing error handling in UI when API fails.
+
+**Implementation**:
+
+```typescript
+test('should handle API errors gracefully', async ({ page, interceptNetworkCall }) => {
+  // Simulate 500 error
+  const errorCall = interceptNetworkCall({
+    url: '**/api/users',
+    fulfillResponse: {
+      status: 500,
+      body: { error: 'Internal Server Error' },
+    },
+  });
+
+  await page.goto('/dashboard');
+  await errorCall;
+
+  // Verify UI shows error state
+  await expect(page.getByText('Failed to load users')).toBeVisible();
+  await expect(page.getByTestId('retry-button')).toBeVisible();
+});
+
+// Simulate network timeout
+test('should handle timeout', async ({ page, interceptNetworkCall }) => {
+  await interceptNetworkCall({
+    url: '**/api/slow',
+    handler: async (route) => {
+      // Never respond - simulates timeout
+      await new Promise(() => {});
+    },
+  });
+
+  await page.goto('/slow-page');
+
+  // UI should show timeout error
+  await expect(page.getByText('Request timed out')).toBeVisible({ timeout: 10000 });
+});
+```
+
+**Key Points**:
+
+- Mock error statuses (4xx, 5xx)
+- Test timeout scenarios
+- Validate error UI states
+- No real failures needed
+
+### Example 5: Multiple Intercepts (Order Matters!)
+
+**Context**: Intercepting different endpoints in same test - setup order is critical.
+
+**Implementation**:
+
+```typescript
+test('multiple intercepts', async ({ page, interceptNetworkCall }) => {
+  // ✅ CORRECT: Setup all intercepts BEFORE navigation
+  const usersCall = interceptNetworkCall({ url: '**/api/users' });
+  const productsCall = interceptNetworkCall({ url: '**/api/products' });
+  const ordersCall = interceptNetworkCall({ url: '**/api/orders' });
+
+  // THEN navigate
+  await page.goto('/dashboard');
+
+  // Wait for all (or specific ones)
+  const [users, products] = await Promise.all([usersCall, productsCall]);
+
+  expect(users.responseJson).toHaveLength(10);
+  expect(products.responseJson).toHaveLength(50);
+});
+```
+
+**Key Points**:
+
+- Setup all intercepts before triggering actions
+- Use `Promise.all()` to wait for multiple calls
+- Order: intercept → navigate → await
+- Prevents race conditions
+
+## URL Pattern Matching
+
+**Supported glob patterns:**
+
+```typescript
+'**/api/users'; // Any path ending with /api/users
+'/api/users'; // Exact match
+'**/users/*'; // Any users sub-path
+'**/api/{users,products}'; // Either users or products
+'**/api/users?id=*'; // With query params
+```
+
+**Uses picomatch library** - same pattern syntax as Playwright's `page.route()` but cleaner API.
+
+## Comparison with Vanilla Playwright
+
+| Vanilla Playwright                                          | intercept-network-call                                       |
+| ----------------------------------------------------------- | ------------------------------------------------------------ |
+| `await page.route('/api/users', route => route.continue())` | `const call = interceptNetworkCall({ url: '**/api/users' })` |
+| `const resp = await page.waitForResponse('/api/users')`     | (Combined in single statement)                               |
+| `const json = await resp.json()`                            | `const { responseJson } = await call`                        |
+| `const status = resp.status()`                              | `const { status } = await call`                              |
+| Complex filter predicates                                   | Simple glob patterns                                         |
+
+**Reduction:** ~5-7 lines → ~2-3 lines per interception
+
+## Related Fragments
+
+- `network-first.md` - Core pattern: intercept before navigate
+- `network-recorder.md` - HAR-based offline testing
+- `overview.md` - Fixture composition basics
+
+## Anti-Patterns
+
+**❌ Intercepting after navigation:**
+
+```typescript
+await page.goto('/dashboard'); // Navigation starts
+const usersCall = interceptNetworkCall({ url: '**/api/users' }); // Too late!
+```
+
+**✅ Intercept before navigate:**
+
+```typescript
+const usersCall = interceptNetworkCall({ url: '**/api/users' }); // First
+await page.goto('/dashboard'); // Then navigate
+const { responseJson } = await usersCall; // Then await
+```
+
+**❌ Ignoring the returned Promise:**
+
+```typescript
+interceptNetworkCall({ url: '**/api/users' }); // Not awaited!
+await page.goto('/dashboard');
+// No deterministic wait - race condition
+```
+
+**✅ Always await the intercept:**
+
+```typescript
+const usersCall = interceptNetworkCall({ url: '**/api/users' });
+await page.goto('/dashboard');
+await usersCall; // Deterministic wait
+```

_bmad/bmm/testarch/knowledge/log.md

@@ -0,0 +1,294 @@
+# Log Utility
+
+## Principle
+
+Use structured logging that integrates with Playwright's test reports. Support object logging, test step decoration, and multiple log levels (info, step, success, warning, error, debug).
+
+## Rationale
+
+Console.log in Playwright tests has limitations:
+
+- Not visible in HTML reports
+- No test step integration
+- No structured output
+- Lost in terminal noise during CI
+
+The `log` utility provides:
+
+- **Report integration**: Logs appear in Playwright HTML reports
+- **Test step decoration**: `log.step()` creates collapsible steps in UI
+- **Object logging**: Automatically formats objects/arrays
+- **Multiple levels**: info, step, success, warning, error, debug
+- **Optional console**: Can disable console output but keep report logs
+
+## Pattern Examples
+
+### Example 1: Basic Logging Levels
+
+**Context**: Log different types of messages throughout test execution.
+
+**Implementation**:
+
+```typescript
+import { log } from '@seontechnologies/playwright-utils';
+
+test('logging demo', async ({ page }) => {
+  await log.step('Navigate to login page');
+  await page.goto('/login');
+
+  await log.info('Entering credentials');
+  await page.fill('#username', 'testuser');
+
+  await log.success('Login successful');
+
+  await log.warning('Rate limit approaching');
+
+  await log.debug({ userId: '123', sessionId: 'abc' });
+
+  // Errors still throw but get logged first
+  try {
+    await page.click('#nonexistent');
+  } catch (error) {
+    await log.error('Click failed', false); // false = no console output
+    throw error;
+  }
+});
+```
+
+**Key Points**:
+
+- `step()` creates collapsible steps in Playwright UI
+- `info()`, `success()`, `warning()` for different message types
+- `debug()` for detailed data (objects/arrays)
+- `error()` with optional console suppression
+- All logs appear in test reports
+
+### Example 2: Object and Array Logging
+
+**Context**: Log structured data for debugging without cluttering console.
+
+**Implementation**:
+
+```typescript
+test('object logging', async ({ apiRequest }) => {
+  const { body } = await apiRequest({
+    method: 'GET',
+    path: '/api/users',
+  });
+
+  // Log array of objects
+  await log.debug(body); // Formatted as JSON in report
+
+  // Log specific object
+  await log.info({
+    totalUsers: body.length,
+    firstUser: body[0]?.name,
+    timestamp: new Date().toISOString(),
+  });
+
+  // Complex nested structures
+  await log.debug({
+    request: {
+      method: 'GET',
+      path: '/api/users',
+      timestamp: Date.now(),
+    },
+    response: {
+      status: 200,
+      body: body.slice(0, 3), // First 3 items
+    },
+  });
+});
+```
+
+**Key Points**:
+
+- Objects auto-formatted as pretty JSON
+- Arrays handled gracefully
+- Nested structures supported
+- All visible in Playwright report attachments
+
+### Example 3: Test Step Organization
+
+**Context**: Organize test execution into collapsible steps for better readability in reports.
+
+**Implementation**:
+
+```typescript
+test('organized with steps', async ({ page, apiRequest }) => {
+  await log.step('ARRANGE: Setup test data');
+  const { body: user } = await apiRequest({
+    method: 'POST',
+    path: '/api/users',
+    body: { name: 'Test User' },
+  });
+
+  await log.step('ACT: Perform user action');
+  await page.goto(`/users/${user.id}`);
+  await page.click('#edit');
+  await page.fill('#name', 'Updated Name');
+  await page.click('#save');
+
+  await log.step('ASSERT: Verify changes');
+  await expect(page.getByText('Updated Name')).toBeVisible();
+
+  // In Playwright UI, each step is collapsible
+});
+```
+
+**Key Points**:
+
+- `log.step()` creates collapsible sections
+- Organize by Arrange-Act-Assert
+- Steps visible in Playwright trace viewer
+- Better debugging when tests fail
+
+### Example 4: Conditional Logging
+
+**Context**: Log different messages based on environment or test conditions.
+
+**Implementation**:
+
+```typescript
+test('conditional logging', async ({ page }) => {
+  const isCI = process.env.CI === 'true';
+
+  if (isCI) {
+    await log.info('Running in CI environment');
+  } else {
+    await log.debug('Running locally');
+  }
+
+  const isKafkaWorking = await checkKafkaHealth();
+
+  if (!isKafkaWorking) {
+    await log.warning('Kafka unavailable - skipping event checks');
+  } else {
+    await log.step('Verifying Kafka events');
+    // ... event verification
+  }
+});
+```
+
+**Key Points**:
+
+- Log based on environment
+- Skip logging with conditionals
+- Use appropriate log levels
+- Debug info for local, minimal for CI
+
+### Example 5: Integration with Auth and API
+
+**Context**: Log authenticated API requests with tokens (safely).
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+// Helper to create safe token preview
+function createTokenPreview(token: string): string {
+  if (!token || token.length < 10) return '[invalid]';
+  return `${token.slice(0, 6)}...${token.slice(-4)}`;
+}
+
+test('should log auth flow', async ({ authToken, apiRequest }) => {
+  await log.info(`Using token: ${createTokenPreview(authToken)}`);
+
+  await log.step('Fetch protected resource');
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/protected',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  await log.debug({
+    status,
+    bodyPreview: {
+      id: body.id,
+      recordCount: body.data?.length,
+    },
+  });
+
+  await log.success('Protected resource accessed successfully');
+});
+```
+
+**Key Points**:
+
+- Never log full tokens (security risk)
+- Use preview functions for sensitive data
+- Combine with auth and API utilities
+- Log at appropriate detail level
+
+## Log Levels Guide
+
+| Level     | When to Use                         | Shows in Report      | Shows in Console |
+| --------- | ----------------------------------- | -------------------- | ---------------- |
+| `step`    | Test organization, major actions    | ✅ Collapsible steps | ✅ Yes           |
+| `info`    | General information, state changes  | ✅ Yes               | ✅ Yes           |
+| `success` | Successful operations               | ✅ Yes               | ✅ Yes           |
+| `warning` | Non-critical issues, skipped checks | ✅ Yes               | ✅ Yes           |
+| `error`   | Failures, exceptions                | ✅ Yes               | ✅ Configurable  |
+| `debug`   | Detailed data, objects              | ✅ Yes (attached)    | ✅ Configurable  |
+
+## Comparison with console.log
+
+| console.log             | log Utility               |
+| ----------------------- | ------------------------- |
+| Not in reports          | Appears in reports        |
+| No test steps           | Creates collapsible steps |
+| Manual JSON.stringify() | Auto-formats objects      |
+| No log levels           | 6 log levels              |
+| Lost in CI output       | Preserved in artifacts    |
+
+## Related Fragments
+
+- `overview.md` - Basic usage and imports
+- `api-request.md` - Log API requests
+- `auth-session.md` - Log auth flow (safely)
+- `recurse.md` - Log polling progress
+
+## Anti-Patterns
+
+**❌ Logging objects in steps:**
+
+```typescript
+await log.step({ user: 'test', action: 'create' }); // Shows empty in UI
+```
+
+**✅ Use strings for steps, objects for debug:**
+
+```typescript
+await log.step('Creating user: test'); // Readable in UI
+await log.debug({ user: 'test', action: 'create' }); // Detailed data
+```
+
+**❌ Logging sensitive data:**
+
+```typescript
+await log.info(`Password: ${password}`); // Security risk!
+await log.info(`Token: ${authToken}`); // Full token exposed!
+```
+
+**✅ Use previews or omit sensitive data:**
+
+```typescript
+await log.info('User authenticated successfully'); // No sensitive data
+await log.debug({ tokenPreview: token.slice(0, 6) + '...' });
+```
+
+**❌ Excessive logging in loops:**
+
+```typescript
+for (const item of items) {
+  await log.info(`Processing ${item.id}`); // 100 log entries!
+}
+```
+
+**✅ Log summary or use debug level:**
+
+```typescript
+await log.step(`Processing ${items.length} items`);
+await log.debug({ itemIds: items.map((i) => i.id) }); // One log entry
+```

_bmad/bmm/testarch/knowledge/network-error-monitor.md

@@ -0,0 +1,272 @@
+# Network Error Monitor
+
+## Principle
+
+Automatically detect and fail tests when HTTP 4xx/5xx errors occur during execution. Act like Sentry for tests - catch silent backend failures even when UI passes assertions.
+
+## Rationale
+
+Traditional Playwright tests focus on UI:
+
+- Backend 500 errors ignored if UI looks correct
+- Silent failures slip through
+- No visibility into background API health
+- Tests pass while features are broken
+
+The `network-error-monitor` provides:
+
+- **Automatic detection**: All HTTP 4xx/5xx responses tracked
+- **Test failures**: Fail tests with backend errors (even if UI passes)
+- **Structured artifacts**: JSON reports with error details
+- **Smart opt-out**: Disable for validation tests expecting errors
+- **Deduplication**: Group repeated errors by pattern
+- **Domino effect prevention**: Limit test failures per error pattern
+
+## Pattern Examples
+
+### Example 1: Basic Auto-Monitoring
+
+**Context**: Automatically fail tests when backend errors occur.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+// Monitoring automatically enabled
+test('should load dashboard', async ({ page }) => {
+  await page.goto('/dashboard');
+  await expect(page.locator('h1')).toContainText('Dashboard');
+
+  // ✅ Passes if no HTTP errors
+  // ❌ Fails if any 4xx/5xx errors detected with clear message:
+  //    "Network errors detected: 2 request(s) failed"
+  //    Failed requests:
+  //      GET 500 https://api.example.com/users
+  //      POST 503 https://api.example.com/metrics
+});
+```
+
+**Key Points**:
+
+- Zero setup - auto-enabled for all tests
+- Fails on any 4xx/5xx response
+- Structured error message with URLs and status codes
+- JSON artifact attached to test report
+
+### Example 2: Opt-Out for Validation Tests
+
+**Context**: Some tests expect errors (validation, error handling, edge cases).
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+// Opt-out with annotation
+test('should show error on invalid input', { annotation: [{ type: 'skipNetworkMonitoring' }] }, async ({ page }) => {
+  await page.goto('/form');
+  await page.click('#submit'); // Triggers 400 error
+
+  // Monitoring disabled - test won't fail on 400
+  await expect(page.getByText('Invalid input')).toBeVisible();
+});
+
+// Or opt-out entire describe block
+test.describe('error handling', { annotation: [{ type: 'skipNetworkMonitoring' }] }, () => {
+  test('handles 404', async ({ page }) => {
+    // All tests in this block skip monitoring
+  });
+
+  test('handles 500', async ({ page }) => {
+    // Monitoring disabled
+  });
+});
+```
+
+**Key Points**:
+
+- Use annotation `{ type: 'skipNetworkMonitoring' }`
+- Can opt-out single test or entire describe block
+- Monitoring still active for other tests
+- Perfect for intentional error scenarios
+
+### Example 3: Integration with Merged Fixtures
+
+**Context**: Combine network-error-monitor with other utilities.
+
+**Implementation**:
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { mergeTests } from '@playwright/test';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as networkErrorMonitorFixture } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+export const test = mergeTests(
+  authFixture,
+  networkErrorMonitorFixture,
+  // Add other fixtures
+);
+
+// In tests
+import { test, expect } from '../support/merged-fixtures';
+
+test('authenticated with monitoring', async ({ page, authToken }) => {
+  // Both auth and network monitoring active
+  await page.goto('/protected');
+
+  // Fails if backend returns errors during auth flow
+});
+```
+
+**Key Points**:
+
+- Combine with `mergeTests`
+- Works alongside all other utilities
+- Monitoring active automatically
+- No extra setup needed
+
+### Example 4: Domino Effect Prevention
+
+**Context**: One failing endpoint shouldn't fail all tests.
+
+**Implementation**:
+
+```typescript
+// Configuration (internal to utility)
+const config = {
+  maxTestsPerError: 3, // Max 3 tests fail per unique error pattern
+};
+
+// Scenario:
+// Test 1: GET /api/broken → 500 error → Test fails ❌
+// Test 2: GET /api/broken → 500 error → Test fails ❌
+// Test 3: GET /api/broken → 500 error → Test fails ❌
+// Test 4: GET /api/broken → 500 error → Test passes ⚠️ (limit reached, warning logged)
+// Test 5: Different error pattern → Test fails ❌ (new pattern, counter resets)
+```
+
+**Key Points**:
+
+- Limits cascading failures
+- Groups errors by URL + status code pattern
+- Warns when limit reached
+- Prevents flaky backend from failing entire suite
+
+### Example 5: Artifact Structure
+
+**Context**: Debugging failed tests with network error artifacts.
+
+**Implementation**:
+
+When test fails due to network errors, artifact attached:
+
+```json
+// test-results/my-test/network-errors.json
+{
+  "errors": [
+    {
+      "url": "https://api.example.com/users",
+      "method": "GET",
+      "status": 500,
+      "statusText": "Internal Server Error",
+      "timestamp": "2024-08-13T10:30:45.123Z"
+    },
+    {
+      "url": "https://api.example.com/metrics",
+      "method": "POST",
+      "status": 503,
+      "statusText": "Service Unavailable",
+      "timestamp": "2024-08-13T10:30:46.456Z"
+    }
+  ],
+  "summary": {
+    "totalErrors": 2,
+    "uniquePatterns": 2
+  }
+}
+```
+
+**Key Points**:
+
+- JSON artifact per failed test
+- Full error details (URL, method, status, timestamp)
+- Summary statistics
+- Easy debugging with structured data
+
+## Comparison with Manual Error Checks
+
+| Manual Approach                                        | network-error-monitor      |
+| ------------------------------------------------------ | -------------------------- |
+| `page.on('response', resp => { if (!resp.ok()) ... })` | Auto-enabled, zero setup   |
+| Check each response manually                           | Automatic for all requests |
+| Custom error tracking logic                            | Built-in deduplication     |
+| No structured artifacts                                | JSON artifacts attached    |
+| Easy to forget                                         | Never miss a backend error |
+
+## When to Use
+
+**Auto-enabled for:**
+
+- ✅ All E2E tests
+- ✅ Integration tests
+- ✅ Any test hitting real APIs
+
+**Opt-out for:**
+
+- ❌ Validation tests (expecting 4xx)
+- ❌ Error handling tests (expecting 5xx)
+- ❌ Offline tests (network-recorder playback)
+
+## Integration with Framework Setup
+
+In `*framework` workflow, mention network-error-monitor:
+
+```typescript
+// Add to merged-fixtures.ts
+import { test as networkErrorMonitorFixture } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+export const test = mergeTests(
+  // ... other fixtures
+  networkErrorMonitorFixture,
+);
+```
+
+## Related Fragments
+
+- `overview.md` - Installation and fixtures
+- `fixtures-composition.md` - Merging with other utilities
+- `error-handling.md` - Traditional error handling patterns
+
+## Anti-Patterns
+
+**❌ Opting out of monitoring globally:**
+
+```typescript
+// Every test skips monitoring
+test.use({ annotation: [{ type: 'skipNetworkMonitoring' }] });
+```
+
+**✅ Opt-out only for specific error tests:**
+
+```typescript
+test.describe('error scenarios', { annotation: [{ type: 'skipNetworkMonitoring' }] }, () => {
+  // Only these tests skip monitoring
+});
+```
+
+**❌ Ignoring network error artifacts:**
+
+```typescript
+// Test fails, artifact shows 500 errors
+// Developer: "Works on my machine" ¯\_(ツ)_/¯
+```
+
+**✅ Check artifacts for root cause:**
+
+```typescript
+// Read network-errors.json artifact
+// Identify failing endpoint: GET /api/users → 500
+// Fix backend issue before merging
+```

_bmad/bmm/testarch/knowledge/network-first.md

@@ -0,0 +1,486 @@
+# Network-First Safeguards
+
+## Principle
+
+Register network interceptions **before** any navigation or user action. Store the interception promise and await it immediately after the triggering step. Replace implicit waits with deterministic signals based on network responses, spinner disappearance, or event hooks.
+
+## Rationale
+
+The most common source of flaky E2E tests is **race conditions** between navigation and network interception:
+
+- Navigate then intercept = missed requests (too late)
+- No explicit wait = assertion runs before response arrives
+- Hard waits (`waitForTimeout(3000)`) = slow, unreliable, brittle
+
+Network-first patterns provide:
+
+- **Zero race conditions**: Intercept is active before triggering action
+- **Deterministic waits**: Wait for actual response, not arbitrary timeouts
+- **Actionable failures**: Assert on response status/body, not generic "element not found"
+- **Speed**: No padding with extra wait time
+
+## Pattern Examples
+
+### Example 1: Intercept Before Navigate Pattern
+
+**Context**: The foundational pattern for all E2E tests. Always register route interception **before** the action that triggers the request (navigation, click, form submit).
+
+**Implementation**:
+
+```typescript
+// ✅ CORRECT: Intercept BEFORE navigate
+test('user can view dashboard data', async ({ page }) => {
+  // Step 1: Register interception FIRST
+  const usersPromise = page.waitForResponse((resp) => resp.url().includes('/api/users') && resp.status() === 200);
+
+  // Step 2: THEN trigger the request
+  await page.goto('/dashboard');
+
+  // Step 3: THEN await the response
+  const usersResponse = await usersPromise;
+  const users = await usersResponse.json();
+
+  // Step 4: Assert on structured data
+  expect(users).toHaveLength(10);
+  await expect(page.getByText(users[0].name)).toBeVisible();
+});
+
+// Cypress equivalent
+describe('Dashboard', () => {
+  it('should display users', () => {
+    // Step 1: Register interception FIRST
+    cy.intercept('GET', '**/api/users').as('getUsers');
+
+    // Step 2: THEN trigger
+    cy.visit('/dashboard');
+
+    // Step 3: THEN await
+    cy.wait('@getUsers').then((interception) => {
+      // Step 4: Assert on structured data
+      expect(interception.response.statusCode).to.equal(200);
+      expect(interception.response.body).to.have.length(10);
+      cy.contains(interception.response.body[0].name).should('be.visible');
+    });
+  });
+});
+
+// ❌ WRONG: Navigate BEFORE intercept (race condition!)
+test('flaky test example', async ({ page }) => {
+  await page.goto('/dashboard'); // Request fires immediately
+
+  const usersPromise = page.waitForResponse('/api/users'); // TOO LATE - might miss it
+  const response = await usersPromise; // May timeout randomly
+});
+```
+
+**Key Points**:
+
+- Playwright: Use `page.waitForResponse()` with URL pattern or predicate **before** `page.goto()` or `page.click()`
+- Cypress: Use `cy.intercept().as()` **before** `cy.visit()` or `cy.click()`
+- Store promise/alias, trigger action, **then** await response
+- This prevents 95% of race-condition flakiness in E2E tests
+
+### Example 2: HAR Capture for Debugging
+
+**Context**: When debugging flaky tests or building deterministic mocks, capture real network traffic with HAR files. Replay them in tests for consistent, offline-capable test runs.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Enable HAR recording
+export default defineConfig({
+  use: {
+    // Record HAR on first run
+    recordHar: { path: './hars/', mode: 'minimal' },
+    // Or replay HAR in tests
+    // serviceWorkers: 'block',
+  },
+});
+
+// Capture HAR for specific test
+test('capture network for order flow', async ({ page, context }) => {
+  // Start recording
+  await context.routeFromHAR('./hars/order-flow.har', {
+    url: '**/api/**',
+    update: true, // Update HAR with new requests
+  });
+
+  await page.goto('/checkout');
+  await page.fill('[data-testid="credit-card"]', '4111111111111111');
+  await page.click('[data-testid="submit-order"]');
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+
+  // HAR saved to ./hars/order-flow.har
+});
+
+// Replay HAR for deterministic tests (no real API needed)
+test('replay order flow from HAR', async ({ page, context }) => {
+  // Replay captured HAR
+  await context.routeFromHAR('./hars/order-flow.har', {
+    url: '**/api/**',
+    update: false, // Read-only mode
+  });
+
+  // Test runs with exact recorded responses - fully deterministic
+  await page.goto('/checkout');
+  await page.fill('[data-testid="credit-card"]', '4111111111111111');
+  await page.click('[data-testid="submit-order"]');
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+});
+
+// Custom mock based on HAR insights
+test('mock order response based on HAR', async ({ page }) => {
+  // After analyzing HAR, create focused mock
+  await page.route('**/api/orders', (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({
+        orderId: '12345',
+        status: 'confirmed',
+        total: 99.99,
+      }),
+    }),
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+  await expect(page.getByText('Order #12345')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- HAR files capture real request/response pairs for analysis
+- `update: true` records new traffic; `update: false` replays existing
+- Replay mode makes tests fully deterministic (no upstream API needed)
+- Use HAR to understand API contracts, then create focused mocks
+
+### Example 3: Network Stub with Edge Cases
+
+**Context**: When testing error handling, timeouts, and edge cases, stub network responses to simulate failures. Test both happy path and error scenarios.
+
+**Implementation**:
+
+```typescript
+// Test happy path
+test('order succeeds with valid data', async ({ page }) => {
+  await page.route('**/api/orders', (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({ orderId: '123', status: 'confirmed' }),
+    }),
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+});
+
+// Test 500 error
+test('order fails with server error', async ({ page }) => {
+  // Listen for console errors (app should log gracefully)
+  const consoleErrors: string[] = [];
+  page.on('console', (msg) => {
+    if (msg.type() === 'error') consoleErrors.push(msg.text());
+  });
+
+  // Stub 500 error
+  await page.route('**/api/orders', (route) =>
+    route.fulfill({
+      status: 500,
+      contentType: 'application/json',
+      body: JSON.stringify({ error: 'Internal Server Error' }),
+    }),
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+
+  // Assert UI shows error gracefully
+  await expect(page.getByText('Something went wrong')).toBeVisible();
+  await expect(page.getByText('Please try again')).toBeVisible();
+
+  // Verify error logged (not thrown)
+  expect(consoleErrors.some((e) => e.includes('Order failed'))).toBeTruthy();
+});
+
+// Test network timeout
+test('order times out after 10 seconds', async ({ page }) => {
+  // Stub delayed response (never resolves within timeout)
+  await page.route(
+    '**/api/orders',
+    (route) => new Promise(() => {}), // Never resolves - simulates timeout
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+
+  // App should show timeout message after configured timeout
+  await expect(page.getByText('Request timed out')).toBeVisible({ timeout: 15000 });
+});
+
+// Test partial data response
+test('order handles missing optional fields', async ({ page }) => {
+  await page.route('**/api/orders', (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      // Missing optional fields like 'trackingNumber', 'estimatedDelivery'
+      body: JSON.stringify({ orderId: '123', status: 'confirmed' }),
+    }),
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+
+  // App should handle gracefully - no crash, shows what's available
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+  await expect(page.getByText('Tracking information pending')).toBeVisible();
+});
+
+// Cypress equivalents
+describe('Order Edge Cases', () => {
+  it('should handle 500 error', () => {
+    cy.intercept('POST', '**/api/orders', {
+      statusCode: 500,
+      body: { error: 'Internal Server Error' },
+    }).as('orderFailed');
+
+    cy.visit('/checkout');
+    cy.get('[data-testid="submit-order"]').click();
+    cy.wait('@orderFailed');
+    cy.contains('Something went wrong').should('be.visible');
+  });
+
+  it('should handle timeout', () => {
+    cy.intercept('POST', '**/api/orders', (req) => {
+      req.reply({ delay: 20000 }); // Delay beyond app timeout
+    }).as('orderTimeout');
+
+    cy.visit('/checkout');
+    cy.get('[data-testid="submit-order"]').click();
+    cy.contains('Request timed out', { timeout: 15000 }).should('be.visible');
+  });
+});
+```
+
+**Key Points**:
+
+- Stub different HTTP status codes (200, 400, 500, 503)
+- Simulate timeouts with `delay` or non-resolving promises
+- Test partial/incomplete data responses
+- Verify app handles errors gracefully (no crashes, user-friendly messages)
+
+### Example 4: Deterministic Waiting
+
+**Context**: Never use hard waits (`waitForTimeout(3000)`). Always wait for explicit signals: network responses, element state changes, or custom events.
+
+**Implementation**:
+
+```typescript
+// ✅ GOOD: Wait for response with predicate
+test('wait for specific response', async ({ page }) => {
+  const responsePromise = page.waitForResponse((resp) => resp.url().includes('/api/users') && resp.status() === 200);
+
+  await page.goto('/dashboard');
+  const response = await responsePromise;
+
+  expect(response.status()).toBe(200);
+  await expect(page.getByText('Dashboard')).toBeVisible();
+});
+
+// ✅ GOOD: Wait for multiple responses
+test('wait for all required data', async ({ page }) => {
+  const usersPromise = page.waitForResponse('**/api/users');
+  const productsPromise = page.waitForResponse('**/api/products');
+  const ordersPromise = page.waitForResponse('**/api/orders');
+
+  await page.goto('/dashboard');
+
+  // Wait for all in parallel
+  const [users, products, orders] = await Promise.all([usersPromise, productsPromise, ordersPromise]);
+
+  expect(users.status()).toBe(200);
+  expect(products.status()).toBe(200);
+  expect(orders.status()).toBe(200);
+});
+
+// ✅ GOOD: Wait for spinner to disappear
+test('wait for loading indicator', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // Wait for spinner to disappear (signals data loaded)
+  await expect(page.getByTestId('loading-spinner')).not.toBeVisible();
+  await expect(page.getByText('Dashboard')).toBeVisible();
+});
+
+// ✅ GOOD: Wait for custom event (advanced)
+test('wait for custom ready event', async ({ page }) => {
+  let appReady = false;
+  page.on('console', (msg) => {
+    if (msg.text() === 'App ready') appReady = true;
+  });
+
+  await page.goto('/dashboard');
+
+  // Poll until custom condition met
+  await page.waitForFunction(() => appReady, { timeout: 10000 });
+
+  await expect(page.getByText('Dashboard')).toBeVisible();
+});
+
+// ❌ BAD: Hard wait (arbitrary timeout)
+test('flaky hard wait example', async ({ page }) => {
+  await page.goto('/dashboard');
+  await page.waitForTimeout(3000); // WHY 3 seconds? What if slower? What if faster?
+  await expect(page.getByText('Dashboard')).toBeVisible(); // May fail if >3s
+});
+
+// Cypress equivalents
+describe('Deterministic Waiting', () => {
+  it('should wait for response', () => {
+    cy.intercept('GET', '**/api/users').as('getUsers');
+    cy.visit('/dashboard');
+    cy.wait('@getUsers').its('response.statusCode').should('eq', 200);
+    cy.contains('Dashboard').should('be.visible');
+  });
+
+  it('should wait for spinner to disappear', () => {
+    cy.visit('/dashboard');
+    cy.get('[data-testid="loading-spinner"]').should('not.exist');
+    cy.contains('Dashboard').should('be.visible');
+  });
+
+  // ❌ BAD: Hard wait
+  it('flaky hard wait', () => {
+    cy.visit('/dashboard');
+    cy.wait(3000); // NEVER DO THIS
+    cy.contains('Dashboard').should('be.visible');
+  });
+});
+```
+
+**Key Points**:
+
+- `waitForResponse()` with URL pattern or predicate = deterministic
+- `waitForLoadState('networkidle')` = wait for all network activity to finish
+- Wait for element state changes (spinner disappears, button enabled)
+- **NEVER** use `waitForTimeout()` or `cy.wait(ms)` - always non-deterministic
+
+### Example 5: Anti-Pattern - Navigate Then Mock
+
+**Problem**:
+
+```typescript
+// ❌ BAD: Race condition - mock registered AFTER navigation starts
+test('flaky test - navigate then mock', async ({ page }) => {
+  // Navigation starts immediately
+  await page.goto('/dashboard'); // Request to /api/users fires NOW
+
+  // Mock registered too late - request already sent
+  await page.route('**/api/users', (route) =>
+    route.fulfill({
+      status: 200,
+      body: JSON.stringify([{ id: 1, name: 'Test User' }]),
+    }),
+  );
+
+  // Test randomly passes/fails depending on timing
+  await expect(page.getByText('Test User')).toBeVisible(); // Flaky!
+});
+
+// ❌ BAD: No wait for response
+test('flaky test - no explicit wait', async ({ page }) => {
+  await page.route('**/api/users', (route) => route.fulfill({ status: 200, body: JSON.stringify([]) }));
+
+  await page.goto('/dashboard');
+
+  // Assertion runs immediately - may fail if response slow
+  await expect(page.getByText('No users found')).toBeVisible(); // Flaky!
+});
+
+// ❌ BAD: Generic timeout
+test('flaky test - hard wait', async ({ page }) => {
+  await page.goto('/dashboard');
+  await page.waitForTimeout(2000); // Arbitrary wait - brittle
+
+  await expect(page.getByText('Dashboard')).toBeVisible();
+});
+```
+
+**Why It Fails**:
+
+- **Mock after navigate**: Request fires during navigation, mock isn't active yet (race condition)
+- **No explicit wait**: Assertion runs before response arrives (timing-dependent)
+- **Hard waits**: Slow tests, brittle (fails if < timeout, wastes time if > timeout)
+- **Non-deterministic**: Passes locally, fails in CI (different speeds)
+
+**Better Approach**: Always intercept → trigger → await
+
+```typescript
+// ✅ GOOD: Intercept BEFORE navigate
+test('deterministic test', async ({ page }) => {
+  // Step 1: Register mock FIRST
+  await page.route('**/api/users', (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify([{ id: 1, name: 'Test User' }]),
+    }),
+  );
+
+  // Step 2: Store response promise BEFORE trigger
+  const responsePromise = page.waitForResponse('**/api/users');
+
+  // Step 3: THEN trigger
+  await page.goto('/dashboard');
+
+  // Step 4: THEN await response
+  await responsePromise;
+
+  // Step 5: THEN assert (data is guaranteed loaded)
+  await expect(page.getByText('Test User')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Order matters: Mock → Promise → Trigger → Await → Assert
+- No race conditions: Mock is active before request fires
+- Explicit wait: Response promise ensures data loaded
+- Deterministic: Always passes if app works correctly
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (test generation), `*automate` (test expansion), `*framework` (network setup)
+- **Related fragments**:
+  - `fixture-architecture.md` - Network fixture patterns
+  - `data-factories.md` - API-first setup with network
+  - `test-quality.md` - Deterministic test principles
+
+## Debugging Network Issues
+
+When network tests fail, check:
+
+1. **Timing**: Is interception registered **before** action?
+2. **URL pattern**: Does pattern match actual request URL?
+3. **Response format**: Is mocked response valid JSON/format?
+4. **Status code**: Is app checking for 200 vs 201 vs 204?
+5. **HAR file**: Capture real traffic to understand actual API contract
+
+```typescript
+// Debug network issues with logging
+test('debug network', async ({ page }) => {
+  // Log all requests
+  page.on('request', (req) => console.log('→', req.method(), req.url()));
+
+  // Log all responses
+  page.on('response', (resp) => console.log('←', resp.status(), resp.url()));
+
+  await page.goto('/dashboard');
+});
+```
+
+_Source: Murat Testing Philosophy (lines 94-137), Playwright network patterns, Cypress intercept best practices._

_bmad/bmm/testarch/knowledge/network-recorder.md

@@ -0,0 +1,265 @@
+# Network Recorder Utility
+
+## Principle
+
+Record network traffic to HAR files during test execution, then play back from disk for offline testing. Enables frontend tests to run in complete isolation from backend services with intelligent stateful CRUD detection for realistic API behavior.
+
+## Rationale
+
+Traditional E2E tests require live backend services:
+
+- Slow (real network latency)
+- Flaky (backend instability affects tests)
+- Expensive (full stack running for UI tests)
+- Coupled (UI tests break when API changes)
+
+HAR-based recording/playback provides:
+
+- **True offline testing**: UI tests run without backend
+- **Deterministic behavior**: Same responses every time
+- **Fast execution**: No network latency
+- **Stateful mocking**: CRUD operations work naturally (not just read-only)
+- **Environment flexibility**: Map URLs for any environment
+
+## Pattern Examples
+
+### Example 1: Basic Record and Playback
+
+**Context**: The fundamental pattern - record traffic once, play back for all subsequent runs.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/network-recorder/fixtures';
+
+// Set mode in test file (recommended)
+process.env.PW_NET_MODE = 'playback'; // or 'record'
+
+test('CRUD operations work offline', async ({ page, context, networkRecorder }) => {
+  // Setup recorder (records or plays back based on PW_NET_MODE)
+  await networkRecorder.setup(context);
+
+  await page.goto('/');
+
+  // First time (record mode): Records all network traffic to HAR
+  // Subsequent runs (playback mode): Plays back from HAR (no backend!)
+  await page.fill('#movie-name', 'Inception');
+  await page.click('#add-movie');
+
+  // Intelligent CRUD detection makes this work offline!
+  await expect(page.getByText('Inception')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- `PW_NET_MODE=record` captures traffic to HAR files
+- `PW_NET_MODE=playback` replays from HAR files
+- Set mode in test file or via environment variable
+- HAR files auto-organized by test name
+- Stateful mocking detects CRUD operations
+
+### Example 2: Complete CRUD Flow with HAR
+
+**Context**: Full create-read-update-delete flow that works completely offline.
+
+**Implementation**:
+
+```typescript
+process.env.PW_NET_MODE = 'playback';
+
+test.describe('Movie CRUD - offline with network recorder', () => {
+  test.beforeEach(async ({ page, networkRecorder, context }) => {
+    await networkRecorder.setup(context);
+    await page.goto('/');
+  });
+
+  test('should add, edit, delete movie browser-only', async ({ page, interceptNetworkCall }) => {
+    // Create
+    await page.fill('#movie-name', 'Inception');
+    await page.fill('#year', '2010');
+    await page.click('#add-movie');
+
+    // Verify create (reads from stateful HAR)
+    await expect(page.getByText('Inception')).toBeVisible();
+
+    // Update
+    await page.getByText('Inception').click();
+    await page.fill('#movie-name', "Inception Director's Cut");
+
+    const updateCall = interceptNetworkCall({
+      method: 'PUT',
+      url: '/movies/*',
+    });
+
+    await page.click('#save');
+    await updateCall; // Wait for update
+
+    // Verify update (HAR reflects state change!)
+    await page.click('#back');
+    await expect(page.getByText("Inception Director's Cut")).toBeVisible();
+
+    // Delete
+    await page.click(`[data-testid="delete-Inception Director's Cut"]`);
+
+    // Verify delete (HAR reflects removal!)
+    await expect(page.getByText("Inception Director's Cut")).not.toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Full CRUD operations work offline
+- Stateful HAR mocking tracks creates/updates/deletes
+- Combine with `interceptNetworkCall` for deterministic waits
+- First run records, subsequent runs replay
+
+### Example 3: Environment Switching
+
+**Context**: Record in dev environment, play back in CI with different base URLs.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Map URLs for different environments
+export default defineConfig({
+  use: {
+    baseURL: process.env.CI ? 'https://app.ci.example.com' : 'http://localhost:3000',
+  },
+});
+
+// Test works in both environments
+test('cross-environment playback', async ({ page, context, networkRecorder }) => {
+  await networkRecorder.setup(context);
+
+  // In dev: hits http://localhost:3000/api/movies
+  // In CI: HAR replays with https://app.ci.example.com/api/movies
+  await page.goto('/movies');
+
+  // Network recorder auto-maps URLs
+  await expect(page.getByTestId('movie-list')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- HAR files record absolute URLs
+- Playback maps to current baseURL
+- Same HAR works across environments
+- No manual URL rewriting needed
+
+### Example 4: Automatic vs Manual Mode Control
+
+**Context**: Choose between environment-based switching or in-test mode control.
+
+**Implementation**:
+
+```typescript
+// Option 1: Environment variable (recommended for CI)
+PW_NET_MODE=record npm run test:pw   # Record traffic
+PW_NET_MODE=playback npm run test:pw # Playback traffic
+
+// Option 2: In-test control (recommended for development)
+process.env.PW_NET_MODE = 'record'  // Set at top of test file
+
+test('my test', async ({ page, context, networkRecorder }) => {
+  await networkRecorder.setup(context)
+  // ...
+})
+
+// Option 3: Auto-fallback (record if HAR missing, else playback)
+// This is the default behavior when PW_NET_MODE not set
+test('auto mode', async ({ page, context, networkRecorder }) => {
+  await networkRecorder.setup(context)
+  // First run: auto-records
+  // Subsequent runs: auto-plays back
+})
+```
+
+**Key Points**:
+
+- Three mode options: record, playback, auto
+- `PW_NET_MODE` environment variable
+- In-test `process.env.PW_NET_MODE` assignment
+- Auto-fallback when no mode specified
+
+## Why Use This Instead of Native Playwright?
+
+| Native Playwright (`routeFromHAR`) | network-recorder Utility       |
+| ---------------------------------- | ------------------------------ |
+| ~80 lines setup boilerplate        | ~5 lines total                 |
+| Manual HAR file management         | Automatic file organization    |
+| Complex setup/teardown             | Automatic cleanup via fixtures |
+| **Read-only tests**                | **Full CRUD support**          |
+| **Stateless**                      | **Stateful mocking**           |
+| Manual URL mapping                 | Automatic environment mapping  |
+
+**The game-changer: Stateful CRUD detection**
+
+Native Playwright HAR playback is stateless - a POST create followed by GET list won't show the created item. This utility intelligently tracks CRUD operations in memory to reflect state changes, making offline tests behave like real APIs.
+
+## Integration with Other Utilities
+
+**With interceptNetworkCall** (deterministic waits):
+
+```typescript
+test('use both utilities', async ({ page, context, networkRecorder, interceptNetworkCall }) => {
+  await networkRecorder.setup(context);
+
+  const createCall = interceptNetworkCall({
+    method: 'POST',
+    url: '/api/movies',
+  });
+
+  await page.click('#add-movie');
+  await createCall; // Wait for create (works with HAR!)
+
+  // Network recorder provides playback, intercept provides determinism
+});
+```
+
+## Related Fragments
+
+- `overview.md` - Installation and fixture patterns
+- `intercept-network-call.md` - Combine for deterministic offline tests
+- `auth-session.md` - Record authenticated traffic
+- `network-first.md` - Core pattern for intercept-before-navigate
+
+## Anti-Patterns
+
+**❌ Mixing record and playback in same test:**
+
+```typescript
+process.env.PW_NET_MODE = 'record';
+// ... some test code ...
+process.env.PW_NET_MODE = 'playback'; // Don't switch mid-test
+```
+
+**✅ One mode per test:**
+
+```typescript
+process.env.PW_NET_MODE = 'playback'; // Set once at top
+
+test('my test', async ({ page, context, networkRecorder }) => {
+  await networkRecorder.setup(context);
+  // Entire test uses playback mode
+});
+```
+
+**❌ Forgetting to call setup:**
+
+```typescript
+test('broken', async ({ page, networkRecorder }) => {
+  await page.goto('/'); // HAR not active!
+});
+```
+
+**✅ Always call setup before navigation:**
+
+```typescript
+test('correct', async ({ page, context, networkRecorder }) => {
+  await networkRecorder.setup(context); // Must setup first
+  await page.goto('/'); // Now HAR is active
+});
+```

_bmad/bmm/testarch/knowledge/nfr-criteria.md

@@ -0,0 +1,670 @@
+# Non-Functional Requirements (NFR) Criteria
+
+## Principle
+
+Non-functional requirements (security, performance, reliability, maintainability) are **validated through automated tests**, not checklists. NFR assessment uses objective pass/fail criteria tied to measurable thresholds. Ambiguous requirements default to CONCERNS until clarified.
+
+## Rationale
+
+**The Problem**: Teams ship features that "work" functionally but fail under load, expose security vulnerabilities, or lack error recovery. NFRs are treated as optional "nice-to-haves" instead of release blockers.
+
+**The Solution**: Define explicit NFR criteria with automated validation. Security tests verify auth/authz and secret handling. Performance tests enforce SLO/SLA thresholds with profiling evidence. Reliability tests validate error handling, retries, and health checks. Maintainability is measured by test coverage, code duplication, and observability.
+
+**Why This Matters**:
+
+- Prevents production incidents (security breaches, performance degradation, cascading failures)
+- Provides objective release criteria (no subjective "feels fast enough")
+- Automates compliance validation (audit trail for regulated environments)
+- Forces clarity on ambiguous requirements (default to CONCERNS)
+
+## Pattern Examples
+
+### Example 1: Security NFR Validation (Auth, Secrets, OWASP)
+
+**Context**: Automated security tests enforcing authentication, authorization, and secret handling
+
+**Implementation**:
+
+```typescript
+// tests/nfr/security.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Security NFR: Authentication & Authorization', () => {
+  test('unauthenticated users cannot access protected routes', async ({ page }) => {
+    // Attempt to access dashboard without auth
+    await page.goto('/dashboard');
+
+    // Should redirect to login (not expose data)
+    await expect(page).toHaveURL(/\/login/);
+    await expect(page.getByText('Please sign in')).toBeVisible();
+
+    // Verify no sensitive data leaked in response
+    const pageContent = await page.content();
+    expect(pageContent).not.toContain('user_id');
+    expect(pageContent).not.toContain('api_key');
+  });
+
+  test('JWT tokens expire after 15 minutes', async ({ page, request }) => {
+    // Login and capture token
+    await page.goto('/login');
+    await page.getByLabel('Email').fill('test@example.com');
+    await page.getByLabel('Password').fill('ValidPass123!');
+    await page.getByRole('button', { name: 'Sign In' }).click();
+
+    const token = await page.evaluate(() => localStorage.getItem('auth_token'));
+    expect(token).toBeTruthy();
+
+    // Wait 16 minutes (use mock clock in real tests)
+    await page.clock.fastForward('00:16:00');
+
+    // Token should be expired, API call should fail
+    const response = await request.get('/api/user/profile', {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    expect(response.status()).toBe(401);
+    const body = await response.json();
+    expect(body.error).toContain('expired');
+  });
+
+  test('passwords are never logged or exposed in errors', async ({ page }) => {
+    // Trigger login error
+    await page.goto('/login');
+    await page.getByLabel('Email').fill('test@example.com');
+    await page.getByLabel('Password').fill('WrongPassword123!');
+
+    // Monitor console for password leaks
+    const consoleLogs: string[] = [];
+    page.on('console', (msg) => consoleLogs.push(msg.text()));
+
+    await page.getByRole('button', { name: 'Sign In' }).click();
+
+    // Error shown to user (generic message)
+    await expect(page.getByText('Invalid credentials')).toBeVisible();
+
+    // Verify password NEVER appears in console, DOM, or network
+    const pageContent = await page.content();
+    expect(pageContent).not.toContain('WrongPassword123!');
+    expect(consoleLogs.join('\n')).not.toContain('WrongPassword123!');
+  });
+
+  test('RBAC: users can only access resources they own', async ({ page, request }) => {
+    // Login as User A
+    const userAToken = await login(request, 'userA@example.com', 'password');
+
+    // Try to access User B's order
+    const response = await request.get('/api/orders/user-b-order-id', {
+      headers: { Authorization: `Bearer ${userAToken}` },
+    });
+
+    expect(response.status()).toBe(403); // Forbidden
+    const body = await response.json();
+    expect(body.error).toContain('insufficient permissions');
+  });
+
+  test('SQL injection attempts are blocked', async ({ page }) => {
+    await page.goto('/search');
+
+    // Attempt SQL injection
+    await page.getByPlaceholder('Search products').fill("'; DROP TABLE users; --");
+    await page.getByRole('button', { name: 'Search' }).click();
+
+    // Should return empty results, NOT crash or expose error
+    await expect(page.getByText('No results found')).toBeVisible();
+
+    // Verify app still works (table not dropped)
+    await page.goto('/dashboard');
+    await expect(page.getByText('Welcome')).toBeVisible();
+  });
+
+  test('XSS attempts are sanitized', async ({ page }) => {
+    await page.goto('/profile/edit');
+
+    // Attempt XSS injection
+    const xssPayload = '<script>alert("XSS")</script>';
+    await page.getByLabel('Bio').fill(xssPayload);
+    await page.getByRole('button', { name: 'Save' }).click();
+
+    // Reload and verify XSS is escaped (not executed)
+    await page.reload();
+    const bio = await page.getByTestId('user-bio').textContent();
+
+    // Text should be escaped, script should NOT execute
+    expect(bio).toContain('&lt;script&gt;');
+    expect(bio).not.toContain('<script>');
+  });
+});
+
+// Helper
+async function login(request: any, email: string, password: string): Promise<string> {
+  const response = await request.post('/api/auth/login', {
+    data: { email, password },
+  });
+  const body = await response.json();
+  return body.token;
+}
+```
+
+**Key Points**:
+
+- Authentication: Unauthenticated access redirected (not exposed)
+- Authorization: RBAC enforced (403 for insufficient permissions)
+- Token expiry: JWT expires after 15 minutes (automated validation)
+- Secret handling: Passwords never logged or exposed in errors
+- OWASP Top 10: SQL injection and XSS blocked (input sanitization)
+
+**Security NFR Criteria**:
+
+- ✅ PASS: All 6 tests green (auth, authz, token expiry, secret handling, SQL injection, XSS)
+- ⚠️ CONCERNS: 1-2 tests failing with mitigation plan and owner assigned
+- ❌ FAIL: Critical exposure (unauthenticated access, password leak, SQL injection succeeds)
+
+---
+
+### Example 2: Performance NFR Validation (k6 Load Testing for SLO/SLA)
+
+**Context**: Use k6 for load testing, stress testing, and SLO/SLA enforcement (NOT Playwright)
+
+**Implementation**:
+
+```javascript
+// tests/nfr/performance.k6.js
+import http from 'k6/http';
+import { check, sleep } from 'k6';
+import { Rate, Trend } from 'k6/metrics';
+
+// Custom metrics
+const errorRate = new Rate('errors');
+const apiDuration = new Trend('api_duration');
+
+// Performance thresholds (SLO/SLA)
+export const options = {
+  stages: [
+    { duration: '1m', target: 50 }, // Ramp up to 50 users
+    { duration: '3m', target: 50 }, // Stay at 50 users for 3 minutes
+    { duration: '1m', target: 100 }, // Spike to 100 users
+    { duration: '3m', target: 100 }, // Stay at 100 users
+    { duration: '1m', target: 0 }, // Ramp down
+  ],
+  thresholds: {
+    // SLO: 95% of requests must complete in <500ms
+    http_req_duration: ['p(95)<500'],
+    // SLO: Error rate must be <1%
+    errors: ['rate<0.01'],
+    // SLA: API endpoints must respond in <1s (99th percentile)
+    api_duration: ['p(99)<1000'],
+  },
+};
+
+export default function () {
+  // Test 1: Homepage load performance
+  const homepageResponse = http.get(`${__ENV.BASE_URL}/`);
+  check(homepageResponse, {
+    'homepage status is 200': (r) => r.status === 200,
+    'homepage loads in <2s': (r) => r.timings.duration < 2000,
+  });
+  errorRate.add(homepageResponse.status !== 200);
+
+  // Test 2: API endpoint performance
+  const apiResponse = http.get(`${__ENV.BASE_URL}/api/products?limit=10`, {
+    headers: { Authorization: `Bearer ${__ENV.API_TOKEN}` },
+  });
+  check(apiResponse, {
+    'API status is 200': (r) => r.status === 200,
+    'API responds in <500ms': (r) => r.timings.duration < 500,
+  });
+  apiDuration.add(apiResponse.timings.duration);
+  errorRate.add(apiResponse.status !== 200);
+
+  // Test 3: Search endpoint under load
+  const searchResponse = http.get(`${__ENV.BASE_URL}/api/search?q=laptop&limit=100`);
+  check(searchResponse, {
+    'search status is 200': (r) => r.status === 200,
+    'search responds in <1s': (r) => r.timings.duration < 1000,
+    'search returns results': (r) => JSON.parse(r.body).results.length > 0,
+  });
+  errorRate.add(searchResponse.status !== 200);
+
+  sleep(1); // Realistic user think time
+}
+
+// Threshold validation (run after test)
+export function handleSummary(data) {
+  const p95Duration = data.metrics.http_req_duration.values['p(95)'];
+  const p99ApiDuration = data.metrics.api_duration.values['p(99)'];
+  const errorRateValue = data.metrics.errors.values.rate;
+
+  console.log(`P95 request duration: ${p95Duration.toFixed(2)}ms`);
+  console.log(`P99 API duration: ${p99ApiDuration.toFixed(2)}ms`);
+  console.log(`Error rate: ${(errorRateValue * 100).toFixed(2)}%`);
+
+  return {
+    'summary.json': JSON.stringify(data),
+    stdout: `
+Performance NFR Results:
+- P95 request duration: ${p95Duration < 500 ? '✅ PASS' : '❌ FAIL'} (${p95Duration.toFixed(2)}ms / 500ms threshold)
+- P99 API duration: ${p99ApiDuration < 1000 ? '✅ PASS' : '❌ FAIL'} (${p99ApiDuration.toFixed(2)}ms / 1000ms threshold)
+- Error rate: ${errorRateValue < 0.01 ? '✅ PASS' : '❌ FAIL'} (${(errorRateValue * 100).toFixed(2)}% / 1% threshold)
+    `,
+  };
+}
+```
+
+**Run k6 tests:**
+
+```bash
+# Local smoke test (10 VUs, 30s)
+k6 run --vus 10 --duration 30s tests/nfr/performance.k6.js
+
+# Full load test (stages defined in script)
+k6 run tests/nfr/performance.k6.js
+
+# CI integration with thresholds
+k6 run --out json=performance-results.json tests/nfr/performance.k6.js
+```
+
+**Key Points**:
+
+- **k6 is the right tool** for load testing (NOT Playwright)
+- SLO/SLA thresholds enforced automatically (`p(95)<500`, `rate<0.01`)
+- Realistic load simulation (ramp up, sustained load, spike testing)
+- Comprehensive metrics (p50, p95, p99, error rate, throughput)
+- CI-friendly (JSON output, exit codes based on thresholds)
+
+**Performance NFR Criteria**:
+
+- ✅ PASS: All SLO/SLA targets met with k6 profiling evidence (p95 < 500ms, error rate < 1%)
+- ⚠️ CONCERNS: Trending toward limits (e.g., p95 = 480ms approaching 500ms) or missing baselines
+- ❌ FAIL: SLO/SLA breached (e.g., p95 > 500ms) or error rate > 1%
+
+**Performance Testing Levels (from Test Architect course):**
+
+- **Load testing**: System behavior under expected load
+- **Stress testing**: System behavior under extreme load (breaking point)
+- **Spike testing**: Sudden load increases (traffic spikes)
+- **Endurance/Soak testing**: System behavior under sustained load (memory leaks, resource exhaustion)
+- **Benchmarking**: Baseline measurements for comparison
+
+**Note**: Playwright can validate **perceived performance** (Core Web Vitals via Lighthouse), but k6 validates **system performance** (throughput, latency, resource limits under load)
+
+---
+
+### Example 3: Reliability NFR Validation (Playwright for UI Resilience)
+
+**Context**: Automated reliability tests validating graceful degradation and recovery paths
+
+**Implementation**:
+
+```typescript
+// tests/nfr/reliability.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Reliability NFR: Error Handling & Recovery', () => {
+  test('app remains functional when API returns 500 error', async ({ page, context }) => {
+    // Mock API failure
+    await context.route('**/api/products', (route) => {
+      route.fulfill({ status: 500, body: JSON.stringify({ error: 'Internal Server Error' }) });
+    });
+
+    await page.goto('/products');
+
+    // User sees error message (not blank page or crash)
+    await expect(page.getByText('Unable to load products. Please try again.')).toBeVisible();
+    await expect(page.getByRole('button', { name: 'Retry' })).toBeVisible();
+
+    // App navigation still works (graceful degradation)
+    await page.getByRole('link', { name: 'Home' }).click();
+    await expect(page).toHaveURL('/');
+  });
+
+  test('API client retries on transient failures (3 attempts)', async ({ page, context }) => {
+    let attemptCount = 0;
+
+    await context.route('**/api/checkout', (route) => {
+      attemptCount++;
+
+      // Fail first 2 attempts, succeed on 3rd
+      if (attemptCount < 3) {
+        route.fulfill({ status: 503, body: JSON.stringify({ error: 'Service Unavailable' }) });
+      } else {
+        route.fulfill({ status: 200, body: JSON.stringify({ orderId: '12345' }) });
+      }
+    });
+
+    await page.goto('/checkout');
+    await page.getByRole('button', { name: 'Place Order' }).click();
+
+    // Should succeed after 3 attempts
+    await expect(page.getByText('Order placed successfully')).toBeVisible();
+    expect(attemptCount).toBe(3);
+  });
+
+  test('app handles network disconnection gracefully', async ({ page, context }) => {
+    await page.goto('/dashboard');
+
+    // Simulate offline mode
+    await context.setOffline(true);
+
+    // Trigger action requiring network
+    await page.getByRole('button', { name: 'Refresh Data' }).click();
+
+    // User sees offline indicator (not crash)
+    await expect(page.getByText('You are offline. Changes will sync when reconnected.')).toBeVisible();
+
+    // Reconnect
+    await context.setOffline(false);
+    await page.getByRole('button', { name: 'Refresh Data' }).click();
+
+    // Data loads successfully
+    await expect(page.getByText('Data updated')).toBeVisible();
+  });
+
+  test('health check endpoint returns service status', async ({ request }) => {
+    const response = await request.get('/api/health');
+
+    expect(response.status()).toBe(200);
+
+    const health = await response.json();
+    expect(health).toHaveProperty('status', 'healthy');
+    expect(health).toHaveProperty('timestamp');
+    expect(health).toHaveProperty('services');
+
+    // Verify critical services are monitored
+    expect(health.services).toHaveProperty('database');
+    expect(health.services).toHaveProperty('cache');
+    expect(health.services).toHaveProperty('queue');
+
+    // All services should be UP
+    expect(health.services.database.status).toBe('UP');
+    expect(health.services.cache.status).toBe('UP');
+    expect(health.services.queue.status).toBe('UP');
+  });
+
+  test('circuit breaker opens after 5 consecutive failures', async ({ page, context }) => {
+    let failureCount = 0;
+
+    await context.route('**/api/recommendations', (route) => {
+      failureCount++;
+      route.fulfill({ status: 500, body: JSON.stringify({ error: 'Service Error' }) });
+    });
+
+    await page.goto('/product/123');
+
+    // Wait for circuit breaker to open (fallback UI appears)
+    await expect(page.getByText('Recommendations temporarily unavailable')).toBeVisible({ timeout: 10000 });
+
+    // Verify circuit breaker stopped making requests after threshold (should be ≤5)
+    expect(failureCount).toBeLessThanOrEqual(5);
+  });
+
+  test('rate limiting gracefully handles 429 responses', async ({ page, context }) => {
+    let requestCount = 0;
+
+    await context.route('**/api/search', (route) => {
+      requestCount++;
+
+      if (requestCount > 10) {
+        // Rate limit exceeded
+        route.fulfill({
+          status: 429,
+          headers: { 'Retry-After': '5' },
+          body: JSON.stringify({ error: 'Rate limit exceeded' }),
+        });
+      } else {
+        route.fulfill({ status: 200, body: JSON.stringify({ results: [] }) });
+      }
+    });
+
+    await page.goto('/search');
+
+    // Make 15 search requests rapidly
+    for (let i = 0; i < 15; i++) {
+      await page.getByPlaceholder('Search').fill(`query-${i}`);
+      await page.getByRole('button', { name: 'Search' }).click();
+    }
+
+    // User sees rate limit message (not crash)
+    await expect(page.getByText('Too many requests. Please wait a moment.')).toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Error handling: Graceful degradation (500 error → user-friendly message + retry button)
+- Retries: 3 attempts on transient failures (503 → eventual success)
+- Offline handling: Network disconnection detected (sync when reconnected)
+- Health checks: `/api/health` monitors database, cache, queue
+- Circuit breaker: Opens after 5 failures (fallback UI, stop retries)
+- Rate limiting: 429 response handled (Retry-After header respected)
+
+**Reliability NFR Criteria**:
+
+- ✅ PASS: Error handling, retries, health checks verified (all 6 tests green)
+- ⚠️ CONCERNS: Partial coverage (e.g., missing circuit breaker) or no telemetry
+- ❌ FAIL: No recovery path (500 error crashes app) or unresolved crash scenarios
+
+---
+
+### Example 4: Maintainability NFR Validation (CI Tools, Not Playwright)
+
+**Context**: Use proper CI tools for code quality validation (coverage, duplication, vulnerabilities)
+
+**Implementation**:
+
+```yaml
+# .github/workflows/nfr-maintainability.yml
+name: NFR - Maintainability
+
+on: [push, pull_request]
+
+jobs:
+  test-coverage:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests with coverage
+        run: npm run test:coverage
+
+      - name: Check coverage threshold (80% minimum)
+        run: |
+          COVERAGE=$(jq '.total.lines.pct' coverage/coverage-summary.json)
+          echo "Coverage: $COVERAGE%"
+          if (( $(echo "$COVERAGE < 80" | bc -l) )); then
+            echo "❌ FAIL: Coverage $COVERAGE% below 80% threshold"
+            exit 1
+          else
+            echo "✅ PASS: Coverage $COVERAGE% meets 80% threshold"
+          fi
+
+  code-duplication:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+
+      - name: Check code duplication (<5% allowed)
+        run: |
+          npx jscpd src/ --threshold 5 --format json --output duplication.json
+          DUPLICATION=$(jq '.statistics.total.percentage' duplication.json)
+          echo "Duplication: $DUPLICATION%"
+          if (( $(echo "$DUPLICATION >= 5" | bc -l) )); then
+            echo "❌ FAIL: Duplication $DUPLICATION% exceeds 5% threshold"
+            exit 1
+          else
+            echo "✅ PASS: Duplication $DUPLICATION% below 5% threshold"
+          fi
+
+  vulnerability-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run npm audit (no critical/high vulnerabilities)
+        run: |
+          npm audit --json > audit.json || true
+          CRITICAL=$(jq '.metadata.vulnerabilities.critical' audit.json)
+          HIGH=$(jq '.metadata.vulnerabilities.high' audit.json)
+          echo "Critical: $CRITICAL, High: $HIGH"
+          if [ "$CRITICAL" -gt 0 ] || [ "$HIGH" -gt 0 ]; then
+            echo "❌ FAIL: Found $CRITICAL critical and $HIGH high vulnerabilities"
+            npm audit
+            exit 1
+          else
+            echo "✅ PASS: No critical/high vulnerabilities"
+          fi
+```
+
+**Playwright Tests for Observability (E2E Validation):**
+
+```typescript
+// tests/nfr/observability.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Maintainability NFR: Observability Validation', () => {
+  test('critical errors are reported to monitoring service', async ({ page, context }) => {
+    const sentryEvents: any[] = [];
+
+    // Mock Sentry SDK to verify error tracking
+    await context.addInitScript(() => {
+      (window as any).Sentry = {
+        captureException: (error: Error) => {
+          console.log('SENTRY_CAPTURE:', JSON.stringify({ message: error.message, stack: error.stack }));
+        },
+      };
+    });
+
+    page.on('console', (msg) => {
+      if (msg.text().includes('SENTRY_CAPTURE:')) {
+        sentryEvents.push(JSON.parse(msg.text().replace('SENTRY_CAPTURE:', '')));
+      }
+    });
+
+    // Trigger error by mocking API failure
+    await context.route('**/api/products', (route) => {
+      route.fulfill({ status: 500, body: JSON.stringify({ error: 'Database Error' }) });
+    });
+
+    await page.goto('/products');
+
+    // Wait for error UI and Sentry capture
+    await expect(page.getByText('Unable to load products')).toBeVisible();
+
+    // Verify error was captured by monitoring
+    expect(sentryEvents.length).toBeGreaterThan(0);
+    expect(sentryEvents[0]).toHaveProperty('message');
+    expect(sentryEvents[0]).toHaveProperty('stack');
+  });
+
+  test('API response times are tracked in telemetry', async ({ request }) => {
+    const response = await request.get('/api/products?limit=10');
+
+    expect(response.ok()).toBeTruthy();
+
+    // Verify Server-Timing header for APM (Application Performance Monitoring)
+    const serverTiming = response.headers()['server-timing'];
+
+    expect(serverTiming).toBeTruthy();
+    expect(serverTiming).toContain('db'); // Database query time
+    expect(serverTiming).toContain('total'); // Total processing time
+  });
+
+  test('structured logging present in application', async ({ request }) => {
+    // Make API call that generates logs
+    const response = await request.post('/api/orders', {
+      data: { productId: '123', quantity: 2 },
+    });
+
+    expect(response.ok()).toBeTruthy();
+
+    // Note: In real scenarios, validate logs in monitoring system (Datadog, CloudWatch)
+    // This test validates the logging contract exists (Server-Timing, trace IDs in headers)
+    const traceId = response.headers()['x-trace-id'];
+    expect(traceId).toBeTruthy(); // Confirms structured logging with correlation IDs
+  });
+});
+```
+
+**Key Points**:
+
+- **Coverage/duplication**: CI jobs (GitHub Actions), not Playwright tests
+- **Vulnerability scanning**: npm audit in CI, not Playwright tests
+- **Observability**: Playwright validates error tracking (Sentry) and telemetry headers
+- **Structured logging**: Validate logging contract (trace IDs, Server-Timing headers)
+- **Separation of concerns**: Build-time checks (coverage, audit) vs runtime checks (error tracking, telemetry)
+
+**Maintainability NFR Criteria**:
+
+- ✅ PASS: Clean code (80%+ coverage from CI, <5% duplication from CI), observability validated in E2E, no critical vulnerabilities from npm audit
+- ⚠️ CONCERNS: Duplication >5%, coverage 60-79%, or unclear ownership
+- ❌ FAIL: Absent tests (<60%), tangled implementations (>10% duplication), or no observability
+
+---
+
+## NFR Assessment Checklist
+
+Before release gate:
+
+- [ ] **Security** (Playwright E2E + Security Tools):
+  - [ ] Auth/authz tests green (unauthenticated redirect, RBAC enforced)
+  - [ ] Secrets never logged or exposed in errors
+  - [ ] OWASP Top 10 validated (SQL injection blocked, XSS sanitized)
+  - [ ] Security audit completed (vulnerability scan, penetration test if applicable)
+
+- [ ] **Performance** (k6 Load Testing):
+  - [ ] SLO/SLA targets met with k6 evidence (p95 <500ms, error rate <1%)
+  - [ ] Load testing completed (expected load)
+  - [ ] Stress testing completed (breaking point identified)
+  - [ ] Spike testing completed (handles traffic spikes)
+  - [ ] Endurance testing completed (no memory leaks under sustained load)
+
+- [ ] **Reliability** (Playwright E2E + API Tests):
+  - [ ] Error handling graceful (500 → user-friendly message + retry)
+  - [ ] Retries implemented (3 attempts on transient failures)
+  - [ ] Health checks monitored (/api/health endpoint)
+  - [ ] Circuit breaker tested (opens after failure threshold)
+  - [ ] Offline handling validated (network disconnection graceful)
+
+- [ ] **Maintainability** (CI Tools):
+  - [ ] Test coverage ≥80% (from CI coverage report)
+  - [ ] Code duplication <5% (from jscpd CI job)
+  - [ ] No critical/high vulnerabilities (from npm audit CI job)
+  - [ ] Structured logging validated (Playwright validates telemetry headers)
+  - [ ] Error tracking configured (Sentry/monitoring integration validated)
+
+- [ ] **Ambiguous requirements**: Default to CONCERNS (force team to clarify thresholds and evidence)
+- [ ] **NFR criteria documented**: Measurable thresholds defined (not subjective "fast enough")
+- [ ] **Automated validation**: NFR tests run in CI pipeline (not manual checklists)
+- [ ] **Tool selection**: Right tool for each NFR (k6 for performance, Playwright for security/reliability E2E, CI tools for maintainability)
+
+## NFR Gate Decision Matrix
+
+| Category            | PASS Criteria                                | CONCERNS Criteria                            | FAIL Criteria                                  |
+| ------------------- | -------------------------------------------- | -------------------------------------------- | ---------------------------------------------- |
+| **Security**        | Auth/authz, secret handling, OWASP verified  | Minor gaps with clear owners                 | Critical exposure or missing controls          |
+| **Performance**     | Metrics meet SLO/SLA with profiling evidence | Trending toward limits or missing baselines  | SLO/SLA breached or resource leaks detected    |
+| **Reliability**     | Error handling, retries, health checks OK    | Partial coverage or missing telemetry        | No recovery path or unresolved crash scenarios |
+| **Maintainability** | Clean code, tests, docs shipped together     | Duplication, low coverage, unclear ownership | Absent tests, tangled code, no observability   |
+
+**Default**: If targets or evidence are undefined → **CONCERNS** (force team to clarify before sign-off)
+
+## Integration Points
+
+- **Used in workflows**: `*nfr-assess` (automated NFR validation), `*trace` (gate decision Phase 2), `*test-design` (NFR risk assessment via Utility Tree)
+- **Related fragments**: `risk-governance.md` (NFR risk scoring), `probability-impact.md` (NFR impact assessment), `test-quality.md` (maintainability standards), `test-levels-framework.md` (system-level testing for NFRs)
+- **Tools by NFR Category**:
+  - **Security**: Playwright (E2E auth/authz), OWASP ZAP, Burp Suite, npm audit, Snyk
+  - **Performance**: k6 (load/stress/spike/endurance), Lighthouse (Core Web Vitals), Artillery
+  - **Reliability**: Playwright (E2E error handling), API tests (retries, health checks), Chaos Engineering tools
+  - **Maintainability**: GitHub Actions (coverage, duplication, audit), jscpd, Playwright (observability validation)
+
+_Source: Test Architect course (NFR testing approaches, Utility Tree, Quality Scenarios), ISO/IEC 25010 Software Quality Characteristics, OWASP Top 10, k6 documentation, SRE practices_

_bmad/bmm/testarch/knowledge/overview.md

@@ -0,0 +1,283 @@
+# Playwright Utils Overview
+
+## Principle
+
+Use production-ready, fixture-based utilities from `@seontechnologies/playwright-utils` for common Playwright testing patterns. Build test helpers as pure functions first, then wrap in framework-specific fixtures for composability and reuse.
+
+## Rationale
+
+Writing Playwright utilities from scratch for every project leads to:
+
+- Duplicated code across test suites
+- Inconsistent patterns and quality
+- Maintenance burden when Playwright APIs change
+- Missing advanced features (schema validation, HAR recording, auth persistence)
+
+`@seontechnologies/playwright-utils` provides:
+
+- **Production-tested utilities**: Used at SEON Technologies in production
+- **Functional-first design**: Core logic as pure functions, fixtures for convenience
+- **Composable fixtures**: Use `mergeTests` to combine utilities
+- **TypeScript support**: Full type safety with generic types
+- **Comprehensive coverage**: API requests, auth, network, logging, file handling, burn-in
+
+## Installation
+
+```bash
+npm install -D @seontechnologies/playwright-utils
+```
+
+**Peer Dependencies:**
+
+- `@playwright/test` >= 1.54.1 (required)
+- `ajv` >= 8.0.0 (optional - for JSON Schema validation)
+- `zod` >= 3.0.0 (optional - for Zod schema validation)
+
+## Available Utilities
+
+### Core Testing Utilities
+
+| Utility                    | Purpose                                    | Test Context  |
+| -------------------------- | ------------------------------------------ | ------------- |
+| **api-request**            | Typed HTTP client with schema validation   | API tests     |
+| **network-recorder**       | HAR record/playback for offline testing    | UI tests      |
+| **auth-session**           | Token persistence, multi-user auth         | Both UI & API |
+| **recurse**                | Cypress-style polling for async conditions | Both UI & API |
+| **intercept-network-call** | Network spy/stub with auto JSON parsing    | UI tests      |
+| **log**                    | Playwright report-integrated logging       | Both UI & API |
+| **file-utils**             | CSV/XLSX/PDF/ZIP reading & validation      | Both UI & API |
+| **burn-in**                | Smart test selection with git diff         | CI/CD         |
+| **network-error-monitor**  | Automatic HTTP 4xx/5xx detection           | UI tests      |
+
+## Design Patterns
+
+### Pattern 1: Functional Core, Fixture Shell
+
+**Context**: All utilities follow the same architectural pattern - pure function as core, fixture as wrapper.
+
+**Implementation**:
+
+```typescript
+// Direct import (pass Playwright context explicitly)
+import { apiRequest } from '@seontechnologies/playwright-utils';
+
+test('direct usage', async ({ request }) => {
+  const { status, body } = await apiRequest({
+    request, // Must pass request context
+    method: 'GET',
+    path: '/api/users',
+  });
+});
+
+// Fixture import (context injected automatically)
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('fixture usage', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    // No need to pass request context
+    method: 'GET',
+    path: '/api/users',
+  });
+});
+```
+
+**Key Points**:
+
+- Pure functions testable without Playwright running
+- Fixtures inject framework dependencies automatically
+- Choose direct import (more control) or fixture (convenience)
+
+### Pattern 2: Subpath Imports for Tree-Shaking
+
+**Context**: Import only what you need to keep bundle sizes small.
+
+**Implementation**:
+
+```typescript
+// Import specific utility
+import { apiRequest } from '@seontechnologies/playwright-utils/api-request';
+
+// Import specific fixture
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+// Import everything (use sparingly)
+import { apiRequest, recurse, log } from '@seontechnologies/playwright-utils';
+```
+
+**Key Points**:
+
+- Subpath imports enable tree-shaking
+- Keep bundle sizes minimal
+- Import from specific paths for production builds
+
+### Pattern 3: Fixture Composition with mergeTests
+
+**Context**: Combine multiple playwright-utils fixtures with your own custom fixtures.
+
+**Implementation**:
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { mergeTests } from '@playwright/test';
+import { test as apiRequestFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as recurseFixture } from '@seontechnologies/playwright-utils/recurse/fixtures';
+import { test as logFixture } from '@seontechnologies/playwright-utils/log/fixtures';
+
+// Merge all fixtures into one test object
+export const test = mergeTests(apiRequestFixture, authFixture, recurseFixture, logFixture);
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// In your tests
+import { test, expect } from '../support/merged-fixtures';
+
+test('all utilities available', async ({ apiRequest, authToken, recurse, log }) => {
+  await log.step('Making authenticated API request');
+
+  const { body } = await apiRequest({
+    method: 'GET',
+    path: '/api/protected',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  await recurse(
+    () => apiRequest({ method: 'GET', path: `/status/${body.id}` }),
+    (res) => res.body.ready === true,
+  );
+});
+```
+
+**Key Points**:
+
+- `mergeTests` combines multiple fixtures without conflicts
+- Create one merged-fixtures.ts file per project
+- Import test object from your merged fixtures in all tests
+- All utilities available in single test signature
+
+## Integration with Existing Tests
+
+### Gradual Adoption Strategy
+
+**1. Start with logging** (zero breaking changes):
+
+```typescript
+import { log } from '@seontechnologies/playwright-utils';
+
+test('existing test', async ({ page }) => {
+  await log.step('Navigate to page'); // Just add logging
+  await page.goto('/dashboard');
+  // Rest of test unchanged
+});
+```
+
+**2. Add API utilities** (for API tests):
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test('API test', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/users',
+  });
+
+  expect(status).toBe(200);
+});
+```
+
+**3. Expand to network utilities** (for UI tests):
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('UI with network control', async ({ page, interceptNetworkCall }) => {
+  const usersCall = interceptNetworkCall({
+    url: '**/api/users',
+  });
+
+  await page.goto('/dashboard');
+  const { responseJson } = await usersCall;
+
+  expect(responseJson).toHaveLength(10);
+});
+```
+
+**4. Full integration** (merged fixtures):
+
+Create merged-fixtures.ts and use across all tests.
+
+## Related Fragments
+
+- `api-request.md` - HTTP client with schema validation
+- `network-recorder.md` - HAR-based offline testing
+- `auth-session.md` - Token management
+- `intercept-network-call.md` - Network interception
+- `recurse.md` - Polling patterns
+- `log.md` - Logging utility
+- `file-utils.md` - File operations
+- `fixtures-composition.md` - Advanced mergeTests patterns
+
+## Anti-Patterns
+
+**❌ Don't mix direct and fixture imports in same test:**
+
+```typescript
+import { apiRequest } from '@seontechnologies/playwright-utils';
+import { test } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+
+test('bad', async ({ request, authToken }) => {
+  // Confusing - mixing direct (needs request) and fixture (has authToken)
+  await apiRequest({ request, method: 'GET', path: '/api/users' });
+});
+```
+
+**✅ Use consistent import style:**
+
+```typescript
+import { test } from '../support/merged-fixtures';
+
+test('good', async ({ apiRequest, authToken }) => {
+  // Clean - all from fixtures
+  await apiRequest({ method: 'GET', path: '/api/users' });
+});
+```
+
+**❌ Don't import everything when you need one utility:**
+
+```typescript
+import * as utils from '@seontechnologies/playwright-utils'; // Large bundle
+```
+
+**✅ Use subpath imports:**
+
+```typescript
+import { apiRequest } from '@seontechnologies/playwright-utils/api-request'; // Small bundle
+```
+
+## Reference Implementation
+
+The official `@seontechnologies/playwright-utils` repository provides working examples of all patterns described in these fragments.
+
+**Repository:** <https://github.com/seontechnologies/playwright-utils>
+
+**Key resources:**
+
+- **Test examples:** `playwright/tests` - All utilities in action
+- **Framework setup:** `playwright.config.ts`, `playwright/support/merged-fixtures.ts`
+- **CI patterns:** `.github/workflows/` - GitHub Actions with sharding, parallelization
+
+**Quick start:**
+
+```bash
+git clone https://github.com/seontechnologies/playwright-utils.git
+cd playwright-utils
+nvm use
+npm install
+npm run test:pw-ui  # Explore tests with Playwright UI
+npm run test:pw
+```
+
+All patterns in TEA fragments are production-tested in this repository.

_bmad/bmm/testarch/knowledge/playwright-config.md

@@ -0,0 +1,730 @@
+# Playwright Configuration Guardrails
+
+## Principle
+
+Load environment configs via a central map (`envConfigMap`), standardize timeouts (action 15s, navigation 30s, expect 10s, test 60s), emit HTML + JUnit reporters, and store artifacts under `test-results/` for CI upload. Keep `.env.example`, `.nvmrc`, and browser dependencies versioned so local and CI runs stay aligned.
+
+## Rationale
+
+Environment-specific configuration prevents hardcoded URLs, timeouts, and credentials from leaking into tests. A central config map with fail-fast validation catches missing environments early. Standardized timeouts reduce flakiness while remaining long enough for real-world network conditions. Consistent artifact storage (`test-results/`, `playwright-report/`) enables CI pipelines to upload failure evidence automatically. Versioned dependencies (`.nvmrc`, `package.json` browser versions) eliminate "works on my machine" issues between local and CI environments.
+
+## Pattern Examples
+
+### Example 1: Environment-Based Configuration
+
+**Context**: When testing against multiple environments (local, staging, production), use a central config map that loads environment-specific settings and fails fast if `TEST_ENV` is invalid.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Central config loader
+import { config as dotenvConfig } from 'dotenv';
+import path from 'path';
+
+// Load .env from project root
+dotenvConfig({
+  path: path.resolve(__dirname, '../../.env'),
+});
+
+// Central environment config map
+const envConfigMap = {
+  local: require('./playwright/config/local.config').default,
+  staging: require('./playwright/config/staging.config').default,
+  production: require('./playwright/config/production.config').default,
+};
+
+const environment = process.env.TEST_ENV || 'local';
+
+// Fail fast if environment not supported
+if (!Object.keys(envConfigMap).includes(environment)) {
+  console.error(`❌ No configuration found for environment: ${environment}`);
+  console.error(`   Available environments: ${Object.keys(envConfigMap).join(', ')}`);
+  process.exit(1);
+}
+
+console.log(`✅ Running tests against: ${environment.toUpperCase()}`);
+
+export default envConfigMap[environment as keyof typeof envConfigMap];
+```
+
+```typescript
+// playwright/config/base.config.ts - Shared base configuration
+import { defineConfig } from '@playwright/test';
+import path from 'path';
+
+export const baseConfig = defineConfig({
+  testDir: path.resolve(__dirname, '../tests'),
+  outputDir: path.resolve(__dirname, '../../test-results'),
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: [
+    ['html', { outputFolder: 'playwright-report', open: 'never' }],
+    ['junit', { outputFile: 'test-results/results.xml' }],
+    ['list'],
+  ],
+  use: {
+    actionTimeout: 15000,
+    navigationTimeout: 30000,
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+    video: 'retain-on-failure',
+  },
+  globalSetup: path.resolve(__dirname, '../support/global-setup.ts'),
+  timeout: 60000,
+  expect: { timeout: 10000 },
+});
+```
+
+```typescript
+// playwright/config/local.config.ts - Local environment
+import { defineConfig } from '@playwright/test';
+import { baseConfig } from './base.config';
+
+export default defineConfig({
+  ...baseConfig,
+  use: {
+    ...baseConfig.use,
+    baseURL: 'http://localhost:3000',
+    video: 'off', // No video locally for speed
+  },
+  webServer: {
+    command: 'npm run dev',
+    url: 'http://localhost:3000',
+    reuseExistingServer: !process.env.CI,
+    timeout: 120000,
+  },
+});
+```
+
+```typescript
+// playwright/config/staging.config.ts - Staging environment
+import { defineConfig } from '@playwright/test';
+import { baseConfig } from './base.config';
+
+export default defineConfig({
+  ...baseConfig,
+  use: {
+    ...baseConfig.use,
+    baseURL: 'https://staging.example.com',
+    ignoreHTTPSErrors: true, // Allow self-signed certs in staging
+  },
+});
+```
+
+```typescript
+// playwright/config/production.config.ts - Production environment
+import { defineConfig } from '@playwright/test';
+import { baseConfig } from './base.config';
+
+export default defineConfig({
+  ...baseConfig,
+  retries: 3, // More retries in production
+  use: {
+    ...baseConfig.use,
+    baseURL: 'https://example.com',
+    video: 'on', // Always record production failures
+  },
+});
+```
+
+```bash
+# .env.example - Template for developers
+TEST_ENV=local
+API_KEY=your_api_key_here
+DATABASE_URL=postgresql://localhost:5432/test_db
+```
+
+**Key Points**:
+
+- Central `envConfigMap` prevents environment misconfiguration
+- Fail-fast validation with clear error message (available envs listed)
+- Base config defines shared settings, environment configs override
+- `.env.example` provides template for required secrets
+- `TEST_ENV=local` as default for local development
+- Production config increases retries and enables video recording
+
+### Example 2: Timeout Standards
+
+**Context**: When tests fail due to inconsistent timeout settings, standardize timeouts across all tests: action 15s, navigation 30s, expect 10s, test 60s. Expose overrides through fixtures rather than inline literals.
+
+**Implementation**:
+
+```typescript
+// playwright/config/base.config.ts - Standardized timeouts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  // Global test timeout: 60 seconds
+  timeout: 60000,
+
+  use: {
+    // Action timeout: 15 seconds (click, fill, etc.)
+    actionTimeout: 15000,
+
+    // Navigation timeout: 30 seconds (page.goto, page.reload)
+    navigationTimeout: 30000,
+  },
+
+  // Expect timeout: 10 seconds (all assertions)
+  expect: {
+    timeout: 10000,
+  },
+});
+```
+
+```typescript
+// playwright/support/fixtures/timeout-fixture.ts - Timeout override fixture
+import { test as base } from '@playwright/test';
+
+type TimeoutOptions = {
+  extendedTimeout: (timeoutMs: number) => Promise<void>;
+};
+
+export const test = base.extend<TimeoutOptions>({
+  extendedTimeout: async ({}, use, testInfo) => {
+    const originalTimeout = testInfo.timeout;
+
+    await use(async (timeoutMs: number) => {
+      testInfo.setTimeout(timeoutMs);
+    });
+
+    // Restore original timeout after test
+    testInfo.setTimeout(originalTimeout);
+  },
+});
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// Usage in tests - Standard timeouts (implicit)
+import { test, expect } from '@playwright/test';
+
+test('user can log in', async ({ page }) => {
+  await page.goto('/login'); // Uses 30s navigation timeout
+  await page.fill('[data-testid="email"]', 'test@example.com'); // Uses 15s action timeout
+  await page.click('[data-testid="login-button"]'); // Uses 15s action timeout
+
+  await expect(page.getByText('Welcome')).toBeVisible(); // Uses 10s expect timeout
+});
+```
+
+```typescript
+// Usage in tests - Per-test timeout override
+import { test, expect } from '../support/fixtures/timeout-fixture';
+
+test('slow data processing operation', async ({ page, extendedTimeout }) => {
+  // Override default 60s timeout for this slow test
+  await extendedTimeout(180000); // 3 minutes
+
+  await page.goto('/data-processing');
+  await page.click('[data-testid="process-large-file"]');
+
+  // Wait for long-running operation
+  await expect(page.getByText('Processing complete')).toBeVisible({
+    timeout: 120000, // 2 minutes for assertion
+  });
+});
+```
+
+```typescript
+// Per-assertion timeout override (inline)
+test('API returns quickly', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // Override expect timeout for fast API (reduce flakiness detection)
+  await expect(page.getByTestId('user-name')).toBeVisible({ timeout: 5000 }); // 5s instead of 10s
+
+  // Override expect timeout for slow external API
+  await expect(page.getByTestId('weather-widget')).toBeVisible({ timeout: 20000 }); // 20s instead of 10s
+});
+```
+
+**Key Points**:
+
+- **Standardized timeouts**: action 15s, navigation 30s, expect 10s, test 60s (global defaults)
+- Fixture-based override (`extendedTimeout`) for slow tests (preferred over inline)
+- Per-assertion timeout override via `{ timeout: X }` option (use sparingly)
+- Avoid hard waits (`page.waitForTimeout(3000)`) - use event-based waits instead
+- CI environments may need longer timeouts (handle in environment-specific config)
+
+### Example 3: Artifact Output Configuration
+
+**Context**: When debugging failures in CI, configure artifacts (screenshots, videos, traces, HTML reports) to be captured on failure and stored in consistent locations for upload.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Artifact configuration
+import { defineConfig } from '@playwright/test';
+import path from 'path';
+
+export default defineConfig({
+  // Output directory for test artifacts
+  outputDir: path.resolve(__dirname, './test-results'),
+
+  use: {
+    // Screenshot on failure only (saves space)
+    screenshot: 'only-on-failure',
+
+    // Video recording on failure + retry
+    video: 'retain-on-failure',
+
+    // Trace recording on first retry (best debugging data)
+    trace: 'on-first-retry',
+  },
+
+  reporter: [
+    // HTML report (visual, interactive)
+    [
+      'html',
+      {
+        outputFolder: 'playwright-report',
+        open: 'never', // Don't auto-open in CI
+      },
+    ],
+
+    // JUnit XML (CI integration)
+    [
+      'junit',
+      {
+        outputFile: 'test-results/results.xml',
+      },
+    ],
+
+    // List reporter (console output)
+    ['list'],
+  ],
+});
+```
+
+```typescript
+// playwright/support/fixtures/artifact-fixture.ts - Custom artifact capture
+import { test as base } from '@playwright/test';
+import fs from 'fs';
+import path from 'path';
+
+export const test = base.extend({
+  // Auto-capture console logs on failure
+  page: async ({ page }, use, testInfo) => {
+    const logs: string[] = [];
+
+    page.on('console', (msg) => {
+      logs.push(`[${msg.type()}] ${msg.text()}`);
+    });
+
+    await use(page);
+
+    // Save logs on failure
+    if (testInfo.status !== testInfo.expectedStatus) {
+      const logsPath = path.join(testInfo.outputDir, 'console-logs.txt');
+      fs.writeFileSync(logsPath, logs.join('\n'));
+      testInfo.attachments.push({
+        name: 'console-logs',
+        contentType: 'text/plain',
+        path: logsPath,
+      });
+    }
+  },
+});
+```
+
+```yaml
+# .github/workflows/e2e.yml - CI artifact upload
+name: E2E Tests
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps
+
+      - name: Run tests
+        run: npm run test
+        env:
+          TEST_ENV: staging
+
+      # Upload test artifacts on failure
+      - name: Upload test results
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results
+          path: test-results/
+          retention-days: 30
+
+      - name: Upload Playwright report
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 30
+```
+
+```typescript
+// Example: Custom screenshot on specific condition
+test('capture screenshot on specific error', async ({ page }) => {
+  await page.goto('/checkout');
+
+  try {
+    await page.click('[data-testid="submit-payment"]');
+    await expect(page.getByText('Order Confirmed')).toBeVisible();
+  } catch (error) {
+    // Capture custom screenshot with timestamp
+    await page.screenshot({
+      path: `test-results/payment-error-${Date.now()}.png`,
+      fullPage: true,
+    });
+    throw error;
+  }
+});
+```
+
+**Key Points**:
+
+- `screenshot: 'only-on-failure'` saves space (not every test)
+- `video: 'retain-on-failure'` captures full flow on failures
+- `trace: 'on-first-retry'` provides deep debugging data (network, DOM, console)
+- HTML report at `playwright-report/` (visual debugging)
+- JUnit XML at `test-results/results.xml` (CI integration)
+- CI uploads artifacts on failure with 30-day retention
+- Custom fixture can capture console logs, network logs, etc.
+
+### Example 4: Parallelization Configuration
+
+**Context**: When tests run slowly in CI, configure parallelization with worker count, sharding, and fully parallel execution to maximize speed while maintaining stability.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Parallelization settings
+import { defineConfig } from '@playwright/test';
+import os from 'os';
+
+export default defineConfig({
+  // Run tests in parallel within single file
+  fullyParallel: true,
+
+  // Worker configuration
+  workers: process.env.CI
+    ? 1 // Serial in CI for stability (or 2 for faster CI)
+    : os.cpus().length - 1, // Parallel locally (leave 1 CPU for OS)
+
+  // Prevent accidentally committed .only() from blocking CI
+  forbidOnly: !!process.env.CI,
+
+  // Retry failed tests in CI
+  retries: process.env.CI ? 2 : 0,
+
+  // Shard configuration (split tests across multiple machines)
+  shard:
+    process.env.SHARD_INDEX && process.env.SHARD_TOTAL
+      ? {
+          current: parseInt(process.env.SHARD_INDEX, 10),
+          total: parseInt(process.env.SHARD_TOTAL, 10),
+        }
+      : undefined,
+});
+```
+
+```yaml
+# .github/workflows/e2e-parallel.yml - Sharded CI execution
+name: E2E Tests (Parallel)
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [1, 2, 3, 4] # Split tests across 4 machines
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps
+
+      - name: Run tests (shard ${{ matrix.shard }})
+        run: npm run test
+        env:
+          SHARD_INDEX: ${{ matrix.shard }}
+          SHARD_TOTAL: 4
+          TEST_ENV: staging
+
+      - name: Upload test results
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results-shard-${{ matrix.shard }}
+          path: test-results/
+```
+
+```typescript
+// playwright/config/serial.config.ts - Serial execution for flaky tests
+import { defineConfig } from '@playwright/test';
+import { baseConfig } from './base.config';
+
+export default defineConfig({
+  ...baseConfig,
+
+  // Disable parallel execution
+  fullyParallel: false,
+  workers: 1,
+
+  // Used for: authentication flows, database-dependent tests, feature flag tests
+});
+```
+
+```typescript
+// Usage: Force serial execution for specific tests
+import { test } from '@playwright/test';
+
+// Serial execution for auth tests (shared session state)
+test.describe.configure({ mode: 'serial' });
+
+test.describe('Authentication Flow', () => {
+  test('user can log in', async ({ page }) => {
+    // First test in serial block
+  });
+
+  test('user can access dashboard', async ({ page }) => {
+    // Depends on previous test (serial)
+  });
+});
+```
+
+```typescript
+// Usage: Parallel execution for independent tests (default)
+import { test } from '@playwright/test';
+
+test.describe('Product Catalog', () => {
+  test('can view product 1', async ({ page }) => {
+    // Runs in parallel with other tests
+  });
+
+  test('can view product 2', async ({ page }) => {
+    // Runs in parallel with other tests
+  });
+});
+```
+
+**Key Points**:
+
+- `fullyParallel: true` enables parallel execution within single test file
+- Workers: 1 in CI (stability), N-1 CPUs locally (speed)
+- Sharding splits tests across multiple CI machines (4x faster with 4 shards)
+- `test.describe.configure({ mode: 'serial' })` for dependent tests
+- `forbidOnly: true` in CI prevents `.only()` from blocking pipeline
+- Matrix strategy in CI runs shards concurrently
+
+### Example 5: Project Configuration
+
+**Context**: When testing across multiple browsers, devices, or configurations, use Playwright projects to run the same tests against different environments (chromium, firefox, webkit, mobile).
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Multiple browser projects
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  projects: [
+    // Desktop browsers
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+    {
+      name: 'firefox',
+      use: { ...devices['Desktop Firefox'] },
+    },
+    {
+      name: 'webkit',
+      use: { ...devices['Desktop Safari'] },
+    },
+
+    // Mobile browsers
+    {
+      name: 'mobile-chrome',
+      use: { ...devices['Pixel 5'] },
+    },
+    {
+      name: 'mobile-safari',
+      use: { ...devices['iPhone 13'] },
+    },
+
+    // Tablet
+    {
+      name: 'tablet',
+      use: { ...devices['iPad Pro'] },
+    },
+  ],
+});
+```
+
+```typescript
+// playwright.config.ts - Authenticated vs. unauthenticated projects
+import { defineConfig } from '@playwright/test';
+import path from 'path';
+
+export default defineConfig({
+  projects: [
+    // Setup project (runs first, creates auth state)
+    {
+      name: 'setup',
+      testMatch: /global-setup\.ts/,
+    },
+
+    // Authenticated tests (reuse auth state)
+    {
+      name: 'authenticated',
+      dependencies: ['setup'],
+      use: {
+        storageState: path.resolve(__dirname, './playwright/.auth/user.json'),
+      },
+      testMatch: /.*authenticated\.spec\.ts/,
+    },
+
+    // Unauthenticated tests (public pages)
+    {
+      name: 'unauthenticated',
+      testMatch: /.*unauthenticated\.spec\.ts/,
+    },
+  ],
+});
+```
+
+```typescript
+// playwright/support/global-setup.ts - Setup project for auth
+import { chromium, FullConfig } from '@playwright/test';
+import path from 'path';
+
+async function globalSetup(config: FullConfig) {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+
+  // Perform authentication
+  await page.goto('http://localhost:3000/login');
+  await page.fill('[data-testid="email"]', 'test@example.com');
+  await page.fill('[data-testid="password"]', 'password123');
+  await page.click('[data-testid="login-button"]');
+
+  // Wait for authentication to complete
+  await page.waitForURL('**/dashboard');
+
+  // Save authentication state
+  await page.context().storageState({
+    path: path.resolve(__dirname, '../.auth/user.json'),
+  });
+
+  await browser.close();
+}
+
+export default globalSetup;
+```
+
+```bash
+# Run specific project
+npx playwright test --project=chromium
+npx playwright test --project=mobile-chrome
+npx playwright test --project=authenticated
+
+# Run multiple projects
+npx playwright test --project=chromium --project=firefox
+
+# Run all projects (default)
+npx playwright test
+```
+
+```typescript
+// Usage: Project-specific test
+import { test, expect } from '@playwright/test';
+
+test('mobile navigation works', async ({ page, isMobile }) => {
+  await page.goto('/');
+
+  if (isMobile) {
+    // Open mobile menu
+    await page.click('[data-testid="hamburger-menu"]');
+  }
+
+  await page.click('[data-testid="products-link"]');
+  await expect(page).toHaveURL(/.*products/);
+});
+```
+
+```yaml
+# .github/workflows/e2e-cross-browser.yml - CI cross-browser testing
+name: E2E Tests (Cross-Browser)
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        project: [chromium, firefox, webkit, mobile-chrome]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+      - run: npm ci
+      - run: npx playwright install --with-deps
+
+      - name: Run tests (${{ matrix.project }})
+        run: npx playwright test --project=${{ matrix.project }}
+```
+
+**Key Points**:
+
+- Projects enable testing across browsers, devices, and configurations
+- `devices` from `@playwright/test` provide preset configurations (Pixel 5, iPhone 13, etc.)
+- `dependencies` ensures setup project runs first (auth, data seeding)
+- `storageState` shares authentication across tests (0 seconds auth per test)
+- `testMatch` filters which tests run in which project
+- CI matrix strategy runs projects in parallel (4x faster with 4 projects)
+- `isMobile` context property for conditional logic in tests
+
+## Integration Points
+
+- **Used in workflows**: `*framework` (config setup), `*ci` (parallelization, artifact upload)
+- **Related fragments**:
+  - `fixture-architecture.md` - Fixture-based timeout overrides
+  - `ci-burn-in.md` - CI pipeline artifact upload
+  - `test-quality.md` - Timeout standards (no hard waits)
+  - `data-factories.md` - Per-test isolation (no shared global state)
+
+## Configuration Checklist
+
+**Before deploying tests, verify**:
+
+- [ ] Environment config map with fail-fast validation
+- [ ] Standardized timeouts (action 15s, navigation 30s, expect 10s, test 60s)
+- [ ] Artifact storage at `test-results/` and `playwright-report/`
+- [ ] HTML + JUnit reporters configured
+- [ ] `.env.example`, `.nvmrc`, browser versions committed
+- [ ] Parallelization configured (workers, sharding)
+- [ ] Projects defined for cross-browser/device testing (if needed)
+- [ ] CI uploads artifacts on failure with 30-day retention
+
+_Source: Playwright book repo, SEON configuration example, Murat testing philosophy (lines 216-271)._

_bmad/bmm/testarch/knowledge/probability-impact.md

@@ -0,0 +1,601 @@
+# Probability and Impact Scale
+
+## Principle
+
+Risk scoring uses a **probability × impact** matrix (1-9 scale) to prioritize testing efforts. Higher scores (6-9) demand immediate action; lower scores (1-3) require documentation only. This systematic approach ensures testing resources focus on the highest-value risks.
+
+## Rationale
+
+**The Problem**: Without quantifiable risk assessment, teams over-test low-value scenarios while missing critical risks. Gut feeling leads to inconsistent prioritization and missed edge cases.
+
+**The Solution**: Standardize risk evaluation with a 3×3 matrix (probability: 1-3, impact: 1-3). Multiply to derive risk score (1-9). Automate classification (DOCUMENT, MONITOR, MITIGATE, BLOCK) based on thresholds. This approach surfaces hidden risks early and justifies testing decisions to stakeholders.
+
+**Why This Matters**:
+
+- Consistent risk language across product, engineering, and QA
+- Objective prioritization of test scenarios (not politics)
+- Automatic gate decisions (score=9 → FAIL until resolved)
+- Audit trail for compliance and retrospectives
+
+## Pattern Examples
+
+### Example 1: Probability-Impact Matrix Implementation (Automated Classification)
+
+**Context**: Implement a reusable risk scoring system with automatic threshold classification
+
+**Implementation**:
+
+```typescript
+// src/testing/risk-matrix.ts
+
+/**
+ * Probability levels:
+ * 1 = Unlikely (standard implementation, low uncertainty)
+ * 2 = Possible (edge cases or partial unknowns)
+ * 3 = Likely (known issues, new integrations, high ambiguity)
+ */
+export type Probability = 1 | 2 | 3;
+
+/**
+ * Impact levels:
+ * 1 = Minor (cosmetic issues or easy workarounds)
+ * 2 = Degraded (partial feature loss or manual workaround)
+ * 3 = Critical (blockers, data/security/regulatory exposure)
+ */
+export type Impact = 1 | 2 | 3;
+
+/**
+ * Risk score (probability × impact): 1-9
+ */
+export type RiskScore = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+
+/**
+ * Action categories based on risk score thresholds
+ */
+export type RiskAction = 'DOCUMENT' | 'MONITOR' | 'MITIGATE' | 'BLOCK';
+
+export type RiskAssessment = {
+  probability: Probability;
+  impact: Impact;
+  score: RiskScore;
+  action: RiskAction;
+  reasoning: string;
+};
+
+/**
+ * Calculate risk score: probability × impact
+ */
+export function calculateRiskScore(probability: Probability, impact: Impact): RiskScore {
+  return (probability * impact) as RiskScore;
+}
+
+/**
+ * Classify risk action based on score thresholds:
+ * - 1-3: DOCUMENT (awareness only)
+ * - 4-5: MONITOR (watch closely, plan mitigations)
+ * - 6-8: MITIGATE (CONCERNS at gate until mitigated)
+ * - 9: BLOCK (automatic FAIL until resolved or waived)
+ */
+export function classifyRiskAction(score: RiskScore): RiskAction {
+  if (score >= 9) return 'BLOCK';
+  if (score >= 6) return 'MITIGATE';
+  if (score >= 4) return 'MONITOR';
+  return 'DOCUMENT';
+}
+
+/**
+ * Full risk assessment with automatic classification
+ */
+export function assessRisk(params: { probability: Probability; impact: Impact; reasoning: string }): RiskAssessment {
+  const { probability, impact, reasoning } = params;
+
+  const score = calculateRiskScore(probability, impact);
+  const action = classifyRiskAction(score);
+
+  return { probability, impact, score, action, reasoning };
+}
+
+/**
+ * Generate risk matrix visualization (3x3 grid)
+ * Returns markdown table with color-coded scores
+ */
+export function generateRiskMatrix(): string {
+  const matrix: string[][] = [];
+  const header = ['Impact \\ Probability', 'Unlikely (1)', 'Possible (2)', 'Likely (3)'];
+  matrix.push(header);
+
+  const impactLabels = ['Critical (3)', 'Degraded (2)', 'Minor (1)'];
+  for (let impact = 3; impact >= 1; impact--) {
+    const row = [impactLabels[3 - impact]];
+    for (let probability = 1; probability <= 3; probability++) {
+      const score = calculateRiskScore(probability as Probability, impact as Impact);
+      const action = classifyRiskAction(score);
+      const emoji = action === 'BLOCK' ? '🔴' : action === 'MITIGATE' ? '🟠' : action === 'MONITOR' ? '🟡' : '🟢';
+      row.push(`${emoji} ${score}`);
+    }
+    matrix.push(row);
+  }
+
+  return matrix.map((row) => `| ${row.join(' | ')} |`).join('\n');
+}
+```
+
+**Key Points**:
+
+- Type-safe probability/impact (1-3 enforced at compile time)
+- Automatic action classification (DOCUMENT, MONITOR, MITIGATE, BLOCK)
+- Visual matrix generation for documentation
+- Risk score formula: `probability * impact` (max = 9)
+- Threshold-based decision rules (6-8 = MITIGATE, 9 = BLOCK)
+
+---
+
+### Example 2: Risk Assessment Workflow (Test Planning Integration)
+
+**Context**: Apply risk matrix during test design to prioritize scenarios
+
+**Implementation**:
+
+```typescript
+// tests/e2e/test-planning/risk-assessment.ts
+import { assessRisk, generateRiskMatrix, type RiskAssessment } from '../../../src/testing/risk-matrix';
+
+export type TestScenario = {
+  id: string;
+  title: string;
+  feature: string;
+  risk: RiskAssessment;
+  testLevel: 'E2E' | 'API' | 'Unit';
+  priority: 'P0' | 'P1' | 'P2' | 'P3';
+  owner: string;
+};
+
+/**
+ * Assess test scenarios and auto-assign priority based on risk score
+ */
+export function assessTestScenarios(scenarios: Omit<TestScenario, 'risk' | 'priority'>[]): TestScenario[] {
+  return scenarios.map((scenario) => {
+    // Auto-assign priority based on risk score
+    const priority = mapRiskToPriority(scenario.risk.score);
+    return { ...scenario, priority };
+  });
+}
+
+/**
+ * Map risk score to test priority (P0-P3)
+ * P0: Critical (score 9) - blocks release
+ * P1: High (score 6-8) - must fix before release
+ * P2: Medium (score 4-5) - fix if time permits
+ * P3: Low (score 1-3) - document and defer
+ */
+function mapRiskToPriority(score: number): 'P0' | 'P1' | 'P2' | 'P3' {
+  if (score === 9) return 'P0';
+  if (score >= 6) return 'P1';
+  if (score >= 4) return 'P2';
+  return 'P3';
+}
+
+/**
+ * Example: Payment flow risk assessment
+ */
+export const paymentScenarios: Array<Omit<TestScenario, 'priority'>> = [
+  {
+    id: 'PAY-001',
+    title: 'Valid credit card payment completes successfully',
+    feature: 'Checkout',
+    risk: assessRisk({
+      probability: 2, // Possible (standard Stripe integration)
+      impact: 3, // Critical (revenue loss if broken)
+      reasoning: 'Core revenue flow, but Stripe is well-tested',
+    }),
+    testLevel: 'E2E',
+    owner: 'qa-team',
+  },
+  {
+    id: 'PAY-002',
+    title: 'Expired credit card shows user-friendly error',
+    feature: 'Checkout',
+    risk: assessRisk({
+      probability: 3, // Likely (edge case handling often buggy)
+      impact: 2, // Degraded (users see error, but can retry)
+      reasoning: 'Error handling logic is custom and complex',
+    }),
+    testLevel: 'E2E',
+    owner: 'qa-team',
+  },
+  {
+    id: 'PAY-003',
+    title: 'Payment confirmation email formatting is correct',
+    feature: 'Email',
+    risk: assessRisk({
+      probability: 2, // Possible (template changes occasionally break)
+      impact: 1, // Minor (cosmetic issue, email still sent)
+      reasoning: 'Non-blocking, users get email regardless',
+    }),
+    testLevel: 'Unit',
+    owner: 'dev-team',
+  },
+  {
+    id: 'PAY-004',
+    title: 'Payment fails gracefully when Stripe is down',
+    feature: 'Checkout',
+    risk: assessRisk({
+      probability: 1, // Unlikely (Stripe has 99.99% uptime)
+      impact: 3, // Critical (complete checkout failure)
+      reasoning: 'Rare but catastrophic, requires retry mechanism',
+    }),
+    testLevel: 'API',
+    owner: 'qa-team',
+  },
+];
+
+/**
+ * Generate risk assessment report with priority distribution
+ */
+export function generateRiskReport(scenarios: TestScenario[]): string {
+  const priorityCounts = scenarios.reduce(
+    (acc, s) => {
+      acc[s.priority] = (acc[s.priority] || 0) + 1;
+      return acc;
+    },
+    {} as Record<string, number>,
+  );
+
+  const actionCounts = scenarios.reduce(
+    (acc, s) => {
+      acc[s.risk.action] = (acc[s.risk.action] || 0) + 1;
+      return acc;
+    },
+    {} as Record<string, number>,
+  );
+
+  return `
+# Risk Assessment Report
+
+## Risk Matrix
+${generateRiskMatrix()}
+
+## Priority Distribution
+- **P0 (Blocker)**: ${priorityCounts.P0 || 0} scenarios
+- **P1 (High)**: ${priorityCounts.P1 || 0} scenarios
+- **P2 (Medium)**: ${priorityCounts.P2 || 0} scenarios
+- **P3 (Low)**: ${priorityCounts.P3 || 0} scenarios
+
+## Action Required
+- **BLOCK**: ${actionCounts.BLOCK || 0} scenarios (auto-fail gate)
+- **MITIGATE**: ${actionCounts.MITIGATE || 0} scenarios (concerns at gate)
+- **MONITOR**: ${actionCounts.MONITOR || 0} scenarios (watch closely)
+- **DOCUMENT**: ${actionCounts.DOCUMENT || 0} scenarios (awareness only)
+
+## Scenarios by Risk Score (Highest First)
+${scenarios
+  .sort((a, b) => b.risk.score - a.risk.score)
+  .map((s) => `- **[${s.priority}]** ${s.id}: ${s.title} (Score: ${s.risk.score} - ${s.risk.action})`)
+  .join('\n')}
+`.trim();
+}
+```
+
+**Key Points**:
+
+- Risk score → Priority mapping (P0-P3 automated)
+- Report generation with priority/action distribution
+- Scenarios sorted by risk score (highest first)
+- Visual matrix included in reports
+- Reusable across projects (extract to shared library)
+
+---
+
+### Example 3: Dynamic Risk Re-Assessment (Continuous Evaluation)
+
+**Context**: Recalculate risk scores as project evolves (requirements change, mitigations implemented)
+
+**Implementation**:
+
+```typescript
+// src/testing/risk-tracking.ts
+import { type RiskAssessment, assessRisk, type Probability, type Impact } from './risk-matrix';
+
+export type RiskHistory = {
+  timestamp: Date;
+  assessment: RiskAssessment;
+  changedBy: string;
+  reason: string;
+};
+
+export type TrackedRisk = {
+  id: string;
+  title: string;
+  feature: string;
+  currentRisk: RiskAssessment;
+  history: RiskHistory[];
+  mitigations: string[];
+  status: 'OPEN' | 'MITIGATED' | 'WAIVED' | 'RESOLVED';
+};
+
+export class RiskTracker {
+  private risks: Map<string, TrackedRisk> = new Map();
+
+  /**
+   * Add new risk to tracker
+   */
+  addRisk(params: {
+    id: string;
+    title: string;
+    feature: string;
+    probability: Probability;
+    impact: Impact;
+    reasoning: string;
+    changedBy: string;
+  }): TrackedRisk {
+    const { id, title, feature, probability, impact, reasoning, changedBy } = params;
+
+    const assessment = assessRisk({ probability, impact, reasoning });
+
+    const risk: TrackedRisk = {
+      id,
+      title,
+      feature,
+      currentRisk: assessment,
+      history: [
+        {
+          timestamp: new Date(),
+          assessment,
+          changedBy,
+          reason: 'Initial assessment',
+        },
+      ],
+      mitigations: [],
+      status: 'OPEN',
+    };
+
+    this.risks.set(id, risk);
+    return risk;
+  }
+
+  /**
+   * Reassess risk (probability or impact changed)
+   */
+  reassessRisk(params: {
+    id: string;
+    probability?: Probability;
+    impact?: Impact;
+    reasoning: string;
+    changedBy: string;
+  }): TrackedRisk | null {
+    const { id, probability, impact, reasoning, changedBy } = params;
+    const risk = this.risks.get(id);
+    if (!risk) return null;
+
+    // Use existing values if not provided
+    const newProbability = probability ?? risk.currentRisk.probability;
+    const newImpact = impact ?? risk.currentRisk.impact;
+
+    const newAssessment = assessRisk({
+      probability: newProbability,
+      impact: newImpact,
+      reasoning,
+    });
+
+    risk.currentRisk = newAssessment;
+    risk.history.push({
+      timestamp: new Date(),
+      assessment: newAssessment,
+      changedBy,
+      reason: reasoning,
+    });
+
+    this.risks.set(id, risk);
+    return risk;
+  }
+
+  /**
+   * Mark risk as mitigated (probability reduced)
+   */
+  mitigateRisk(params: { id: string; newProbability: Probability; mitigation: string; changedBy: string }): TrackedRisk | null {
+    const { id, newProbability, mitigation, changedBy } = params;
+    const risk = this.reassessRisk({
+      id,
+      probability: newProbability,
+      reasoning: `Mitigation implemented: ${mitigation}`,
+      changedBy,
+    });
+
+    if (risk) {
+      risk.mitigations.push(mitigation);
+      if (risk.currentRisk.action === 'DOCUMENT' || risk.currentRisk.action === 'MONITOR') {
+        risk.status = 'MITIGATED';
+      }
+    }
+
+    return risk;
+  }
+
+  /**
+   * Get risks requiring action (MITIGATE or BLOCK)
+   */
+  getRisksRequiringAction(): TrackedRisk[] {
+    return Array.from(this.risks.values()).filter(
+      (r) => r.status === 'OPEN' && (r.currentRisk.action === 'MITIGATE' || r.currentRisk.action === 'BLOCK'),
+    );
+  }
+
+  /**
+   * Generate risk trend report (show changes over time)
+   */
+  generateTrendReport(riskId: string): string | null {
+    const risk = this.risks.get(riskId);
+    if (!risk) return null;
+
+    return `
+# Risk Trend Report: ${risk.id}
+
+**Title**: ${risk.title}
+**Feature**: ${risk.feature}
+**Status**: ${risk.status}
+
+## Current Assessment
+- **Probability**: ${risk.currentRisk.probability}
+- **Impact**: ${risk.currentRisk.impact}
+- **Score**: ${risk.currentRisk.score}
+- **Action**: ${risk.currentRisk.action}
+- **Reasoning**: ${risk.currentRisk.reasoning}
+
+## Mitigations Applied
+${risk.mitigations.length > 0 ? risk.mitigations.map((m) => `- ${m}`).join('\n') : '- None'}
+
+## History (${risk.history.length} changes)
+${risk.history
+  .reverse()
+  .map((h) => `- **${h.timestamp.toISOString()}** by ${h.changedBy}: Score ${h.assessment.score} (${h.assessment.action}) - ${h.reason}`)
+  .join('\n')}
+`.trim();
+  }
+}
+```
+
+**Key Points**:
+
+- Historical tracking (audit trail for risk changes)
+- Mitigation impact tracking (probability reduction)
+- Status lifecycle (OPEN → MITIGATED → RESOLVED)
+- Trend reports (show risk evolution over time)
+- Re-assessment triggers (requirements change, new info)
+
+---
+
+### Example 4: Risk Matrix in Gate Decision (Integration with Trace Workflow)
+
+**Context**: Use probability-impact scores to drive gate decisions (PASS/CONCERNS/FAIL/WAIVED)
+
+**Implementation**:
+
+```typescript
+// src/testing/gate-decision.ts
+import { type RiskScore, classifyRiskAction, type RiskAction } from './risk-matrix';
+import { type TrackedRisk } from './risk-tracking';
+
+export type GateDecision = 'PASS' | 'CONCERNS' | 'FAIL' | 'WAIVED';
+
+export type GateResult = {
+  decision: GateDecision;
+  blockers: TrackedRisk[]; // Score=9, action=BLOCK
+  concerns: TrackedRisk[]; // Score 6-8, action=MITIGATE
+  monitored: TrackedRisk[]; // Score 4-5, action=MONITOR
+  documented: TrackedRisk[]; // Score 1-3, action=DOCUMENT
+  summary: string;
+};
+
+/**
+ * Evaluate gate based on risk assessments
+ */
+export function evaluateGateFromRisks(risks: TrackedRisk[]): GateResult {
+  const blockers = risks.filter((r) => r.currentRisk.action === 'BLOCK' && r.status === 'OPEN');
+  const concerns = risks.filter((r) => r.currentRisk.action === 'MITIGATE' && r.status === 'OPEN');
+  const monitored = risks.filter((r) => r.currentRisk.action === 'MONITOR');
+  const documented = risks.filter((r) => r.currentRisk.action === 'DOCUMENT');
+
+  let decision: GateDecision;
+
+  if (blockers.length > 0) {
+    decision = 'FAIL';
+  } else if (concerns.length > 0) {
+    decision = 'CONCERNS';
+  } else {
+    decision = 'PASS';
+  }
+
+  const summary = generateGateSummary({ decision, blockers, concerns, monitored, documented });
+
+  return { decision, blockers, concerns, monitored, documented, summary };
+}
+
+/**
+ * Generate gate decision summary
+ */
+function generateGateSummary(result: Omit<GateResult, 'summary'>): string {
+  const { decision, blockers, concerns, monitored, documented } = result;
+
+  const lines: string[] = [`## Gate Decision: ${decision}`];
+
+  if (decision === 'FAIL') {
+    lines.push(`\n**Blockers** (${blockers.length}): Automatic FAIL until resolved or waived`);
+    blockers.forEach((r) => {
+      lines.push(`- **${r.id}**: ${r.title} (Score: ${r.currentRisk.score})`);
+      lines.push(`  - Probability: ${r.currentRisk.probability}, Impact: ${r.currentRisk.impact}`);
+      lines.push(`  - Reasoning: ${r.currentRisk.reasoning}`);
+    });
+  }
+
+  if (concerns.length > 0) {
+    lines.push(`\n**Concerns** (${concerns.length}): Address before release`);
+    concerns.forEach((r) => {
+      lines.push(`- **${r.id}**: ${r.title} (Score: ${r.currentRisk.score})`);
+      lines.push(`  - Mitigations: ${r.mitigations.join(', ') || 'None'}`);
+    });
+  }
+
+  if (monitored.length > 0) {
+    lines.push(`\n**Monitored** (${monitored.length}): Watch closely`);
+    monitored.forEach((r) => lines.push(`- **${r.id}**: ${r.title} (Score: ${r.currentRisk.score})`));
+  }
+
+  if (documented.length > 0) {
+    lines.push(`\n**Documented** (${documented.length}): Awareness only`);
+  }
+
+  lines.push(`\n---\n`);
+  lines.push(`**Next Steps**:`);
+  if (decision === 'FAIL') {
+    lines.push(`- Resolve blockers or request formal waiver`);
+  } else if (decision === 'CONCERNS') {
+    lines.push(`- Implement mitigations for high-risk scenarios (score 6-8)`);
+    lines.push(`- Re-run gate after mitigations`);
+  } else {
+    lines.push(`- Proceed with release`);
+  }
+
+  return lines.join('\n');
+}
+```
+
+**Key Points**:
+
+- Gate decision driven by risk scores (not gut feeling)
+- Automatic FAIL for score=9 (blockers)
+- CONCERNS for score 6-8 (requires mitigation)
+- PASS only when no blockers/concerns
+- Actionable summary with next steps
+- Integration with trace workflow (Phase 2)
+
+---
+
+## Probability-Impact Threshold Summary
+
+| Score | Action   | Gate Impact          | Typical Use Case                       |
+| ----- | -------- | -------------------- | -------------------------------------- |
+| 1-3   | DOCUMENT | None                 | Cosmetic issues, low-priority bugs     |
+| 4-5   | MONITOR  | None (watch closely) | Edge cases, partial unknowns           |
+| 6-8   | MITIGATE | CONCERNS at gate     | High-impact scenarios needing coverage |
+| 9     | BLOCK    | Automatic FAIL       | Critical blockers, must resolve        |
+
+## Risk Assessment Checklist
+
+Before deploying risk matrix:
+
+- [ ] **Probability scale defined**: 1 (unlikely), 2 (possible), 3 (likely) with clear examples
+- [ ] **Impact scale defined**: 1 (minor), 2 (degraded), 3 (critical) with concrete criteria
+- [ ] **Threshold rules documented**: Score → Action mapping (1-3 = DOCUMENT, 4-5 = MONITOR, 6-8 = MITIGATE, 9 = BLOCK)
+- [ ] **Gate integration**: Risk scores drive gate decisions (PASS/CONCERNS/FAIL/WAIVED)
+- [ ] **Re-assessment process**: Risks re-evaluated as project evolves (requirements change, mitigations applied)
+- [ ] **Audit trail**: Historical tracking for risk changes (who, when, why)
+- [ ] **Mitigation tracking**: Link mitigations to probability reduction (quantify impact)
+- [ ] **Reporting**: Risk matrix visualization, trend reports, gate summaries
+
+## Integration Points
+
+- **Used in workflows**: `*test-design` (initial risk assessment), `*trace` (gate decision Phase 2), `*nfr-assess` (security/performance risks)
+- **Related fragments**: `risk-governance.md` (risk scoring matrix, gate decision engine), `test-priorities-matrix.md` (P0-P3 mapping), `nfr-criteria.md` (impact assessment for NFRs)
+- **Tools**: TypeScript for type safety, markdown for reports, version control for audit trail
+
+_Source: Murat risk model summary, gate decision patterns from production systems, probability-impact matrix from risk governance practices_

_bmad/bmm/testarch/knowledge/recurse.md

@@ -0,0 +1,296 @@
+# Recurse (Polling) Utility
+
+## Principle
+
+Use Cypress-style polling with Playwright's `expect.poll` to wait for asynchronous conditions. Provides configurable timeout, interval, logging, and post-polling callbacks with enhanced error categorization.
+
+## Rationale
+
+Testing async operations (background jobs, eventual consistency, webhook processing) requires polling:
+
+- Vanilla `expect.poll` is verbose
+- No built-in logging for debugging
+- Generic timeout errors
+- No post-poll hooks
+
+The `recurse` utility provides:
+
+- **Clean syntax**: Inspired by cypress-recurse
+- **Enhanced errors**: Timeout vs command failure vs predicate errors
+- **Built-in logging**: Track polling progress
+- **Post-poll callbacks**: Process results after success
+- **Type-safe**: Full TypeScript generic support
+
+## Pattern Examples
+
+### Example 1: Basic Polling
+
+**Context**: Wait for async operation to complete with custom timeout and interval.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/recurse/fixtures';
+
+test('should wait for job completion', async ({ recurse, apiRequest }) => {
+  // Start job
+  const { body } = await apiRequest({
+    method: 'POST',
+    path: '/api/jobs',
+    body: { type: 'export' },
+  });
+
+  // Poll until ready
+  const result = await recurse(
+    () => apiRequest({ method: 'GET', path: `/api/jobs/${body.id}` }),
+    (response) => response.body.status === 'completed',
+    {
+      timeout: 60000, // 60 seconds max
+      interval: 2000, // Check every 2 seconds
+      log: 'Waiting for export job to complete',
+    },
+  );
+
+  expect(result.body.downloadUrl).toBeDefined();
+});
+```
+
+**Key Points**:
+
+- First arg: command function (what to execute)
+- Second arg: predicate function (when to stop)
+- Options: timeout, interval, log message
+- Returns the value when predicate returns true
+
+### Example 2: Polling with Assertions
+
+**Context**: Use assertions directly in predicate for more expressive tests.
+
+**Implementation**:
+
+```typescript
+test('should poll with assertions', async ({ recurse, apiRequest }) => {
+  await apiRequest({
+    method: 'POST',
+    path: '/api/events',
+    body: { type: 'user-created', userId: '123' },
+  });
+
+  // Poll with assertions in predicate
+  await recurse(
+    async () => {
+      const { body } = await apiRequest({ method: 'GET', path: '/api/events/123' });
+      return body;
+    },
+    (event) => {
+      // Use assertions instead of boolean returns
+      expect(event.processed).toBe(true);
+      expect(event.timestamp).toBeDefined();
+      // If assertions pass, predicate succeeds
+    },
+    { timeout: 30000 },
+  );
+});
+```
+
+**Key Points**:
+
+- Predicate can use `expect()` assertions
+- If assertions throw, polling continues
+- If assertions pass, polling succeeds
+- More expressive than boolean returns
+
+### Example 3: Custom Error Messages
+
+**Context**: Provide context-specific error messages for timeout failures.
+
+**Implementation**:
+
+```typescript
+test('custom error on timeout', async ({ recurse, apiRequest }) => {
+  try {
+    await recurse(
+      () => apiRequest({ method: 'GET', path: '/api/status' }),
+      (res) => res.body.ready === true,
+      {
+        timeout: 10000,
+        error: 'System failed to become ready within 10 seconds - check background workers',
+      },
+    );
+  } catch (error) {
+    // Error message includes custom context
+    expect(error.message).toContain('check background workers');
+    throw error;
+  }
+});
+```
+
+**Key Points**:
+
+- `error` option provides custom message
+- Replaces default "Timed out after X ms"
+- Include debugging hints in error message
+- Helps diagnose failures faster
+
+### Example 4: Post-Polling Callback
+
+**Context**: Process or log results after successful polling.
+
+**Implementation**:
+
+```typescript
+test('post-poll processing', async ({ recurse, apiRequest }) => {
+  const finalResult = await recurse(
+    () => apiRequest({ method: 'GET', path: '/api/batch-job/123' }),
+    (res) => res.body.status === 'completed',
+    {
+      timeout: 60000,
+      post: (result) => {
+        // Runs after successful polling
+        console.log(`Job completed in ${result.body.duration}ms`);
+        console.log(`Processed ${result.body.itemsProcessed} items`);
+        return result.body;
+      },
+    },
+  );
+
+  expect(finalResult.itemsProcessed).toBeGreaterThan(0);
+});
+```
+
+**Key Points**:
+
+- `post` callback runs after predicate succeeds
+- Receives the final result
+- Can transform or log results
+- Return value becomes final `recurse` result
+
+### Example 5: Integration with API Request (Common Pattern)
+
+**Context**: Most common use case - polling API endpoints for state changes.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('end-to-end polling', async ({ apiRequest, recurse }) => {
+  // Trigger async operation
+  const { body: createResp } = await apiRequest({
+    method: 'POST',
+    path: '/api/data-import',
+    body: { source: 's3://bucket/data.csv' },
+  });
+
+  // Poll until import completes
+  const importResult = await recurse(
+    () => apiRequest({ method: 'GET', path: `/api/data-import/${createResp.importId}` }),
+    (response) => {
+      const { status, rowsImported } = response.body;
+      return status === 'completed' && rowsImported > 0;
+    },
+    {
+      timeout: 120000, // 2 minutes for large imports
+      interval: 5000, // Check every 5 seconds
+      log: `Polling import ${createResp.importId}`,
+    },
+  );
+
+  expect(importResult.body.rowsImported).toBeGreaterThan(1000);
+  expect(importResult.body.errors).toHaveLength(0);
+});
+```
+
+**Key Points**:
+
+- Combine `apiRequest` + `recurse` for API polling
+- Both from `@seontechnologies/playwright-utils/fixtures`
+- Complex predicates with multiple conditions
+- Logging shows polling progress in test reports
+
+## Enhanced Error Types
+
+The utility categorizes errors for easier debugging:
+
+```typescript
+// TimeoutError - Predicate never returned true
+Error: Polling timed out after 30000ms: Job never completed
+
+// CommandError - Command function threw
+Error: Command failed: Request failed with status 500
+
+// PredicateError - Predicate function threw (not from assertions)
+Error: Predicate failed: Cannot read property 'status' of undefined
+```
+
+## Comparison with Vanilla Playwright
+
+| Vanilla Playwright                                                | recurse Utility                                                           |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `await expect.poll(() => { ... }, { timeout: 30000 }).toBe(true)` | `await recurse(() => { ... }, (val) => val === true, { timeout: 30000 })` |
+| No logging                                                        | Built-in log option                                                       |
+| Generic timeout errors                                            | Categorized errors (timeout/command/predicate)                            |
+| No post-poll hooks                                                | `post` callback support                                                   |
+
+## When to Use
+
+**Use recurse for:**
+
+- ✅ Background job completion
+- ✅ Webhook/event processing
+- ✅ Database eventual consistency
+- ✅ Cache propagation
+- ✅ State machine transitions
+
+**Stick with vanilla expect.poll for:**
+
+- Simple UI element visibility (use `expect(locator).toBeVisible()`)
+- Single-property checks
+- Cases where logging isn't needed
+
+## Related Fragments
+
+- `api-request.md` - Combine for API endpoint polling
+- `overview.md` - Fixture composition patterns
+- `fixtures-composition.md` - Using with mergeTests
+
+## Anti-Patterns
+
+**❌ Using hard waits instead of polling:**
+
+```typescript
+await page.click('#export');
+await page.waitForTimeout(5000); // Arbitrary wait
+expect(await page.textContent('#status')).toBe('Ready');
+```
+
+**✅ Poll for actual condition:**
+
+```typescript
+await page.click('#export');
+await recurse(
+  () => page.textContent('#status'),
+  (status) => status === 'Ready',
+  { timeout: 10000 },
+);
+```
+
+**❌ Polling too frequently:**
+
+```typescript
+await recurse(
+  () => apiRequest({ method: 'GET', path: '/status' }),
+  (res) => res.body.ready,
+  { interval: 100 }, // Hammers API every 100ms!
+);
+```
+
+**✅ Reasonable interval for API calls:**
+
+```typescript
+await recurse(
+  () => apiRequest({ method: 'GET', path: '/status' }),
+  (res) => res.body.ready,
+  { interval: 2000 }, // Check every 2 seconds (reasonable)
+);
+```