@muggleai/works 4.10.0 → 4.11.0

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

@@ -0,0 +1,134 @@
+---
+name: muggle-do-task
+description: Run a browser automation task on a website using natural language. Finds or creates the Muggle Test project, use case, test case, and script, then executes locally via the electron app. Use when the user wants to perform an action on a website (post, fill a form, click through a flow) rather than implement a code change.
+---
+
+# Muggle Test Task Runner
+
+> Telemetry first step: see [`_shared/telemetry-emit.md`](../_shared/telemetry-emit.md). Use `skillName: "muggle-do-task"`.
+
+Runs a browser automation task described in plain English. Finds or creates the necessary Muggle Test entities automatically, then executes locally with mutation-driven step prediction.
+
+## Step 1 — Parse the prompt
+
+From `$ARGUMENTS`, extract:
+
+- **`domain`** — the target website domain (e.g., `x.com`, `amazon.com`, `localhost:3000`). Normalize: strip `www.`, strip `https://`, lowercase. Result: bare domain with no scheme, no trailing slash.
+- **`useCaseName`** — the core action being performed, stripped of variable content (e.g., `"Publish a post"`, `"Add to cart"`, `"Submit a form"`).
+- **`mutations`** — variable parameters as a `string[]` (JSON array of strings). Each string is either:
+  - A plain-English instruction describing what varies this run (e.g., `"The post content should be 'Hello world'"`)
+  - A local file path for uploads (e.g., `"Attach the image at C:\\Users\\stan4\\Pictures\\photo.jpg"`)
+  
+  Examples: `["The post content should be 'Hello world'"]`, `["Attach the image at C:\\Users\\stan4\\photo.jpg", "Caption should be 'My photo'"]`
+- **`localUrl`** — the full URL to test against (e.g., `https://x.com`, `http://localhost:3000`). For external sites, use `https://<domain>`. For local dev servers, use the port the user's app is running on.
+
+If the prompt is ambiguous and you cannot confidently extract these, ask one clarifying question before proceeding.
+
+## Step 2 — Find or create Project
+
+Load and call `muggle-remote-project-list`. Find a project whose URL contains `domain` (case-insensitive substring match).
+
+**If found:** use it. Tell the user: `Found project: <name>`.
+
+**If not found:** call `muggle-remote-project-create` with:
+- `projectName`: `<domain>`
+- `description`: `E2E acceptance testing project for <domain>`
+- `url`: `https://<domain>`
+
+Tell the user: `Created project: <name>`.
+
+## Step 3 — Find or create Use Case
+
+Load and call `muggle-remote-use-case-list` filtered by `projectId`. Fuzzy-match against `useCaseName`:
+- Case-insensitive
+- Strip punctuation
+- Match if either string is a substring of the other
+
+If multiple candidates, pick the closest and tell the user which was selected.
+
+**If not found:** call `muggle-remote-use-case-create-from-prompts` with:
+- `projectId`: from Step 2
+- `instructions`: `["<original prompt>"]`
+
+Use the first result. Capture its `id` as `useCaseId`. If the result is empty or the call fails, stop and tell the user: "Could not create use case — try rephrasing the task description."
+
+Tell the user: `Created use case: <title>`.
+
+## Step 4 — Find or create Test Case
+
+Load and call `muggle-remote-test-case-list-by-use-case` with `useCaseId`. Filter for test cases where `status` equals `ACTIVE`.
+
+**If not found:** call `muggle-remote-test-case-create` with:
+- `projectId`: from Step 2
+- `useCaseId`: from Step 3
+- `title`: `<useCaseName>`
+- `description`: `Test case for: <original prompt>`
+- `goal`: `Successfully complete: <useCaseName>`
+- `expectedResult`: `The action completes without error`
+- `url`: `https://<domain>`
+
+Tell the user: `Created test case: <id>`.
+
+## Step 5 — Find active Test Script
+
+Load and call `muggle-remote-test-script-list` with:
+- `projectId`: from Step 2
+- `testCaseId`: from Step 4
+
+Tell the user which mutations will be applied: `Mutations: <mutations[]>` (or "no mutations" if empty).
+
+Filter for scripts where `status` equals `ACTIVE` or `PUBLISHED`. If all returned scripts have another status (`DRAFT`, `GENERATION_PENDING`, `FAILED`), treat as "no active script" and proceed to Phase 1.
+
+---
+
+### Phase 1 — No active script: generate locally
+
+1. Load and call `muggle-remote-test-case-get` with the test case ID from Step 4. This returns the full test case object needed by the local execution tool.
+
+2. Load and call `muggle-local-execute-test-generation` with:
+   - `testCase`: the full object from step 1 above
+   - `localUrl`: from Step 1
+   - `mutations`: the `mutations[]` array from Step 1 (omit if empty)
+
+3. Tell the user:
+> Script generation is running in the Muggle Test window. Once complete, run `/muggle-do "<original prompt>"` again to execute the task.
+
+Do not proceed further.
+
+---
+
+### Phase 2 — Active script found: replay with mutations
+
+## Step 6 — Fetch Action Script
+
+1. Load and call `muggle-remote-test-script-get` with the script ID from Step 5. Extract `actionScriptId`. If `actionScriptId` is missing or null, stop and tell the user: "The script record is incomplete — it may still be generating. Try again in a moment."
+
+2. Load and call `muggle-remote-action-script-get` with `actionScriptId`.
+
+Tell the user: `Executing task...`
+
+## Step 7 — Execute locally
+
+Load and call `muggle-local-execute-replay` with:
+- `testScript`: the full object from Step 6 (from `muggle-remote-test-script-get`)
+- `actionScript`: the content from Step 6 (from `muggle-remote-action-script-get`)
+- `localUrl`: from Step 1
+- `mutations`: the `mutations[]` array from Step 1 (omit if empty)
+
+Tell the user:
+> Running **[useCaseName]** on [domain]. Watch the Muggle Test window — it will execute the task with your parameters applied.
+
+## Step 8 — Route failures through the failure-mode handler
+
+If Phase 1 generation or Phase 2 replay returns `failed` or any non-passing terminal state, follow [`_shared/failure-mode-handling.md`](../_shared/failure-mode-handling.md):
+
+- **Phase 1 (generation) failure** → section C (buckets: `transient` / `infra` / `agent-course` / `product-uxux`).
+- **Phase 2 (replay) failure** → section B (buckets: `infra` / `stale-script` / `product-defect`).
+
+Steps:
+1. Read the run via `muggle-local-run-result-get` and extract signals per the heuristics in the shared doc.
+2. Emit `regen-failure-classified` or `replay-failure-classified` via `muggle-local-telemetry-event-emit` **before** asking the user.
+3. Present the recommended action via `AskUserQuestion` with the alternatives the shared doc lists for that bucket.
+4. After the user picks, emit the matching `*-resolved` event with `userAction`.
+
+If the user picks `muggle-feedback` from any bucket's options, invoke the `muggle-feedback` skill via the `Skill` tool with the `runId`. Skip silently on clean success.

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

