@muggleai/works 4.8.3 → 4.9.0

package/dist/plugin/skills/muggle-pr-visual-walkthrough/SKILL.md

@@ -17,6 +17,23 @@ This is the **canonical PR-walkthrough workflow** shared across every Muggle ent
 
 Rendering is always done by `muggle build-pr-section`, a battle-tested CLI that handles deterministic markdown layout, per-step screenshots, and automatic fit-vs-overflow (oversized content spills into a follow-up comment). Never hand-write the walkthrough markdown.
 
+## Preferences
+
+User preferences are available in the session context (injected at session start). Look for the line starting with `Muggle Preferences` — it contains key=value pairs like `autoLogin=ask showElectronBrowser=always ...`.
+
+If no preferences line is present, treat all preferences as `"ask"`.
+
+When you reach a decision gated by a preference:
+- **`always`** → proceed without asking the user
+- **`never`** → skip without asking the user  
+- **`ask`** → ask the user, then offer: "Want me to remember this choice for future sessions?" If yes, call `muggle-local-preferences-set` with the key, their chosen value, and scope `global`.
+
+This skill uses these preferences:
+
+| Preference | Decision it gates |
+|------------|------------------|
+| `postPRVisualWalkthrough` | Post visual walkthrough to PR |
+
 ## Input contract: the `E2eReport` JSON
 
 Every caller must build an `E2eReport` JSON object and have it in conversation context before invoking this skill. The schema is defined in `src/cli/pr-section/types.ts` (`E2eReportSchema`) and enforced by the CLI with Zod — malformed input exits non-zero with a descriptive stderr message.

package/dist/plugin/skills/muggle-preferences/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: muggle-preferences
+description: >-
+  View, set, or reset Muggle AI preferences that control testing behavior.
+  Use when user asks to see preferences, change a setting, configure Muggle
+  defaults, or manage muggle config. Triggers on: 'muggle preferences',
+  'show muggle settings', 'change muggle preference', 'set autoLogin to
+  always', 'muggle config', 'reset muggle preferences', 'show my muggle
+  settings', 'configure muggle'.
+---
+
+# Muggle Preferences
+
+View, set, or reset the preference knobs that control Muggle AI behavior.
+
+## Operations
+
+Parse the user's request to determine which operation to perform:
+
+- **List** — user wants to see current values (default when no specific change requested)
+- **Set** — user wants to change a specific preference
+- **Reset** — user wants to restore a preference (or all preferences) to defaults
+
+## List
+
+1. Read preferences from session context. Look for the line starting with `Muggle Preferences` — it contains key=value pairs like `autoLogin=ask showElectronBrowser=always ...`.
+
+   If no preferences line is present, treat all preferences as `"ask"` (the default).
+
+2. Present all 12 preferences in a table:
+
+```
+Muggle AI — Preferences
+
+| Preference               | Value  | Description                                              |
+|--------------------------|--------|----------------------------------------------------------|
+| autoLogin                | ask    | Reuse saved credentials without prompting                |
+| autoSelectProject        | ask    | Reuse last-used project for this repo                    |
+| showElectronBrowser      | ask    | Show browser window during local tests                   |
+| openTestResultsAfterRun  | ask    | Open results page on dashboard after local test          |
+| defaultExecutionMode     | ask    | Default to local or remote test execution                |
+| autoPublishLocalResults  | ask    | Upload local results to Muggle cloud                     |
+| suggestRelatedUseCases   | ask    | Suggest related use cases after creating/running one     |
+| suggestRelatedTestCases  | ask    | Suggest related test cases after creating/running one    |
+| autoDetectChanges        | ask    | Scan local git changes and map to affected test cases    |
+| postPRVisualWalkthrough  | ask    | Post visual walkthrough with screenshots to PR           |
+| checkForUpdates          | ask    | Check for newer Muggle version at session start          |
+| verboseOutput            | ask    | Show detailed progress logs during execution             |
+
+Values: always (proceed without asking) · ask (prompt each time) · never (skip without asking)
+Scope:  global (~/.muggle-ai/) or project (.muggle-ai/ in repo root)
+```
+
+## Set
+
+1. Parse the requested key and value from the user's message.
+
+2. Validate the key is one of: `autoLogin`, `autoSelectProject`, `showElectronBrowser`, `openTestResultsAfterRun`, `defaultExecutionMode`, `autoPublishLocalResults`, `suggestRelatedUseCases`, `suggestRelatedTestCases`, `autoDetectChanges`, `postPRVisualWalkthrough`, `checkForUpdates`, `verboseOutput`.
+
+   If the key is ambiguous or not recognized, show the full list and ask the user to clarify.
+
+3. Validate the value is one of: `always`, `ask`, `never`.
+
+4. Determine scope:
+   - Default to `global`.
+   - If the user says "for this project", "project-level", or "just this repo", use `project` scope and pass `cwd` as the current working directory.
+
+5. Call `muggle-local-preferences-set` with:
+   - `key`: The preference key
+   - `value`: The chosen value
+   - `scope`: `"global"` or `"project"`
+   - `cwd`: Current working directory (required when scope is `"project"`)
+
+6. Confirm: `Set {key} to {value} ({scope}).`
+
+## Reset
+
+1. If the user asks to reset a **specific key**: call `muggle-local-preferences-set` with `value: "ask"` for that key.
+
+2. If the user asks to reset **all preferences**: call `muggle-local-preferences-set` for each of the 12 keys with `value: "ask"`.
+
+3. Confirm what was reset.

