@muggleai/works 4.10.1 → 4.11.1

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

@@ -8,108 +8,65 @@ disable-model-invocation: true
 
 > Telemetry first step: see [`_shared/telemetry-emit.md`](../_shared/telemetry-emit.md). Use `skillName: "muggle-do"`.
 
-Muggle Test Do runs a battle-tested autonomous dev cycle: **pre-flight → requirements → impact analysis → validate code → unit tests → E2E acceptance → open PR**.
+Runs an autonomous dev cycle from requirements to PR. **Fire and review:** the user answers one pre-flight questionnaire, then walks away.
 
-The design goal is **fire and review**: the user answers one consolidated pre-flight questionnaire, then walks away. Every subsequent stage runs unattended until completion or a genuine blocker.
-
-For maintenance tasks, use the dedicated skills:
+For maintenance, use the dedicated skills:
 
 - `/muggle:muggle-status`
 - `/muggle:muggle-repair`
 - `/muggle:muggle-upgrade`
 
-## Preferences
-
-Gates run per [`preference-gates/README.md`](../muggle-preferences/preference-gates/README.md).
-
-| Preference | Stage | Decision it gates |
-|------------|-------|-------------------|
-| `autoUseWorktree` | 1 (pre-flight) | Create a worktree (see [`_shared/use-worktrees.md`](../_shared/use-worktrees.md)) |
-| `autoE2ETest` | 6 (e2e-acceptance) | Run E2E every cycle (default `always`), or fold the question into pre-flight |
-| `autoRebase` | 6 (e2e-acceptance) | Rebase onto `origin/<default>` (see [`_shared/rebase-before-e2e.md`](../_shared/rebase-before-e2e.md)) |
-| `autoCreatePR` | 7 (open-prs) | Push the branch and open the PR (see [`do/open-prs.md`](../do/open-prs.md)) |
-| `autoCleanup` | 7 (post-merge) | Run cleanup sequence (see [`_shared/post-merge-cleanup.md`](../_shared/post-merge-cleanup.md)) |
-
-## Input routing
-
-Treat `$ARGUMENTS` as the user command:
-
-- Empty / `help` / `menu` / `?` → show menu and session selector.
-- Anything else → infer intent:
-  - **Task automation** (user wants to perform an action on a website — post something, fill a form, click through a flow) → invoke `muggle:muggle-do-task` skill with the full prompt as arguments.
-  - **Feature development** (user wants to build, implement, fix, or refactor code) → treat as a new task description and start/resume a dev-cycle session.
-
-  When in doubt, ask one question: "Do you want me to run this as a browser automation task, or implement it as a code change?"
-
-## The seven stages
+## The pipeline
 
 | # | Stage | File | User-facing? |
 | :- | :---- | :--- | :----------- |
-| 1 | Pre-flight | [../do/pre-flight.md](../do/pre-flight.md) | **Yes — single consolidated turn** |
+| 1 | Pre-flight | [../do/pre-flight.md](../do/pre-flight.md) | **Yes — one consolidated turn** |
 | 2 | Requirements | [../do/requirements.md](../do/requirements.md) | No |
-| 3 | Impact analysis | [../do/impact-analysis.md](../do/impact-analysis.md) | No |
-| 4 | Validate code | [../do/validate-code.md](../do/validate-code.md) | No |
+| 3 | Build | [../do/build.md](../do/build.md) | No |
+| 4 | Impact analysis | [../do/impact-analysis.md](../do/impact-analysis.md) | No |
 | 5 | Unit tests | [../do/unit-tests.md](../do/unit-tests.md) | No |
 | 6 | E2E acceptance | [../do/e2e-acceptance.md](../do/e2e-acceptance.md) | No |
 | 7 | Open PR | [../do/open-prs.md](../do/open-prs.md) | No |
+| 8 | PR follow-up | [../muggle-pr-followup/SKILL.md](../muggle-pr-followup/SKILL.md) (generic) — invoked with muggle-do's cycle declaration | **Yes — only on ambiguous reviews** |
 
