@tamsensedev/runner 0.0.0-stage → 0.1.0

package/library/skills/task-interview/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: task-interview
+description: Use when a task or spec leaves a decision open and you are tempted to ask: research first, ask only questions that pass three tests, settle corner cases as assumptions with a reason, and either ask in short rounds with a recommended answer first (when a person can answer, or on the TAMsense spec step with submit_questions) or decide with the recommendation and report it (on any other unattended TAMsense step).
+---
+
+# Task interview
+
+Finding facts is your job. Decisions about intent belong to the person who owns the task. Most "questions" are facts you have not looked up yet, or corners with a safe default. Ask only what is left after both.
+
+## 1. Research before any question
+
+Look before you ask: the task, the spec and its decisions, the project's rules (`project-orientation`), the code around the change, existing tests, data you can read locally.
+
+- Never ask where something is, which component to use or how the code works today. Look it up.
+- If the answer has several plausible candidates in the code, the question becomes "which of these", with the real paths as options.
+- When a person corrects a fact, check it in the code before you rely on it.
+
+## 2. Sweep the corners instead of asking about them
+
+Most defects are corners: one part of the change meeting one unusual condition. More questions do not find them; a sweep does. For each part of the change, go through:
+
+- empty or missing data, one item, very many items;
+- invalid or too long input, first use and repeated use;
+- missing access, a signed-out user, two people editing at once;
+- a failed or slow external call, old stored data, existing users;
+- phone width; numbers and money (zero, rounding, unknown versus zero); dates and time zones.
+
+Settle every condition that applies in one of three ways: an assumption with its reason (a safe default exists), out of scope, or a question (only if it passes the test below).
+
+## 3. The question test
+
+Ask a question only if all three hold:
+
+1. **Not discoverable.** The code, the data, the spec and the project's rules do not answer it.
+2. **It changes the result.** The two most likely answers lead to different changes or different acceptance criteria.
+3. **No safe default.** Or a wrong default is costly: lost or wrong data, money, permissions and privacy, a public API or stored format, a migration that is hard to undo, or visible text and behaviour the owner cares about.
+
+Rank the questions that pass by impact times uncertainty. On a tie: scope first, then data and security, then what the user sees, then technical details. Stop when you can predict the answer to the next questions; record those as assumptions.
+
+## 4. How to write a question
+
+```
+id: empty_state
+Question: What should the task list show when a board has no tasks?
+Why it matters: It decides the empty-state text and whether a "Create a task" button is added.
+Options:
+  1. A short hint (recommended): the page says "No tasks yet", nothing else changes.
+  2. A hint and a button: the page also offers "Create a task", which needs a new route.
+```
+
+- One plain sentence; the owner may not be a developer.
+- A "why it matters" line.
+- 2 to 4 mutually exclusive options, the recommended one first and marked; each option says what happens if it is chosen.
+- Several picks only when the options are additive.
+- Zero questions is a good result.
+
+## 5. Rounds
+
+- **Round 1:** at most 4 questions, ideally 2 or 3. Ask only questions that do not depend on another open question of the same round; note dependent decisions for later.
+- **Round 2 (optional):** at most 3 more, only if an answer was vague ("not sure", "depends"), contradicts another answer or the code, or unlocked a dependent decision.
+- No third round. About 6 questions in total. Whatever is left becomes an assumption.
+- An unanswered question takes the recommended option and is recorded as an assumption.
+
+## 6. When nobody can answer (a TAMsense run)
+
+On the TAMsense spec step the owner answers after the run: hand the brief and the round's questions in with `submit_questions` and finish. The owner clicks through them on the task page, and the next round or the spec continues from your brief.
+
+On any other step of a TAMsense run nobody answers, so never stop to wait:
+
+1. Take the recommended option and keep working.
+2. If a wrong guess would be costly and hard to undo (deleting data, a destructive migration, money, permissions), build the safe part only and leave the risky part out.
+3. In the report, list each decision as the question, the options, what you chose and why, so the owner can correct it in one reply. If the board lets you hand the task back to the spec step and the open decision blocks the work, hand it back with these questions in the note.
+
+## Common mistakes
+
+| Thought | What to do instead |
+|---|---|
+| "I'll ask which file handles this" | Search the code; ask only to choose between real candidates. |
+| "Better ask about the empty state too" | If a safe default exists, write it as an assumption with the reason. |
+| "Let me ask everything at once" | One round of independent questions; dependent ones wait. |
+| "Whatever you think is best" came back | That is a delegation: take your recommendation and say so. |
+| "I'll wait for an answer" | In a run nobody answers: decide, record, report. |
+
+Sources: adapted from openai/codex Plan Mode template and request_user_input tool (Apache-2.0, commit 430a167), github/spec-kit clarify and specify commands (MIT, commit c06e670), mattpocock/skills grilling (MIT, commit 5beb35b), awslabs/aidlc-workflows corner checklist and requirements analysis (MIT-0, commit 95d2b44), addyosmani/agent-skills interview-me (MIT, commit aeac41d) and humanlayer/humanlayer create_plan (Apache-2.0, commit 99abe67). Changed: merged into one question policy, rewritten for batched rounds and unattended runs.

