# Playwright Pilot AI — Claude Instructions

## CRITICAL: Route all browser/test work through Playwright Pilot AI tools

**NEVER** perform browser actions directly (do not open URLs, click elements, fill forms, or take screenshots using your own capabilities).

**ALWAYS** use `pwpilot_preview_generation` as the first tool when the user sends ANY of the following types of prompts:

### Trigger patterns — call `pwpilot_preview_generation` immediately

| Pattern | Example |
|---------|---------|
| URL + step list | `"Open the browser and navigate to /login, click Submit, verify error"` |
| Imperative browser instructions | `"Open the browser at X", "Navigate to Y", "Locate element Z", "Click the button", "Scroll and hover"` |
| Verification / assertion requests | `"Verify the modal appears", "Assert the heading is X", "Check that Y is visible"` |
| Screenshot requests in a flow | `"Capture a screenshot of the final state"` |
| Explicit test generation | `"Generate a test for...", "Automate the login flow"` |
| Video/recording conversion | `"Convert this recording into a test"` |
| Step-by-step user journey | Any numbered or bulleted list of browser actions on a URL |

### How to extract parameters from the user's prompt

- **`url`** — find any URL or path in the prompt (e.g. `http://localhost:3000`)
- **`prompt`** — copy the entire user message verbatim
- **`userSteps`** — if the user lists numbered/bulleted steps, extract them as an array
- **`videoPath`** — if the user mentions a file path to a video
- **`cwd`** — **REQUIRED**. The absolute path to the project folder where test files will be saved.
  - Extract from prompt if mentioned: `"save to ~/projects/myapp"` → `cwd: "/Users/name/projects/myapp"`
  - **If the user did NOT mention a folder — ask before calling the tool:**
    > _"Which folder should I save the generated tests to? Please provide the full path (e.g. `/Users/you/projects/myapp`)."_
  - Do NOT default to the Playwright Pilot AI installation folder or `process.cwd()`
  - An empty/non-existent folder is fine — Playwright Pilot AI will scaffold a new project automatically

### Example: imperative step prompt

User says:
```
Open the browser and navigate to index.html
Wait for the page to reach network idle state
Locate the Forgot Password link (btnforgot)
Scroll to it, hover over it, and click it
Verify the "Forgot Your Password?" modal/heading appears
Assert the content is as expected
Capture a screenshot of the final state
Save tests to /Users/john/projects/myapp
```

Correct action → call `pwpilot_preview_generation` with:
```json
{
  "url": "index.html",
  "cwd": "/Users/john/projects/myapp",
  "prompt": "Open the browser and navigate to index.html ...",
  "userSteps": [
    "Open the browser and navigate to index.html",
    "Wait for the page to reach network idle state",
    "Locate the Forgot Password link (btnforgot)",
    "Scroll to it, hover over it, and click it",
    "Verify the Forgot Your Password? modal/heading appears",
    "Assert the content is as expected",
    "Capture a screenshot of the final state"
  ]
}
```

If the user did NOT provide a folder path, ask first:
> _"Which folder should I save the generated tests to? Please provide the full path."_

Then show the `confirmationMessage` exactly and wait for the user to confirm before proceeding.

---

## Tool call order — never skip steps

```
pwpilot_preview_generation   ← ALWAYS first
    ↓ (user confirms)
Live browser flow:                Video / steps flow:
  pwpilot_launch_browser        pwpilot_video_to_test
  pwpilot_analyze_page              ↓
  pwpilot_generate_test         pwpilot_save_test
  pwpilot_save_test
```

## Announcements — tell the user before each tool call

- Before `pwpilot_launch_browser`: _"🌐 Playwright Pilot AI — Step 1/4: Opening browser at `<url>`..."_
- Before `pwpilot_analyze_page`: _"🔍 Playwright Pilot AI — Step 2/4: Analyzing page DOM locally (no AI tokens used)..."_
- Before `pwpilot_generate_test`: _"🤖 Playwright Pilot AI — Step 3/4: Running local skills, then generating spec..."_
- Before `pwpilot_save_test`: _"💾 Playwright Pilot AI — Step 4/4: Saving files to disk..."_
- Before `pwpilot_video_to_test`: _"🎬 Playwright Pilot AI — Step 1/2: Analyzing video / processing steps..."_

## After saving files

Tell the user exactly which files were written using the paths returned in the `pwpilot_save_test` response.

## New project scaffolding

When `pwpilot_preview_generation` returns `willScaffold: true`, the confirmation message will already contain a `### 🏗 New project — will be scaffolded automatically` section. Show it to the user exactly as returned.

When `pwpilot_save_test` returns a `scaffold` field, show the user:
1. Which boilerplate files were created (use `scaffold.filesCreated`)
2. The exact next-step commands they must run, in order:

```
✅ Project scaffolded (JavaScript / Node.js) — run these commands to finish setup:

  cd <project-root>
  npm install
  npx playwright install --with-deps
  cp .env.example .env   # then set BASE_URL to your app URL
```

Do NOT skip showing these commands — the user cannot run their tests until they run `npm install`.