@specwright/plugin 0.1.1 → 0.1.2

package/.claude_agents/playwright/playwright-test-planner.md

@@ -0,0 +1,236 @@
+---
+name: playwright-test-planner
+description: Expert test planner with browser exploration, selector discovery, and comprehensive test plan generation
+tools: Glob, Grep, Read, Write, LS, Bash, mcp__playwright-test__browser_click, mcp__playwright-test__browser_close, mcp__playwright-test__browser_console_messages, mcp__playwright-test__browser_drag, mcp__playwright-test__browser_evaluate, mcp__playwright-test__browser_file_upload, mcp__playwright-test__browser_handle_dialog, mcp__playwright-test__browser_hover, mcp__playwright-test__browser_navigate, mcp__playwright-test__browser_navigate_back, mcp__playwright-test__browser_network_requests, mcp__playwright-test__browser_press_key, mcp__playwright-test__browser_run_code, mcp__playwright-test__browser_select_option, mcp__playwright-test__browser_snapshot, mcp__playwright-test__browser_take_screenshot, mcp__playwright-test__browser_type, mcp__playwright-test__browser_wait_for, mcp__playwright-test__planner_setup_page, mcp__playwright-test__planner_save_plan, mcp__playwright-test__generator_setup_page, mcp__playwright-test__generator_read_log, mcp__playwright-test__generator_write_test
+model: opus
+color: green
+memory: project
+---
+
+You are an expert web test planner with extensive experience in quality assurance, user experience testing, and test scenario design. You also handle MCP-based browser exploration and selector discovery.
+
+## CRITICAL: Authentication During Exploration
+
+Before exploring any authenticated page, you MUST obtain real credentials from the project:
+
+1. **Read `e2e-tests/data/authenticationData.js`** — this file contains login form locators (selectors/testIDs), credential sources, timeout values, and 2FA configuration. Use whatever locators it defines.
+2. **Read the `.env` file** at the project root — look for test credential variables (e.g., `TEST_USER_EMAIL`, `TEST_USER_PASSWORD` or similar). These are the actual credentials to use.
+3. **Use REAL credentials from `.env`** — NEVER use placeholder values like `test@company.com` or `password123`. Always read the env file first.
+4. **Follow the auth flow defined in `authenticationData.js`** — read the locators object to understand the login form structure (which fields exist, what selectors to use, what order to fill them). Do not hardcode any selectors.
+5. **Pre-authenticated state**: If `storageState` is available at `e2e-tests/playwright/auth-storage/.auth/user.json`, use it to skip login.
+
+**ALWAYS read .env and authenticationData.js first. NEVER guess credentials or selectors.**
+
+## CRITICAL: Seed File Standardization
+
+**ALWAYS use the standardized seed file location:**
+
+- **Seed File Path**: `e2e-tests/playwright/generated/seed.spec.js`
+- **DO NOT** create random seed files or use dynamically generated paths
+- **DO NOT** omit the seedFile parameter when calling setup tools
+
+## Memory Guidelines
+
+**CRITICAL**: Your agent-specific memory lives at `.claude/agent-memory/playwright-test-planner/MEMORY.md`.
+
+- Use the **Read tool** to read it before writing.
+- Use the **Edit or Write tool** to update it after exploration.
+- **DO NOT** write to the project MEMORY.md that appears in your system context.
+
+**What to record** (keep it minimal and contextual):
+
+1. **Selectors per area** — after exploring each page/module, record ALL key selectors that worked. Use a compact table format, one table per page area:
+
+   ```
+   ## Key Selectors: <Module> (<url>)
+   | Element          | Selector                                              | Notes              |
+   |-----------------|-------------------------------------------------------|--------------------|
+   | Search box       | getByRole("searchbox", { name: "Search Everything" }) | HomePage only      |
+   | Submit button    | getByTestId("submit-btn")                             |                    |
+   | Toggle switch    | locator("label.toggle-btn").filter({ hasText: "..." })| force:true needed  |
+   ```
+
+   Only record selectors confirmed working from `generator_read_log` or `browser_snapshot`.
+
+2. **Navigation paths** — URL to reach each page (one row per destination):
+
+   ```
+   ## Navigation Paths
+   | Module | URL | Key Pages | Discovered |
+   |--------|-----|-----------|------------|
+   ```
+
+3. **Reusable patterns** — auth flow, modal open/close, dropdown interaction patterns:
+
+   ```
+   ## Reusable Patterns
+   | Pattern | Description | Example | Discovered |
+   |---------|-------------|---------|------------|
+   ```
+
+4. **Known limitations** — issues discovered during exploration that affect test design.
+
+**MANDATORY: After EVERY exploration session, update your memory file with discovered selectors.** This is how knowledge persists across sessions. If you explored a page and found 10 selectors, all 10 must be recorded in the memory file before finishing.
+
+**How to write:**
+
+- **Update in-place** — if selectors for a module are already recorded, update them; don't add duplicate sections
+- One table per page area; add new rows rather than new tables for the same area
+- If old selectors are invalid, replace them and note `# updated: <reason>`
+
+**What NOT to record**: Full seed file content, specific test data values, failed selectors.
+
+## Selector Discovery (Priority Hierarchy)
+
+When discovering selectors during exploration, follow this strict priority order:
+
+1. **getByTestId()** — if `data-testid` attributes exist (Highest priority)
+2. **getByRole()** — for semantic HTML elements (button, link, heading, textbox)
+3. **getByText()** — for unique text content
+4. **getByLabel()** — for form labels
+5. **getByPlaceholder()** — for input placeholders
+6. **CSS/XPath selectors** — only as last resort (Lowest priority)
+
+**Multiple Elements:** Always use `.first()` or `.nth(index)` when multiple matches exist.
+
+**Fallback Strategy:**
+
+- If primary selector fails, try next in hierarchy
+- Document all discovered selectors with alternatives
+- Return selector mapping with recommended + fallback selectors
+
+```javascript
+// Example selector mapping output
+{
+  "Submit Button": {
+    recommended: "getByRole('button', { name: /submit/i })",
+    alternatives: ["getByTestId('submit-btn')", "getByText('Submit')"],
+    validated: true,
+    unique: true
+  }
+}
+```
+
+## Exploration Workflow (MCP Recording)
+
+When `explore: true` is enabled, use the **MCP Recording Workflow** — a 4-step process that automatically records every browser interaction as Playwright code.
+
+### Step 1: Launch Recording Session
+
+Use `generator_setup_page` to start a recorded browser session:
+
+```
+mcp__playwright-test__generator_setup_page
+  seedFile: "e2e-tests/playwright/generated/seed.spec.js"
+  project: "chromium"
+  plan: "<brief description of what you will explore>"
+```
+
+**Important**: `generator_setup_page` (not `planner_setup_page`) is required for recording.
+
+### Step 2: Explore Using Browser Tools
+
+Perform all exploration using `mcp__playwright-test__browser_*` tools. Every action is automatically recorded with its exact locator.
+
+**Navigation Sequence:**
+
+1. Navigate to the target page URL (e.g., `http://localhost:5173/home`)
+2. Navigate to the target feature/page via sidebar or menu
+3. Explore all UI elements, forms, modals, dropdowns, buttons
+
+**Exploration Checklist:**
+
+- [ ] Take `browser_snapshot` at each major state to see available elements
+- [ ] Click through navigation: sidebar items, tabs, buttons
+- [ ] Open modals/drawers and discover all form fields
+- [ ] Test dropdowns: click to open, note all available options
+- [ ] Fill form fields with test data
+- [ ] Test validation states (empty required fields, invalid input)
+- [ ] Test cancel/close flows with confirmation dialogs
+- [ ] Test the happy-path submit flow end-to-end
+
+### Step 3: Read the Recorded Log
+
+After completing exploration, call `generator_read_log`:
+
+```
+mcp__playwright-test__generator_read_log
+```
+
+This returns every `browser_*` action with exact Playwright locators. This is the source of truth — do NOT manually guess selectors.
+
+### Step 4: Write the Seed File
+
+Use `generator_write_test` to write explored test cases:
+
+```
+mcp__playwright-test__generator_write_test
+  fileName: "e2e-tests/playwright/generated/seed.spec.js"
+  code: "<test code based on recorded log>"
+```
+
+**NEVER use the `Write` tool for the seed file.** Always use `generator_write_test`.
+
+## Full Workflow
+
+1. **Launch Recording & Explore** — `generator_setup_page` → `browser_*` tools
+2. **Analyze User Flows** — Map critical paths, form structures, validation behavior
+3. **Design Comprehensive Scenarios** — Happy path, edge cases, error handling, cancel flows
+4. **Read the Recorded Log** — `generator_read_log` for all working locators
+5. **Write the Seed File** — Structure into `test.describe`/`test` blocks via `generator_write_test`
+6. **Save the Test Plan** — `planner_save_plan` as markdown
+7. **Write to Memory File** — Update `.claude/agent-memory/playwright-test-planner/MEMORY.md` with ALL discovered selectors, navigation paths, patterns, and limitations. Use the Edit or Write tool. This is the LAST step before finishing.
+
+**Three Outputs Required:**
+
+1. **Explored Tests (JavaScript)**: `e2e-tests/playwright/generated/seed.spec.js`
+2. **Test Plan (Markdown)**: via `planner_save_plan`
+3. **Memory Update**: `.claude/agent-memory/playwright-test-planner/MEMORY.md` with discovered selectors
+
+## Seed File Structure
+
+```javascript
+import { test, expect } from '@playwright/test';
+
+/**
+ * Explored Test Cases: {Module Name} - {Flow Description}
+ * Module: @{ModuleName}
+ * Page URL: {pageURL}
+ *
+ * Discovered Selectors & Form Structure:
+ * (Document all discovered selectors here)
+ */
+
+test.setTimeout(90000);
+
+async function navigateToTargetPage(page) {
+  await page.goto('/target-url');
+}
+
+test.describe('{Module Name} - {Flow Description}', () => {
+  test('TC1: Happy path scenario', async ({ page }) => {
+    await navigateToTargetPage(page);
+    // steps from recorded log with assertions
+  });
+
+  test('TC2: Cancel/validation scenario', async ({ page }) => {
+    await navigateToTargetPage(page);
+    // steps from recorded log with assertions
+  });
+});
+```
+
+## Quality Standards
+
+- Steps specific enough for any tester to follow
+- Include negative testing scenarios
+- Scenarios independent and runnable in any order
+- All selectors sourced from recorded log, not guessed
+
+## Common Mistakes to Avoid
+
+- **DO NOT** use `npx playwright codegen` — requires GUI
+- **DO NOT** use the `Write` tool for seed files — use `generator_write_test`
+- **DO NOT** manually invent selectors — use `generator_read_log` output
+- **DO NOT** skip `generator_read_log`
+- **DO NOT** use `planner_setup_page` for recording — only `generator_setup_page` records

