Chore/portfolio polish

.claude/README.md

@@ -0,0 +1,128 @@
+# SDET Claude Code Kit — TypeScript + Playwright (contract-first)
+
+A composable set of **15 skills**, **3 subagents**, **9 slash commands** and **3 hooks** for Claude Code that turns a TS+Playwright repository into a SDET / Test Architect workspace. Designed around progressive disclosure, deterministic validators, and OpenAPI as the single source of truth.
+
+> Companion artefact: see the full architectural blueprint in the `docs/` of the originating chat (or paste the markdown into your repo).
+
+## What is in this kit
+
+```
+.claude/
+├── settings.json                    # hooks configuration
+├── skills/                          # 15 skills, each with SKILL.md + scripts/ + references/
+│   ├── playwright-framework-bootstrap/
+│   ├── api-client-from-openapi/
+│   ├── test-data-factory-builder/
+│   ├── fixture-architect/
+│   ├── config-and-secrets/
+│   ├── requirements-to-test-design/
+│   ├── gherkin-test-case-author/
+│   ├── playwright-test-author-ui/
+│   ├── playwright-test-author-api/
+│   ├── playwright-debug-conductor/
+│   ├── test-code-reviewer/
+│   ├── flaky-triage/
+│   ├── run-analyzer/
+│   ├── coverage-gap-analyzer/
+│   └── release-report-composer/
+├── agents/
+│   ├── test-design-agent.md         # isolated context for test design
+│   ├── flaky-detective.md           # post-run flake hunter
+│   └── contract-drift-watch.md      # haiku-cheap drift checker
+├── commands/                        # 9 slash commands (/test-new, /test-fix, /test-review, …)
+└── hooks/
+    ├── guard-bash.sh                # blocks rm -rf, force push, hard reset on protected branches
+    ├── guard-paths.sh               # blocks edits to generated/, .env, node_modules/
+    └── typecheck-touched.sh         # tsc --noEmit per touched file
+CLAUDE.md                            # thin project conventions (≤ 300 lines)
+tests-config.json                    # single source of layout truth
+```
+
+## Install
+
+1. Drop `.claude/`, `CLAUDE.md`, and `tests-config.json` into the root of your TS+Playwright repo.
+2. Make scripts executable (already done in this archive):
+   ```bash
+   chmod +x .claude/hooks/*.sh .claude/skills/*/scripts/*.sh .claude/skills/*/scripts/*.ts
+   ```
+3. Open the repo in Claude Code (`claude`). Verify skills are listed in `/skills`.
+4. Adjust `tests-config.json` if your layout differs.
+
+## How it works
+
+- **Skills** (`.claude/skills/*`) auto-trigger via their `description` frontmatter. Each skill lints its own outputs through `scripts/*` validators that exit non-zero on violations.
+- **Subagents** (`.claude/agents/*`) run with isolated context and minimal tools — invoke them when the main thread should not be polluted (test design, flake forensics, contract diff).
+- **Slash commands** (`.claude/commands/*`) compose multiple skills into pipelines: `/test-new`, `/test-fix`, `/test-review`, `/spec-sync`, `/flake-hunt`, `/coverage`, `/release-report`, `/factory`, `/page`.
+- **Hooks** (`.claude/hooks/*`) execute deterministic guards (Bash safety, path protection, typecheck) that should never be left to the LLM.
+
+## Quick start
+
+```bash
+# In Claude Code:
+/test-new coupon-apply       # full SDET pipeline from a user story
+/spec-sync                   # regenerate OpenAPI types and drift report
+/flake-hunt 20               # hunt flaky tests via 20 reruns + triage
+/test-review                 # review staged test changes
+/release-report v1.42.0      # executive release readiness summary
+```
+
+## Contract-first workflow (how it ties together)
+
+```
+specs/openapi.yaml
+   │
+   │  api-client-from-openapi  →  tests/api/generated/{schema.d.ts, zod/}
+   │  contract-drift-watch     →  CONTRACT_DRIFT.md
+   ▼
+tests/factories/*.factory.ts   ←  test-data-factory-builder (uses generated types)
+   │
+   ▼
+tests/api/clients/*Client.ts   ←  fixtures/api.ts  (DI)
+                                  ↑
+                                  fixture-architect
+   ▼
+tests/specs/api/**/*.spec.ts   ←  playwright-test-author-api  (asserts via zod schemas)
+tests/specs/**/*.spec.ts       ←  playwright-test-author-ui
+                                  ↓
+                                  test-code-reviewer  (gates the PR)
+                                  ↓
+                                  run-analyzer + coverage-gap-analyzer + flaky-triage
+                                  ↓
+                                  release-report-composer
+```
+
+## Sprint roadmap (recommended)
+
+- **Sprint 0** — Foundation: bootstrap, config-and-secrets, fixture-architect, factory-builder, api-client-from-openapi, hooks, CLAUDE.md, tests-config.json.
+- **Sprint 1** — Authoring: requirements-to-test-design, gherkin-author, playwright-test-author-ui/-api, slash commands `/test-new`, `/factory`, `/spec-sync`.
+- **Sprint 2** — Quality gates: test-code-reviewer, debug-conductor, flaky-triage, slash commands `/test-fix`, `/test-review`, `/flake-hunt`.
+- **Sprint 3** — Analytics: run-analyzer, coverage-gap-analyzer, release-report-composer; subagent `contract-drift-watch`; GitHub MCP integration.
+- **Sprint 4** — Advanced: Playwright MCP for exploratory loops, self-healing pipeline (flaky-detective → GitHub issue), custom Allure reporter.
+
+## Customising
+
+- **Different layout?** Edit `tests-config.json`. All skills read from it.
+- **GraphQL or gRPC?** Add a parallel skill (e.g. `asyncapi-client-builder`) following the same template structure. Reuse factory and fixture skills.
+- **Different model preferences?** Each skill respects the host Claude Code model setting; subagents pin their model in frontmatter.
+
+## Anti-patterns this kit prevents
+
+- `page.waitForTimeout(N)` and other hard waits → blocked by `lint-ui-spec.ts`.
+- CSS/XPath selectors in specs → blocked by `lint-ui-spec.ts` and `test-code-reviewer`.
+- Hardcoded URLs/secrets → blocked by `scan-hardcoded.sh` and the path hook.
+- Inline data literals as test data → factory-builder rewrites to `factory.build()`.
+- Page object instantiated inside a test → fixture-architect lifts it.
+- Spec drift between API and tests → `contract-diff.ts` blocks the PR.
+
+See `.claude/skills/test-code-reviewer/references/aqa-anti-patterns.md` for the full catalogue.
+
+## Caveats
+
+- The validators are heuristic, not full AST analysis. They favour false positives over false negatives.
+- Hooks execute shell with the user's privileges. Audit them before sharing across teams.
+- Playwright MCP is intentionally NOT wired in by default — the CLI + skills loop is far cheaper for repeated automation tasks. Wire MCP for exploratory or self-healing flows separately.
+- The skill descriptions are tuned for Claude Code; transferring to Claude.ai requires re-checking trigger phrases.
+
+## License
+
+MIT.

