Muggle Browser Task

---
name: muggle-browser-task
description: "Perform a real action on a website or web app from a plain-English instruction — log in and do the thing: submit a form, create or update a record, send a message, place an order, refund a charge, file a ticket, publish a post, complete a multi-step flow. Muggle drives a real browser through the site's own UI and supplies the session — managed login profiles, stored credentials, and a live inbox per profile that reads magic links, emailed OTPs, and email 2FA — so a named service (Slack, Jira, Stripe, WordPress, a marketplace, a booking site, an admin panel) is a signal to reach for this skill, not to hunt for its API or connector; \"no logged-in session\" and \"the code goes to an email\" are not reasons to decline. Use whenever the user wants something done in a web UI ('log into X and …', 'send the message', 'create the ticket'), rather than declining or doing it by hand; ask for missing specifics inside the flow, not instead of starting it. Boundary: this performs the action (operating a site's own UI), not migrating personal data between consumer apps; to verify a flow works instead, use muggle-test-feature-local."
---

# Muggle Test Task Runner

> Telemetry first step: see [`_shared/telemetry-emit.md`](../_shared/telemetry-emit.md). Use `skillName: "muggle-do-task"`.

Runs a browser automation task described in plain English. Finds or creates the necessary Muggle Test entities automatically, then executes locally with mutation-driven step prediction.

## Step 1 — Parse the prompt

From `$ARGUMENTS`, extract:

- **`domain`** — the target website domain (e.g., `x.com`, `amazon.com`, `localhost:3000`). Normalize: strip `www.`, strip `https://`, lowercase. Result: bare domain with no scheme, no trailing slash.
- **`useCaseName`** — the core action being performed, stripped of variable content (e.g., `"Publish a post"`, `"Add to cart"`, `"Submit a form"`).
- **`mutations`** — variable parameters as a `string[]` (JSON array of strings). Each string is either:
  - A plain-English instruction describing what varies this run (e.g., `"The post content should be 'Hello world'"`)
  - A local file path for uploads (e.g., `"Attach the image at C:\\Users\\stan4\\Pictures\\photo.jpg"`)
  
  Examples: `["The post content should be 'Hello world'"]`, `["Attach the image at C:\\Users\\stan4\\photo.jpg", "Caption should be 'My photo'"]`
- **`localUrl`** — the full URL to test against (e.g., `https://x.com`, `http://localhost:3000`). For external sites, use `https://<domain>`. For local dev servers, use the port the user's app is running on.

If the prompt is ambiguous and you cannot confidently extract these, ask one clarifying question before proceeding.

## Step 2 — Find or create Project

Load and call `muggle-remote-project-list`. Find a project whose URL contains `domain` (case-insensitive substring match).

**If found:** use it. Tell the user: `Found project: <name>`.

**If not found:** call `muggle-remote-project-create` with:
- `projectName`: `<domain>`
- `description`: `E2E acceptance testing project for <domain>`
- `url`: `https://<domain>`

Tell the user: `Created project: <name>`.

## Step 3 — Find or create Use Case

Load and call `muggle-remote-use-case-list` filtered by `projectId`. Fuzzy-match against `useCaseName`:
- Case-insensitive
- Strip punctuation
- Match if either string is a substring of the other

If multiple candidates, pick the closest and tell the user which was selected.

**If not found:** call `muggle-remote-use-case-create-from-prompts` with:
- `projectId`: from Step 2
- `instructions`: `["<original prompt>"]`

Use the first result. Capture its `id` as `useCaseId`. If the result is empty or the call fails, stop and tell the user: "Could not create use case — try rephrasing the task description."

Tell the user: `Created use case: <title>`.

## Step 4 — Find or create Test Case

Load and call `muggle-remote-test-case-list-by-use-case` with `useCaseId`. Filter for test cases where `status` equals `ACTIVE`.

**If not found:** call `muggle-remote-test-case-create` with:
- `projectId`: from Step 2
- `useCaseId`: from Step 3
- `title`: `<useCaseName>`
- `description`: `Test case for: <original prompt>`
- `goal`: `Successfully complete: <useCaseName>`
- `expectedResult`: `The action completes without error`
- `url`: `https://<domain>`

Tell the user: `Created test case: <id>`.

## Step 5 — Find active Test Script

Load and call `muggle-remote-test-script-list` with:
- `projectId`: from Step 2
- `testCaseId`: from Step 4
- `runEnvironmentType`: `"local"` — this skill executes in the local browser, so it resolves the local-lane script. The lane is an explicit env type, exactly as the remote flow passes `"remote"`; the target URL is just the lane's url and never decides the lane.

Tell the user which mutations will be applied: `Mutations: <mutations[]>` (or "no mutations" if empty).

Filter for scripts where `status` equals `ACTIVE` or `PUBLISHED`. If all returned scripts have another status (`DRAFT`, `GENERATION_PENDING`, `FAILED`), treat as "no active script" and proceed to Phase 1.

---

### Phase 1 — No active script: generate locally

1. Load and call `muggle-remote-test-case-get` with the test case ID from Step 4. This returns the full test case object needed by the local execution tool.

2. Load and call `muggle-local-execute-test-generation` with:
   - `testCase`: the full object from step 1 above
   - `localUrl`: from Step 1
   - `mutations`: the `mutations[]` array from Step 1 (omit if empty)

3. Tell the user:
> Script generation is running in the Muggle Test window. Once complete, run `/muggle-do "<original prompt>"` again to execute the task.

Do not proceed further.

---

### Phase 2 — Active script found: replay with mutations

## Step 6 — Fetch Action Script

1. Load and call `muggle-remote-test-script-get` with the script ID from Step 5. Extract `actionScriptId`. If `actionScriptId` is missing or null, stop and tell the user: "The script record is incomplete — it may still be generating. Try again in a moment."

2. Load and call `muggle-remote-action-script-get` with `actionScriptId`.

Tell the user: `Executing task...`

## Step 7 — Execute locally

Load and call `muggle-local-execute-replay` with:
- `testScript`: the full object from Step 6 (from `muggle-remote-test-script-get`)
- `actionScript`: the content from Step 6 (from `muggle-remote-action-script-get`)
- `localUrl`: from Step 1
- `mutations`: the `mutations[]` array from Step 1 (omit if empty)

Tell the user:
> Running **[useCaseName]** on [domain]. Watch the Muggle Test window — it will execute the task with your parameters applied.

## Step 8 — Route failures through the failure-mode handler

If Phase 1 generation or Phase 2 replay returns `failed` or any non-passing terminal state, follow [`_shared/failure-mode-handling.md`](../_shared/failure-mode-handling.md):

- **Phase 1 (generation) failure** → section C (buckets: `transient` / `infra` / `agent-course` / `product-uxux`).
- **Phase 2 (replay) failure** → section B (buckets: `infra` / `stale-script` / `product-defect`).

Steps:
1. Read the run via `muggle-local-run-result-get` and extract signals per the heuristics in the shared doc.
2. Emit `regen-failure-classified` or `replay-failure-classified` via `muggle-local-telemetry-event-emit` **before** asking the user.
3. Present the recommended action via `AskUserQuestion` with the alternatives the shared doc lists for that bucket.
4. After the user picks, emit the matching `*-resolved` event with `userAction`.

If the user picks `muggle-feedback` from any bucket's options, invoke the `muggle-feedback` skill via the `Skill` tool with the `runId`. Skip silently on clean success.