package/dist/plugin/skills/muggle-status/SKILL.md

@@ -7,6 +7,23 @@ description: Check health of the Muggle AI installation. Use when user types mug
 
 Run a full health check and report results.
 
+## Preferences
+
+User preferences are available in the session context (injected at session start). Look for the line starting with `Muggle Preferences` — it contains key=value pairs like `autoLogin=ask showElectronBrowser=always ...`.
+
+If no preferences line is present, treat all preferences as `"ask"`.
+
+When you reach a decision gated by a preference:
+- **`always`** → proceed without asking the user
+- **`never`** → skip without asking the user  
+- **`ask`** → ask the user, then offer: "Want me to remember this choice for future sessions?" If yes, call `muggle-local-preferences-set` with the key, their chosen value, and scope `global`.
+
+This skill uses these preferences:
+
+| Preference | Decision it gates |
+|------------|------------------|
+| `checkForUpdates` | Check for newer Muggle version |
+
 ## Checks
 
 1. **Electron app** — read `~/.muggle-ai/electron-app/` to find the installed version directory. Read `.install-metadata.json` to get version and checksum. Verify the binary exists at the expected path. On macOS, check code signing with `spctl --assess --verbose`.
@@ -15,6 +32,8 @@ Run a full health check and report results.
 
 3. **Authentication** — call `muggle-remote-auth-status`. Report whether credentials are valid and when they expire.
 
+4. **CLI version** — capture installed (`muggle --version`) and latest (`npm view @muggleai/works version`). Compare with `sort -V`; flag as out-of-date only when latest is strictly greater.
+
 ## Output
 
 ```
@@ -23,8 +42,9 @@ Muggle AI — Status
 Electron app   [pass/fail]  version, binary status
 MCP server     [pass/fail]  responsive, auth state
 Authentication [pass/fail]  user, expiry
+CLI version    [pass/warn]  installed → latest
 
 [All systems operational / Issues found — run /muggle:muggle-repair to fix.]
 ```
 
-Use pass/fail indicators for each check. If any check fails, tell the user to run `/muggle:muggle-repair`.
+Use pass/fail indicators for each check. If any check fails, tell the user to run `/muggle:muggle-repair`. If the CLI version check warns (installed < latest), tell the user to run `/muggle:muggle-upgrade`.

package/dist/plugin/skills/muggle-test/SKILL.md

@@ -32,6 +32,28 @@ Every test case verifies exactly **one** user-observable behavior. Never bundle
 
 **Never skip the generate→review cycle.** Even when you are 100% confident about the right shape, always present the generated test cases to the user before calling `muggle-remote-test-case-create`. "I'll skip the generate→review cycle and create directly" is a sign you're about to get it wrong.
 
+## Preferences
+
+User preferences are available in the session context (injected at session start). Look for the line starting with `Muggle Preferences` — it contains key=value pairs like `autoLogin=ask showElectronBrowser=always ...`.
+
+If no preferences line is present, treat all preferences as `"ask"`.
+
+When you reach a decision gated by a preference:
+- **`always`** → proceed without asking the user
+- **`never`** → skip without asking the user  
+- **`ask`** → ask the user, then offer: "Want me to remember this choice for future sessions?" If yes, call `muggle-local-preferences-set` with the key, their chosen value, and scope `global`.
+
+This skill uses these preferences:
+
+| Preference | Decision it gates |
+|------------|------------------|
+| `autoLogin` | Reuse saved credentials when auth is required |
+| `autoSelectProject` | Reuse last-used Muggle project for this repo |
+| `autoDetectChanges` | Scan local git changes and map to affected test cases |
+| `defaultExecutionMode` | Default to local or remote test execution |
+| `autoPublishLocalResults` | Upload local results to Muggle cloud after run |
+| `postPRVisualWalkthrough` | Post visual walkthrough to PR after results are available |
+
 ## Step 1: Confirm Scope of Work (Always First)
 
 Parse the user's query and explicitly confirm their expectation. There are exactly two modes:
@@ -418,3 +440,7 @@ This skill always uses **Mode A** (post to an existing PR); `muggle-do` is the o
 - **Always publish before opening browser** — the dashboard needs the published data to show results
 - **Delegate PR posting to `muggle-pr-visual-walkthrough`** — never inline the walkthrough markdown or call `gh pr comment` directly from this skill; ask the user and hand off
 - **Can be invoked at any state** — if the user already has a project or use cases set up, skip to the relevant step rather than re-doing everything
+
+## Agent Dispatch
+
+When used in a multi-agent team (e.g., muggle-ai-teams), this skill is available through the **acceptance-tester** agent at `plugin/agents/acceptance-tester.md`. Orchestrators can dispatch it via `Agent()` instead of invoking this skill directly. The agent wraps this skill and four others (muggle-test-import, muggle-preferences, muggle-repair, muggle-status) and returns structured test results with blocking issues and suggested fixes for coding agents to act on.

package/dist/plugin/skills/muggle-test-feature-local/SKILL.md

@@ -22,6 +22,26 @@ The local URL only changes where the browser opens; it does not change the remot
 - **Selections** (project, use case, test case, script): Use `AskQuestion` with labeled options the user can click.
 - **Free-text inputs** (URLs, descriptions): Only use plain text prompts when there is no finite set of options. Even then, offer a detected/default value when possible.
 
+## Preferences
+
+User preferences are available in the session context (injected at session start). Look for the line starting with `Muggle Preferences` — it contains key=value pairs like `autoLogin=ask showElectronBrowser=always ...`.
+
+If no preferences line is present, treat all preferences as `"ask"`.
+
+When you reach a decision gated by a preference:
+- **`always`** → proceed without asking the user
+- **`never`** → skip without asking the user  
+- **`ask`** → ask the user, then offer: "Want me to remember this choice for future sessions?" If yes, call `muggle-local-preferences-set` with the key, their chosen value, and scope `global`.
+
+This skill uses these preferences:
+
+| Preference | Decision it gates |
+|------------|------------------|
+| `autoLogin` | Reuse saved credentials when auth is required |
+| `autoSelectProject` | Reuse last-used Muggle project for this repo |
+| `showElectronBrowser` | Show Electron browser window during local E2E tests |
+| `openTestResultsAfterRun` | Open results page on Muggle dashboard after run |
+
 ## Workflow
 
 ### 1. Auth
@@ -65,9 +85,20 @@ Prompt for projects: "Pick the project to group this test into:"
   2. `muggle-remote-use-case-create-from-prompts` with `projectId` and `instructions: ["<the user's natural-language instruction>"]` — persist. Use the created use case id and continue to test-case selection.
 - **Test case — Create new test case** (requires a chosen `useCaseId`): User provides an instruction describing what to test.
   1. `muggle-remote-test-case-generate-from-prompt` with `projectId`, `useCaseId`, `instruction` — **preview only** (server test-case prompt preview); show the returned draft(s); get confirmation via `AskQuestion`.
-  2. Persist the accepted draft with `muggle-remote-test-case-create`, mapping preview fields into the required properties (`title`, `description`, `goal`, `expectedResult`, `url`, etc.). Then continue from **section 4** with that `testCaseId`.
+  2. Persist the accepted draft with `muggle-remote-test-case-create`, mapping preview fields into the required properties (`title`, `description`, `goal`, `expectedResult`, `url`, etc.). Then continue from **section 5** with that `testCaseId`.
+
+### 3. Ensure Local Services Are Ready
+
+Before detecting the local URL, verify that the services the user needs are actually running. Use the `muggle:muggle-test-prepare` integration contract:
+
+1. Check if `/tmp/muggle-test-prepare.json` exists.
+2. If it exists, verify tracked PIDs are alive with `kill -0`.
+3. If all live → services are ready, proceed to Step 4 (Local URL).
+4. If the file is missing or has stale PIDs → invoke the `muggle:muggle-test-prepare` skill via the `Skill` tool to get services started. Once it completes, proceed to Step 4.
+
+This step is especially important when the user's app depends on sibling services (a backend API, an auth service, etc.) that may not be running yet. The prepare skill handles discovery, startup, and cleanup so this skill doesn't have to.
 
