@assertrx/dino 1.0.0

package/extensions/playwright-mcp.ts

@@ -0,0 +1,142 @@
+/**
+ * Bridge Microsoft Playwright MCP tools into pi.dev as custom tools.
+ *
+ * This extension spawns `@playwright/mcp` as a local stdio MCP server,
+ * lists the tools it exposes, and registers each one with pi so the agent
+ * can call them like any other tool.
+ */
+import { createRequire } from "node:module";
+import path from "node:path";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type, type TSchema } from "typebox";
+
+const require = createRequire(import.meta.url);
+
+function jsonSchemaToTypeBox(schema: unknown): TSchema {
+  if (!schema || typeof schema !== "object") {
+    return Type.Any();
+  }
+  const s = schema as Record<string, any>;
+
+  switch (s.type) {
+    case "object": {
+      const properties: Record<string, TSchema> = {};
+      const required = new Set<string>(s.required ?? []);
+      for (const [key, value] of Object.entries(s.properties ?? {})) {
+        const child = jsonSchemaToTypeBox(value);
+        properties[key] = required.has(key) ? child : Type.Optional(child);
+      }
+      return Type.Object(properties);
+    }
+    case "array":
+      return Type.Array(jsonSchemaToTypeBox(s.items));
+    case "string":
+      return Type.String({ description: s.description });
+    case "number":
+    case "integer":
+      return Type.Number({ description: s.description });
+    case "boolean":
+      return Type.Boolean({ description: s.description });
+    case "null":
+      return Type.Null();
+    default:
+      break;
+  }
+
+  if (Array.isArray(s.enum)) {
+    return Type.Union(s.enum.map((value: unknown) => Type.Literal(value)));
+  }
+
+  return Type.Any({ description: s.description });
+}
+
+export default async function (pi: ExtensionAPI) {
+  let serverPath: string;
+  try {
+    const pkgPath = require.resolve("@playwright/mcp/package.json");
+    serverPath = path.join(path.dirname(pkgPath), "cli.js");
+  } catch {
+    console.warn(
+      "[playwright-mcp] @playwright/mcp is not installed. " +
+        "Run `npm install` in the Dino package directory."
+    );
+    return;
+  }
+
+  const transport = new StdioClientTransport({
+    command: process.execPath,
+    args: [serverPath],
+    stderr: "inherit",
+  });
+
+  const client = new Client({
+    name: "dino-playwright-mcp",
+    version: "0.1.0",
+  });
+
+  try {
+    await client.connect(transport);
+  } catch (err) {
+    console.warn("[playwright-mcp] Could not connect to Playwright MCP server:", err);
+    return;
+  }
+
+  let tools;
+  try {
+    const result = await client.listTools();
+    tools = result.tools;
+  } catch (err) {
+    console.warn("[playwright-mcp] Could not list Playwright MCP tools:", err);
+    return;
+  }
+
+  for (const tool of tools) {
+    pi.registerTool({
+      name: tool.name,
+      label: tool.name,
+      description: tool.description ?? ``,
+      promptSnippet: tool.name.startsWith("browser_")
+        ? `Browser automation via Playwright MCP: ${tool.description ?? tool.name}`
+        : `Playwright MCP tool: ${tool.description ?? tool.name}`,
+      parameters: jsonSchemaToTypeBox(tool.inputSchema),
+      async execute(_toolCallId, params) {
+        const result = await client.callTool({
+          name: tool.name,
+          arguments: (params ?? {}) as Record<string, unknown>,
+        });
+
+        const content = result.content.map((item) => {
+          if (item.type === "text") {
+            return { type: "text" as const, text: item.text };
+          }
+          if (item.type === "image") {
+            return {
+              type: "image" as const,
+              data: item.data,
+              mimeType: item.mimeType,
+            };
+          }
+          return { type: "text" as const, text: JSON.stringify(item) };
+        });
+
+        return { content, details: result };
+      },
+    });
+  }
+
+  console.log(`[playwright-mcp] Registered ${tools.length} Playwright MCP tool(s).`);
+
+  const cleanup = async () => {
+    try {
+      await transport.close();
+      await client.close();
+    } catch {
+      // ignore cleanup errors
+    }
+  };
+  process.on("SIGINT", cleanup);
+  process.on("SIGTERM", cleanup);
+  pi.on("session_shutdown", cleanup);
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@assertrx/dino",
+  "version": "1.0.0",
+  "description": "A friendly purple dinosaur pi package with a custom TUI header, theme, and Playwright skills.",
+  "keywords": [
+    "pi-package"
+  ],
+  "license": "MIT",
+  "author": "",
+  "files": [
+    "extensions",
+    "prompts",
+    "skills",
+    "themes",
+    "README.md",
+    "scripts"
+  ],
+  "scripts": {
+    "start:all": "node scripts/start-dino.mjs",
+    "start:api": "node scripts/start-dino.mjs",
+    "postinstall": "npx playwright install chromium"
+  },
+  "dependencies": {
+    "@mablhq/mabl-cli": "^2.127.20",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@playwright/cli": "^0.1.18",
+    "@playwright/mcp": "^0.0.79",
+    "typebox": "^1.1.38"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ],
+    "prompts": [
+      "./prompts"
+    ],
+    "skills": [
+      "./skills"
+    ],
+    "themes": [
+      "./themes"
+    ]
+  }
+}

