@bugzy-ai/bugzy 1.14.0 → 1.15.0

package/dist/cli/index.cjs

@@ -104,9 +104,9 @@ var init_generate_test_cases = __esm({
     generateTestCasesTask = {
       slug: TASK_SLUGS.GENERATE_TEST_CASES,
       name: "Generate Test Cases",
-      description: "Generate manual test case documentation AND automated Playwright test scripts from test plan",
+      description: "Generate manual test case documentation AND automated test scripts from test plan",
       frontmatter: {
-        description: "Generate manual test case documentation AND automated Playwright test scripts from test plan",
+        description: "Generate manual test case documentation AND automated test scripts from test plan",
         "argument-hint": "--type [exploratory|functional|regression|smoke] --focus [optional-feature]"
       },
       steps: [
@@ -114,12 +114,12 @@ var init_generate_test_cases = __esm({
         {
           inline: true,
           title: "Generate Test Cases Overview",
-          content: `Generate comprehensive test artifacts including BOTH manual test case documentation AND automated Playwright test scripts.
+          content: `Generate comprehensive test artifacts including BOTH manual test case documentation AND automated test scripts. Read \`./tests/CLAUDE.md\` for framework-specific conventions, directory structure, and commands.
 
 This command generates:
 1. **Manual Test Case Documentation** (in \`./test-cases/\`) - Human-readable test cases in markdown format
-2. **Automated Playwright Tests** (in \`./tests/specs/\`) - Executable TypeScript test scripts
-3. **Page Object Models** (in \`./tests/pages/\`) - Reusable page classes for automated tests
+2. **Automated Test Scripts** (in directory from \`./tests/CLAUDE.md\`) - Executable test scripts
+3. **Page Objects** (in directory from \`./tests/CLAUDE.md\`) - Reusable page classes for automated tests
 4. **Supporting Files** (fixtures, helpers, components) - As needed for test automation`
         },
         // Step 2: Security Notice (library)
@@ -154,9 +154,9 @@ Read the test plan from \`test-plan.md\` to understand:
 
 **1.2 Check Existing Test Cases and Tests**
 - List all files in \`./test-cases/\` to understand existing manual test coverage
-- List all files in \`./tests/specs/\` to understand existing automated tests
+- List existing automated tests in the test directory (see \`./tests/CLAUDE.md\` for structure)
 - Determine next test case ID (TC-XXX format)
-- Identify existing Page Objects in \`./tests/pages/\`
+- Identify existing page objects (see \`./tests/CLAUDE.md\` for directory)
 - Avoid creating overlapping test cases or duplicate automation`
         },
         // Step 6: Documentation Researcher (conditional library step)
@@ -265,8 +265,8 @@ Before invoking the agent, identify the test cases for the current area:
 - Test type: {type}
 - Test plan: test-plan.md
 - Manual test cases directory: ./test-cases/
-- Existing automated tests: ./tests/specs/
-- Existing Page Objects: ./tests/pages/
+- Existing automated tests: [directory from ./tests/CLAUDE.md]
+- Existing page objects: [directory from ./tests/CLAUDE.md]
 
 **Knowledge Base Patterns (MUST APPLY):**
 Include ALL relevant testing patterns from the knowledge base that apply to this area. For example, if the KB documents timing behaviors (animation delays, loading states), selector gotchas, or recommended assertion approaches \u2014 list them here explicitly and instruct the agent to use the specific patterns described (e.g., specific assertion methods with specific timeouts). The test-code-generator does not have access to the knowledge base, so you MUST relay the exact patterns and recommended code approaches.
@@ -277,7 +277,7 @@ Include ALL relevant testing patterns from the knowledge base that apply to this
 3. Explore the feature area to understand implementation (gather selectors, URLs, flows)
 4. Build missing Page Objects and supporting code
 5. For each test case marked \`automated: true\`:
-   - Create automated Playwright test in ./tests/specs/
+   - Create automated test in the test directory (from ./tests/CLAUDE.md)
    - Update the manual test case file to reference the automated test path
    - Apply ALL knowledge base patterns listed above (timing, selectors, assertions)
 6. Run and iterate on each test until it passes or fails with a product bug
@@ -308,15 +308,7 @@ Move to the next area and repeat until all areas are complete.
         {
           inline: true,
           title: "Create Directories if Needed",
-          content: `Ensure required directories exist:
-\`\`\`bash
-mkdir -p ./test-cases
-mkdir -p ./tests/specs
-mkdir -p ./tests/pages
-mkdir -p ./tests/components
-mkdir -p ./tests/fixtures
-mkdir -p ./tests/helpers
-\`\`\``
+          content: `Ensure required directories exist. Create the \`./test-cases/\` directory for manual test cases, and create the test directories specified in \`./tests/CLAUDE.md\` (test specs, page objects, components, fixtures, helpers).`
         },
         // Step 14: Extract Env Variables (library)
         "extract-env-variables",
@@ -336,7 +328,7 @@ mkdir -p ./tests/helpers
    - Features covered by automation
    - Areas kept manual-only (and why)
 3. Highlight key automated test scenarios
-4. Share command to run automated tests: npx playwright test
+4. Share command to run automated tests (from \`./tests/CLAUDE.md\`)
 5. Ask for team review and validation
 6. Mention any areas needing exploration or clarification
 7. Use appropriate channel and threading for the update
@@ -381,8 +373,8 @@ The team communication should include:
 - Areas kept manual-only (and why)
 
 **Next Steps:**
-- Command to run automated tests: \`npx playwright test\`
-- Instructions to run specific test file
+- Command to run automated tests (from \`./tests/CLAUDE.md\`)
+- Instructions to run specific test file (from \`./tests/CLAUDE.md\`)
 - Note about copying .env.testdata to .env
 - Mention any exploration needed for edge cases
 
@@ -398,7 +390,7 @@ The team communication should include:
 - **Test Independence**: Each test must be runnable in isolation and in parallel`
         }
       ],
-      requiredSubagents: ["test-runner", "test-code-generator"],
+      requiredSubagents: ["browser-automation", "test-code-generator"],
       optionalSubagents: ["documentation-researcher", "team-communicator"],
       dependentTasks: []
     };
@@ -605,7 +597,7 @@ The team communication should include:
 - Instructions for the user to fill in actual values in .env.testdata before running tests`
         }
       ],
-      requiredSubagents: ["test-runner"],
+      requiredSubagents: ["browser-automation"],
       optionalSubagents: ["documentation-researcher", "team-communicator"],
       dependentTasks: []
     };
@@ -697,7 +689,28 @@ The handler file contains all necessary processing logic for the detected intent
 - Response guidelines
 - Memory update instructions`
         },
-        // Step 6: Clarification Protocol (for ambiguous intents)
+        // Step 6: Post Response via Team Communicator
+        {
+          inline: true,
+          title: "Post Response to Team",
+          content: `## Post Response to the Team
+
+After processing the message through the handler and composing your response:
+
+{{INVOKE_TEAM_COMMUNICATOR}} to post the response back to the team.
+
+**Context to include in the delegation:**
+- The original message/question from the team member
+- Your composed response with all gathered data
+- Whether this should be a thread reply (if the original message was in a thread) or a new message
+- The relevant channel (from project-context.md)
+
+**Do NOT:**
+- Skip posting and just display the response as text output
+- Ask the user whether to post \u2014 the message came from the team, the response goes back to the team
+- Compose a draft without sending it`
+        },
+        // Step 7: Clarification Protocol (for ambiguous intents)
         "clarification-protocol",
         // Step 8: Knowledge Base Update (library)
         "update-knowledge-base",
@@ -1122,7 +1135,7 @@ After queuing and notifying, the task is DONE. Do NOT:
 - Execute /verify-changes, /run-tests, /generate-test-cases directly
 - Wait for team response (messaging infrastructure handles that)
 - Create or modify test files
-- Run Playwright tests
+- Run automated tests
 
 #### 5.6 Update Event Processor Memory
 If new patterns discovered, append to \`.bugzy/runtime/memory/event-processor.md\`:
@@ -1237,10 +1250,10 @@ var init_run_tests = __esm({
     runTestsTask = {
       slug: TASK_SLUGS.RUN_TESTS,
       name: "Run Tests",
-      description: "Execute automated Playwright tests, analyze failures, and fix test issues automatically",
+      description: "Execute automated tests, analyze failures, and fix test issues automatically",
       frontmatter: {
-        description: "Execute automated Playwright tests, analyze failures, and fix test issues automatically",
-        "argument-hint": '[file-pattern|tag|all] (e.g., "auth", "@smoke", "tests/specs/login.spec.ts")'
+        description: "Execute automated tests, analyze failures, and fix test issues automatically",
+        "argument-hint": '[file-pattern|tag|all] (e.g., "auth", "@smoke", or a specific test file path)'
       },
       steps: [
         // Step 1: Overview (inline)
@@ -1249,7 +1262,7 @@ var init_run_tests = __esm({
           title: "Run Tests Overview",
           content: `# Run Tests Command
 
-Execute automated Playwright tests, analyze failures using JSON reports, automatically fix test issues, and log product bugs.`
+Execute automated tests, analyze failures using JSON reports, automatically fix test issues, and log product bugs. Read \`./tests/CLAUDE.md\` for framework-specific conventions and commands.`
         },
         // Step 2: Security Notice (library)
         "security-notice",
@@ -1262,9 +1275,9 @@ Execute automated Playwright tests, analyze failures using JSON reports, automat
 **Parse Arguments:**
 Extract the following from arguments:
 - **selector**: Test selection criteria
-  - File pattern: "auth" \u2192 finds tests/specs/**/*auth*.spec.ts
-  - Tag: "@smoke" \u2192 runs tests with @smoke annotation
-  - Specific file: "tests/specs/login.spec.ts"
+  - File pattern: "auth" \u2192 find matching test files (see \`./tests/CLAUDE.md\` for directory structure)
+  - Tag: "@smoke" \u2192 runs tests with tag annotation
+  - Specific file: path to a specific test file
   - All tests: "all" or "" \u2192 runs entire test suite`
         },
         // Step 4: Load Project Context (library)
