diff --git a/.claude/commands/verify-service.md b/.claude/commands/verify-service.md new file mode 100644 index 0000000..7d8f4e2 --- /dev/null +++ b/.claude/commands/verify-service.md @@ -0,0 +1,65 @@ +Exploratory service-UI verification (ADR-008 Level 4 / ADR-017) + +Drive a browser against a **staging** deploy of a service, exercise its +`roles//VERIFY.md` acceptance journeys plus free exploration, and write a +tracked report. Argument: the service/role name (e.g. `/verify-service photoprism`). + +## Prerequisites (this is forward-looking — ADR-017 dependencies) + +This skill cannot run until all of these exist; if any is missing, say so and stop — +do not improvise around it: + +- `ubongo` with the `playwright` Claude Code plugin (browser automation tools). +- A **staging** deploy of the target service (ADR-008 Level 2). +- Authentik (staging) for test-user provisioning + SSO. +- `roles//VERIFY.md` present. + +## Process + +### Phase 0 — safety gate (staging only) + +Confirm the target resolves to the **staging** environment/inventory, never production. +If you cannot prove it is staging, **stop** — exploratory clicking is destructive +(ADR-002). State why you stopped. + +### Phase 1 — read intent + +Read `roles//VERIFY.md`: the Critical user journeys, What good looks like, Not +browser-verifiable, and Test data sections. + +### Phase 2 — test user + +Provision (reuse-or-create) a test user in the staging Authentik `test` group, with +ephemeral credentials held only for this run. Never use a real/production account. + +### Phase 3 — drive the browser + +Via the `playwright` plugin, on `ubongo`: open the service's staging URL (resolved via +boma DNS), authenticate through the real Traefik + Authentik SSO flow, then execute each +`VERIFY.md` journey — judging pass/fail and screenshotting key states — and free-explore +for anything obviously broken. Save screenshots to the git-ignored `.verify-runs/` +working dir; avoid capturing credential screens. + +### Phase 4 — write the report + +Save to `docs/testing/reviews/YYYY-MM-DD-.md` and overwrite +`docs/testing/reviews/latest.md`. Structure: + +- **One-line verdict** — e.g. "5/5 journeys passed; one manual check pending". +- **Run metadata** — date, service, staging env, test user, reviewed commit SHA. +- **Per-journey result** — pass/fail against `VERIFY.md`, with the evidence (linked + screenshot path) and any observation. +- **Free-exploration findings** — anything noticed beyond the listed journeys. +- **Manual-test checklist** — the "Not browser-verifiable" items plus anything Claude + couldn't do: numbered steps, expected result, and why it was handed off. + +### Phase 5 — clean up + commit + +Offer to clean up the `test`-group user (or note that the staging rebuild will). +Commit the report markdown per CLAUDE.md git conventions. **Do not** commit +`.verify-runs/` (git-ignored). + +## Notes + +- Reports (markdown) are committed; screenshots stay local on `ubongo` in `.verify-runs/`. +- Exploratory and interactive — this is not a deterministic CI gate.