package/prompts/create-pr.md

@@ -0,0 +1,110 @@
+---
+description: Create a GitHub PR for current changes, installing gh and git setup if needed
+---
+
+Create a GitHub pull request for the changes in the current workspace. Install the GitHub CLI (`gh`) if it is missing, and handle both existing git repos and brand-new projects.
+
+## Steps
+
+1. **Check for GitHub CLI**.
+   - Run `bash` commands to check `gh --version` or `which gh`.
+   - If `gh` is present, note the version and continue.
+   - If `gh` is missing, install it:
+     - **macOS / Homebrew**: `brew install gh`
+     - **Windows / winget**: `winget install --id GitHub.cli`
+     - **Windows / chocolatey**: `choco install gh`
+     - **Ubuntu / Debian**: `sudo apt update && sudo apt install -y gh`
+     - **Fedora / RHEL**: `sudo dnf install -y gh`
+   - After installing, verify with `gh --version`.
+
+2. **Check `gh` authentication**.
+   - Run `gh auth status`.
+   - If not authenticated, ask the user to run `gh auth login` manually (do not paste tokens into chat). Do not proceed until authenticated.
+
+3. **Detect git project state**.
+   - Check whether `.git` exists in the current workspace.
+
+### A. Existing git project
+
+If `.git` exists:
+
+1. **Inspect changes**.
+   - Run `git status --short` to see modified/untracked files.
+   - Show the user a concise summary of the changes.
+
+2. **Prepare a branch**.
+   - Get the current branch with `git branch --show-current`.
+   - If currently on `main` or `master`, create and switch to a feature branch:
+     ```bash
+     git checkout -b update/<short-description>
+     ```
+   - Use a descriptive branch name based on the changes.
+
+3. **Configure git identity if needed**.
+   - Run `git config user.name` and `git config user.email`.
+   - If either is missing, ask the user for a name and email, then set them locally:
+     ```bash
+     git config user.name "Name"
+     git config user.email "email@example.com"
+     ```
+
+4. **Commit and push**.
+   - Stage the relevant changes with `git add`.
+   - Commit with a clear message. Ask the user for a message if one is not obvious, or use a sensible default summarizing the changes.
+   - Push the branch:
+     ```bash
+     git push -u origin <branch-name>
+     ```
+
+5. **Create the pull request**.
+   - Use `gh pr create` with non-interactive flags:
+     ```bash
+     gh pr create --title "<title>" --body "<body>" --base <base-branch>
+     ```
+   - Derive the PR title and body from the commit message and changed files.
+   - If a PR already exists for this branch, run `gh pr view <branch>` and report the URL instead.
+
+### B. New project without git
+
+If `.git` does not exist:
+
+1. **Ask the user** for:
+   - The desired GitHub repository name.
+   - Whether it should be public or private.
+   - The GitHub owner/organization (default to the authenticated user).
+
+2. **Create the remote repository**.
+   - Run:
+     ```bash
+     gh repo create <owner>/<repo> --<public|private> --source=. --remote=origin --push
+     ```
+   - If the user only provided a repo name without an owner, use `gh repo create <repo> --<public|private> --source=. --remote=origin --push`.
+
+3. **Configure git identity**.
+   - Ask for name and email if not already set globally.
+
+4. **Commit the current code**.
+   - Run:
+     ```bash
+     git add .
+     git commit -m "Initial commit"
+     git push -u origin main
+     ```
+   - If `main` is not the default branch name, use `master` or ask the user.
+
+5. **Report the repository URL**.
+
+## Rules
+
+- Never paste credentials or tokens into the chat.
+- Ask the user before creating a public repo if privacy matters.
+- Do not run `gh auth login` automatically; prompt the user to authenticate manually.
+- Do not overwrite or ignore local git configuration without asking.
+- If there are no changes to commit, report that and stop.
+- Keep the PR title/body concise and relevant to the actual changes.
+
+After completing, summarize:
+- Whether `gh` was installed or already present.
+- The repository and branch used.
+- The commit message and PR URL (if created).
+- Any errors or manual steps the user still needs to take.

