@muggleai/works 4.11.4 → 4.12.0

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

@@ -1,104 +1,8 @@
-# PR Creation Agent (Stage 7 — Open PR)
+# Create-or-Update PR (Stage 7)
 
-Open a pull request for each repo that has changes. If an E2E walkthrough report is available from the previous stage, attach it. Honor preference gates. Hand off to stage 8 once done.
+Two modes, set by the `/muggle-do` invocation. Each consumer loads only its mode's file.
 
-## Turn preamble
-
-```
-**Stage 7 — Open PR** — pushing the branch and opening the PR.
-```
-
-## Inputs
-
-- Per-repo: name, path, branch.
-- Requirements: goal, acceptance criteria.
-- **Optional** E2E acceptance report from stage 6 — only present when validation ran. Produced by [`e2e-acceptance.md`](e2e-acceptance.md); schema is canonical in [`muggle-pr-visual-walkthrough/SKILL.md`](../muggle-pr-visual-walkthrough/SKILL.md) (Zod-validated by the CLI).
-
-## Per repo
-
-0. **`autoCreatePR` gate** — apply per [`../muggle-preferences/preference-gates/autoCreatePR.md`](../muggle-preferences/preference-gates/autoCreatePR.md). On skip, record the reason in `result.md` and move on.
-
-1. **Push:** `git push -u origin <branch>` in the repo directory.
-
-2. **Title** (under 70 chars):
-   - E2E report exists and has failures → `[E2E FAILING] <goal>`
-   - No E2E report at all (validation was `unit-only` or `skip`) → `[UNVERIFIED] <goal>` or `[UNIT-ONLY] <goal>` to match the validation strategy
-   - Otherwise → `<goal>`
-
-3. **Body** — assemble in order:
-   - `## Goal` — from requirements.
-   - `## Acceptance Criteria` — bulleted; omit section if empty.
-   - `## Changes` — summary of what changed in this repo.
-   - `## Validation` — one line: link to E2E report, or `unit-only`, or `skip — <reason>`.
-   - **If an E2E report exists,** invoke [`muggle-pr-visual-walkthrough`](../muggle-pr-visual-walkthrough/SKILL.md) Mode B to render the walkthrough block. Embed the returned `body` verbatim (it brings its own `## E2E Acceptance Results` heading). If no report, skip this block entirely.
-
-4. **Create:** `gh pr create --title "..." --body "..." --head <branch>`. Capture the PR URL and number.
-
-5. **Overflow comment:** if the walkthrough skill returned a non-null `comment`, post it once:
-   ```bash
-   jq -r '.comment' /tmp/muggle-pr-section.json | gh pr comment <PR#> --body-file -
-   ```
-   Never post when `comment` is `null`.
-
-## Stage 8 handoff
-
-After every repo is processed, build the manifest and dispatch **one follow-up loop per opened PR**. The dispatches are the LAST action this stage takes — once they fire, the original session is free.
-
-Write `.muggle-do/sessions/<slug>/prs.json` with one entry per **opened** PR (skip repos where `autoCreatePR` short-circuited or PR creation failed):
-
-```json
-[{ "repo": "owner/repo", "number": 142, "url": "...", "head_sha": "...", "state": "open" }]
-```
-
-Seed `.muggle-do/sessions/<slug>/last_seen.json` keyed by `"<owner>/<repo>#<n>"` with the empty-cursor shape (full shape in [`../muggle-pr-followup/contract.md`](../muggle-pr-followup/contract.md)). Stage 7 only seeds; each per-PR loop owns advancing its own cursor.
-
-Also seed `.muggle-do/sessions/<slug>/cycle.json` — the muggle-do implementation cycle declaration the follow-up loop will invoke on each actionable review:
-
-```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>",
-  "useSubagent": false
-}
-```
-
-For each entry in `prs.json`, dispatch its own loop as the final action:
-```
-/loop 1m /muggle:muggle-pr-followup <slug> <pr-number>
-```
-Resolve `<slug>` from the session directory's basename. One loop per PR — multi-repo sessions opening N PRs result in N independent loops, each tracking its own PR's review thread.
-
-If `prs.json` is empty (all repos skipped, or all PR creations failed), **do not dispatch** — record the reason in `result.md` and exit.
-
-## Self-check before exit
-
-- [ ] Every non-skipped repo got `gh pr create` to succeed.
-- [ ] When an E2E report existed, the walkthrough block was rendered via Mode B (not hand-written).
-- [ ] Overflow `comment` was posted only when non-null.
-- [ ] `prs.json` and `last_seen.json` reflect the PRs actually opened.
-- [ ] If `prs.json` is non-empty, the `/loop` dispatch was the last action.
-
-## Output
-
-**PRs Created:** repo → URL
-**Skipped:** repo → reason (when `autoCreatePR` short-circuited)
-**Overflow comments posted:** repo → PR #
-**Stage 8:** `Watching <N> PR(s) — one /loop 1m /muggle:muggle-pr-followup <slug> <pr#> per PR` | `No PRs to watch — stage 8 not dispatched`
-**Errors:** repo → message
-
-## Post-merge cleanup
-
-Gated by `autoCleanup`. Fires in a follow-up turn after merge — never from this stage. See [`../_shared/post-merge-cleanup.md`](../_shared/post-merge-cleanup.md).
-
-Append one short reminder tied to the gate value:
-
-- `always` → `Once merged, I'll run the cleanup sequence automatically.`
-- `never` → omit.
-- `ask` / absent → `Once merged, I'll check with you about cleanup.`
+| Mode | When | Procedure |
+| :--- | :--- | :-------- |
+| Forward | After stages 1–6 of a fresh feature (called by `/muggle-do`'s forward pipeline). Creates the PR, seeds state, dispatches the first watcher. | [`open-prs/forward.md`](open-prs/forward.md) |
+| Update | The PR already exists; the address-reviews orchestrator called this stage to push + refresh title/description/walkthrough. | [`open-prs/update.md`](open-prs/update.md) |

package/plugin/skills/do/per-comment-replies.md

@@ -0,0 +1,61 @@
+# Per-Comment Inline Replies
+
+A `/muggle-do` step invoked from [`address-reviews.md`](address-reviews.md) (Step 4f) after the push has succeeded. Posts one inline nested reply on each line comment from the actionable reviews, describing what was done for that comment and referencing the new SHA.
+
+This is **not** a top-level "summary reply on the review." Each comment thread gets its own reply, in context, via GitHub's `/comments/{id}/replies` endpoint.
+
+## Inputs
+
+- `actionable_reviews` — the list of reviews classified actionable in `address-reviews.md` Step 2.
+- `new_sha` — the SHA `open-prs/update.md` just pushed.
+- The PR's owner, repo, number.
+
+## Procedure
+
+### Step 1 — Build the comment-to-change map
+
+For each comment in each actionable review, the cycle's `build.md` produced (or should have produced) a one-line note describing what was changed for that specific comment. Two sources, in order:
+
+1. If `build.md` returned a `comment_changes` map keyed by comment id → short description, use it directly.
+2. If not (legacy `build.md` that doesn't return that shape yet), infer from the diff + the comment's body: which file/line did the comment refer to, and what changed at or near it. The inferred description is best-effort; better to be brief than wrong.
+
+If a comment has no associated change in either source (e.g. the comment was a question, not a change request), use the comment's body to compose a one-sentence answer.
+
+### Step 2 — Post one reply per comment
+
+For each comment id with a description:
+
+```bash
+gh api --method POST \
+  -H "Accept: application/vnd.github+json" \
+  repos/<owner>/<repo>/pulls/<n>/comments/<comment-id>/replies \
+  -f body="<reply-body>"
+```
+
+Reply body uses the template in [`../muggle-pr-followup/output-templates/inline-reply.md`](../muggle-pr-followup/output-templates/inline-reply.md):
+
+```
+Addressed in <short-sha>: <one-line summary of the change made for THIS comment>.
+```
+
+`<short-sha>` is the first 7 chars of `new_sha`. The body must contain the literal `<short-sha>` substring — the resolve-reminder stage greps for it to classify threads as addressed-by-loop.
+
+### Step 3 — Handle review-body-only comments
+
+If an actionable review has a non-empty `body` and **zero** line comments, GitHub has no `/replies` endpoint for the review body itself (the API has been inconsistent on this and the only reliable path is a top-level PR comment that references the review). Use the *top-level reference* form:
+
+```
+Re: review #<review_id> — addressed in <short-sha>: <one-line summary>.
+```
+
+Posted per [`../_shared/github-cli-recipes/top-level-comment.md`](../_shared/github-cli-recipes/top-level-comment.md). Fires at most once per actionable review-with-no-line-comments. Does not fire if the review has line comments — Step 2 covers those.
+
+## Failure modes
+
+- `gh api` returns an error for an individual reply → log to `followup.log`, continue with the remaining comments. Do not abort the whole step over one failure; the push has already happened and other replies still need posting.
+- All replies fail → surface the most-recent `gh` error to the user, but do not abort the overall `/muggle-do` invocation. The resolve-reminder stage still runs; the watcher still respawns. The next cycle on this PR will produce more replies and the missing ones can be picked up by the human reviewer.
+
+## Invariants
+
+- One reply per line comment. No per-review summary reply anywhere.
+- Every reply body contains the new SHA's 7-char prefix — the resolve-reminder stage greps for it.

package/plugin/skills/do/resolve-reminder.md

@@ -0,0 +1,70 @@
+# Resolve-Reminder Stage
+
+A `/muggle-do` stage that runs in **address-reviews mode only**, after per-comment inline replies have been posted. Scans every unresolved comment thread on the PR, classifies them, and posts ONE top-level PR comment listing the threads the loop addressed in this push.
+
+Runs zero or one times per `/muggle-do` invocation:
+
+- Runs when at least one actionable review was processed (i.e. the cycle actually pushed).
+- Does not run when the entire input batch was ambiguous (no push, nothing to remind about).
+- Does not run in the forward pipeline (a fresh PR has no review threads to remind about).
+
+## Turn preamble (inline within `/muggle-do` cycle)
+
+This stage does not print a turn preamble — it runs inside `/muggle-do`'s address-reviews cycle, immediately after per-comment replies and before respawning the watcher.
+
+## Inputs
+
+- The current PR (URL, owner, repo, number) from the session's `prs.json`.
+- `last_seen.pushed_shas[]` from `last_seen.json` — the list of every SHA `/muggle-do` has pushed for this PR.
+- The loop user's GitHub login (cached in `state.md` under `Loop user:` — re-resolve per [`../_shared/github-cli-recipes/loop-user-identity.md`](../_shared/github-cli-recipes/loop-user-identity.md) if missing).
+
+## Procedure
+
+### Step 1 — Fetch unresolved comment threads
+
+Per [`../_shared/github-cli-recipes/unresolved-threads.md`](../_shared/github-cli-recipes/unresolved-threads.md). Filter client-side to `isResolved == false`. Each thread carries its line comments with `author.login`, `body`, and `databaseId`.
+
+If the API call fails, log the error to `followup.log` and skip the stage. Do not surface a user-facing error — the resolve reminder is a nice-to-have, not load-bearing. The reply summaries on the threads themselves still happen.
+
+### Step 2 — Classify each thread
+
+For each unresolved thread, walk its comments in chronological order. Classify by the **first match** that applies:
+
+- **Addressed by the loop** — at least one comment authored by the loop user **and** that comment's body cites a SHA prefix in `last_seen.pushed_shas[]`. Bodies use the form *"Addressed in `<short-sha>`: ..."* per [`../muggle-pr-followup/output-templates/inline-reply.md`](../muggle-pr-followup/output-templates/inline-reply.md), so a substring match on any `pushed_shas[i][:7]` works.
+- **Addressed by a human** — at least one comment authored by a non-loop-user identity created after the original comment's timestamp, and no addressed-by-loop signal.
+- **Not addressed** — neither of the above.
+
+The classification considers only the unresolved threads' comments. Do not cross-reference timeline events from outside the threads.
+
+### Step 3 — Build the resolve-reminder list
+
+Collect the thread `databaseId` of every thread classified as **addressed by the loop in this push** (i.e. citing a SHA in `pushed_shas[]` where that SHA was added by the current invocation; older SHAs were already covered by prior cycles' reminders).
+
+Note: the watcher does not maintain a "addressed-this-cycle" set; this stage derives it by comparing thread comments to the most-recent appended SHA. The simplest deterministic rule: include a thread iff at least one of its bot replies cites the **most recent** `pushed_shas[-1]`. Earlier SHAs were already addressed in past reminders.
+
+### Step 4 — Post the top-level reminder comment
+
+If the resolve-reminder list is non-empty, post **one** top-level PR comment using the template in [`../muggle-pr-followup/output-templates/resolve-reminder.md`](../muggle-pr-followup/output-templates/resolve-reminder.md) per [`../_shared/github-cli-recipes/top-level-comment.md`](../_shared/github-cli-recipes/top-level-comment.md).
+
+If the list is empty (the push didn't end up addressing any threads — e.g. the actionable work was on lines that had no comment threads), post **nothing**. Still emit telemetry so the stage's run is observable.
+
+### Step 5 — Emit telemetry
+
+Emit one event per [`../_shared/telemetry-events/muggle-do-resolve-reminder.md`](../_shared/telemetry-events/muggle-do-resolve-reminder.md). Include:
+
+- `addressed_by_loop` — count of threads added to the reminder list in Step 3.
+- `addressed_by_human` — count from Step 2's other category.
+- `not_addressed` — count from Step 2's "not addressed" category.
+- `comment_posted` — true iff Step 4 actually posted a comment.
+
+## Failure modes
+
+This stage is best-effort. Any failure is logged to `followup.log` and silently skipped — the reviewer still gets the per-comment inline replies (the canonical signal that work was done), and the cycle continues to respawn the watcher.
+
+The one exception: do not silently swallow a `gh pr comment` failure if Step 4 ran. The comment is a user-visible artifact; if it fails, surface the underlying `gh` error to the user so they know the reminder didn't post.
+
+## Invariants
+
+- Telemetry fires once per invocation, even when no comment is posted.
+- The reminder only covers threads addressed by the **most recent** push — older SHAs were covered by prior cycles' reminders.
+- This stage suggests; it does not resolve threads on the reviewer's behalf.

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.