@muggleai/works 4.11.3 → 4.12.0

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

@@ -1,72 +1,68 @@
 ---
 name: muggle-do
-description: Unified Muggle AI workflow entry point. Use when user types muggle do or asks for autonomous implementation to PR.
+description: Unified Muggle AI workflow entry point. Use when user types muggle do or asks for autonomous implementation to PR. Also handles the `address-reviews` directive (dispatched by the muggle-pr-followup watcher when new submitted reviews land on a PR).
 disable-model-invocation: true
 ---
 
 # Muggle Test Do
 
-> Telemetry first step: see [`_shared/telemetry-emit.md`](../_shared/telemetry-emit.md). Use `skillName: "muggle-do"`.
+> Telemetry first step: see [`../_shared/telemetry-emit.md`](../_shared/telemetry-emit.md). Use `skillName: "muggle-do"`.
 
-Runs an autonomous dev cycle from requirements to PR. **Fire and review:** the user answers one pre-flight questionnaire, then walks away.
+Runs an autonomous dev cycle from requirements to PR. **Fire and review:** user answers one pre-flight questionnaire, then walks away. The [muggle-pr-followup](../muggle-pr-followup/SKILL.md) watcher invokes `/muggle-do` again with the *address-reviews* directive when new reviews land.
 
-For maintenance, use the dedicated skills:
+## Forward pipeline (fresh feature)
 
-- `/muggle:muggle-status`
-- `/muggle:muggle-repair`
-- `/muggle:muggle-upgrade`
+| # | Stage | File |
+| :- | :---- | :--- |
+| 1 | Pre-flight (only user-facing stage) | [`../do/pre-flight.md`](../do/pre-flight.md) |
+| 2 | Requirements | [`../do/requirements.md`](../do/requirements.md) |
+| 3 | Build | [`../do/build.md`](../do/build.md) |
+| 4 | Impact analysis | [`../do/impact-analysis.md`](../do/impact-analysis.md) |
+| 5 | Unit tests | [`../do/unit-tests.md`](../do/unit-tests.md) |
+| 6 | E2E acceptance | [`../do/e2e-acceptance.md`](../do/e2e-acceptance.md) |
+| 7 | Create or update PR | [`../do/open-prs.md`](../do/open-prs.md) |
+| 8 | Hand off to watcher | [`../muggle-pr-followup/SKILL.md`](../muggle-pr-followup/SKILL.md) |
 
-## The pipeline
+Stage 7 dispatches one watcher per opened PR as its last action.
 
-| # | Stage | File | User-facing? |
-| :- | :---- | :--- | :----------- |
-| 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 | 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** |
+## Address-reviews flow
 
-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.
+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.
 
-**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.
+## Input routing
 
-## Preferences
+Inspect `$ARGUMENTS` in this order:
 
-| Preference | Stage | Decision it gates |
-|------------|-------|-------------------|
-| `autoE2ETest` | 6 (E2E acceptance) | Run E2E every cycle (default `always`), or fold the question into pre-flight |
+1. **Address-reviews** — input contains a `github.com/.../pull/<n>` URL **and** one or more integers ≥ 100000000 (review id shape) → [`../do/address-reviews.md`](../do/address-reviews.md). Programmatic; never ask.
+2. **Empty / `help` / `menu` / `?`** → menu + session selector.
+3. **Task automation** (perform an action on a website) → `muggle:muggle-do-task`.
+4. **Otherwise** → forward pipeline at Stage 1.
 
-Other gates that fire during this cycle (`autoUseWorktree`, `autoRebase`, `autoCreatePR`, `autoCleanup`) are owned by the per-stage files; see each stage for its contract.
+When in doubt between #3 and #4, ask one question.
 
-## Input routing
-
-Treat `$ARGUMENTS` as the user command:
+## Preferences
 
-- 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.
+| Preference | Gate |
+| :--------- | :--- |
+| `autoE2ETest` | Stage 6 — run E2E every cycle (default `always`), or fold into pre-flight |
 
-When in doubt, ask one question: "Browser automation task, or code change?"
+`autoUseWorktree`, `autoRebase`, `autoCreatePR`, `autoCleanup` fire from per-stage files.
 
 ## Session model
 