-### 3. Local URL
+### 4. Local URL
 
 Try to auto-detect the dev server URL by checking running terminals or common ports (e.g., `lsof -iTCP -sTCP:LISTEN -nP | grep -E ':(3000|3001|4200|5173|8080)'`). If a likely URL is found, present it as a clickable default via `AskQuestion`:
 - Option 1: "http://localhost:3000" (or whatever was detected)
@@ -77,14 +108,14 @@ If nothing detected, ask as free text: "Your local app should be running. What's
 
 Remind them: local URL is only the execution target, not tied to cloud project config.
 
-### 4. Existing scripts vs new generation
+### 5. Existing scripts vs new generation
 
 `muggle-remote-test-script-list` with `testCaseId`.
 
 - **If any replayable/succeeded scripts exist:** use `AskQuestion` to present them as clickable options. Show: name, created/updated, step count per option. Include **"Generate new script"** as the last option.
 - **If none:** go straight to generation (no need to ask replay vs generate).
 
-### 5. Load data for the chosen path
+### 6. Load data for the chosen path
 
 **Determine `freshSession`**
 
@@ -122,39 +153,39 @@ The MCP client often uses a **default wait of 300000 ms (5 minutes)** for `muggl
 - **`Electron execution timed out after 300000ms`:** Orchestration wait too short — see **`timeoutMs`** above.
 - **Exit code 26** (and messages like **LLM failed to generate / replay action script**): Often corresponds to a completed exploration whose **outcome was goal not achievable** (`goal_not_achievable`, summary with `halt`) — e.g. verifying "view script after a successful run" when **no run or script exists yet** in the UI. Use `muggle-local-run-result-get` and read the **summary / structured summary**; do not assume an Electron crash. **Fix:** choose a **project that already has** completed runs and scripts, or **change the test case** so preconditions match what localhost can satisfy (e.g. include steps to create and run a test first, or assert only empty-state UI when no runs exist).
 
-### 6. Execute (no approval prompt)
+### 7. Execute (no approval prompt)
 
 Call `muggle-local-execute-test-generation` or `muggle-local-execute-replay` directly. **Do not** ask the user to re-approve the Electron launch — the user choosing this skill in the first place is the approval. The browser defaults to visible; only pass `showUi: false` if the user explicitly asked for headless.
 
-### 7. After successful generation only
+### 8. After successful generation only
 
 - `muggle-local-publish-test-script`
 - Open returned `viewUrl` for the user (`open "<viewUrl>"` on macOS or OS equivalent).
 
-### 8. Report
+### 9. Report
 
 - `muggle-local-run-result-get` with the run id from execute.
 - Include: status, duration, pass/fail summary, per-step summary, artifact/screenshot paths, errors if failed, and script view URL when publishing ran.
 
-### 9. Offer to post a visual walkthrough to the PR
+### 10. Offer to post a visual walkthrough to the PR
 
-After reporting results, gather the required input and hand off to the shared **`muggle-pr-visual-walkthrough`** skill, which renders the walkthrough via `muggle build-pr-section` and posts it to the current branch's open PR.
+After reporting results, gather the required input and hand off to the shared **`muggle:muggle-pr-visual-walkthrough`** skill, which renders the walkthrough via `muggle build-pr-section` and posts it to the current branch's open PR.
 
-#### 9a: Gather per-step screenshots
+#### 10a: Gather per-step screenshots
 
-The shared skill takes an **`E2eReport` JSON** that includes per-step screenshot URLs. After step 7 has called `muggle-local-publish-test-script` and you have the `testScriptId`:
+The shared skill takes an **`E2eReport` JSON** that includes per-step screenshot URLs. After step 8 has called `muggle-local-publish-test-script` and you have the `testScriptId`:
 
 1. Call `muggle-remote-test-script-get` with the `testScriptId`.
 2. Extract per step: `steps[].operation.action` and `steps[].operation.screenshotUrl`.
 3. Build the `steps` array: `[{ stepIndex: 0, action: "...", screenshotUrl: "..." }, ...]`.
-4. If the run failed, capture `failureStepIndex`, `error`, and the local `artifactsDir` from the run result in step 8.
+4. If the run failed, capture `failureStepIndex`, `error`, and the local `artifactsDir` from the run result in step 9.
 5. Populate `description` (test case title/description) and `useCaseName` (parent use case title) on the report entry — optional but strongly recommended; they drive the grouped overview and the per-test collapsible headers. Prefer values already in your conversation context from earlier steps (e.g. the test case you just created or selected, or the use case you confirmed); only call `muggle-remote-test-case-get` / `muggle-remote-use-case-get` for anything you don't already have.
 
 Assemble the `E2eReport`:
 
 ```json
 {
-  "projectId": "<projectId from step 2>",
+  "projectId": "<projectId from step 2 (Targets)>",
   "tests": [
     {
       "name": "<test case title>",
@@ -171,9 +202,9 @@ Assemble the `E2eReport`:
 }
 ```
 
-See the `muggle-pr-visual-walkthrough` skill for the full schema including the failed-test shape.
+See the `muggle:muggle-pr-visual-walkthrough` skill for the full schema including the failed-test shape.
 
-#### 9b: Ask the user
+#### 10b: Ask the user
 
 Use `AskQuestion`:
 
@@ -182,11 +213,11 @@ Use `AskQuestion`:
 - Option 1: "Yes, post to PR"
 - Option 2: "Skip"
 
-#### 9c: Invoke the shared skill in Mode A
+#### 10c: Invoke the shared skill in Mode A
 
-If the user chooses "Yes, post to PR", invoke the `muggle-pr-visual-walkthrough` skill via the `Skill` tool. With the `E2eReport` in context, the skill renders the markdown block via the CLI, finds the PR via `gh pr view`, posts `body` as a comment, posts the overflow `comment` only if the CLI emitted one, and confirms the PR URL to the user.
+If the user chooses "Yes, post to PR", invoke the `muggle:muggle-pr-visual-walkthrough` skill via the `Skill` tool. With the `E2eReport` in context, the skill renders the markdown block via the CLI, finds the PR via `gh pr view`, posts `body` as a comment, posts the overflow `comment` only if the CLI emitted one, and confirms the PR URL to the user.
 
-Always use **Mode A** (post to existing PR) from this skill. Never hand-write the walkthrough markdown or call `gh pr comment` directly — delegate to `muggle-pr-visual-walkthrough`.
+Always use **Mode A** (post to existing PR) from this skill. Never hand-write the walkthrough markdown or call `gh pr comment` directly — delegate to `muggle:muggle-pr-visual-walkthrough`.
 
 ## Non-negotiables
 
@@ -197,4 +228,4 @@ Always use **Mode A** (post to existing PR) from this skill. Never hand-write th
 - Replay: never hand-built or simplified `actionScript` — only from `muggle-remote-action-script-get`.
 - Use `AskQuestion` for every selection — project, use case, test case, script. Never ask the user to type a number.
 - Project, use case, and test case selection lists must always include "Create new ...". Include "Show full list" whenever the API returned at least one row for that step; omit "Show full list" when the list is empty (offer "Create new ..." only). For creates, use preview tools (`muggle-remote-use-case-prompt-preview`, `muggle-remote-test-case-generate-from-prompt`) before persisting.
-- PR posting is always optional and always delegated to the `muggle-pr-visual-walkthrough` skill — never inline the walkthrough markdown or call `gh pr comment` directly from this skill.
+- PR posting is always optional and always delegated to the `muggle:muggle-pr-visual-walkthrough` skill — never inline the walkthrough markdown or call `gh pr comment` directly from this skill.

package/dist/plugin/skills/muggle-test-import/SKILL.md

@@ -18,6 +18,26 @@ This skill migrates existing test artifacts into Muggle Test. It reads your sour
 structures them into use cases and test cases, gets your approval, then creates everything
 in a Muggle project via the API.
 
+## Preferences
+
+User preferences are available in the session context (injected at session start). Look for the line starting with `Muggle Preferences` — it contains key=value pairs like `autoLogin=ask showElectronBrowser=always ...`.
+
+If no preferences line is present, treat all preferences as `"ask"`.
+
+When you reach a decision gated by a preference:
+- **`always`** → proceed without asking the user
+- **`never`** → skip without asking the user  
+- **`ask`** → ask the user, then offer: "Want me to remember this choice for future sessions?" If yes, call `muggle-local-preferences-set` with the key, their chosen value, and scope `global`.
+
+This skill uses these preferences:
+
+| Preference | Decision it gates |
+|------------|------------------|
+| `autoLogin` | Reuse saved credentials when auth is required |
+| `autoSelectProject` | Reuse last-used Muggle project for this repo |
+| `suggestRelatedUseCases` | Suggest related use cases after import |
+| `suggestRelatedTestCases` | Suggest related test cases after import |
+
 ## Concepts
 
 - **Use case**: A high-level feature or user workflow (e.g., "User Registration", "Checkout Flow")

package/dist/plugin/skills/muggle-test-prepare/SKILL.md

@@ -0,0 +1,276 @@
+---
+name: muggle-test-prepare
+description: "Make sure dev servers and sibling services are ready on the user's machine before running E2E acceptance tests. Checks which services need to be running, discovers sibling directories by folder name, verifies what's already listening, and offers to start anything that's missing — with the user's approval at every step. Use this skill whenever the user needs to prepare their local environment for E2E testing, verify their services are up, get their local dev stack ready, or when other muggle skills detect that required services are not listening on common ports. Triggers on: 'prepare for testing', 'make sure my services are running', 'check my local env', 'get ready for tests', 'are my services up', 'prepare local environment', 'spin up services', 'set up for E2E', 'verify my setup'. Also use when muggle-test, muggle-do, or muggle-test-feature-local need services running."
+---
+
+# Muggle Test Prepare
+
+Make sure the local services a user needs for E2E acceptance testing are up and ready. Check what's already running, discover sibling service directories by folder name, and offer to start anything that's missing — always with the user in control.
+
+Some users start their own services (tmux scripts, docker-compose, a terminal per service). Others want help launching them. This skill handles both: it verifies readiness first, and only offers to start things when something is missing.
+
+## Privacy Boundary
+
+This skill touches the user's local machine — processes, ports, directories outside the current repo. Every action is explicit and confirmed.
+
+- **Folder names are public.** You may list directory names in a parent folder to discover sibling services.
+- **File contents are private until confirmed.** Never read files inside a directory the user hasn't explicitly identified as a service to start. Once confirmed, you may inspect only top-level project indicator files (`package.json`, `Makefile`, `Cargo.toml`, `go.mod`, `pyproject.toml`, `docker-compose.yml`) to determine the start command.
+- **Never traverse upward more than one level** from the current working directory to list folders.
+
+## PID Tracking
+
+All launched processes are tracked in `/tmp/muggle-test-prepare.json`:
+
+```json
+{
+  "session_started": "2025-01-15T10:30:00Z",
+  "testing_scope": "frontend",
+  "excluded_services": [
+    {"name": "payment-gateway", "reason": "Needs production certificates"}
+  ],
+  "services": [
+    {
+      "name": "backend-api",
+      "dir": "/Users/user/Github/backend-api",
+      "command": "npm run dev",
+      "pid": 12345,
+      "port": 3001,
+      "log": "/tmp/muggle-prepare-backend-api.log"
+    }
+  ]
+}
+```
+
+The `testing_scope` field records what the user is testing (from Step 1). The `excluded_services` field records services the user said can't run locally (from Step 2), so other skills understand what's intentionally absent vs. forgotten.
+
+**On every invocation**, check this file first. If it exists with live PIDs (verify with `kill -0`), present the running services and ask:
+
+Use `AskQuestion`:
+- Option 1: "Keep them running — skip to testing"
+- Option 2: "Tear down and start fresh"
+- Option 3: "Add more services to the running set"
+
+Prune any dead PIDs silently (the process crashed on its own — no point asking about it).
+
+## Workflow
+
+### Step 1: What Are You Testing?
+
+Before discovering services, understand the shape of the testing so you can scope correctly. Use `AskQuestion`:
+
+> "What are you testing locally?"
+
+- Option 1: "A frontend feature — I need the UI and its backend dependencies running"
+- Option 2: "A backend API — I just need the API server running"
+- Option 3: "The full stack — everything needs to be up"
+
+This scopes the rest of the workflow. If the user is testing a backend API, they probably don't need a frontend dev server. If they're testing a frontend feature, they need the frontend plus whatever backends it talks to. Keep this answer in mind when presenting service candidates in Step 3 — pre-check the ones that match and leave the rest unchecked.
+
+### Step 2: Viability Check
+
+Some services can't run on a developer's machine by design — they need production secrets, HSMs, specific certificates, or cloud-only infrastructure. Don't waste time trying to discover or start them.
+
+**If the user already volunteered this information** in their initial message (e.g., "the payment-gateway can't run locally"), acknowledge it and skip the question — don't re-ask what they already answered.
+
+Otherwise, use `AskQuestion`:
+
+> "Are there any services in your stack that **can't** run locally? (e.g., needs production secrets, specific certificates, or cloud-only infra)"
+
+- Option 1: "All my services can run locally"
+- Option 2: "Some can't — I'll tell you which"
+
+If the user picks option 2, collect the names. Acknowledge them and exclude from discovery.
+
+If an excluded service is a hard dependency for the app under test, **suggest testing in a preview/staging environment instead** — the user can merge first and use `/muggle-test` in remote mode, where everything is already up and running. Frame it as an alternative, not a dead end:
+
+> "Since **payment-gateway** can't run locally, you might get better coverage by merging and running `/muggle-test` against your preview environment — everything's wired up there. Want to continue with a partial local setup, or switch to remote testing?"
+
+- Option 1: "Continue locally — I'll work around the missing service"
+- Option 2: "Switch to remote — I'll merge and test on preview"
+
+If the user chooses remote, hand off to `/muggle-test` in remote mode and exit this skill.
+
+### Step 3: Identify Required Services & How to Start Them
+
+Figure out which services need to be running. Start by listing folder names in the **parent directory** of the current working directory — these are the most likely candidates.
+
+```bash
+ls -d "$(dirname "$PWD")"/*/ | xargs -I{} basename {}
+```
+
+Present folder names only (not contents) as candidates. Use `AskQuestion` with `multiSelect: true`:
+
+> "Which of these need to be running for your tests?"
+
+List each folder name as an option. Pre-check the ones that match the testing scope from Step 1 (e.g., if testing a frontend feature, pre-check the frontend and likely backends). Always include these fixed tail options:
+- "Just the current project (no other services needed)"
+- "None of these — I'll tell you what I need"
+
+If the user provides manual paths, verify they exist before continuing. If a path doesn't exist, report it and ask for correction.
+
+**Include the current working directory as a candidate** — the user might be editing the backend but also need the frontend (a sibling) started, or vice versa.
+
+**Immediately after the user selects services**, ask how they want to handle startup. This avoids making someone who prefers their own scripts wait through command detection before they get to say "I'll handle it."
+
+Use `AskQuestion`:
+
+> "How do you want to handle these?"
+
+- Option 1: "Check what's running, start what's missing for me"
+- Option 2: "I'll start them myself — just verify they're up when I'm done"
+
+If the user picks **option 2**: skip Steps 4-6. Wait for them to confirm they're ready, then go straight to Step 4 (Check What's Already Running) to verify everything is listening, and report readiness (Step 7).
+
+If the user picks **option 1**: proceed through Steps 4-7 as normal.
+
+### Step 4: Check What's Already Running
+
+Before offering to start anything, check what's already listening on common dev ports:
+
+```bash
+lsof -iTCP -sTCP:LISTEN -nP 2>/dev/null | grep -E ':(3000|3001|3002|4200|5173|5174|8080|8081|8000|8888|4000|9000)'
+```
+
+Cross-reference against the selected service directories. If a selected service appears to already be running (match by port or by the process's working directory), report it as ready:
+
+> "**backend-api** is already listening on port 3001 (PID 54321) — looks good."
+
+If **all** required services are already running, report readiness and skip straight to Step 7. No need to go through Steps 5-6.
+
+If some are running and some aren't, acknowledge the running ones and continue to Step 5 only for the missing services. Use `AskQuestion` for any already-running service the user might want restarted:
+- Option 1: "It's fine, keep it"
+- Option 2: "Restart it"
+
+For services that are already running and the user wants to keep, add them to the PID tracking file so cleanup can find them later, but mark them as `external: true` so cleanup knows not to kill them (the user started them independently).
+
+### Step 5: Determine Start Commands
+
+For each required service that isn't already running, figure out how to start it. Propose the command so there's a shared understanding.
+
+Read **only** the indicator file that exists — don't read additional files.
+
+**Detection order:**
+
+| Indicator | Stack | Default command | What to check |
+|:----------|:------|:----------------|:--------------|
+| `package.json` | Node.js | `npm run dev` | Read `scripts` field: prefer `dev` > `start` > `serve` |
+| `Makefile` | Various | `make dev` | Just check existence; propose `make dev` or `make run` |
+| `Cargo.toml` | Rust | `cargo run` | Just check existence |
+| `go.mod` | Go | `go run .` | Just check existence |
+| `pyproject.toml` | Python | Check for framework | Read `[project.scripts]` or `[tool.poetry.scripts]` if present |
+| `requirements.txt` | Python | `python app.py` | Just check existence |
+| `docker-compose.yml` | Docker | `docker compose up` | Just check existence |
+
+If no indicator file is found, tell the user and ask them to provide the start command manually.
+
+**Present all proposed commands in a single summary:**
+
+```
+Service              Directory                          Command
+────────────────────────────────────────────────────────────────
+backend-api          ~/Github/backend-api               npm run dev
+auth-service         ~/Github/auth-service              go run .
+frontend             ~/Github/frontend                  npm run dev
+────────────────────────────────────────────────────────────────
+```
+
+Use `AskQuestion`:
+- Option 1: "Looks good, start them"
+- Option 2: "I need to edit some commands"
+
+If the user needs edits, collect corrections and re-present.
+
+### Step 6: Start Services
+
+For each service, launch in the background:
+
+```bash
+cd "<service-dir>" && nohup <command> > /tmp/muggle-prepare-<service-name>.log 2>&1 &
+echo $!
+```
+
+Capture the PID. Write all service entries to `/tmp/muggle-test-prepare.json`.
+
+**Startup verification** — after a short pause (~3-5 seconds per service), check:
+
+1. PID is alive: `kill -0 <pid> 2>/dev/null`
+2. Port is listening (if known): `lsof -iTCP:<port> -sTCP:LISTEN -nP 2>/dev/null`
+
+If a service's PID dies immediately, read the last 20 lines of its log and show the user:
+
+> "**backend-api** exited right after starting. Here's the tail of its log:"
+
+Then ask how to proceed:
+- Option 1: "Skip it and continue with the others"
+- Option 2: "Let me fix it — I'll re-invoke later"
+
+**Port discovery** — if the port isn't known upfront, after the service starts, re-scan listening ports and try to identify which new port appeared. Record it in the tracking file if found. If not found within ~10 seconds, note the port as unknown — the service may take longer to boot.
+
+### Step 7: Report Readiness
+
+Whether you started the services or the user did, confirm that everything is listening:
+
+```
+Service              PID      Port     Status
+──────────────────────────────────────────────
+backend-api          12345    3001     Running
+auth-service         12346    8080     Running
+frontend             12347    3000     Running
+──────────────────────────────────────────────
+All 3 services verified. Ready for E2E testing.
+```
+
+If you launched the services, also show:
+```
+Logs: /tmp/muggle-prepare-*.log
+Cleanup: say "stop services" or re-invoke this skill.
+```
+
+## Cleanup
+
+Cleanup is triggered when:
+- The user says "stop services", "tear down", "clean up", or "I'm done testing"
+- Another skill signals that a test run is complete
+- This skill is re-invoked and the user chooses "tear down and start fresh"
+
+**Cleanup steps:**
+
+1. Read `/tmp/muggle-test-prepare.json`
+2. Skip any services marked `external: true` (the user started them independently)
+3. For each managed service, send `SIGTERM`: `kill <pid>`
+4. Wait ~2 seconds, verify with `kill -0`
+5. If still alive, `kill -9 <pid>`
+6. Remove log files: `rm -f /tmp/muggle-prepare-*.log`
+7. Remove the tracking file: `rm -f /tmp/muggle-test-prepare.json`
+
+Report:
+
+```
+Stopped 3 services:
+  backend-api    (PID 12345)
+  auth-service   (PID 12346)
+  frontend       (PID 12347)
+```
+
+## Integration Contract (for other skills)
+
+When `muggle-test`, `muggle-do`, or `muggle-test-feature-local` want to check if services are ready:
+
+1. Check if `/tmp/muggle-test-prepare.json` exists
+2. Verify PIDs are alive with `kill -0`
+3. If all live → services are ready, proceed to test execution
+4. If missing or stale → invoke `muggle-test-prepare`
+
+After a test run completes, the calling skill can invoke cleanup by re-invoking this skill with cleanup intent, or leave services running for the next run (the user chose lifecycle management, not clean-state resets).
+
+## Guardrails
+
+- **Verify first, offer to start second** — always check what's already running before proposing to start anything. If everything is up, just confirm readiness and move on.
+- **The user may prefer to start services themselves** — always offer that option. Some developers have their own startup scripts, tmux layouts, or docker-compose setups they'd rather use.
+- **Never start a process the user didn't approve** — every command is presented and confirmed before execution.
+- **Never read file contents outside confirmed directories** — folder names are discoverable; file contents require explicit user selection.
+- **Never leave orphan processes untracked** — every background PID goes into the tracking file.
+- **Never kill a process the user started independently** — services marked `external: true` survive cleanup.
+- **Never assume start commands** — always verify by checking project indicator files; always confirm with the user.
+- **Bail early on non-viable services** — don't attempt to start something the user said can't run locally.
+- **Idempotent** — if services are already tracked and alive, offer to keep them rather than double-starting.