@muggleai/works 4.9.2 → 4.10.1

package/plugin/skills/do/pr-followup.md

@@ -0,0 +1,225 @@
+# PR follow-up agent (Stage 8/8)
+
+You are babysitting one or more open pull requests opened by stage 7. Each invocation of this stage is **one polling tick** dispatched by `/loop 5m /muggle:muggle-do-pr-followup <slug>`. The tick is short, idempotent, and addresses **at most one item per PR**.
+
+The loop ends when every PR in the session is merged or closed.
+
+## Turn preamble
+
+Start the turn with:
+
+```
+**Stage 8/8 — PR follow-up** — polling <N> PR(s), tick #<K>.
+```
+
+Resolve `<N>` from `prs.json` (non-terminal entries only) and `<K>` from the tick counter in `state.md`.
+
+## Stage-8 exception to the no-mid-cycle-questions rule
+
+Stages 2–7 never ask the user mid-cycle. **Stage 8 may escalate** when a reviewer comment is ambiguous (see [Decision rule: classify](#decision-rule-classify) below). This is deliberate — the user has already walked away by the time stage 8 starts, and forcing a guess on an ambiguous design comment is worse than pausing.
+
+Escalation is the **only** user-facing path in stage 8. Anything else — directives, questions, CI failures, retries — runs silently.
+
+## Inputs
+
+Read these from `.muggle-do/sessions/<slug>/`:
+
+- `state.md` — current tick counter, session metadata, the pre-flight answers (for context when classifying comments).
+- `prs.json` — list of `{repo, number, url, head_sha, state}`. Entries with `state: "merged"` or `state: "closed"` are skipped.
+- `last_seen.json` — per-PR cursor: `{commentId, reviewId, checkRunCompletedAt, last_pushed_sha, idle_tick_count, escalated_comment_ids[]}`.
+
+If any of these don't exist, the tick is a no-op — log an error to `followup.log` and exit.
+
+## Per-tick contract
+
+Do these steps in order. **Do not batch — at most one actionable item per PR.**
+
+### Step 1: Refresh PR states
+
+For each PR in `prs.json` not already terminal:
+
+```bash
+gh pr view <number> --repo <repo> --json state,mergedAt,closedAt,headRefOid
+```
+
+If `state` is `MERGED` or `CLOSED`, mark the entry terminal in `prs.json`. Update `head_sha` if it changed.
+
+### Step 2: Termination check
+
+If every entry in `prs.json` is now terminal:
+
+1. Write `result.md` with one section per PR (URL, final state, count of items addressed, count escalated, final commit SHA).
+2. **Do not schedule the next tick.** End the turn with no `ScheduleWakeup`-equivalent — `/loop` ends naturally.
+3. Emit the final tick-summary telemetry event (see [Telemetry](#telemetry)) with `prs_terminal == pr_count`.
+
+### Step 3: Resolve the reviewer allow-list (every tick)
+
+For each non-terminal PR, compute the set of GitHub logins allowed to drive changes:
+
+```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`).
+
+This is per-tick by design (decision 9): reviewers added or removed after the PR opened take effect on the next poll.
+
+### Step 4: Pull new actionable items
+
+For each non-terminal PR, fetch items newer than the cursor in `last_seen.json`:
+
+- **Line-level review comments**:
+  ```bash
+  gh api repos/<owner>/<repo>/pulls/<number>/comments --paginate
+  ```
+  Filter to comments with `id > last_seen.commentId` AND `user.login` in the allow-list AND not already in `escalated_comment_ids` (avoid re-escalating).
+
+- **CHANGES_REQUESTED review bodies** (only when the review has a non-empty body and no associated line comments):
+  ```bash
+  gh api repos/<owner>/<repo>/pulls/<number>/reviews --paginate
+  ```
+  Filter to reviews with `id > last_seen.reviewId` AND `state == "CHANGES_REQUESTED"` AND `user.login` in the allow-list AND `body` is non-empty.
+
+- **Failing CI checks** (apply the `head_sha` guard, decision 11):
+  ```bash
+  gh pr checks <number> --repo <repo> --json name,state,completedAt,detailsUrl,workflow
+  ```
+  Filter to checks where `state == "FAILURE"` AND `completedAt > last_seen.checkRunCompletedAt`. **Skip any check whose target SHA equals `last_pushed_sha`** — CI is still digesting our last push, addressing it again would double-handle.
+
+### Step 5: Pick one item per PR
+
+If a PR has zero actionable items, increment `idle_tick_count` for that PR. Otherwise sort the PR's items by timestamp ascending and take the **oldest one**. Reset `idle_tick_count` to 0 for that PR.
+
+If every PR has zero actionable items this tick:
+- Append a one-line heartbeat to `followup.log`: `<ts> tick #<K> idle (PRs: #A, #B, ...)`.
+- If `idle_tick_count >= 12` for any PR, also rewrite `state.md` with `idle since <ts>, last poll <ts>` for that PR (decision 12).
+- Emit tick-summary telemetry, exit the turn (next tick fires in 5 min via `/loop`).
+
+### Step 6: Classify and route
+
+For each picked item, classify it:
+
+#### Decision rule: classify
+
+| Class | Signals | Action |
+| :---- | :------ | :----- |
+| **directive** | Imperative verb on a concrete target: "rename X to Y", "extract this", "add a null check", "remove this branch", "use `const` here", "this should be `async`", "delete this comment". Includes review-body summaries that read as a list of changes. | Fix → commit → push → reply `Done in <sha> — <one-line>`. |
+| **question** | Ends with `?` and is not a rhetorical disguise. "Why this approach?", "Is this called from X?", "Does this need to handle Z?". | Reply inline with the answer. No code change. No push. |
+| **CI failure** | Source is a failing check, not a comment. | Read the failing job log, fix, commit, push. No reply. |
+| **ambiguous** (default) | Proposes an alternative without instructing ("I think we should use Z instead", "Have you considered Y?"), conflicts with a deliberate choice in the PR description or design doc, or is a multi-part comment mixing question and change request. | **Escalate.** See [Step 7: Escalate](#step-7-escalate). |
+
+When the comment matches neither **directive** nor **question** cleanly, default to **ambiguous**. Do not guess. The cost of escalating a directive that could have been auto-handled is small; the cost of pushing a wrong change because we guessed is large.
+
+#### Decision rule: reply text (adaptive, decision 6)
+
+- **directive**: short, one-line. `Done in <sha> — renamed \`fooBar\` to \`foo_bar\` per request.` Use the [reply-routing helper](#reply-routing) to hit the correct endpoint.
+- **question**: answer inline. Pull surrounding-code context if needed. Reply length matches the question's complexity — don't write three paragraphs to answer a yes/no.
+- **CI failure**: no comment to reply to. The fix commit is the response. The commit message should reference the failing check by name (e.g. `fix(ci): typecheck — narrow type of foo`).
+- **ambiguous**: no reply written by the bot. The escalation goes to the user, who replies to the comment themselves.
+
+### Step 7: Escalate
+
+When the picked item is **ambiguous**:
+
+1. Add the comment id to `last_seen.escalated_comment_ids` so it isn't re-picked next tick.
+2. Append an entry to `followup.log` describing the comment and why it was classified ambiguous.
+3. Pause this PR's loop by writing `escalated: true` against the PR's entry in `prs.json`. Subsequent ticks skip this PR until the user clears the escalation.
+4. End the turn with a **single terminal message** to the user:
+
+```
+**Stage 8 escalation — <repo>#<number>**
+
+<reviewer-login> left an ambiguous comment on <file>:<line>:
+
+> <quoted comment body>
+
+Classifying it as a directive would mean: <one-line interpretation>
+Classifying it as a question would mean: <one-line alternative>
+
+Reply to that GitHub comment yourself, or tell me which way to go. I'll resume polling once the comment is either resolved or has a follow-up from you.
+```
+
+The user clears the escalation by either resolving the GitHub thread (the next tick sees it resolved and removes it from `escalated_comment_ids`) or by replying in this terminal session with a directive that the next tick will pick up.
+
+### Step 8: Update cursors and push
+
+After addressing a non-escalated item:
+
+- Advance `last_seen.commentId` / `last_seen.reviewId` / `last_seen.checkRunCompletedAt` past the addressed item.
+- If a push happened, set `last_seen.last_pushed_sha` to the new HEAD SHA. This arms the `head_sha` guard for the next tick (decision 11).
+- Emit per-item telemetry (see [Telemetry](#telemetry)).
+
+### Step 9: Emit tick-summary telemetry and exit
+
+Emit one `muggle-local-telemetry-skill-emit` event per tick (see [Telemetry](#telemetry)). Exit the turn. Next tick fires in 5 min via `/loop`.
+
+## Reply routing
+
+GitHub's PR comment APIs are not uniform. Route by parent type:
+
+- **Reply to a line-level review comment** (most common): `POST /repos/{owner}/{repo}/pulls/{n}/comments/{comment_id}/replies` with `{"body": "..."}`. The reply lands in the same review thread.
+- **Reply to a CHANGES_REQUESTED review body** (no inline comment to reply to): post a fresh top-level PR comment via `gh pr comment <number> --body "..."` referencing the review. There is no "reply to review body" endpoint.
+- **Failing CI**: no reply. The fix commit is the response.
+
+Never post the same reply twice — the cursor in `last_seen.json` is the only re-entry guard.
+
+## Telemetry
+
+Two telemetry shapes per tick (decision 14):
+
+**Per-item** (one event per addressed/escalated item):
+
+```json
+{
+  "skill": "muggle-do-pr-followup",
+  "event": "item",
+  "session_slug": "<slug>",
+  "repo": "<repo>",
+  "pr_number": <n>,
+  "item_type": "directive|question|ci_failure|ambiguous",
+  "outcome": "fixed_and_pushed|replied|escalated",
+  "comment_id": <id-or-null>,
+  "head_sha": "<sha-or-null>"
+}
+```
+
+**Per-tick summary** (always one, even on idle ticks):
+
+```json
+{
+  "skill": "muggle-do-pr-followup",
+  "event": "tick",
+  "session_slug": "<slug>",
+  "tick": <K>,
+  "pr_count": <total>,
+  "prs_terminal": <count>,
+  "items_seen": <count>,
+  "items_addressed": <count>,
+  "items_escalated": <count>,
+  "pushed": true|false,
+  "tick_duration_ms": <ms>
+}
+```
+
+## Output
+
+This stage produces no console output beyond:
+- The turn preamble (always).
+- An escalation terminal message (only when an item is classified ambiguous).
+- The final `result.md` summary (only on the terminating tick — written to disk, not printed).
+
+Everything else lives in `followup.log` and `last_seen.json`.
+
+## Self-check before ending the turn
+
+Before exiting, confirm:
+
+- [ ] `last_seen.json` was advanced for every item handled.
+- [ ] `prs.json` reflects current PR states (terminal entries marked).
+- [ ] `followup.log` has at minimum a heartbeat or per-item line for this tick.
+- [ ] Telemetry events were emitted (per-item + per-tick).
+- [ ] If pushed, `last_pushed_sha` is set.
+- [ ] If escalated, `escalated_comment_ids` contains the comment id.
+- [ ] If terminal, the loop is NOT continued (do not schedule another tick).
+
+If any are missing, fix before exit — a dropped cursor causes double-handling next tick.

package/plugin/skills/do/pre-flight.md

@@ -17,7 +17,7 @@ Start the turn with:
 You receive:
 
 - The user's task description (from `$ARGUMENTS`).
-- The list of configured repos (names + paths) from the Muggle config.
+- The list of configured repos (names + paths) from the Muggle Test config.
 - Any session directory that already exists (resumption case).
 
 ## Silent detection (do this first — no user prompts)
@@ -26,31 +26,38 @@ Before asking anything, gather every fact you can resolve without the user:
 
 1. **Candidate repo(s).** Match keywords in the task description against configured repo names. If one repo is an obvious match, propose it as the default; if two or three are plausible, list them.
 2. **Current branch and default branch** for each candidate repo. Run `git -C <repo> symbolic-ref refs/remotes/origin/HEAD --short` and `git -C <repo> branch --show-current`. If the current branch is the default, the pre-flight must collect a new branch name.
-3. **Running dev server.** Scan common dev ports — `lsof -iTCP -sTCP:LISTEN -nP | grep -E ':(3000|3001|3999|4200|5173|8080)'` — and hit `/` with `curl -s -o /dev/null -w "%{http_code}"` to confirm 2xx.
-4. **Running backend.** If the repo's `.env.local` (or equivalent) declares a backend URL (e.g. `REACT_APP_BACKEND_BASE_URL=http://localhost:5050`), probe the health endpoint; note up/down.
-5. **Muggle MCP auth.** Call `muggle-remote-auth-status`. If expired, you will ask to re-auth in the questionnaire.
-6. **Candidate Muggle projects.** Call `muggle-remote-project-list` and rank by semantic match against the task description and the repo's dev URL.
-7. **Existing test-user secrets.** For each candidate Muggle project, call `muggle-remote-secret-list` and note whether `managed_profile_email` / `managed_profile_password` exist.
+3. **Running dev server.** Detect listening ports and reconcile env-file URL/port using [`../_shared/dev-server-readiness.md`](../_shared/dev-server-readiness.md).
+4. **Running backend.** Probe backend health per [`../_shared/dev-server-readiness.md`](../_shared/dev-server-readiness.md) ("Backend health"). Note up/down.
+5. **Muggle Test MCP auth.** Call `muggle-remote-auth-status`. If expired, you will ask to re-auth in the questionnaire.
+6. **Candidate Muggle Test projects.** Call `muggle-remote-project-list` and rank by semantic match against the task description and the repo's dev URL.
+7. **Existing test-user secrets.** For each candidate Muggle Test project, call `muggle-remote-secret-list` and note whether `managed_profile_email` / `managed_profile_password` exist.
 8. **Auth0 tenant in use for local dev.** Grep the repo's env file for `*AUTH0_DOMAIN*`; record the tenant. This tells the user whether the staging-tenant test user will work or not.
+9. **Branch hygiene signals** for the `autoUseWorktree` and `autoRebase` gates (see [`../_shared/use-worktrees.md`](../_shared/use-worktrees.md), [`../_shared/rebase-before-e2e.md`](../_shared/rebase-before-e2e.md)):
+   - Is the current checkout already a worktree? `git -C <repo> rev-parse --is-inside-work-tree` plus `git -C <repo> worktree list`.
+   - How many commits behind `origin/<default>`? `git -C <repo> fetch origin && git -C <repo> rev-list --count "HEAD..origin/$(git -C <repo> symbolic-ref refs/remotes/origin/HEAD --short | sed 's|origin/||')"`.
+10. **`autoE2ETest` preference.** Read the session-context preferences line. Unset → treat as `always` (this gate's default — opposite of the system-wide `ask` default). `ask` → surface in Q13. `always` → no question; stage 6 runs.
 
 ## The consolidated questionnaire
 
-Present **one `AskQuestion`** (or the platform's structured-selection equivalent) that collects every remaining decision. Use detected values as defaults whenever possible. Questions to include, in this order:
+Present **one `AskUserQuestion`** (or the platform's structured-selection equivalent) that collects every remaining decision. Use detected values as defaults whenever possible. Questions to include, in this order:
 
 1. **Task scope clarification** — only if the task description is genuinely ambiguous. Offer 2–3 interpretations as options plus "Other — type a clarification." If the task is unambiguous, omit.
 2. **Repo(s) to modify** — pre-selected with the best silent match. "Confirm <repo>" / "Change repo" / "Multi-repo (list them)".
 3. **Branch name** — default: `users/<user>/<slug>` derived from the task. "Use default" / "Use different name (type)".
 4. **Validation strategy** — the single most important question. Options:
-   - **Local E2E** (Muggle Electron against a running localhost) — default if a dev server was detected.
+   - **Local E2E** (Muggle Test Electron against a running localhost) — default if a dev server was detected.
    - **Staging replay** — for changes already deployed to a preview URL.
    - **Unit tests only** — skip E2E, acceptable for pure refactors or backend-only changes.
    - **Skip validation** — explicit opt-out; the PR title gets `[UNVERIFIED]`.
 5. **Local URL** — only if validation is Local E2E. Default: the detected port. "Confirm `<detected>`" / "Type a different URL".
 6. **Backend reachable?** — only if validation is Local E2E and a backend URL is declared. If the health probe failed, ask "Start the backend now and I'll re-probe" / "Proceed anyway" / "Skip to unit tests only".
-7. **Muggle project** — pre-selected with the best silent match. "Use <top match>" / "Use a different existing project (list)" / "Create new".
+7. **Muggle Test project** — pre-selected with the best silent match. "Use <top match>" / "Use a different existing project (list)" / "Create new".
 8. **Test-user credentials** — only if validation is Local E2E AND the Auth0 tenant in the repo differs from the tenant the managed secrets were created under. Options: "Reuse existing secrets (may fail if tenant mismatch — will surface failure)" / "Create new secrets for this tenant (provide email + password)" / "Switch to staging replay".
 9. **PR target branch** — default: the repo's default branch. "Use default" / "Target a different branch".
-10. **Re-auth Muggle MCP?** — only if auth was missing/expired. "Log in now" / "Abort".
+10. **Re-auth Muggle Test MCP?** — only if auth was missing/expired. "Log in now" / "Abort".
+11. **Worktree for this change?** — gate: [`autoUseWorktree`](../muggle-preferences/preference-gates/autoUseWorktree.md). Options: create a sibling worktree, or work in the current checkout.
+12. **Rebase onto `origin/<default>` first?** — gate: [`autoRebase`](../muggle-preferences/preference-gates/autoRebase.md), only if `behind > 0`. Options: rebase before stage 6, or run as-is.
+13. **Run E2E at the end of every cycle?** — gate: [`autoE2ETest`](../muggle-preferences/preference-gates/autoE2ETest.md), only if step 10's silent detection resolved to `ask`. Options: always run stage 6, or ask each cycle.
 
 If fewer than two of the above need the user, still gather them in a single turn — never open a second round.
 
@@ -73,7 +80,7 @@ After the user answers, write **`state.md`** with every resolved value, verbatim
 - Validation: <strategy>
 - Local URL: <url or N/A>
 - Backend status: <up | down | N/A>
-- Muggle project: <name> (<uuid>)
+- Muggle Test project: <name> (<uuid>)
 - Test credentials: <existing | new | skip>
 - PR target: <branch>
 - Auth status: <ok | re-authed | N/A>

package/plugin/skills/m/SKILL.md

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

package/plugin/skills/mdo/SKILL.md

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

package/plugin/skills/mfeedback/SKILL.md

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

package/plugin/skills/mimport/SKILL.md

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

package/plugin/skills/mpr/SKILL.md

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

package/plugin/skills/mprefs/SKILL.md

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

package/plugin/skills/mregen/SKILL.md

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

package/plugin/skills/mrelease/SKILL.md

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

package/plugin/skills/mrepair/SKILL.md

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

package/plugin/skills/mstatus/SKILL.md

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

package/plugin/skills/mtest/SKILL.md

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

package/plugin/skills/mtestlocal/SKILL.md

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

package/plugin/skills/mtestprep/SKILL.md

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

package/plugin/skills/muggle/SKILL.md

@@ -1,32 +1,25 @@
 ---
 name: muggle
-description: Muggle AI command router and menu. Use when user types "muggle" or asks for available Muggle commands.
+description: Muggle AI command router and menu. Use when user types "muggle" or asks for available Muggle Test commands.
 ---
 
-# Muggle
+# Muggle Test
 
-Use this as the top-level Muggle command router.
+> Telemetry first step: see [`_shared/telemetry-emit.md`](../_shared/telemetry-emit.md). Use `skillName: "muggle"`.
 
-## Preferences
-
-User preferences are available in the session context (injected at session start). Look for the line starting with `Muggle Preferences` — it contains key=value pairs like `autoLogin=ask showElectronBrowser=always ...`.
+Use this as the top-level Muggle Test command router.
 
-If no preferences line is present, treat all preferences as `"ask"`.
+## Preferences
 
-When you reach a decision gated by a preference:
-- **`always`** → proceed without asking the user
-- **`never`** → skip without asking the user  
-- **`ask`** → ask the user, then offer: "Want me to remember this choice for future sessions?" If yes, call `muggle-local-preferences-set` with the key, their chosen value, and scope `global`.
+User preferences are injected by the SessionStart hook into a `Muggle Test Preferences` line in session context (key=value pairs). Resolution: defaults → `~/.muggle-ai/preferences.json` (global) → `<repo>/.muggle-ai/preferences.json` (project). Treat absent prefs as `ask`.
 
-This skill uses these preferences:
+This router skill itself does not gate any decision on a preference — it just routes user intent to a downstream skill. Each downstream skill consults its own preferences. For example, `checkForUpdates` is consulted by `muggle-status` (Check 4), not here.
 
-| Preference | Decision it gates |
-|------------|------------------|
-| `checkForUpdates` | Check for newer Muggle version |
+If the user types "muggle" with no subcommand and you want to surface a contextual hint about the update-check pref, defer to `muggle-status` rather than reimplementing the gate in this router.
 
 ## Menu
 
-When user asks for "muggle" with no specific subcommand, use `AskQuestion` to present these four options:
+When user asks for "muggle" with no specific subcommand, use `AskUserQuestion` to present these four options:
 
 - "Test a feature — run E2E acceptance tests locally or remotely" → `muggle-test-feature-local` (local) or `muggle-test` (remote/change-driven)
 - "Build something — implement a feature with E2E acceptance tests and a visual PR" → `muggle-do`
@@ -44,5 +37,6 @@ 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`
+- 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 `AskQuestion` with the most likely options rather than asking the user to type a clarification.
+If intent is ambiguous, use `AskUserQuestion` with the most likely options rather than asking the user to type a clarification.

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

@@ -4,9 +4,11 @@ description: Unified Muggle AI workflow entry point. Use when user types muggle
 disable-model-invocation: true
 ---
 
-# Muggle Do
+# Muggle Test Do
 
-Muggle Do runs a battle-tested autonomous dev cycle: **pre-flight → requirements → impact analysis → validate code → unit tests → E2E acceptance → open PR**.
+> 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**.
 
 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.
 
@@ -16,12 +18,28 @@ For maintenance tasks, use the dedicated skills:
 - `/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 → treat as a new task description and start/resume a dev-cycle session.
+- 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
 
@@ -39,7 +57,7 @@ Treat `$ARGUMENTS` as the user command:
 
 ## Front-loading (stage 1 non-negotiable)
 
-All ambiguity — task scope, repo selection, validation strategy, localhost URL, backend health, Muggle project, test-user credentials, branch name, PR target — is resolved in a **single** pre-flight turn. See `pre-flight.md` for the exact questionnaire.
+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.
 
 **Red-flag behaviors (do not do):**
 

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

@@ -0,0 +1,37 @@
+---
+name: muggle-do-pr-followup
+description: One polling tick of /muggle-do stage 8 — addresses reviewer comments and CI failures on PRs opened by an earlier /muggle-do session. Dispatched by `/loop 5m /muggle:muggle-do-pr-followup <slug>` after stage 7; also re-runnable by hand on any session slug.
+disable-model-invocation: true
+---
+
+# Muggle Test Do — PR follow-up
+
+> Telemetry first step: see [`_shared/telemetry-emit.md`](../_shared/telemetry-emit.md). Use `skillName: "muggle-do-pr-followup"`.
+
+This skill is the **dispatch entry** for stage 8 of /muggle-do. It is intentionally thin — the actual per-tick logic lives in [`../do/pr-followup.md`](../do/pr-followup.md), the single source of truth.
+
+## Input routing
+
+`$ARGUMENTS` is the **session slug** (the directory name under `.muggle-do/sessions/`).
+
+- Empty / `help` / `?` → list available session slugs from `.muggle-do/sessions/` that have a non-empty `prs.json` with at least one non-terminal entry, then exit. Do not start a poll.
+- Otherwise → resolve `.muggle-do/sessions/<slug>/`. If the directory or its `prs.json` is missing, log the error to `followup.log` (creating it if needed) and exit. Do **not** ask the user.
+
+## Run one tick
+
+With a valid session slug, follow [`../do/pr-followup.md`](../do/pr-followup.md) exactly. That file owns:
+
+- The turn preamble.
+- The 9-step per-tick contract.
+- The classify rule (directive / question / CI failure / ambiguous → escalate).
+- Reply routing.
+- Telemetry shape.
+- The self-check before exit.
+
+This skill file adds nothing beyond the slug resolution above.
+
+## Why a separate entry exists
+
+- `/loop 5m /muggle:muggle-do-pr-followup <slug>` (dispatched by stage 7 of /muggle-do) needs a slash-addressable target.
+- Manual re-attach: if `/loop` was killed and the user wants to resume, they can run `/muggle:muggle-do-pr-followup <slug>` once to drive a single tick, or re-dispatch the `/loop` themselves.
+- Isolated debugging: a single tick is reproducible against a real session dir.