Skip to main content

The four agents

PACE E2E includes four AI agents, each with a single job. They form an assembly line: you describe what you want, and the agents carry it from English prose all the way to a reviewed, runnable test.

You invoke them inside your AI coding tool (Claude Code, Codex, Gemini CLI, or similar). Their canonical prompt files live in tests/agents/playwright-*.md. The prompts are written to be host-neutral — the same instructions work across different AI tools.

1. Planner — English → spec​

Prompt file: tests/agents/playwright-planner.md

You give the Planner a free-form description of a scenario:

"Test that we can add an Account Manager to a project's Key Members grid and see the success toast."

The Planner reads the application source, the existing page objects, and the project's rulebook, then writes a structured spec file at tests/specs/{feature}/{name}.md. It fills in the frontmatter (id, feature, title, fixture, data references) and builds the numbered step list with intent and method for each step.

The Planner does not write TypeScript. Its output is the English spec.

2. Stabilizer — recording + English → spec + data​

Prompt file: tests/agents/playwright-stabilizer.md

The Stabilizer is an alternative starting point when you have already captured a flow using VS Code's built-in Playwright Recorder instead of writing steps from scratch. You give it two things:

  • The raw recording file (a .spec.ts full of low-level page.locator(…).click() calls, saved in tests/recordings/).
  • A set of paired English statements explaining the intent of each step (a short .steps.md file, or typed directly into the prompt).

The Stabilizer extracts the hard-coded values from the recording, moves them into tests/data/, and writes a clean canonical spec with proper frontmatter and intent/method fields. It also produces an alignment report showing how each raw recorder line maps to a logical step.

Like the Planner, the Stabilizer does not produce a .spec.ts file. That is the Generator's job.

3. Generator — spec → runnable test​

Prompt file: tests/agents/playwright-generator.md

The Generator takes a finished spec and turns it into an executable Playwright test at tests/e2e/{feature}/{name}.spec.ts. It:

  1. Reads the spec frontmatter to know which fixture and data to use.
  2. Translates each method: line into TypeScript calls on the correct page objects and helpers.
  3. If a step is annotated [NEW: ClassName.methodName()], it reads the PACE application source to understand the screen's DOM, writes the new method, and adds it to the right page-object file.
  4. Smoke-runs the generated test once (in a real browser against the target environment) to confirm it compiles and executes without crashing.

The Generator does not review the test for correctness or rule compliance. That is the Reviewer's job.

4. Reviewer — quality gate​

Prompt file: tests/agents/playwright-reviewer.md

The Reviewer reads the generated test file (and any page-object or helper changes the Generator made) against the project's rulebook: tests/agents/rules/playwright-rules.md.

It produces a structured PASS / FAIL verdict. For every finding it identifies the file, the line number, the rule that was violated, and the severity (critical / major / minor). A PASS means the test meets all the project's standards and is ready to commit. A FAIL means the Generator must revise and the Reviewer runs again.

The Reviewer does not modify any code. It only reports.

How the agents fit together​

You (English description)
        │
        ▼
   Planner  ──or──  Stabilizer (recording + English)
        │
        ▼
   tests/specs/{feature}/{name}.md  +  tests/data/ entries
        │
        ▼
   Generator
        │
        ▼
   tests/e2e/{feature}/{name}.spec.ts  +  page-object extensions
        │
        ▼
   Reviewer
        │
      PASS? ──yes──▶  commit
        │
       no
        │
        ▼
   Generator fixes & Reviewer re-checks

You are involved at the very start (writing the description or recording the flow) and at the very end (reviewing the Reviewer's PASS verdict before committing). The middle steps are fully automated.