-**Stage 1 (pre-flight) is the ONLY stage that talks to the user.** Stages 2–7 run silently to completion. If a later stage hits a genuine blocker that the pre-flight didn't cover, escalate with a single terminal message — do not open a second round of questions.
-
-## Front-loading (stage 1 non-negotiable)
+Stage 1 talks to the user once. Stages 2–7 run silently. Stage 7 dispatches **one Stage-8 follow-up loop per PR** it opens (not one per session); each loop polls its own PR independently for new submitted reviews. When a review lands, the loop cycles back through Stage 3 (Build) → 4 → 5 → 6 → fresh visual walkthrough → push to the existing branch, then resumes polling for the next round. Each loop may escalate once on an ambiguous review.
 
-All ambiguity — task scope, repo selection, validation strategy, localhost URL, backend health, Muggle Test project, test-user credentials, branch name, PR target — is resolved in a **single** pre-flight turn. See `pre-flight.md` for the exact questionnaire.
+**Each stage's file is the single source of truth for that stage** — definition, contract, inputs/outputs, preference gates, output format. Read each stage file directly for its rules. This file is only the orchestration spine.
 
-**Red-flag behaviors (do not do):**
-
-- Asking a clarifying question mid-cycle because "I didn't think of that at pre-flight."
-- Starting a dev server mid-cycle and discovering the port is wrong.
-- Reaching the E2E stage before knowing how the user wants it validated.
-- Asking the user to "pick one" across multiple turns instead of one turn.
-
-If any of these happen, the pre-flight was incomplete — treat it as a skill bug, not a user bug, and expand `pre-flight.md` to cover the missed case after the run.
-
-## Session model
+## Preferences
 
-Every run writes to `.muggle-do/sessions/<slug>/`:
+| Preference | Stage | Decision it gates |
+|------------|-------|-------------------|
+| `autoE2ETest` | 6 (E2E acceptance) | Run E2E every cycle (default `always`), or fold the question into pre-flight |
 
-- `state.md` — one-screen live status: current stage (N/7), last update timestamp, pre-flight answers verbatim, any blockers.
-- `iterations/<NNN>.md` — append-only log of stage transitions for iteration NNN: what ran, what was decided, what artifacts were produced.
-- `requirements.md` — frozen output of stage 2.
-- `result.md` — final summary written by stage 7 (PR URLs, E2E outcome, open issues).
+Other gates that fire during this cycle (`autoUseWorktree`, `autoRebase`, `autoCreatePR`, `autoCleanup`) are owned by the per-stage files; see each stage for its contract.
 
-**On every stage transition, you MUST:**
+## Input routing
 
-1. Append a dated entry to the active `iterations/<NNN>.md`: `### Stage N/7 — <name> (<timestamp>)` followed by the stage's output.
-2. Rewrite `state.md` to reflect the new current stage and any relevant counters.
+Treat `$ARGUMENTS` as the user command:
 
-If these files don't exist, create them — missing session files means the user lost visibility into the cycle, which is the exact failure mode this skill exists to prevent.
+- Empty / `help` / `menu` / `?` → show menu and session selector.
+- Anything else → infer intent:
+  - **Task automation** (perform an action on a website — post something, fill a form, click through a flow) → invoke `muggle:muggle-do-task` with the full prompt.
+  - **Feature development** (build / fix / refactor code) → start or resume a dev-cycle session.
 
-## Turn preamble
+When in doubt, ask one question: "Browser automation task, or code change?"
 
-Each stage turn MUST begin with one line in this form before any other output:
+## Session model
 
-```
-**Stage N/7 — <stage name>** — <one-line intent>
-```
+Every run writes to `.muggle-do/sessions/<slug>/`. Stages own the files they produce:
 
