@muggleai/works 5.8.0 → 5.9.0

package/plugin/skills/muggle-pr-visual-walkthrough/SKILL.md

@@ -1,236 +1,41 @@
----
-name: muggle-pr-visual-walkthrough
-model: sonnet
-description: Renders and posts a visual walkthrough of Muggle AI E2E acceptance test results to a PR — per-test-case dashboard links, step-by-step screenshots, and pass/fail summary — using the `muggle build-pr-section` CLI for deterministic formatting with automatic fit-vs-overflow. Use at the end of any Muggle Test test run (local or remote) to give PR reviewers clickable visual evidence that user flows work. Triggers on 'post results to PR', 'attach walkthrough to PR', 'share E2E screenshots on the PR', 'add visual walkthrough to PR'.
----
-
-# Muggle Test PR Visual Walkthrough
-
-> Telemetry first step: see [`_shared/telemetry-emit.md`](../_shared/telemetry-emit.md). Use `skillName: "muggle-pr-visual-walkthrough"`.
-
-Renders a visual walkthrough of Muggle AI E2E acceptance test results and posts it to a PR. Each test case is linked to its detail page on the Muggle AI dashboard, so PR reviewers can click through to see step-by-step screenshots and action scripts — not just a pass/fail flag.
-
-This is the **canonical PR-walkthrough workflow** shared across every Muggle Test entry point:
-
-| Caller | Mode | When to invoke |
-| :--- | :--- | :--- |
-| `muggle-test` | **Mode A** (post to existing PR) | After publishing results, user opts in via `AskUserQuestion` |
-| `muggle-test-feature-local` | **Mode A** (post to existing PR) | After publishing the run, user opts in via `AskUserQuestion` |
-| `muggle-do` / `open-prs.md` | **Mode B** (render-only for embedding) | During PR creation — caller embeds `body` in `gh pr create` and posts `comment` as follow-up |
-| `muggle-test` Mode C / `acceptance-tester` agent | **Mode C** (embed in verdict comment) | Inside a open-PR sweep orchestrator — caller folds the rendered body into a single per-PR verdict comment instead of posting separately |
-
-Rendering is always done by `muggle build-pr-section`, a battle-tested CLI that handles deterministic markdown layout, per-step screenshots, and automatic fit-vs-overflow (oversized content spills into a follow-up comment). Never hand-write the walkthrough markdown.
-
-## Preferences
-
-This skill is invoked by callers (`muggle-test`, `muggle-test-feature-local`, `muggle-do`) **after** the caller has already consulted the `postPRVisualWalkthrough` gate and decided to post. Therefore **the gating happens upstream, not in this skill** — by the time this skill runs, the user has already approved posting (either via the saved gate value or by explicit pick).
-
-| Preference | Where it's gated | Decision it gates |
-|------------|------------------|-------------------|
-| `postPRVisualWalkthrough` | Caller skill (e.g. `muggle-test` Step 9, `muggle-test-feature-local` Step 10) | Post visual walkthrough to PR |
-
-Per-key gate definitions live in `plugin/skills/muggle-preferences/preference-gates/`. This skill only renders and posts.
-
-## Input contract: the `E2eReport` JSON
-
-Every caller must build an `E2eReport` JSON object and have it in conversation context before invoking this skill. The schema is defined in `src/cli/pr-section/types.ts` (`E2eReportSchema`) and enforced by the CLI with Zod — malformed input exits non-zero with a descriptive stderr message.
-
-```json
-{
-  "projectId": "<UUID>",
-  "tests": [
-    {
-      "name": "<test case title>",
-      "description": "<one-line description of what this test verifies>",
-      "useCaseName": "<parent use case title>",
-      "testCaseId": "<UUID>",
-      "testScriptId": "<UUID>",
-      "runId": "<UUID>",
-      "viewUrl": "https://www.muggle-ai.com/...",
-      "status": "passed",
-      "steps": [
-        { "stepIndex": 0, "action": "Click login button", "screenshotUrl": "https://..." },
-        { "stepIndex": 1, "action": "Type email", "screenshotUrl": "https://..." }
-      ]
-    },
-    {
-      "name": "Checkout flow",
-      "description": "Verify a shopper can complete checkout with a saved card.",
-      "useCaseName": "Purchase",
-      "testCaseId": "<UUID>",
-      "testScriptId": "<UUID>",
-      "runId": "<UUID>",
-      "viewUrl": "https://www.muggle-ai.com/...",
-      "status": "failed",
-      "steps": [
-        { "stepIndex": 0, "action": "Open cart", "screenshotUrl": "https://..." }
-      ],
-      "failureStepIndex": 2,
-      "error": "Element not found: Click checkout button",
-      "artifactsDir": "/Users/.../~/.muggle-ai/sessions/<runId>"
-    },
-    {
-      "name": "Clear search input restores full list",
-      "description": "Verify clearing the search input restores all options.",
-      "useCaseName": "Filter Dropdowns",
-      "testCaseId": "<UUID>",
-      "runId": "<UUID>",
-      "viewUrl": "https://www.muggle-ai.com/...",
-      "status": "inconclusive",
-      "steps": [],
-      "reason": "No replayable script exists yet — needs first generation run."
-    }
-  ]
-}
-```
-
-Required fields per test: `name`, `testCaseId`, `runId`, `viewUrl`, `status`, `steps[]` with `{stepIndex, action, screenshotUrl}`.
-
-- **Failed** tests additionally require `failureStepIndex` and `error`.
-- **Inconclusive** tests additionally require `reason` (one short sentence on why the result is neither pass nor fail). `steps[]` may be empty — that's fine. Inconclusive is for runs that couldn't be classified pass/fail (no replayable script, environment precondition unmet, infra error blocked execution, agent stalled before reaching the assertion). **Never silently drop these — always emit them as `inconclusive`.** The CLI counts them in the overview and renders an `⚠️` row with the dashboard link so reviewers can click through. If you find yourself wanting to skip a test or hand-write a comment because the schema "doesn't fit," that is the schema fitting — use `inconclusive`.
-
-### Verdict
-
-The renderer computes a verdict from the tests and emits a `**Verdict:** ✅ PASS | ❌ FAIL | ⚠️ INCONCLUSIVE` line at the top of the overview. The policy is strict:
-
-- Any failed test → **FAIL** (regardless of how many passed or are inconclusive).
-- No failures but any inconclusive → **INCONCLUSIVE**.
-- All passed → **PASS**.
-- Empty report → no verdict line.
-
-You do not compute or render the verdict yourself — the CLI does. Never write a "Verdict: PASS" line into a hand-edited summary; it will conflict with the CLI's computed verdict.
-
-**Optional but recommended** per test:
-- `description` — a one-line summary of what the test case verifies. Shown in the collapsible header for each test and helps reviewers understand the test without expanding it. Pull from the test case's `title`/`description` via `muggle-remote-test-case-get`.
-- `useCaseName` — the parent use case title. When present on any test, the overview list is grouped by use case; otherwise it is rendered as a flat list. Pull from `muggle-remote-use-case-get` using the test case's parent use-case id.
-- `testScriptId` and `artifactsDir` are also optional.
-
-If any required field is missing, stop and tell the caller exactly what's missing. Never fabricate data.
-
-## Step 1: Assemble the `E2eReport`
-
-Read `plugin/skills/muggle-pr-visual-walkthrough/e2e-report-assembly.md` for the full assembly guide.
-
-## Step 2: Render via `muggle build-pr-section`
-
-Pipe the `E2eReport` JSON to the CLI. It writes `{"body": "...", "comment": "..." | null}` to stdout — the `body` is the E2E markdown block, and `comment` is a non-null overflow comment only when the full body exceeds the byte budget (default 60 KB).
-
-```bash
-echo "$REPORT_JSON" | muggle build-pr-section > /tmp/muggle-pr-section.json
-```
-
-- Exit **non-zero** → the CLI wrote a descriptive error to stderr. Surface it to the user; do not swallow it.
-- `comment` is **`null`** (fit case) → everything is inline in `body`. Post `body` only.
-- `comment` is a **non-null string** (overflow case) → `body` contains the summary + a pointer; `comment` contains the full per-step details. Post both, in order.
-
-Never hand-write the walkthrough markdown. Never modify the CLI's output before posting. The CLI owns the format.
-
-## Step 3 — Mode A: Post to an existing PR
-
-Used by `muggle-test` and `muggle-test-feature-local`, where the user is mid-development and a PR already exists on the current branch.
-
-### 3A.1: Find the PR
-
-```bash
-gh pr view --json number,url,title 2>/dev/null
-```
-
-- **PR exists** → continue to 3A.2
-- **No PR exists** → use `AskUserQuestion`:
-  - "Create a new PR with the visual walkthrough in the body"
-  - "Skip posting"
-  - If the user chooses to create a new PR, switch to Mode B and return the rendered `body`/`comment` to the caller for embedding in `gh pr create`. Do not create the PR directly from this skill unless the caller has no better way to do it.
-- **`gh` not installed or not authenticated** → tell the user, suggest `gh auth login`, stop.
-
-### 3A.2: Post the body as a PR comment
-
-Extract the `body` field with `jq -r` (not `sed`) so JSON escape sequences are properly decoded, append the Muggle Works signature (command `/muggle-pr-visual-walkthrough`) per [`../_shared/vcs/post-signature.md`](../_shared/vcs/post-signature.md), then pipe to `--body-file -`. The renderer's sentinel stays at the top of `body`, so the report-format guardrail still recognises the post:
-
-```bash
-{
-  jq -r '.body' /tmp/muggle-pr-section.json
-  printf '\n\n%s\n' '🤖 _Posted by `/muggle-pr-visual-walkthrough` · [Muggle Works](https://github.com/multiplex-ai/muggle-ai-works)_'
-} | gh pr comment <pr-number> --body-file -
-```
-
-### 3A.3: Post the overflow comment only if the CLI emitted one
-
-```bash
-{
-  jq -r '.comment' /tmp/muggle-pr-section.json
-  printf '\n\n%s\n' '🤖 _Posted by `/muggle-pr-visual-walkthrough` · [Muggle Works](https://github.com/multiplex-ai/muggle-ai-works)_'
-} | gh pr comment <pr-number> --body-file -
-```
-
-**Skip this step entirely if `comment` is `null`** — do not post a placeholder. The CLI decides fit-vs-overflow; never post the overflow comment speculatively.
-
-### 3A.4: Confirm to the user
-
-> "Visual walkthrough posted to PR #<number>. Reviewers can click any test case link to see the step-by-step screenshots on the Muggle AI dashboard."
-
-Include the PR URL in the confirmation.
-
-## Step 3 — Mode B: Return rendered block for embedding in a new PR
-
-Used by `muggle-do`'s `open-prs.md`, where the PR does not exist yet and the caller is assembling the PR body from multiple sections (`## Goal`, `## Acceptance Criteria`, `## Changes`, plus this walkthrough).
-
-Instead of posting, **return** the CLI output to the caller's context so they can:
-
-1. **Embed `body`** in their PR body, concatenated after `## Changes`. `body` already includes its own `## E2E Acceptance Results` header — do not add another.
-2. **Create the PR** with `gh pr create --title "..." --body "..."` using the concatenated body.
-3. **Post `comment` as a follow-up only if the CLI emitted one**, ending the posted body with the signature (the caller owns this post, so command `/muggle-do`) per [`../_shared/vcs/post-signature.md`](../_shared/vcs/post-signature.md):
-
-   ```bash
-   {
-     jq -r '.comment' /tmp/muggle-pr-section.json
-     printf '\n\n%s\n' '🤖 _Posted by `/muggle-do` · [Muggle Works](https://github.com/multiplex-ai/muggle-ai-works)_'
-   } | gh pr comment <new-pr-number> --body-file -
-   ```
-
-   Skip if `comment` is `null`.
-
-In Mode B, this skill does not call `gh pr comment` or `gh pr create` itself — the caller owns PR creation because it also owns branch pushing, title building (including `[E2E FAILING]` prefix on failures), and multi-repo orchestration.
-
-## Step 3 — Mode C: Embed mode for open-PR sweep orchestrators
-
-Used when invoked as a sub-step of a open-PR sweep orchestrator (see `plugin/skills/muggle-test/SKILL.md` Mode C) rather than as a top-level user invocation. The orchestrator's `acceptance-tester` subagent (see `plugin/agents/acceptance-tester.md`) composes a **single per-PR verdict comment** and folds the walkthrough into it — posting separately would create 2–3 disparate comments per test cycle and clutter the PR.
-
-### 3C.1: Detect embed mode
-
-The caller passes `mode: "embed"` as a skill argument. Default behavior (no `mode` passed, or `mode: "post"`) is Mode A — unchanged.
-
-### 3C.2: Render but do not post
-
-Run `muggle build-pr-section` exactly as in Step 2. Then, **instead of calling `gh pr comment`**:
-
-1. **Return** the CLI output (`{ body, comment }`) to the caller as this skill's result.
-2. Do **not** find a PR, do **not** post a standalone comment, do **not** prompt the user.
-3. If `comment` is non-null (overflow case), return it alongside `body` — the orchestrator decides how to handle overflow (typically: inline `body` in the verdict comment, post `comment` as a follow-up).
-
-### 3C.3: Hand off
-
-The orchestrator (`acceptance-tester`) concatenates the returned `body` into its verdict comment template alongside the verdict summary, change-list, and any other sections it owns, then posts a single `gh pr comment` itself. This skill's job ends at returning the rendered markdown.
-
-In Mode C, the same fit-vs-overflow contract from Step 2 applies — never modify the CLI's output, never fabricate fields, never post anything. The caller owns posting.
-
-## Tool Reference
-
-| Phase | Tool |
-|:------|:-----|
-| Gather per-step data (muggle-test, muggle-test-feature-local) | `muggle-remote-test-script-get` |
-| Render the walkthrough markdown | `muggle build-pr-section` (shell) |
-| Find existing PR (Mode A) | `gh pr view` |
-| Post comment(s) (Mode A) | `gh pr comment` |
-| Create new PR (Mode B, caller handles) | `gh pr create` |
-| User confirmation (Mode A no-PR branch) | `AskUserQuestion` |
-
-## Guardrails
-
-- **Never hand-write the walkthrough markdown** — always call `muggle build-pr-section`. The CLI is the single source of truth for formatting. If a test outcome doesn't fit `passed | failed`, that's what `inconclusive` is for — never fall back to a hand-written summary, a custom table, a "Verdict: PASS" header, a `Tested on:`/`Project:` footer, or any other freeform text. The CLI already emits per-test-case dashboard links (no project-level link), uses `https://www.muggle-ai.com/...` URLs (never the test target's `localhost` URL), and computes the verdict — anything you would manually add is wrong by construction.
-- **Never modify the CLI's output** — post `body` and (if present) `comment` verbatim. Any reformatting defeats the fit-vs-overflow budget math.
-- **Never invent report fields** — if `projectId`, a per-test `viewUrl`, or per-step `screenshotUrl` is missing, stop and report what's missing. Do not fabricate URLs or fill in placeholders.
-- **Never post the overflow comment when `comment` is `null`** — the CLI decides fit-vs-overflow.
-- **Never create a PR without confirmation in Mode A** — if no PR exists, ask the user or switch to Mode B and hand back to the caller.
-- **Don't run tests** — this skill only renders and posts existing results. If the `E2eReport` is not in context, redirect the caller to `muggle-test`, `muggle-test-feature-local`, or `muggle-do`.
-- **Mode is chosen by the caller, not the user** — `muggle-test` top-level uses Mode A; `muggle-do` uses Mode B; open-PR sweep orchestrators (`muggle-test` Mode C / `acceptance-tester`) pass `mode: "embed"` for Mode C. Don't ask the user which mode to use.
-- **Never post in Mode C** — when `mode: "embed"` is passed, return the rendered body to the caller and stop. The orchestrator owns the single verdict comment.
+---
+name: muggle-pr-visual-walkthrough
+model: sonnet
+description: Renders and posts a visual walkthrough of Muggle AI E2E acceptance test results to a PR — per-test-case dashboard links, step-by-step screenshots, and pass/fail summary — using the `muggle build-pr-section` CLI for deterministic formatting with automatic fit-vs-overflow. Use at the end of any Muggle Test test run (local or remote) to give PR reviewers clickable visual evidence that user flows work. Triggers on 'post results to PR', 'attach walkthrough to PR', 'share E2E screenshots on the PR', 'add visual walkthrough to PR'.
+---
+
+# Muggle Test PR Visual Walkthrough
+
+> Telemetry first step: see [`_shared/telemetry-emit.md`](../_shared/telemetry-emit.md). Use `skillName: "muggle-pr-visual-walkthrough"`.
+
+Renders a visual walkthrough of Muggle AI E2E acceptance test results and posts it to a PR. Each test case links to its detail page on the Muggle AI dashboard, so reviewers can click through to step-by-step screenshots — not just a pass/fail flag.
+
+This skill is a **dispatcher**: it resolves the mode and any user interaction, then hands execution to the `visual-walkthrough-builder` agent (`plugin/agents/visual-walkthrough-builder.md`), which renders and delivers per its own contract.
+
+This is the **canonical PR-walkthrough workflow** shared across every Muggle Test entry point:
+
+| Caller | Mode | When to invoke |
+| :--- | :--- | :--- |
+| `muggle-test` | **Mode A** (post to existing PR) | After publishing results, user opts in via `AskUserQuestion` |
+| `muggle-test-feature-local` | **Mode A** (post to existing PR) | After publishing the run, user opts in via `AskUserQuestion` |
+| `muggle-do` / `open-prs.md` | **Mode B** (render-only for embedding) | During PR creation — caller embeds `body` in the PR create call and posts `comment` as follow-up |
+| `muggle-test` Mode C / `acceptance-tester` agent | **Mode C** (embed in verdict comment) | Inside an open-PR sweep orchestrator — caller folds the rendered body into a single per-PR verdict comment |
+
+## Preferences
+
+Callers consult the `postPRVisualWalkthrough` gate **before** invoking this skill — by the time it runs, posting is already approved. Per-key gate definitions live in `plugin/skills/muggle-preferences/preference-gates/`.
+
+## Procedure
+
+1. **Resolve the mode.** Chosen by the caller, never the user: top-level `muggle-test`/`muggle-test-feature-local` → `post` (Mode A); `muggle-do` PR creation → `render-for-new-pr` (Mode B); an orchestrator passing `mode: "embed"` → Mode C.
+2. **Mode A only — find the PR** with `gh pr view --json number,url,title`. No PR on the branch → `AskUserQuestion`: create a new PR with the walkthrough in the body (switch to Mode B and hand the rendered block back to the caller), or skip posting. `gh` missing/unauthenticated → tell the user, suggest `gh auth login`, stop. This is the skill's only interactive branch — resolve it **before** dispatching.
+3. **Gather the inputs.** The `E2eReport` JSON if the caller already assembled it (see [`e2e-report-assembly.md`](e2e-report-assembly.md)), else the run identifiers (`projectId`, per-test `runId`/`testCaseId`) the agent needs to assemble it.
+4. **Dispatch** the `visual-walkthrough-builder` agent (subagent type `muggle:visual-walkthrough-builder`; bare `visual-walkthrough-builder` where the plugin namespace is absent), synchronously, passing: mode, PR number + repo (Mode A), and the report JSON or identifiers. In a harness with no agent/subagent facility, execute `plugin/agents/visual-walkthrough-builder.md` inline instead.
+5. **Relay the result.** Mode A → confirm to the user with the PR URL. Modes B/C → return the agent's `{body, comment}` to the caller verbatim; the caller owns PR creation (Mode B) or the single verdict comment (Mode C). A `needs-input:` line from the agent names a missing report field — surface it to the caller; never fabricate the field.
+
+## Guardrails
+
+- The rendered markdown is CLI-owned end to end — this skill never writes, edits, or post-processes it; those rules ride with the agent.
+- Mode is chosen by the caller, not the user.
+- Never create a PR without confirmation in Mode A.
+- Don't run tests — this skill only dispatches rendering/posting of existing results. No report and no run identifiers in context → redirect the caller to `muggle-test`, `muggle-test-feature-local`, or `muggle-do`.

package/plugin/skills/muggle-test-prepare/SKILL.md

@@ -1,129 +1,130 @@
----
-name: muggle-test-prepare
-model: opus
-description: "Get a user's local environment ready before running E2E acceptance tests — verify the dev servers, APIs, and sibling services they need are up and responding, and offer to start whatever is missing (with approval per step). Trigger when the user wants to confirm specific ports or localhost URLs are listening before testing (check if localhost:3000 and the api on 8080 are up, are my services running), spin up their local dev stack, or verify their setup — and whenever another muggle skill (muggle-test, muggle-do, muggle-test-feature-local) needs services running but they're not. This is environment readiness and service startup, not running the tests."
----
-
-# Muggle Test Prepare
-
-> Telemetry first step: see [`_shared/telemetry-emit.md`](../_shared/telemetry-emit.md). Use `skillName: "muggle-test-prepare"`.
-
-Make sure the local services a user needs for E2E acceptance testing are up and ready. Check what's already running, discover sibling service directories by folder name, and offer to start anything that's missing — always with the user in control.
-
-Some users start their own services (tmux scripts, docker-compose, a terminal per service). Others want help launching them. This skill handles both: it verifies readiness first, and only offers to start things when something is missing.
-
-## Privacy Boundary
-
-This skill touches the user's local machine — processes, ports, directories outside the current repo. Every action is explicit and confirmed.
-
-- **Folder names are public.** You may list directory names in a parent folder to discover sibling services.
-- **File contents are private until confirmed.** Never read files inside a directory the user hasn't explicitly identified as a service to start. Once confirmed, you may inspect only top-level project indicator files (`package.json`, `Makefile`, `Cargo.toml`, `go.mod`, `pyproject.toml`, `docker-compose.yml`) to determine the start command.
-- **Never traverse upward more than one level** from the current working directory to list folders.
-
-## PID Tracking
-
-All launched processes are tracked in `/tmp/muggle-test-prepare.json`:
-
-```json
-{
-  "session_started": "2025-01-15T10:30:00Z",
-  "testing_scope": "frontend",
-  "excluded_services": [
-    {"name": "payment-gateway", "reason": "Needs production certificates"}
-  ],
-  "services": [
-    {
-      "name": "backend-api",
-      "dir": "/Users/user/Github/backend-api",
-      "command": "npm run dev",
-      "pid": 12345,
-      "port": 3001,
-      "log": "/tmp/muggle-prepare-backend-api.log"
-    }
-  ]
-}
-```
-
-`testing_scope` records what the user is testing (from [scope](./steps/scope.md)). `excluded_services` records services the user said can't run locally (from [viability-check](./steps/viability-check.md)).
-
-This file is **ephemeral runtime state**, not the saved recipe. The durable plan lives at `<repo>/.muggle-ai/prepare-plan.json` (or the parent-dir-keyed entry in `~/.muggle-ai/prepare-plans.json`) and is consulted in [reuse-plan](./steps/reuse-plan.md) before any other stage. The two files never merge.
-
-**On every invocation**, check this file first. If it exists with live PIDs (verify with `kill -0`), `AskUserQuestion`:
-- Option 1: "Keep them running — skip to testing"
-- Option 2: "Tear down and start fresh"
-- Option 3: "Add more services to the running set"
-
-Prune dead PIDs silently.
-
-## Preferences
-
-Gates run per [`preference-gates/README.md`](../muggle-preferences/preference-gates/README.md).
-
-| Preference | Gates |
-|------------|-------|
-| `autoRebase` | [rebase-check](./steps/rebase-check.md) — rebase onto `origin/<default>` before starting dev servers |
-| `reusePreparePlan` | [reuse-plan](./steps/reuse-plan.md) — reuse the saved prepare plan for this stack, or rediscover |
-| `autoSelectLocalHost` | [check-running](./steps/check-running.md) — reuse the recorded dev-server URL silently, or confirm it each run |
-
-## Workflow
-
-Run the stages in this order. The sequence number is display-only — it lives only in this table for at-a-glance ordering; detail files and cross-references use slugs. Each row links to its detail file; read the file when you reach the stage.
-
-| # | Stage | Summary |
-|:--|:------|:--------|
-| 0 | [reuse-plan](./steps/reuse-plan.md) | Reuse saved prepare plan (gated); short-circuits to check-running on reuse |
-| 1 | [rebase-check](./steps/rebase-check.md) | Rebase onto default branch (gated) |
-| 2 | [scope](./steps/scope.md) | Frontend / backend / full stack |
-| 3 | [viability-check](./steps/viability-check.md) | Exclude services that can't run locally |
-| 4 | [identify-services](./steps/identify-services.md) | Pick required services + startup mode |
-| 5 | [check-running](./steps/check-running.md) | Detect what's already listening |
-| 6 | [env-file](./steps/env-file.md) | Env file present + correct |
-| 7 | [start-commands](./steps/start-commands.md) | Determine per-service start command |
-| 8 | [fresh-install](./steps/fresh-install.md) | Auto-install deps if missing/stale |
-| 9 | [start-services](./steps/start-services.md) | Launch + two-stage readiness |
-| 10 | [smoke-test](./steps/smoke-test.md) | HTTP + body sniff + log tail; clean-restart on fail |
-| 11 | [readiness-report](./steps/readiness-report.md) | Final ready table |
-
-## Cleanup
-
-Triggered when the user says "stop services", "tear down", "clean up", "I'm done testing", another skill signals run complete, or this skill is re-invoked with "tear down and start fresh".
-
-1. Read `/tmp/muggle-test-prepare.json`
-2. Skip services marked `external: true`
-3. For each managed service: `kill <pid>` (SIGTERM)
-4. Wait ~2 s, verify with `kill -0`
-5. If still alive: `kill -9 <pid>`
-6. `rm -f /tmp/muggle-prepare-*.log`
-7. `rm -f /tmp/muggle-test-prepare.json`
-
-Report:
-
-```
-Stopped 3 services:
-  backend-api    (PID 12345)
-  auth-service   (PID 12346)
-  frontend       (PID 12347)
-```
-
-## Integration Contract (for other skills)
-
-`muggle-test-feature-local`, `muggle-do`, and local-mode `muggle-test` MUST invoke this skill before any workflow step. Idempotent — fast exit when healthy. Treat success as short-lived; re-invoke if more than a few minutes pass before testing. Never bypass on "the user knows their stack is up" — that assumption is why this skill exists.
-
-After a test run, the caller can re-invoke for cleanup or leave services running for the next run.
-
-## Guardrails
-
-- **Never invent or default a host/port** — the dev-server URL is a recorded value, not a guess. Resolve it from `<repo>/.muggle-ai/last-host.json` (the [`autoSelectLocalHost`](../muggle-preferences/preference-gates/autoSelectLocalHost.md) cache) before probing ports; a framework default like `:3000` is never a fallback. See [check-running](./steps/check-running.md).
-- **No silent auto-selection without a gate** — when no preference authorizes a silent choice (host, restart, kill), confirm with the user. A gate set to `always` is the only license to skip the question; absent that, ask.
-- **Verify first, offer to start second** — check what's already running before proposing to start anything.
-- **The user may prefer to start services themselves** — always offer that option.
-- **Never start a process the user didn't approve.**
-- **Never read file contents outside confirmed directories** — folder names are discoverable; file contents require explicit user selection.
-- **Never leave orphan processes untracked** — every background PID goes into the tracking file.
-- **Never kill a process the user started independently** — `external: true` survives cleanup.
-- **Never assume start commands** — verify via indicator file; confirm with user.
-- **Bail early on non-viable services** — don't start what can't run locally.
-- **Idempotent** — already-tracked alive services are kept; [smoke-test](./steps/smoke-test.md) still runs against them.
-- **Port-listening is never enough** — smoke-test (HTTP + body sniff + log tail) is mandatory before the final report.
-- **Clean Restart is the recommended fix** — first option in the smoke-test diagnose-and-fix loop; lint/build/missing-deps issues need nuke-and-reinstall.
-- **Fresh install is automatic** — [fresh-install](./steps/fresh-install.md) notifies, doesn't ask.
+---
+name: muggle-test-prepare
+model: opus
+description: "Get a user's local environment ready before running E2E acceptance tests — verify the dev servers, APIs, and sibling services they need are up and responding, and offer to start whatever is missing (with approval per step). Trigger when the user wants to confirm specific ports or localhost URLs are listening before testing (check if localhost:3000 and the api on 8080 are up, are my services running), spin up their local dev stack, or verify their setup — and whenever another muggle skill (muggle-test, muggle-do, muggle-test-feature-local) needs services running but they're not. This is environment readiness and service startup, not running the tests."
+---
+
+# Muggle Test Prepare
+
+> Telemetry first step: see [`_shared/telemetry-emit.md`](../_shared/telemetry-emit.md). Use `skillName: "muggle-test-prepare"`.
+
+Make sure the local services a user needs for E2E acceptance testing are up and ready. Check what's already running, discover sibling service directories by folder name, and offer to start anything that's missing — always with the user in control.
+
+Some users start their own services (tmux scripts, docker-compose, a terminal per service). Others want help launching them. This skill handles both: it verifies readiness first, and only offers to start things when something is missing.
+
+The skill runs in two phases because a dispatched agent has no channel back to the user. **Decide (in-session):** resolve every choice that needs a human — plan reuse, scope, exclusions, service selection, start approvals. **Execute (agent):** hand the fully-resolved plan to the `test-prepare-runner` agent (`plugin/agents/test-prepare-runner.md`); it runs the mechanical stages headless and returns the readiness verdict, or a `needs-input:` line for any decision the plan left open.
+
+## Privacy Boundary
+
+This skill touches the user's local machine — processes, ports, directories outside the current repo. Every action is explicit and confirmed.
+
+- **Folder names are public.** You may list directory names in a parent folder to discover sibling services.
+- **File contents are private until confirmed.** Never read files inside a directory the user hasn't explicitly identified as a service to start. Once confirmed, you may inspect only top-level project indicator files (`package.json`, `Makefile`, `Cargo.toml`, `go.mod`, `pyproject.toml`, `docker-compose.yml`) to determine the start command.
+- **Never traverse upward more than one level** from the current working directory to list folders.
+
+## PID Tracking
+
+All launched processes are tracked in `/tmp/muggle-test-prepare.json`:
+
+```json
+{
+  "session_started": "2025-01-15T10:30:00Z",
+  "testing_scope": "frontend",
+  "excluded_services": [
+    {"name": "payment-gateway", "reason": "Needs production certificates"}
+  ],
+  "services": [
+    {
+      "name": "backend-api",
+      "dir": "/Users/user/Github/backend-api",
+      "command": "npm run dev",
+      "pid": 12345,
+      "port": 3001,
+      "log": "/tmp/muggle-prepare-backend-api.log"
+    }
+  ]
+}
+```
+
+`testing_scope` records what the user is testing (from [scope](./steps/scope.md)). `excluded_services` records services the user said can't run locally (from [viability-check](./steps/viability-check.md)).
+
+This file is **ephemeral runtime state**, not the saved recipe. The durable plan lives at `<repo>/.muggle-ai/prepare-plan.json` (or the parent-dir-keyed entry in `~/.muggle-ai/prepare-plans.json`) and is consulted in [reuse-plan](./steps/reuse-plan.md) before any other stage. The two files never merge. The `test-prepare-runner` agent writes this file during execution; the triage below and Cleanup read it.
+
+**On every invocation**, check this file first. If it exists with live PIDs (verify with `kill -0`), `AskUserQuestion`:
+- Option 1: "Keep them running — skip to testing"
+- Option 2: "Tear down and start fresh"
+- Option 3: "Add more services to the running set"
+
+Prune dead PIDs silently.
+
+## Preferences
+
+Gates run per [`preference-gates/README.md`](../muggle-preferences/preference-gates/README.md). All three resolve in the Decide phase; the agent receives outcomes, never gates.
+
+| Preference | Gates |
+|------------|-------|
+| `autoRebase` | [rebase-check](./steps/rebase-check.md) — rebase onto `origin/<default>` before starting dev servers |
+| `reusePreparePlan` | [reuse-plan](./steps/reuse-plan.md) — reuse the saved prepare plan for this stack, or rediscover |
+| `autoSelectLocalHost` | [check-running](./steps/check-running.md) — reuse the recorded dev-server URL silently, or confirm it each run |
+
+## Workflow
+
+**Decide (in-session).** Run these stages in order; read each detail file when you reach it:
+
+| # | Stage | Summary |
+|:--|:------|:--------|
+| 0 | [reuse-plan](./steps/reuse-plan.md) | Reuse saved prepare plan (gated); on reuse, skip straight to dispatch |
+| 1 | [rebase-check](./steps/rebase-check.md) | Rebase onto default branch (gated) |
+| 2 | [scope](./steps/scope.md) | Frontend / backend / full stack |
+| 3 | [viability-check](./steps/viability-check.md) | Exclude services that can't run locally |
+| 4 | [identify-services](./steps/identify-services.md) | Pick required services + startup mode |
+
+The Decide phase's output is the **resolved prepare plan**: `services[]` (name, dir, start command, expected port, `external` flag, approval granted), `testingScope`, `excludedServices[]`, the recorded dev-server URL, and resolved gate outcomes.
+
+**Execute (agent).** Dispatch the `test-prepare-runner` agent (subagent type `muggle:test-prepare-runner`; bare `test-prepare-runner` where the plugin namespace is absent), synchronously, passing the resolved plan; it returns `READY` / `DEGRADED` plus the readiness table. The agent's own definition lists its stage files; in a harness with no agent/subagent facility, run the execute-phase stages ([check-running](./steps/check-running.md) through [readiness-report](./steps/readiness-report.md)) inline instead.
+
+Relay the readiness table to the user or calling skill verbatim. A `needs-input:` line from the agent names an unresolved decision — resolve it here (asking the user if needed) and re-dispatch; the agent never asks.
+
+## Cleanup
+
+Triggered when the user says "stop services", "tear down", "clean up", "I'm done testing", another skill signals run complete, or this skill is re-invoked with "tear down and start fresh". Runs in-session, not in the agent.
+
+1. Read `/tmp/muggle-test-prepare.json`
+2. Skip services marked `external: true`
+3. For each managed service: `kill <pid>` (SIGTERM)
+4. Wait ~2 s, verify with `kill -0`
+5. If still alive: `kill -9 <pid>`
+6. `rm -f /tmp/muggle-prepare-*.log`
+7. `rm -f /tmp/muggle-test-prepare.json`
+
+Report:
+
+```
+Stopped 3 services:
+  backend-api    (PID 12345)
+  auth-service   (PID 12346)
+  frontend       (PID 12347)
+```
+
+## Integration Contract (for other skills)
+
+`muggle-test-feature-local`, `muggle-do`, and local-mode `muggle-test` MUST invoke this skill before any workflow step. Idempotent — fast exit when healthy. Treat success as short-lived; re-invoke if more than a few minutes pass before testing. Never bypass on "the user knows their stack is up" — that assumption is why this skill exists.
+
+After a test run, the caller can re-invoke for cleanup or leave services running for the next run.
+
+## Guardrails
+
+- **Never invent or default a host/port** — the dev-server URL is a recorded value, not a guess. Resolve it from `<repo>/.muggle-ai/last-host.json` (the [`autoSelectLocalHost`](../muggle-preferences/preference-gates/autoSelectLocalHost.md) cache) before probing ports; a framework default like `:3000` is never a fallback. See [check-running](./steps/check-running.md).
+- **No silent auto-selection without a gate** — when no preference authorizes a silent choice (host, restart, kill), confirm with the user. A gate set to `always` is the only license to skip the question; absent that, ask.
+- **Verify first, offer to start second** — check what's already running before proposing to start anything.
+- **The user may prefer to start services themselves** — always offer that option.
+- **Never start a process the user didn't approve** — approvals are granted in Decide and travel in the plan; the agent starts nothing outside it.
+- **Never read file contents outside confirmed directories** — folder names are discoverable; file contents require explicit user selection.
+- **Never leave orphan processes untracked** — every background PID goes into the tracking file.
+- **Never kill a process the user started independently** — `external: true` survives cleanup.
+- **Never assume start commands** — verify via indicator file; confirm with user.
+- **Bail early on non-viable services** — don't start what can't run locally.
+- **Idempotent** — already-tracked alive services are kept; [smoke-test](./steps/smoke-test.md) still runs against them.
+- **Port-listening is never enough** — smoke-test (HTTP + body sniff + log tail) is mandatory before the final report.
+- **Clean Restart is the recommended fix** — first option in the smoke-test diagnose-and-fix loop; lint/build/missing-deps issues need nuke-and-reinstall.
+- **Fresh install is automatic** — [fresh-install](./steps/fresh-install.md) notifies, doesn't ask.