@metasession.co/devaudit-cli 0.1.1 → 0.1.3

package/sdlc/files/_common/skills/_schema/skill.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://devaudit.metasession.co/sdlc/skills/skill.schema.json",
+  "title": "Claude Code Skill frontmatter",
+  "description": "Validates the YAML frontmatter at the top of every SKILL.md under sdlc/files/_common/skills/ or sdlc/files/stacks/<name>/skills/. The body of SKILL.md (everything after the frontmatter) is free-form Markdown — Claude reads it as the skill's instructions and isn't validated here.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["name", "description"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9-]{1,63}$",
+      "description": "Lowercase identifier — matches the parent directory under skills/ and is how Claude refers to the skill when invoking it. 2–64 chars, lowercase, kebab-cased."
+    },
+    "description": {
+      "type": "string",
+      "minLength": 50,
+      "description": "What the skill does AND when Claude should invoke it. Both halves matter — without 'when to use' triggers, discovery doesn't fire. Aim for 100–500 characters."
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
+      "description": "Optional semver. Useful when a skill's expected behaviour changes incompatibly; consumers can pin to a known version."
+    },
+    "tags": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true,
+      "description": "Optional tags for grouping skills (e.g. 'testing', 'security', 'compliance'). Not consumed by Claude — useful for documentation tooling."
+    },
+    "license": {
+      "type": "string",
+      "description": "Optional SPDX licence identifier or 'proprietary'."
+    }
+  }
+}