-This is how the user can tell, at a glance, what phase the cycle is in without parsing a long response.
+| File | Owned by | Purpose |
+| :--- | :------- | :------ |
+| `state.md` | Stage 1 (rewritten by every transition) | Current stage, pre-flight answers, blockers |
+| `iterations/<NNN>.md` | Every stage | Append-only stage transition log |
+| `requirements.md` | Stage 2 | Frozen requirements |
+| `prs.json`, `last_seen.json`, `followup.log` | Stage 8 | See [`pr-followup.md`](../do/pr-followup.md) |
+| `result.md` | Stage 7 (seeded), Stage 8 (finalized) | Per-PR final state |
 
 ## Guardrails
 
-- **No mid-cycle user questions.** Anything not covered by pre-flight is a skill bug; escalate once, do not loop.
-- **Do not skip unit tests before E2E acceptance tests.**
-- **Do not skip E2E acceptance tests due to missing scripts** — generate when needed.
-- **Do not hand-write the E2E block of the PR body.** The `open-prs.md` stage MUST invoke `muggle-pr-visual-walkthrough` Mode B to render the screenshots-and-steps section. Hand-writing it loses the dashboard links the user relies on for review.
-- **If the same stage fails 3 times in a row, escalate with details.**
-- **If total iterations reach 3 and E2E acceptance tests still fail**, continue to PR creation with `[E2E FAILING]` in the title; the visual walkthrough section makes the failures reviewable.
-
-## Completion contract
-
-When stage 7 finishes, the final message to the user contains at minimum:
-
-- PR URL(s)
-- E2E status (passing / `[E2E FAILING]`)
-- Link to the run dashboard for each test case (via the walkthrough skill output)
-- Path to `result.md` for full details
-
-No other content. The user already read the walkthrough in the PR body — do not re-summarize it here.
+- **Stage 1 is the only forward-pipeline user-facing stage.** Stages 2–7 don't ask questions mid-cycle. If a stage hits a blocker pre-flight didn't cover, treat as a pre-flight bug — escalate once and expand `pre-flight.md` after the run.
+- **Stage 8 may escalate** once per ambiguous review comment, and may dispatch back to Stage 3 when needed — see [`pr-followup.md`](../do/pr-followup.md).
+- **If the same stage fails 3 times in a row, escalate** with details.
+- **If 3 cycle iterations reach E2E with failures**, ship with `[E2E FAILING]` per [`open-prs.md`](../do/open-prs.md). The walkthrough section keeps the failures reviewable.

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

@@ -32,7 +32,8 @@ If intent is ambiguous, use `AskUserQuestion` once with options **Submit / List
 
 ## Non-negotiables (all ops)
 
-- Use `AskUserQuestion` for every selection (project, test case, run, target type, confirm). Never ask the user to "reply with a number" in plain text.
+- Use `AskUserQuestion` for every selection (project, test case, run, target type, which step(s), confirm). Step selection must be a clickable picker built from the rendered steps (see [`ops/submit.md`](ops/submit.md) §3b) — never ask the user to type a number.
+- Always render the run's steps and summary (§2) **before** collecting feedback — users can only point at what they can see.
 - Convert step numbers between 1-based (rendered to user) and 0-based (wire format) at the boundary. Never expose 0-based indices to the user.
 - One MCP submit/delete call per feedback piece — never batch into a single call.
 - Surface the `feedbackAnalysisWorkflowRuntimeId` returned by submit so the user knows regeneration is running. Do not poll it from this skill.

package/dist/plugin/skills/muggle-feedback/ops/submit.md

@@ -55,6 +55,8 @@ Print:
 
 ## 3. Collect feedback (batch)
 
+### 3a. Pick the scope (entity type)
+
 Use `AskUserQuestion` to scope which targets:
 
 > "Where is the problem?"
@@ -63,10 +65,21 @@ Use `AskUserQuestion` to scope which targets:
 > - The whole script's outcome / summary
 > - Multiple steps **and** the whole outcome
 