package/prompts/generate-bdd-from-url.md

@@ -0,0 +1,65 @@
+---
+description: Generate exhaustive Gherkin BDD scenarios for a single page using the bdd-gherkin skill
+argument-hint: "<URL> [output-dir]"
+---
+
+Use the `bdd-gherkin` skill and `playwright-cli` commands to inspect the page at $1 and generate exhaustive Gherkin BDD scenarios for **that page only**. Fall back to the Playwright MCP bridge (`browser_*` tools) only if `playwright-cli` is unavailable or fails.
+
+## Preferred tooling
+
+- **Primary:** `playwright-cli` (`open`, `snapshot`, `goto`, `click`, `fill`, etc.)
+- **Fallback:** Playwright MCP (`browser_navigate`, `browser_snapshot`, etc.)
+
+## Workflow
+
+1. **Load the BDD skill**.
+   - Read `skills/bdd-gherkin/SKILL.md` first and follow its rules.
+
+2. **Inspect the target page with `playwright-cli` first**.
+   - Check whether `playwright-cli` is on PATH. If not, use `npx -p @playwright/cli playwright-cli ...`.
+   - Run `playwright-cli open $1` to load the page.
+   - Run `playwright-cli snapshot` to capture the accessibility tree, visible fields, buttons, links, tables, and any validation/error messages.
+   - If `playwright-cli` cannot be resolved or its commands fail, fall back to the Playwright MCP bridge: use `browser_navigate` to load $1 and `browser_snapshot` to inspect it.
+   - If the page requires authentication and an env file is provided, follow the secure login flow from the `playwright-cli` skill.
+   - Identify the primary actor(s), the business capability the page supports, and every interactive element or workflow step on the page.
+   - Do **not** navigate away from the page; generate scenarios for the page pointed to by $1 only.
+
+3. **Derive business context**.
+   - From the page content, determine:
+     - The business feature/capability (e.g., "Transfer Money", "User Login", "Apply for Loan").
+     - The primary actor(s) (e.g., customer, admin, visitor).
+     - The business value provided by the page.
+     - Required fields, optional fields, constraints, and possible outcomes.
+   - If the page is ambiguous or critical business rules are not visible (e.g., user roles, backend rules), ask **one or two concise clarifying questions** before generating scenarios. Otherwise, proceed directly.
+
+4. **Generate exhaustive Gherkin scenarios**.
+   Cover the following categories for the page:
+
+   - **Happy path** — successful completion of the primary action.
+   - **Validation / invalid input** — missing required fields, malformed input, out-of-range values, wrong formats.
+   - **Edge cases** — boundary values, empty input, maximum/minimum lengths, special characters, whitespace, zero/null amounts.
+   - **Business rules / state-based cases** — preconditions that affect behavior (e.g., insufficient balance, locked account, existing record).
+   - **Error / negative cases** — visible error messages, disabled actions, failed submissions.
+   - **UI / interaction cases** — toggles, show/hide password, dropdown dependencies, disabled fields, cancel/reset actions.
+   - **Accessibility / usability cases** — keyboard focus, visible labels, error announcement (if inferable from the page).
+
+5. **Follow Gherkin best practices**.
+   - Use a single-focused Scenario for each behavior.
+   - Use **exactly one `When` action per scenario**; move setup details into `Given` or `Background`.
+   - Use `Background` liberally for shared preconditions.
+   - Use data tables when a `Given` step has two or more fields.
+   - Use business language, not Selenium/implementation detail.
+   - Include a business value statement (`As a ... I want ... So that ...`) when it adds clarity.
+   - Use Scenario Outlines only when data variation is the central focus.
+   - Keep tags minimal.
+
+6. **Save the feature file**.
+   - Write the generated Gherkin to `${2:-tests/features/}/<page-name>.feature`.
+   - Use a clear, kebab-case file name derived from the page (e.g., `transfer-money-page.feature`, `login-page.feature`).
+   - If the page supports multiple distinct capabilities, split into multiple feature files in the output directory.
+
+## Output
+
+- The saved `.feature` file path(s).
+- A brief summary of the scenario categories covered (happy path, validation, edge cases, errors, etc.).
+- Any clarifying assumptions made about business rules or user roles.

