@muggleai/works 4.13.1 → 4.14.0

package/README.md

@@ -123,7 +123,7 @@ Call local execution MCP tools directly (for example `muggle-local-execute-test-
 
 ---
 
-## How does it work?
+## Architecture
 
 muggle-ai-works separates test management from test execution. All entity management (projects, use cases, test cases) lives in the cloud via `muggle-remote-*` tools. Local execution (`muggle-local-*`) is stateless — it receives what it needs and runs the test.
 
@@ -201,7 +201,7 @@ OPEN_PRS      → PR #42 opened
 DONE          → 1 iteration, all green
 ```
 
-- Session-based with crash recovery (`.muggle-do/sessions/`)
+- Session-based with crash recovery (`~/.muggle-ai/muggle-do/sessions/`)
 - Auto-triage: analyzes failures and loops back to fix (max 3 iterations)
 - Multi-repo support via `muggle-repos.json`
 - PRs include E2E acceptance results and screenshots in the description
@@ -556,7 +556,7 @@ CI/CD and publishing
 | `verify-end-user-upgrade.yml` | Weekly + manual | Existing-user upgrade validation (cleanup + re-download + health checks) |
 | `publish-works-to-npm.yml` | Tag `v*` or manual  | Verify (including release checksums), audit, smoke-install, publish to npm |
 
-**Publishing `@muggleai/works`:** use the repo-level skill **`plugin/skills/muggle-works-npm-release/SKILL.md`** (bump + `pnpm run sync:versions`, local verify, `chore(release)` PR, merge, then `workflow_dispatch` with an explicit `version`). Do not rely on tagging alone while `package.json` / marketplace manifests on `master` are still old — CI can publish a version that does not match the checked-in manifests. Tag `v*` push remains a valid workflow trigger when it matches the merged release commit.
+**Publishing `@muggleai/works`:** use the maintainer-only skill **`.claude/skills/muggle-works-npm-release/SKILL.md`** — a repo-local project skill (invoke `/muggle-works-npm-release` in Claude Code, or `/mrelease`, while working in this repo; mirrored to `.cursor/skills/` for Cursor). It is intentionally not in the published plugin (`plugin/skills/`) since it is maintainer-only. It does the bump + `pnpm run sync:versions`, local verify, `chore(release)` PR, merge, then `workflow_dispatch` with an explicit `version`. Do not rely on tagging alone while `package.json` / marketplace manifests on `master` are still old — CI can publish a version that does not match the checked-in manifests. Tag `v*` push remains a valid workflow trigger when it matches the merged release commit.
 
 Release tag strategy
 

package/dist/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "muggle",
   "description": "Run real-browser end-to-end (E2E) acceptance tests on your web app from any AI coding agent. Generate test scripts from plain English, replay them on localhost, capture screenshots, and validate user flows like signup, checkout, and dashboards. Works across Claude Code, Cursor, Codex, and Windsurf.",
-  "version": "4.13.1",
+  "version": "4.14.0",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/dist/plugin/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "muggle",
   "displayName": "Muggle AI",
   "description": "Ship quality products with AI-powered end-to-end (E2E) acceptance testing that validates your web app like a real user — from Claude Code and Cursor to PR.",
-  "version": "4.13.1",
+  "version": "4.14.0",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/dist/plugin/README.md

@@ -33,7 +33,7 @@ Type `muggle` to discover the full command family.
 | `/muggle:muggle-repair` | Diagnose and fix broken installation automatically. |
 | `/muggle:muggle-upgrade` | Update Electron browser test runner and MCP server to latest version. |
 
-Each skill above also ships a short alias to save typing — `m` (router), `mtest`, `mdo`, `mpr`, `mprefs`, `mstatus`, `mrepair`, `mupgrade`, `mfeedback`, `mimport`, `mtestlocal`, `mtestprep`, `mregen`, `mrelease`. Type `/m` (Claude Code) or `m` (Cursor) to open the menu, or jump straight to one (e.g. `/mtest`).
+Each skill above also ships a short alias to save typing — `m` (router), `mtest`, `mdo`, `mpr`, `mprefs`, `mstatus`, `mrepair`, `mupgrade`, `mfeedback`, `mimport`, `mtestlocal`, `mtestprep`, `mregen`. Type `/m` (Claude Code) or `m` (Cursor) to open the menu, or jump straight to one (e.g. `/mtest`).
 
 ## MCP Tools
 

package/dist/plugin/commands/mprfollowup.md

@@ -0,0 +1,7 @@
+---
+description: Watch a PR for review follow-ups (alias for /muggle-pr-followup)
+argument-hint: [PR url | slug pr-number | empty to auto-track]
+allowed-tools: [Skill]
+---
+
+Invoke the `muggle-pr-followup` skill via the Skill tool. Forward `$ARGUMENTS` as the skill's `args`.

package/dist/plugin/skills/_aliases.json

@@ -13,6 +13,6 @@
         "mtestlocal",
         "mtestprep",
         "mregen",
-        "mrelease"
+        "mprfollowup"
     ]
 }

package/dist/plugin/skills/_shared/resolve-e2e-validation-context.md

@@ -8,7 +8,7 @@ The sections below are the steps in order: reuse an existing context if one is o
 
 ## Reuse an existing context
 
-If a `## Pre-flight answers` block already exists for this working tree — the current session slot, or the most recent sibling session under `.muggle-do/sessions/*` — fire the [`autoReuseValidationContext`](../muggle-preferences/preference-gates/autoReuseValidationContext.md) gate before gathering anything:
+If a `## Pre-flight answers` block already exists for this working tree — the current session slot, or the most recent sibling session under `~/.muggle-ai/muggle-do/sessions/*` — fire the [`autoReuseValidationContext`](../muggle-preferences/preference-gates/autoReuseValidationContext.md) gate before gathering anything:
 
 - `always` → copy the existing block into this session; skip the questionnaire.
 - `never` → ignore it; run the full gather below.