.claude/STARTER.md

@@ -0,0 +1,102 @@
+# Starter — first 30 minutes after init
+
+You just ran `init.sh`. The repo is now greenfield-ready: scaffolded, dependencies installed, hooks set, kit copied. Here is the shortest path to your first green test.
+
+## 1. Sanity check (1 min)
+
+```bash
+npm run verify
+```
+
+You should see all green or warnings only. Failures are blocking — fix them before moving on.
+
+## 2. Open in Claude Code (1 min)
+
+```bash
+claude
+```
+
+Skills auto-discover from `.claude/skills/`. The first message Claude Code sees is `CLAUDE.md`.
+
+## 3. Scaffold the test framework folders (5 min)
+
+In Claude Code:
+
+> Scaffold the test framework folders.
+
+This triggers `playwright-framework-bootstrap`. It will create:
+
+- `tests/{pages,components,fixtures,factories,api,specs,data,infra}/`
+- `tests/pages/BasePage.ts`
+- `playwright.config.ts`
+- Path aliases (`@pages/*`, `@api/*`, …) wired into `tsconfig.json`.
+
+If the agent asks confirmation, say yes.
+
+## 4. Configure environment (3 min)
+
+```bash
+cp .env.example .env.local
+```
+
+Edit `.env.local` and set at least:
+
+- `BASE_URL` — your application URL (or `http://localhost:3000`).
+- `TEST_USER_EMAIL`, `TEST_USER_PASSWORD` — a test user that can log in.
+
+Do not commit `.env.local`. It is gitignored.
+
+## 5. Write your first test (10 min)
+
+In Claude Code:
+
+> Design and write a smoke test that verifies the homepage loads and shows the header.
+
+This pipeline triggers:
+
+1. `requirements-to-test-design` — quick design doc.
+2. `playwright-test-author-ui` — actual spec.
+
+Run it:
+
+```bash
+npm run test:smoke
+```
+
+If green, commit:
+
+```bash
+git add -A && git commit -m "test: smoke for homepage"
+```
+
+The pre-commit hook will lint and typecheck staged files.
+
+## 6. When you have your first API spec (later)
+
+Create `specs/openapi.yaml` with at least one endpoint, then:
+
+```bash
+# Tell Claude Code:  Sync the OpenAPI spec.
+# Or run manually:
+node -e "const fs=require('fs');const c=JSON.parse(fs.readFileSync('tests-config.json'));c.openapi.enabled=true;fs.writeFileSync('tests-config.json',JSON.stringify(c,null,2)+'\n')"
+npm run spec:sync
+```
+
+This generates types in `tests/api/generated/` and unlocks `playwright-test-author-api` and the `contract-drift-watch` subagent.
+
+## Common issues
+
+| Symptom                                          | Fix                                                                                                |
+| ------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
+| `npx playwright install` fails                   | Run `sudo npx playwright install-deps` (Linux) or skip with `--no-deps`.                           |
+| `husky install` fails                            | You need a git repo. `init.sh` runs `git init`, but if you skipped, do it manually.                |
+| `tsc` complains about missing `@playwright/test` | `npm install` did not finish. Re-run.                                                              |
+| Hook says "tsc-files: command not found"         | `npm install` did not finish. Hooks soft-fail (warning only) — fix when convenient.                |
+| Skill fires when you don't expect it             | Check the skill's `description` field. Tighten "Do NOT use when..." block or add a CLAUDE.md note. |
+
+## Next reading
+
+- `CLAUDE.md` — project conventions enforced by skills.
+- `SDET_KIT_README.md` — full kit reference (15 skills, 3 subagents, 9 commands).
+- `.claude/skills/playwright-framework-bootstrap/references/folder-rationale.md` — why the layout looks like this.
+- `docs/greenfield-checklist.md` — sprint-by-sprint adoption plan.