package/sdlc/files/_common/skills/e2e-test-engineer/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: e2e-test-engineer
+description: Maintain or bootstrap a project's end-to-end and visual regression test pack. Use when the user wants to add, update, or retire e2e or visual tests for a feature, ticket, issue, or PR — OR when no e2e suite exists yet and one needs setting up using best practices for the detected stack. Covers deriving the scenarios a change needs, matching the project's conventions, removing obsolete tests (only after confirmation), running the suite, and filing defects for failures or missed acceptance criteria. Trigger on phrases like "add e2e tests for [ticket]", "update the test pack", "what tests do we need for this issue", "are any tests obsolete", "run the e2e tests and file issues", "add visual regression coverage", "set up e2e tests for this project", or "bootstrap an e2e suite". Framework-agnostic (Playwright, Cypress, Selenium, etc.) and tracker-agnostic (GitHub, Jira, Linear, etc.). Do NOT use for unit, component, or API-only tests, or performance tests.
+---
+
+# E2E Test Engineer
+
+Maintain or bootstrap a project's e2e and visual regression test suite. Given an issue (or ticket, or PR) plus the implementation, derive the scenarios the change actually needs, reconcile them with what's already there (adding what's missing, retiring what's obsolete), run the suite, and surface defects and missed acceptance criteria. When no suite exists yet, set one up using best practices for the detected tech stack before adding the change's tests as the first real tests in the new suite.
+
+## Scope
+
+**In scope**
+- End-to-end tests (UI-driven, user-flow level) in any framework.
+- Visual regression tests in any tool.
+- Maintaining an existing test pack — adding, updating, retiring tests.
+- Bootstrapping a new e2e suite when none exists, including framework selection, structure, configuration, a starter smoke test, and (optionally) CI integration.
+
+**Out of scope**
+- Unit, component, or API-only tests.
+- Performance, load, or accessibility audits, unless the project's e2e pack already includes them — in which case follow its lead.
+
+## The workflow
+
+Six phases. Don't skip them and don't reorder — each one feeds the next. Communicate progress as you go; long silent phases feel like the skill has stalled.
+
+### Phase 1 — Orient
+
+Three things must be in hand before designing tests: the **test stack**, the **change**, and the **issue tracker**. Discover them in parallel where possible.
+
+**Detect the test stack** from the repo:
+
+- *E2E framework signals* — `playwright.config.*`, `cypress.config.*`, `wdio.conf.*`, `nightwatch.conf.*`, `codecept.conf.*`, `testcafe.config.*`. Failing that, check `package.json` dependencies for `@playwright/test`, `cypress`, `webdriverio`, `puppeteer`, `selenium-webdriver`, or Python equivalents (`pytest-playwright`, `selenium`, `splinter`).
+- *Test location* — common patterns: `e2e/`, `tests/e2e/`, `cypress/e2e/`, `playwright/`, `test/e2e/`, `__tests__/e2e/`.
+- *Visual regression tool* — Playwright or Cypress built-in snapshots, `cypress-image-snapshot`, `cypress-visual-regression`, `percy`, `applitools-eyes-*`, `chromatic`, `backstop.json`, `loki`, `reg-suit`. If none of these are present, the project doesn't do visual regression and you should only add it if the issue explicitly asks for it.
+- *Run command* — search `package.json` scripts for `e2e`, `test:e2e`, `cy:run`, `pw:test`. Failing that, check `Makefile`, `justfile`, `tox.ini`, `pyproject.toml`, CI config. If still unclear, ask.
+
+**Detect the issue tracker** so you can read the input issue now and file defect issues later:
+
+- GitHub: git remote on `github.com` → use the `gh` CLI if installed, or a connected GitHub MCP.
+- GitLab: `glab` CLI or a GitLab MCP.
+- Jira: an Atlassian MCP, or `jira-cli` config.
+- Linear: a Linear MCP.
+- Azure DevOps: the `az boards` CLI or an ADO MCP.
+- None of the above: ask the user where the source issue lives and where defects should go. Final fallback is a paste-ready markdown report.
+
+**Take in the change.** The user typically gives you one of:
+
+- An issue/ticket ID or URL → fetch its full text, description, comments, and acceptance criteria.
+- A PR/MR URL or a branch name → fetch the description and the diff.
+- A pasted description → use what you've been given; ask for the diff or branch if not provided.
+
+Briefly summarise what you found (the stack, the tracker, the change in one or two sentences) and confirm before continuing. The user is far more responsive to corrections now than after you've written twelve test files.
+
+**If no e2e suite was found, go to Phase 1b before continuing.** Otherwise skip to Phase 2.
+
+### Phase 1b — Bootstrap (only when no suite exists)
+
+This phase runs only if Phase 1 found no e2e framework, no test directory, and no relevant dependencies. Don't run it just because the existing suite is small or messy — that's a maintenance problem, not a bootstrap one.
+
+The goal of bootstrap is a working, well-configured e2e suite with one passing smoke test, set up so that any tests added afterward (including the change's tests in Phase 5) feel native to the project. **Read `references/bootstrap.md`** before you start — it has the per-stack framework recommendations, official-installer commands, config best practices, and structure templates.
+
+The bootstrap workflow:
+
+1. **Gather extra context** beyond what Phase 1 found:
+   - Frontend framework (React, Vue, Angular, Svelte, Next.js, Nuxt, mobile, Electron, etc.) — from `package.json` deps or equivalent.
+   - Language — `tsconfig.json` for TypeScript, otherwise JS or whatever the project uses.
+   - Package manager — `pnpm-lock.yaml` → pnpm; `yarn.lock` → yarn; otherwise npm. Or pip/poetry/uv for Python; bundler for Ruby; etc.
+   - Dev server command and port — from `scripts` in `package.json` or the equivalent.
+   - CI system — `.github/workflows/`, `.gitlab-ci.yml`, `.circleci/`, `Jenkinsfile`, `azure-pipelines.yml`.
+   - Any existing unit/integration test framework — for matching style (assertions, file naming, runner conventions).
+
+2. **Propose a framework choice with a one-line rationale, and get explicit confirmation.** This is a long-lived decision; do not install anything without a clear "yes". Use `references/bootstrap.md` for the recommendation matrix. Briefly mention the runner-up so the user can override if their team has a preference you couldn't infer.
+
+3. **Decide whether to include visual regression now.** If the user asked for it, or the originating issue is visually significant, yes. If unsure, ask. Visual regression has its own tooling decision (built-in snapshots vs cloud service like Percy/Chromatic/Applitools) — `references/bootstrap.md` covers this.
+
+4. **Install with the official installer** wherever one exists (e.g. `npm init playwright@latest`, `npx cypress install`). Official installers set up sensible defaults the skill shouldn't try to second-guess.
+
+5. **Lay out the directory structure** for the project's expected scale: a top-level test directory (`e2e/` or whatever the framework's installer chose), with subfolders for specs, fixtures, page objects (or fixture-based equivalent), helpers, and visual specs if applicable. Write the structure as a short tree in your reply so the user can see what was created.
+
+6. **Configure for best practice** — base URL pointing at the project's dev server, retries on CI only, parallel workers, an HTML reporter, trace on first retry, `screenshot: 'only-on-failure'` (failure forensics — see *Evidence vs failure forensics* below for per-AC evidence capture), video retention on failure, and (if the framework supports it) auto-starting the dev server before the suite runs. Specifics per framework are in `references/bootstrap.md`.
+
+7. **Establish the abstraction pattern** — write one Page Object Model (or one fixture, depending on framework idioms) as a worked example so the change's tests in Phase 5 have a template to follow.
+
+8. **Write a smoke test** that proves the setup works end-to-end: load the home page, assert the title or a known stable element. Run it. It must pass before you continue.
+
+9. **Wire up runner scripts** — at minimum `test:e2e` (headless), `test:e2e:ui` or `:headed` (interactive), `test:e2e:debug`, and `test:e2e:update-snapshots` if visual regression is in.
+
+10. **Offer a CI job** — write the YAML (or equivalent) for the project's CI system, but **do not commit it without confirmation**. Show it inline first.
+
+11. **Write a short README** in the test directory explaining structure, how to run, how to add new tests, and how to update visual baselines. Future contributors (and the skill itself, on next invocation) will thank you.
+
+After bootstrap, if there's a change to test, continue to Phase 2 as normal. If the user only wanted the suite set up with no specific change in mind, stop here with a final summary.
+
+### Phase 2 — Understand the change
+
+You cannot write the right tests without understanding what changed and why. Spend real time here.
+
+1. **Read the issue end-to-end.** Capture: the user-facing goal, the explicit acceptance criteria (number them), any negative criteria ("should not allow X"), edge cases the description mentions, and any references to existing behaviour that must stay intact.
+
+2. **Read the implementation.** From the diff or branch:
+   - Which files changed — routes, components, state, API contracts, styles?
+   - What's the user-facing entry point — what URL, what control, what flow leads here?
+   - What pre-conditions does the new behaviour assume — auth state, feature flag, seed data?
+   - What adjacent surfaces share code with the change and could regress as a side effect?
+
+3. **Read the surrounding app** enough to know how a real user reaches the changed area. Look at routing, navigation, and the one or two most adjacent features.
+
+4. **Write a short mental model** in your reply: *trigger → new behaviour → expected outcomes → likely side-effects*. If anything is ambiguous, ask the user before designing scenarios. Guesses here cascade into bad tests.
+
+### Phase 3 — Design scenarios
+
+The goal is the *minimum* set of scenarios that, if they all pass, would give a reasonable person high confidence the change works as intended and hasn't broken adjacent functionality. "Minimum" is load-bearing: e2e tests are slow to run and expensive to maintain, and a bloated suite gets ignored.
+
+Derive scenarios from these sources, in this order:
+
+1. **One scenario per acceptance criterion.** If an AC is compound ("user can filter by status AND see a count"), split it.
+
+2. **One negative scenario per error path the change introduces.** Invalid input, unauthorised access, network failure — only if the change has explicit handling for it.
+
+3. **Boundary scenarios** where the change has obvious boundaries: empty state, max length, zero results, single result, many results.
+
+4. **Adjacent regression scenarios** — pick the one or two nearby flows most likely to break because they share code with the change. Don't try to re-test the whole app from this seat.
+
+5. **Visual regression scenarios** (only if the project does visual regression): each visually-changed component or page state gets a snapshot at the breakpoints the project already covers. Add one or two adjacent surfaces that share styling.
+
+Resist padding. A new endpoint doesn't need a test that re-verifies login if login is already covered. Match the project's existing depth — if it covers one happy path per feature, don't add six.
+
+For each scenario, write a one-line description. Present the full grouped list to the user before writing any code: *"Here's the coverage I'd propose — anything to add or drop?"*
+
+### Phase 4 — Reconcile with existing tests
+
+For the area touched by the change, look at what's already there.
+
+1. **Overlap** — find existing tests that already cover scenarios from Phase 3. Don't duplicate; either reuse or note the overlap and drop the duplicate from your add list.
+
+2. **Obsolete** — a test is obsolete when:
+   - The behaviour it asserts has been intentionally removed or replaced.
+   - The selectors or routes it uses no longer exist and the new equivalents are covered elsewhere.
+   - It tests an old version of a flow that has been fully superseded.
+
+   A test is **not** obsolete just because it's failing. Failing tests are signals, not garbage. Be conservative — when in doubt, propose updating rather than deleting.
+
+3. **Needs updating** — existing tests where the scenario is still valid but selectors, routes, or assertions have shifted.
+
+Present three lists to the user:
+- **To add** — new scenarios not already covered.
+- **To update** — existing tests needing adjustment.
+- **To delete** — genuinely obsolete tests, each with a one-line rationale.
+
+**Do not delete anything without explicit confirmation.** Not even tests you're 95% sure about. The cost of asking is one sentence; the cost of deleting real coverage is real. Wait for a clear "yes, delete those" before removing anything.
+
+### Phase 5 — Implement
+
+Write the tests in the project's existing style.
+
+- **Match the structure.** Same directory, same file-naming pattern, same test-ID or tag convention.
+- **Reuse existing helpers.** Page Object Models, fixtures, custom commands, test-data factories — use them. Don't invent parallel infrastructure.
+- **Match the assertion style.** If the codebase uses `expect(locator).toBeVisible()`, don't switch to `assert.isTrue(...)`.
+- **Read 2–3 nearby tests before writing.** Fastest way to absorb conventions you wouldn't have noticed otherwise.
+
+For **visual regression** specifically:
+- New tests need baseline images. Generate them, but **do not auto-approve** — surface them for the user to verify before they're committed.
+- Use the project's existing breakpoints, viewports, and element-masking conventions.
+
+Do additions, updates, and (approved) deletions in the same change so the suite stays internally consistent.
+
+### Phase 6 — Execute and report
+
+Run the suite. Strategy:
+
+1. **Run the new and updated tests first** in isolation if the framework supports filtering. Fast feedback on whether your tests themselves work.
+2. **Then run the full suite** to catch regressions outside the changed area.
+3. **For visual regression**, run the project's normal comparison mode against existing baselines.
+
+Triage every failure into one of these buckets *before* taking any action:
+
+- **Flake** — non-deterministic; passes on rerun. Rerun once. If it passes, note it. If it keeps flaking, flag it but don't file a noisy bug.
+- **Test bug** — your test is wrong (bad selector, wrong assertion, timing). Fix the test; don't file anything.
+- **Application defect** — the app does the wrong thing. File it.
+- **Visual diff — intended** — the snapshot changed because the change intentionally changed the UI. Update the baseline and surface it for user approval.
+- **Visual diff — unintended** — a snapshot changed somewhere the change shouldn't have affected. File it as a regression.
+
+**Then check for missed requirements.** For each numbered acceptance criterion from Phase 2, confirm at least one *passing* test covers it. An AC with no passing test — because no test was written, or because the test fails — is a missed requirement. File it.
+
+### Filing defects
+
+Use whatever tracker integration you found in Phase 1: `gh issue create`, `glab issue create`, a Jira or Linear MCP tool, `az boards work-item create`. If nothing is available, produce a markdown report with each defect formatted ready to paste.
+
+Each filed issue needs:
+
+- **Title** — short, specific, describes the symptom not the cause. *"Filter by status shows zero results when status=pending"*, not *"Filter broken"*.
+- **Steps to reproduce** — numbered, minimal, exact.
+- **Expected vs actual** — on separate lines, no ambiguity.
+- **Environment** — branch, commit SHA, test command, browser/viewport if relevant.
+- **Evidence** — link or path to the failing test, error output, screenshot, trace.
+- **Link back** to the originating issue/PR.
+- **Severity** — your honest call: blocker, major, minor. Don't inflate.
+
+Show the user the full set of issues you're about to file. Get confirmation. Then file them.
+
+### Final report
+
+Wrap up with a summary the user can drop into the PR or ticket:
+
+- Tests added — count, with a list.
+- Tests updated — count.
+- Tests deleted — count, with rationale.
+- Suite result — passing, failing, flaky.
+- Defects filed — count, with links.
+- Missed requirements — count, with links.
+
+---
+
+## Evidence vs failure forensics
+
+Playwright's auto-screenshot (`screenshot: 'only-on-failure'`) is for **failure forensics** — "what state was the page in when this test broke?" For a passing test it captures the post-test screen, which is useless as compliance evidence.
+
+To prove an AC was actually verified, call `evidenceShot()` **at the assertion that proves it**, before any further interaction:
+
+```ts
+import { evidenceShot } from './helpers/evidence';
+
+test('AC1: edit dialog opens with fields pre-filled', async ({ page }) => {
+  await openEditDialog(page, item.id);
+  await expect(dialog.locator('#name')).toHaveValue(item.name);
+  await evidenceShot(page, 'REQ-037', 'AC1-edit-dialog-prefilled');
+  // ...rest of test
+});
+```
+
+**Discipline:**
+
+- Call `evidenceShot` **immediately after** the AC-proving assertion, before navigating, closing dialogs, or any further interaction.
+- Slug as `AC<n>-<what-this-proves>` — the filename documents the claim.
+- One screenshot per AC, not per test.
+- Failure forensics stays untouched (`screenshot: 'only-on-failure'` + `trace: 'on-first-retry'`).
+
+The helper is shipped automatically into `e2e/helpers/evidence.ts` by the SDLC sync (node-stack consumers). Output lands at `compliance/evidence/<REQ-ID>/screenshots/<slug>.png` — commit these PNGs as part of the evidence pack so reviewers can corroborate the test-plan AC mapping.
+
+The canonical helper source lives at `references/evidence.ts` in this skill.
+
+---
+
+## Principles
+
+**Match the project's existing depth.** If it tests one happy path per feature, don't add six scenarios per AC. If it tests exhaustively, match that. Right coverage is coverage consistent with what's already there.
+
+**E2E is expensive.** Every test you add costs CI time and maintenance forever. Add what's needed for confidence in the change; resist adding more. The goal is a suite that stays trusted, not a suite that's maximal.
+
+**Don't invent infrastructure.** If the project uses POMs, use POMs. If it uses fixtures, use fixtures. If something is genuinely missing that you need, ask the user before adding it.
+
+**Confirm before destructive or public actions.** Deleting tests, approving new visual baselines, filing defects in a tracker — all need explicit user sign-off. The cost of confirming is a sentence; the cost of getting it wrong is real.
+
+**Ambiguity is a question, not a guess.** If an AC is unclear or the implementation does something the issue doesn't describe, ask. Tests built on guesses about intent are worse than no tests — they encode and propagate the misunderstanding.