package/dist/plugin/skills/do/address-reviews.md

@@ -19,7 +19,7 @@ Exact phrasing comes from the watcher's dispatch (see [`../muggle-pr-followup/co
 
 ## Inputs from disk
 
-Read from `.muggle-do/sessions/<slug>/`:
+Read from `~/.muggle-ai/muggle-do/sessions/<slug>/`:
 
 - `prs.json` — to locate the PR's local checkout path (the `repo` field maps to a configured local repo) and capture `head_sha_before`.
 - `last_seen.json` — for `pushed_shas[]` (used by the resolve-reminder stage) and to update the cursor.

package/dist/plugin/skills/do/build.md

@@ -20,7 +20,8 @@ For each affected repo:
 1. **Re-read `requirements.md`.** Treat goal + AC as frozen. If something is unclear at this stage, that's a pre-flight bug — escalate, do not improvise.
 2. **Apply the change** in the repo's worktree. Edit existing files first; create new files only when the requirements demand it. Match the surrounding code's style, naming, and file layout.
 3. **Don't add what wasn't asked for.** No speculative abstractions, no extra logging, no "while I'm here" refactors. Three similar lines is better than a premature abstraction.
-4. **Commit** with a conventional-commit subject:
+4. **Cover new logic with tests.** If you added or changed non-trivial logic (a hook, reducer, parser, state machine, branching util), write its unit tests now — Stage 5 only *runs* the suite, it never authors tests. Untested new logic is a Definition-of-Done failure, not a Stage-5 gap.
+5. **Commit** with a conventional-commit subject:
    - `feat(<scope>): <short>` for new behavior
    - `fix(<scope>): <short>` for bug fixes
    - `refactor(<scope>): <short>` for reshape

package/dist/plugin/skills/do/open-prs/forward.md

@@ -40,13 +40,13 @@ Forward pipeline's Stage 7. Invoked by `/muggle-do` after stages 1–6 of a fres
 
 After every repo is processed, build the watcher manifest and dispatch one watcher loop per opened PR. The dispatches are the LAST action this stage takes.
 