package/prompts/generate-pom-from-url-cli.md

@@ -0,0 +1,48 @@
+---
+description: Generate Playwright Page Object Models from a live URL using playwright-cli
+argument-hint: "<URL> [output-dir] [auth-env-file]"
+---
+
+Use the `playwright-pom` skill and `playwright-cli` commands to generate Page Object Models from the website at $1.
+
+Scope and rules:
+- Start at $1 and explore only pages on the same origin.
+- Use `playwright-cli open <url>` to launch the browser. If `playwright-cli` is not on PATH, use `npx -p @playwright/cli playwright-cli open <url>` instead.
+- Use `playwright-cli snapshot` to capture the accessibility tree and element refs for each page.
+- Use `playwright-cli goto <url>` or `playwright-cli click <ref>` to navigate to additional pages.
+- Generate one focused page object per unique page or reusable component.
+- Use resilient locators: `getByRole`, `getByLabel`, `getByTestId`, `getByPlaceholder`, `getByText` (in that order). Use CSS/XPath only as a last resort.
+- Each page object should expose high-level business methods (e.g., `loginAs(user)`, `searchFor(term)`) built from the low-level locators.
+- Keep selectors and URLs inside the page object; tests should read like user workflows.
+- Save generated files under `${2:-tests/pom/}` with clear, kebab-case names (e.g., `login-page.ts`).
+- Only target applications you own or have explicit authorization to test.
+- Do not interact with destructive actions (delete, remove, sign out) unless explicitly requested.
+- Stop after covering the main interactive pages; report which pages were generated and which were skipped.
+
+## Authentication
+
+If the site requires login, handle credentials securely:
+
+1. **Preferred: provide an auth env file** as the third argument (`$3`).
+   - The env file should contain variables such as:
+     ```bash
+     POM_AUTH_URL=https://example.com/login
+     POM_USERNAME=user@example.com
+     POM_PASSWORD=secret
+     ```
+   - Load the file in a single bash command, use the variables immediately to fill the login form via `playwright-cli fill`/`click`, and **do not echo, log, or persist the values anywhere**.
+   - Do not include the env file in generated POMs, snapshots, or test code.
+   - Mark the env file in `.gitignore` and delete it when the session is complete.
+   - After logging in, you may use `playwright-cli state-save <file>` to persist the authenticated session if you need to revisit pages.
+
+2. **Fallback: manual login**.
+   - If no env file is provided, `playwright-cli open` the login page and ask the user to complete authentication manually in the browser session.
+   - Then continue generating POMs from the authenticated state.
+
+3. **Never** ask the user to paste credentials into the chat, and **never** hardcode credentials into generated files.
+
+After generating, summarize:
+- The pages and components covered
+- The output file paths
+- Any pages that could not be inspected and why
+- How authentication was handled (env file or manual)

package/prompts/generate-pom-from-url.md

