@muggleai/works 4.10.1 → 4.11.0

package/plugin/skills/_shared/pr-followup-helpers.md

@@ -0,0 +1,150 @@
+# PR follow-up helpers
+
+Generic operational guidance for running a PR-comment follow-up loop on GitHub: reviewer allow-list resolution, reply routing across the different comment endpoints, and a classification rule for reviewer comments with worked examples and a borderline test. Caller-agnostic — any loop that picks one comment per tick and decides what to do with it can drive off this doc.
+
+The classification produces an **action shape** (in-place change, deep-cycle through the caller's implementation pipeline, reply only, escalate, etc.) — the caller maps each shape to its specific routing (which stage to dispatch, which terminal-message template to use, which reply endpoint to hit).
+
+## Resolving the reviewer allow-list
+
+Stage 8 only acts on comments authored by users in the **allow-list** = (requested reviewers ∪ CODEOWNERS) − bots − PR author. Re-resolve every tick (decision 9 in the design doc).
+
+### Step 1: requested reviewers
+
+```bash
+gh pr view <number> --repo <owner>/<repo> --json reviewRequests,author
+```
+
+`reviewRequests` is an array of `{ login? , slug? }`. User reviewers have `login`; team reviewers have `slug` (and `name`). Expand teams to member logins:
+
+```bash
+gh api orgs/<org>/teams/<slug>/members --jq '.[].login'
+```
+
+Record `prAuthor = author.login` for the exclusion step.
+
+### Step 2: CODEOWNERS
+
+Look for the file in this order — first hit wins:
+
+1. `.github/CODEOWNERS`
+2. `CODEOWNERS`
+3. `docs/CODEOWNERS`
+
+Read from the PR's **head branch** (not master), because a PR that adds CODEOWNERS should be allowed to take effect once merged but is informational while open. In practice this means:
+
+```bash
+gh api repos/<owner>/<repo>/contents/.github/CODEOWNERS?ref=<head_sha> --jq '.content' | base64 -d
+```
+
+Parse line-by-line:
+
+- Skip blank lines and lines starting with `#`.
+- Each line is `<pattern> <owner1> <owner2> ...`.
+- Owners are either `@user` or `@org/team`. Strip the leading `@`.
+- For our purposes we don't need to match `<pattern>` against changed files — CODEOWNERS membership for the *repo* is enough. Collect the union of all owners across all lines.
+
+Expand `@org/team` to member logins via the orgs/teams/members endpoint (same as Step 1).
+
+If no CODEOWNERS file exists in any of the three locations, the CODEOWNERS contribution is empty. Don't fail.
+
+### Step 3: filter
+
+Allow-list = (requested reviewers ∪ CODEOWNERS) − `{prAuthor}` − bot logins.
+
+Bot logins are any login matching:
+
+- Ends with `[bot]` (e.g. `dependabot[bot]`)
+- Exact match in the standard list: `dependabot`, `github-actions`, `renovate`, `mergify`
+
+A comment author not in the allow-list is silently ignored — do not reply, do not address.
+
+## Reply routing
+
+GitHub's PR APIs are not uniform across comment types. Route by parent type.
+
+### Line-level review comment
+
+A comment attached to a specific file:line that belongs to a review thread. This is the **most common** path.
+
+```bash
+gh api \
+  --method POST \
+  -H "Accept: application/vnd.github+json" \
+  /repos/<owner>/<repo>/pulls/<number>/comments/<comment_id>/replies \
+  -f body="Done in $(git rev-parse --short HEAD) — renamed \`fooBar\` to \`foo_bar\`."
+```
+
+The reply lands in the same review thread. The reply itself becomes a new line-level comment with `in_reply_to_id = <comment_id>`.
+
+### Review body (CHANGES_REQUESTED with no inline comments)
+
+A reviewer left a summary review with `state: CHANGES_REQUESTED` and a body, but **no** inline comments. GitHub has no "reply to review body" endpoint — post a top-level PR comment that references the review:
+
+```bash
+gh pr comment <number> --repo <owner>/<repo> --body "Re: review #<review_id> — done in $(git rev-parse --short HEAD)."
+```
+
+### Failing CI check
+
+No reply. The fix commit IS the response. Include the failing check name in the commit subject so the connection is obvious in `git log`:
+
+```
+fix(ci): typecheck — narrow type of foo
+fix(ci): lint — remove unused import
+```
+
+### Never
+
+- Never post a top-level comment in reply to a line-level comment. It loses thread context and pollutes the PR conversation tab.
+- Never `gh pr review --comment` for replies — that endpoint is for *new* reviews, not replies.
+- Never reply twice to the same comment. The cursor in `last_seen.json` is the only re-entry guard; advance it after every reply.
+
+## Classify
+
+Classify the **review as a unit**, not individual comments.
+
+| Class | Signal | Action |
+| :---- | :----- | :----- |
+| **actionable** | Review names at least one concrete change or asks an answerable question. Soft phrasing counts when there's a concrete referent. | Treat as amended requirements; run the caller's implementation cycle; reply with one summary referencing the new SHA. |
+| **ambiguous** | No actionable signal — pure vibes, contradictory, or depends on knowledge the loop can't access. | Escalate once with two interpretations; pause the PR. |
+
+Default to **actionable**. CI catches wrong attempts; reviewers correct on the next round. Escalation is a round-trip with an absent user — reserve it.
+
+Reply summary shape:
+
+- **actionable**: `Addressed review <review_id> in <sha> — cycle ran clean (or: with <N> failures, see walkthrough).`
+- **ambiguous**: no bot reply.
+
+### Worked examples — Actionable reviews
+
+| Review (summarized) | Why actionable |
+| :------------------ | :------------- |
+| 3 comments: "rename `fooBar` to `foo_bar`", "use `const` here", "fix this typo" | Three concrete edits |
+| 1 comment: "could the procedure be simpler?" | Soft-phrased but the intent is clear — simplify; pick the best interpretation, run the cycle, reply with what was changed |
+| Review body: "Mostly looks good. Two things: extract the validation into a helper, and add a null check before the lookup." Plus 0 line comments. | Two concrete directives in the body |
+| 4 comments: "why this approach?", "is this called from X?", "does this need to handle empty array?", "what's the perf here?" | All questions but each is answerable; cycle dispatches an "answer + maybe-fix" pass and the reply summary captures each answer |
+| 1 comment: "rewrite this module — the architecture doesn't match the spec" | Substantive rebuild, but the direction is clear: redo the module per the spec |
+| 1 comment: "I'd lean toward the bar.ts pattern" | Concrete referent (bar.ts) — apply that pattern |
+
+The single review goes through one full cycle regardless of comment count.
+
+### Worked examples — Ambiguous reviews
+
+| Review (summarized) | Why ambiguous |
+| :------------------ | :------------ |
+| 1 comment: "👀" / "hmm" / ":thinking:" | No signal at all |
+| 1 comment: "this is wrong" with no target or direction | Asserts a problem but doesn't propose a fix |
+| 2 comments: "use X" + "but actually don't use X" | Self-contradicting — can't reconcile without the reviewer |
+| 1 comment: "we discussed this offline — please address" | References context the loop doesn't have |
+| 1 comment: "won't this break the prod migration we did last week?" | Implicit change request gated on knowledge the loop can't access |
+| Mixed: 2 concrete directives + 1 comment "but also, rethink the whole approach" | The "rethink the whole approach" subverts the other two; escalate to confirm scope |
+
+Escalate per the caller's escalation procedure (write the review id to the cursor's escalated set, emit one terminal message with both interpretations, pause the PR until the user resolves).
+
+### Borderline rule
+
+If you can paraphrase the review's intent as **"do X"** with X being a concrete change (one or several) — it's actionable. Pick the best interpretation and dispatch the cycle.
+
+If you can paraphrase it only as **"the reviewer is dissatisfied but I can't tell with what"** — it's ambiguous.
+
+When the review mixes both ("3 concrete directives + 1 dissatisfaction"), the safer move is usually to action the concrete directives and ask about the dissatisfaction in the reply summary. Pure ambiguity means *nothing* in the review is actionable.