@@ -0,0 +1,39 @@
+---
+name: muggle-feedback
+description: Capture feedback on a generated Muggle Test action script — either step-level or whole-script — and submit it so the system can analyze it and regenerate affected scripts. Use when the user has just run a Muggle Test (local or remote) and wants to flag what went wrong, when they paste a Muggle dashboard URL with a test script or run, or when they want to view or delete previously submitted feedback. Triggers on: '/muggle-feedback', 'give feedback on this run', 'the test was wrong', 'step N didn't work', 'the script clicked the wrong button', 'flag this run', 'the summary is wrong', 'show my feedback', 'list feedback', 'delete that feedback'. Skill auto-detects the run context from a recent local run, a remote run, or a Muggle dashboard URL in the prompt.
+---
+
+# Muggle Test Feedback
+
+> Telemetry first step: see [`_shared/telemetry-emit.md`](../_shared/telemetry-emit.md). Use `skillName: "muggle-feedback"`.
+
+Capture user feedback on what a generated Muggle Test action script did wrong. The server uses each feedback row to find similar test cases via LLM and regenerate their scripts in the background.
+
+## Routing
+
+Pick the operation, then read its op file for the procedure.
+
+| Intent | Op file |
+|---|---|
+| "give feedback on this run" / "the test was wrong" / "step N didn't work" / a Muggle dashboard URL in the prompt / chained from another skill | [`ops/submit.md`](ops/submit.md) |
+| "show my feedback" / "list feedback for this project" / "what feedback have I filed" | [`ops/list.md`](ops/list.md) |
+| "delete that feedback" / "remove feedback for X" | [`ops/delete.md`](ops/delete.md) |
+
+If intent is ambiguous, use `AskUserQuestion` once with options **Submit / List / Delete** — never ask the user to type a clarification in plain text.
+
+## Constraints (all ops)
+
+- **Feedback attaches to a cloud action-script id.** A local run that has not yet been uploaded to the cloud has no such id. Submit must upload the run first if needed.
+- **Feedback target is one of two shapes:**
+  - **Whole script** — `target.targetType = "actionScript"`, `target.targetId = <actionScriptId>`.
+  - **One specific step** — `target.targetType = "step"`, `target.targetId = "<actionScriptId>:<stepIndex>"` where `stepIndex` is **0-based** on the wire even though steps are shown to the user 1-based.
+- **Project scope.** All ops scope to the user's last-used project (`muggle-local-last-project-get`). If unset, ask once and persist via `muggle-local-last-project-set` so subsequent ops in this session reuse it.
+- **`feedbackText` must be non-empty.** Re-prompt the user if they leave it blank.
+
+## Non-negotiables (all ops)
+
+- Use `AskUserQuestion` for every selection (project, test case, run, target type, which step(s), confirm). Step selection must be a clickable picker built from the rendered steps (see [`ops/submit.md`](ops/submit.md) §3b) — never ask the user to type a number.
+- Always render the run's steps and summary (§2) **before** collecting feedback — users can only point at what they can see.
+- Convert step numbers between 1-based (rendered to user) and 0-based (wire format) at the boundary. Never expose 0-based indices to the user.
+- One MCP submit/delete call per feedback piece — never batch into a single call.
+- Surface the `feedbackAnalysisWorkflowRuntimeId` returned by submit so the user knows regeneration is running. Do not poll it from this skill.