package/sdlc/files/_common/skills/e2e-test-engineer/references/bootstrap.md

@@ -0,0 +1,244 @@
+# Bootstrap Reference
+
+Detailed guidance for setting up an e2e suite from scratch. Read this when Phase 1b of `SKILL.md` is in play.
+
+## Contents
+1. Framework selection matrix (by tech stack)
+2. Visual regression tool selection
+3. Official installer commands
+4. Best-practice configuration
+5. Directory structure templates
+6. CI snippets
+7. Anti-patterns to avoid
+
+---
+
+## 1. Framework selection matrix
+
+Recommend a primary, mention the runner-up, get user confirmation before installing. These recommendations reflect current best practice for new projects; if the team has a strong preference, follow it.
+
+### Web apps — JavaScript / TypeScript
+
+| Stack | Primary | Runner-up | Rationale |
+|---|---|---|---|
+| React / Next.js / Remix | **Playwright** | Cypress | Fast, parallel by default, multi-browser, first-party TS, built-in visual regression, excellent trace viewer. |
+| Vue / Nuxt | **Playwright** | Cypress | Same reasons. |
+| Angular | **Playwright** | Cypress | Playwright has overtaken Cypress as the Angular community default; Cypress still common in established Angular shops. |
+| Svelte / SvelteKit | **Playwright** | — | SvelteKit's official template ships Playwright. |
+| Static sites / SSG | **Playwright** | Cypress | Either works; Playwright is simpler to set up. |
+| Legacy multi-browser-grid needs | **WebdriverIO** | Selenium | Needed when integrating with existing Sauce Labs / BrowserStack grids or non-Chromium-family browsers beyond what Playwright covers. |
+| Anything requiring real IE11 (rare) | **Selenium** | — | Only Selenium still targets IE. |
+
+### Mobile
+
+| Stack | Primary | Runner-up | Rationale |
+|---|---|---|---|
+| React Native | **Detox** | Appium | Native, fast, integrates with RN test infra. |
+| Native iOS / Android cross-platform | **Appium** | Maestro | Industry standard; Maestro is gaining popularity for simpler flows. |
+| Mobile web | **Playwright** (mobile emulation) | Appium (for real-device need) | Playwright covers viewport + UA emulation; Appium for real-device touch interactions. |
+
+### Desktop
+
+| Stack | Primary | Runner-up | Rationale |
+|---|---|---|---|
+| Electron | **Playwright** | WebdriverIO + Electron service | Playwright has first-party Electron support. |
+| Tauri | **WebdriverIO** + Tauri driver | — | Official path. |
+
+### Backend-rendered / non-JS web apps
+
+| Stack | Primary | Runner-up | Rationale |
+|---|---|---|---|
+| Python (Django, Flask, FastAPI with templates) | **pytest-playwright** | Selenium + pytest | Same Playwright engine, idiomatic for Python test suites. |
+| Ruby on Rails | **Capybara + Cuprite** | Capybara + Selenium | Cuprite uses CDP, faster than Selenium. |
+| Java (Spring etc.) | **Playwright for Java** | Selenium + JUnit/TestNG | Playwright Java is mature; Selenium still dominant in enterprise Java. |
+| .NET | **Playwright for .NET** | Selenium + NUnit/xUnit | Playwright .NET is well-supported. |
+| PHP (Laravel, Symfony) | **Playwright via PHP** or **Pest browser plugin** | Codeception | Pest's browser plugin is gaining ground for Laravel. |
+
+### When to question the default
+
+- **Team already uses Cypress productively elsewhere** — stick with Cypress for consistency.
+- **Heavy iframe / cross-origin needs** — Cypress historically struggled here; Playwright handles it. (Cypress has improved but Playwright is smoother.)
+- **Component testing matters too** — Cypress has a unified e2e + component runner; with Playwright you'd add a separate component test setup.
+
+---
+
+## 2. Visual regression tool selection
+
+Only add visual regression if the user asked for it or the originating issue is visually significant. Default off for greenfield bootstrap unless explicitly requested.
+
+| Need | Recommendation | Notes |
+|---|---|---|
+| Default for Playwright | **`toHaveScreenshot()` built-in** | Zero extra deps; baselines stored in repo. Configure `threshold` and `maxDiffPixels`. |
+| Default for Cypress | **`cypress-image-snapshot`** | Or `cypress-visual-regression`. Both store baselines in repo. |
+| Default for WebdriverIO | **`@wdio/visual-service`** | Maintained, image-comparison-based. |
+| Default for BackstopJS-style standalone | **BackstopJS** | Use only if not integrating with an e2e framework above. |
+| Cross-team approval workflow needed | **Percy** or **Chromatic** | Cloud, web-based diff review. Chromatic is Storybook-friendly. Percy is generic. |
+| Heavy use of AI-assisted diffing / dynamic content | **Applitools** | Commercial, ML-based comparison, handles dynamic content gracefully. Higher cost. |
+
+Baseline strategy on first bootstrap: generate baselines locally, then have the user verify each one before committing. Never auto-approve baselines in CI on first run.
+
+---
+
+## 3. Official installer commands
+
+Always prefer the official installer — it gives the framework's authors' recommended defaults, which the skill should not override without reason.
+
+```bash
+# Playwright (Node)
+npm init playwright@latest
+# Picks language, test dir, GitHub Actions, browsers.
+
+# Playwright (Python)
+pip install pytest-playwright
+playwright install
+
+# Cypress
+npm install --save-dev cypress
+npx cypress open  # first run sets up structure
+
+# WebdriverIO
+npm init wdio@latest .
+
+# Detox (React Native)
+npm install --save-dev detox
+detox init
+
+# Appium
+npm install --save-dev appium @wdio/cli
+# Then use wdio installer
+
+# Selenium (Java, Maven)
+# Add selenium-java + junit-jupiter to pom.xml; no CLI installer.
+```
+
+Match the package manager: `npm` → `npm install`, `pnpm` → `pnpm add`, `yarn` → `yarn add`.
+
+---
+
+## 4. Best-practice configuration
+
+### Playwright (`playwright.config.ts`)
+
+Key settings to set up beyond the installer defaults:
+
+- `baseURL` — pointing at the project's dev server (`http://localhost:3000`, `5173`, `4200`, etc. depending on framework).
+- `retries: process.env.CI ? 2 : 0` — flake tolerance in CI only.
+- `workers: process.env.CI ? 2 : undefined` — explicit CI worker count.
+- `reporter: [['html'], ['list']]` — and add `['junit', ...]` if CI needs JUnit XML.
+- `use.trace: 'on-first-retry'` — full trace on flake.
+- `use.screenshot: 'only-on-failure'`.
+- `use.video: 'retain-on-failure'`.
+- `webServer` — auto-start the dev server before tests; saves CI config complexity.
+- `projects` — at least Chromium; add Firefox/WebKit if cross-browser matters; add a mobile viewport project if relevant.
+- `expect.toHaveScreenshot` — set `threshold` (default 0.2 is usually too lax for UI work; try 0.1) and `maxDiffPixels` for noise tolerance.
+
+### Cypress (`cypress.config.ts`)
+
+- `baseUrl`.
+- `viewportWidth`, `viewportHeight` — set explicitly so visual diffs are stable.
+- `retries: { runMode: 2, openMode: 0 }`.
+- `video: false` (or `true` with `videoCompression`) — videos are large; opt in deliberately.
+- `screenshotOnRunFailure: true`.
+- For visual regression with `cypress-image-snapshot`: configure `failureThreshold` and `failureThresholdType: 'percent'`.
+
+### Universal
+
+- Pin framework versions in `package.json` (no `^` for the test runner) — flake from runner updates is real.
+- Add the test browsers to `.gitignore` if downloaded outside `node_modules`.
+- Add baseline images to git if visual regression is set up.
+
+---
+
+## 5. Directory structure templates
+
+### Playwright (TypeScript)
+
+```
+e2e/
+├── tests/
+│   ├── auth/
+│   │   └── login.spec.ts
+│   └── home.smoke.spec.ts
+├── pages/
+│   └── login.page.ts
+├── fixtures/
+│   ├── auth.fixture.ts
+│   └── test-data.ts
+├── helpers/
+│   └── api-setup.ts
+└── visual/
+    └── home.visual.spec.ts
+playwright.config.ts
+```
+
+Playwright idiom is fixtures over POMs. POMs work; fixtures are more native. Use whichever the user prefers, but be consistent.
+
+### Cypress
+
+```
+cypress/
+├── e2e/
+│   ├── auth/
+│   │   └── login.cy.ts
+│   └── home.smoke.cy.ts
+├── support/
+│   ├── commands.ts        # custom commands
+│   ├── e2e.ts             # global setup
+│   └── pages/
+│       └── login.page.ts
+├── fixtures/
+│   └── users.json
+└── snapshots/             # visual baselines if using image-snapshot
+cypress.config.ts
+```
+
+Cypress idiom is custom commands (`cy.login(...)`) over POMs, but POMs are fine and increasingly common.
+
+---
+
+## 6. CI snippets
+
+Offer these as suggestions, get user confirmation before writing or committing.
+
+### GitHub Actions — Playwright
+
+```yaml
+name: E2E
+on: [push, pull_request]
+jobs:
+  e2e:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 'lts/*' }
+      - run: npm ci
+      - run: npx playwright install --with-deps
+      - run: npm run test:e2e
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 14
+```
+
+### GitHub Actions — Cypress
+
+Use the official `cypress-io/github-action` — handles caching and parallelisation. Equivalent shape; see Cypress docs for current syntax (it changes more often than other CI integrations).
+
+### GitLab CI / CircleCI / Jenkins
+
+Each framework's docs have reference pipelines; link the user to them rather than hand-writing from scratch. The shape is always: install deps → install browsers → start dev server (or rely on `webServer` config) → run tests → upload artifacts.
+
+---
+
+## 7. Anti-patterns to avoid
+
+- **Don't write your own framework wrapper.** Use the framework's idioms directly. Wrappers ossify and the framework upgrades pass them by.
+- **Don't add every browser.** Start with one (Chromium); add others when the user has a real reason (cross-browser bugs reported, multi-browser SLA).
+- **Don't enable video by default.** It's expensive in CI; opt in for the suites that need it.
+- **Don't auto-approve visual baselines.** Bake in a manual approval step on first generation and on diff.
+- **Don't put real credentials in fixtures.** Use environment variables, dotfiles (`.env.test`, gitignored), or per-environment auth state files.
+- **Don't ignore the trace viewer / debug tools.** Playwright's trace viewer and Cypress's time-travel debugger are the reason these tools exist; lean on them for triage.
+- **Don't skip the smoke test on bootstrap.** A passing smoke test is the proof the setup is real. Without it you're handing the user broken infrastructure.