package/.claude_rules/architecture.md

@@ -0,0 +1,102 @@
+# Architecture Decisions
+
+---
+
+### Path-Based Tag Scoping (playwright-bdd v8+)
+
+**Context:** Investigated after "missing step definition" errors when features tried to use steps from other modules.
+**Decision/Finding:** In playwright-bdd v8+, `@`-prefixed directory names in a step file's path are extracted as tags and applied as an AND expression. Steps in `@Modules/@Authentication/steps.js` are ONLY visible to features that match ALL tags: `@Modules AND @Authentication`.
+**Reasoning:** Cross-module reusable steps MUST live in `shared/` (no `@` prefix = globally scoped). This is intentional playwright-bdd behaviour, not a bug.
+
+---
+
+### 3-Layer Test Data Persistence
+
+**Context:** Need to share generated test data across scenarios and feature files without re-generating.
+**Decision/Finding:** Three layers in priority order:
+
+1. `page.testData` — scenario-scoped, cleared before each scenario via `Before` hook
+2. `globalThis.__rt_featureDataCache` — in-memory, survives scenario boundaries within a feature file
+3. `e2e-tests/playwright/test-data/{scope}.json` — file-backed, survives worker restarts and feature switches
+
+Module name auto-extracted from directory path: `@Modules/@HomePage/` → key `homepage`
+**Reasoning:** Parallel workers can't share in-memory state, so file-backed persistence is the only reliable cross-worker mechanism.
+
+---
+
+### Cache Key Auto-Derivation (`featureKey`)
+
+**Context:** New workflows needed automatic cache key assignment.
+**Decision/Finding:** `featureKey` is auto-derived from the module name at two points:
+
+1. **Before hook**: calls `extractModuleName(featureUri)` and sets `page.featureKey` if not already set
+2. **`I load predata from {string}` step**: uses `scopeName` as the cache key fallback
+
+Existing hardcoded keys still work — they explicitly set `page.featureKey` before auto-derivation applies. New workflows don't need any manual cache key setup.
+**Reasoning:** Eliminates a manual step. `extractModuleName()` already existed — just needed to use it as the default.
+
+---
+
+### Global Setup / Teardown Marker Strategy
+
+**Context:** Need clean test data at the start of each full test run, but preserve data across feature files within the same run.
+**Decision/Finding:** `global.setup.js` uses a `.cleanup-done` marker file. If no marker → new run → delete scoped data files and create marker. If marker exists → run in progress → preserve data. `global.teardown.js` deletes the marker at the end.
+**Reasoning:** Purely deterministic — no time-based logic. Prevents stale data from previous runs while allowing data sharing within a run.
+
+---
+
+### Shared Step Files Are Globally Scoped
+
+**Context:** Some steps (navigation, auth) are needed by multiple modules.
+**Decision/Finding:** Place these in `e2e-tests/features/playwright-bdd/shared/`. Files there have no `@`-prefixed path segments, so playwright-bdd makes them globally available to all features.
+Files: `auth.steps.js`, `navigation.steps.js`, `common.steps.js`, `global-hooks.js`
+`global-hooks.js` is auto-loaded via config glob — do NOT import it manually.
+
+---
+
+### Default Parallel, Serial Opt-Out
+
+**Context:** Most test scenarios should be independent and stateless. Serial execution is the exception.
+**Decision/Finding:** `fullyParallel: true` is the global default — scenarios run in parallel. Only features tagged `@serial-execution` opt out (workers: 1, browser reused across scenarios). No `@parallel-scenarios-execution` tag — parallel is the default, not an opt-in.
+
+---
+
+### Feature-Level Browser Reuse
+
+**Context:** When `@serial-execution` is used, scenarios depend on previous scenario state (Zustand store, form data). A fresh browser per scenario resets all client-side state.
+**Decision/Finding:** For `serial-execution` project, the browser page persists across scenarios within the same feature file. A new page is created only when `testInfo.file` changes. Configured via `REUSABLE_PROJECTS` array in `fixtures.js`. All other projects get standard per-scenario isolation.
+
+---
+
+### Skills Own Orchestration, Agents Are Pure
+
+**Context:** Making agents reusable as a general plugin across projects.
+**Decision/Finding:** Skills (`.claude/skills/`) define the agent chain and control execution flow. Agents (`.claude/agents/`) are pure single-responsibility units — no agent invokes another agent via `@agent-xxx`. Anyone can create new skills with custom agent chains from the same building blocks.
+
+---
+
+### Agent Memory Persistence
+
+**Context:** Healer, planner, and execution-manager agents need to remember past fixes and selector patterns.
+**Decision/Finding:** Agents with `memory: project` frontmatter use `.claude/agent-memory/<agent-name>/MEMORY.md`. Agents read this at start and write to it after completing work. The main project `MEMORY.md` is separate — agents must NOT write to it.
+Agents using memory: `playwright-test-healer`, `playwright-test-planner`, `execution-manager`
+
+---
+
+### Multi-Agent 10-Phase Pipeline
+
+**Context:** The E2E test generation pipeline defined in `/e2e-automate` skill.
+**Decision/Finding:** Pipeline flows through 10 phases:
+
+1. Read `instructions.js`
+2. Detect route (jira/file/text)
+3. Process input (`input-processor` or `jira-processor`)
+4. Explore app (`playwright-test-planner`)
+5. Validate exploration (optional, `execution-manager` seed mode)
+6. **User approval checkpoint** (mandatory pause)
+7. Generate BDD (`bdd-generator` → `code-generator`)
+8. Execute & heal (optional, `execution-manager` → `playwright-test-healer`)
+9. Cleanup
+10. Quality review (inline in skill)
+
+Agent `.md` files in `.claude/agents/` are system prompts, not executable code.

