@muggleai/works 4.10.0 → 4.11.0

package/dist/plugin/skills/_shared/failure-mode-handling.md

@@ -0,0 +1,244 @@
+# Failure-Mode Handling — Shared Reference
+
+> Source of truth for **(a)** the pre-execution replay-vs-regen choice and **(b)** the post-execution failure router used by `muggle-test`, `muggle-test-feature-local`, `muggle-do-task`, and `muggle-test-regenerate-missing`. Skills MUST link here rather than restate the rules.
+
+## The contract
+
+Every decision in this doc follows the same shape:
+
+1. **Classify** — pick a bucket from a fixed taxonomy based on the available signals.
+2. **Suggest** — present the bucket-specific suggestion to the user via `AskUserQuestion`.
+3. **User decides** — the user always makes the final call. Never auto-act.
+4. **Emit telemetry** — record `(aiClassification, aiSuggestion, userAction, signals)` via `muggle-local-telemetry-event-emit` so the rules can be refined later from real data.
+
+The classification rules below are **starting heuristics**. Trust the AI's bucket only enough to phrase a default suggestion — let the user override freely.
+
+---
+
+## F. Run-level verdict taxonomy
+
+The buckets in sections A–C operate **per script** (one classification per test-case execution). This section defines the **single verdict** an acceptance-tester subagent returns to its orchestrator — one verdict per PR / per dispatched run, summarizing every test case it touched.
+
+### Verdicts
+
+| Verdict | Meaning |
+|---|---|
+| **PASS** | All relevant test cases ran and passed. The PR's user-visible change is exercised and works. |
+| **FAIL** | At least one test case demonstrated wrong behavior caused by the PR code. The PR is regressive. |
+| **PARTIAL** | Some relevant tests passed; some were INCONCLUSIVE (not failed). Useful coverage, with gaps. |
+| **INCONCLUSIVE** | All relevant tests were blocked by environment factors — script staleness, empty local DB, missing fixtures, tests out of date relative to current master UI. **Not a regression signal.** |
+| **BLOCKED** | An infra blocker prevented any meaningful execution: Auth0 tenant rejecting test emails, dev server unreachable, MCP service down, port wouldn't bind. **Not a regression signal.** |
+| **SKIPPED** | No code under test — placeholder branch, empty diff vs. master, deliberate no-op change. |
+
+PASS and FAIL are the only verdicts that say something about the PR itself. PARTIAL means "some coverage, some gaps." INCONCLUSIVE, BLOCKED, and SKIPPED all mean **don't draw a regression conclusion from this run** — they signal an environment, script, or input problem, not a product defect.
+
+### Mapping per-script buckets to run verdicts
+
+When the subagent aggregates per-script results from sections B and C into one verdict:
+
+| Per-script bucket | Section | Typical run verdict |
+|---|---|---|
+| `infra` (replay or regen) | B / C | **BLOCKED** |
+| `stale-script` (replay) | B | **INCONCLUSIVE** |
+| `product-defect` (replay) | B | **FAIL** |
+| `product-uxux` (regen) | C | **FAIL** |
+| `agent-course` (regen) | C | **INCONCLUSIVE** (agent couldn't complete, not a PR defect) |
+| `transient` (regen) | C | retry once; if still transient → **INCONCLUSIVE** |
+
+When a run mixes buckets across multiple test cases, take the most-significant verdict in this priority order: **FAIL > PARTIAL > BLOCKED > INCONCLUSIVE > SKIPPED > PASS**. If any one test case maps to FAIL, the run is FAIL. If some passed and some were INCONCLUSIVE, the run is PARTIAL.
+
+### How orchestrators consume the verdict
+
+Subagents return the verdict as part of a structured block, not free-form prose. The orchestrator parses this block to decide whether to post a "regression" PR comment, a "needs investigation" comment, or skip the PR. See `agents/acceptance-tester.md` for the exact block format the subagent must emit.
+
+---
+
+## A. Pre-execution: replay vs regen (used by `muggle-test`)
+
+Run during change analysis, **per impacted test case**. Picks the initial execution mode before Step 7. Other skills with a single user-picked target (`muggle-test-feature-local`, `muggle-do-task`) skip this section — the user already chose.
+
+### Inputs
+
+- The change summary from `git diff` (file paths + diff content).
+- The test case (title, description, instructions, last passing run timestamp).
+- Existing test scripts for that test case from `muggle-remote-test-script-list`.
+
+### Rules (fire in order; first match wins)
+
+| # | Condition | Mode | Reason |
+|---|---|---|---|
+| 1 | No replayable/succeeded script exists for the test case | `regen` | Nothing to replay. |
+| 2 | A changed file looks like UI/markup mapped to this test case (component, page, route, template, JSX/TSX/Vue/Svelte/HTML, CSS that changes layout or selectors) | `regen` | Selectors likely broken — replay would fail on staleness. |
+| 3 | Last successful run was > **30 days** ago | `regen` | Drift accumulates; the saved script is stale even without a flagged change. |
+| 4 | Otherwise — changes are logic-only / backend / styling-without-DOM-impact | `replay` | Selectors should still work; replay catches real regressions. |
+
+### Mapping "changed file → test case"
+
+Use the test case's `instructions` and `goal` text plus filenames in the diff. Match heuristically — a test case titled "Submit signup form" plus a diff in `app/auth/signup/page.tsx` is a clear match. When in doubt, prefer `regen` (rule 2 wins) — a needless regen wastes budget; a stale replay fails the test for the wrong reason.
+
+### Telemetry
+
+Emit **`pre-execution-classification`** for every test case in the batch, before execution starts:
+
+```json
+{
+  "eventType": "pre-execution-classification",
+  "skillName": "muggle-test",
+  "aiClassification": "replay" | "regen",
+  "aiSuggestion": "<same as classification>",
+  "testCaseId": "<id>",
+  "projectId": "<id>",
+  "signals": ["rule-1-no-script" | "rule-2-ui-changed" | "rule-3-stale-30d" | "rule-4-default-replay"],
+  "metadata": { "lastPassedAgeDays": <n>, "changedFilesMatched": ["..."] }
+}
+```
+
+Skill MAY surface the per-test-case decision in the report (e.g., "regenerating 3, replaying 5") so the user can override before execution. If the user overrides, emit a follow-up event with `userAction` set to the overriding mode.
+
+---
+
+## B. Post-replay failure (used by all four skills with replays)
+
+Triggered when `muggle-local-execute-replay` returns `status: "failed"` (or non-zero Electron exit) **and** the run is not an orchestration timeout already covered in `muggle-test-feature-local/SKILL.md` Step 6.
+
+### Buckets
+
+| Bucket | Meaning |
+|---|---|
+| **infra** | Something is wrong inside Muggle Test itself (e.g., click didn't register on a clearly-clickable element, Electron crash, browser engine quirk). Not the user's fault and not a stale script. |
+| **stale-script** | The test script no longer matches the live UI (selectors moved, label paths changed, page renamed). The product still works; the script is out of date. |
+| **product-defect** | The script and infra are fine; the user's app actually misbehaved (assertion failure on previously-passing step, unexpected error, wrong page after action). This is the failure mode acceptance testing exists to catch. |
+
+### Initial signal heuristics
+
+Derive signals from the run's per-step results, error messages, and step screenshots (`muggle-local-run-result-get`):
+
+- **infra** signals: `electron-crash`, `chromium-error`, `click-no-effect-on-clickable-element`, `timeout-on-trivial-wait`, `internal-error-in-mcp-output`.
+- **stale-script** signals: `element-not-found`, `selector-timeout`, `label-path-mismatch`, `nav-target-404`, `aria-label-changed`.
+- **product-defect** signals: `assertion-failed-on-passing-step`, `unexpected-error-toast`, `wrong-page-after-action`, `network-500-from-app`, `form-validation-rejected-valid-input`.
+
+If signals span multiple buckets, pick the most specific one and list all signals in telemetry — the user can override.
+
+### Suggestions per bucket
+
+Present via `AskUserQuestion`. The first option is the AI's recommendation (label it `(Recommended)`); always include the others so the user can redirect. **Always include "Skip — just report" so the user can opt out without committing to anything.**
+
+| Bucket | Recommended suggestion | Other options |
+|---|---|---|
+| **infra** | Report bug to Muggle AI → invoke `muggle-feedback` skill with `category: "muggle-infra"` (and run id / signals). | Retry; muggle-feedback (different category); Skip. |
+| **stale-script** | Regenerate the script → call `muggle-local-execute-test-generation` (or remote equivalent) for this test case, then re-replay. | Retry as-is; muggle-feedback; Skip. |
+| **product-defect** | Surface as a real defect — show the failing step + screenshot + one-line summary; offer to share via email/SMS/file ticket (see "Sharing real defects" below). | muggle-feedback (if the script's *expectation* was wrong); Retry; Skip. |
+
+### Sharing real defects
+
+When the user picks "share / file ticket" on a `product-defect`:
+
+1. Build a one-paragraph summary: test case title, failing step, expected-vs-actual, screenshot path, run id.
+2. Ask `AskUserQuestion`: where to share?
+   - Email — open `mailto:` with the summary pre-filled.
+   - SMS — copy the summary to clipboard, instruct user to paste.
+   - File ticket — if `gh` is available and there's a repo, offer `gh issue create` with the summary as the body; otherwise copy summary and instruct user.
+   - Skip — just keep the report.
+3. Record the choice in telemetry (`userAction: "share-email" | "share-sms" | "share-ticket" | "skip"`).
+
+### Telemetry
+
+Emit **two events per failure**: one when the AI classifies (before asking the user) and one when the user picks an action.
+
+```json
+{
+  "eventType": "replay-failure-classified",
+  "skillName": "<this skill>",
+  "aiClassification": "infra" | "stale-script" | "product-defect",
+  "aiSuggestion": "report-bug" | "regenerate" | "share-defect",
+  "runId": "<local run id>",
+  "testCaseId": "<id>",
+  "projectId": "<id>",
+  "signals": ["element-not-found", "selector-timeout"],
+  "metadata": { "failingStep": "<step name>", "errorExcerpt": "<first 200 chars>" }
+}
+```
+
+```json
+{
+  "eventType": "replay-failure-resolved",
+  "skillName": "<this skill>",
+  "aiClassification": "<same as above>",
+  "aiSuggestion": "<same as above>",
+  "userAction": "regenerate" | "report-bug" | "share-email" | "retry" | "muggle-feedback" | "skip",
+  "runId": "<local run id>",
+  "testCaseId": "<id>",
+  "projectId": "<id>"
+}
+```
+
+The `(aiSuggestion, userAction)` pair is the metric we tune from — when they diverge, the classifier needs work.
+
+---
+
+## C. Post-regen failure (used by all four skills with generation)
+
+Triggered when `muggle-local-execute-test-generation` (or the remote equivalent) returns `failed`, exit 26, `goal_not_achievable`, or any other non-passing terminal state.
+
+### Buckets
+
+| Bucket | Meaning |
+|---|---|
+| **transient** | Network blip, single LLM call failed, intermittent flake. Likely succeeds on retry without changing anything. |
+| **infra** | A Muggle Test bug stopped generation from progressing (handler crash, schema validation in our code, deterministic LLM-pipeline failure). |
+| **agent-course** | The generation agent went down a wrong path (chose the wrong button, misread the goal, looped on a blocking modal). The product is fine and the test case is fine — the agent's *course* needs steering. |
+| **product-uxux** | The product itself blocks the test (broken page, missing element, server error). Agent can't proceed because the feature doesn't actually work. |
+
+### Initial signal heuristics
+
+From `muggle-local-run-result-get` (summary, structured summary, last steps, error):
+
+- **transient**: `network-error`, `llm-rate-limit`, `single-tool-call-error`, run had partial progress then died.
+- **infra**: `electron-mcp-handler-crash`, `internal-validation-error`, `pipeline-stuck`, identical failure repeated more than twice.
+- **agent-course**: `goal_not_achievable` with summary mentioning the agent picked a different element, looped on a modal, kept trying the same wrong action; many steps but no real progress.
+- **product-uxux**: server 5xx in step screenshots, "page not found" reached repeatedly, expected element provably absent (visible in screenshot), product clearly broken in the artifact log.
+
+### Suggestions per bucket
+
+Present via `AskUserQuestion`. **Always show the run summary first** so the user has context, then offer the bucket's recommended action plus alternatives.
+
+| Bucket | Recommended suggestion | Other options |
+|---|---|---|
+| **transient** | Retry as-is. | muggle-feedback; Edit test case; Skip. |
+| **infra** | Report bug to Muggle AI → `muggle-feedback` with `category: "muggle-infra"` (run id, signals, summary excerpt). | Retry; Skip. |
+| **agent-course** | Steer the agent → invoke `muggle-feedback` skill so the user describes what should have happened; the workflow re-runs with the corrected course. | Retry; Edit test case; Skip. |
+| **product-uxux** | Wait for fix — share the run summary + screenshot to the dev. Offer email / SMS / file ticket (see "Sharing real defects" in section B). | Retry once the fix lands; muggle-feedback; Skip. |
+
+### Telemetry
+
+Same two-event pattern as section B, with `eventType` values `regen-failure-classified` and `regen-failure-resolved`. `aiClassification` is one of the four bucket strings; `userAction` is the user's pick.
+
+```json
+{
+  "eventType": "regen-failure-classified",
+  "skillName": "<this skill>",
+  "aiClassification": "transient" | "infra" | "agent-course" | "product-uxux",
+  "aiSuggestion": "retry" | "report-bug" | "muggle-feedback" | "wait-and-share",
+  "runId": "<local run id>",
+  "testCaseId": "<id>",
+  "projectId": "<id>",
+  "signals": ["goal_not_achievable", "loop-on-modal"],
+  "metadata": { "summary": "<excerpt>", "stepsCompleted": <n> }
+}
+```
+
+---
+
+## D. Emitting telemetry — implementation notes
+
+- Tool: `muggle-local-telemetry-event-emit` (local-only, fire-and-forget).
+- Sink: `~/.muggle-ai/telemetry/failure-events.jsonl` (one JSON record per line, append-only).
+- Never block the skill on a telemetry call. If the tool errors, log and continue.
+- Always emit the **classified** event before asking the user, and the **resolved** event immediately after the user picks. Don't merge them into one event after the fact — the *latency* between AI suggestion and user choice is also data.
+- For the pre-execution classifier (section A), the event has no separate "resolved" pair unless the user actively overrides; if they do, emit a single follow-up `pre-execution-classification` event with `userAction` set.
+
+## E. What this doc deliberately does not bake in
+
+- **Quantitative thresholds** beyond rule A.3 (30-day drift). Bucket signal lists above are an initial best guess; once telemetry has data, the user will refine which signals reliably indicate which bucket.
+- **Auto-retry**. There is no "if X then automatically rerun" path anywhere. The user decides every time — that's the whole point of the contract.
+- **Cross-bucket fallbacks**. If the AI mis-classifies, the user picks a different option from the AskUserQuestion list; the AI does not retry classification.

package/dist/plugin/skills/_shared/post-merge-cleanup.md

@@ -0,0 +1,10 @@
+# Cleanup After the Change Is Merged
+
+Gated by [`autoCleanup`](../muggle-preferences/preference-gates/autoCleanup.md). Follow the standard procedure in [`preference-gates/README.md`](../muggle-preferences/preference-gates/README.md). Fire only after the PR is **merged** — never while it's still open.
+
+On `always`, the four steps below run as one pre-authorized sequence (no per-step prompts). Stop on the first failure; do not force.
+
+1. `git worktree remove {worktreePath}` — only if a worktree was used.
+2. `git branch -d {branch}` then `git push origin --delete {branch}`.
+3. Clear `.muggle-ai/` session folders for this branch's runs and stale `/tmp/muggle-prepare-*.log` files. Cloud results stay.
+4. Invoke `commit-commands:clean_gone` via the `Skill` tool.

package/dist/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/dist/plugin/skills/_shared/rebase-before-e2e.md

@@ -0,0 +1,15 @@
+# Rebase Onto the Default Branch Before Dev Server / E2E
+
+Gated by [`autoRebase`](../muggle-preferences/preference-gates/autoRebase.md). Follow the standard procedure in [`preference-gates/README.md`](../muggle-preferences/preference-gates/README.md).
+
+**Fire only when `behind > 0`:**
+
+```bash
+git fetch origin
+default=$(git symbolic-ref refs/remotes/origin/HEAD --short | sed 's|origin/||')
+behind=$(git rev-list --count "HEAD..origin/${default}")
+```
+
+Pass `{behind}` and `{default}` to the picker prompts. On `always`, run `git rebase origin/${default}`; stop and report on conflicts — never auto-resolve.
+
+Stale branches produce false failures and false greens — that's why this gate exists.

package/dist/plugin/skills/_shared/telemetry-emit.md

@@ -0,0 +1,15 @@
+# Skill Telemetry — Shared Convention
+
+At the start of every `muggle-*` skill, call `muggle-local-telemetry-skill-emit` once. Fire-and-forget — never await, never let a telemetry failure block the skill.
+
+**Args:**
+
+- `skillName`: this skill's name (e.g. `"muggle-test"`)
+- `trigger`: one of
+  - `"user-slash"` — user typed `/<skill-name>` (the common case; default this)
+  - `"claude-proactive"` — Claude matched on the skill's description, not a slash command
+  - `"nested-skill"` — invoked from another skill via the `Skill` tool
+
+## Failure-mode events
+
+Skills that run replays or generations also emit structured failure-mode events through a separate tool — `muggle-local-telemetry-event-emit`. Don't reinvent the schema or sink in the skill; follow [`failure-mode-handling.md`](./failure-mode-handling.md), which defines the bucket taxonomies, the AI-classify → user-pick contract, and the exact event shape.

package/dist/plugin/skills/_shared/use-worktrees.md

@@ -0,0 +1,53 @@
+# Worktrees for Dev Work
+
+Use this for feature development, local validation, and PR iteration.
+
+## Core guidance
+
+- **One worktree per branch.** Never switch branches inside a long-lived checkout.
+- **Isolate runtime resources.** Parallel worktrees need unique ports and isolated mutable test state.
+- **Keep worktrees disposable.** Create for focused work, remove after merge.
+
+## Start new change work
+
+1. Update the base branch (usually `main`).
+2. Create a new worktree and branch:
+   ```bash
+   git worktree add <repo>-worktrees/<slug> -b <branch>
+   ```
+3. Install dependencies and run setup in that worktree.
+4. Keep all edits and commits for the change in that same worktree.
+
+## Test in the worktree
+
+- Run lint, typecheck, and unit/integration tests from the worktree.
+- Run your local E2E acceptance flow from that same worktree for user-facing validation.
+- Run the dev server from the same worktree so code, env, and cache all match.
+- In parallel runs, ensure each worktree has a unique port and isolated test data.
+
+## E2E + worktree checklist
+
+1. Confirm command cwd, checked-out branch, and server source are the same worktree.
+2. Start the app from that worktree and verify readiness first (see [`dev-server-readiness.md`](dev-server-readiness.md)).
+3. Run local E2E acceptance checks in that same session.
+4. Isolate test data across parallel branches (separate users/accounts/orgs or resettable fixtures).
+5. Re-run E2E acceptance checks after meaningful code changes during PR review.
+
+## Common failure modes to avoid
+
+- **Mixed checkouts:** Test command and server run from different directories.
+- **Port collision:** Multiple branches share a dev-server port.
+- **Shared mutable state:** Parallel runs mutate the same account or fixtures.
+- **Stale server:** Old process still serves previous branch code.
+
+## Pull request workflow
+
+1. Commit on the branch tied to the worktree.
+2. Push the branch and open the PR.
+3. Keep review fixes in that same worktree.
+4. Re-run relevant checks before each push, including E2E acceptance checks for user-facing changes.
+
+## Tear down
+
+After merge, remove the worktree.  
+See [`post-merge-cleanup.md`](post-merge-cleanup.md).

package/dist/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.