package/library/skills/test-driven-development/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: test-driven-development
+description: Use when adding behaviour or fixing a bug in a project, before writing the implementation: write a test in the project's own framework, watch it fail for the right reason, make it pass with minimal code, then run the suite. Covers what to do when the project has no test setup.
+---
+
+# Test-driven development
+
+If you never saw a test fail, you do not know that it tests anything. Write the test first, watch it fail, then write the code.
+
+## Step 0: Find the project's test setup
+
+Before anything else (see `project-orientation`):
+
+- Which framework, where tests live, how they are named, which helpers and fixtures exist, and the exact command to run one file and the whole suite.
+- Copy the shape of a neighbouring test: imports, setup, naming, assertion style.
+
+**If the project has no test setup at all:** do not add a test framework, new dependencies or a test folder structure the maintainers did not choose. Verify the change another way that you can show evidence for (type check, build, running the code with a fixture input, a throwaway script outside the repository) and write in the report: "No test setup in this repository; verified by: ...".
+
+**If tests exist but not for this area:** add the test in the existing framework, next to the code, following the closest existing example.
+
+## When to use it, and when not
+
+Use it for new behaviour, bug fixes, and behaviour changes in code that has a reasonable seam to test at.
+
+Usually skip it, and say so in the report, for: configuration-only changes, generated code, pure markup or styling with no logic, copy changes, dependency bumps, and code with no seam that can show the behaviour (then explain the gap rather than writing a hollow test). Exploratory spikes are fine, but throw the spike away or start the test-first cycle from it before you commit.
+
+## The cycle
+
+### Red: write one failing test
+
+One behaviour per test, a name that reads as a sentence about it, real code rather than mocks where that is cheap.
+
+```ts
+test('retries a failing call up to 3 times, then succeeds', async () => {
+  let attempts = 0
+  const call = async () => {
+    attempts++
+    if (attempts < 3) throw new Error('fail')
+    return 'ok'
+  }
+
+  await expect(retry(call)).resolves.toBe('ok')
+  expect(attempts).toBe(3)
+})
+```
+
+Before writing the body, name the production change that would make this test fail. If you cannot name one, the test is not testing behaviour. More in [references/writing-good-tests.md](references/writing-good-tests.md).
+
+### Verify red: run it and read the failure
+
+```
+pnpm vitest run src/retry.test.ts
+```
+
+- It must **fail**, not error. A typo, a missing import or a syntax error is not a red test.
+- The failure message must be the one you expect ("expected 'ok', received undefined").
+- It must fail because the behaviour is missing, not because of setup.
+- If it passes immediately, it tests existing behaviour or nothing at all: fix the test.
+
+### Green: the minimal code that passes
+
+Write the simplest code that makes this test pass. No extra options, no handling for cases no test asks for yet. Do not change the test to fit the code.
+
+### Verify green
+
+Run the test again, then the tests around it, then the project's full suite (or the widest suite that runs in reasonable time). A green file is not a green suite. Output should be clean: no new warnings or errors in the log.
+
+Any failure in the wider run goes in the report by name, including ones you did not cause (check against the baseline from `project-orientation`).
+
+### Refactor
+
+Only on green: remove duplication, improve names, extract helpers. Re-run after each change. Do not add behaviour while refactoring.
+
+Repeat for the next behaviour: one test, one minimal implementation, at a time. Do not write the whole test file first.
+
+## If you wrote the code first
+
+It happens: an exploration turned into the fix, or the change was made before this skill was loaded. Do not pretend. Prove the test can fail:
+
+1. Save your change to the production file: `git diff -- path/to/file > "$TMPDIR/fix.patch"` (any temp location outside the repository).
+2. Restore the original: `git checkout -- path/to/file`.
+3. Run the new test and confirm it fails for the right reason.
+4. Re-apply: `git apply "$TMPDIR/fix.patch"`, check with `git diff --stat` that the change is back, and run the test again to see it pass.
+
+If the test passes without your change, it does not cover the change. Fix the test.
+
+## Bug fixes
+
+1. Write a test that reproduces the reported bug exactly (the input, the wrong output). For a hard bug, follow `systematic-debugging` first.
+2. Watch it fail with the symptom from the report.
+3. Fix the cause. Watch it pass.
+4. Run the suite.
+
+## Keep tests deterministic
+
+Fixed dates and time zones, seeded random data, no dependence on test order, no real network, temp folders per test. Wait for conditions, not for time (see `systematic-debugging`, flaky tests reference).
+
+## Common rationalisations
+
+| Excuse | Reality |
+|---|---|
+| "Too simple to test" | Simple code breaks too; the test takes a minute. |
+| "I'll add tests after" | Tests written after pass immediately and prove nothing; they check what you built, not what was asked. |
+| "I already tried it by hand" | A manual try leaves no record and is not repeated on the next change. |
+| "The existing code has no tests" | Add tests for the part you change, in the project's framework. |
+| "Hard to test" | Often a sign the design is hard to use. Find a better seam, or report the gap. |
+| "I need to mock everything" | The code is too coupled, or the test is at the wrong level. Test higher up with real collaborators. |
+
+## Done when
+
+- [ ] Each new behaviour and each fixed bug has a test that you saw fail for the right reason, then pass.
+- [ ] Tests assert real behaviour through the public surface, with expected values written out by hand.
+- [ ] The full relevant suite passes, or failures are listed with their cause (yours fixed, pre-existing reported).
+- [ ] The report says which tests were added, or why none were (no test setup, no seam, not applicable).
+
+Sources: obra/superpowers (MIT, commit bb92a77) test-driven-development. Changed: rewritten for unattended work in existing repositories.