-Every run writes to `.muggle-do/sessions/<slug>/`. Stages own the files they produce:
+`.muggle-do/sessions/<slug>/`. Schemas: [`../muggle-pr-followup/state-schemas.md`](../muggle-pr-followup/state-schemas.md).
 
-| 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 |
+| File | Owner |
+| :--- | :---- |
+| `state.md` | Stage 1 or bootstrap |
+| `iterations/<NNN>.md` | Every stage |
+| `requirements.md` | Stage 2 (forward only) |
+| `prs.json`, `last_seen.json`, `followup.log` | Stage 7 / watcher / `/muggle-do` |
+| `result.md` | Stage 7 (seeded), terminal tick (finalized) |
 
 ## Guardrails
 
-- **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.
+- Stage 1 is the only user-facing forward stage. Stages 2–7 don't ask mid-cycle; blocker → pre-flight bug.
+- Same stage failing 3× → escalate.
+- 3 cycle iterations reach E2E with failures → ship with `[E2E FAILING]`.
+- Address-reviews escalation (ambiguous or design-adjustment) does not block the watcher; user resolves on GitHub.

package/plugin/skills/muggle-pr-followup/CLAUDE.md

@@ -0,0 +1,25 @@
+# muggle-pr-followup — folder TOC
+
+This folder holds the watcher loop for PR review follow-ups. The watcher is a **dumb pipe**: it polls for new submitted reviews and dispatches `/muggle-do` when there are any. Cycle execution, classification, replies, and escalation all live in `/muggle-do`'s address-reviews mode — see [stage-8 design](../../../../muggle-ai-brain/architecture/2026-05-08-muggle-do-pr-comment-loop-design.md) for the architectural rationale.
+
+## Files in this folder
+
+- [`SKILL.md`](SKILL.md) — public entry. Smart-inference routing between bootstrap mode (URL input) and tick mode (slug + PR number). Read first.
+- [`bootstrap.md`](bootstrap.md) — the bootstrap procedure (one-shot non-interactive seed + watcher dispatch).
+- [`contract.md`](contract.md) — the watcher per-tick procedure (poll → dispatch → exit).
+- [`state-schemas.md`](state-schemas.md) — canonical JSON shapes of session state files.
+- [`output-templates.md`](output-templates.md) — TOC of message templates; per-group files in `output-templates/`.
+
+## Cross-folder dependencies
+
+Shared with other skills, under `../_shared/`:
+
+- [`pr-followup-helpers.md`](../_shared/pr-followup-helpers.md) — TOC of allow-list / reply-routing / classify; per-section files in `_shared/pr-followup-helpers/`. Called by `/muggle-do`, not by this folder.
+- [`telemetry-emit.md`](../_shared/telemetry-emit.md) — how to emit a telemetry event.
+- [`telemetry-events.md`](../_shared/telemetry-events.md) — TOC of canonical event shapes; per-event files in `_shared/telemetry-events/`.
+- [`github-cli-recipes.md`](../_shared/github-cli-recipes.md) — TOC of reusable `gh` / `git` snippets; per-recipe files in `_shared/github-cli-recipes/`.
+
+Caller-specific, under `../do/`:
+
+- [`open-prs.md`](../do/open-prs.md) — TOC for the create-or-update PR stage; per-mode files in `do/open-prs/`.
+- [`resolve-reminder.md`](../do/resolve-reminder.md) — `/muggle-do`'s post-replies stage that posts the resolve-reminder top-level comment.

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

@@ -1,59 +1,37 @@
 ---
 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.
+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. 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.
 disable-model-invocation: true
 ---
 
-# Muggle PR Follow-up
+# muggle-pr-followup
 
-> Telemetry first step: see [`_shared/telemetry-emit.md`](../_shared/telemetry-emit.md). Use `skillName: "muggle-pr-followup"`.
+> 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.
+A watcher that babysits one open PR's review thread. Polls for new submitted reviews; when any land, hands them off to `/muggle-do` and exits. `/muggle-do` is the executor — it classifies the reviews, runs the work, pushes, replies per comment, and respawns the watcher.
 
-**Per-PR isolation.** One dispatch per PR, not per session. Multi-PR work runs N independent loops.
+**The watcher is a dumb pipe.** It does not classify reviews, iterate cycles, post replies, or escalate. All of that lives in `/muggle-do`. See [stage-8 design](../../../../muggle-ai-brain/architecture/2026-05-08-muggle-do-pr-comment-loop-design.md) for the rationale.
 
