How it all fits together

The authoring pipeline

Every test in this repo follows the same path from idea to executable file:

1. You describe a user flow in English
         — OR —
   You record it with the VS Code Playwright recorder

2. The Planner or Stabilizer agent turns that into a structured spec
   saved at  tests/specs/<feature>/<name>.md

3. The Generator agent reads the spec and produces a runnable test
   saved at  tests/e2e/<feature>/<name>.spec.ts

4. The Reviewer agent checks the generated test against the rulebook
   and returns PASS or FAIL with line-precise findings

5. Playwright runs the test suite and produces an HTML report

No step requires you to write TypeScript. The only things a tester authors are the English description and, optionally, some data values in a .jsonc file.

The four agents

Each agent has a single, focused job. Their canonical prompt files live in tests/agents/.

Planner (tests/agents/playwright-planner.md) Takes a free-form English scenario — a user story, a bullet list of steps, or a quick paragraph — and produces a structured spec file at tests/specs/. The spec describes the preconditions, the actions, and the expected outcomes in a format the Generator understands.

Stabilizer (tests/agents/playwright-stabilizer.md) Takes a raw VS Code Playwright recording (a .json file) plus a paired set of English steps you wrote while recording, and converts them into a clean spec at tests/specs/. It also updates the shared data files in tests/data/ with any values it finds in the recording. Use this when you captured a flow by clicking through the app rather than describing it from memory.

Generator (tests/agents/playwright-generator.md) Reads a spec from tests/specs/ and emits a runnable .spec.ts file at tests/e2e/. It also does a smoke-run of the generated test to catch obvious errors before handing control back to you.

Reviewer (tests/agents/playwright-reviewer.md) Reads a generated test (and any page-object or helper changes it introduces) and checks everything against the rulebook at tests/agents/rules/playwright-rules.md. It returns a structured PASS or FAIL verdict with specific line references so the Generator (or a developer) knows exactly what to fix.

Where things live

Location	Purpose
tests/specs/	English specs — source of truth for what a test should do
tests/e2e/	Generated .spec.ts files — do not edit by hand
tests/data/*.jsonc	Shared test data (project IDs, names, env-variable references)
tests/data/env/	Per-environment overrides for dev2, staging, etc.
tests/page-objects/	Page-object classes that encapsulate UI interactions
tests/utils/	Helpers including the data-resolver that handles {{env:...}} refs
tests/fixtures/	Playwright fixture definitions
tests/recordings/	Raw VS Code recordings and stabilizer reports
tests/agents/	Canonical agent prompt files
tests/agents/rules/	The rulebook the Reviewer checks against

Note on selectors: Button labels, field names, and CSS selectors come from the PACE application itself. Because the application source is in the sibling pace-ui-application repo, the agents search that checkout when they need to verify that a selector actually exists in the UI. You do not need to look those up yourself.

---

Ready to try it? See Authoring from a recording for a step-by-step walkthrough, or browse the Commands overview for the full list of AI slash commands available in this repo.