@@ -1280,34 +1293,26 @@ Extract the following from arguments:
           inline: true,
           title: "Identify Automated Tests to Run",
           content: `#### Understand Test Selection
+
+Read \`./tests/CLAUDE.md\` for the test directory structure, file patterns, and execution commands.
+
 Parse the selector argument to determine which tests to run:
 
 **File Pattern** (e.g., "auth", "login"):
-- Find matching test files: \`tests/specs/**/*[pattern]*.spec.ts\`
+- Find matching test files in the test directory specified by \`./tests/CLAUDE.md\`
 - Example: "auth" \u2192 finds all test files with "auth" in the name
 
 **Tag** (e.g., "@smoke", "@regression"):
-- Run tests with specific Playwright tag annotation
-- Use Playwright's \`--grep\` option
+- Run tests with specific tag annotation using the tag command from \`./tests/CLAUDE.md\`
 
-**Specific File** (e.g., "tests/specs/auth/login.spec.ts"):
-- Run that specific test file
+**Specific File**:
+- Run that specific test file using the single-file command from \`./tests/CLAUDE.md\`
 
 **All Tests** ("all" or no selector):
-- Run entire test suite: \`tests/specs/**/*.spec.ts\`
+- Run entire test suite using the run-all command from \`./tests/CLAUDE.md\`
 
 #### Find Matching Test Files
-Use glob patterns to find test files:
-\`\`\`bash
-# For file pattern
-ls tests/specs/**/*[pattern]*.spec.ts
-
-# For specific file
-ls tests/specs/auth/login.spec.ts
-
-# For all tests
-ls tests/specs/**/*.spec.ts
-\`\`\`
+Use glob patterns to find test files in the directory structure defined by \`./tests/CLAUDE.md\`.
 
 #### Validate Test Files Exist
 Check that at least one test file was found:
@@ -1321,7 +1326,7 @@ Before running tests, confirm the selection with the user if ambiguous:
 - **No selector** (all tests): Confirm running full suite before executing`
         },
         // Step 7-10: Test Execution (library steps)
-        "run-playwright-tests",
+        "run-tests",
         "parse-test-results",
         "triage-failures",
         "fix-test-issues",
@@ -1347,8 +1352,8 @@ If no test cases match the selection criteria:
 2. List available test cases or suggest running \`/generate-test-cases\` first
 3. Provide examples of valid selection criteria
 
-#### If Test Runner Agent Fails
-If the test-runner agent encounters issues:
+#### If Browser Automation Agent Fails
+If the browser-automation agent encounters issues:
 1. Report the specific error
 2. Suggest troubleshooting steps
 3. Offer to run tests individually if batch execution failed
@@ -1362,18 +1367,18 @@ If selected test cases have formatting issues:
 ### Important Notes
 
 **Test Selection Strategy**:
-- **Always read** \`.bugzy/runtime/test-execution-strategy.md\` before selecting tests
+- **Always read** \`./tests/docs/test-execution-strategy.md\` before selecting tests
 - Default to \`@smoke\` tests for fast validation unless user explicitly requests otherwise
 - Smoke tests provide 100% manual test case coverage with zero redundancy (~2-5 min)
 - Full regression includes intentional redundancy for diagnostic value (~10-15 min)
 - Use context keywords from user request to choose appropriate tier
 
 **Test Execution**:
-- Automated Playwright tests are executed via bash command, not through agents
+- Automated tests are executed via bash command, not through agents
 - Test execution time varies by tier (see strategy document for details)
 - JSON reports provide structured test results for analysis
-- Playwright automatically captures traces, screenshots, and videos on failures
-- Test artifacts are stored in test-results/ directory
+- Test framework may capture traces, screenshots, and videos on failures (see \`./tests/CLAUDE.md\`)
+- Test artifacts are stored as defined in \`./tests/CLAUDE.md\`
 
 **Failure Handling**:
 - Test failures are automatically triaged (product bugs vs test issues)
@@ -1383,11 +1388,11 @@ If selected test cases have formatting issues:
 - Critical failures trigger immediate team notification
 
 **Related Documentation**:
-- \`.bugzy/runtime/test-execution-strategy.md\` - When and why to run specific tests
-- \`.bugzy/runtime/testing-best-practices.md\` - How to write tests (patterns and anti-patterns)`
+- \`./tests/docs/test-execution-strategy.md\` - When and why to run specific tests
+- \`./tests/docs/testing-best-practices.md\` - How to write tests (patterns and anti-patterns)`
         }
       ],
-      requiredSubagents: ["test-runner", "test-debugger-fixer"],
+      requiredSubagents: ["browser-automation", "test-debugger-fixer"],
       optionalSubagents: ["issue-tracker", "team-communicator"],
       dependentTasks: []
     };
@@ -1419,7 +1424,7 @@ var init_verify_changes = __esm({
 ## Overview
 
 This task performs comprehensive change verification with:
-- **Automated testing**: Execute Playwright tests with automatic triage and fixing
+- **Automated testing**: Execute automated tests with automatic triage and fixing
 - **Manual verification checklists**: Generate role-specific checklists for non-automatable scenarios
 - **Multi-trigger support**: Works from manual CLI, Slack messages, GitHub PRs, and CI/CD
 - **Smart output routing**: Results formatted and delivered to the appropriate channel`
@@ -1650,11 +1655,11 @@ Analyze the change description to identify affected feature areas:
 
 | Description Keywords | Inferred Test Scope | Example |
 |---------------------|-------------------|---------|
-| "login", "authentication", "sign in/up" | \`tests/specs/auth/\` | "Fix login page validation" -> Auth tests |
-| "checkout", "payment", "purchase" | \`tests/specs/checkout/\` | "Optimize checkout flow" -> Checkout tests |
-| "cart", "shopping cart", "add to cart" | \`tests/specs/cart/\` | "Update cart calculations" -> Cart tests |
+| "login", "authentication", "sign in/up" | Auth test suite | "Fix login page validation" -> Auth tests |
+| "checkout", "payment", "purchase" | Checkout test suite | "Optimize checkout flow" -> Checkout tests |
+| "cart", "shopping cart", "add to cart" | Cart test suite | "Update cart calculations" -> Cart tests |
 | "API", "endpoint", "backend" | API test suites | "Add new user API endpoint" -> User API tests |
-| "profile", "account", "settings" | \`tests/specs/profile/\` or \`tests/specs/settings/\` | "Profile page redesign" -> Profile tests |
+| "profile", "account", "settings" | Profile/settings test suite | "Profile page redesign" -> Profile tests |
 
 **Inference strategy:**
 1. **Extract feature keywords** from PR title and description
@@ -1729,13 +1734,13 @@ If the Jira issue or PR references test accounts/data (e.g., TEST_PREMIUM_USER,
 
 **CRITICAL**: Never conclude "manual verification required" or "BLOCKED" solely because test data is missing. Always create the test artifacts first.
 
-### Generate Playwright Specs
+### Generate Automated Test Specs
 
 {{INVOKE_TEST_CODE_GENERATOR}} to create automated test specs:
 - Read the manual test cases you just created
 - Explore the feature in the browser to discover selectors and flows
-- Create Page Objects in \`./tests/pages/\` if needed
-- Create test specs in \`./tests/specs/\` matching the test cases
+- Create page objects in the directory specified by \`./tests/CLAUDE.md\`
+- Create test specs in the directory specified by \`./tests/CLAUDE.md\`
 - Run each new test to verify it passes
 - Update the manual test case with \`automated_test\` reference
 
@@ -1745,7 +1750,7 @@ Skip this step \u2014 proceed directly to running existing tests.`,
           conditionalOnSubagent: "test-code-generator"
         },
         // Step 8-11: Test Execution (library steps)
-        "run-playwright-tests",
+        "run-tests",
         "parse-test-results",
         "triage-failures",
         "fix-test-issues",
@@ -1934,7 +1939,7 @@ Post PR comment if GitHub context available.`,
 - Recommend: Check test configuration and prerequisites
 
 **If test execution fails:**
-- Report specific error (Playwright not installed, env vars missing)
+- Report specific error (test framework not installed, env vars missing)
 - Suggest troubleshooting steps
 - Don't proceed with triage if tests didn't run
 
@@ -1964,7 +1969,7 @@ A successful verification includes:
 10. Clear recommendation provided (merge / review / block)`
         }
       ],
-      requiredSubagents: ["test-runner", "test-debugger-fixer"],
+      requiredSubagents: ["browser-automation", "test-debugger-fixer"],
       optionalSubagents: ["documentation-researcher", "issue-tracker", "team-communicator", "changelog-historian", "test-code-generator"],
       dependentTasks: []
     };
@@ -2021,7 +2026,7 @@ This command orchestrates the complete test coverage workflow in a single execut
         },
         // Phase 2: Exploration Protocol
         "exploration-protocol",
-        // Execute exploration via test-runner
+        // Execute exploration via browser-automation
         "create-exploration-test-case",
         "run-exploration",
         "process-exploration-results",
@@ -2032,7 +2037,7 @@ This command orchestrates the complete test coverage workflow in a single execut
         "generate-test-cases",
         "automate-test-cases",
         // Phase 5: Test Execution
-        "run-playwright-tests",
+        "run-tests",
         "parse-test-results",
         // Phase 6: Triage and Fix (NEW - was missing from full-test-coverage)
         "triage-failures",
@@ -2049,7 +2054,7 @@ This command orchestrates the complete test coverage workflow in a single execut
         },
         "generate-final-report"
       ],
-      requiredSubagents: ["test-runner", "test-code-generator", "test-debugger-fixer"],
+      requiredSubagents: ["browser-automation", "test-code-generator", "test-debugger-fixer"],
       optionalSubagents: ["documentation-researcher", "team-communicator", "issue-tracker"],
       dependentTasks: ["run-tests", "generate-test-cases"]
     };