.claude/agents/contract-drift-watch.md

@@ -0,0 +1,22 @@
+---
+name: contract-drift-watch
+description: MUST BE USED whenever specs/openapi.yaml is modified or before a release. Runs api-client-from-openapi's drift checker, emits CONTRACT_DRIFT.md, and proposes test updates for breaking changes. Read-only by design — never edits production code.
+tools: Read, Glob, Grep, Bash
+model: haiku
+---
+
+You are a contract drift auditor. You are deliberately running on Haiku to keep cost low — most of your work is parsing diffs, not reasoning.
+
+Operating rules:
+
+- Re-run `scripts/gen-openapi-fetch.sh` and `scripts/contract-diff.ts` from the `api-client-from-openapi` skill.
+- Classify each diff as breaking / non-breaking per `references/contract-drift-policy.md`.
+- For each breaking change, locate affected tests via `grep -R '@endpoint:'` and list them as patch candidates.
+- Do NOT edit any test or generated file. Suggest only.
+- If no `tests/api/generated/.snapshot/schema.previous.d.ts` exists, abort with a message asking the human to commit a baseline.
+
+Your final message MUST end with:
+
+```
+ARTIFACT: CONTRACT_DRIFT.md
+```

.claude/agents/flaky-detective.md

@@ -0,0 +1,23 @@
+---
+name: flaky-detective
+description: Use PROACTIVELY after any test run with retries > 0 or failures. Performs flake triage in isolation, classifies root causes, and emits FLAKE_REPORT.md plus suggested patch diffs without touching unrelated files.
+tools: Read, Glob, Grep, Bash
+model: sonnet
+---
+
+You are a flake detective. Your single job is to diagnose intermittent test failures and propose minimal, targeted patches.
+
+Operating rules:
+
+- Use the `flaky-triage` skill exclusively.
+- Never write new test logic; you only diagnose and propose patches.
+- Output is ALWAYS `FLAKE_REPORT.md` in the repo root and a `Suggested patches` section in the report containing unified diffs.
+- For each flaky test you classify into exactly one bucket from `references/flake-taxonomy.md`. If you genuinely cannot, classify as "haunted" with quarantine recommendation and an issue tracker stub.
+- You do NOT modify files. The orchestrator (or human) applies patches.
+- You do NOT speculate. If the trace is missing, you say so and request a re-run with `--trace=on --repeat-each=20`.
+
+Your final message MUST end with:
+
+```
+ARTIFACT: FLAKE_REPORT.md
+```

.claude/agents/test-design-agent.md

