playwright-test-agent 0.1.4 → 0.1.7

package/bin/playwright-test-agent.mjs

@@ -1,29 +1,29 @@
-#!/usr/bin/env node
-
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { initializeProject } from '../playwright-test-agent/scripts/init-playwright.mjs';
-
-const usage = `Usage: playwright-test-agent init [target-directory]
-
+#!/usr/bin/env node
+
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { initializeProject } from '../playwright-test-agent/scripts/init-playwright.mjs';
+
+const usage = `Usage: playwright-test-agent init [target-directory]
+
 Initialize Playwright Test agents, install the playwright-test-agent skill,
-and update AGENTS.md and CLAUDE.md in the target project.`;
-
-const [command, targetDirectory, ...extraArguments] = process.argv.slice(2);
-
-if (command !== 'init' || extraArguments.length > 0) {
-  console.error(usage);
-  process.exitCode = 1;
-} else {
-  const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-
-  try {
-    await initializeProject({
-      projectDir: path.resolve(targetDirectory ?? process.cwd()),
-      skillSourceDir: path.join(packageRoot, 'playwright-test-agent'),
-    });
-  } catch (error) {
-    console.error(`playwright-test-agent init failed: ${error.message}`);
-    process.exitCode = 1;
-  }
-}
+install Playwright CLI globally, and update AGENTS.md and CLAUDE.md.`;
+
+const [command, targetDirectory, ...extraArguments] = process.argv.slice(2);
+
+if (command !== 'init' || extraArguments.length > 0) {
+  console.error(usage);
+  process.exitCode = 1;
+} else {
+  const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+  try {
+    await initializeProject({
+      projectDir: path.resolve(targetDirectory ?? process.cwd()),
+      skillSourceDir: path.join(packageRoot, 'playwright-test-agent'),
+    });
+  } catch (error) {
+    console.error(`playwright-test-agent init failed: ${error.message}`);
+    process.exitCode = 1;
+  }
+}

package/package.json