-## Input
+**Per-PR isolation.** One watcher per PR. Multi-PR work runs N independent watchers.
 
-`$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.
+## Routing
 
-- 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.
+The skill recognizes two modes by inspecting `$ARGUMENTS` and falling back to on-disk state. It never runs procedure inline — it identifies the mode and routes to the appropriate procedure file.
 
-## Contract
+| Input | On-disk check | Mode |
+| :---- | :------------ | :--- |
+| First arg matches `https?://github\.com/[^/]+/[^/]+/pull/\d+` | — | **bootstrap** → [`bootstrap.md`](bootstrap.md) |
+| `<slug> <pr-number>` | session dir for `<slug>` exists | **tick** → [`contract.md`](contract.md) |
+| `<slug> <pr-number>` | session dir missing | **error:** "no session at `<path>`; pass a PR URL to start one" |
+| `<pr-number>` alone | exactly one existing session contains it | **tick** for that PR |
+| `<pr-number>` alone | zero or multiple matches | **error:** ambiguous; list candidates and exit |
+| empty / `help` / `?` | — | **help:** list active loops per [`output-templates/help.md`](output-templates/help.md) |
 
-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.
+Bootstrap accepts two optional trailing flags:
 
-## Caller-supplied implementation cycle
+- `--slug=<name>` — override the default `<repo>-pr<n>` slug
+- `--resume` — opt in to reusing an existing session slot (default is refuse on conflict)
 
-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`:
+## Folder TOC
 
-```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.
+See [`CLAUDE.md`](CLAUDE.md) for the one-line index of every file in this folder.

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