@@ -2076,7 +2081,7 @@ var init_explore_application = __esm({
         {
           inline: true,
           title: "Explore Application Overview",
-          content: `Discover actual UI elements, workflows, and behaviors using the test-runner agent. Updates test plan and project documentation with findings.`
+          content: `Discover actual UI elements, workflows, and behaviors using the browser-automation agent. Updates test plan and project documentation with findings.`
         },
         // Step 2: Security Notice (from library)
         "security-notice",
@@ -2123,7 +2128,7 @@ var init_explore_application = __esm({
         "cleanup-temp-files",
         "update-knowledge-base"
       ],
-      requiredSubagents: ["test-runner"],
+      requiredSubagents: ["browser-automation"],
       optionalSubagents: ["team-communicator"],
       dependentTasks: []
     };
@@ -2494,9 +2499,9 @@ var INTEGRATIONS = {
   }
 };
 var SUBAGENTS = {
-  "test-runner": {
-    role: "test-runner",
-    name: "Test Runner",
+  "browser-automation": {
+    role: "browser-automation",
+    name: "Browser Automation",
     description: "Execute automated browser tests (always included)",
     icon: "play",
     integrations: [INTEGRATIONS.playwright],
@@ -2553,7 +2558,7 @@ var SUBAGENTS = {
   "test-code-generator": {
     role: "test-code-generator",
     name: "Test Code Generator",
-    description: "Generate automated Playwright test scripts and Page Objects",
+    description: "Generate automated test scripts and page objects",
     icon: "code",
     integrations: [INTEGRATIONS.playwright],
     model: "sonnet",
@@ -2768,7 +2773,7 @@ init_cjs_shims();
 // src/subagents/templates/index.ts
 init_cjs_shims();
 
-// src/subagents/templates/test-runner/playwright.ts
+// src/subagents/templates/browser-automation/playwright.ts
 init_cjs_shims();
 
 // src/subagents/templates/memory-template.ts
@@ -2815,16 +2820,16 @@ After completing your work, update your memory file with relevant insights.
 **Remember:** Every entry should answer "How does this change what I do?"
 `;
 
-// src/subagents/templates/test-runner/playwright.ts
+// src/subagents/templates/browser-automation/playwright.ts
 var FRONTMATTER = {
-  name: "test-runner",
-  description: `Execute test cases using Playwright browser automation with comprehensive logging and evidence capture. Use this agent when you need to run automated tests with video recording. Examples: <example>Context: The user wants to execute a specific test case that has been written.
+  name: "browser-automation",
+  description: `Execute test cases using browser automation with comprehensive logging and evidence capture. Use this agent when you need to run automated tests with video recording. Examples: <example>Context: The user wants to execute a specific test case that has been written.
 user: "Run the login test case located at ./test-cases/TC-001-login.md"
-assistant: "I'll use the test-runner agent to execute this test case and capture all the results with video evidence."
-<commentary>Since the user wants to execute a test case file, use the Task tool to launch the test-runner agent with the test case file path.</commentary></example> <example>Context: After generating test cases, the user wants to validate them.
+assistant: "I'll use the browser-automation agent to execute this test case and capture all the results with video evidence."
+<commentary>Since the user wants to execute a test case file, use the Task tool to launch the browser-automation agent with the test case file path.</commentary></example> <example>Context: After generating test cases, the user wants to validate them.
 user: "Execute the smoke test for the checkout flow"
-assistant: "Let me use the test-runner agent to execute the checkout smoke test and record all findings with video."
-<commentary>The user needs to run a specific test, so launch the test-runner agent to perform the browser automation with video recording and capture results.</commentary></example>`,
+assistant: "Let me use the browser-automation agent to execute the checkout smoke test and record all findings with video."
+<commentary>The user needs to run a specific test, so launch the browser-automation agent to perform the browser automation with video recording and capture results.</commentary></example>`,
   model: "sonnet",
   color: "green"
 };
@@ -2837,9 +2842,9 @@ var CONTENT = `You are an expert automated test execution specialist with deep e
    - Structure of \`steps.json\` with timestamps and video synchronization
    - Field descriptions and data types
 
-2. ${MEMORY_READ_INSTRUCTIONS.replace(/{ROLE}/g, "test-runner")}
+2. ${MEMORY_READ_INSTRUCTIONS.replace(/{ROLE}/g, "browser-automation")}
 
-   **Memory Sections for Test Runner**:
+   **Memory Sections for Browser Automation**:
    - **Test Execution History**: Pass/fail rates, execution times, flaky test patterns
    - **Flaky Test Tracking**: Tests that pass inconsistently with root cause analysis
    - **Environment-Specific Patterns**: Timing differences across staging/production/local
@@ -2905,7 +2910,7 @@ var CONTENT = `You are an expert automated test execution specialist with deep e
 **Execution Workflow:**
 
 1. **Load Memory** (ALWAYS DO THIS FIRST):
-   - Read \`.bugzy/runtime/memory/test-runner.md\` to access your working knowledge
+   - Read \`.bugzy/runtime/memory/browser-automation.md\` to access your working knowledge
    - Check if this test is known to be flaky (apply extra waits if so)
    - Review timing requirements for pages this test will visit
    - Note environment-specific patterns for current TEST_BASE_URL
@@ -2957,9 +2962,9 @@ var CONTENT = `You are an expert automated test execution specialist with deep e
     - Video filename reference (just basename, not full path)
     - Execution ID in metadata.executionId (from BUGZY_EXECUTION_ID environment variable)
     - All other fields following the schema in \`.bugzy/runtime/templates/test-result-schema.md\`
-15. ${MEMORY_UPDATE_INSTRUCTIONS.replace(/{ROLE}/g, "test-runner")}
+15. ${MEMORY_UPDATE_INSTRUCTIONS.replace(/{ROLE}/g, "browser-automation")}
 
-    Specifically for test-runner, consider updating:
+    Specifically for browser-automation, consider updating:
     - **Test Execution History**: Add test case ID, status, execution time, browser, environment, date
     - **Flaky Test Tracking**: If test failed multiple times, add symptoms and patterns
     - **Timing Requirements by Page**: Document new timing patterns observed
@@ -3033,49 +3038,59 @@ When you encounter ambiguous test steps, make intelligent decisions based on com
 init_cjs_shims();
 var FRONTMATTER2 = {
   name: "test-code-generator",
-  description: `Generate automated Playwright test scripts, Page Objects, and manual test case documentation from test plans. Use this agent when you need to create executable test code. Examples: <example>Context: The user has a test plan and wants to generate automated tests.
+  description: `Generate automated test scripts, page objects, and test case documentation from test plans. Use this agent when you need to create executable test code. Examples: <example>Context: The user has a test plan and wants to generate automated tests.
 user: "Generate test cases for the login feature based on the test plan"
-assistant: "I'll use the test-code-generator agent to create both manual test case documentation and automated Playwright test scripts with Page Objects."
+assistant: "I'll use the test-code-generator agent to create both manual test case documentation and automated test scripts with page objects."
 <commentary>Since the user wants to generate test code from a test plan, use the Task tool to launch the test-code-generator agent.</commentary></example> <example>Context: After exploring the application, the user wants to create automated tests.
 user: "Create automated tests for the checkout flow"
-assistant: "Let me use the test-code-generator agent to generate test scripts, Page Objects, and test case documentation for the checkout flow."
+assistant: "Let me use the test-code-generator agent to generate test scripts, page objects, and test case documentation for the checkout flow."
 <commentary>The user needs automated test generation, so launch the test-code-generator agent to create all necessary test artifacts.</commentary></example>`,
   model: "sonnet",
   color: "purple"
 };
-var CONTENT2 = `You are an expert Playwright test automation engineer specializing in generating high-quality automated test code and comprehensive test case documentation.
+var CONTENT2 = `You are an expert test automation engineer specializing in generating high-quality automated test code and comprehensive test case documentation.
+
+**IMPORTANT: Read \`./tests/CLAUDE.md\` first.** This file defines the test framework, directory structure, conventions, selector strategies, fix patterns, and test execution commands for this project. All generated code must follow these conventions.
 
 **Core Responsibilities:**
 
-1. **Best Practices Reference**: ALWAYS start by reading \`.bugzy/runtime/testing-best-practices.md\`. This guide contains all detailed patterns for Page Object Model, selector strategies, test organization, authentication, TypeScript practices, and anti-patterns. Follow it meticulously.
+1. **Framework Conventions**: Read \`./tests/CLAUDE.md\` to understand:
+   - The test framework and language used
+   - Directory structure (where to put test specs, page objects, fixtures, helpers)
+   - Test structure conventions (how to organize test steps, tagging, etc.)
+   - Selector priority and strategies
+   - How to run tests
+   - Common fix patterns
+
+2. **Best Practices Reference**: Read \`./tests/docs/testing-best-practices.md\` for additional detailed patterns covering test organization, authentication, and anti-patterns. Follow it meticulously.
 
-2. **Environment Configuration**:
+3. **Environment Configuration**:
    - Read \`.env.testdata\` for available environment variables
    - Reference variables using \`process.env.VAR_NAME\` in tests
    - Add new required variables to \`.env.testdata\`
    - NEVER read \`.env\` file (secrets only)
    - **If a required variable is missing from \`.env.testdata\`**: Add it with an empty value and a \`# TODO: configure\` comment. Continue creating tests using \`process.env.VAR_NAME\` \u2014 tests will fail until configured, which is expected. Do NOT skip test creation because of missing data.
 
-3. ${MEMORY_READ_INSTRUCTIONS.replace(/{ROLE}/g, "test-code-generator")}
+4. ${MEMORY_READ_INSTRUCTIONS.replace(/{ROLE}/g, "test-code-generator")}
 
    **Memory Sections for Test Code Generator**:
-   - Generated artifacts (Page Objects, tests, fixtures, helpers)
+   - Generated artifacts (page objects, tests, fixtures, helpers)
    - Test cases automated
    - Selector strategies that work for this application
    - Application architecture patterns learned
    - Environment variables used
    - Test creation history and outcomes
 
-4. **Read Existing Manual Test Cases**: The generate-test-cases task has already created manual test case documentation in ./test-cases/*.md with frontmatter indicating which should be automated (automated: true/false). Your job is to:
+5. **Read Existing Manual Test Cases**: The generate-test-cases task has already created manual test case documentation in ./test-cases/*.md with frontmatter indicating which should be automated (automated: true/false). Your job is to:
    - Read the manual test case files
-   - For test cases marked \`automated: true\`, generate automated Playwright tests
+   - For test cases marked \`automated: true\`, generate automated tests
    - Update the manual test case file with the automated_test reference
-   - Create supporting artifacts: Page Objects, fixtures, helpers, components, types
+   - Create supporting artifacts: page objects, fixtures, helpers, components, types
 
-5. **Mandatory Application Exploration**: NEVER generate Page Objects without exploring the live application first using playwright-cli:
+6. **Mandatory Application Exploration**: NEVER generate page objects without exploring the live application first using playwright-cli:
    - Navigate to pages, authenticate, inspect elements
    - Capture screenshots for documentation
-   - Document exact role names, labels, text, URLs
+   - Document exact element identifiers, labels, text, URLs
    - Test navigation flows manually
    - **NEVER assume selectors** - verify in browser or tests will fail
 
@@ -3083,7 +3098,7 @@ var CONTENT2 = `You are an expert Playwright test automation engineer specializi
 
 1. **Load Memory**:
    - Read \`.bugzy/runtime/memory/test-code-generator.md\`
-   - Check existing Page Objects, automated tests, selector strategies, naming conventions
+   - Check existing page objects, automated tests, selector strategies, naming conventions
    - Avoid duplication by reusing established patterns
 
 2. **Read Manual Test Cases**:
@@ -3097,20 +3112,20 @@ var CONTENT2 = `You are an expert Playwright test automation engineer specializi
 
    **STEP 1: Check Existing Infrastructure**
 
-   - **Review memory**: Check \`.bugzy/runtime/memory/test-code-generator.md\` for existing POMs
-   - **Scan codebase**: Look for relevant Page Objects in \`./tests/pages/\`
-   - **Identify gaps**: Determine what POMs or helpers are missing for this test
+   - **Review memory**: Check \`.bugzy/runtime/memory/test-code-generator.md\` for existing page objects
+   - **Scan codebase**: Look for relevant page objects in the directory specified by \`./tests/CLAUDE.md\`
+   - **Identify gaps**: Determine what page objects or helpers are missing for this test
 
    **STEP 2: Build Missing Infrastructure** (if needed)
 
    - **Explore feature under test**: Use playwright-cli to:
      * Navigate to the feature's pages
-     * Inspect elements and gather selectors (role, label, text)
+     * Inspect elements and gather selectors
      * Document actual URLs from the browser
      * Capture screenshots for documentation
      * Test navigation flows manually
      * NEVER assume selectors - verify everything in browser
-   - **Create Page Objects**: Build POMs for new pages/components using verified selectors
+   - **Create page objects**: Build page objects for new pages/components using verified selectors, following conventions from \`./tests/CLAUDE.md\`
    - **Create supporting code**: Add any needed fixtures, helpers, or types
 
    **STEP 3: Create Automated Test**
@@ -3118,20 +3133,18 @@ var CONTENT2 = `You are an expert Playwright test automation engineer specializi
    - **Read the manual test case** (./test-cases/TC-XXX-*.md):
      * Understand the test objective and steps
      * Note any preconditions or test data requirements
-   - **Generate automated test** (./tests/specs/*.spec.ts):
+   - **Generate automated test** in the directory specified by \`./tests/CLAUDE.md\`:
      * Use the manual test case steps as the basis
-     * Create executable Playwright test using Page Objects
-     * **REQUIRED**: Structure test with \`test.step()\` calls matching the manual test case steps one-to-one
-     * Each test.step() should directly correspond to a numbered step in the manual test case
+     * Follow the test structure conventions from \`./tests/CLAUDE.md\`
      * Reference manual test case ID in comments
-     * Tag critical tests with @smoke
+     * Tag critical tests appropriately (e.g., @smoke)
    - **Update manual test case file**:
      * Set \`automated_test:\` field to the path of the automated test file
      * Link manual \u2194 automated test bidirectionally
 
    **STEP 4: Verify and Fix Until Working** (CRITICAL - up to 3 attempts)
 
-   - **Run test**: Execute \`npx playwright test [test-file]\` using Bash tool
+   - **Run test**: Execute the test using the command from \`./tests/CLAUDE.md\`
    - **Analyze results**:
      * Pass \u2192 Run 2-3 more times to verify stability, then proceed to STEP 5
      * Fail \u2192 Proceed to failure analysis below
@@ -3145,60 +3158,12 @@ var CONTENT2 = `You are an expert Playwright test automation engineer specializi
    | **Product Bug** | Selectors are correct, test logic matches user flow, app behaves unexpectedly, screenshots show app in wrong state | STOP fixing - document as bug, mark test as blocked |
    | **Test Issue** | Selector not found (but element exists), timeout errors, flaky behavior, wrong assertions | Proceed to fix |
 
-   **4b. Fix Patterns** (apply based on root cause):
-
-   **Fix Type 1: Brittle Selectors**
-   - **Problem**: CSS selectors or fragile XPath that breaks when UI changes
-   - **Fix**: Replace with role-based selectors
-   \`\`\`typescript
-   // BEFORE (brittle)
-   await page.locator('.btn-primary').click();
-   // AFTER (semantic)
-   await page.getByRole('button', { name: 'Sign In' }).click();
-   \`\`\`
-
-   **Fix Type 2: Missing Wait Conditions**
-   - **Problem**: Test doesn't wait for elements or actions to complete
-   - **Fix**: Add explicit wait for expected state
-   \`\`\`typescript
-   // BEFORE (race condition)
-   await page.goto('/dashboard');
-   const items = await page.locator('.item').count();
-   // AFTER (explicit wait)
-   await page.goto('/dashboard');
-   await expect(page.locator('.item')).toHaveCount(5);
-   \`\`\`
-
-   **Fix Type 3: Race Conditions**
-   - **Problem**: Test executes actions before application is ready
-   - **Fix**: Wait for specific application state
-   \`\`\`typescript
-   // BEFORE
-   await saveButton.click();
-   await expect(successMessage).toBeVisible();
-   // AFTER
-   await page.locator('.validation-complete').waitFor();
-   await saveButton.click();
-   await expect(successMessage).toBeVisible();
-   \`\`\`
-
-   **Fix Type 4: Wrong Assertions**
-   - **Problem**: Assertion expects incorrect value or state
-   - **Fix**: Update assertion to match actual app behavior (if app is correct)
-
-   **Fix Type 5: Test Isolation Issues**
-   - **Problem**: Test depends on state from previous tests
-   - **Fix**: Add proper setup/teardown or use fixtures
-
-   **Fix Type 6: Flaky Tests**
-   - **Problem**: Test passes inconsistently
-   - **Fix**: Identify non-determinism source (timing, race conditions, animation delays)
-   - Run test 10 times to confirm stability after fix
+   **4b. Fix Patterns**: Refer to the "Common Fix Patterns" section in \`./tests/CLAUDE.md\` for framework-specific fix strategies. Apply the appropriate pattern based on root cause.
 
    **4c. Fix Workflow**:
    1. Read failure report and classify (product bug vs test issue)
    2. If product bug: Document and mark test as blocked, move to next test
-   3. If test issue: Apply appropriate fix from patterns above
+   3. If test issue: Apply appropriate fix pattern from \`./tests/CLAUDE.md\`
    4. Re-run test to verify fix
    5. If still failing: Repeat (max 3 total attempts: exec-1, exec-2, exec-3)
    6. After 3 failed attempts: Reclassify as likely product bug and document
@@ -3207,9 +3172,9 @@ var CONTENT2 = `You are an expert Playwright test automation engineer specializi
 
    | Failure Type | Root Cause | Action |
    |--------------|------------|--------|
-   | Selector not found | Element exists, wrong selector | Replace with semantic selector |
-   | Timeout waiting | Missing wait condition | Add explicit wait |
-   | Flaky (timing) | Race condition | Add synchronization wait |
+   | Selector not found | Element exists, wrong selector | Apply selector fix pattern from CLAUDE.md |
+   | Timeout waiting | Missing wait condition | Apply wait fix pattern from CLAUDE.md |
+   | Flaky (timing) | Race condition | Apply synchronization fix pattern from CLAUDE.md |
    | Wrong assertion | Incorrect expected value | Update assertion (if app is correct) |
    | Test isolation | Depends on other tests | Add setup/teardown or fixtures |
    | Product bug | App behaves incorrectly | STOP - Report as bug, don't fix test |
@@ -3217,13 +3182,13 @@ var CONTENT2 = `You are an expert Playwright test automation engineer specializi
    **STEP 5: Move to Next Test Case**
 
    - Repeat process for each test case in the plan
-   - Reuse existing POMs and infrastructure wherever possible
+   - Reuse existing page objects and infrastructure wherever possible
    - Continuously update memory with new patterns and learnings
 
 4. ${MEMORY_UPDATE_INSTRUCTIONS.replace(/{ROLE}/g, "test-code-generator")}
 
    Specifically for test-code-generator, consider updating:
-   - **Generated Artifacts**: Document Page Objects, tests, fixtures created with details
+   - **Generated Artifacts**: Document page objects, tests, fixtures created with details
    - **Test Cases Automated**: Record which test cases were automated with references
    - **Selector Strategies**: Note what selector strategies work well for this application
    - **Application Patterns**: Document architecture patterns learned
@@ -3233,7 +3198,7 @@ var CONTENT2 = `You are an expert Playwright test automation engineer specializi
    - Test automation results (tests created, pass/fail status, issues found)
    - Manual test cases automated (count, IDs, titles)
    - Automated tests created (count, smoke vs functional)
-   - Page Objects, fixtures, helpers added
+   - Page objects, fixtures, helpers added
    - Next steps (commands to run tests)
 
 **Memory File Structure**: Your memory file (\`.bugzy/runtime/memory/test-code-generator.md\`) should follow this structure:
@@ -3244,7 +3209,7 @@ var CONTENT2 = `You are an expert Playwright test automation engineer specializi
 ## Last Updated: [timestamp]
 
 ## Generated Test Artifacts
-[Page Objects created with locators and methods]
+[Page objects created with locators and methods]
 [Test cases automated with manual TC references and file paths]
 [Fixtures, helpers, components created]
 
@@ -3253,26 +3218,24 @@ var CONTENT2 = `You are an expert Playwright test automation engineer specializi
 [Tests passing vs failing with product bugs]
 
 ## Fixed Issues History
-- [Date] TC-001 login.spec.ts: Replaced CSS selector with getByRole('button', { name: 'Submit' })
-- [Date] TC-003 checkout.spec.ts: Added waitForLoadState for async validation
+- [Date] TC-001: Applied selector fix pattern
+- [Date] TC-003: Applied wait fix pattern for async validation
 
 ## Failure Pattern Library
 
 ### Pattern: Selector Timeout on Dynamic Content
-**Symptoms**: "Timeout waiting for selector", element loads after timeout
+**Symptoms**: Element not found, element loads after timeout
 **Root Cause**: Selector runs before element rendered
-**Fix Strategy**: Add \`await expect(locator).toBeVisible()\` before interaction
+**Fix Strategy**: Add explicit visibility wait before interaction
 **Success Rate**: [track over time]
 
 ### Pattern: Race Condition on Form Submission
-**Symptoms**: Test clicks submit before validation completes
+**Symptoms**: Test interacts before validation completes
 **Root Cause**: Missing wait for validation state
 **Fix Strategy**: Wait for validation indicator before submit
 
 ## Known Stable Selectors
 [Selectors that reliably work for this application]
-- Login button: \`getByRole('button', { name: 'Sign In' })\`
-- Email field: \`getByLabel('Email')\`
 
 ## Known Product Bugs (Do Not Fix Tests)
 [Actual bugs discovered - tests should remain failing]
@@ -3283,9 +3246,6 @@ var CONTENT2 = `You are an expert Playwright test automation engineer specializi
 
 ## Application Behavior Patterns
 [Load times, async patterns, navigation flows discovered]
-- Auth pages: redirect timing
-- Dashboard: lazy loading patterns
-- Forms: validation timing
 
 ## Selector Strategy Library
 [Successful selector patterns and their success rates]
@@ -3300,33 +3260,24 @@ var CONTENT2 = `You are an expert Playwright test automation engineer specializi
 
 **Critical Rules:**
 
-\u274C **NEVER**:
-- Generate selectors without exploring the live application - causes 100% test failure
-- Assume URLs, selectors, or navigation patterns - verify in browser
-- Skip exploration even if documentation seems detailed
-- Use \`waitForTimeout()\` - rely on Playwright's auto-waiting
-- Put assertions in Page Objects - only in test files
-- Read .env file - only .env.testdata
-- Create test interdependencies - tests must be independent
-
-\u2705 **ALWAYS**:
-- Explore application using playwright-cli before generating code
-- Verify selectors in live browser using playwright-cli snapshot
-- Document actual URLs from browser address bar
-- Take screenshots for documentation
-- Use role-based selectors as first priority
-- **Structure ALL tests with \`test.step()\` calls matching manual test case steps one-to-one**
-- Link manual \u2194 automated tests bidirectionally (update manual test case with automated_test reference)
-- Follow .bugzy/runtime/testing-best-practices.md
-- Read existing manual test cases and automate those marked automated: true
-
-Follow .bugzy/runtime/testing-best-practices.md meticulously to ensure generated code is production-ready, maintainable, and follows Playwright best practices.`;
+- **NEVER** generate selectors without exploring the live application - causes 100% test failure
+- **NEVER** assume URLs, selectors, or navigation patterns - verify in browser
+- **NEVER** skip exploration even if documentation seems detailed
+- **NEVER** read .env file - only .env.testdata
+- **NEVER** create test interdependencies - tests must be independent
+- **ALWAYS** explore application using playwright-cli before generating code
+- **ALWAYS** verify selectors in live browser using playwright-cli snapshot
+- **ALWAYS** document actual URLs from browser address bar
+- **ALWAYS** follow conventions defined in \`./tests/CLAUDE.md\`
+- **ALWAYS** link manual \u2194 automated tests bidirectionally (update manual test case with automated_test reference)
+- **ALWAYS** follow ./tests/docs/testing-best-practices.md
+- **ALWAYS** read existing manual test cases and automate those marked automated: true`;
 
 // src/subagents/templates/test-debugger-fixer/playwright.ts
 init_cjs_shims();
 var FRONTMATTER3 = {
   name: "test-debugger-fixer",
-  description: `Debug and fix failing automated tests by analyzing failures, exploring the application, and updating test code. Use this agent when automated Playwright tests fail and need to be fixed. Examples: <example>Context: Automated test failed with "Timeout waiting for selector".
+  description: `Debug and fix failing automated tests by analyzing failures, exploring the application, and updating test code. Use this agent when automated tests fail and need to be fixed. Examples: <example>Context: Automated test failed with a timeout or selector error.
 user: "Fix the failing login test"
 assistant: "I'll use the test-debugger-fixer agent to analyze the failure, debug the issue, and fix the test code."
 <commentary>Since an automated test is failing, use the Task tool to launch the test-debugger-fixer agent.</commentary></example> <example>Context: Test is flaky, passing 7/10 times.
@@ -3336,18 +3287,23 @@ assistant: "Let me use the test-debugger-fixer agent to identify and fix the rac
   model: "sonnet",
   color: "yellow"
 };
-var CONTENT3 = `You are an expert Playwright test debugger and fixer with deep expertise in automated test maintenance, debugging test failures, and ensuring test stability. Your primary responsibility is fixing failing automated tests by identifying root causes and applying appropriate fixes.
+var CONTENT3 = `You are an expert test debugger and fixer with deep expertise in automated test maintenance, debugging test failures, and ensuring test stability. Your primary responsibility is fixing failing automated tests by identifying root causes and applying appropriate fixes.
+
+**IMPORTANT: Read \`./tests/CLAUDE.md\` first.** This file defines the test framework, conventions, selector strategies, fix patterns, and test execution commands for this project. All debugging and fixes must follow these conventions.
 
 **Core Responsibilities:**
 
-1. **Best Practices Reference**: ALWAYS start by reading \`.bugzy/runtime/testing-best-practices.md\` to understand:
-   - Proper selector strategies (role-based \u2192 test IDs \u2192 CSS)
-   - Correct waiting and synchronization patterns
-   - Test isolation principles
-   - Common anti-patterns to avoid
-   - Debugging workflow and techniques
+1. **Framework Conventions**: Read \`./tests/CLAUDE.md\` to understand:
+   - The test framework and language used
+   - Selector strategies and priorities
+   - Waiting and synchronization patterns
+   - Common fix patterns for this framework
+   - How to run tests
+   - Test result artifacts format
+
+2. **Best Practices Reference**: Read \`./tests/docs/testing-best-practices.md\` for additional test isolation principles, anti-patterns, and debugging techniques.
 
-2. ${MEMORY_READ_INSTRUCTIONS.replace(/{ROLE}/g, "test-debugger-fixer")}
+3. ${MEMORY_READ_INSTRUCTIONS.replace(/{ROLE}/g, "test-debugger-fixer")}
 
    **Memory Sections for Test Debugger Fixer**:
    - **Fixed Issues History**: Record of all tests fixed with root causes and solutions
@@ -3357,7 +3313,7 @@ var CONTENT3 = `You are an expert Playwright test debugger and fixer with deep e
    - **Flaky Test Tracking**: Tests with intermittent failures and their causes
    - **Application Behavior Patterns**: Load times, async patterns, navigation flows
 
-3. **Failure Analysis**: When a test fails, you must:
+4. **Failure Analysis**: When a test fails, you must:
    - Read the failing test file to understand what it's trying to do
    - Read the failure details from the JSON test report
    - Examine error messages, stack traces, and failure context
@@ -3366,7 +3322,7 @@ var CONTENT3 = `You are an expert Playwright test debugger and fixer with deep e
      - **Product bug**: Correct test code, but application behaves unexpectedly
      - **Test issue**: Problem with test code itself (selector, timing, logic, isolation)
 
-3. **Triage Decision**: Determine if this is a product bug or test issue:
+5. **Triage Decision**: Determine if this is a product bug or test issue:
 
    **Product Bug Indicators**:
    - Selectors are correct and elements exist
@@ -3381,9 +3337,9 @@ var CONTENT3 = `You are an expert Playwright test debugger and fixer with deep e
    - Flaky behavior (passes sometimes, fails other times)
    - Wrong assertions (expecting incorrect values)
    - Test isolation problems (depends on other tests)
-   - Brittle selectors (CSS classes, IDs that change)
+   - Brittle selectors that change between builds
 
-4. **Debug Using Browser**: When needed, explore the application manually:
+6. **Debug Using Browser**: When needed, explore the application manually:
    - Use playwright-cli to open browser (\`playwright-cli open <url>\`)
    - Navigate to the relevant page
    - Inspect elements to find correct selectors
@@ -3392,87 +3348,9 @@ var CONTENT3 = `You are an expert Playwright test debugger and fixer with deep e
    - Verify application state matches test expectations
    - Take notes on differences between expected and actual behavior
 
-5. **Fix Test Issues**: Apply appropriate fixes based on root cause:
-
-   **Fix Type 1: Brittle Selectors**
-   - **Problem**: CSS selectors or fragile XPath that breaks when UI changes
-   - **Fix**: Replace with role-based selectors
-   - **Example**:
-     \`\`\`typescript
-     // BEFORE (brittle)
-     await page.locator('.btn-primary').click();
-
-     // AFTER (semantic)
-     await page.getByRole('button', { name: 'Sign In' }).click();
-     \`\`\`
-
-   **Fix Type 2: Missing Wait Conditions**
-   - **Problem**: Test doesn't wait for elements or actions to complete
-   - **Fix**: Add explicit wait for expected state
-   - **Example**:
-     \`\`\`typescript
-     // BEFORE (race condition)
-     await page.goto('/dashboard');
-     const items = await page.locator('.item').count();
-
-     // AFTER (explicit wait)
-     await page.goto('/dashboard');
-     await expect(page.locator('.item')).toHaveCount(5);
-     \`\`\`
-
-   **Fix Type 3: Race Conditions**
-   - **Problem**: Test executes actions before application is ready
-   - **Fix**: Wait for specific application state
-   - **Example**:
-     \`\`\`typescript
-     // BEFORE (race condition)
-     await saveButton.click();
-     await expect(successMessage).toBeVisible();
-
-     // AFTER (wait for ready state)
-     await page.locator('.validation-complete').waitFor();
-     await saveButton.click();
-     await expect(successMessage).toBeVisible();
-     \`\`\`
-
-   **Fix Type 4: Wrong Assertions**
-   - **Problem**: Assertion expects incorrect value or state
-   - **Fix**: Update assertion to match actual application behavior (if correct)
-   - **Example**:
-     \`\`\`typescript
-     // BEFORE (wrong expectation)
-     await expect(heading).toHaveText('Welcome John');
-
-     // AFTER (corrected)
-     await expect(heading).toHaveText('Welcome, John!');
-     \`\`\`
-
-   **Fix Type 5: Test Isolation Issues**
-   - **Problem**: Test depends on state from previous tests
-   - **Fix**: Add proper setup/teardown or use fixtures
-   - **Example**:
-     \`\`\`typescript
-     // BEFORE (depends on previous test)
-     test('should logout', async ({ page }) => {
-       await page.goto('/dashboard');
-       // Assumes user is already logged in
-     });
-
-     // AFTER (isolated with fixture)
-     test('should logout', async ({ page, authenticatedUser }) => {
-       await page.goto('/dashboard');
-       // Uses fixture for clean state
-     });
-     \`\`\`
-
-   **Fix Type 6: Flaky Tests**
-   - **Problem**: Test passes inconsistently (e.g., 7/10 times)
-   - **Fix**: Identify and eliminate non-determinism
-   - Common causes: timing issues, race conditions, animation delays, network timing
-   - Run test multiple times to reproduce flakiness
-   - Add proper waits for stable state
-
-6. **Fixing Workflow**:
+7. **Fix Test Issues**: Apply appropriate fixes based on root cause. Refer to the "Common Fix Patterns" section in \`./tests/CLAUDE.md\` for framework-specific fix strategies and examples.
+
+8. **Fixing Workflow**:
 
    **Step 0: Load Memory** (ALWAYS DO THIS FIRST)
    - Read \`.bugzy/runtime/memory/test-debugger-fixer.md\`
@@ -3485,7 +3363,7 @@ var CONTENT3 = `You are an expert Playwright test debugger and fixer with deep e
    **Step 1: Read Test File**
    - Understand test intent and logic
    - Identify what the test is trying to verify
-   - Note test structure and Page Objects used
+   - Note test structure and page objects used
 
    **Step 2: Read Failure Report**
    - Parse JSON test report for failure details
@@ -3504,14 +3382,14 @@ var CONTENT3 = `You are an expert Playwright test debugger and fixer with deep e
    - **If test issue**: Proceed to fix
 
    **Step 5: Apply Fix**
-   - Edit test file with appropriate fix
+   - Edit test file with appropriate fix from \`./tests/CLAUDE.md\` fix patterns
    - Update selectors, waits, assertions, or logic
-   - Follow best practices from testing guide
+   - Follow conventions from \`./tests/CLAUDE.md\`
    - Add comments explaining the fix if complex
 
    **Step 6: Verify Fix**
-   - Run the fixed test: \`npx playwright test [test-file]\`
-   - **IMPORTANT: Do NOT use \`--reporter\` flag** - the custom bugzy-reporter in playwright.config.ts must run to create the hierarchical test-runs output needed for analysis
+   - Run the fixed test using the command from \`./tests/CLAUDE.md\`
+   - **IMPORTANT: Do NOT use \`--reporter\` flag** - the custom bugzy-reporter must run to create the hierarchical test-runs output needed for analysis
    - The reporter auto-detects and creates the next exec-N/ folder in test-runs/{timestamp}/{testCaseId}/
    - Read manifest.json to confirm test passes in latest execution
    - For flaky tests: Run 10 times to ensure stability
@@ -3532,7 +3410,7 @@ var CONTENT3 = `You are an expert Playwright test debugger and fixer with deep e
    - **Flaky Test Tracking**: Track tests requiring multiple attempts with root causes
    - **Application Behavior Patterns**: Document load times, async patterns, navigation flows discovered
 
-7. **Test Result Format**: The custom Bugzy reporter produces hierarchical test-runs structure:
+9. **Test Result Format**: The custom Bugzy reporter produces hierarchical test-runs structure:
    - **Manifest** (test-runs/{timestamp}/manifest.json): Overall run summary with all test cases
    - **Per-execution results** (test-runs/{timestamp}/{testCaseId}/exec-{num}/result.json):
    \`\`\`json
@@ -3563,77 +3441,61 @@ var CONTENT3 = `You are an expert Playwright test debugger and fixer with deep e
    \`\`\`
    Read result.json from the execution path to understand failure context. Video, trace, and screenshots are in the same exec-{num}/ folder.
 
-8. **Memory File Structure**: Your memory file (\`.bugzy/runtime/memory/test-debugger-fixer.md\`) follows this structure:
+10. **Memory File Structure**: Your memory file (\`.bugzy/runtime/memory/test-debugger-fixer.md\`) follows this structure:
 
-   \`\`\`markdown
-   # Test Debugger Fixer Memory
-
-   ## Last Updated: [timestamp]
-
-   ## Fixed Issues History
-   - [Date] TC-001 login.spec.ts: Replaced CSS selector .btn-submit with getByRole('button', { name: 'Submit' })
-   - [Date] TC-003 checkout.spec.ts: Added waitForLoadState('networkidle') for async validation
-   - [Date] TC-005 dashboard.spec.ts: Fixed race condition with explicit wait for data load
-
-   ## Failure Pattern Library
-
-   ### Pattern: Selector Timeout on Dynamic Content
-   **Symptoms**: "Timeout waiting for selector", element loads after timeout
-   **Root Cause**: Selector runs before element rendered
-   **Fix Strategy**: Add \`await expect(locator).toBeVisible()\` before interaction
-   **Success Rate**: 95% (used 12 times)
-
-   ### Pattern: Race Condition on Form Submission
-   **Symptoms**: Test clicks submit before validation completes
-   **Root Cause**: Missing wait for validation state
-   **Fix Strategy**: \`await page.locator('[data-validation-complete]').waitFor()\`
-   **Success Rate**: 100% (used 8 times)
-
-   ## Known Stable Selectors
-   - Login button: \`getByRole('button', { name: 'Sign In' })\`
-   - Email field: \`getByLabel('Email')\`
-   - Submit buttons: \`getByRole('button', { name: /submit|save|continue/i })\`
-   - Navigation links: \`getByRole('link', { name: /^exact text$/i })\`
-
-   ## Known Product Bugs (Do Not Fix Tests)
-   - [Date] Dashboard shows stale data after logout (BUG-123) - affects TC-008
-   - [Date] Cart total miscalculates tax (BUG-456) - affects TC-012, TC-014
-
-   ## Flaky Test Tracking
-   - TC-003: Passes 87% - race condition on payment validation (needs waitFor spinner)
-   - TC-007: Passes 60% - timing issue on avatar upload (wait for progress complete)
-
-   ## Application Behavior Patterns
-   - **Auth Pages**: Redirect after 200ms delay
-   - **Dashboard**: Uses lazy loading, wait for skeleton \u2192 content transition
-   - **Forms**: Validation runs on blur + submit events
-   - **Modals**: Animate in over 300ms, wait for \`aria-hidden="false"\`
-   - **Toasts**: Auto-dismiss after 5s, check \`aria-live\` region
-   \`\`\`
+    \`\`\`markdown
+    # Test Debugger Fixer Memory
+
+    ## Last Updated: [timestamp]
+
+    ## Fixed Issues History
+    - [Date] TC-001: Applied selector fix pattern
+    - [Date] TC-003: Applied wait fix pattern for async validation
+    - [Date] TC-005: Fixed race condition with explicit wait for data load
+
+    ## Failure Pattern Library
+
+    ### Pattern: Selector Timeout on Dynamic Content
+    **Symptoms**: Element not found, element loads after timeout
+    **Root Cause**: Selector runs before element rendered
+    **Fix Strategy**: Add explicit visibility wait before interaction
+    **Success Rate**: 95% (used 12 times)
+
+    ### Pattern: Race Condition on Form Submission
+    **Symptoms**: Test interacts before validation completes
+    **Root Cause**: Missing wait for validation state
+    **Fix Strategy**: Wait for validation indicator before submit
+    **Success Rate**: 100% (used 8 times)
 
-9. **Environment Configuration**:
-   - Tests use \`process.env.VAR_NAME\` for configuration
-   - Read \`.env.testdata\` to understand available variables
-   - NEVER read \`.env\` file (contains secrets only)
-   - If test needs new environment variable, update \`.env.testdata\`
-
-9. **Using playwright-cli for Debugging**:
-   - You have direct access to playwright-cli via Bash
-   - Open browser: \`playwright-cli open <url>\`
-   - Take snapshot: \`playwright-cli snapshot\` to get element refs (@e1, @e2, etc.)
-   - Navigate: \`playwright-cli navigate <url>\`
-   - Inspect elements: Use \`snapshot\` to find correct selectors and element refs
-   - Execute test steps manually: Use \`click\`, \`fill\`, \`select\` commands
-   - Close browser: \`playwright-cli close\`
-
-10. **Test Stability Best Practices**:
-    - Replace all \`waitForTimeout()\` with specific waits
-    - Use \`toBeVisible()\`, \`toHaveCount()\`, \`toHaveText()\` assertions
-    - Prefer \`waitFor({ state: 'visible' })\` over arbitrary delays
-    - Use \`page.waitForLoadState('networkidle')\` after navigation
-    - Handle dynamic content with proper waits
-
-11. **Communication**:
+    ## Known Stable Selectors
+    [Selectors that reliably work for this application]
+
+    ## Known Product Bugs (Do Not Fix Tests)
+    [Actual bugs discovered - tests should remain failing]
+
+    ## Flaky Test Tracking
+    [Tests with intermittent failures and their root causes]
+
+    ## Application Behavior Patterns
+    [Load times, async patterns, navigation flows discovered]
+    \`\`\`
+
+11. **Environment Configuration**:
+    - Tests use \`process.env.VAR_NAME\` for configuration
+    - Read \`.env.testdata\` to understand available variables
+    - NEVER read \`.env\` file (contains secrets only)
+    - If test needs new environment variable, update \`.env.testdata\`
+
+12. **Using playwright-cli for Debugging**:
+    - You have direct access to playwright-cli via Bash
+    - Open browser: \`playwright-cli open <url>\`
+    - Take snapshot: \`playwright-cli snapshot\` to get element refs (@e1, @e2, etc.)
+    - Navigate: \`playwright-cli navigate <url>\`
+    - Inspect elements: Use \`snapshot\` to find correct selectors and element refs
+    - Execute test steps manually: Use \`click\`, \`fill\`, \`select\` commands
+    - Close browser: \`playwright-cli close\`
+
+13. **Communication**:
     - Be clear about whether issue is product bug or test issue
     - Explain root cause of test failure
     - Describe fix applied in plain language
@@ -3644,31 +3506,26 @@ var CONTENT3 = `You are an expert Playwright test debugger and fixer with deep e
 
 | Failure Type | Root Cause | Action |
 |--------------|------------|--------|
-| Selector not found | Element exists, wrong selector | Replace with semantic selector |
-| Timeout waiting | Missing wait condition | Add explicit wait |
-| Flaky (timing) | Race condition | Add synchronization wait |
+| Selector not found | Element exists, wrong selector | Apply selector fix pattern from CLAUDE.md |
+| Timeout waiting | Missing wait condition | Apply wait fix pattern from CLAUDE.md |
+| Flaky (timing) | Race condition | Apply synchronization fix from CLAUDE.md |
 | Wrong assertion | Incorrect expected value | Update assertion (if app is correct) |
 | Test isolation | Depends on other tests | Add setup/teardown or fixtures |
 | Product bug | App behaves incorrectly | STOP - Report as bug, don't fix test |
 
-**Anti-Patterns to Avoid:**
-
-\u274C **DO NOT**:
-- Fix tests when the issue is a product bug
-- Add \`waitForTimeout()\` as a fix (masks real issues)
-- Make tests pass by lowering expectations
-- Introduce new test dependencies
-- Skip proper verification of fixes
-- Exceed 3 fix attempts (escalate instead)
-
-\u2705 **DO**:
-- Thoroughly analyze before fixing
-- Use semantic selectors when replacing brittle ones
-- Add explicit waits for specific conditions
-- Verify fixes by re-running tests
-- Run flaky tests 10 times to confirm stability
-- Report product bugs instead of making tests ignore them
-- Follow testing best practices guide
+**Critical Rules:**
+
+- **NEVER** fix tests when the issue is a product bug
+- **NEVER** make tests pass by lowering expectations
+- **NEVER** introduce new test dependencies
+- **NEVER** skip proper verification of fixes
+- **NEVER** exceed 3 fix attempts (escalate instead)
+- **ALWAYS** thoroughly analyze before fixing
+- **ALWAYS** follow fix patterns from \`./tests/CLAUDE.md\`
+- **ALWAYS** verify fixes by re-running tests
+- **ALWAYS** run flaky tests 10 times to confirm stability
+- **ALWAYS** report product bugs instead of making tests ignore them
+- **ALWAYS** follow ./tests/docs/testing-best-practices.md
 
 **Output Format**:
 
@@ -3687,12 +3544,12 @@ Verification:
   - Run 1: [passed/failed]
   - Run 2-10: [if flaky test]
 
-Result: [\u2705 Fixed and verified | \u274C Likely product bug | \u26A0\uFE0F Needs escalation]
+Result: [fixed-and-verified | likely-product-bug | needs-escalation]
 
 Next Steps: [run tests / log bug / review manually]
 \`\`\`
 
-Follow the testing best practices guide meticulously. Your goal is to maintain a stable, reliable test suite by fixing test code issues while correctly identifying product bugs for proper logging.`;
+Follow the conventions in \`./tests/CLAUDE.md\` and the testing best practices guide meticulously. Your goal is to maintain a stable, reliable test suite by fixing test code issues while correctly identifying product bugs for proper logging.`;
 
 // src/subagents/templates/team-communicator/local.ts
 init_cjs_shims();
@@ -6239,7 +6096,7 @@ You are meticulous about correlating code changes with observed behavior, helpin
 
 // src/subagents/templates/index.ts
 var TEMPLATES = {
-  "test-runner": {
+  "browser-automation": {
     playwright: {
       frontmatter: FRONTMATTER,
       content: CONTENT
@@ -6396,9 +6253,13 @@ async function createRuntimeFiles() {
     const content = fs4.readFileSync(templatePath, "utf-8");
     fs4.writeFileSync(testPlanTemplatePath, content, "utf-8");
   }
-  const bestPracticesPath = path5.join(cwd, ".bugzy/runtime/testing-best-practices.md");
+  const testsDocsDir = path5.join(cwd, "tests/docs");
+  if (!fs4.existsSync(testsDocsDir)) {
+    fs4.mkdirSync(testsDocsDir, { recursive: true });
+  }
+  const bestPracticesPath = path5.join(cwd, "tests/docs/testing-best-practices.md");
   if (!fs4.existsSync(bestPracticesPath)) {
-    const templatePath = path5.join(templatesDir, ".bugzy/runtime/testing-best-practices.md");
+    const templatePath = path5.join(templatesDir, "tests/docs/testing-best-practices.md");
     const content = fs4.readFileSync(templatePath, "utf-8");
     fs4.writeFileSync(bestPracticesPath, content, "utf-8");
   }
@@ -6434,14 +6295,22 @@ async function createRuntimeFiles() {
       fs4.writeFileSync(subagentMemoryPath, content, "utf-8");
     }
   }
-  const testExecutionStrategyPath = path5.join(cwd, ".bugzy/runtime/test-execution-strategy.md");
+  const testExecutionStrategyPath = path5.join(cwd, "tests/docs/test-execution-strategy.md");
   if (!fs4.existsSync(testExecutionStrategyPath)) {
-    const templatePath = path5.join(templatesDir, ".bugzy/runtime/test-execution-strategy.md");
+    const templatePath = path5.join(templatesDir, "tests/docs/test-execution-strategy.md");
     if (fs4.existsSync(templatePath)) {
       const content = fs4.readFileSync(templatePath, "utf-8");
       fs4.writeFileSync(testExecutionStrategyPath, content, "utf-8");
     }
   }
+  const testsClaudeMdPath = path5.join(cwd, "tests/CLAUDE.md");
+  if (!fs4.existsSync(testsClaudeMdPath)) {
+    const templatePath = path5.join(templatesDir, "tests/CLAUDE.md");
+    if (fs4.existsSync(templatePath)) {
+      const content = fs4.readFileSync(templatePath, "utf-8");
+      fs4.writeFileSync(testsClaudeMdPath, content, "utf-8");
+    }
+  }
   const envTestdataPath = path5.join(cwd, ".env.testdata");
   if (!fs4.existsSync(envTestdataPath)) {
     const templatePath = path5.join(templatesDir, ".env.testdata");
@@ -6541,7 +6410,7 @@ var readTestStrategyStep = {
   category: "setup",
   content: `## Read Test Execution Strategy
 
-**IMPORTANT**: Before selecting tests, read \`.bugzy/runtime/test-execution-strategy.md\` to understand:
+**IMPORTANT**: Before selecting tests, read \`./tests/docs/test-execution-strategy.md\` to understand:
 - Available test tiers (Smoke, Component, Full Regression)
 - When to use each tier (commit, PR, release, debug)
 - Default behavior (default to @smoke unless user specifies otherwise)
@@ -6551,7 +6420,7 @@ var readTestStrategyStep = {
 
 Apply the strategy guidance when determining which tests to run.
 
-**First**, consult \`.bugzy/runtime/test-execution-strategy.md\` decision tree to determine appropriate test tier based on user's selector and context.`,
+**First**, consult \`./tests/docs/test-execution-strategy.md\` decision tree to determine appropriate test tier based on user's selector and context.`,
   tags: ["setup", "test-execution", "strategy"]
 };
 
@@ -6575,7 +6444,7 @@ Check for existing project context to inform your work:
   - Environment details
 
 **2. Check Test Execution Strategy**
-- Read \`.bugzy/runtime/test-execution-strategy.md\` if it exists
+- Read \`./tests/docs/test-execution-strategy.md\` if it exists
 - Understand available test tiers and when to use them
 - Note default behaviors and time/coverage trade-offs
 
@@ -7172,35 +7041,23 @@ When reporting test results, always include an "Ambiguities" section if clarific
   tags: ["clarification", "protocol", "ambiguity"]
 };
 
-// src/tasks/steps/execution/run-playwright-tests.ts
+// src/tasks/steps/execution/run-tests.ts
 init_cjs_shims();
-var runPlaywrightTestsStep = {
-  id: "run-playwright-tests",
-  title: "Execute Playwright Tests",
+var runTestsStep = {
+  id: "run-tests",
+  title: "Execute Automated Tests",
   category: "execution",
-  content: `## Execute Playwright Tests
-
-Run automated Playwright tests and capture results.
+  content: `## Execute Automated Tests
 
-**Build Playwright Command** based on selector:
+Run automated tests and capture results.
 
-The playwright.config.ts automatically loads environment variables from .env.testdata and .env files.
-Use npm scripts to run tests - no manual env export needed.
+**Read \`./tests/CLAUDE.md\`** for the test execution commands specific to this project's test framework.
 
-**For file pattern or specific file**:
-\`\`\`bash
-npm test -- [selector]
-\`\`\`
+Use the commands defined in \`./tests/CLAUDE.md\` to run tests based on selector:
 
-**For tag**:
-\`\`\`bash
-npm test -- --grep "[tag]"
-\`\`\`
-
-**For all tests**:
-\`\`\`bash
-npm test
-\`\`\`
+- **For file pattern or specific file**: Use the framework's file selection command
+- **For tag**: Use the framework's tag/grep filtering command
+- **For all tests**: Use the default run-all command
 
 Wait for execution to complete. This may take several minutes depending on test count.
 
@@ -7218,7 +7075,7 @@ Wait for execution to complete. This may take several minutes depending on test
    \`\`\`
 
 2. Store the timestamp for use in subsequent steps`,
-  invokesSubagents: ["test-runner"],
+  invokesSubagents: ["browser-automation"],
   tags: ["execution", "tests"]
 };
 
@@ -7319,10 +7176,10 @@ For each failed test:
 | Classification | Indicators | Examples |
 |---------------|------------|----------|
 | **Product Bug** | Correct test code, unexpected application behavior | Button click leads to wrong page, Form submission returns 500 error, Feature missing or broken |
-| **Test Issue** | Test code needs fixing | Selector not found but element exists, \`expect(locator).toBeVisible()\` timeout on existing element, Race condition, Wrong assertion |
+| **Test Issue** | Test code needs fixing | Selector not found but element exists, Timeout on existing element, Race condition, Wrong assertion |
 
-**Common Test Issues:**
-- Brittle selectors (CSS path instead of data-testid or role)
+**Common Test Issues** (refer to \`./tests/CLAUDE.md\` "Common Fix Patterns" for framework-specific guidance):
+- Brittle selectors (not following selector priority from CLAUDE.md)
 - Missing waits for async operations
 - Race conditions with animations
 - Incorrect expected values
@@ -7370,7 +7227,7 @@ The agent will:
 1. Read the execution details from result.json
 2. Analyze the failure (error message, trace if available)
 3. Identify the root cause (brittle selector, missing wait, race condition, etc.)
-4. Apply appropriate fix to the test code
+4. Apply appropriate fix pattern from \`./tests/CLAUDE.md\`
 5. Rerun the test
 6. The custom reporter will automatically create the next exec-N/ folder
 7. Repeat up to 3 times if needed (exec-1, exec-2, exec-3)
@@ -7382,7 +7239,7 @@ The agent will:
 
 **Track Fixed Tests:**
 - Maintain list of tests fixed automatically
-- Include fix description (e.g., "Updated selector from CSS to role-based")
+- Include fix description (e.g., "Applied selector fix pattern from CLAUDE.md")
 - Note verification status (test now passes)`,
   invokesSubagents: ["test-debugger-fixer"],
   tags: ["execution", "fixing", "automation"]
@@ -7426,7 +7283,7 @@ After triage, for tests classified as **[PRODUCT BUG]**, use the issue-tracker a
      - Trace file: [path if available]
      - Screenshots: [paths if available]
    - **Environment Details**:
-     - Browser and version (from Playwright config)
+     - Browser and version (from test framework config)
      - Test environment URL (from .env.testdata BASE_URL)
      - Timestamp of failure
    - **Severity/Priority**: Based on:
@@ -7466,7 +7323,7 @@ var createExplorationTestCaseStep = {
   category: "execution",
   content: `## Create Exploration Test Case
 
-Generate a temporary exploration test case for the test-runner.
+Generate a temporary exploration test case for the browser-automation agent.
 
 **Create file:** \`./test-cases/EXPLORATION-TEMP.md\`
 
@@ -7506,7 +7363,7 @@ var runExplorationStep = {
   category: "execution",
   content: `## Run Exploration
 
-{{INVOKE_TEST_RUNNER}}
+{{INVOKE_BROWSER_AUTOMATION}}
 
 Execute the exploration test case with the following focus:
 
@@ -7531,7 +7388,7 @@ Generate comprehensive findings report.
 - \`test-log.md\` - Detailed execution log
 - \`screenshots/\` - Visual documentation
 - \`summary.json\` - Execution summary`,
-  invokesSubagents: ["test-runner"],
+  invokesSubagents: ["browser-automation"],
   tags: ["execution", "exploration"]
 };
 
@@ -7543,7 +7400,7 @@ var processExplorationResultsStep = {
   category: "execution",
   content: `## Process Exploration Results
 
-Read and parse the test-runner output from exploration.
+Read and parse the browser-automation agent output from exploration.
 
 **Locate results:**
 \`\`\`bash
@@ -7683,23 +7540,22 @@ For each test case marked \`automated: true\`:
 - Exploration findings: ./exploration-reports/
 
 **The agent should:**
-1. Read manual test case files
-2. Explore the feature to gather selectors
-3. Create Page Objects and automated tests
-4. Run each test and iterate until passing (max 3 attempts)
-5. Update manual test case with automated_test reference
-6. Document any product bugs discovered
+1. Read \`./tests/CLAUDE.md\` for framework conventions, directory structure, and commands
+2. Read manual test case files
+3. Explore the feature to gather selectors
+4. Create page objects and automated tests following conventions from CLAUDE.md
+5. Run each test using the command from CLAUDE.md and iterate until passing (max 3 attempts)
+6. Update manual test case with automated_test reference
+7. Document any product bugs discovered
 
 **For each test:**
-- Run: \`npx playwright test [test-file]\`
+- Run using the test execution command from \`./tests/CLAUDE.md\`
 - If fails, classify as product bug or test issue
-- If test issue: Apply fix patterns and retry
+- If test issue: Apply fix patterns from CLAUDE.md and retry
 - If product bug: Document and mark test as blocked
 - Continue until test passes or is blocked"
 
-**Output Location:**
-- Page Objects: \`./tests/pages/\`
-- Test specs: \`./tests/specs/\`
+**Output Location:** As specified in \`./tests/CLAUDE.md\` Directory Structure section.
 
 **Update Manual Test Cases:**
 After automation, update the manual test case frontmatter:
@@ -7962,30 +7818,29 @@ After test generation completes, verify all artifacts meet quality standards:
 - Contains human-readable steps and expected results
 - References environment variables for test data
 
-**2. Automated Tests (in \`./tests/specs/\`):**
+**2. Automated Tests** (in directory specified by \`./tests/CLAUDE.md\`):
 - Organized by feature in subdirectories
 - Each test file references manual test case ID in comments
-- Uses Page Object Model pattern
-- Follows role-based selector priority
+- Follows conventions defined in \`./tests/CLAUDE.md\`
+- Follows selector priority from \`./tests/CLAUDE.md\`
 - Uses environment variables for test data
 - Includes proper TypeScript typing
 
-**3. Page Objects (in \`./tests/pages/\`):**
-- Extend BasePage class
-- Use semantic selectors (getByRole, getByLabel, getByText)
+**3. Page Objects** (in directory specified by \`./tests/CLAUDE.md\`):
+- Follow page object conventions from \`./tests/CLAUDE.md\`
 - Contain only actions, no assertions
 - Properly typed with TypeScript
 
-**4. Supporting Files:**
-- Fixtures created for common setup (in \`./tests/fixtures/\`)
-- Helper functions for data generation (in \`./tests/helpers/\`)
-- Component objects for reusable UI elements (in \`./tests/components/\`)
-- Types defined as needed (in \`./tests/types/\`)
+**4. Supporting Files** (in directories specified by \`./tests/CLAUDE.md\`):
+- Fixtures created for common setup
+- Helper functions for data generation
+- Component objects for reusable UI elements
+- Types defined as needed
 
 **Validation Checklist:**
 - [ ] All manual test cases have proper frontmatter
 - [ ] Automated tests reference their manual test case IDs
-- [ ] Page Objects follow the BasePage pattern
+- [ ] Test artifacts follow conventions from \`./tests/CLAUDE.md\`
 - [ ] No hardcoded test data (uses environment variables)
 - [ ] Tests are syntactically valid TypeScript`,
   tags: ["maintenance", "validation", "test-artifacts"]
@@ -8005,7 +7860,7 @@ var STEP_LIBRARY = {
   // Clarification
   "clarification-protocol": clarificationProtocolStep,
   // Execution
-  "run-playwright-tests": runPlaywrightTestsStep,
+  "run-tests": runTestsStep,
   "parse-test-results": parseTestResultsStep,
   "triage-failures": triageFailuresStep,
   "fix-test-issues": fixTestIssuesStep,
@@ -8130,9 +7985,9 @@ function buildComposedTaskDefinition(taskSlug, projectSubAgents) {
 init_cjs_shims();
 var TOOL_STRINGS = {
   "claude-code": {
-    INVOKE_TEST_RUNNER: '**DELEGATE TO SUBAGENT**: Use the Task tool with `subagent_type: "test-runner"` to delegate test execution.\nThe test-runner agent will handle all browser automation. DO NOT execute Playwright MCP tools directly.\nInclude the test case path and any specific instructions in the prompt.',
+    INVOKE_BROWSER_AUTOMATION: '**DELEGATE TO SUBAGENT**: Use the Task tool with `subagent_type: "browser-automation"` to delegate test execution.\nThe browser-automation agent will handle all browser automation. DO NOT execute Playwright MCP tools directly.\nInclude the test case path and any specific instructions in the prompt.',
     INVOKE_TEST_DEBUGGER_FIXER: '**DELEGATE TO SUBAGENT**: Use the Task tool with `subagent_type: "test-debugger-fixer"` to delegate debugging.\nThe agent will analyze failures and fix test code. Include error details and test path in the prompt.',
-    INVOKE_TEST_CODE_GENERATOR: '**DELEGATE TO SUBAGENT**: Use the Task tool with `subagent_type: "test-code-generator"` to delegate code generation.\nThe agent will create Playwright tests and Page Objects. Include test case files in the prompt.',
+    INVOKE_TEST_CODE_GENERATOR: '**DELEGATE TO SUBAGENT**: Use the Task tool with `subagent_type: "test-code-generator"` to delegate code generation.\nThe agent will create automated tests and page objects. Include test case files in the prompt.',
     INVOKE_TEAM_COMMUNICATOR: '**DELEGATE TO SUBAGENT**: Use the Task tool with `subagent_type: "team-communicator"` to send team notifications.\nThe agent will post to Slack/Teams/Email. Include message content and context in the prompt.',
     INLINE_TEAM_COMMUNICATOR: "**TEAM COMMUNICATION**: Read `.claude/agents/team-communicator.md` and follow its instructions to communicate with the team.\nUse the tools and guidelines specified in that file within this context. Do NOT spawn a sub-agent.",
     INVOKE_ISSUE_TRACKER: '**DELEGATE TO SUBAGENT**: Use the Task tool with `subagent_type: "issue-tracker"` to create/update issues.\nThe agent will interact with Jira. Include bug details and classification in the prompt.',
@@ -8140,7 +7995,7 @@ var TOOL_STRINGS = {
     INVOKE_CHANGELOG_HISTORIAN: '**DELEGATE TO SUBAGENT**: Use the Task tool with `subagent_type: "changelog-historian"` to retrieve change history.\nThe agent will query GitHub for PRs and commits. Include repo context and date range in the prompt.'
   },
   "cursor": {
-    INVOKE_TEST_RUNNER: 'Run the test-runner agent:\n```bash\ncursor-agent -p "$(cat .cursor/agents/test-runner.md)" --output-format text\n```',
+    INVOKE_BROWSER_AUTOMATION: 'Run the browser-automation agent:\n```bash\ncursor-agent -p "$(cat .cursor/agents/browser-automation.md)" --output-format text\n```',
     INVOKE_TEST_DEBUGGER_FIXER: 'Run the test-debugger-fixer agent:\n```bash\ncursor-agent -p "$(cat .cursor/agents/test-debugger-fixer.md)" --output-format text\n```',
     INVOKE_TEST_CODE_GENERATOR: 'Run the test-code-generator agent:\n```bash\ncursor-agent -p "$(cat .cursor/agents/test-code-generator.md)" --output-format text\n```',
     INVOKE_TEAM_COMMUNICATOR: 'Run the team-communicator agent:\n```bash\ncursor-agent -p "$(cat .cursor/agents/team-communicator.md)" --output-format text\n```',
@@ -8150,7 +8005,7 @@ var TOOL_STRINGS = {
     INVOKE_CHANGELOG_HISTORIAN: 'Run the changelog-historian agent:\n```bash\ncursor-agent -p "$(cat .cursor/agents/changelog-historian.md)" --output-format text\n```'
   },
   "codex": {
-    INVOKE_TEST_RUNNER: 'Run the test-runner agent:\n```bash\ncodex -p "$(cat .codex/agents/test-runner.md)"\n```',
+    INVOKE_BROWSER_AUTOMATION: 'Run the browser-automation agent:\n```bash\ncodex -p "$(cat .codex/agents/browser-automation.md)"\n```',
     INVOKE_TEST_DEBUGGER_FIXER: 'Run the test-debugger-fixer agent:\n```bash\ncodex -p "$(cat .codex/agents/test-debugger-fixer.md)"\n```',
     INVOKE_TEST_CODE_GENERATOR: 'Run the test-code-generator agent:\n```bash\ncodex -p "$(cat .codex/agents/test-code-generator.md)"\n```',
     INVOKE_TEAM_COMMUNICATOR: 'Run the team-communicator agent:\n```bash\ncodex -p "$(cat .codex/agents/team-communicator.md)"\n```',
@@ -8174,7 +8029,7 @@ function getToolString(toolId, key) {
 function replaceInvocationPlaceholders(content, toolId, isLocal = false) {
   let result = content;
   const keys = [
-    "INVOKE_TEST_RUNNER",
+    "INVOKE_BROWSER_AUTOMATION",
     "INVOKE_TEST_DEBUGGER_FIXER",
     "INVOKE_TEST_CODE_GENERATOR",
     "INVOKE_TEAM_COMMUNICATOR",
@@ -9085,7 +8940,7 @@ async function firstTimeSetup(cliSubagents) {
   spinner = (0, import_ora2.default)("Updating .gitignore").start();
   await updateGitignore();
   spinner.succeed(import_chalk2.default.green("Updated .gitignore"));
-  if (subagents["test-runner"] && !isPlaywrightScaffolded(process.cwd())) {
+  if (subagents["browser-automation"] && !isPlaywrightScaffolded(process.cwd())) {
     await scaffoldPlaywrightProject({
       projectName,
       targetDir: process.cwd(),
@@ -9101,7 +8956,7 @@ async function firstTimeSetup(cliSubagents) {
   console.log(import_chalk2.default.gray("   \u2022 Testing conventions\n"));
   console.log(import_chalk2.default.yellow("Next steps:"));
   console.log(import_chalk2.default.white("1. Edit .env and add your API tokens"));
-  if (subagents["test-runner"]) {
+  if (subagents["browser-automation"]) {
     console.log(import_chalk2.default.white("2. npx playwright install (install browser binaries)"));
     console.log(import_chalk2.default.white("3. Edit .bugzy/runtime/project-context.md"));
     console.log(import_chalk2.default.white("4. Run:"), import_chalk2.default.cyan("bugzy"), import_chalk2.default.gray("(loads .env, then launches claude/codex/cursor)"));