CLAUDE.md — Test Automation Scaffold Constitution

This file is always loaded. It is the constitution (hard rules), the workflow, and the index of skills. The deep rules live in .claude/skills/<name>/SKILL.md; this file routes you there. When this file and a skill disagree, the skill wins — and that's a bug to fix here.

You are working in an AI-native Playwright + TypeScript scaffold that distills hard-won lessons from real-world Playwright suites. It tests UI (functional + e2e) and API, with security coverage, using the Page Object Model, fixture-based DI, deterministic waits, and runtime-validated schemas.

0. First contact — is this scaffold even configured?

If PROJECT.md does NOT exist in the repo root, this is a fresh clone. Run the bootstrap skill first — it interviews the user about the target app, applies a profile (generic / controlled / salesforce / api-only), prunes what isn't needed, and writes PROJECT.md. Do not generate tests against an unconfigured scaffold.

If PROJECT.md exists, read it — it records the target's profile, auth model, locator strategy, and API-contract source. Those decisions override the generic defaults below.

If the recorded profile is salesforce, also load the salesforce skill before doing anything else Salesforce-specific — the pack (§7) replaces several generic defaults outright.

1. The Constitution (hard stops — these are REFUSALS, not warnings)

Never ship, and refuse to generate, any of the following:

A hook (ESLint) enforces #1, #2, #5. The rest are on you.

Rule #15 is the Salesforce-specific sharpening of #4, and it earns its own row because Salesforce field API names are org state, not application source. An admin can add, rename, or delete a field with no deploy and no commit, so there is no repository to read them from — describe is the only source of truth. Margin__c existing in someone else's org proves nothing about yours.

2. The conversation contract — audit-then-edit

Every non-trivial task runs the same loop:

1. State — the user states the goal in plain language.
2. Route + explore — load the matching skill (§4); gather evidence (playwright-cli / OpenAPI / ls). Missing a primary input → ASK, do not guess.
3. Propose — emit a scope block: what changes, in which files, why, trade-offs, and a confidence 1–10. Confidence < 5 means exploration is incomplete → do NOT propose; go back and ASK.
4. Approve — wait for the user. No code before approval (except trivial Direct-Mode fixes).
5. Apply — make the edits per the leaf skill; re-check every Constitution rule.
6. Verify — lint + run the affected tests (never the whole suite). Red → debugging.
7. Report + commit — list files changed; ask before committing.

Direct Mode: one-line fixes / typos may skip the proposal — but still verify the premise is real first. The user can opt into Direct Mode for a session by saying "just do it."

3. The architecture in one screen

config/        URLs + runtime settings (process.env). NEVER paths/messages.
enums/         endpoint PATHS, UI ROUTES, UI MESSAGES (as const). Verified, never guessed.
env/           .env.<environment> files (gitignored; *.example tracked).
helpers/       util/network.ts (deterministic waits), util/forms.ts, auth/auth.setup.ts
pages/         base.page.ts + *.page.ts + components/  (locators-on-top, actions only)
test-data/     factories/ (Faker, dynamic happy-path) + static/ (as const, invalid/boundary)
fixtures/      api/ (ApiRequest + Zod schemas) + pom/ + helper/ + test-options.ts (single import)
tests/         api/ (backend = SUT)  functional/ (one screen)  e2e/ (full journey)

Projects, not just folders (playwright.config.ts): api (no browser), setup (auth state), functional, e2e. The SEAM is what is the system under test — not which tool makes the call. API-as-setup is a fixture inside UI tests; API-as-SUT is the api project.

Every spec imports from one place: import { test, expect } from '<...>/fixtures/test-options';

4. Routing — describe the work, the skill loads itself

Salesforce (only when PROJECT.md profile is salesforce)

These override the generic skills above for anything Salesforce-specific. salesforce is the hub — load it first if you're unsure which of the six applies.

If nothing matches, default to common-tasks or ASK. Naming a skill is a fallback for when the wrong one loaded.

5. When NOT to use this scaffold (be honest)

• Large, pure API suite where the API is the SUT and the backend is non-TypeScript → recommend a backend-native framework instead (pytest + Pydantic, RestAssured, or Schemathesis/Dredd for contract testing from OpenAPI). Playwright's API mode is overkill there. See api-testing Phase 1.
• Load / performance testing → k6 or Gatling, not this.
• This scaffold's API project is for API-as-setup and same-stack, modest API-as-SUT suites that benefit from sharing types/fixtures with the UI tests.

6. Profiles (set by bootstrap, recorded in PROJECT.md)

The selectors and wait-strategy skills read the active profile from PROJECT.md.

7. The Salesforce pack

salesforce is not just a locator preference — it ships its own skills (§4) and its own code:

config/salesforce.config.ts           org URLs, API version pin, admin + subject personas
enums/salesforce/                     sObject names, ui-api paths, /lightning/* routes
helpers/salesforce/                   auth · describe · soql · lightning waits · contract · permissions
fixtures/salesforce/                  adminOrg + org + orgAs · persona contexts · metadata schemas
pages/salesforce/                     Lightning component objects (combobox, datatable, modal, toast…)
test-data/salesforce/personas.ts      the persona lattice (9 personas, one axis apart)
test-data/salesforce/contracts/       the contract AS DATA — shape + CRUD + FLS per persona
tests/salesforce/contract/            org project: drift · field shape · permissions   (no browser)
tests/salesforce/ui/                  salesforce project: behaviour as the subject persona
scripts/generate-sobject-schemas.ts   describe → Zod          (run at bootstrap, per org)
scripts/generate-visible-fields.ts    per-persona visible-field sets  (leak detection)

Four things differ from every other profile, and they are the whole reason the pack exists:

1. Two identities, not one. adminOrg (System Admin) ARRANGES and TEARS DOWN; the subject persona ACTS and ASSERTS. Arrange as a restricted user → teardown silently cannot delete → data leaks. Assert as an admin → Modify All Data bypasses sharing and FLS → the test passes with the permission model completely broken. UI projects default to standardUser, never admin.
2. Auth is org auth, not a login form. The JWT bearer flow mints a session without touching the login UI — which is also how you legitimately get past mandatory MFA. Never automate an MFA challenge.
3. The API contract is org metadata. Salesforce ships no OpenAPI. describe is the contract, and it changes the moment an admin clicks Save — so drift detection is a first-class test type (@contract).
4. Every assertion has a "for whom". The permission model is the product. Personas form a lattice (each differs on exactly one axis), and absence assertions need a positive control that is not an admin — an admin passes via Modify All Data even with the grant broken.

Layering is not optional here (docs/salesforce/TEST-ARCHITECTURE.md):

Field metadata and permission matrices in the UI are a wrong-layer error: ~100× the cost, and UI absence is ambiguous (FLS? page layout? record type?) where the API tells you which.

If the profile is NOT salesforce, bootstrap prunes all of the above.