---
name: run-test-plan
description: Execute a Markdown test-plan directory or a tagged subset, delegate each test to a fresh agent, collect evidence, and display the completed HTML test-run report.
---

Use SnagBadger's catalog/execution/reporting modules through its installed runner. Find the runner root and the target project's testing configuration; read [the workflow contract](../../../docs/integration/agent-testing.md) for configuration, CLI commands, and bridge responses. Skills installed outside the source checkout use the runner root's copy of that contract.

Resolve the application from the existing onboarding discovery/readiness record. When several applications are available, ask the user to choose even when one has a default. Within the chosen application include every configured catalog unless the request explicitly narrows that scope. Use the public `resolveCatalogScope` helper in `tooling/testing/catalog-scope.mts` with the existing discovered targets and configured catalog paths; it returns either the choice required or the exact catalog scope. Run each returned catalog with its configured `--catalog-id` in a separate fresh output directory, preserving the complete scope in the final summary.

"Execute smoke test plan" means `--tag smoke` across that scope. Clarify ambiguous tag combinations before choosing all/any/exclude. Inspect discovery/selection diagnostics; definitions validate when reached. Report unselectable files as coverage gaps. No matches executes nothing: present alternatives and wait for an explicit revised selection. Preserve implicit directory sections. Read the catalog contract for `.snag.md` identities and free-form bodies.

Discover the user's configured browser MCP and native agent-delegation tools. Read their actual tool contracts and choose a runtime manifest. Browser tests need a **new browser context**, not a new tab in a shared profile. Set isolation true only when the tool explicitly creates contexts or a disposable storage probe demonstrates the capability. Read [runtime mappings](../../../docs/integration/testing-runtimes.md) for Chrome DevTools and other hosts; installed skills use the runner root's copy. Keep unavailable screenshot/video capabilities false. Every executeTest request requires a fresh agent with no inherited coordinator conversation. If fresh delegation is unavailable, report the prerequisite rather than pretending this workflow ran.

Start the CLI in a persistent/background execution session. Service one bridge request at a time using `next` and `complete`; response files must reference the current request ID. The pending packet lives at `<output>/bridge/request.json`; give the worker this actual locator or a saved packet, rather than guessing a requests directory. The engine owns selection, hook ordering, verdict validation, persistence, and report rendering:

- createBrowserContext: create a unique context for the requested identity; return its handle and explicit browserContext attestation.
- browserAction: execute the project hook's action in that exact context. Select/target its page before acting; return the tool result's serializable value.
- instruction: carry out the scoped setup/cleanup instruction against its supplied context. Return success or an explicit error.
- startVideo / stopVideo: operate on that session. Return saved recording evidence plus its environment-readable file path on stop.
- executeTest: start a fresh agent with only the task packet, request ID, output directory, runner location, and execute-test skill. Wait for its completed response before proceeding.
- getCoordinatorUsage (only when tokenUsage is supported): return cumulative runtime counters for this run, excluding delegated attempts; return null when unavailable. Read [the token contract](../../../docs/integration/test-run-viewer.md) before enabling it.
- closeBrowserContext: release the created context and its pages through the selected runtime's documented lifecycle; report cleanup limitations explicitly.

After delegation, inspect its saved result/evidence rather than replacing its observations with the coordinator's assumptions. Preserve unavailable proof, hook errors, failures, and unfinished attempts. The engine runs configured automatic retry passes after the first pass; keep servicing each retry request with a fresh agent. Read [retry configuration](../../../docs/integration/test-run-viewer.md#automatic-retries-and-flaky-results) before changing limits or invoking additional manual retries with `--retry --ids ...`; retain prior attempts. Poll progress without long blocking waits and keep the user informed.

On cancellation, record `cancel`, stop/finish the active worker, return its interrupted response, and continue servicing cleanup requests. If the coordinator is interrupted, preserve checkpoint.json, pending requests, and raw artifacts; use the reporting skill to render the partial run.

When execution exits, use create-test-report if review is pending. Open/display the generated index.html and link it in the final response with counts and important limitations. Completion means every selected test is represented by an outcome or a stopped-run explanation, and the actual report is available to the user. This workflow creates local bug drafts; live tracker submission follows separate user authorization.