@@ -0,0 +1,45 @@
+---
+description: Generate Playwright Page Object Models from a live URL using the Playwright MCP bridge
+argument-hint: "<URL> [output-dir] [auth-env-file]"
+---
+
+Use the `playwright-pom` skill and the Playwright MCP `browser_*` tools to generate Page Object Models from the website at $1.
+
+Scope and rules:
+- Start at $1 and explore only pages on the same origin.
+- Use `browser_navigate` to open each page and `browser_snapshot` to inspect the accessibility tree.
+- Generate one focused page object per unique page or reusable component.
+- Use resilient locators: `getByRole`, `getByLabel`, `getByTestId`, `getByPlaceholder`, `getByText` (in that order). Use CSS/XPath only as a last resort.
+- Each page object should expose high-level business methods (e.g., `loginAs(user)`, `searchFor(term)`) built from the low-level locators.
+- Keep implementation details (selectors, URLs) inside the page object; tests should read like user workflows.
+- Save the generated files under `${2:-tests/pom/}` using clear, kebab-case names (e.g., `login-page.ts`).
+- Only target applications you own or have explicit authorization to test.
+- Do not interact with destructive actions (delete, remove, sign out) unless explicitly requested.
+- Stop after covering the main interactive pages; report which pages were generated and which were skipped.
+
+## Authentication
+
+If the site requires login, handle credentials securely:
+
+1. **Preferred: provide an auth env file** as the third argument (`$3`).
+   - The env file should contain variables such as:
+     ```bash
+     POM_AUTH_URL=https://example.com/login
+     POM_USERNAME=user@example.com
+     POM_PASSWORD=secret
+     ```
+   - Load the file in a single bash command, use the values immediately to log in via `browser_navigate` + `browser_fill_form`/`browser_type`, and **do not echo, log, or persist the values anywhere**.
+   - Do not include the env file in generated POMs, snapshots, or test code.
+   - Mark the env file in `.gitignore` and delete it when the session is complete.
+
+2. **Fallback: manual login**.
+   - If no env file is provided, `browser_navigate` to the login page and ask the user to complete login manually in the browser session.
+   - Then continue generating POMs from the authenticated state.
+
+3. **Never** ask the user to paste credentials into the chat, and **never** hardcode credentials into generated files.
+
+After generating, summarize:
+- The pages and components covered
+- The output file paths
+- Any pages that could not be inspected and why
+- How authentication was handled (env file or manual)

package/prompts/generate-spec-from-feature.md