-Write `.muggle-do/sessions/<slug>/prs.json` per [`../../muggle-pr-followup/state-schemas.md`](../../muggle-pr-followup/state-schemas.md#prsjson):
+Write `~/.muggle-ai/muggle-do/sessions/<slug>/prs.json` per [`../../muggle-pr-followup/state-schemas.md`](../../muggle-pr-followup/state-schemas.md#prsjson):
 
 ```json
 [{ "repo": "owner/repo", "number": 142, "url": "...", "head_sha": "...", "state": "open" }]
 ```
 
-Seed `.muggle-do/sessions/<slug>/last_seen.json` per [`../../muggle-pr-followup/state-schemas.md`](../../muggle-pr-followup/state-schemas.md#last_seenjson) — empty cursor shape with `pushed_shas: []`. Forward mode never has prior reviews to skip, so `reviewId: 0`.
+Seed `~/.muggle-ai/muggle-do/sessions/<slug>/last_seen.json` per [`../../muggle-pr-followup/state-schemas.md`](../../muggle-pr-followup/state-schemas.md#last_seenjson) — empty cursor shape with `pushed_shas: []`. Forward mode never has prior reviews to skip, so `reviewId: 0`.
 
 **Do not** seed `cycle.json` or `requirements.md`. The watcher is a dumb pipe; `/muggle-do` reads reviews off GitHub.
 

package/dist/plugin/skills/do/open-prs/update.md

@@ -13,7 +13,7 @@ Does **not** create a PR, seed session state, or dispatch a watcher (`/muggle-do
 ## Inputs
 
 - Per-repo: path, branch (head ref name).
-- The existing PR URL + number from `.muggle-do/sessions/<slug>/prs.json`.
+- The existing PR URL + number from `~/.muggle-ai/muggle-do/sessions/<slug>/prs.json`.
 - **Optional** E2E acceptance report from stage 6. Produced by [`../e2e-acceptance.md`](../e2e-acceptance.md); schema in [`../../muggle-pr-visual-walkthrough/SKILL.md`](../../muggle-pr-visual-walkthrough/SKILL.md).
 
 ## Procedure

package/dist/plugin/skills/mprfollowup/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: mprfollowup
+description: Explicit short alias for the `muggle-pr-followup` skill. ONLY invoke when the user explicitly types `mprfollowup` or `/mprfollowup` — never auto-trigger from any other phrasing.
+---
+
+# mprfollowup — alias for muggle-pr-followup
+
+Invoke the `muggle-pr-followup` skill via the Skill tool. Forward any user-provided arguments unchanged.

package/dist/plugin/skills/muggle/SKILL.md

@@ -37,6 +37,7 @@ If the user intent clearly matches one command, route directly — no menu neede
 - test localhost/validate single feature/test a feature → `muggle-test-feature-local`
 - build/implement from request/end-to-end → `muggle-do`
 - post results to PR/attach walkthrough/visual evidence on PR → `muggle-pr-visual-walkthrough`
+- watch my PR for reviews/follow up on PR reviews/babysit PR review thread → `muggle-pr-followup`
 - give feedback on a run/the test was wrong/step N didn't work/show my feedback/delete feedback → `muggle-feedback`
 
 If intent is ambiguous, use `AskUserQuestion` with the most likely options rather than asking the user to type a clarification.

package/dist/plugin/skills/muggle-do/SKILL.md

@@ -25,6 +25,31 @@ Runs an autonomous dev cycle from requirements to PR. **Fire and review:** user
 
 Stage 7 dispatches one watcher per opened PR as its last action.
 
+## Execution protocol (non-negotiable)
+
+The pipeline table lists **pointers, not summaries**. Open each stage's file and execute from it — running a stage off its one-line row here is how tests, E2E, and session state get silently skipped. If you have not read a stage's file this run, you have not run that stage.
+
+**Bootstrap before any code, in order:**
+1. Emit telemetry — [`../_shared/telemetry-emit.md`](../_shared/telemetry-emit.md), `skillName: "muggle-do"`.
+2. Create `~/.muggle-ai/muggle-do/sessions/<slug>/` with `state.md` + `iterations/001.md` (pre-flight owns this; do it even when running unattended).
+3. `TodoWrite` one item per stage 1–8 — these stages are the checklist; never swap in your own decomposition.
+
+**Per stage:** read the file → execute it → append a marker to `iterations/<NNN>.md` citing the evidence that file requires (jest exit code, E2E verdict + `runId`, screenshot path). A stage is done only when its evidence is written, never on recollection.
+
+### "Autonomous" / "without my intervention" collapses exactly one thing
+Best-effort the Stage-1 questionnaire and don't ask. It does **not** license skipping telemetry, session artifacts, requirements, unit tests, E2E (`autoE2ETest` defaults to `always`), browser verification, the gate below, or the watcher hand-off. Run the whole pipeline silently — never a shortcut.
+
+### Definition of Done — gate before Stage 7
+Do not create or update a PR until each line holds, or is waived by a one-line reason written into `state.md` (silence is not a waiver):
+- `requirements.md` written (forward runs)
+- Build clean — typecheck + lint on changed files
+- New/changed logic carries unit tests (authored in Stage 3; Stage 5 only runs the suite)
+- Unit suite run, PASS recorded
+- E2E verdict recorded with `runId` per `autoE2ETest` — or `[E2E FAILING]` / `SKIPPED` + reason
+- UI changes verified in a real browser with evidence (screenshot path or muggle `runId`); `curl` + `grep` is not verification
+
+Opening a PR with an unchecked, unwaived line is a cycle failure.
+
 ## Address-reviews flow
 
 When invoked with the directive (PR URL + slug + review ids), routes to [`../do/address-reviews.md`](../do/address-reviews.md). Shares stages 3–6 + walkthrough with the forward pipeline; skips pre-flight, requirements, and PR creation. See the orchestrator for the cycle's exact step order, classification rules, and respawn logic.
@@ -50,7 +75,7 @@ When in doubt between #3 and #4, ask one question.
 
 ## Session model
 
-`.muggle-do/sessions/<slug>/`. Schemas: [`../muggle-pr-followup/state-schemas.md`](../muggle-pr-followup/state-schemas.md).
+`~/.muggle-ai/muggle-do/sessions/<slug>/`. Schemas: [`../muggle-pr-followup/state-schemas.md`](../muggle-pr-followup/state-schemas.md).
 
 | File | Owner |
 | :--- | :---- |

package/dist/plugin/skills/muggle-feedback/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: muggle-feedback
-description: Capture feedback on a generated Muggle Test action script — either step-level or whole-script — and submit it so the system can analyze it and regenerate affected scripts. Use when the user has just run a Muggle Test (local or remote) and wants to flag what went wrong, when they paste a Muggle dashboard URL with a test script or run, or when they want to view or delete previously submitted feedback. Triggers on: '/muggle-feedback', 'give feedback on this run', 'the test was wrong', 'step N didn't work', 'the script clicked the wrong button', 'flag this run', 'the summary is wrong', 'show my feedback', 'list feedback', 'delete that feedback'. Skill auto-detects the run context from a recent local run, a remote run, or a Muggle dashboard URL in the prompt.
+description: Use when the user wants to flag that a generated Muggle Test action script — or one specific step in it — did the wrong thing, and have it captured so Muggle can analyze and regenerate affected scripts. Covers any report that a script or step is wrong, broken, or misbehaving (clicked the wrong element, bad summary, "step N didn't work", "broken at the submit step"), whether the user just ran a test locally or remotely or pastes a Muggle dashboard run/script URL and points at what failed. Also use to view, list, or delete previously submitted feedback. Triggers on '/muggle-feedback', 'give feedback on this run', 'the test was wrong', 'flag this run', 'show/list/delete my feedback'. Auto-detects run context from a recent local run, a remote run, or a dashboard URL in the prompt.
 ---
 
 # Muggle Test Feedback

package/dist/plugin/skills/muggle-pr-followup/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: muggle-pr-followup
-description: Watcher loop for PR review follow-ups. Polls one PR for new submitted reviews and dispatches `/muggle-do` (address-reviews mode) when there are any. A dumb pipe — no classification, no cycle execution, no replies. Run it with no args to auto-track every PR you pushed this session (poll-only watchers, any repo). Use `/loop 1m /muggle:muggle-pr-followup <slug> <pr-number>` for ongoing polling, or `/muggle:muggle-pr-followup <pr-url>` to bootstrap a fresh watcher on an existing PR (asks once for the E2E validation context, then runs unattended).
-disable-model-invocation: true
+description: Use this skill when the user wants a pull request's incoming review feedback handled for them — it watches one PR's review thread and, each time a reviewer submits new comments, dispatches the work to address them. Engage on PR-review-follow-up intent: "watch my PR and address review comments as they come in", "keep an eye on PR #123 and respond to reviewer feedback", "follow up on my PR's reviews", "babysit my PR's review thread", "auto-handle reviews on the PR I just opened", "I'm stepping away — handle my PR's reviews while I'm gone". Run with no args to track every PR you pushed this session (any repo); pass a PR URL to start watching a specific one. This is PR-review-specific automation: when the recurring thing the user wants handled is a PR's review comments, use this — not the generic `loop` skill. It only watches and dispatches; the actual edits and replies are `muggle-do`. Not for posting test results to a PR (use muggle-pr-visual-walkthrough).
 ---
 
 # muggle-pr-followup

package/dist/plugin/skills/muggle-pr-followup/bootstrap.md

@@ -37,11 +37,13 @@ Per [`../_shared/github-cli-recipes/verify-working-tree.md`](../_shared/github-c
 
 ### Step 4 — Resolve the slug
 
-Default: `<repo>-pr<n>` (e.g. `muggle-ai-works-pr154`). Override: `--slug=<name>`. Session dir is `.muggle-do/sessions/<slug>/` relative to the caller's working tree.
+Default: `<repo>-pr<n>` (e.g. `muggle-ai-works-pr154`). Override: `--slug=<name>`. Session dir is `~/.muggle-ai/muggle-do/sessions/<slug>/` (under the user's home, shared across repos; the slug's repo-pr<n> prefix keeps it unique).
 
 ### Step 5 — Idempotency check
 
-If `.muggle-do/sessions/<slug>/` exists:
+**Legacy-slot migration.** Pre-move sessions lived at the repo-relative `.muggle-do/sessions/<slug>/` ([`state-schemas.md`](state-schemas.md#legacy-location)). If the new home-dir slot is absent but `<working-tree>/.muggle-do/sessions/<slug>/` exists (working tree from Step 3), move it to the new location first — this carries an in-flight watcher's cursor, `escalated_review_ids`, and `pushed_shas` across the upgrade. Bootstrap is the only stage that performs this: it is the one entry point that knows the old repo-relative path (the cwd), and it is the natural re-entry point after a plugin upgrade. A slot that fails to migrate loses nothing durable — GitHub holds the reviews, so a fresh bootstrap (cursor `0`) re-processes them.
+
+If `~/.muggle-ai/muggle-do/sessions/<slug>/` exists (including a slot just migrated above):
 
 - Without `--resume` → exit with the slot-conflict abort. Both remedies (delete + re-run, or pass `--resume`) are spelled out in the message.
 - With `--resume` → refresh `prs.json[0].head_sha` to the current `headRefOid` from Step 2; leave `last_seen.json` and the cursor untouched. If `state.md` already has a `## Pre-flight answers` block, skip to Step 8; if not (older session), run Step 6.5 to backfill it, then skip to Step 8.
@@ -61,7 +63,7 @@ Capture the fields for Step 7. Do **not** run E2E now — the first watcher tick
 
 Identify the loop user once per [`../_shared/github-cli-recipes/loop-user-identity.md`](../_shared/github-cli-recipes/loop-user-identity.md); cache in `state.md`.
 
-Write under `.muggle-do/sessions/<slug>/`:
+Write under `~/.muggle-ai/muggle-do/sessions/<slug>/`:
 
 **`prs.json`** — see [`state-schemas.md`](state-schemas.md#prsjson). One entry, `state` = `"open"`, `head_sha` from Step 2's `headRefOid`.
 

package/dist/plugin/skills/muggle-pr-followup/contract.md

@@ -16,7 +16,7 @@ Routing into this mode is documented in [`SKILL.md`](SKILL.md#routing). The arch
 
 ## Inputs from disk
 
-Read these from `.muggle-do/sessions/<slug>/`:
+Read these from `~/.muggle-ai/muggle-do/sessions/<slug>/`:
 
 - `prs.json` — see [`state-schemas.md`](state-schemas.md#prsjson). The watcher touches the single entry whose `number` matches the dispatched PR number.
 - `last_seen.json` — see [`state-schemas.md`](state-schemas.md#last_seenjson). Keyed by `"<owner>/<repo>#<n>"`.

package/dist/plugin/skills/muggle-pr-followup/state-schemas.md

@@ -1,9 +1,13 @@
 # Session State Schemas
 
-Canonical shapes for the JSON files in a PR-follow-up session slot. The slot path is `.muggle-do/sessions/<slug>/` (the caller's session dir; `muggle-do` is the current and only caller).
+Canonical shapes for the JSON files in a PR-follow-up session slot. The slot path is `~/.muggle-ai/muggle-do/sessions/<slug>/` (under the user's home, shared across repos; `muggle-do` is the current and only caller).
 
 All files are atomic writes — the caller rewrites the whole file each time, never mutates in place. Use a temp file + rename if the platform supports it.
 
+## Legacy location
+
+Before the move to the user's home, slots lived at the repo-relative `.muggle-do/sessions/<slug>/` (one per working tree, still gitignored). Bootstrap's Step 5 migrates a legacy slot to the home-dir location on the next run for that PR; nothing else reads the old path. The state is ephemeral and reconstructible from GitHub, so an un-migrated slot costs only a re-bootstrap, not data.
+
 ## `prs.json`
 
 A list of one entry. (Historical: the file is an array for forward-compat with the original session-wide model. Today, each PR has its own session slot, so the array always has exactly one entry.)

package/dist/plugin/skills/muggle-preferences/ops/configure.md

@@ -28,7 +28,8 @@ For each option: label = key name, description = first paragraph of `preference-
 - `multiSelect: true`, `header: "Auth & session"` — `autoLogin`, `autoSelectProject`, `checkForUpdates`, `verboseOutput`
 - `multiSelect: true`, `header: "Test setup"` — `autoSelectLocalHost`, `autoDetectChanges`, `autoReuseValidationContext`
 - `multiSelect: true`, `header: "Test run"` — `showElectronBrowser`, `openTestResultsAfterRun`, `autoPublishLocalResults`
-- `multiSelect: true`, `header: "Suggestions & PR"` — `suggestRelatedUseCases`, `suggestRelatedTestCases`, `postPRVisualWalkthrough`, `autoCreatePR`
+- `multiSelect: true`, `header: "Suggestions"` — `suggestRelatedUseCases`, `suggestRelatedTestCases`
+- `multiSelect: true`, `header: "PR"` — `postPRVisualWalkthrough`, `autoCreatePR`, `autoWatchPR`
 - `multiSelect: true`, `header: "Branch hygiene"` — `autoUseWorktree`, `autoRebase`, `autoCleanup`
 - `multiSelect: false`, `header: "E2E acceptance"` — `autoE2ETest`. Options: `Always run Stage 6 at the end` (`always` — default), `Ask each cycle` (`ask`). No `never` option.
 - `multiSelect: false`, `header: "Default mode"` — `defaultExecutionMode`. Options: `Local — run on my computer` (`local`), `Remote — run in the Muggle Test cloud` (`remote`), `Ask each time` (don't change).

package/dist/plugin/skills/muggle-preferences/preference-gates/autoWatchPR.md

@@ -0,0 +1,13 @@
+# `autoWatchPR`
+
+After a PR is sent at the end of a test run, controls whether Muggle starts a `muggle-pr-followup` watcher on it — a loop that polls the PR for newly submitted reviews and hands them to `/muggle-do` to address — or leaves you to start one yourself with `/mprfollowup`. Fires once a PR exists (muggle-test, muggle-test-feature-local), reusing the E2E validation context from that run so the watcher never re-prompts. Substitute `{pr}`.
+
+**Picker 1** — header `Watch PR?`, question `"Watch '{pr}' for review follow-ups and address them as they land?"`
+- `Watch it` — `Start a muggle-pr-followup loop on this PR.` → `always`
+- `Ask me next time` — `Decide per run.` → `ask`
+- `Skip — I'll watch it myself` — `Leave it; run /mprfollowup later if you want.` → `never`
+
+**Silent action**
+- `always` → `Watching {pr} for review follow-ups`
+- `ask` → `Asking about PR watching`
+- `never` → `Not watching {pr}`

package/dist/plugin/skills/muggle-preferences/preference-gates/reusePreparePlan.md

@@ -0,0 +1,11 @@
+# `reusePreparePlan`
+
+Reuse the saved prepare plan for this stack (skip scope / viability / service-selection / start-commands and jump straight to check-running + smoke-test), or rediscover from scratch. Substitute `{services}` with a comma-separated list of saved service names.
+
+**Picker 1** — header `Reuse prepare plan`, question `"Found a saved plan for this stack ({services}) — reuse it, or rediscover from scratch?"`
+- `Reuse this plan` — `Skip the discovery questions; verify and start what's missing.` → `always`
+- `Rediscover from scratch` — `Re-ask scope, services, and start commands.` → `never`
+
+**Silent action**
+- `always` → `Reusing saved prepare plan ({services})`
+- `never` → `Rediscovering this stack from scratch`

package/dist/plugin/skills/muggle-status/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: muggle-status
-description: Check health of the Muggle AI installation. Use when user types muggle status, asks for Muggle Test health, MCP health, or auth validity.
+description: Use this skill to check the health of the user's Muggle AI installation and diagnose why it's misbehaving — MCP server connectivity, tool loading, login/auth validity, and overall setup. Engage on an explicit "muggle status", but also on any diagnostic question about Muggle itself: "is muggle working / healthy / set up right?", "why does muggle keep failing / timing out / saying it can't connect?", "are the muggle MCP tools actually loading?", "is my muggle login/auth still valid?", "muggle's been acting up — take a look / what's wrong?", "muggle commands fail silently — is the install unhealthy?". This is diagnosis and reporting: prefer it over answering from memory whenever the user is unsure Muggle itself is functioning. Boundary: checking/diagnosing is muggle-status; actually fixing a broken install is muggle-repair (a clear "fix it" goes there). Not for the health of the user's own app, CI, or infrastructure.
 ---
 
 # Muggle Test Status

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

@@ -1,6 +1,6 @@
 ---
 name: muggle-test
-description: "Run change-driven E2E acceptance testing using Muggle AI — detects local code changes, maps them to use cases, and generates test scripts either locally (real browser on localhost) or remotely (cloud execution on a preview/staging URL). Publishes results to Muggle Test dashboard, opens them in the browser, and posts E2E acceptance summaries with screenshots to the PR. Use this skill whenever the user wants to test their changes, run E2E acceptance tests on recent work, validate what they've been working on, or check if their code changes broke anything. Triggers on: 'test my changes', 'run tests on my changes', 'acceptance test my work', 'check my changes', 'validate my changes', 'test before I push', 'make sure my changes work', 'regression test my changes', 'test on preview', 'test on staging'. This is the go-to skill for change-driven E2E acceptance testing — it handles everything from change detection to test execution to result reporting."
+description: "Run change-driven E2E acceptance testing using Muggle AI — detect the user's recent code changes (local diff or a PR), map them to affected user flows, then run real-browser acceptance tests on localhost or a deployed preview/staging URL, publish results to the dashboard, and post a screenshot summary to the PR. Use this whenever the user wants to test, validate, check, or regression-test their own changes or work — 'test my changes', 'validate my changes', 'regression test my work', 'make sure I didn't break anything', 'did my recent commits/changes break anything or any user flows?', 'test before I push' — and especially as the acceptance-test gate before opening a pull request or merging (e.g. 'validate my changes before I open the PR' means run the acceptance suite, not just a completion checklist). The defining signal is change-driven validation of in-progress work tied to a commit, push, PR, or merge. For testing one specific named feature/flow use muggle-test-feature-local; this is not importing existing tests, configuring preferences, or replaying a single named script."
 ---
 
 # Muggle Test — Change-Driven E2E Acceptance Router
@@ -49,6 +49,7 @@ Gates run per `preference-gates/README.md`.
 | `showElectronBrowser` | 7A | Show the Electron browser window during local test execution (vs. run headless) |
 | `postPRVisualWalkthrough` | 9 | Post visual walkthrough to PR after results are available |
 | `autoCreatePR` | 9 (if no PR) | Auto-create the PR when posting the walkthrough has no PR to target |
+| `autoWatchPR` | 9.5 (if a PR exists) | Start a `muggle-pr-followup` watcher on the PR after the run |
 
 ## Step 1: Confirm Scope of Work (Always First)
 
@@ -413,12 +414,24 @@ Tell the user:
 
 After reporting results:
 
-1. Fire [`postPRVisualWalkthrough`](../muggle-preferences/preference-gates/postPRVisualWalkthrough.md). On skip → Step 10.
+1. Fire [`postPRVisualWalkthrough`](../muggle-preferences/preference-gates/postPRVisualWalkthrough.md). On skip → Step 9.5.
 2. `gh pr view --json number,title,url 2>/dev/null` — find the PR.
-3. If no PR: fire [`autoCreatePR`](../muggle-preferences/preference-gates/autoCreatePR.md). On skip → Step 10.
+3. If no PR: fire [`autoCreatePR`](../muggle-preferences/preference-gates/autoCreatePR.md). On skip → Step 9.5.
 4. Assemble the `E2eReport` — see [`../muggle-pr-visual-walkthrough/e2e-report-assembly.md`](../muggle-pr-visual-walkthrough/e2e-report-assembly.md). Include all runs from Step 7A (passed and failed).
 5. Invoke [`../muggle-pr-visual-walkthrough/SKILL.md`](../muggle-pr-visual-walkthrough/SKILL.md) Mode A with the `E2eReport`.
 
+## Step 9.5: Offer to watch the PR for review follow-ups
+
+Once a PR exists for this work, offer to keep watching its review thread.
+
+1. Identify the PR — reuse the `gh pr view --json number,title,url` result from Step 9 if available, else run it now. No PR (none exists, none created) → Step 10.
+2. Fire [`autoWatchPR`](../muggle-preferences/preference-gates/autoWatchPR.md) with `{pr}` = `<owner>/<repo>#<number>`. On skip → Step 10.
+3. On proceed: start the watcher reusing this run's context so it never re-prompts —
+   - Seed the `muggle-pr-followup` session slot and dispatch its loop per the stage-8 seeding in [`../do/open-prs/forward.md`](../do/open-prs/forward.md) (default slug `<repo>-pr<number>`).
+   - Additionally write `state.md`'s `## Pre-flight answers` block from the context resolved this run — validation strategy, local URL, project, credentials, auth, working tree — per [`../_shared/resolve-e2e-validation-context.md`](../_shared/resolve-e2e-validation-context.md#persisted-fields). Strategy = `local-e2e` (local run), `staging-replay` (remote), or `unit-only`/`skip` if no E2E ran.
+
+The `/mprfollowup` shortcut starts the same watcher manually at any time.
+
 ## Step 10: Offer feedback on failures
 
 After the report is complete, if **any** test in the run had a `failed` or unexpected status (or the user verbally flags something looked off), suggest the feedback skill:

package/dist/plugin/skills/muggle-test-feature-local/SKILL.md

@@ -51,6 +51,7 @@ Gates run per `preference-gates/README.md`.
 | `openTestResultsAfterRun` | 8 | Open results page on Muggle Test dashboard after run |
 | `postPRVisualWalkthrough` | 10 | Post visual walkthrough to PR after results |
 | `autoCreatePR` | 10 (if no PR) | Auto-create the PR when posting the walkthrough has no PR to target |
+| `autoWatchPR` | 10.5 (if a PR exists) | Start a `muggle-pr-followup` watcher on the PR after the run |
 | `autoCleanup` | post-merge | Run cleanup after the PR for this work is merged (see [`_shared/post-merge-cleanup.md`](../_shared/post-merge-cleanup.md)) |
 
 ## Workflow
@@ -242,12 +243,24 @@ Non-blocking — one click to dismiss. Do not re-ask for the same `runId` within
 
 After reporting results:
 
-1. Fire [`postPRVisualWalkthrough`](../muggle-preferences/preference-gates/postPRVisualWalkthrough.md). On skip → end.
+1. Fire [`postPRVisualWalkthrough`](../muggle-preferences/preference-gates/postPRVisualWalkthrough.md). On skip → 10.5.
 2. `gh pr view --json number,title,url 2>/dev/null` — find the PR.
-3. If no PR: fire [`autoCreatePR`](../muggle-preferences/preference-gates/autoCreatePR.md). On skip → end.
+3. If no PR: fire [`autoCreatePR`](../muggle-preferences/preference-gates/autoCreatePR.md). On skip → 10.5.
 4. Assemble the `E2eReport` — see [`../muggle-pr-visual-walkthrough/e2e-report-assembly.md`](../muggle-pr-visual-walkthrough/e2e-report-assembly.md).
 5. Invoke [`../muggle-pr-visual-walkthrough/SKILL.md`](../muggle-pr-visual-walkthrough/SKILL.md) Mode A with the `E2eReport`.
 
+### 10.5. Offer to watch the PR for review follow-ups
+
+Once a PR exists for this work, offer to keep watching its review thread.
+
+1. Identify the PR — reuse the `gh pr view --json number,title,url` result from section 10 if available, else run it now. No PR (none exists, none created) → end.
+2. Fire [`autoWatchPR`](../muggle-preferences/preference-gates/autoWatchPR.md) with `{pr}` = `<owner>/<repo>#<number>`. On skip → end.
+3. On proceed: start the watcher reusing this run's context so it never re-prompts —
+   - Seed the `muggle-pr-followup` session slot and dispatch its loop per the stage-8 seeding in [`../do/open-prs/forward.md`](../do/open-prs/forward.md) (default slug `<repo>-pr<number>`).
+   - Additionally write `state.md`'s `## Pre-flight answers` block from the context resolved this run — validation strategy, local URL, project, credentials, auth, working tree — per [`../_shared/resolve-e2e-validation-context.md`](../_shared/resolve-e2e-validation-context.md#persisted-fields). Strategy = `local-e2e` for this local E2E run.
+
+The `/mprfollowup` shortcut starts the same watcher manually at any time.
+
 ## Non-negotiables
 
 - No silent auth skip.

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

@@ -1,6 +1,6 @@
 ---
 name: muggle-test-prepare
-description: "Make sure dev servers and sibling services are ready on the user's machine before running E2E acceptance tests. Checks which services need to be running, discovers sibling directories by folder name, verifies what's already listening, and offers to start anything that's missing — with the user's approval at every step. Use this skill whenever the user needs to prepare their local environment for E2E testing, verify their services are up, get their local dev stack ready, or when other muggle skills detect that required services are not listening on common ports. Triggers on: 'prepare for testing', 'make sure my services are running', 'check my local env', 'get ready for tests', 'are my services up', 'prepare local environment', 'spin up services', 'set up for E2E', 'verify my setup'. Also use when muggle-test, muggle-do, or muggle-test-feature-local need services running."
+description: "Use this skill to get a user's local environment ready before running E2E acceptance tests — verifying that the dev servers, APIs, and sibling services they need are actually up and responding, and offering to start whatever is missing (with approval at each step). Trigger whenever the user wants to confirm that specific ports or localhost URLs are listening/up before testing (e.g. 'check if localhost:3000 and the api on 8080 are listening', 'are my services up?'), make sure required services are running, spin up or prepare 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 listening on the expected ports. This is environment readiness and service startup, not running the tests themselves."
 ---
 
 # Muggle Test Prepare
@@ -45,6 +45,8 @@ All launched processes are tracked in `/tmp/muggle-test-prepare.json`:
 
 `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"
@@ -59,6 +61,7 @@ Gates run per [`preference-gates/README.md`](../muggle-preferences/preference-ga
 | 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 |
 
 ## Workflow
 
@@ -66,6 +69,7 @@ Run the stages in this order. The sequence number is display-only — it lives o
 
 | # | 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 |

package/dist/plugin/skills/muggle-test-prepare/steps/check-running.md

@@ -6,7 +6,7 @@ Run port detection and (when an app declares a backend URL) backend-health probe
 
 If **all** required services are running, skip straight to [smoke-test](./smoke-test.md) — don't trust port-listening alone.
 
-If some are running, acknowledge and continue to [start-commands](./start-commands.md) only for the missing ones. For already-running services:
+If some are running, acknowledge and continue to [start-commands](./start-commands.md) only for the missing ones. **Exception:** when this stage is entered via the [reuse-plan](./reuse-plan.md) short-circuit, the missing entries already have their `command` populated in `/tmp/muggle-test-prepare.json` from the reused plan — skip `start-commands` and go straight to [env-file](./env-file.md). For already-running services:
 - Option 1: "It's fine, keep it"
 - Option 2: "Restart it"
 
@@ -16,11 +16,13 @@ Mark kept services as `external: true` in the tracking file so cleanup leaves th
 
 When the user wants a port held by a process they did **not** select (typically a stale dev server from a sibling worktree):
 
-> "Port 3999 is held by PID 87421 (you didn't select this process). How do you want to proceed?"
+The held process is likely something the user is still using — a current test or dev server they value more than this prepare run. Don't auto-decide; leave the kill-vs-pause call to them.
 
-- Option 1: "Use the next available port" (recommended — non-destructive)
-- Option 2: "Force-kill PID 87421 and claim port 3999"
-- Option 3: "Abort"
+> "Port 3999 is held by PID 87421 (you didn't select this process — it may be a test or dev server you're still using). How do you want to proceed?"
+
+- Option 1: "Use the next available port" (recommended — non-destructive, leaves the existing process running)
+- Option 2: "Force-kill PID 87421 and claim port 3999" (kill-switch — only if you don't need that process)
+- Option 3: "Pause — leave it running, I'll finish up and re-run prepare later"
 
 **Option 1**: probe `3999 + N` for `N = 1, 2, …` until nothing listens. Record the new port and any env file edit (`PORT=` in `.env.local` etc.). Dev server may need restart to pick up.
 

package/dist/plugin/skills/muggle-test-prepare/steps/identify-services.md

@@ -1,5 +1,7 @@
 # Identify required services & startup mode
 
+> Skipped when [reuse-plan](./reuse-plan.md) short-circuits — a reused plan supplies the service list and startup mode.
+
 List folder names in the **parent directory** of the current working directory:
 
 ```bash

package/dist/plugin/skills/muggle-test-prepare/steps/readiness-report.md

@@ -24,3 +24,33 @@ If you launched the services:
 Logs: /tmp/muggle-prepare-*.log
 Cleanup: say "stop services" or re-invoke this skill.
 ```
+
+## Save the plan
+
+If this run came through discovery (i.e. Stage 0 [reuse-plan](./reuse-plan.md) did **not** short-circuit), persist the plan so the next run can skip the questions.
+
+Build the JSON from the in-memory tracking file, dropping runtime fields:
+
+```bash
+jq '{
+  version: 1,
+  updated: now | todate,
+  testing_scope: .testing_scope,
+  excluded_services: .excluded_services,
+  services: [.services[] | {name, dir, command, port}]
+}' /tmp/muggle-test-prepare.json
+```
+
+Resolve the write location:
+
+- If `git rev-parse --show-toplevel` succeeds (call the result `$REPO`) → write `$REPO/.muggle-ai/prepare-plan.json`. Create `$REPO/.muggle-ai/` if missing.
+- Else → upsert the entry under key `$(dirname "$PWD")` (absolute) in `~/.muggle-ai/prepare-plans.json`. Create the file as `{}` if missing.
+
+Then print, once:
+
+```
+✓ Saved this stack as your prepare plan — next run can skip the questions.
+  (Disable with `/muggle-preferences reusePreparePlan`.)
+```
+
+If this run short-circuited via [reuse-plan](./reuse-plan.md), don't rewrite — but **do** refresh `updated` and any `command` that was re-derived during validation. Skip the announcement on the refresh path.

package/dist/plugin/skills/muggle-test-prepare/steps/reuse-plan.md

@@ -0,0 +1,44 @@
+# Stage 0 — reuse saved plan (or fall through)
+
+A previously saved **prepare plan** is the durable recipe for this stack. Distinct from the ephemeral `/tmp/muggle-test-prepare.json` tracker — that file holds live PIDs/logs and is rebuilt every run.
+
+## Resolve
+
+In order; first hit wins.
+
+1. **Project plan.** If `git rev-parse --show-toplevel` succeeds (call the result `$REPO`) and `$REPO/.muggle-ai/prepare-plan.json` exists → load it.
+2. **Global plan.** Else if `~/.muggle-ai/prepare-plans.json` exists, read the entry keyed by `$(dirname "$PWD")` (absolute path). If present → load that entry's value.
+3. **No plan found** → exit this step; the workflow continues at [rebase-check](./rebase-check.md).
+
+A loaded plan is a JSON object with `version`, `updated`, `testing_scope`, `excluded_services`, `services`. Reject and treat as "no plan" if `version != 1` or `services` is empty.
+
+## Gate `reusePreparePlan`
+
+Per [`muggle-preferences/preference-gates/README.md`](../../muggle-preferences/preference-gates/README.md). Read the current value from the `Muggle Test Preferences` session-context line; absent → `ask`.
+
+- `always` → silently take the **reuse path** (below). Print the silent footer (substitute `{services}` with the comma-separated names from the loaded plan).
+- `never` → take the **rediscover path**: exit this step; continue at [rebase-check](./rebase-check.md).
+- `ask` → print the loaded plan as a table:
+
+  ```
+  Service              Directory                          Command          Port
+  ──────────────────────────────────────────────────────────────────────────────
+  backend-api          ~/Github/backend-api               npm run dev      3001
+  …
+  ──────────────────────────────────────────────────────────────────────────────
+  ```
+
+  Run Picker 1 from the gate file (substitute `{services}`). Then Picker 2 ("Remember this choice?") per the shared template. Branch by Picker 1.
+
+## Reuse path
+
+1. **Validate per service entry.** For each `{name, dir, command, port}`:
+   - `dir` exists → keep. Else drop the entry and log `"Dropped <name>: directory <dir> no longer exists"`.
+   - The indicator file that produced `command` still exists in `dir` (e.g. `package.json` for an `npm`/`node` command; see the indicator table in [start-commands](./start-commands.md)) → keep. Else re-derive **just that one entry** by running the indicator-detection from [start-commands](./start-commands.md) against `dir`, and replace its `command`. Log `"Re-derived <name>: <old> → <new>"`.
+2. **All entries dropped** → discard the plan; continue at [rebase-check](./rebase-check.md). Otherwise proceed with surviving + re-derived entries.
+3. **Hydrate** `/tmp/muggle-test-prepare.json` with the surviving entries (no PIDs yet, `testing_scope` from the plan, `excluded_services` from the plan).
+4. **Short-circuit** to [check-running](./check-running.md). The skipped stages are [scope](./scope.md), [viability-check](./viability-check.md), [identify-services](./identify-services.md), [start-commands](./start-commands.md) — the reused plan supplies their answers. The remaining stages run normally: [env-file](./env-file.md), [fresh-install](./fresh-install.md), [start-services](./start-services.md) (only for entries not already listening), [smoke-test](./smoke-test.md), [readiness-report](./readiness-report.md).
+
+## Rediscover path
+
+Continue at [rebase-check](./rebase-check.md). The full normal flow runs.

package/dist/release-manifest.json

@@ -1,7 +1,7 @@
 {
-  "release": "4.13.1",
-  "buildId": "run-44-1",
-  "commitSha": "2a73f80aae062cd7e19babb81f87727ccbd9aff7",
-  "buildTime": "2026-05-28T07:33:33Z",
+  "release": "4.14.0",
+  "buildId": "run-45-1",
+  "commitSha": "47f4274095fc578a67e19811afc335a1b8e0c0b4",
+  "buildTime": "2026-05-29T22:27:05Z",
   "serviceName": "muggle-ai-works-mcp"
 }