package/sdlc/files/_common/skills/e2e-test-engineer/references/evidence.ts

@@ -0,0 +1,40 @@
+import path from 'path';
+import { type Page } from '@playwright/test';
+
+const SLUG_RE = /^[A-Za-z0-9_-]+$/;
+
+/**
+ * Write a per-assertion screenshot into the requirement's evidence pack.
+ *
+ * Call this AT the assertion that proves the AC, before any further
+ * interaction or navigation. The PNG is committed as part of the
+ * evidence pack and used by reviewers to corroborate the test-plan
+ * AC mapping.
+ *
+ * Output path: `compliance/evidence/<reqId>/screenshots/<slug>.png`
+ *
+ * @example
+ *   await expect(dialog.locator('#name')).toHaveValue(item.name);
+ *   await evidenceShot(page, 'REQ-037', 'AC1-edit-dialog-prefilled');
+ */
+export async function evidenceShot(
+  page: Page,
+  reqId: string,
+  slug: string,
+  opts: { fullPage?: boolean } = {},
+): Promise<void> {
+  if (!SLUG_RE.test(reqId)) {
+    throw new Error(`evidenceShot: invalid reqId "${reqId}" (must match ${SLUG_RE})`);
+  }
+  if (!SLUG_RE.test(slug)) {
+    throw new Error(`evidenceShot: invalid slug "${slug}" (must match ${SLUG_RE})`);
+  }
+  const out = path.join(
+    process.cwd(),
+    'compliance/evidence',
+    reqId,
+    'screenshots',
+    `${slug}.png`,
+  );
+  await page.screenshot({ path: out, fullPage: opts.fullPage ?? true });
+}