package/plugin/skills/muggle-feedback/ops/delete.md

@@ -0,0 +1,49 @@
+# Delete feedback
+
+Soft-delete a feedback entry. Always confirm with the user before deleting — this is a write the user cannot undo from this skill.
+
+## 1. Identify the feedback
+
+Three paths:
+
+- **Explicit id** — user named the feedback id (e.g. "delete feedback `abcd-1234-...`"). Use it.
+- **Recently shown id** — the user is referring to a row from a list rendered earlier in the conversation. Resolve from that context.
+- **No id given** — run [`list.md`](list.md) first to surface entries; offer "Delete one" as the next-action; the user picks.
+
+## 2. Show what will be deleted
+
+Print:
+
+```
+Feedback: <id>
+Target:   <Whole script | Step N>
+Test case: <title>
+Created:  <human-readable>
+Text:
+  <full feedbackText, indented>
+```
+
+## 3. Confirm
+
+`AskUserQuestion`:
+
+> "Delete this feedback?"
+> - **Delete** — proceed
+> - **Cancel** — abort
+
+If the user cancels, print "Cancelled — feedback kept." and stop.
+
+## 4. Soft-delete
+
+`muggle-remote-user-feedback-delete` with the feedback id.
+
+## 5. Report
+
+On success: `✓ Deleted feedback <id>.`
+
+On failure: print the error verbatim. If the error is "not found", inform the user the entry was likely already deleted and continue gracefully.
+
+## Non-negotiables
+
+- Never delete without an explicit confirm step, even if the user said "delete X" in their original prompt — the confirm shows what they're actually deleting.
+- One delete call per invocation. No bulk delete in v1.

package/plugin/skills/muggle-feedback/ops/list.md