package/library/skills/test-driven-development/references/writing-good-tests.md

@@ -0,0 +1,85 @@
+# Writing good tests
+
+Read this when writing or changing a test, adding a mock, or adding a test helper.
+
+A test exists to catch a specific break. Two rules carry most of the weight:
+
+1. Every test names the break it catches.
+2. Every test exercises the real thing.
+
+## Rule 1: name the break
+
+Before writing the body, answer: which production change would make this test fail, and is that change a bug or a deliberate decision? A good test catches a wrong branch, a missing side effect, a wrong argument, a boundary case or a broken contract.
+
+**Derive expected values independently.** Use literals and hand-checked fixtures. An expected value computed by the code under test (or its helpers) passes whatever the code does.
+
+```ts
+// Bad: the same builder produces both sides, so it is always equal
+const expected = buildSearchQuery({ tag: 'urgent' })
+expect(buildSearchQuery({ tag: 'urgent' })).toBe(expected)
+
+// Bad: recomputes the answer the way the code does
+expect(add(a, b)).toBe(a + b)
+
+// Good: written out by hand
+expect(buildSearchQuery({ tag: 'urgent' })).toBe('tag:"urgent"')
+```
+
+Table-driven tests with literal expected values are a good shape for many cases.
+
+**No change detectors.** A test that only fails on intentional decisions (a constant's value, exact message wording, private structure) fires on every redesign and sleeps through real bugs. Test the behaviour that depends on the decision: not `expect(MAX_RETRIES).toBe(5)` but "a failing call is retried 5 times and a sixth attempt never happens".
+
+**Behaviour, not source text.** Asserting that a file contains a certain line proves only that the file is the file. Run the script, config or template against a controlled input and check the output, side effect or exit code.
+
+**Your code, not the framework.** Test the contract your code makes at its boundary: the route you register, the query you build, the payload you send. Do not test that the router calls a registered handler; that is the framework's job. Constructors, getters and simple pass-throughs earn a test only when they validate, normalise, default, derive or cause a side effect.
+
+**Through the public surface.** Test via the function, endpoint, component or command that callers use. A test that breaks when you refactor internals without changing behaviour is coupled to implementation. Avoid checking results through a side channel (querying the database directly) when the public interface can show them.
+
+## Rule 2: exercise the real thing
+
+**Never assert on a mock.** An assertion that a mock was rendered or exists passes when the mock is there and says nothing about the component.
+
+```ts
+// Bad: tests the mock
+expect(screen.getByTestId('sidebar-mock')).toBeInTheDocument()
+
+// Good: tests the real behaviour
+expect(screen.getByRole('navigation')).toBeInTheDocument()
+```
+
+**Mock at the right level.** Before replacing a method, learn all its side effects. Mock the slow or external part below it (network, paid API, clock, email) and keep what the test depends on real. A mock that swallows a write that the code later reads makes the test pass while the real thing breaks.
+
+**Make doubles specific.** When arguments, call counts or order are part of the contract, assert them. Give success, error and malformed responses their own fixtures, so the wrong branch cannot satisfy the test.
+
+**Mirror real data completely.** Fake responses should have the full structure of the real one, not only the fields this test reads. Partial fakes hide failures in code that reads the other fields.
+
+**Production code carries production methods only.** Cleanup or reset methods that only tests call belong in test utilities, not on the production class.
+
+**Prefer real components over elaborate mocks.** When mock setup is longer than the test logic, or the test breaks whenever the mock changes, switch to a test with real collaborators (an in-memory database, the real module, the project's existing test server).
+
+## The mutation check
+
+Before finishing, imagine small breaks in the production code. At least one test should fail for each realistic one:
+
+- A wrong constant or argument.
+- A wrong branch taken.
+- A missing state change or side effect.
+- An empty or default return value.
+- Missing validation for zero, empty, null, unauthorised or malformed input.
+
+If nothing fails for a realistic mutation, that behaviour is unprotected. For an important change you can make the mutation for real: invert one condition, run the tests, confirm a failure, restore the line, and confirm with `git diff` that it is restored.
+
+## Warning signs
+
+- Setup and assertion share the same object, so they are equal by construction.
+- The test can only fail by crashing or by a missing selector.
+- The test fails on every intentional change but never on accidental breakage.
+- Expected values are hidden behind loops, builders or helpers.
+- The test greps source text.
+- The test exists for coverage and checks no outcome.
+- An assertion checks a `*-mock` test id, or fails if you remove the mock.
+- A method is called only from test files.
+- Mock setup is more than half the test, or you cannot say why the mock is needed.
+- Writing all the tests for a feature before any implementation: tests for imagined behaviour test the shape of things, not what users see. Go one test at a time.
+
+Sources: obra/superpowers (MIT, commit bb92a77) writing-good-tests and mattpocock/skills (MIT, commit 5beb35b) tdd. Changed: shortened and merged.

package/library/skills/ui-testing/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: ui-testing
+description: Use when a change affects what users see or click in a web app and should be checked in a real browser, when writing or fixing Playwright or Cypress tests, or when a test step must verify UI behaviour. Runs the project's E2E suite or a headless check from a temp folder and reports screenshots and errors as evidence.
+---
+
+# UI testing in a headless browser
+
+Reading the code tells you what should happen; a browser shows what does. This skill gets the app running, drives the changed flows headless, and turns what it saw into evidence for the report. Nobody watches the run, so every step must finish on its own and leave the machine as it was.
+
+The project's own setup wins: its E2E framework, config, fixtures, page objects, test data, auth helpers and scripts. Use them before anything from here.
+
+## Hard rules
+
+1. **Headless only.** Never open a window: no `--headed`, `--ui`, `--debug`, `show-report`, `show-trace`, `cypress open`, `PWDEBUG`. Playwright's HTML reporter opens a browser on failure when not in CI, so run with `--reporter=line` and `PW_TEST_HTML_REPORT_OPEN=never`. Set `BROWSER=none` when starting dev servers so they do not open one either.
+2. **No new dependencies.** Do not add packages to the repository and do not download browsers (`playwright install`, `npx some-tool@latest`) just to check. Use what is installed. If the project has no Playwright but the `TAMSENSE_PLAYWRIGHT` environment variable is set, the TAMsense runner has already installed `playwright-core` and a headless browser outside the project, and the headless check script uses them. If nothing is, check from the code and say the browser check could not run.
+3. **The project's own start command, on a free port.** Start the app with its dev or preview script, never a hand-made server that skips its config. Prefer the headless check script, which starts the server and stops its whole process tree for you. Stop it at the end, including child processes, and confirm the port is free again.
+8. **Stop only what you started, by process id.** This is someone's own computer and their other programs may be running. Never kill processes by name or pattern: no `taskkill /IM`, `pkill`, `killall`, `Stop-Process -Name`. If you start a server yourself, record its PID and stop that process tree (`taskkill /PID <pid> /T /F` on Windows, `kill -- -<pgid>` elsewhere). If a process you started cannot be stopped that way, say so in the report and leave the rest alone.
+4. **Outputs outside the repository.** Screenshots, traces, reports, scratch scripts and auth state go to a new folder in the OS temp directory. `git status` must show nothing new from you when you finish.
+5. **Never fake it.** If the app cannot start (missing environment variables, secrets, a database or service you may not use), report exactly what is missing. Do not mock the whole backend and call the result a pass, and do not invent screenshots or results.
+6. **Do not write to shared systems.** If the local app is configured against a shared or production backend or database, look but do not submit forms or trigger writes.
+7. **Never hide failures.** Do not skip, `fixme`, delete or loosen a failing test to get a green run. In a check step, a failing test is a finding.
+
+## Process
+
+### 1. Decide what to check
+
+From the task, the spec's acceptance criteria and the diff (`git diff origin/<base>...HEAD --stat`, then the changed components, routes and styles), write a short list of scenarios before touching the browser:
+
+- The main flow the task changed, end to end.
+- Its states: loading, empty, error, long or unusual content, many items, disabled controls.
+- A narrow screen (390 px wide) if layout or styles changed, plus a desktop width.
+- Keyboard use for any new or changed control (Tab to it, activate with Enter or Space, Escape closes overlays). The `accessibility` skill has the full checks.
+
+### 2. Find how this project runs and tests its UI
+
+- E2E setup: `playwright.config.*`, `cypress.config.*`, `e2e/` or `tests/` folders, scripts like `test:e2e` in `package.json`, and the CI workflow steps that run them (they show the exact command, env vars and services).
+- The app: dev and preview scripts, required env vars (`.env.example`, config validation, README), services it needs (database, cache, other apps in a monorepo). Check whether required variables are set by name; never print their values.
+- Auth: seeded test users, a test login endpoint, existing storage-state setup.
+- The installed Playwright or Cypress version.
+
+### 3a. The project has an E2E suite
+
+Run the specs related to the change, then the whole suite if it is fast enough.
+
+- Playwright: `PW_TEST_HTML_REPORT_OPEN=never npx playwright test <specs> --reporter=line --output <tmp>/test-results` (use the package manager the project uses). Its `webServer` config usually starts the app: check the port and `reuseExistingServer`, and make sure no stale server of yours is still running.
+- Cypress: `npx cypress run --spec <specs> --config screenshotsFolder=<tmp>/screens,videosFolder=<tmp>/videos,video=false` (headless by default).
+- If a run fails, rerun the failing spec alone to separate a real failure from a flaky one, and read the error and screenshot. Decide whether the failure comes from the change (the diff touches that flow) or existed before; say which and why.
+
+In a code step, add or update tests for the changed flow following the suite's structure; see [references/playwright-patterns.md](references/playwright-patterns.md) for locators, waiting, auth, mocking and the plan, write, repair loop. In a review or test step, do not edit the repository's tests; check extra scenarios with 3b instead.
+
+### 3b. No suite, or scenarios the suite does not cover
+
+Use the headless check in [references/headless-check.md](references/headless-check.md): a Node.js script you write to a temp folder that resolves Playwright from the project, starts the app with the project's command on a free port, visits the pages at 1280 and 390 px, runs your steps, saves screenshots and a JSON summary (console errors, failed requests, horizontal overflow, optional axe scan), and stops the app.
+
+If Playwright is not installed in the project and no other headless browser tool is available, do not install one. Check the change from the code and say so.
+
+### 4. Look at the evidence
+
+- Open every screenshot with the Read tool and compare it with what the scenario expects. Describe what you see in plain words: what is on the screen, what is wrong, where.
+- Console errors, page errors and failed requests from the changed code are findings; third-party noise is not, but name it so the reader knows you saw it.
+- Sideways scrolling at 390 px, cut-off text, overlapping elements, missing states and dead buttons are findings.
+- For visual quality and consistency with the design system, apply the `design-review` skill; for the rules list, `web-interface-guidelines`; for accessibility, `accessibility`.
+
+### 5. Clean up
+
+Stop the servers you started, by their process id only (hard rule 8), check the port no longer answers, remove containers and temp folders you created unless the task asks to keep artifacts, and run `git status` in every repository to confirm you left nothing behind.
+
+## Report
+
+```
+UI check: <passed | failed | could not run>
+How: <suite command or headless check>, browser <chromium | chrome | msedge>, widths <1280, 390>
+Scenarios:
+- <scenario>: pass | fail | not checked (why). Evidence: <what the screenshot or log shows>
+Findings:
+- <file:line if traced> <what is wrong, how to reproduce, what was expected>
+Not checked: <and why: missing env vars X, Y; no browser available; flow needs an external provider>
+Assumptions: <test account used, data you created locally, version>
+```
+
+In a test step, base the verdict on the scenarios: a broken acceptance criterion, an error from the changed code or a layout broken on narrow screens fails it. If the browser check could not run, do not report it as passed; judge from the other evidence (tests, code) and state clearly that the UI was not seen. If the change itself stops the app from starting or building, that is a failure.
+
+## Common mistakes
+
+- Assuming the page works because the build passed.
+- Fixed sleeps instead of waiting for the element that proves readiness.
+- Letting the HTML reporter or a dev server open a browser window.
+- Leaving the dev server running, or `test-results/` and screenshots inside the repository.
+- Testing only the happy path at desktop width.
+- Pointing the check at staging or production because the local app did not start.
+- Listing screenshot paths without saying what they show.
+
+## Done when
+
+- Every scenario from step 1 is checked or listed as not checked with a reason.
+- Evidence (described screenshots, error lines, failing assertions) backs each finding.
+- No window was opened, no dependency added, nothing left running or written into the repository.
+
+Sources: the start, wait, act, stop approach of anthropics/skills webapp-testing (Apache-2.0, commit dbd4588), testdino-hq/playwright-skill (MIT, commit 178d1cb), ideas from the Playwright test agents (Apache-2.0). Changed: rewritten for Node and the project's own setup, unattended rules added.

package/library/skills/ui-testing/references/headless-check.md

@@ -0,0 +1,262 @@
+# Headless check without an E2E suite
+
+Read this when the project has no Playwright or Cypress tests you can run for the change, but you still need to see the pages: screenshots, console errors, failed requests, horizontal overflow on narrow screens, and optionally an axe scan.
+
+The script below starts the app with the project's own command on a free port, waits for it, opens each page headless at a desktop and a phone width, runs optional steps you write, saves screenshots and a JSON summary to a temp folder, and stops the app and all its child processes at the end.
+
+## What it needs
+
+- Node.js 20 or newer.
+- The `playwright`, `@playwright/test` or `playwright-core` package already installed in the project (it is resolved from the project folder you give it; in a monorepo, use the package folder of the web app). If the project has none and the `TAMSENSE_PLAYWRIGHT` environment variable is set, the script loads the `playwright-core` that the TAMsense runner installed in that folder, with the headless browser from the `TAMSENSE_PLAYWRIGHT_BROWSERS` folder. Nothing is installed.
+- A browser that is already on the machine: Playwright's downloaded Chromium (the project's or the runner's), or the system Chrome or Edge as a fallback. If none works, the script stops and says so. Do not run `playwright install` or add packages to get one; report that the check could not run.
+- `axe-core` is optional: if the project already has it, each page also gets an accessibility scan.
+
+## How to use it
+
+1. Make a new folder in the OS temp directory (`node -p "require('os').tmpdir()"`), for example `<tmp>/ui-check-<random>`. Never inside the repository.
+2. Write the script there as `ui-check.mjs` and edit only the `CONFIG` block and the `steps` function.
+3. Run `node <tmp>/ui-check-<random>/ui-check.mjs` with a timeout of a few minutes. It prints the summary; screenshots are in `CONFIG.outDir`.
+4. Open the screenshots with the Read tool and look at them. Describe in the report what each one shows; the paths alone mean nothing to the reader.
+5. Delete the folder when the report is written, unless the task asks you to keep artifacts.
+
+`startCommand` is the project's own dev or preview command with `{port}` where the port goes, for example `pnpm dev --port {port} --strictPort` (Vite), `npm run dev -- -p {port}` (Next.js), `pnpm nuxt dev --port {port}`, `bin/rails server -p {port}`, `python manage.py runserver 127.0.0.1:{port}`. The script also sets `PORT`. Leave it empty and set `baseUrl` if the app is already running or is static files you serve another way.
+
+On Windows the command runs in `cmd.exe`, which may not see the same PATH as your shell. If the summary says the command is not recognized, use absolute paths (for example the full path to `node.exe` and the package manager's script) rather than changing anything in the project.
+
+## The script
+
+```js
+import { createRequire } from 'node:module'
+import { spawn, execFileSync } from 'node:child_process'
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import net from 'node:net'
+
+const CONFIG = {
+    projectDir: '/absolute/path/to/web/app',
+    outDir: '/absolute/path/to/tmp/ui-check-1234/out',
+    startCommand: 'pnpm dev --port {port} --strictPort',
+    baseUrl: '',
+    paths: ['/'],
+    widths: [1280, 390],
+    startTimeoutMs: 120_000,
+    navigationTimeoutMs: 30_000,
+}
+
+async function steps(page, { path, width }) {
+}
+
+const MAX_ITEMS = 20
+const serverOutput = []
+
+function keepTail(chunk) {
+    serverOutput.push(...String(chunk).split('\n').filter(Boolean))
+    serverOutput.splice(0, Math.max(0, serverOutput.length - 40))
+}
+
+function requireFrom(dir, names) {
+    const require = createRequire(join(dir, 'package.json'))
+    for (const name of names) {
+        try {
+            return require(name)
+        } catch {}
+    }
+    return null
+}
+
+function loadFromProject(names) {
+    const found = requireFrom(CONFIG.projectDir, names)
+    const runnerCopy = process.env.TAMSENSE_PLAYWRIGHT
+    if (found || !names.includes('playwright-core') || !runnerCopy) return found
+    if (process.env.TAMSENSE_PLAYWRIGHT_BROWSERS) process.env.PLAYWRIGHT_BROWSERS_PATH = process.env.TAMSENSE_PLAYWRIGHT_BROWSERS
+    return requireFrom(runnerCopy, ['playwright-core'])
+}
+
+function freePort() {
+    return new Promise((resolve, reject) => {
+        const server = net.createServer()
+        server.on('error', reject)
+        server.listen(0, '127.0.0.1', () => {
+            const { port } = server.address()
+            server.close(() => resolve(port))
+        })
+    })
+}
+
+function startServer(command, port) {
+    const child = spawn(command.replaceAll('{port}', String(port)), {
+        cwd: CONFIG.projectDir,
+        shell: true,
+        env: { ...process.env, PORT: String(port), BROWSER: 'none' },
+        detached: process.platform !== 'win32',
+        windowsHide: true,
+        stdio: ['ignore', 'pipe', 'pipe'],
+    })
+    child.stdout.on('data', keepTail)
+    child.stderr.on('data', keepTail)
+    return child
+}
+
+function stopServer(child) {
+    if (!child || child.exitCode !== null) return 'not running'
+    try {
+        if (process.platform === 'win32') {
+            const taskkill = join(process.env.SystemRoot ?? 'C:\\Windows', 'System32', 'taskkill.exe')
+            execFileSync(taskkill, ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' })
+        } else {
+            process.kill(-child.pid, 'SIGKILL')
+        }
+        return 'stopped'
+    } catch (error) {
+        child.kill('SIGKILL')
+        return `could not stop the process tree of pid ${child.pid}: ${error.message}`
+    } finally {
+        child.stdout.destroy()
+        child.stderr.destroy()
+        child.unref()
+    }
+}
+
+async function waitForServer(url, child) {
+    const deadline = Date.now() + CONFIG.startTimeoutMs
+    while (Date.now() < deadline) {
+        if (child && child.exitCode !== null) throw new Error(`start command exited with code ${child.exitCode}`)
+        try {
+            await fetch(url, { redirect: 'manual', signal: AbortSignal.timeout(5_000) })
+            return
+        } catch {}
+        await new Promise(resolve => setTimeout(resolve, 1_000))
+    }
+    throw new Error(`no response from ${url} within ${CONFIG.startTimeoutMs / 1000}s`)
+}
+
+async function launchBrowser(chromium) {
+    const failures = []
+    for (const channel of [undefined, 'chromium', 'chrome', 'msedge']) {
+        try {
+            return await chromium.launch({ headless: true, channel })
+        } catch (error) {
+            failures.push(`${channel ?? 'playwright chromium'}: ${String(error.message).split('\n')[0]}`)
+        }
+    }
+    throw new Error(`no browser available without downloading one: ${failures.join(' | ')}`)
+}
+
+async function runAxe(page, axeSource) {
+    try {
+        await page.addScriptTag({ content: axeSource })
+        return await page.evaluate(async () => {
+            const result = await window.axe.run(document, {
+                runOnly: { type: 'tag', values: ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa'] },
+            })
+            return result.violations.map(violation => ({
+                rule: violation.id,
+                impact: violation.impact,
+                help: violation.help,
+                count: violation.nodes.length,
+                targets: violation.nodes.slice(0, 5).map(node => JSON.stringify(node.target)),
+            }))
+        })
+    } catch (error) {
+        return { error: String(error.message).split('\n')[0] }
+    }
+}
+
+async function checkPage(browser, url, path, width, axeSource) {
+    const context = await browser.newContext({ viewport: { width, height: 900 } })
+    const page = await context.newPage()
+    const result = { path, width, consoleErrors: [], pageErrors: [], failedRequests: [], badResponses: [] }
+    const add = (list, item) => { if (list.length < MAX_ITEMS) list.push(item) }
+    page.on('console', message => { if (message.type() === 'error') add(result.consoleErrors, message.text()) })
+    page.on('pageerror', error => add(result.pageErrors, String(error.message)))
+    page.on('requestfailed', request => add(result.failedRequests, `${request.method()} ${request.url()} ${request.failure()?.errorText ?? ''}`))
+    page.on('response', response => { if (response.status() >= 400) add(result.badResponses, `${response.status()} ${response.url()}`) })
+    try {
+        const response = await page.goto(url, { waitUntil: 'load', timeout: CONFIG.navigationTimeoutMs })
+        result.status = response?.status() ?? null
+        await page.waitForLoadState('networkidle', { timeout: 5_000 }).catch(() => {})
+        result.steps = await steps(page, { path, width })
+        result.title = await page.title()
+        result.finalUrl = page.url()
+        result.horizontalOverflowPx = await page.evaluate(() => document.documentElement.scrollWidth - document.documentElement.clientWidth)
+        const name = `${path.replace(/[^a-z0-9]+/gi, '_').replace(/^_|_$/g, '') || 'root'}-${width}.png`
+        result.screenshot = join(CONFIG.outDir, name)
+        await page.screenshot({ path: result.screenshot, fullPage: true })
+        if (axeSource) result.axe = await runAxe(page, axeSource)
+    } catch (error) {
+        result.error = String(error.message).split('\n')[0]
+    } finally {
+        await context.close()
+    }
+    return result
+}
+
+async function main() {
+    mkdirSync(CONFIG.outDir, { recursive: true })
+    const summary = { pages: [], serverOutputTail: serverOutput }
+    const playwright = loadFromProject(['playwright', '@playwright/test', 'playwright-core'])
+    if (!playwright?.chromium) throw new Error(`Playwright is not installed in ${CONFIG.projectDir} and TAMSENSE_PLAYWRIGHT is not set`)
+    const axeSource = loadFromProject(['axe-core'])?.source ?? null
+    summary.axe = axeSource ? 'axe-core found in the project' : 'axe-core not installed, scan skipped'
+
+    let server = null
+    let browser = null
+    try {
+        let baseUrl = CONFIG.baseUrl
+        if (CONFIG.startCommand) {
+            const port = await freePort()
+            server = startServer(CONFIG.startCommand, port)
+            baseUrl = `http://localhost:${port}`
+        }
+        if (!baseUrl) throw new Error('set CONFIG.startCommand or CONFIG.baseUrl')
+        summary.baseUrl = baseUrl
+        await waitForServer(baseUrl, server)
+        browser = await launchBrowser(playwright.chromium)
+        for (const path of CONFIG.paths) {
+            for (const width of CONFIG.widths) {
+                summary.pages.push(await checkPage(browser, new URL(path, baseUrl).href, path, width, axeSource))
+            }
+        }
+    } catch (error) {
+        summary.setupError = String(error.message)
+        process.exitCode = 2
+    } finally {
+        await browser?.close().catch(() => {})
+        if (server) summary.server = stopServer(server)
+        writeFileSync(join(CONFIG.outDir, 'summary.json'), JSON.stringify(summary, null, 2))
+        console.log(JSON.stringify(summary, null, 2))
+    }
+}
+
+main().catch(error => {
+    console.error(error.message)
+    process.exitCode = 2
+})
+```
+
+## Writing steps
+
+`steps` runs on every page and width before the screenshot. Use it to reach the state the task changed: open the dialog, fill and submit the form, switch the tab. Branch on `path` when pages need different steps. Whatever it returns is saved as `steps` in that page's summary (for example the focus order from a keyboard pass, see the `accessibility` skill). Use the same rules as in tests: role and label locators, web-first waits, no fixed sleeps (see [playwright-patterns.md](playwright-patterns.md)).
+
+```js
+async function steps(page, { path }) {
+    if (path !== '/settings') return
+    await page.getByRole('button', { name: 'Edit profile' }).click()
+    await page.getByLabel('Display name').fill('A very long display name that should wrap or truncate')
+    await page.getByRole('button', { name: 'Save' }).click()
+    await page.getByRole('status').waitFor()
+}
+```
+
+Steps that write data only touch the local app and whatever local database it uses. If the dev server is configured to talk to a shared or production backend or database, do not submit forms or trigger writes; check that first (see the `safe-database-changes` skill for how to read where the app connects).
+
+## Reading the summary
+
+- `server`: should be `stopped`. Anything else names a process you must stop yourself before finishing.
+- `setupError`: the app or the browser did not start. Report it with the last lines of `serverOutputTail` (strip anything that looks like a secret). Do not retry with a different command unless the first one was clearly wrong, and never invent results.
+- `status` 4xx or 5xx, `pageErrors`, `consoleErrors`: real findings when they come from the changed code; noise from browser extensions does not exist here, but third-party scripts and dev-server warnings do. Say which is which.
+- `badResponses` and `failedRequests`: API calls the page needed that failed. A 401 or a redirect to a login page means the page needs a signed-in user (see the auth section of [playwright-patterns.md](playwright-patterns.md)).
+- `horizontalOverflowPx` above 0 at 390 px: the page scrolls sideways on phones.
+- `axe`: list each rule with impact and a target; the `accessibility` skill explains how to judge them.
+
+Written for this library. The start, wait, act, stop approach follows anthropics/skills `webapp-testing` (Apache-2.0, commit dbd4588f9e1033efb41dad4bef2f7947c8993d44, Copyright 2026 Anthropic, PBC); the script is new Node.js code, not a translation of its Python helper.