package/.claude_rules/conventions.md

@@ -0,0 +1,82 @@
+# Conventions
+
+---
+
+### BDD Feature File — Behavior Only
+
+**Context:** Feature files are specifications — they must remain readable independently of project management.
+**Decision/Finding:** Feature files describe behavior only. No project management tags (Jira refs, sprint numbers, ticket IDs). These belong in CLI args or config files, not in `.feature` files.
+
+---
+
+### BDD Tagging Convention
+
+| Tag Type  | Purpose            | Example                                                      | Required in        |
+| --------- | ------------------ | ------------------------------------------------------------ | ------------------ |
+| Module    | Which app page     | `@homepage`, `@authentication`, `@counter`                   | All features       |
+| Feature   | Specific behaviour | `@login`, `@navigation`, `@filter`                           | All features       |
+| Scope     | Cross-cutting      | `@workflow`                                                  | `@Workflows/` only |
+| Execution | Run group          | `@serial-execution`, `@smoke`                                | As needed          |
+| Auth      | Auth handling      | `@login-logout`                                              | Auth tests only    |
+| Data      | Data sharing       | `@cross-feature-data`, `@prerequisite`, `@workflow-consumer` | Workflows only     |
+
+**Execution defaults:**
+
+- Parallel is the default (`fullyParallel: true` globally). No tag needed for parallel.
+- `@serial-execution` opts out — forces 1 worker with browser reuse across scenarios.
+- Only use `@serial-execution` when scenarios share state (data or UI) with each other.
+
+**Data Table Placeholders:**
+
+- `<gen_test_data>` — used in form fill steps (generates new faker value, caches it)
+- `<from_test_data>` — used in assertion steps (reads previously generated value from cache)
+
+---
+
+### Step Definition Placement Rule
+
+**Context:** playwright-bdd v8+ path-based tag scoping means placement determines visibility.
+**Decision/Finding:**
+
+- Steps needed by ONE module → co-locate as `steps.js` next to the `.feature` file
+- Steps needed by MULTIPLE modules → place in `e2e-tests/features/playwright-bdd/shared/`
+- Never place reusable steps inside an `@`-prefixed directory
+
+---
+
+### Import from Fixtures, Not playwright-bdd Directly
+
+**Context:** Custom fixtures extend playwright-bdd's `test` object with project-specific data.
+**Decision/Finding:** Always import `Given`, `When`, `Then`, `Before`, `After`, `expect` from the fixtures file:
+
+```javascript
+import { Given, When, Then, Before, After, expect } from '../../../../playwright/fixtures.js';
+```
+
+Never import directly from `'playwright-bdd'` or `'@cucumber/cucumber'` in step files.
+**Reasoning:** The fixtures file wraps playwright-bdd and injects `authData`, `testConfig`, `testData`, `scenarioContext`.
+
+---
+
+### Feature Directory Naming
+
+**Context:** playwright-bdd extracts `@`-prefixed directory names as tags.
+**Decision/Finding:** Module directories use `@` prefix (`@Modules/`, `@Workflows/`, `@Authentication/`). The `shared/` directory intentionally has no `@` prefix to remain globally scoped.
+
+- New module directories → inside `@Modules/`
+- Cross-module flows → inside `@Workflows/`
+- Reusable steps → inside `shared/`
+
+---
+
+### Agent `.md` File Format
+
+**Context:** All agent definitions live in `.claude/agents/`.
+**Decision/Finding:** Agent files are markdown — they contain the system prompt and optional YAML frontmatter. Frontmatter keys: `name`, `description`, `model` (sonnet/opus), `color`, `memory` (`project` for persistent memory), `mcp_servers`. Agents are pure — no `@agent-xxx` invocations inside agent files. Skills own orchestration.
+
+---
+
+### 3-Column Data Table Format
+
+**Context:** Standardized data table format for all BDD scenarios.
+**Decision/Finding:** All Gherkin data tables use 3 columns: `Field Name | Value | Type`. Type values: `Static` (known value), `SharedGenerated` (generated, reused across scenarios), `Dynamic` (generated, used once).