@@ -0,0 +1,23 @@
+---
+name: test-design-agent
+description: MUST BE USED for transforming a user story or PRD into a structured test design report (equivalence classes, boundary values, decision tables, risk-prioritised). Operates in isolated context to avoid polluting the main coding session.
+tools: Read, Write, Glob, Grep, WebFetch
+model: sonnet
+---
+
+You are a Senior Test Architect. You produce ONE artefact per invocation: `docs/test-design/<slug>.md` following the `requirements-to-test-design` skill template (see `references/design-template.md`).
+
+Operating rules:
+
+- You leverage the `requirements-to-test-design` skill exclusively. If the user request is not a test design ask, report back that this is the wrong agent.
+- You ask at most 3 clarifying questions, only when the AC are genuinely ambiguous. Otherwise proceed with explicit assumptions.
+- You do not write code. You do not write Gherkin. You do not edit tests. The next step in the pipeline is `gherkin-test-case-author`.
+- You explicitly mark "Out of scope" sections to prevent downstream skills from over-reaching.
+- You sort test ideas by `risk-heuristic.ts` priority (P0 → P2).
+- You output the file path of the artefact at the end of your response so the orchestrator can hand off cleanly.
+
+Your final message MUST end with:
+
+```
+ARTIFACT: docs/test-design/<slug>.md
+```

.claude/commands/coverage.md

@@ -0,0 +1,11 @@
+---
+description: Generate coverage gap report (endpoints + AC + pages)
+allowed-tools: Read, Bash, Glob, Grep, Write
+model: sonnet
+---
+
+# Pipeline
+
+1. Use the `coverage-gap-analyzer` skill.
+2. Run `scripts/analyze-coverage.ts`.
+3. Read `COVERAGE_GAPS.md`. Highlight P0 gaps in your message.

.claude/commands/factory.md

@@ -0,0 +1,14 @@
+---
+description: Generate a Fishery-based factory for an entity
+argument-hint: <EntityName>
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+model: sonnet
+---
+
+# Pipeline
+
+1. Use the `test-data-factory-builder` skill.
+2. Read the type for `$ARGUMENTS` from `tests/api/generated/schema.d.ts` or fall back to a domain model.
+3. Generate `tests/factories/$ARGUMENTS.factory.ts` from `references/factory.template.ts`.
+4. Update `tests/factories/index.ts` aggregator.
+5. Run `scripts/factory-rules.ts`. Fix until exit 0.

.claude/commands/flake-hunt.md

@@ -0,0 +1,17 @@
+---
+description: Detect flakes by repeating the suite and triaging
+argument-hint: <repeat-count, default 10>
+allowed-tools: Read, Bash, Glob, Grep
+model: sonnet
+---
+
+# Context
+
+- Repeat count: $ARGUMENTS (default 10)
+
+# Pipeline
+
+1. Run: `mkdir -p runs && for i in $(seq 1 ${ARGUMENTS:-10}); do npx playwright test --reporter=json --output=runs/$i.json || true; done`.
+2. Hand off to the `flaky-detective` subagent.
+3. The subagent runs `flake-rate.ts ./runs > FLAKE_REPORT.md` and classifies.
+4. Output the report path.

.claude/commands/page.md

@@ -0,0 +1,13 @@
+---
+description: Scaffold a new page object class
+argument-hint: <PageName>
+allowed-tools: Read, Write, Edit, Glob, Grep
+model: sonnet
+---
+
+# Pipeline
+
+1. Use the `playwright-framework-bootstrap` skill (page-object generator portion).
+2. Generate `tests/pages/$ARGUMENTS.ts` extending `BasePage`. No `expect`, no hardcoded URL, locators-only by default.
+3. Update `tests/pages/index.ts` aggregator.
+4. Run `lint-page-object.ts` from `test-code-reviewer`. Fix until exit 0.

.claude/commands/release-report.md

@@ -0,0 +1,13 @@
+---
+description: Compose release readiness report (verdict + summary)
+argument-hint: <version e.g. v1.42.0>
+allowed-tools: Read, Bash, Glob, Grep, Write
+model: sonnet
+---
+
+# Pipeline
+
+1. Use the `release-report-composer` skill.
+2. Read `RUN_SUMMARY.md`, `COVERAGE_GAPS.md`, `FLAKE_REPORT.md`, `CONTRACT_DRIFT.md` (whichever exist).
+3. Run `scripts/compose-release.ts $ARGUMENTS`.
+4. Display the verdict and the path to the report.

.claude/commands/spec-sync.md

@@ -0,0 +1,19 @@
+---
+description: Sync OpenAPI spec → typed clients → drift report
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+model: sonnet
+---
+
+# Context
+
+- Spec: @specs/openapi.yaml
+- Generated: @tests/api/generated/
+
+# Pipeline
+
+1. Use the `api-client-from-openapi` skill.
+2. Validate spec via `scripts/validate-spec.sh`.
+3. Regenerate types via `scripts/gen-openapi-fetch.sh`.
+4. Run `scripts/contract-diff.ts`. If breaking, write `CONTRACT_DRIFT.md` and stop.
+5. Update affected client wrappers in `tests/api/clients/`.
+6. Suggest test updates for breaking changes (do not auto-edit).