@@ -0,0 +1,88 @@
+# Bootstrap Procedure
+
+The procedure for the **bootstrap mode** of `muggle-pr-followup` — invoked when a user dispatches the skill with a GitHub PR URL. Routing into this mode is documented in [`SKILL.md`](SKILL.md#routing).
+
+Bootstrap is **non-interactive**: it runs straight through, prompts the user for nothing, and ends with the first watcher dispatched. The first review the watcher sees triggers `/muggle-do`, where working-tree validation surfaces (via the existing E2E stage / muggle-test).
+
+## Turn preamble
+
+```
+**muggle-pr-followup bootstrap** — seeding state for <owner>/<repo>#<n>.
+```
+
+## Input
+
+`$ARGUMENTS = <pr-url> [--slug=<name>] [--resume]`
+
+- `<pr-url>` matches `https?://github\.com/[^/]+/[^/]+/pull/\d+` — required.
+- `--slug=<name>` overrides the default `<repo>-pr<n>` slug.
+- `--resume` opts into refreshing an existing slot instead of refusing on conflict.
+
+## Procedure
+
+### Step 1 — Parse the URL
+
+Extract `<owner>`, `<repo>`, `<pr-number>`. On malformed input, exit with the malformed-URL abort from [`output-templates/bootstrap.md`](output-templates/bootstrap.md).
+
+### Step 2 — Fetch PR metadata
+
+Per [`../_shared/github-cli-recipes/pr-metadata.md`](../_shared/github-cli-recipes/pr-metadata.md).
+
+If `state` is `MERGED` or `CLOSED`, exit with the terminal-PR abort. If the `gh` call fails (not found, auth missing), surface the underlying error verbatim and exit.
+
+### Step 3 — Verify the working tree
+
+Per [`../_shared/github-cli-recipes/verify-working-tree.md`](../_shared/github-cli-recipes/verify-working-tree.md). On any check failure, exit with the wrong-working-tree abort.
+
+### 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.
+
+### Step 5 — Idempotency check
+
+If `.muggle-do/sessions/<slug>/` exists:
+
+- 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`, `state.md`, and everything else untouched. Skip to Step 8 (no need to re-seed; no need to refetch the cursor).
+
+### Step 6 — Resolve the initial cursor
+
+Fetch reviews per [`../_shared/github-cli-recipes/submitted-reviews.md`](../_shared/github-cli-recipes/submitted-reviews.md) with cursor 0, then take `max(id)`. If none, the cursor is 0. The watcher only acts on `id > cursor`, so this pins forward-only.
+
+### Step 7 — Seed state files
+
+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>/`:
+
+**`prs.json`** — see [`state-schemas.md`](state-schemas.md#prsjson). One entry, `state` = `"open"`, `head_sha` from Step 2's `headRefOid`.
+
+**`last_seen.json`** — see [`state-schemas.md`](state-schemas.md#last_seenjson). One key (`"<owner>/<repo>#<n>"`), `reviewId` from Step 6, `last_pushed_sha: null`, `idle_tick_count: 0`, `cycles_completed: 0`, `escalated_review_ids: []`, `pushed_shas: []`.
+
+**`state.md`** — see [`state-schemas.md`](state-schemas.md#statemd). `Bootstrapped from URL: yes`. Cache the loop-user login.
+
+Do **not** write `cycle.json` or `requirements.md` — those files are no longer part of the session slot.
+
+Create `iterations/` subdir (empty) for future caller use.
+
+### Step 8 — Dispatch the first watcher
+
+The last action of this turn:
+
+```
+/loop 1m /muggle:muggle-pr-followup <slug> <n>
+```
+
+### Step 9 — Print the success summary
+
+Use the success-summary template from [`output-templates/bootstrap.md`](output-templates/bootstrap.md). Print it **before** the `/loop` dispatch so it's visible.
+
+### Step 10 — Emit telemetry
+
+Emit one event per [`../_shared/telemetry-events/pr-followup-bootstrap.md`](../_shared/telemetry-events/pr-followup-bootstrap.md). `caller = "user"` for direct invocation. Fire-and-forget per [`../_shared/telemetry-emit.md`](../_shared/telemetry-emit.md).
+
+## Invariants
+
+- All state writes happen in Step 7 — earlier aborts leave nothing on disk.
+- If Step 7 fails mid-write, surface the OS error and tell the user to `rm -rf <slot>` and re-run; do not dispatch the watcher.
+- Bootstrap never retries.

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

@@ -1,190 +1,73 @@
-# PR follow-up per-tick contract
+# Watcher 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.
+The procedure for the **tick mode** of `muggle-pr-followup` — one polling iteration scoped to one PR. The watcher is a dumb pipe: it polls for new submitted reviews, dispatches `/muggle-do` if there are any, and exits. It does not classify, amend requirements, post replies, run cycles, or escalate.
 
-## 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):
+Routing into this mode is documented in [`SKILL.md`](SKILL.md#routing). The architectural rationale lives in the brain doc `architecture/2026-05-08-muggle-do-pr-comment-loop-design.md`.
 
-- `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
+## Turn preamble
 
-```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
+**muggle-pr-followup tick** — polling <repo>#<pr-number>.
 ```
 
-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`).
+## Input
 
-### Step 4: Pull new submitted reviews
+`$ARGUMENTS = <slug> <pr-number>` (or `<pr-number>` alone — slug inferred from on-disk state per [`SKILL.md`](SKILL.md#routing)).
 
-```bash
-gh api repos/<owner>/<repo>/pulls/<number>/reviews --paginate
-```
+## Inputs from disk
 
-Filter to reviews where:
+Read these from `.muggle-do/sessions/<slug>/`:
 
-- `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.
+- `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>"`.
 
-### Step 5: Pick the oldest new review
+If either file is missing or the PR is not in `prs.json`, the tick is a no-op. Log an error line in `followup.log` and exit. The watcher must not be invoked in this state — if it happens, the slot is corrupt.
 
-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`.
+## Procedure
 
-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.
+### Step 1 — Refresh PR state
 
-**At most one review per tick.** If two reviews land between ticks, the second waits.
+Per [`../_shared/github-cli-recipes/pr-metadata.md`](../_shared/github-cli-recipes/pr-metadata.md). Update `prs.json[0].head_sha` and `prs.json[0].state` from the response.
 
-### Step 6: Classify the review
+### Step 2 — Termination check
 
-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:
+If `state` is `MERGED` or `CLOSED`:
 
-- **Actionable** → continue to Step 7.
-- **Ambiguous** → continue to Step 8.
+1. Mark the entry terminal in `prs.json`.
+2. Write `result.md` per [`state-schemas.md`](state-schemas.md#resultmd).
+3. Append a terminal line to `followup.log` per [`output-templates/watcher-log.md`](output-templates/watcher-log.md).
+4. Emit a `tick` event with `terminal: true` per [`../_shared/telemetry-events/pr-followup-tick.md`](../_shared/telemetry-events/pr-followup-tick.md).
+5. Exit. **Do not schedule another tick.** The `/loop` framework stops invoking this skill once it sees no follow-up dispatch.
 
-### Step 7: Dispatch the implementation cycle
+### Step 3 — Fetch new submitted reviews
 
-When the review is actionable:
+Per [`../_shared/github-cli-recipes/submitted-reviews.md`](../_shared/github-cli-recipes/submitted-reviews.md). **Also exclude review ids that appear in `last_seen.escalated_review_ids`** — those have already been escalated and the watcher must not re-dispatch them.
 
-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.
+### Step 4 — If zero new reviews → idle
 
-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.
+1. Increment `last_seen.idle_tick_count`.
+2. Append an idle line to `followup.log` per [`output-templates/watcher-log.md`](output-templates/watcher-log.md).
+3. Emit a `tick` event with `idle: true`, `reviews_seen: 0`, `dispatched_review_ids: []`.
+4. Exit. The next tick fires in 1 min via `/loop`.
 
-### Step 8: Escalate
+### Step 5 — If one or more new reviews → dispatch
 
-When the review is ambiguous, or the cycle failed:
+The watcher does **not** classify. Classification, batching, replying, escalation, and cycle execution all live in `/muggle-do`. The watcher's job is to hand over the list of new review ids and exit.
 
-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:
+1. Reset `last_seen.idle_tick_count` to 0.
+2. Dispatch `/muggle-do` with an *address-reviews* directive carrying:
+   - PR URL (from `prs.json[0].url`)
+   - Session slug (from the invocation arguments)
+   - Every new review id from Step 3, as a space-separated list
 
-```
-**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>
-}
-```
+   Exact phrasing belongs to `/muggle-do`'s intent-routing. A reasonable shape is:
+   ```
+   /muggle-do address reviews <id1> <id2> ... on <pr-url> slug=<slug>
+   ```
+3. Append a dispatching line to `followup.log` per [`output-templates/watcher-log.md`](output-templates/watcher-log.md).
+4. Emit a `tick` event with `reviews_seen: <count>`, `dispatched_review_ids: [<id>, ...]`.
+5. Exit. **Do not schedule another tick.** `/muggle-do` will respawn the watcher at the end of its cycle.
 
 ## 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.
+No console output beyond the turn preamble and (if Step 5 fires) the `/muggle-do` dispatch. The watcher is invisible to the reviewer.

package/plugin/skills/muggle-pr-followup/output-templates/bootstrap.md

@@ -0,0 +1,42 @@
+# Bootstrap output templates
+
+## Success summary (printed just before dispatch)
+
+```
+Bootstrapped PR follow-up for <owner>/<repo>#<n>
+  Slug:           <slug>
+  Cursor:         review #<id> (forward-only) | empty (no prior reviews)
+  Working tree:   <toplevel>
+  Dispatching:    /loop 1m /muggle:muggle-pr-followup <slug> <n>
+```
+
+## Aborts
+
+**Terminal PR:**
+```
+PR <owner>/<repo>#<n> is <state>; nothing to poll. Bootstrap aborted.
+```
+
+**Wrong working tree / wrong branch:**
+```
+Bootstrap needs the PR's branch checked out locally.
+Current cwd:    <toplevel-or-"not in a git repo">
+Current branch: <HEAD-or-"n/a">
+Expected:       a clone of <owner>/<repo> on branch <headRefName>.
+From that clone, run: gh pr checkout <n>
+```
+
+**Slot conflict (no `--resume`):**
+```
+Session <slug> already exists at <path>.
+To reuse it, pass --resume on this invocation.
+To start fresh, rm -rf the directory and re-run.
+```
+
+**Malformed URL:**
+```
+Could not parse <input> as a GitHub PR URL.
+Expected: https://github.com/<owner>/<repo>/pull/<number>
+```
+
+**GitHub API failure (PR not found, no auth, etc.):** repeat the underlying `gh` error verbatim. Do not paraphrase.