package/plugin/skills/do/build.md

@@ -0,0 +1,51 @@
+# Build Agent (Stage 3)
+
+Implement the code change for this dev cycle. Read the frozen requirements from stage 2, produce the edits in each affected repo's worktree, and commit.
+
+## Turn preamble
+
+```
+**Stage 3 — Build** — implementing the change per the frozen requirements.
+```
+
+## Inputs
+
+- `requirements.md` from stage 2: goal, acceptance criteria, affected repos.
+- `state.md` from pre-flight: worktree path per repo, target branch, anything else the build needs to know about the environment.
+
+## Your job
+
+For each affected repo:
+
+1. **Re-read `requirements.md`.** Treat goal + AC as frozen. If something is unclear at this stage, that's a pre-flight bug — escalate, do not improvise.
+2. **Apply the change** in the repo's worktree. Edit existing files first; create new files only when the requirements demand it. Match the surrounding code's style, naming, and file layout.
+3. **Don't add what wasn't asked for.** No speculative abstractions, no extra logging, no "while I'm here" refactors. Three similar lines is better than a premature abstraction.
+4. **Commit** with a conventional-commit subject:
+   - `feat(<scope>): <short>` for new behavior
+   - `fix(<scope>): <short>` for bug fixes
+   - `refactor(<scope>): <short>` for reshape
+   - `docs(...)`, `chore(...)`, `test(...)` as appropriate
+
+   The body explains *why* when the why is non-obvious. The diff already says *what*.
+
+## Output
+
+Per repo:
+
+**Repo:** name
+- Files edited / created: list
+- Commit subject: `<conventional commit>`
+- Notable choices: anything that needed a judgment call (briefly)
+
+**Overall:** READY for impact analysis | BLOCKED — reason
+
+If a requirement is fundamentally unimplementable as written, halt and escalate with the specific blocker — do not ship a half-finished implementation.
+
+## Re-entry from stage 8
+
+Stage 8 (PR follow-up) may dispatch back to this stage when a reviewer comment requires real implementation work rather than an in-place doc edit. When re-entered:
+
+- The dispatch from stage 8 carries the comment(s) that triggered the re-build as additional context; treat them as amendments to the goal/AC for this iteration.
+- Continue on the existing branch — do not re-create the worktree.
+- Cycle forward through impact analysis → unit tests → E2E → open PR (which is a no-op since the PR already exists; just push).
+- Stage 8 resumes polling after the push lands.