-For each chosen target, prompt for the feedback paragraph in plain text. Keep prompts specific:
+### 3b. Pick the step(s) — clickable picker
+
+When 3a includes any step-level scope, present the rendered steps as a **clickable `AskUserQuestion` picker** — never as a typed number.
+
+- **Option format** — Label: `Step <n>: <action label> on <element text or id>` (≤80 chars). Description: the step's `briefExplanation` (≤120 chars).
+- **Multi-select** — `multiSelect: true` for "Multiple steps" or "Multiple steps and the whole outcome"; `multiSelect: false` for "One specific step".
+- **Long scripts (>10 steps)** — rank by keyword overlap with the user's prompt (label or briefExplanation); fall back to the first 10 if no match. Append **"Show all steps"** as a final option that re-asks with the full list — never silently truncate.
+
+For each selected step, prompt in plain text:
+
+> "What should step `<n>` have done instead?"
+
+For the whole-script scope, prompt:
 
-- For a step: "What should step `<n>` have done instead?"
-- For the whole script: "What's wrong with the overall outcome?"
+> "What's wrong with the overall outcome?"
 
 Validate each paragraph is non-empty (re-prompt if blank). Build an in-memory list of feedback pieces:
 

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

@@ -0,0 +1,59 @@
+---
+name: muggle-pr-followup
+description: Generic per-PR follow-up loop. One polling tick per dispatch. Watches one PR for new submitted reviews; when an actionable review lands, invokes the caller's implementation cycle (build/test/walkthrough/push handler the caller declares), then resumes polling. Use as `/loop 1m /muggle:muggle-pr-followup <session-slug> <pr-number>`. Caller-agnostic — `muggle-do` is the first caller but not the last.
+disable-model-invocation: true
+---
+
+# Muggle PR Follow-up
+
+> Telemetry first step: see [`_shared/telemetry-emit.md`](../_shared/telemetry-emit.md). Use `skillName: "muggle-pr-followup"`.
+
+A generic loop that babysits one open PR until it's merged or closed. Polls for submitted reviews; on an actionable review, dispatches the caller's implementation cycle to re-build, re-test, refresh the walkthrough, and push.
+
+**Per-PR isolation.** One dispatch per PR, not per session. Multi-PR work runs N independent loops.
+
+## Input
+
+`$ARGUMENTS = <session-slug> <pr-number>`. The session-slug is the directory basename under `.muggle-<caller>/sessions/` (e.g. `.muggle-do/sessions/`) that this loop reads its state from. The pr-number identifies which PR in that session's manifest this loop watches.
+
+- Empty / `help` / `?` → list active `(slug, pr-number)` pairs across known callers, exit.
+- One argument → ambiguous; list PRs under that slug, exit.
+- Two arguments → resolve and run one tick.
+
+## Contract
+
+The per-tick contract — termination check, allow-list resolution, review polling, classify, cycle dispatch, escalation, telemetry — lives in [`contract.md`](contract.md). Read it before driving a tick.
+
+## Caller-supplied implementation cycle
+
+The skill itself is caller-agnostic. When an actionable review lands, it invokes the **implementation cycle** declared by the caller in the session's `cycle.json`:
+
+```json
+{
+  "cycleName": "muggle-do dev cycle",
+  "steps": [
+    { "stage": 3, "file": "../do/build.md" },
+    { "stage": 4, "file": "../do/impact-analysis.md" },
+    { "stage": 5, "file": "../do/unit-tests.md" },
+    { "stage": 6, "file": "../do/e2e-acceptance.md" },
+    { "name": "post-walkthrough", "skill": "muggle-pr-visual-walkthrough", "mode": "A" }
+  ],
+  "pushHandler": "git push origin <branch>"
+}
+```
+
+The cycle's job: read the amended `requirements.md`, run each declared step, push to the existing branch. The cycle returns one of `pushed | escalated | failed`. The skill doesn't care what's inside the steps — it just iterates them, captures the outcome, and writes a reply summary referencing the new SHA.
+
+Callers without a `cycle.json` are rejected with `no cycle declared — caller must seed cycle.json at dispatch time`.
+
+## Subagent dispatch (optional)
+
+A caller may declare `"useSubagent": true` in `cycle.json`. When set, the implementation cycle runs as a separate Claude subagent rather than inline in the loop's tick — gives stronger isolation per PR but adds overhead per cycle. Default is inline (which is itself isolated per-tick via `/loop`).
+
+## Design adjustment escalation
+
+When the implementation cycle reports back that the review requires not just code change but a **design adjustment** beyond what the current requirements support (e.g. the build stage discovers the requested change conflicts with a load-bearing assumption), the cycle returns `failed: design-adjustment`. The loop treats this like an ambiguous escalation but with a different terminal message that points at the design conflict and asks the user to decide.
+
+## Why a separate skill (and not e.g. inside the caller's own skill folder)
+
+`/loop` dispatches via slash command; slash commands resolve to top-level skills under `plugin/skills/`. A per-tick loop driven by `/loop` therefore has to live as a top-level skill. Putting the loop's content directly inside a caller-specific folder would make `/loop`-dispatch impossible (or fragile via shell-only entry points). Keeping the loop generic and caller-agnostic is what lets `/loop` dispatch into it cleanly.

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