@@ -1,17 +1,17 @@
-{
-  "name": "playwright-test-agent",
-  "version": "0.1.4",
-  "description": "Initialize Playwright Test agents and install the playwright-test-agent skill.",
-  "type": "module",
-  "bin": {
-    "playwright-test-agent": "bin/playwright-test-agent.mjs"
-  },
-  "files": [
-    "bin/",
-    "playwright-test-agent/"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "license": "UNLICENSED"
-}
+{
+  "name": "playwright-test-agent",
+  "version": "0.1.7",
+  "description": "Initialize Playwright Test agents with a Playwright CLI-first browser workflow.",
+  "type": "module",
+  "bin": {
+    "playwright-test-agent": "bin/playwright-test-agent.mjs"
+  },
+  "files": [
+    "bin/",
+    "playwright-test-agent/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "UNLICENSED"
+}

package/playwright-test-agent/SKILL.md

@@ -1,113 +1,54 @@
 ---
 name: playwright-test-agent
-description: Use first when a user asks to test a website, browser workflow, HTTP API, or application feature, including planning, generating, running, debugging, healing, screenshots, and reusable test evidence.
+description: Use first when a user asks to investigate or test a website, browser workflow, HTTP API, or application feature with Playwright, including planning, generation, execution, debugging, healing, and evidence collection.
 ---
 
 # Playwright Test Agent
 
-Use Playwright Test for durable automation. The main agent orchestrates Playwright's official planner, generator, and healer subagents instead of replacing their work with ad hoc browser exploration. Pure HTTP API tests may be written directly with Playwright `APIRequestContext` without those subagents.
+Use Planner -> Generator -> Healer for durable tests. `AGENTS.md` or `CLAUDE.md` defines the platform-specific role routing. Generated role definitions use `playwright-cli` as their primary browser interface, so MCP tool injection is not required.
 
-This file is the single source of truth for the testing workflow. Project-level `AGENTS.md` and `CLAUDE.md` only force this skill to be loaded and name the platform-specific subagents; do not duplicate or infer the detailed workflow from those routing files.
+## Prepare the objective
 
-## Platform agent names
+The main agent may inspect the local project for relevant requirements, routes, fixtures, and constraints. Do not require a seed/config audit before planning.
 
-| Role | Codex | Claude Code |
-|---|---|---|
-| Planner | `playwright_test_planner` | `playwright-test-planner` |
-| Generator | `playwright_test_generator` | `playwright-test-generator` |
-| Healer | `playwright_test_healer` | `playwright-test-healer` |
+Before Planner, ask for information that could materially change purpose, scope, safety, or expected behavior: deployed URL, intended role, success criteria, allowed data mutations, and environment constraints. Do not ask for UI details Planner can safely discover.
 
-Use the names for the active platform. The role names below refer to these mapped agents.
+If the request is sufficient, begin Planner immediately. If investigation finds a missing, incorrect, or contradictory URL, credential, role, prerequisite, expected result, or authorization boundary, pause and ask for the specific correction. Resume Planner with the correction and blocking observation. Do not guess credentials, probe nearby environments, bypass access controls, or wander through unrelated pages.
 
-## Agent responsibilities
+Keep credentials and tokens in environment variables or ignored secret files. Never copy them into plans, tests, screenshots, evidence, or chat.
 
-- **Main agent:** Own the user conversation, inspect only the local project for context, gather the minimum non-discoverable information from the user, locate the default seed generated by `playwright init-agents`, start Planner, Generator, and Healer directly as leaf subagents, present the plan for confirmation, and report final results. It must not open, navigate, inspect, screenshot, or otherwise investigate the deployed website itself. It must not insert an intermediary or nested agent between itself and any Playwright Test agent.
-- **Planner:** Run the generated seed to establish page context, global setup, dependencies, fixtures, and hooks. Explore the deployed application for the requested scenarios and user flows, compare observations with the request and optional PRD, and save a precise human-readable Markdown plan under `specs/`. It does not generate the formal test files and must not spawn another agent. It must call its own injected `planner_setup_page` and `planner_save_plan` tools directly.
-- **Generator:** Read the complete user-confirmed Markdown plan and the same generated seed, execute each scenario to validate locators and assertions against the live application, and generate executable Playwright tests under the configured test directory. It must not invent unconfirmed scenarios or expected behavior, must not spawn another agent, and must call its own injected `generator_setup_page`, `generator_read_log`, and `generator_write_test` tools directly.
-- **Healer:** Run the failing test, replay its steps, inspect the current UI, propose and apply test-side patches, and rerun until the test passes or a guardrail stops the loop. It must not spawn another agent and must call its own injected `test_list`, `test_run`, `test_debug`, and relevant `browser_*` tools directly. It must report a likely broken product, environment/data problem, or plan conflict instead of weakening assertions merely to obtain a pass.
+## Planner
 
-For UI testing, keep these responsibilities and sequence:
+Planner investigates the live application with `playwright-cli` and saves a human-readable Markdown plan under `specs/`. Use `open`/`goto`, compact `snapshot` or `find`, and refs for interaction. Supply a seed only when explicitly identified; do not perform a separate seed discovery pass.
 
-```text
-request + deployed URL -> locate generated seed -> planner -> user confirms plan
-                       -> generator -> healer for failures -> final report
-```
-
-Planner, Generator, and Healer are terminal/leaf agents in this flow. The main agent starts the platform-specific agent for each role directly and passes all required inputs in that invocation. Never delegate their work to `live_planner`, `live_generator`, `live_healer`, a same-role nested agent, or another intermediary. If a directly started agent lacks any required MCP tool, stop with an MCP-injection diagnosis; do not create another subagent level and do not replace that agent's work in the main agent.
-
-## Initialize once per project
-
-Inspect the target project first. If Playwright Test, its config, or either Codex/Claude agent set is missing, tell the user initialization will modify the project, then run from the target project:
-
-```bash
-npx playwright-test-agent init
-```
-
-The command installs this skill for Codex and Claude, selects the ready-to-use Playwright defaults (TypeScript, `playwright-tests/`, no GitHub Actions, Chromium with browser installation), and runs both:
-
-```text
-npx playwright init-agents --loop=codex
-npx playwright init-agents --loop=claude
-```
-
-It uses the project-local Playwright command. Never install a global/additional Playwright CLI or run `playwright init-skills`.
-
-`playwright init-agents` also creates the project's default `seed.spec.ts`. Its directory follows the selected Playwright project's `testDir`, so it may be under `playwright-tests/`, `e2e/`, `tests/`, or another configured directory. Do not hardcode the path. Locate it from `playwright.config.*`, the generated agent definitions, or the filesystem before invoking planner or generator.
-
-## Understand the request
+The plan contains prerequisites, test data, independent scenarios, steps, observable expected results, exclusions, and intended output files. Reconnaissance must not mutate durable/shared data or perform consequential actions unless authorized.
 
-Before testing, the main agent may briefly inspect the local target project for relevant source, routes/API clients, environment examples, existing tests, fixtures, the generated seed, and run instructions. The project may otherwise be empty or contain no useful application context; in that case, do not keep searching the filesystem or invent missing details.
+Show the scenario list and exclusions to the user. Generator starts only after confirmation.
 
-This local project inspection is the maximum reconnaissance the main agent may perform. The main agent must not use browser tools, HTTP requests, screenshots, or other means to investigate the deployed application. All live website reconnaissance belongs exclusively to the Planner. The main agent may read and summarize Planner output, but it must not independently verify or extend that investigation.
+## Generator
 
-Before starting the Planner, the main agent may ask the user to clarify information that materially affects the purpose, scope, safety, or expected result of the test plan. Relevant questions may cover the business goal, in-scope and excluded flows, user roles or accounts, expected success and failure outcomes, allowed data mutations, test-data constraints, environment limitations, and required browsers or devices. Ask only questions whose answers could change the plan or authorization boundary; if a necessary answer is missing, wait for it before starting the Planner.
+Generator converts the confirmed plan into executable tests. Use `playwright-cli` to validate flows, locators, and assertions against the live application, then write the tests directly. Generate only confirmed scenarios; prefer independent tests, semantic locators, explicit assertions, and environment-based secrets.
 
-Do not ask the user for UI facts the Planner can safely discover from the deployed application, such as field labels, button locations, page structure, or ordinary navigation. Once the main agent has the test objective, deployed base URL, and any necessary non-discoverable constraints, invoke the Planner and let it perform all live investigation. For example, "test this project's login feature" plus its deployment URL is enough to investigate a public login page, unless the intended account role, authenticated outcome, or permitted side effects must first be clarified.
+For API-only scenarios, use Playwright `APIRequestContext` directly and assert status, headers, schema, stable business invariants, and safe mutation cleanup.
 
-Pass the planner the exact objective, deployed URL, generated seed path, known authentication/roles, allowed side effects, supplied test data, and relevant project or PRD context. The seed is produced by initialization, not supplied by the user. It may remain the default page-context seed or be customized for project fixtures, global setup, dependencies, or authenticated context. Credentials are required before attempting an authenticated-only flow, but not merely to investigate a publicly reachable login page.
+## Healer
 
-If no seed can be located after initialization, treat the Playwright agent setup as incomplete. Check the configured test directory and generated agent definitions, then rerun `npx playwright-test-agent init` when regeneration is needed. Do not ask the user to author a seed, invent an arbitrary path, or continue to planner without the initialized project context.
+Use Healer only for failures. Run the failing test with `npx playwright test`, reproduce and inspect the current UI with `playwright-cli`, apply justified test-side changes, and rerun within guardrails.
 
-If planner reconnaissance shows that information is missing, invalid, stale, or contradictory—for example, the URL is unreachable, a page or control does not exist, credentials fail, the observed role differs, a required variable is absent, or application behavior conflicts with the request—stop that planning attempt. Report the exact mismatch without exposing secrets and ask the user to correct or complete it. Do not repeatedly try nearby URLs, guess credentials, wander through unrelated pages, or substitute the main agent's own exploration. Resume with the planner only after the user supplies enough corrected information.
+Do not weaken assertions, add arbitrary sleeps, retry blindly, or skip merely to pass. If behavior conflicts with the confirmed plan, preserve evidence and ask whether it is a regression or intended change. Classify unresolved failures as application defect, test defect, environment/data problem, or product decision.
 
-Never put credentials or tokens in plans, source, screenshots, reports, or chat output. Use environment variables or an ignored secret file.
+## Evidence
 
-## Plan and confirm
+Keep evidence under `.playwright-evidence/`. Prefer DOM snapshots and targeted `find` output; take screenshots only when visual evidence is necessary. Keep trace DOM snapshots, sources, network data, and attachments, but set trace `screenshots: false` to avoid hundreds of screencast JPEGs.
 
-Always have the planner save its human-readable Markdown plan under `specs/` before invoking the generator. Include prerequisites, the generated seed path, test data, independent scenarios, steps or requests, expected observable results, and intended output test files.
+Report the plan path, generated tests, counts when tests ran, evidence paths, and failure classification. Never report skipped or unresolved tests as success.
 
-For UI work, invoke the Planner directly (as the first and only Planner-level subagent) once the objective, deployed base URL, and generated seed path are available and no known mismatch already blocks access. Explicitly name the seed in its prompt and provide an optional PRD only when one is relevant. The Planner runs the seed to perform global setup, dependencies, fixtures, and hooks, then uses its ready page context to inspect the live application. Reconnaissance must not create, delete, submit, purchase, message, or otherwise mutate durable/shared data without authorization.
+## Initialization
 
-If the planner discovers a new missing or incorrect prerequisite, the main agent stops that planning attempt, summarizes what was observed, and asks the user for clarification. Continue or reinvoke the planner only after the prerequisite is resolved; do not let it keep exploring around missing information. If the Planner session itself lacks a required MCP tool, report that direct-session environment failure and wait for the environment to be repaired; do not create a nested fallback agent.
+Run from the target project:
 
-Choose relevant positive, negative, empty, invalid, boundary, permission, persistence, and error scenarios. For login, normally consider valid credentials, empty username, empty password, both empty, wrong password, and unknown user; add MFA, lockout, recovery, or remember-me only when in scope.
-
-Show the complete scenario list and exclusions to the user. Ask whether it is complete. Revise until confirmed. Do not invoke the generator or formally execute tests before confirmation.
-
-## Generate and run
-
-For confirmed UI scenarios, invoke the Generator directly once for the complete confirmed plan (or complete selected scenario set), explicitly naming the Markdown plan and the same generated seed; use the configured Playwright test directory for generated tests. The Generator executes scenarios against the live application to validate locators and assertions while generating. Its internal per-scenario setup does not mean starting a new Generator agent for every scenario, and it must not delegate execution to a nested Generator. If the direct Generator lacks `generator_setup_page`, `generator_read_log`, or `generator_write_test`, report an MCP-injection failure and stop. Require one independent test per file, semantic locators, an assertion for every expected result, and environment-based secrets.
-
-For confirmed API-only scenarios, write `APIRequestContext` tests directly under `playwright-tests/`. Assert status, headers, schema, and stable business invariants; define safe setup/cleanup for mutations.
-
-After generation, invoke the Healer directly with one failing UI test name at a time. The Healer runs the test, replays the failing steps, inspects the current UI for the equivalent element or flow, proposes a patch such as a locator, synchronization, or test-data repair, and reruns until it passes or a guardrail stops the loop. It must not delegate diagnosis or repair to a nested Healer. If the direct Healer lacks `test_list`, `test_run`, `test_debug`, or the browser tools needed for diagnosis, report an MCP-injection failure and stop. API failures may be diagnosed directly.
-
-If observed product behavior conflicts with the confirmed plan, report the conflict and ask whether it is a regression or intended change. Do not weaken assertions, add arbitrary sleeps/`networkidle`, retry blindly, or skip/fixme tests merely to get green. If the healer concludes the feature is broken, preserve the failure evidence and report it as an application defect rather than treating a skipped test as success.
-
-## Preserve evidence
-
-All browser-agent and test artifacts must stay under:
-
-```text
-.playwright-evidence/
-├── mcp/           # page YAML snapshots, screenshots, and agent logs
-├── snapshots/     # reusable visual/ARIA baselines
-├── test-results/  # failure screenshots, traces, videos, attachments
-└── report/        # HTML report
+```bash
+npx playwright-test-agent init
 ```
 
-Never save snapshots or screenshots in the project root. Automatic failure evidence is enabled. For key business states, save an explicit screenshot with `testInfo.outputPath('screenshots', '<meaningful-name>.png')` so it remains in `test-results/`. Avoid secrets and sensitive personal data.
-
-Keep trace DOM snapshots, sources, network data, and attachments, but disable trace screenshots (`use.trace.screenshots: false`). Trace screenshots are screencast frames and can create hundreds of JPEG files under trace `resources/`; they are separate from explicit test screenshots and are not needed for ordinary DOM-based diagnosis.
-
-Finish by reporting the plan path, generated test paths, environment without secrets, pass/fail/flaky/skipped counts, and evidence paths. Classify failures as application defect, test defect, environment/data problem, or unresolved product decision.
+The command globally installs `@playwright/cli`, installs its Codex/Claude skills and browser, initializes Playwright Test agents, and reinjects CLI-first instructions into all six generated role definitions. Run it again after Playwright updates regenerate those definitions. Restart Codex or Claude Code after initialization so global skills and changed definitions are reloaded.

package/playwright-test-agent/scripts/init-playwright.mjs

@@ -1,228 +1,301 @@
-#!/usr/bin/env node
-
-import { access, cp, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
-import path from 'node:path';
-import { spawn } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
-
+#!/usr/bin/env node
+
+import { access, cp, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
 const BLOCK_START = '<!-- playwright-test-agent:start -->';
 const BLOCK_END = '<!-- playwright-test-agent:end -->';
-const CODEX_INSTRUCTIONS = `${BLOCK_START}
-## Playwright Test Agent
-
-For any website, browser workflow, HTTP API, or application-feature testing request, load and follow \`.agents/skills/playwright-test-agent/SKILL.md\` before planning or using browser tools. This skill has priority over ad hoc browser automation.
-
-For UI testing, the Codex subagents are \`playwright_test_planner\`, \`playwright_test_generator\`, and \`playwright_test_healer\`. The main agent may inspect only the local project; it must not open, navigate, inspect, screenshot, or otherwise investigate the deployed website itself. Before starting Planner, the main agent may ask for necessary information that materially affects test purpose, scope, expected outcomes, roles, allowed side effects, data, or environment constraints. It must not ask for UI details Planner can safely discover. Once the objective, deployed URL, and necessary non-discoverable constraints are available, start \`playwright_test_planner\` directly as the live-investigation leaf agent.
-
-The main agent must start each Playwright Test agent directly. Planner, Generator, and Healer are leaf agents: do not ask them to spawn \`live_planner\`, \`live_generator\`, \`live_healer\`, or any other nested subagent. Each must use its own injected Playwright Test MCP tools directly. If a directly started agent does not expose its required tools, stop and report the Codex MCP-injection problem; do not retry by creating a second- or third-level agent.
-
-If Planner reports that required test information is missing, invalid, or inconsistent, stop that planning attempt and ask the user for the specific missing information. After the user responds, start \`playwright_test_planner\` again with the corrected information and the previous blocking observation. Do not continue guessing or exploring around the blocker.
-${BLOCK_END}`;
-
-const CLAUDE_INSTRUCTIONS = `${BLOCK_START}
-## Playwright Test Agent
-
-For any website, browser workflow, HTTP API, or application-feature testing request, load and follow \`.claude/skills/playwright-test-agent/SKILL.md\` before planning or using browser tools. This skill has priority over ad hoc browser automation.
-
-For UI testing, the Claude Code subagents are \`playwright-test-planner\`, \`playwright-test-generator\`, and \`playwright-test-healer\`. The main agent may inspect only the local project; it must not open, navigate, inspect, screenshot, or otherwise investigate the deployed website itself. Before starting Planner, the main agent may ask for necessary information that materially affects test purpose, scope, expected outcomes, roles, allowed side effects, data, or environment constraints. It must not ask for UI details Planner can safely discover. Once the objective, deployed URL, and necessary non-discoverable constraints are available, start \`playwright-test-planner\` directly as the live-investigation leaf agent.
-
-The main agent must start each Playwright Test agent directly. Planner, Generator, and Healer are leaf agents: do not ask them to spawn \`live_planner\`, \`live_generator\`, \`live_healer\`, or any other nested subagent. Each must use its own injected Playwright Test MCP tools directly. If a directly started agent does not expose its required tools, stop and report the MCP-injection problem; do not retry by creating a second- or third-level agent.
-
-If Planner reports that required test information is missing, invalid, or inconsistent, stop that planning attempt and ask the user for the specific missing information. After the user responds, start \`playwright-test-planner\` again with the corrected information and the previous blocking observation. Do not continue guessing or exploring around the blocker.
-${BLOCK_END}`;
-
-const exists = async (file) => {
-  try {
-    await access(file);
-    return true;
-  } catch {
-    return false;
+const ROLE_BLOCK_START = '<!-- playwright-test-agent:cli-first:start -->';
+const ROLE_BLOCK_END = '<!-- playwright-test-agent:cli-first:end -->';
+const cliFirstInstructions = (role) => `${ROLE_BLOCK_START}
+
+## Browser tool priority
+
+Use the installed \`playwright-cli\` command as the primary browser interface. Read the globally installed \`playwright-cli\` skill when available. Start or attach a session with \`playwright-cli open\`/\`attach\`, navigate with \`goto\`, inspect compact state with \`snapshot\`, and interact through refs from the latest snapshot. Prefer \`snapshot\` and \`find\` over screenshots. Keep credentials in environment variables or ignored files and never print them.
+
+CLI replaces any conflicting requirement above to call Playwright Test MCP setup, browser, save, generation, or debug tools. Do not stop merely because \`planner_*\`, \`generator_*\`, \`test_*\`, or \`browser_*\` MCP tools are absent, and do not spawn a nested or same-role agent.
+
+${role === 'planner' ? 'Explore with CLI and save the completed Markdown test plan directly under `specs/` using filesystem tools.' : ''}${role === 'generator' ? 'Use CLI to validate the confirmed plan against the live UI, then write executable Playwright test files directly with filesystem tools.' : ''}${role === 'healer' ? 'Run failures with `npx playwright test`, use CLI to inspect and reproduce the current UI, patch the tests directly, and rerun within the healer guardrails.' : ''}
+
+${ROLE_BLOCK_END}`;
+const CODEX_INSTRUCTIONS = `${BLOCK_START}
+## Playwright Test Agent
+
+For website, browser workflow, HTTP API, or application-feature testing, load \`.agents/skills/playwright-test-agent/SKILL.md\` first. Codex must not start Playwright subagents; the main agent performs Planner -> Generator -> Healer in this session. Use \`playwright-cli\` as the primary browser interface and read generated TOML role definitions only for responsibilities. Ask for missing or contradictory purpose, access, role, data, or safety information before or during planning; do not guess or create nested agents.
+
+${BLOCK_END}`;
+
+const CLAUDE_INSTRUCTIONS = `${BLOCK_START}
+## Playwright Test Agent
+
+For website, browser workflow, HTTP API, or application-feature testing, load \`.claude/skills/playwright-test-agent/SKILL.md\` first. Claude Code starts the official \`playwright-test-planner\`, \`playwright-test-generator\`, and \`playwright-test-healer\` directly. These roles use \`playwright-cli\` as their primary browser interface and must not create nested agents. Ask for missing or contradictory purpose, access, role, data, or safety information before or during planning; do not guess.
+
+${BLOCK_END}`;
+
+const exists = async (file) => {
+  try {
+    await access(file);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const defaultRun = (projectDir, command, args) => new Promise((resolve, reject) => {
+  const child = process.platform === 'win32'
+    ? spawn(process.env.ComSpec ?? 'cmd.exe', ['/d', '/s', '/c', command, ...args], {
+        cwd: projectDir,
+        stdio: 'inherit',
+      })
+    : spawn(command, args, { cwd: projectDir, stdio: 'inherit' });
+  child.on('error', reject);
+  child.on('exit', (code) => code === 0
+    ? resolve()
+    : reject(new Error(`${command} ${args.join(' ')} exited with ${code}`)));
+});
+
+function withManagedBlock(source, managedBlock) {
+  const start = source.indexOf(BLOCK_START);
+  const end = source.indexOf(BLOCK_END);
+
+  if ((start === -1) !== (end === -1) || (start !== -1 && end < start)) {
+    throw new Error('found an incomplete playwright-test-agent managed block');
+  }
+
+  if (start !== -1) {
+    return source.slice(0, start) + managedBlock + source.slice(end + BLOCK_END.length);
+  }
+
+  if (source.length === 0) return `${managedBlock}\n`;
+  const separator = source.endsWith('\n') ? '\n' : '\n\n';
+  return `${source}${separator}${managedBlock}\n`;
+}
+
+async function installSkill(projectDir, skillSourceDir) {
+  for (const root of ['.agents', '.claude']) {
+    const destination = path.join(projectDir, root, 'skills', 'playwright-test-agent');
+    await mkdir(destination, { recursive: true });
+    await cp(skillSourceDir, destination, { recursive: true, force: true });
+  }
+}
+
+async function updateInstructionFiles(projectDir) {
+  const files = [
+    ['AGENTS.md', CODEX_INSTRUCTIONS],
+    ['CLAUDE.md', CLAUDE_INSTRUCTIONS],
+  ];
+  for (const [name, managedBlock] of files) {
+    const file = path.join(projectDir, name);
+    const source = await exists(file) ? await readFile(file, 'utf8') : '';
+    await writeFile(file, withManagedBlock(source, managedBlock), 'utf8');
   }
-};
-
-const defaultRun = (projectDir, command, args) => new Promise((resolve, reject) => {
-  const child = process.platform === 'win32'
-    ? spawn(process.env.ComSpec ?? 'cmd.exe', ['/d', '/s', '/c', command, ...args], {
-        cwd: projectDir,
-        stdio: 'inherit',
-      })
-    : spawn(command, args, { cwd: projectDir, stdio: 'inherit' });
-  child.on('error', reject);
-  child.on('exit', (code) => code === 0
-    ? resolve()
-    : reject(new Error(`${command} ${args.join(' ')} exited with ${code}`)));
-});
-
-function withManagedBlock(source, managedBlock) {
-  const start = source.indexOf(BLOCK_START);
-  const end = source.indexOf(BLOCK_END);
+}
 
+function withRoleBlock(source, role) {
+  const start = source.indexOf(ROLE_BLOCK_START);
+  const end = source.indexOf(ROLE_BLOCK_END);
   if ((start === -1) !== (end === -1) || (start !== -1 && end < start)) {
-    throw new Error('found an incomplete playwright-test-agent managed block');
+    throw new Error('found an incomplete playwright-test-agent CLI role block');
   }
-
   if (start !== -1) {
-    return source.slice(0, start) + managedBlock + source.slice(end + BLOCK_END.length);
-  }
-
-  if (source.length === 0) return `${managedBlock}\n`;
-  const separator = source.endsWith('\n') ? '\n' : '\n\n';
-  return `${source}${separator}${managedBlock}\n`;
-}
-
-async function installSkill(projectDir, skillSourceDir) {
-  for (const root of ['.agents', '.claude']) {
-    const destination = path.join(projectDir, root, 'skills', 'playwright-test-agent');
-    await mkdir(destination, { recursive: true });
-    await cp(skillSourceDir, destination, { recursive: true, force: true });
-  }
-}
-
-async function updateInstructionFiles(projectDir) {
-  const files = [
-    ['AGENTS.md', CODEX_INSTRUCTIONS],
-    ['CLAUDE.md', CLAUDE_INSTRUCTIONS],
-  ];
-  for (const [name, managedBlock] of files) {
-    const file = path.join(projectDir, name);
-    const source = await exists(file) ? await readFile(file, 'utf8') : '';
-    await writeFile(file, withManagedBlock(source, managedBlock), 'utf8');
+    return source.slice(0, start) + cliFirstInstructions(role) +
+      source.slice(end + ROLE_BLOCK_END.length);
   }
+  return `${source.trimEnd()}\n\n${cliFirstInstructions(role)}\n`;
 }
 
-async function patchPlaywrightConfig(projectDir) {
-  const configPath = path.join(projectDir, 'playwright.config.ts');
-  let source = await readFile(configPath, 'utf8');
-  source = source.replace(/testDir:\s*['"]\.\/tests['"]/, "testDir: './playwright-tests'");
-  source = source.replace(
-    /reporter:\s*['"]html['"],?/,
-    "reporter: [['html', { outputFolder: '.playwright-evidence/report', open: 'never' }]],",
-  );
-  source = source.replace(
-    /use:\s*\{/,
-    "outputDir: '.playwright-evidence/test-results',\n  snapshotPathTemplate: '.playwright-evidence/snapshots/{testFilePath}/{arg}{ext}',\n  use: {\n    screenshot: 'only-on-failure',\n    video: 'retain-on-failure',",
-  );
-  source = source.replace(
-    /trace:\s*['"][^'"]+['"]/,
-    "trace: { mode: 'retain-on-failure', screenshots: false, snapshots: true, sources: true, attachments: true }",
-  );
-  await writeFile(configPath, source, 'utf8');
+function tomlMultilineBasicString(value) {
+  const escaped = value
+    .replace(/\\/g, '\\\\')
+    .replace(/"""/g, '\\"\\"\\"')
+    .replace(/\r\n?/g, '\n');
+  return `"""\n${escaped}\n"""`;
 }
 
-function withoutTraceScreenshots(source) {
-  const replacement = "trace: { mode: 'retain-on-failure', screenshots: false, snapshots: true, sources: true, attachments: true }";
-  const fromString = source.replace(/trace:\s*['"][^'"]+['"]/, replacement);
-  if (fromString !== source) return fromString;
-
-  return source.replace(/trace:\s*\{([\s\S]*?)\}/, (setting, body) => {
-    if (/screenshots\s*:/.test(body)) {
-      return setting.replace(/screenshots\s*:\s*(?:true|false)/, 'screenshots: false');
-    }
-    return setting.replace('{', '{ screenshots: false,');
-  });
+function patchCodexRole(source, role) {
+  const pattern = /(^|\n)developer_instructions\s*=\s*"""\r?\n([\s\S]*?)\r?\n"""/;
+  const match = source.match(pattern);
+  if (!match) throw new Error('developer_instructions was not found in a Codex role definition');
+  const updated = withRoleBlock(match[2], role);
+  return source
+    .replace(pattern, `${match[1]}developer_instructions = ${tomlMultilineBasicString(updated)}`)
+    .replace(/^sandbox_mode\s*=\s*"[^"]+"/m, 'sandbox_mode = "workspace-write"');
 }
 
-async function disableTraceScreenshots(projectDir) {
-  const configPath = path.join(projectDir, 'playwright.config.ts');
-  if (!await exists(configPath)) return;
-
-  let source = await readFile(configPath, 'utf8');
-  const updated = withoutTraceScreenshots(source);
-
-  if (updated !== source) {
-    await writeFile(configPath, updated, 'utf8');
+function patchClaudeRole(source, role) {
+  let updated = source;
+  if (!/^\s*-\s+Bash\(playwright-cli:\*\)\s*$/m.test(updated)) {
+    const tools = updated.match(/^tools:\s*\r?\n/m);
+    if (!tools) throw new Error('tools list was not found in a Claude role definition');
+    const insertion = '  - Bash(playwright-cli:*)\n  - Bash(npx:*)\n';
+    updated = updated.slice(0, tools.index + tools[0].length) + insertion +
+      updated.slice(tools.index + tools[0].length);
   }
+  return withRoleBlock(updated, role);
 }
 
-async function configureClaudeMcp(projectDir) {
-  const file = path.join(projectDir, '.mcp.json');
-  if (!await exists(file)) return;
-  const config = JSON.parse(await readFile(file, 'utf8'));
-  const server = config.mcpServers?.['playwright-test'];
-  if (!server) return;
-  server.env = {
-    ...(server.env ?? {}),
-    PLAYWRIGHT_MCP_OUTPUT_DIR: '.playwright-evidence/mcp',
-  };
-  await writeFile(file, `${JSON.stringify(config, null, 2)}\n`, 'utf8');
-}
-
-async function configureCodexAgents(projectDir) {
-  for (const name of ['planner', 'generator', 'healer']) {
-    const file = path.join(projectDir, '.codex', 'agents', `playwright_test_${name}.toml`);
-    if (!await exists(file)) continue;
-    let source = await readFile(file, 'utf8');
-    if (!source.includes('[mcp_servers.playwright-test.env]')) {
-      source = `${source.trimEnd()}\n\n[mcp_servers.playwright-test.env]\n` +
-        'PLAYWRIGHT_MCP_OUTPUT_DIR = ".playwright-evidence/mcp"\n';
-      await writeFile(file, source, 'utf8');
+async function configureCliFirstRoles(projectDir) {
+  const roles = ['planner', 'generator', 'healer'];
+  for (const role of roles) {
+    const claudeFile = path.join(projectDir, '.claude', 'agents', `playwright-test-${role}.md`);
+    if (await exists(claudeFile)) {
+      const source = await readFile(claudeFile, 'utf8');
+      await writeFile(claudeFile, patchClaudeRole(source, role), 'utf8');
     }
-  }
-}
 
-async function initializePlaywright(projectDir, run) {
-  const configPath = path.join(projectDir, 'playwright.config.ts');
-  if (!await exists(configPath)) {
-    await run(projectDir, 'npm', [
-      'init',
-      'playwright@latest',
-      '--',
-      '--quiet',
-      '--lang=TypeScript',
-      '--browser=chromium',
-    ]);
-
-    const generatedExample = path.join(projectDir, 'tests', 'example.spec.ts');
-    const targetDir = path.join(projectDir, 'playwright-tests');
-    if (await exists(generatedExample)) {
-      await mkdir(targetDir, { recursive: true });
-      await rename(generatedExample, path.join(targetDir, 'example.spec.ts'));
+    const codexFile = path.join(projectDir, '.codex', 'agents', `playwright_test_${role}.toml`);
+    if (await exists(codexFile)) {
+      const source = await readFile(codexFile, 'utf8');
+      await writeFile(codexFile, patchCodexRole(source, role), 'utf8');
     }
-    await patchPlaywrightConfig(projectDir);
   }
-
-  await disableTraceScreenshots(projectDir);
-
-  await run(projectDir, 'npx', ['--no-install', 'playwright', 'init-agents', '--loop=codex']);
-  await run(projectDir, 'npx', ['--no-install', 'playwright', 'init-agents', '--loop=claude']);
-  await mkdir(path.join(projectDir, '.playwright-evidence', 'mcp'), { recursive: true });
-  await configureClaudeMcp(projectDir);
-  await configureCodexAgents(projectDir);
 }
 
-async function runStage(name, action) {
-  process.stdout.write(`[playwright-test-agent] ${name}...\n`);
-  try {
-    await action();
-  } catch (error) {
-    throw new Error(`${name}: ${error.message}`, { cause: error });
-  }
+async function installPlaywrightCli(projectDir, run) {
+  await run(projectDir, 'npm', ['install', '-g', '@playwright/cli@latest']);
+  await run(projectDir, 'playwright-cli', ['install', '--skills=agents', '--global']);
+  await run(projectDir, 'playwright-cli', ['install', '--skills', '--global']);
+  await run(projectDir, 'playwright-cli', ['install-browser']);
 }
-
-export async function initializeProject({
-  projectDir = process.cwd(),
-  skillSourceDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'),
-  run = defaultRun,
-} = {}) {
-  const target = path.resolve(projectDir);
-  await mkdir(target, { recursive: true });
-
+
+async function patchPlaywrightConfig(projectDir) {
+  const configPath = path.join(projectDir, 'playwright.config.ts');
+  let source = await readFile(configPath, 'utf8');
+  source = source.replace(/testDir:\s*['"]\.\/tests['"]/, "testDir: './playwright-tests'");
+  source = source.replace(
+    /reporter:\s*['"]html['"],?/,
+    "reporter: [['html', { outputFolder: '.playwright-evidence/report', open: 'never' }]],",
+  );
+  source = source.replace(
+    /use:\s*\{/,
+    "outputDir: '.playwright-evidence/test-results',\n  snapshotPathTemplate: '.playwright-evidence/snapshots/{testFilePath}/{arg}{ext}',\n  use: {\n    screenshot: 'only-on-failure',\n    video: 'retain-on-failure',",
+  );
+  source = source.replace(
+    /trace:\s*['"][^'"]+['"]/,
+    "trace: { mode: 'retain-on-failure', screenshots: false, snapshots: true, sources: true, attachments: true }",
+  );
+  await writeFile(configPath, source, 'utf8');
+}
+
+function withoutTraceScreenshots(source) {
+  const replacement = "trace: { mode: 'retain-on-failure', screenshots: false, snapshots: true, sources: true, attachments: true }";
+  const fromString = source.replace(/trace:\s*['"][^'"]+['"]/, replacement);
+  if (fromString !== source) return fromString;
+
+  return source.replace(/trace:\s*\{([\s\S]*?)\}/, (setting, body) => {
+    if (/screenshots\s*:/.test(body)) {
+      return setting.replace(/screenshots\s*:\s*(?:true|false)/, 'screenshots: false');
+    }
+    return setting.replace('{', '{ screenshots: false,');
+  });
+}
+
+async function disableTraceScreenshots(projectDir) {
+  const configPath = path.join(projectDir, 'playwright.config.ts');
+  if (!await exists(configPath)) return;
+
+  let source = await readFile(configPath, 'utf8');
+  const updated = withoutTraceScreenshots(source);
+
+  if (updated !== source) {
+    await writeFile(configPath, updated, 'utf8');
+  }
+}
+
+async function configureClaudeMcp(projectDir) {
+  const file = path.join(projectDir, '.mcp.json');
+  if (!await exists(file)) return;
+  const config = JSON.parse(await readFile(file, 'utf8'));
+  const server = config.mcpServers?.['playwright-test'];
+  if (!server) return;
+  server.env = {
+    ...(server.env ?? {}),
+    PLAYWRIGHT_MCP_OUTPUT_DIR: '.playwright-evidence/mcp',
+  };
+  await writeFile(file, `${JSON.stringify(config, null, 2)}\n`, 'utf8');
+}
+
+async function configureCodexAgents(projectDir) {
+  for (const name of ['planner', 'generator', 'healer']) {
+    const file = path.join(projectDir, '.codex', 'agents', `playwright_test_${name}.toml`);
+    if (!await exists(file)) continue;
+    let source = await readFile(file, 'utf8');
+    if (!source.includes('[mcp_servers.playwright-test.env]')) {
+      source = `${source.trimEnd()}\n\n[mcp_servers.playwright-test.env]\n` +
+        'PLAYWRIGHT_MCP_OUTPUT_DIR = ".playwright-evidence/mcp"\n';
+      await writeFile(file, source, 'utf8');
+    }
+  }
+}
+
+async function initializePlaywright(projectDir, run) {
+  const configPath = path.join(projectDir, 'playwright.config.ts');
+  if (!await exists(configPath)) {
+    await run(projectDir, 'npm', [
+      'init',
+      'playwright@latest',
+      '--',
+      '--quiet',
+      '--lang=TypeScript',
+      '--browser=chromium',
+    ]);
+
+    const generatedExample = path.join(projectDir, 'tests', 'example.spec.ts');
+    const targetDir = path.join(projectDir, 'playwright-tests');
+    if (await exists(generatedExample)) {
+      await mkdir(targetDir, { recursive: true });
+      await rename(generatedExample, path.join(targetDir, 'example.spec.ts'));
+    }
+    await patchPlaywrightConfig(projectDir);
+  }
+
+  await disableTraceScreenshots(projectDir);
+
+  await run(projectDir, 'npx', ['--no-install', 'playwright', 'init-agents', '--loop=codex']);
+  await run(projectDir, 'npx', ['--no-install', 'playwright', 'init-agents', '--loop=claude']);
+  await mkdir(path.join(projectDir, '.playwright-evidence', 'mcp'), { recursive: true });
+  await configureClaudeMcp(projectDir);
+  await configureCodexAgents(projectDir);
+  await configureCliFirstRoles(projectDir);
+}
+
+async function runStage(name, action) {
+  process.stdout.write(`[playwright-test-agent] ${name}...\n`);
+  try {
+    await action();
+  } catch (error) {
+    throw new Error(`${name}: ${error.message}`, { cause: error });
+  }
+}
+
+export async function initializeProject({
+  projectDir = process.cwd(),
+  skillSourceDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'),
+  run = defaultRun,
+} = {}) {
+  const target = path.resolve(projectDir);
+  await mkdir(target, { recursive: true });
+
   await runStage('installing skill', () => installSkill(target, skillSourceDir));
+  await runStage('installing Playwright CLI and browser', () => installPlaywrightCli(target, run));
   await runStage('initializing Playwright Test agents', () => initializePlaywright(target, run));
-  await runStage('updating project instructions', () => updateInstructionFiles(target));
-
-  process.stdout.write(
-    'Playwright Test Agent ready: skills installed for Codex and Claude, ' +
-    'tests in playwright-tests/, evidence in .playwright-evidence/.\n',
-  );
-}
-
-const isDirectInvocation = process.argv[1] &&
-  path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url));
-
-if (isDirectInvocation) {
-  initializeProject({ projectDir: process.argv[2] ?? process.cwd() }).catch((error) => {
-    console.error(`Playwright initialization failed: ${error.message}`);
-    process.exitCode = 1;
-  });
-}
+  await runStage('updating project instructions', () => updateInstructionFiles(target));
+
+  process.stdout.write(
+    'Playwright Test Agent ready: Playwright CLI and skills installed globally, ' +
+    'agent definitions configured CLI-first for Codex and Claude, ' +
+    'tests in playwright-tests/, evidence in .playwright-evidence/.\n',
+  );
+}
+
+const isDirectInvocation = process.argv[1] &&
+  path.resolve(process.argv[1]) === path.resolve(fileURLToPath(import.meta.url));
+
+if (isDirectInvocation) {
+  initializeProject({ projectDir: process.argv[2] ?? process.cwd() }).catch((error) => {
+    console.error(`Playwright initialization failed: ${error.message}`);
+    process.exitCode = 1;
+  });
+}