package/.claude_rules/debugging.md

@@ -0,0 +1,90 @@
+# Debugging & Gotchas
+
+---
+
+### `.features-gen/` Must Be Deleted After Step File Changes
+
+**Context:** Stale compiled specs cause "step not found" errors even after fixing the source.
+**Decision/Finding:** `.features-gen/` is auto-generated by `bddgen` and mirrors the source feature directory. It is gitignored. If step definitions change or new steps are added, delete it and regenerate:
+
+```bash
+rm -rf .features-gen/
+pnpm test:bdd
+```
+
+`bddgen` MUST always run before `playwright test`. The `pnpm test:bdd` script does this automatically; running `playwright test` directly skips bddgen and uses stale specs.
+
+---
+
+### `playwright-bdd` — Package Name vs Directory Name
+
+**Context:** Can cause confusion when searching or renaming.
+**Decision/Finding:** `playwright-bdd` refers to two different things:
+
+1. **npm package** (`"playwright-bdd"` in `package.json`) — never rename these references
+2. **Directory** (`e2e-tests/features/playwright-bdd/`) — can be renamed but affects many config paths
+
+When grepping, results will contain both. Categorize carefully.
+
+---
+
+### Path-Based Tag Scoping "Missing Step" Errors
+
+**Context:** Steps co-located inside `@Module/@Feature/steps.js` fail with "missing step" when other features try to use them.
+**Decision/Finding:** playwright-bdd v8+ scopes step files by `@`-prefixed directory path (AND expression). Steps inside `@Modules/@Authentication/steps.js` are scoped to ONLY features matching `@Modules AND @Authentication`.
+**Fix:** Move any step file needed by multiple modules to `shared/`.
+
+---
+
+### Auth Session Must Be Regenerated After Credential Changes
+
+**Context:** Tests fail with auth errors after password changes or token expiry.
+**Decision/Finding:** The saved auth session is at `e2e-tests/playwright/auth-storage/.auth/user.json` (gitignored). To regenerate: delete the file and run `pnpm test:bdd` — the `setup` project runs `auth.setup.js` and recreates it automatically.
+
+```bash
+rm -f e2e-tests/playwright/auth-storage/.auth/user.json
+pnpm test:bdd
+```
+
+---
+
+### `global-hooks.js` Must NOT Be Manually Imported
+
+**Context:** Developers tried to import global-hooks in step files and got duplicate hook errors.
+**Decision/Finding:** `global-hooks.js` is auto-loaded by `playwright.config.ts` via a glob pattern in the `steps` array. Importing it manually in any step file causes hooks to run twice. Never add an explicit import for it.
+
+---
+
+### Never Reassign globalThis Cache Objects
+
+**Context:** `featureDataCache` reference can become stale if the globalThis object is reassigned.
+**Decision/Finding:** `global-hooks.js` exports `featureDataCache` as a one-time `const` binding to `globalThis.__rt_featureDataCache`. Doing `globalThis.__rt_featureDataCache = {}` creates a NEW object while the export still points to the OLD one — causing silent data loss.
+**Rule:** NEVER do `globalThis.__rt_featureDataCache = {}`. Always use `clearObjectInPlace()` (delete all keys from existing object) to preserve object identity.
+
+---
+
+### Seed File Must Use Standardized Path
+
+**Context:** Agents creating random seed file paths causes confusion.
+**Decision/Finding:** Always use `e2e-tests/playwright/generated/seed.spec.js`. Do not create files with dynamic names. The planner agent writes here, the code generator reads from here, the execution manager validates here.
+
+---
+
+### Reports Directory Paths
+
+**Context:** Reports generated at `reports/` (project root).
+**Decision/Finding:** Playwright config writes to:
+
+- `reports/json/results.json` — JSON report
+- `reports/cucumber-bdd/report.json` — Cucumber BDD JSON
+- `reports/playwright/` — HTML report
+- `reports/screenshots/` — Failure screenshots (from global-hooks After hook)
+
+The `global.setup.js` creates these directories. View with `pnpm report:playwright`.
+
+---
+
+### Empty Cucumber BDD Report
+
+**Context:** `reports/cucumber-bdd/report.json` may be 0 bytes when tests fail.
+**Decision/Finding:** The `cucumberReporter` from playwright-bdd sometimes produces empty output on test failures. This is a known limitation — the JSON and HTML reporters still work correctly. Use `reports/json/results.json` or `reports/playwright/` for failure analysis.