package/plugin/skills/do/e2e-acceptance.md

@@ -1,4 +1,4 @@
-# E2E Acceptance Agent (Stage 6/7)
+# E2E Acceptance Agent (Stage 6)
 
 You are executing E2E acceptance validation for the muggle-do cycle.
 
@@ -11,7 +11,7 @@ Standalone subagent (different invocation path, used by `muggle-test` Mode C): [
 Start the turn with:
 
 ```
-**Stage 6/7 — E2E acceptance** — running browser tests against the validation target from pre-flight.
+**Stage 6 — E2E acceptance** — running browser tests against the validation target from pre-flight.
 ```
 
 ## Design

package/plugin/skills/do/impact-analysis.md

@@ -1,4 +1,4 @@
-# Impact Analysis Agent (Stage 3/7)
+# Impact Analysis Agent (Stage 4)
 
 You are analyzing git repositories to determine which ones have actual code changes that need to go through the dev cycle pipeline.
 
@@ -7,7 +7,7 @@ You are analyzing git repositories to determine which ones have actual code chan
 Start the turn with:
 
 ```
-**Stage 3/7 — Impact analysis** — diffing each affected repo against its default branch.
+**Stage 4 — Impact analysis** — diffing each affected repo against its default branch.
 ```
 
 ## Input

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

@@ -1,114 +1,103 @@
-# PR Creation Agent (Stage 7/7)
+# PR Creation Agent (Stage 7 — Open PR)
 
-You are creating pull requests for each repository that has changes after a successful dev cycle run.
+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.
 
 ## Turn preamble
 
-Start the turn with:
-
 ```
-**Stage 7/7 — Open PR** — rendering the visual walkthrough and pushing the PR.
+**Stage 7 — Open PR** — pushing the branch and opening the PR.
 ```
 
-## Non-negotiable: visual walkthrough is required
-
-**You MUST invoke `muggle-pr-visual-walkthrough` (Mode B) to render the E2E section of the PR body.** Hand-writing the PR body with a text summary and `gh pr create` is a stage failure — reviewers rely on the dashboard links and per-step screenshots the walkthrough produces.
-
-If the E2E stage was skipped (validation was `unit-only` or `skip`), you may omit the walkthrough section — but mark the PR title with `[UNVERIFIED]` or `[UNIT-ONLY]` accordingly, and record the reason in the PR body under `## Validation`.
-
-Before calling `gh pr create`, self-check:
+## Inputs
 
-- [ ] `muggle-pr-visual-walkthrough` was invoked (or the skip reason is recorded).
-- [ ] The `body` returned by the skill is embedded verbatim in the PR body.
-- [ ] If `comment` is non-null, it will be posted as a follow-up after the PR is created.
+- 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).
 
-If you cannot check all three, **halt** — do not create the PR. Fix the upstream stage first.
+## Per repo
 
-## Input
+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.
 
