playwright-test-agent 0.1.6 → 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,
-configure the project MCP servers, 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;
-  }
-}
+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.6",
-  "description": "Initialize Playwright Test, its agents, MCP configuration, and 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,64 +1,54 @@
 ---
 name: playwright-test-agent
-description: Use first when a user asks to investigate or test a website, browser workflow, HTTP API, or application feature with Playwright, including test planning, generation, execution, debugging, healing, and evidence collection.
+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's Planner -> Generator -> Healer workflow for durable, auditable tests. `AGENTS.md` or `CLAUDE.md` defines how the active platform assumes or launches those roles; this Skill contains only their shared workflow.
+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.
 
 ## Prepare the objective
 
-The main agent may inspect the local project for relevant requirements, routes, fixtures, and constraints. Do not require a setup audit or check for a seed, Playwright config, or generated files before beginning Planner.
+The main agent may inspect the local project for relevant requirements, routes, fixtures, and constraints. Do not require a seed/config audit before planning.
 
-Before planning, ask the user for information that could materially change the test purpose, scope, safety, or expected behavior, such as the deployed URL, intended role, success criteria, allowed data mutations, and required environment. Do not ask for UI details Planner can safely discover.
+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.
 
-If the request is sufficient, begin Planner immediately. If investigation reveals that a URL, credential, role, prerequisite, expected result, or authorization boundary is missing, incorrect, or contradictory, pause Planner and ask for the specific correction. Resume Planner with the corrected information and blocking observation. Do not guess credentials, probe nearby environments, bypass access controls, or wander through unrelated pages.
+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.
 
 Keep credentials and tokens in environment variables or ignored secret files. Never copy them into plans, tests, screenshots, evidence, or chat.
 
 ## Planner
 
-Planner owns live application investigation and saves a human-readable Markdown plan under `specs/`. Start page setup immediately. Supply a seed only when the user or request explicitly identifies one; otherwise allow Playwright to use its initialized default. Do not perform a separate seed/config discovery pass.
+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.
 
-The plan contains prerequisites, test data requirements, independent scenarios, steps, observable expected results, exclusions, and intended test outputs. Reconnaissance must not create durable/shared data or perform purchases, submissions, messages, deletion, or other consequential actions unless the user authorized them.
+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.
 
-Show the completed scenario list and exclusions to the user. Generator may start only after the user confirms the plan.
+Show the scenario list and exclusions to the user. Generator starts only after confirmation.
 
 ## Generator
 
-Generator converts the complete confirmed Markdown plan into executable Playwright tests and validates locators and assertions against the application. Generate only confirmed scenarios. Prefer independent tests, semantic locators, assertions for every expected result, and environment-based secrets.
+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.
 
-For API-only scenarios, Playwright `APIRequestContext` tests may be written directly. Assert status, headers, schema, stable business invariants, and safe mutation cleanup.
+For API-only scenarios, use Playwright `APIRequestContext` directly and assert status, headers, schema, stable business invariants, and safe mutation cleanup.
 
 ## Healer
 
-Use Healer only for failing generated tests. Diagnose one failing test at a time, replay the failure, inspect the current application state, apply a test-side correction when justified, and rerun within the role's guardrails.
+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.
 
-Do not weaken assertions, add arbitrary sleeps, retry blindly, or skip a test merely to obtain a pass. If behavior conflicts with the confirmed plan, preserve the evidence and ask whether it is a regression or intended product change. Classify unresolved failures as an application defect, test defect, environment/data problem, or product decision.
+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.
 
 ## Evidence
 
-Keep generated evidence under `.playwright-evidence/`:
+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.
 