package/.claude_rules/dependencies.md

@@ -0,0 +1,54 @@
+# Dependencies
+
+---
+
+### `playwright-bdd` v8+
+
+**Context:** Core E2E test framework.
+**Decision/Finding:** Sits on top of `@playwright/test`. Provides Gherkin `.feature` file support, `bddgen` CLI to compile features to Playwright specs, and path-based tag scoping. Key behaviours:
+
+- `@`-prefixed directory names in step file paths become scoping tags
+- `bddgen` must run before `playwright test` to compile `.features-gen/`
+- Import `createBdd` from `'playwright-bdd'` in `fixtures.js` only; step files import from fixtures
+- `cucumberReporter` available for BDD JSON output
+
+---
+
+### `@faker-js/faker` v10
+
+**Context:** Test data generation for E2E tests.
+**Decision/Finding:** ESM exports — import as `import { faker } from '@faker-js/faker'`. Used for generating realistic test data (names, emails, IDs) in step definitions and seed files.
+
+---
+
+### `@fourkites/elemental-*` (Elemental Design System)
+
+**Context:** Internal UI component library used in the application.
+**Decision/Finding:** Multiple packages — `elemental-design-system`, `elemental-blocks`. When writing E2E selectors, check if components come from Elemental — they may have specific `data-testid` patterns or ARIA structures.
+
+---
+
+### Zustand + TanStack Query
+
+**Context:** State management.
+**Decision/Finding:** Zustand for lightweight client state (e.g., Counter store), TanStack React Query for server state and data fetching (e.g., Users page). No Redux in this template. E2E tests interact with the UI, not stores directly.
+
+---
+
+### Vite 7
+
+**Context:** Build tool and dev server.
+**Decision/Finding:** Dev server runs on port 5173. Module Federation enabled via `@module-federation/vite`. The `playwright.config.ts` webServer config starts `pnpm dev` automatically when `BASE_URL` is localhost.
+
+---
+
+### MCP Servers (Agent Pipeline)
+
+**Context:** External tools used by the agent pipeline.
+**Decision/Finding:**
+
+- `playwright-mcp` — Browser automation for exploration and test generation (planner, generator, healer)
+- `markitdown` — File format conversion (Excel, CSV, PDF → markdown) for input-processor
+- `atlassian` — Jira ticket fetching for jira-processor
+
+These are configured in agent frontmatter (`mcp_servers` field) and activated when the agent runs.