-You receive:
-- Per-repo: repo name, path, branch name
-- Requirements: goal, acceptance criteria
-- E2E acceptance report: passed/failed test cases, each with:
-  - `testCaseId`, `testScriptId`, `runId`, `projectId`
-  - `viewUrl`: link to view run on muggle-ai.com
-  - `steps`: array of `{ stepIndex, action, screenshotUrl }`
-  - `failureStepIndex` and `error` (if failed)
-  - `artifactsDir` (for local debugging)
-  - `description` and `useCaseName` (optional but recommended) — test case one-liner and parent use case title; drive the grouped overview and the per-test collapsible headers in the rendered walkthrough. Prefer values already in the `e2e-acceptance.md` stage's conversation context; only call `muggle-remote-test-case-get` / `muggle-remote-use-case-get` for anything you don't already have.
+1. **Push:** `git push -u origin <branch>` in the repo directory.
 
-## Your Job
+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>`
 
-For each repo with changes:
+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.
 
-0. **Apply the `autoCreatePR` gate** per [`../muggle-preferences/preference-gates/README.md`](../muggle-preferences/preference-gates/README.md) + [`autoCreatePR.md`](../muggle-preferences/preference-gates/autoCreatePR.md). On the skip path, record the reason in `result.md` and move to the next repo.
-
-1. **Push the branch** to origin: `git push -u origin <branch-name>` in the repo directory.
-2. **Build the PR title:**
-   - If E2E acceptance tests have failures: `[E2E FAILING] <goal>`
-   - Otherwise: `<goal>`
-   - Keep under 70 characters
-3. **Render the E2E acceptance block** by invoking the shared `muggle-pr-visual-walkthrough` skill in **Mode B** (render-only for embedding). See "Rendering the E2E acceptance block via the shared skill" below. You receive `{body, comment}` where `body` is the E2E markdown block and `comment` is a non-null overflow comment only when the content exceeds the CLI's byte budget.
-4. **Build the PR body** by concatenating, in order:
-   - `## Goal` — the requirements goal
-   - `## Acceptance Criteria` — bulleted list (omit section if empty)
-   - `## Changes` — summary of what changed in this repo
-   - The `body` field from the skill output (already contains its own `## E2E Acceptance Results` header — do not add another)
-5. **Create the PR** using `gh pr create --title "..." --body "..." --head <branch>` in the repo directory.
-6. **Capture the PR URL** and extract the PR number.
-7. **Post the overflow `comment` only if it is non-null.** In the common case, `comment` is `null` and nothing is posted. Never post speculatively.
+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`.
 
-## Rendering the E2E acceptance block via the shared skill
-
-**Do not hand-write the `## E2E Acceptance Results` markdown, and do not call `muggle build-pr-section` directly from this stage.** The rendering workflow is owned by the shared **`muggle-pr-visual-walkthrough`** skill (see `plugin/skills/muggle-pr-visual-walkthrough/SKILL.md`), which wraps the CLI and enforces the `E2eReport` input contract with a Zod schema.
-
-### Input — the `E2eReport` JSON
-
-The `e2e-acceptance.md` stage already produces an `E2eReport` with the exact shape the skill expects (`projectId` + `tests[]` with per-test `name`, `testCaseId`, `testScriptId`, `runId`, `viewUrl`, `status`, and `steps[]` of `{stepIndex, action, screenshotUrl}`; failed tests additionally have `failureStepIndex`, `error`, and optionally `artifactsDir`; every test may additionally carry `description` and `useCaseName` — optional but recommended — which drive the grouped overview and per-test collapsible headers in the rendered walkthrough). Pass it through unchanged — do not reshape it. The full schema is documented in the shared skill.
+## Stage 8 handoff
 
-### Invocation — Mode B (render-only)
+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.
 
-Invoke `muggle-pr-visual-walkthrough` via the `Skill` tool with the `E2eReport` already in context. The skill will:
+Write `.muggle-do/sessions/<slug>/prs.json` with one entry per **opened** PR (skip repos where `autoCreatePR` short-circuited or PR creation failed):
 
-1. Validate the `E2eReport` and call `muggle build-pr-section` (piping the JSON to stdin).
-2. Parse the CLI's `{body, comment}` stdout.
-3. **Return `{body, comment}` to this stage's conversation** without posting anything — because Mode B is render-only. `body` is the E2E markdown block; `comment` is a non-null overflow follow-up comment only when content exceeds the byte budget, otherwise `null`.
-
-Mode A (where the skill itself finds an existing PR and posts a `gh pr comment`) is **not used by `muggle-do`** — it's for interactive callers like `muggle-test` that are mid-development with a PR already open. `muggle-do` always creates new PRs, so it always uses Mode B.
+```json
+[{ "repo": "owner/repo", "number": 142, "url": "...", "head_sha": "...", "state": "open" }]
+```
 