@@ -0,0 +1,64 @@
+---
+description: Generate a Playwright test spec from a Gherkin feature file, reusing existing POMs
+argument-hint: "<URL> <feature-file> <pom-dir> [output-dir]"
+---
+
+Generate a TypeScript Playwright test spec file that implements the Gherkin scenarios from `$2` for the page at `$1`, reusing existing Page Object Models from `$3`. Create new POMs only when absolutely necessary.
+
+## Inputs
+
+- `$1` — URL of the page under test (used to inspect current UI state and validate selectors).
+- `$2` — Path to the `.feature` file to implement.
+- `$3` — Directory containing existing POM `.ts` files.
+- `$4` — Optional output directory for the generated spec. Defaults to `tests/specs/`.
+
+## Workflow
+
+1. **Load the Playwright skill**.
+   - Read `skills/playwright-core/SKILL.md` to follow Playwright best practices.
+
+2. **Inspect the page at `$1`**.
+   - Prefer `playwright-cli` (`open`, `snapshot`). If unavailable, fall back to Playwright MCP (`browser_navigate`, `browser_snapshot`).
+   - Capture the accessibility tree, form fields, buttons, links, tables, and any visible validation or error messages.
+   - Do not navigate away from the page unless required to verify a shared component.
+
+3. **Read the feature file**.
+   - Read `$2` with the `read` tool.
+   - Parse every `Scenario`, `Scenario Outline`, and `Examples` table.
+   - Note the `Feature`, `Background`, actors, and expected outcomes.
+
+4. **Discover available POMs**.
+   - List all `.ts` files in `$3` using `bash` (e.g., `find $3 -name "*.ts"`).
+   - Read every POM file to understand:
+     - Which page/component it represents.
+     - The public locators and high-level business methods (e.g., `loginAs`, `initiateTransfer`).
+     - Whether an exported `test` fixture file exists (e.g., `fixtures.ts`, `index.ts`).
+   - Build a mental map of reusable components and cross-page navigation helpers (e.g., `BankLayout`).
+
+5. **Map scenarios to POM methods**.
+   - For each Gherkin scenario, decide which existing POM(s) implement the necessary actions and assertions.
+   - Reuse existing business methods whenever possible; do not duplicate selector logic in the spec.
+   - If a scenario needs a component that is not yet modeled, first check whether it belongs in an existing POM (e.g., a shared layout component, a dialog in a page POM). Only create a new POM file if the gap is significant and reusable.
+
+6. **Generate the Playwright spec**.
+   - Write a `.spec.ts` file under `${4:-tests/specs/}` using kebab-case naming derived from the feature (e.g., `login-page.spec.ts`).
+   - Use existing fixtures if `$3` exports a `test` object (e.g., `import { test, expect } from '../pom'`). Otherwise, import POM classes and instantiate them in a `test.beforeEach` or per-test helper.
+   - Each Gherkin scenario should map to one Playwright `test(...)`.
+   - Use `test.describe` to group tests by feature or capability when helpful.
+   - Use `test.beforeEach` for shared `Background` preconditions.
+   - Use `expect` assertions that match the `Then` steps.
+   - For `Scenario Outline` `Examples`, generate one test per example row or use a parameterized loop with `test.each`/`test.describe.each`.
+   - Keep tests readable and free of low-level selectors; all selectors should come from POMs.
+
+7. **Cross-check against the live page**.
+   - Where practical, verify that the POM methods used in the generated spec actually match the live page elements observed in step 2.
+   - If a POM method name suggests behavior that differs from the current page, prefer updating the POM method call or asking the user rather than hardcoding selectors in the spec.
+
+## Output
+
+- Save the generated spec file to `${4:-tests/specs/}<feature-name>.spec.ts`.
+- Report:
+  - The spec file path.
+  - Which POM files were reused and how.
+  - Any POMs that were updated or newly created (should be rare).
+  - Any scenarios that could not be mapped to existing POMs and why.

package/prompts/heal-playwright-failures.md