-```text
-.playwright-evidence/
-|-- mcp/
-|-- snapshots/
-|-- test-results/
-`-- report/
-```
-
-Keep trace DOM snapshots, sources, network data, and attachments, but set trace `screenshots: false`. Trace screenshots are screencast frames and can create hundreds of JPEG resources. Explicit screenshots and failure evidence remain available when needed; avoid secrets and sensitive personal data.
-
-Report the plan path, generated test paths, pass/fail/flaky/skipped counts when tests ran, evidence paths, and failure classification. Never report a skipped or unresolved test as success.
+Report the plan path, generated tests, counts when tests ran, evidence paths, and failure classification. Never report skipped or unresolved tests as success.
 
 ## Initialization
 
-When this Skill or the Playwright Test tools are unavailable, run from the target project:
+Run from the target project:
 
 ```bash
 npx playwright-test-agent init
 ```
 
-The initializer installs the Skill, generates the official role definitions, and configures each platform. Restart the active agent session after initialization so newly configured tools are registered.
+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,339 +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 website, browser workflow, HTTP API, or application-feature testing, first load and follow \`.agents/skills/playwright-test-agent/SKILL.md\`.
-
-Codex must not start \`playwright_test_planner\`, \`playwright_test_generator\`, \`playwright_test_healer\`, or another Playwright subagent. The main agent performs Planner -> Generator -> Healer in the same session with the project-level \`playwright-test\` MCP tools.
-
-For each phase, read the matching generated role definition and follow its \`developer_instructions\` directly:
-- Planner: \`.codex/agents/playwright_test_planner.toml\`; call \`planner_setup_page\`, \`browser_*\`, then \`planner_save_plan\`.
-- Generator: \`.codex/agents/playwright_test_generator.toml\`; call \`generator_setup_page\`, \`browser_*\`, \`generator_read_log\`, then \`generator_write_test\`.
-- Healer: \`.codex/agents/playwright_test_healer.toml\`; call \`test_list\`, \`test_run\`, \`test_debug\`, and relevant \`browser_*\` tools.
-
-These TOML files are role instructions to read, not agents to launch. If the project-level \`playwright-test\` tools are absent, ask the user to rerun \`npx playwright-test-agent init\` and restart Codex; do not create a subagent fallback. Ask for missing or contradictory test-purpose, access, role, data, or safety information before or during Planner, then resume the same phase after clarification. The Skill contains the shared testing rules.
-${BLOCK_END}`;
-
-const CLAUDE_INSTRUCTIONS = `${BLOCK_START}
-## Playwright Test Agent
-
-For website, browser workflow, HTTP API, or application-feature testing, first load and follow \`.claude/skills/playwright-test-agent/SKILL.md\`.
-
-Claude Code uses the official \`playwright-test-planner\`, \`playwright-test-generator\`, and \`playwright-test-healer\` subagents. Start each required role directly and never insert a nested or same-role intermediary. Use Planner for all live website investigation, Generator only after the user confirms the saved plan, and Healer for failing generated tests. Ask for missing or contradictory test-purpose, access, role, data, or safety information before or during Planner, then resume the same phase after clarification. The Skill contains the shared testing rules.
-${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');
-  }
-}
-
-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');
+    return source.slice(0, start) + cliFirstInstructions(role) +
+      source.slice(end + ROLE_BLOCK_END.length);
   }
+  return `${source.trimEnd()}\n\n${cliFirstInstructions(role)}\n`;
 }
 
-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');
+function tomlMultilineBasicString(value) {
+  const escaped = value
+    .replace(/\\/g, '\\\\')
+    .replace(/"""/g, '\\"\\"\\"')
+    .replace(/\r\n?/g, '\n');
+  return `"""\n${escaped}\n"""`;
 }
 
-function normalizeTomlTableName(name) {
-  return name
-    .split('.')
-    .map((part) => part.trim().replace(/^(?:"([^"]+)"|'([^']+)')$/, '$1$2'))
-    .join('.');
+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"');
 }
 
-function findTomlTables(lines, tableName) {
-  const matches = [];
-  for (let index = 0; index < lines.length; index += 1) {
-    const match = lines[index].match(/^\s*\[([^\]]+)\]\s*(?:#.*)?$/);
-    if (match && normalizeTomlTableName(match[1]) === tableName) matches.push(index);
+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 matches;
+  return withRoleBlock(updated, role);
 }
 
-function listTomlTableNames(lines) {
-  return lines
-    .map((line) => line.match(/^\s*\[([^\]]+)\]\s*(?:#.*)?$/))
-    .filter(Boolean)
-    .map((match) => normalizeTomlTableName(match[1]));
-}
-
-function assignmentEnd(lines, start, limit) {
-  let square = 0;
-  let curly = 0;
-  let quote = null;
-  let escaped = false;
-
-  for (let index = start; index < limit; index += 1) {
-    for (const character of lines[index]) {
-      if (escaped) {
-        escaped = false;
-      } else if (quote === '"' && character === '\\') {
-        escaped = true;
-      } else if (quote) {
-        if (character === quote) quote = null;
-      } else if (character === '"' || character === "'") {
-        quote = character;
-      } else if (character === '#') {
-        break;
-      } else if (character === '[') {
-        square += 1;
-      } else if (character === ']') {
-        square -= 1;
-      } else if (character === '{') {
-        curly += 1;
-      } else if (character === '}') {
-        curly -= 1;
-      }
+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');
     }
-    if (square <= 0 && curly <= 0 && !quote) return index + 1;
-  }
-  return limit;
-}
-
-function replaceTomlTable(lines, tableName, assignments, removedKeys = []) {
-  const matches = findTomlTables(lines, tableName);
-  if (matches.length > 1) {
-    throw new Error(`duplicate [${tableName}] tables in .codex/config.toml`);
-  }
-
-  const body = [`[${tableName}]`, ...Object.entries(assignments).map(([key, value]) => `${key} = ${value}`)];
-  if (matches.length === 0) {
-    while (lines.at(-1) === '') lines.pop();
-    if (lines.length > 0) lines.push('');
-    lines.push(...body, '');
-    return;
-  }
 
-  const start = matches[0];
-  let end = start + 1;
-  while (end < lines.length && !/^\s*\[\[?[^\]]+\]\]?\s*(?:#.*)?$/.test(lines[end])) {
-    end += 1;
-  }
-
-  const replacedKeys = new Set([...Object.keys(assignments), ...removedKeys]);
-  const preserved = [];
-  for (let index = start + 1; index < end;) {
-    const match = lines[index].match(/^\s*([A-Za-z0-9_-]+)\s*=/);
-    if (match && replacedKeys.has(match[1])) {
-      index = assignmentEnd(lines, index, end);
-    } else {
-      preserved.push(lines[index]);
-      index += 1;
+    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');
     }
   }
-  while (preserved[0] === '') preserved.shift();
-  while (preserved.at(-1) === '') preserved.pop();
-  lines.splice(start, end - start, ...body, ...(preserved.length ? ['', ...preserved] : []), '');
 }
 
-async function configureCodexMainMcp(projectDir) {
-  const codexDir = path.join(projectDir, '.codex');
-  const file = path.join(codexDir, 'config.toml');
-  await mkdir(codexDir, { recursive: true });
-
-  const source = await exists(file) ? await readFile(file, 'utf8') : '';
-  const lines = source.replace(/\r\n?/g, '\n').split('\n');
-  const command = process.platform === 'win32' ? 'cmd' : 'npx';
-  const args = process.platform === 'win32'
-    ? '["/d", "/s", "/c", "npx", "--no-install", "playwright", "run-test-mcp-server"]'
-    : '["--no-install", "playwright", "run-test-mcp-server"]';
-
-  replaceTomlTable(lines, 'mcp_servers.playwright-test', {
-    command: `"${command}"`,
-    args,
-    cwd: '"."',
-    enabled: 'true',
-    default_tools_approval_mode: '"approve"',
-  }, ['enabled_tools', 'disabled_tools']);
-  replaceTomlTable(lines, 'mcp_servers.playwright-test.env', {
-    PLAYWRIGHT_MCP_OUTPUT_DIR: '".playwright-evidence/mcp"',
-  });
-  for (const tableName of new Set(listTomlTableNames(lines))) {
-    if (tableName.startsWith('mcp_servers.playwright-test.tools.')) {
-      replaceTomlTable(lines, tableName, { approval_mode: '"approve"' });
-    }
-  }
-
-  while (lines.at(-1) === '') lines.pop();
-  await writeFile(file, `${lines.join('\n')}\n`, 'utf8');
+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']);
 }
-
-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 });
+
+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 configureCodexMainMcp(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 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/. ' +
-    'Restart Codex so it loads the project-level playwright-test MCP server.\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;
+  });
+}