-### After rendering
+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
+}
+```
 
-Back in this stage:
+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.
 
-- Embed `body` in the `gh pr create --body` body (see step 4 above).
-- Post the overflow `comment` as a follow-up **only when it is non-null** (see step 7 above).
-- If the CLI exited non-zero, the skill surfaces the stderr error — do not swallow it, surface it to the user.
+If `prs.json` is empty (all repos skipped, or all PR creations failed), **do not dispatch** — record the reason in `result.md` and exit.
 
-### Notes on fit vs. overflow
+## Self-check before exit
 
-- **Common case (fit):** the full evidence (summary, per-test rows, collapsible failure details) lives in the PR description, `comment` is `null`, no follow-up comment is posted.
-- **Overflow case:** the CLI detects the full body would exceed its byte budget; `body` contains the summary, per-test rows, and a pointer line; `comment` contains the overflow details. Post both.
-- You do not make the fit-vs-overflow decision — the CLI does. Never post the comment when it is `null`.
+- [ ] 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 name): (PR URL)
-
-**E2E acceptance overflow comments posted:** (only include repos where an overflow comment was actually posted)
-- (repo name): comment posted to PR #(number)
-
-**Errors:** (any repos where PR creation or comment posting failed, with the error message)
+**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`)
+## Post-merge cleanup
 
-Cleanup fires in a follow-up turn after merge — never from this stage. See [`../_shared/post-merge-cleanup.md`](../_shared/post-merge-cleanup.md).
+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).
 
-After printing PR URLs, append one short reminder tied to the gate's current value:
+Append one short reminder tied to the gate value:
 
 - `always` → `Once merged, I'll run the cleanup sequence automatically.`
 - `never` → omit.

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

@@ -1,4 +1,4 @@
-# Pre-flight Agent (Stage 1/7)
+# Pre-flight Agent (Stage 1)
 
 You are running the **only user-facing stage** of the muggle-do dev cycle. Your job is to consolidate every ambiguity — task scope, repos, validation strategy, environment, credentials, PR target — into a **single turn** so the rest of the cycle can run unattended.
 
@@ -9,7 +9,7 @@ You are running the **only user-facing stage** of the muggle-do dev cycle. Your
 Start the turn with:
 
 ```
-**Stage 1/7 — Pre-flight** — consolidating everything the cycle needs before going silent.
+**Stage 1 — Pre-flight** — consolidating everything the cycle needs before going silent.
 ```
 
 ## Input
@@ -94,7 +94,7 @@ Also initialize `iterations/001.md` with a header:
 ```markdown
 # Iteration 001 — <ISO-8601 timestamp>
 
-### Stage 1/7 — Pre-flight (<timestamp>)
+### Stage 1 — Pre-flight (<timestamp>)
 
 <verbatim copy of pre-flight answers>
 ```

package/plugin/skills/do/requirements.md

@@ -1,4 +1,4 @@
-# Requirements Analysis Agent (Stage 2/7)
+# Requirements Analysis Agent (Stage 2)
 
 You are analyzing a user's task description to extract structured requirements for an autonomous development cycle.
 
@@ -7,7 +7,7 @@ You are analyzing a user's task description to extract structured requirements f
 Start the turn with:
 
 ```
-**Stage 2/7 — Requirements** — extracting structured goals from the pre-flight-clarified task.
+**Stage 2 — Requirements** — extracting structured goals from the pre-flight-clarified task.
 ```
 
 Pre-flight already resolved ambiguity via the consolidated questionnaire. **Do not ask the user any questions here** — infer silently and record assumptions in Notes.

package/plugin/skills/do/unit-tests.md

@@ -1,4 +1,4 @@
-# Unit Test Runner Agent (Stage 5/7)
+# Unit Test Runner Agent (Stage 5)
 
 You are running unit tests for each repository that has changes in the dev cycle pipeline.
 
@@ -7,7 +7,7 @@ You are running unit tests for each repository that has changes in the dev cycle
 Start the turn with:
 
 ```
-**Stage 5/7 — Unit tests** — running each repo's test suite.
+**Stage 5 — Unit tests** — running each repo's test suite.
 ```
 
 ## Input

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

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