@@ -0,0 +1,65 @@
+# List feedback
+
+Show feedback the user has filed. The user usually wants feedback on a specific test case (or test script, or use case) — not the whole project — so the skill picks a scope first.
+
+## 1. Scope to a project
+
+Read `muggle-local-last-project-get`. If set, use it.
+
+If unset: `muggle-remote-project-list` and pick via `AskUserQuestion` (top 5 by recency, plus "Show full list"). Persist with `muggle-local-last-project-set`.
+
+## 2. Pick a narrowing scope
+
+Ask once via `AskUserQuestion` — the list tool accepts at most one narrowing filter:
+
+> "What feedback do you want to see?"
+> - **A specific test case** (most common)
+> - **A specific test script**
+> - **A specific use case**
+> - **All in this project**
+
+If the user came from a chained skill or from a recent run, default to the matching narrowing scope and skip this question.
+
+## 3. Resolve the filter id
+
+- **Test case** → `muggle-remote-test-case-list` with `projectId`, `AskUserQuestion`. Pass picked id as `testCaseId`.
+- **Test script** → first pick a test case (as above), then `muggle-remote-test-script-list` with `testCaseId`, `AskUserQuestion`. Pass as `testScriptId`.
+- **Use case** → `muggle-remote-use-case-list` with `projectId`, `AskUserQuestion`. Pass as `useCaseId`.
+- **All in project** → no narrowing param.
+
+Use relevance-first filtering on each picker: top 3-5 most relevant to the user's stated goal, plus "Show full list".
+
+## 4. Fetch
+
+`muggle-remote-user-feedback-list` with `projectId` and at most one of `actionScriptId` / `testScriptId` / `testCaseId` / `useCaseId`.
+
+If the response has zero entries, print "No feedback yet for `<scope description>`." and offer `AskUserQuestion` with **Submit new feedback / Done**.
+
+## 5. Render
+
+Markdown table sorted by `createdAt` (newest first):
+
+| # | Target | Test case | Excerpt | Created | Id |
+|---|---|---|---|---|---|
+
+- **Target** — "Whole script" or "Step N" (convert wire 0-based index to 1-based for display).
+- **Test case** — when the scope is `testCaseId` or `testScriptId`, all rows share the same test case (use the title from the picker). When the scope is `useCaseId` or project-wide, resolve per row by fetching `muggle-remote-test-script-list` once for each unique `actionScriptId` (cache in-memory) — or skip and show "Test case: …" if there are >20 unique scripts.
+- **Excerpt** — first 80 chars of `feedbackText`, single line.
+- **Created** — human-readable, e.g. `2 days ago`.
+- **Id** — feedback id, truncated to first 8 chars in the table; full id shown in the detail view.
+
+## 6. Offer next action
+
+`AskUserQuestion`:
+
+> "What next?"
+> - **View detail** — pick an entry, print full `feedbackText`, full ids, target, dashboard link if available.
+> - **Delete one** — hand off to [`delete.md`](delete.md).
+> - **Submit new feedback** — hand off to [`submit.md`](submit.md).
+> - **Done**
+
+## Non-negotiables
+
+- One narrowing filter only — never set more than one of `actionScriptId` / `testScriptId` / `testCaseId` / `useCaseId` in the same call.
+- Convert wire 0-based step indices to 1-based when rendering to the user.
+- Don't fetch test-case names per row eagerly past ~20 unique action scripts — make it opt-in.

package/plugin/skills/muggle-feedback/ops/submit.md