@@ -0,0 +1,190 @@
+# PR follow-up per-tick contract
+
+Caller-agnostic per-tick contract for the [muggle-pr-followup](SKILL.md) skill. One tick = one polling iteration scoped to one PR.
+
+## Turn preamble
+
+```
+**PR follow-up** — polling <repo>#<pr-number>, tick #<K>.
+```
+
+Resolve `<K>` from `idle_tick_count + cycles_completed` in this PR's state slot.
+
+## When this contract may break the caller's "no questions" rule
+
+Most callers' forward pipelines never ask the user mid-cycle. This loop, however, may emit a single escalation message when a submitted review is ambiguous (see [classify](#step-6-classify-the-review) below). By the time the loop is polling, the user has walked away from the forward pipeline; forcing a guess on an ambiguous review is worse than pausing.
+
+Escalation is the **only** user-facing path. Otherwise the cycle runs silently end to end.
+
+## Inputs
+
+Read these from `.muggle-<caller>/sessions/<slug>/` (the caller's session dir):
+
+- `state.md` — session metadata (for context when classifying reviews).
+- `prs.json` — list of `{repo, number, url, head_sha, state, escalated?, cycling?}`. This loop touches only the entry whose `number` matches the dispatched PR number.
+- `last_seen.json` — keyed by `"<owner>/<repo>#<n>"`. For this PR: `{reviewId, last_pushed_sha, idle_tick_count, cycles_completed, escalated_review_ids[]}`.
+- `cycle.json` — caller's declared implementation cycle (see [SKILL.md](SKILL.md#caller-supplied-implementation-cycle)).
+
+If any of these don't exist or the PR isn't in `prs.json`, the tick is a no-op — log an error to `followup.log` and exit.
+
+## Per-tick contract
+
+### Step 1: Refresh this PR's state
+
+```bash
+gh pr view <number> --repo <repo> --json state,mergedAt,closedAt,headRefOid
+```
+
+If `state` is `MERGED` or `CLOSED`, mark this entry terminal in `prs.json`. Update `head_sha` if it changed.
+
+### Step 2: Termination check
+
+If this PR is terminal: write a per-PR section into `result.md` (URL, final state, `cycles_completed`, count escalated, final SHA), emit final telemetry, **do not schedule another tick**. Other PRs in the session have their own loops; they terminate independently.
+
+### Step 3: Resolve the reviewer allow-list (every tick)
+
+```bash
+gh pr view <number> --repo <repo> --json reviewRequests,author
+```
+
+Add requested reviewers. Add CODEOWNERS by parsing `.github/CODEOWNERS` (or `CODEOWNERS` / `docs/CODEOWNERS`) from the PR's head branch. Remove the PR author and any bot accounts (logins ending in `[bot]`, plus the standard list: `dependabot`, `github-actions`, `renovate`, `mergify`).
+
+### Step 4: Pull new submitted reviews
+
+```bash
+gh api repos/<owner>/<repo>/pulls/<number>/reviews --paginate
+```
+
+Filter to reviews where:
+
+- `submitted_at` is non-null (skip drafts — `PENDING` reviews are still being composed).
+- `id > last_seen.reviewId`.
+- `user.login` is in the allow-list.
+- `id` is not in `escalated_review_ids`.
+- `state` is `CHANGES_REQUESTED` or `COMMENTED`, OR `APPROVED` with at least one line comment or a non-empty body.
+
+### Step 5: Pick the oldest new review
+
+If no new review past the cursor: increment `idle_tick_count`, append a heartbeat line to `followup.log`, exit. Next tick fires in 1 min via `/loop`.
+
+If one or more: take the oldest by `submitted_at`. Fetch its associated line comments (`gh api repos/<owner>/<repo>/pulls/<n>/comments` filtered by `pull_request_review_id`). Reset `idle_tick_count` to 0.
+
+**At most one review per tick.** If two reviews land between ticks, the second waits.
+
+### Step 6: Classify the review
+
+Apply the classify rule in [`../_shared/pr-followup-helpers.md`](../_shared/pr-followup-helpers.md). The rule applies to the **review as a unit**. Two outcomes:
+
+- **Actionable** → continue to Step 7.
+- **Ambiguous** → continue to Step 8.
+
+### Step 7: Dispatch the implementation cycle
+
+When the review is actionable:
+
+1. **Pause polling** for this PR (set `cycling: true` on this PR's entry in `prs.json`).
+2. **Amend `requirements.md`** in the session dir with a new `## Amendment — review <review_id> by <login> (<timestamp>)` section pasting the review body and each comment (with `<file>:<line>` context).
+3. **Invoke the implementation cycle** declared in the caller's `cycle.json`. Iterate the `steps[]` in order. Each step is either a markdown file to follow, a skill to invoke, or a shell command (per the `cycle.json` schema in SKILL.md). When a step fails, the cycle returns `failed: <step-name>`; the loop escalates per Step 8 with the failure as the reason.
+4. **Push** via `cycle.json`'s `pushHandler`. Set `last_seen.last_pushed_sha` to the new HEAD.
+5. **Reply** per [helpers § Reply routing](../_shared/pr-followup-helpers.md#reply-routing) and [§ Classify](../_shared/pr-followup-helpers.md#classify) (reply shape). For each line comment in the review, derive `<attribution>` from `git diff <last_pushed_sha>..HEAD -- <comment.path>` near `comment.line` ±5 (fall back to `addressed indirectly — see walkthrough` if empty). `<status>` = `ran clean` or `had <N> failures, see walkthrough`. If the review is body-only (no line comments), post the top-level fallback shape; if both body and line comments, threaded replies cover it — no top-level.
+6. **Resume polling**: clear `cycling: true`, increment `cycles_completed`, advance `last_seen.reviewId` past this review.
+7. Emit per-cycle telemetry.
+
+If the cycle returns `failed: design-adjustment` (the cycle discovered the review can't be implemented without rethinking the design itself, not just the code), escalate per Step 8 with a `design-adjustment` reason — the terminal message asks the user to confirm the design intent before retrying.
+
+### Step 8: Escalate
+
+When the review is ambiguous, or the cycle failed:
+
+1. Add the review id to `last_seen.escalated_review_ids`.
+2. Append a `followup.log` entry describing the review and the reason.
+3. Pause this PR's loop by writing `escalated: true` against this PR's entry in `prs.json`.
+4. End the turn with a **single terminal message** to the user:
+
+```
+**PR follow-up escalation — <repo>#<number> — review <review_id>**
+
+<reviewer-login> submitted a review I can't act on coherently:
+
+> <quoted review body, or "(no body)" if empty>
+
+Comments:
+- <file>:<line> — <quoted comment body>
+
+[For ambiguous]
+Best two interpretations:
+1. <one-line interpretation A>
+2. <one-line interpretation B>
+
+[For cycle failure]
+The implementation cycle failed at <step-name>: <reason>.
+
+Reply on the review yourself, leave a follow-up comment, or tell me which way to go.
+```
+
+The user clears the escalation by replying on GitHub (next tick sees a new submitted review past the cursor) or by giving a directive in this terminal session.
+
+### Step 9: Emit tick-summary telemetry and exit
+
+Emit one tick event per `muggle-local-telemetry-skill-emit`. Exit the turn.
+
+## Reply routing
+
+- **Threaded reply per line comment** (default): `POST /repos/{owner}/{repo}/pulls/{n}/comments/{comment_id}/replies`. Use for every line comment in the review so each thread can be resolved in GitHub's UI.
+- **Top-level summary on a body-only review** (fallback): `gh pr comment <number> --body "..."` referencing the review id and the new SHA. Used only when the review has body content and zero line comments — GitHub has no "reply to a review body" endpoint.
+- **Never post the same reply twice** — `last_seen.reviewId` is the only re-entry guard.
+- **Never post a top-level summary alongside threaded replies** — duplication pollutes the Conversation tab.
+
+## Telemetry
+
+**Per-cycle** (one event per actionable review handled):
+
+```json
+{
+  "skill": "muggle-pr-followup",
+  "event": "cycle",
+  "caller": "<caller>",
+  "session_slug": "<slug>",
+  "repo": "<repo>",
+  "pr_number": <n>,
+  "review_id": <id>,
+  "outcome": "pushed|escalated|failed:<step>",
+  "comment_count": <count>,
+  "head_sha_before": "<sha>",
+  "head_sha_after": "<sha-or-null>"
+}
+```
+
+**Per-tick summary** (always one, even idle):
+
+```json
+{
+  "skill": "muggle-pr-followup",
+  "event": "tick",
+  "session_slug": "<slug>",
+  "repo": "<repo>",
+  "pr_number": <n>,
+  "reviews_seen": <count>,
+  "review_picked": true|false,
+  "cycle_dispatched": true|false,
+  "tick_duration_ms": <ms>
+}
+```
+
+## Output
+
+This stage produces no console output beyond:
+- The turn preamble (always).
+- An escalation terminal message (only when escalating).
+- The final `result.md` summary section for this PR (only on the terminating tick — written to disk, not printed).
+
+## Self-check before ending the turn
+
+- [ ] `last_seen.json` advanced for any review handled.
+- [ ] `prs.json` reflects current state (terminal marked; `escalated`/`cycling` flags consistent).
+- [ ] `followup.log` has at minimum a heartbeat or per-review line for this tick.
+- [ ] Telemetry events emitted (per-cycle when applicable + per-tick).
+- [ ] If pushed, `last_pushed_sha` is set and `cycles_completed` incremented.
+- [ ] If actionable, one threaded reply posted per line comment (or one top-level reply for body-only reviews) — never both, never zero.
+- [ ] If escalated, `escalated_review_ids` contains the review id.
+- [ ] If terminal, the loop is NOT continued.

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

@@ -215,6 +215,19 @@ If the user picks `muggle-feedback` from any bucket's options, invoke the `muggl
 
 Skip silently when the run passed cleanly — failure-mode events are by definition about failures.
 
+### 9b. Remind the user to guide the agent (every Electron invocation)
+
+Fires after **every** Electron run, pass or fail. A run can technically pass while still containing steps the user would correct — a misclick, wrong element, or a summary that doesn't match intent. This is the user's chance to flag it before regeneration picks up elsewhere.
+
+**Skip if 9a already routed the user into `muggle-feedback` for this run.** Otherwise ask via `AskUserQuestion`:
+
+> "Did the agent miss or do anything wrong on this run? Your feedback regenerates the affected scripts."
+
+- **Yes — give feedback** → invoke `muggle-feedback` via the `Skill` tool, passing the just-finished `runId` so the submit flow opens on this run's steps and summary.
+- **No — looks good** → continue to Step 10.
+
+Non-blocking — one click to dismiss. Do not re-ask for the same `runId` within a session.
+
 ### 10. Offer to post a visual walkthrough to the PR
 
 After reporting results:
@@ -231,6 +244,7 @@ After reporting results:
 - **Never prompt for Electron launch approval** before execution — invoking this skill is the approval. Just run.
 - If replayable scripts exist, do not default to generation without user choice.
 - No hiding failures: surface errors and artifact paths.
+- **Always offer the agent-guidance reminder after every Electron run** (Step 9b) — pass or fail — unless 9a already routed the user into `muggle-feedback`. Never silently end a run without giving the user a one-click path to flag what was wrong.
 - Replay: never hand-built or simplified `actionScript` — only from `muggle-remote-action-script-get`.
 - Use `AskUserQuestion` for every selection — project, use case, test case, script. Never ask the user to type a number.
 - Project, use case, and test case selection lists must always include "Create new ...". Include "Show full list" whenever the API returned at least one row for that step; omit "Show full list" when the list is empty (offer "Create new ..." only). For creates, use preview tools (`muggle-remote-use-case-prompt-preview`, `muggle-remote-test-case-generate-from-prompt`) before persisting.

package/dist/release-manifest.json

@@ -1,7 +1,7 @@
 {
-  "release": "4.10.1",
-  "buildId": "run-32-1",
-  "commitSha": "8be7ac283bd1924e1d2e2df90f214a40d85a3038",
-  "buildTime": "2026-05-13T18:34:37Z",
+  "release": "4.11.1",
+  "buildId": "run-34-1",
+  "commitSha": "09bc0bf650bd1c56171238fb0065ec3e584bb9fd",
+  "buildTime": "2026-05-19T19:57:13Z",
   "serviceName": "muggle-ai-works-mcp"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@muggleai/works",
     "mcpName": "io.github.multiplex-ai/muggle",
-    "version": "4.10.1",
+    "version": "4.11.1",
     "description": "Ship quality products with AI-powered E2E acceptance testing that validates your web app like a real user — from Claude Code and Cursor to PR.",
     "type": "module",
     "main": "dist/index.js",
@@ -41,14 +41,14 @@
         "test:watch": "vitest"
     },
     "muggleConfig": {
-        "electronAppVersion": "1.0.82",
+        "electronAppVersion": "1.0.87",
         "downloadBaseUrl": "https://github.com/multiplex-ai/muggle-ai-works/releases/download",
         "runtimeTargetDefault": "production",
         "checksums": {
-            "darwin-arm64": "ceab8a6ea1982cff9385896d392519ef2b5545d3f99e1409eec247e888334b02",
-            "darwin-x64": "423b23d98a2858c7e4d203133aab586bbc5014b7cd50a4aa7125803ccaf7deed",
-            "win32-x64": "c231ae9ae512ab97d3ee7980309a807c31b9d8033daab47c50bc1d6f4c112e4f",
-            "linux-x64": "0dd15add46ca7bed5ad8e4d4cb751c63506b9dbb2eec294d9039426baeba8c32"
+            "darwin-arm64": "df04c98269e22ae427bb863956215b3f20cbf2ff0b51c037647d6e734a7b7502",
+            "darwin-x64": "e9f5b8a61f4a9f47743aaabb27d6e4c462dca5aa922ba66ae04f0a0133b8a7eb",
+            "win32-x64": "75e552672757d280259637bdcbe0aae0eecc2417ed9a6e5bd49f42d3466f66cf",
+            "linux-x64": "2c8b64cf549f9a6682db959b17c5f04578d632d5bcdba1ac9efbb45d6a097802"
         }
     },
     "dependencies": {

package/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.10.1",
+  "version": "4.11.1",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"

package/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.10.1",
+  "version": "4.11.1",
   "author": {
     "name": "Muggle AI",
     "email": "support@muggle-ai.com"