@@ -0,0 +1,106 @@
+---
+description: Detect, diagnose, and auto-heal failed Playwright tests by updating selectors, waits, and assertions, then re-run to verify
+argument-hint: "[test-pattern] [max-iterations]"
+---
+
+Run the Playwright test suite, detect failures, diagnose the root cause of each failing test, apply safe fixes, and re-run until the tests pass or the retry budget is exhausted. Only target applications and test code you own or have authorization to modify.
+
+## Steps
+
+1. **Inspect the workspace**.
+   - Use `bash` to list the project root and locate `playwright.config.ts`, `playwright.config.js`, or the configured `testDir`.
+   - Identify the test command from `package.json` (e.g., `test:e2e`, `test`, `e2e`).
+   - Determine whether the user supplied a test pattern in `$1`; if not, use the default project test command or `npx playwright test`.
+
+2. **Run the tests and capture structured results**.
+   - Prefer running with JSON and line reporters so failures are machine-readable:
+     ```bash
+     npx playwright test <pattern> --reporter=line,json --output=./test-results
+     ```
+   - Save JSON output to a file, e.g. `./test-results/playwright-results.json`.
+   - If running all tests is too slow, first list tests with `npx playwright test --list`, then run only the failing subset once identified.
+
+3. **Parse failures**.
+   - From the JSON report, collect each failed test: file path, test title, project/browser, error message, and the last run attempt.
+   - Count distinct failures. If zero failures, stop and report success.
+
+4. **Gather diagnostics for each failure**.
+   - Locate the trace archive for each failing test under `./test-results/` (typically `<test-file>-<project>-<hash>/trace.zip`).
+   - Locate screenshots and videos in the same output directory.
+   - Read the failing test source file using `read`.
+   - Open the trace to inspect the DOM, locator resolution, network, and console errors:
+     ```bash
+     npx playwright show-trace <path-to-trace.zip>
+     ```
+     or, if unavailable, use `npx playwright test <file> --trace on` and re-run.
+   - Extract the relevant failing line, the locator used, the expected value, and any surrounding context (fixtures, setup, teardown).
+
+5. **Classify the root cause**.
+   For each failure, decide which category applies:
+   - **Locator broken** — selector no longer matches an element (renamed class/id, removed element, dynamic content).
+   - **Timing / flakiness** — element appears but assertion or action races with rendering/network/JS.
+   - **Assertion mismatch** — expected text/URL/value changed legitimately (UI copy, route, data).
+   - **Environment / data** — missing dependency, wrong baseURL, test data conflict, auth expired, viewport.
+   - **Real product bug** — failure represents an actual regression; not safe to auto-heal.
+
+6. **Apply safe auto-heals**.
+   Only make changes when the cause is clearly one of the first four categories. Prefer minimal, resilient edits:
+   - **Fix locators**:
+     - Replace brittle CSS/XPath selectors with semantic Playwright locators in this priority order: `getByRole`, `getByLabel`, `getByPlaceholder`, `getByText`, `getByTestId`.
+     - If a dynamic class is unavoidable, prefer stable attributes (`data-testid`, `aria-label`, role + name) over class names.
+   - **Fix timing / flakiness**:
+     - Add explicit waits via web-first assertions (`await expect(locator).toBeVisible()`).
+     - Use `page.waitForURL`, `page.waitForLoadState`, or `page.waitForResponse` when navigation/network is involved.
+     - Remove `page.waitForTimeout` if present; replace with deterministic waits.
+   - **Fix assertions**:
+     - Use `expect(locator).toHaveText(/partial/)` or `toContainText` instead of exact string assertions when copy is volatile.
+     - Update URLs to match current routing only if the new route is clearly correct.
+   - **Fix environment/data**:
+     - Adjust `baseURL`, test fixtures, or setup steps.
+     - Regenerate or reseed test data if it is clearly stale.
+   - Avoid sweeping rewrites. Edit only the failing tests and helper functions directly responsible.
+
+7. **Re-run failed tests**.
+   - Run only the previously failing tests with the same reporter setup.
+   - Capture results and compare with the previous run.
+
+8. **Iterate with a retry budget**.
+   - Use `max-iterations` from `$2`; default to `3` if not provided.
+   - Repeat steps 3–7 until either all targeted tests pass or the budget is exhausted.
+   - If a fix introduces a new failure, revert that change before trying an alternative.
+
+9. **Report and escalate**.
+   - If all targeted tests pass after healing, report the changes and verification results.
+   - If failures remain, summarize:
+     - Which tests still fail.
+     - The most likely root cause (locator, timing, assertion, environment, product bug).
+     - The trace/screenshot paths for human inspection.
+     - Recommended next steps or a proposed fix that requires user confirmation.
+
+## Rules
+
+- Do not auto-heal tests against applications you do not own or have explicit authorization to test.
+- Do not blindly weaken assertions to make tests pass when the failure signals a real product regression.
+- Do not change production application source code; only modify test files, page objects, fixtures, and config.
+- Prefer `getByRole`/`getByTestId` over CSS/XPath; keep selectors as resilient as possible.
+- Never use `page.waitForTimeout` as a fix; always prefer deterministic waits.
+- Keep one behavior per test; do not bundle unrelated fixes into a single large edit.
+- Use `edit` for precise test/code changes; use `write` only for new files or complete rewrites you author.
+- Preserve TypeScript types and existing code style.
+- Do not delete trace archives, screenshots, or videos; they are the primary diagnostic artifacts.
+- Stop iterating if a failure clearly indicates a product bug or requires human product decisions (copy, routing, data).
+
+## Safety check before editing
+
+For each proposed change, verify:
+1. The original failing line and error message are clearly understood.
+2. The fix addresses the diagnosed root cause, not just the symptom.
+3. The change follows Playwright best practices from the `playwright-core` skill.
+4. The same test passes after the fix in the next iteration.
+
+After completing, summarize:
+- Total failures found and the iteration count used.
+- Files modified and the nature of each fix (locator, wait, assertion, fixture, config).
+- Final test run results.
+- Any remaining failures, their likely root cause, and the paths to trace/screenshot artifacts.
+- Any changes that need human review before merging.