@@ -0,0 +1,130 @@
+# Submit feedback
+
+Resolve the action script being commented on, render it for review, collect feedback against one or more steps and/or the whole script, then submit each piece as its own server-side row.
+
+## 1. Resolve the action script (the "anchor")
+
+Pick the first applicable path. Stop at the first that yields an `actionScriptId`.
+
+### 1a. Dashboard URL in user's prompt
+
+A Muggle dashboard URL looks like `https://app.muggle-ai.com/muggleTestV0/dashboard/projects/<projectId>/...`. Scan the user's recent message for any `https://app.muggle-ai.com/...` URL.
+
+- Extract any UUID-shaped path segments. If `/projects/<uuid>` is present, capture as `projectId`. If `/test-scripts/<uuid>` is present, capture as `testScriptId`.
+- If a `testScriptId` was captured: call `muggle-remote-test-script-get` to get the script and read `actionScriptId` off it. Done — proceed to step 2.
+- If only a `projectId` was captured: use it as the project for path 1c and continue to picker.
+- If parsing yields nothing actionable: fall through to 1b.
+
+### 1b. Recent local run (chained or just-finished)
+
+If this skill was invoked by another skill (`muggle-test`, `muggle-test-feature-local`) the caller MUST pass the just-finished `runId` as context. If you have a `runId`:
+
+1. `muggle-local-run-result-get` with the `runId`.
+2. The result includes the test case context. If the run was already published (`muggle-local-publish-test-script` was called), the resulting `testScriptId` gives you the cloud `actionScriptId` via `muggle-remote-test-script-get`.
+3. **If the run was NOT published**, upload it first via `muggle-remote-local-run-upload` (passing the `runId`'s test case context and `actionScript` payload). Use the returned cloud `actionScriptId`.
+
+If no `runId` was passed but the user is plausibly continuing from a recent test:
+
+1. `muggle-local-list-sessions` and pick sessions completed in the last 10 minutes for the current project.
+2. If exactly one fresh session exists, offer it as the default via `AskUserQuestion` ("Feedback on the run from <X> minutes ago?" with **Yes / Pick a different run**).
+3. If multiple, present the top 3 via `AskUserQuestion` (most recent first).
+4. Once picked, follow the publish-or-upload path above.
+
+If neither chained nor recent fits, fall through to 1c.
+
+### 1c. Picker (project → test case → run)
+
+1. **Project.** Read `muggle-local-last-project-get`. If set, use it. Else `muggle-remote-project-list` with `AskUserQuestion` (top 5 by recency, plus "Show full list"). Persist the pick with `muggle-local-last-project-set`.
+2. **Test case.** `muggle-remote-test-case-list` with `projectId`, then `AskUserQuestion`. Top 5 by recency plus "Show full list". Rank by relevance if the user mentioned anything specific.
+3. **Run / script.** `muggle-remote-test-script-list` with `testCaseId`. Show via `AskUserQuestion` with: name + status + updatedAt. Top 5 by recency.
+4. `muggle-remote-test-script-get` on the picked one → note `actionScriptId`.
+
+## 2. Render the script for review
+
+Always render before asking for feedback — the user must see the steps to reference them by index.
+
+`muggle-remote-action-script-get` with the resolved `actionScriptId`.
+
+Print:
+
+- **Header** — project name, test case title, script name, status, run url (if available). For remote, include the dashboard link.
+- **Steps** — numbered list, **1-based**, in order:
+  - `Step <n>: <action label> on <element text or id> — <briefExplanation>`
+  - If `screenshotPath` is present (local) or `screenshotUrl` (remote), append `[screenshot: <path>]` so the user can open it manually.
+- **Summary** — print `summary` from the action script if present, else "No summary recorded".
+
+## 3. Collect feedback (batch)
+
+### 3a. Pick the scope (entity type)
+
+Use `AskUserQuestion` to scope which targets:
+
+> "Where is the problem?"
+> - One specific step
+> - Multiple steps
+> - The whole script's outcome / summary
+> - Multiple steps **and** the whole outcome
+
+### 3b. Pick the step(s) — clickable picker
+
+When 3a includes any step-level scope, present the rendered steps as a **clickable `AskUserQuestion` picker** — never as a typed number.
+
+- **Option format** — Label: `Step <n>: <action label> on <element text or id>` (≤80 chars). Description: the step's `briefExplanation` (≤120 chars).
+- **Multi-select** — `multiSelect: true` for "Multiple steps" or "Multiple steps and the whole outcome"; `multiSelect: false` for "One specific step".
+- **Long scripts (>10 steps)** — rank by keyword overlap with the user's prompt (label or briefExplanation); fall back to the first 10 if no match. Append **"Show all steps"** as a final option that re-asks with the full list — never silently truncate.
+
+For each selected step, prompt in plain text:
+
+> "What should step `<n>` have done instead?"
+
+For the whole-script scope, prompt:
+
+> "What's wrong with the overall outcome?"
+
+Validate each paragraph is non-empty (re-prompt if blank). Build an in-memory list of feedback pieces:
+
+```
+[
+  { kind: "step", stepNumber: 3, text: "..." },
+  { kind: "step", stepNumber: 7, text: "..." },
+  { kind: "actionScript",            text: "..." },
+]
+```
+
+Before submitting, re-confirm the full set with the user via `AskUserQuestion`:
+
+> "Submit these <N> feedback entries?" — **Submit / Edit / Cancel**.
+
+## 4. Submit
+
+For each piece, call `muggle-remote-user-feedback-create` once. Map fields:
+
+| Piece kind | `target.targetType` | `target.targetId` |
+|---|---|---|
+| Step `n` (1-based) | `"step"` | `` `${actionScriptId}:${n - 1}` `` (convert to 0-based) |
+| Whole script | `"actionScript"` | `actionScriptId` |
+
+Always pass `projectId` and `feedbackText`. Capture each response — note `feedback.id` and `feedbackAnalysisWorkflowRuntimeId` (may be undefined).
+
+If a single create call fails, log the error, continue with the rest, and report the failure at the end. Do not abort the batch.
+
+## 5. Report
+
+Print one line per submitted feedback in this shape:
+
+```
+✓ feedback <id> — <target description> [analysis runtime: <id>]
+```
+
+End with a one-line note:
+
+> "Regeneration runs in the background. Re-run this test case later to use the updated script."
+
+If any pieces failed, list them under a `Failed:` header with the error.
+
+## Non-negotiables
+
+- Always render the script (step 2) before collecting feedback.
+- One create call per feedback piece — never concatenate paragraphs across targets.
+- Convert step numbers from 1-based (UI) to 0-based (wire) at submit time.
+- If the user came from a non-uploaded local run, do the upload silently before submit; do not ask for permission for the upload itself.

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

@@ -0,0 +1,59 @@
+---
+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.
+disable-model-invocation: true
+---
+
+# Muggle PR Follow-up
+
+> 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.
+
+**Per-PR isolation.** One dispatch per PR, not per session. Multi-PR work runs N independent loops.
+
+## Input
+
+`$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.
+
+- 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.
+
+## Contract
+
+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.
+
+## Caller-supplied implementation cycle
+
+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`:
+
+```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.