@muggleai/works 4.12.1 → 4.12.3

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

@@ -43,266 +43,52 @@ All launched processes are tracked in `/tmp/muggle-test-prepare.json`:
 }
 ```
 
-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.
+`testing_scope` records what the user is testing (from [scope](./steps/scope.md)). `excluded_services` records services the user said can't run locally (from [viability-check](./steps/viability-check.md)).
 
-**On every invocation**, check this file first. If it exists with live PIDs (verify with `kill -0`), present the running services and ask:
-
-Use `AskUserQuestion`:
+**On every invocation**, check this file first. If it exists with live PIDs (verify with `kill -0`), `AskUserQuestion`:
 - 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).
+Prune dead PIDs silently.
 
 ## Preferences
 
 Gates run per [`preference-gates/README.md`](../muggle-preferences/preference-gates/README.md).
 
-| Preference | Step | Decision it gates |
-|------------|------|-------------------|
-| `autoRebase` | 0 | Rebase onto `origin/<default>` before starting dev servers (see [`_shared/rebase-before-e2e.md`](../_shared/rebase-before-e2e.md)) |
+| Preference | Gates |
+|------------|-------|
+| `autoRebase` | [rebase-check](./steps/rebase-check.md) — rebase onto `origin/<default>` before starting dev servers |
 
 ## Workflow
 
-### Step 0: Rebase check (gated by `autoRebase`)
-
-Fire per [`_shared/rebase-before-e2e.md`](../_shared/rebase-before-e2e.md) when `behind > 0`. Otherwise skip silently.
-
-### Step 1: What Are You Testing?
-
-Before discovering services, understand the shape of the testing so you can scope correctly. Use `AskUserQuestion`:
-
-> "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 `AskUserQuestion`:
-
-> "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 `AskUserQuestion` 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 `AskUserQuestion`:
-
-> "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
-
-Run port detection and (when the app declares a backend URL) backend-health probe per [`_shared/dev-server-readiness.md`](../_shared/dev-server-readiness.md). Cross-reference hits 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 `AskUserQuestion` 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).
-
-**Port already held** — when the user wants a port that is currently held by a process they did **not** select (typically a stale dev server from a sibling worktree). Surface the conflict via `AskUserQuestion`:
-
-> "Port 3999 is held by PID 87421 (you didn't select this process). How do you want to proceed?"
-
-- Option 1: "Use the next available port" (recommended — non-destructive)
-- Option 2: "Force-kill PID 87421 and claim port 3999"
-- Option 3: "Abort"
-
-**Option 1 — next available port:** probe `3999 + N` for `N = 1, 2, 3, ...` until `Test-NetConnection`/`lsof -i :<port>` returns nothing listening. Record the new port (and the env file edit, if `PORT=` is set in `.env.local` etc.) so downstream steps use it. The dev server may need a restart to pick up the new value.
-
-**Option 2 — force-kill (destructive):**
-- **Windows PowerShell:** `Get-NetTCPConnection -LocalPort <port> -ErrorAction SilentlyContinue | ForEach-Object { try { Stop-Process -Id $_.OwningProcess -Force -ErrorAction SilentlyContinue } catch { } }`
-- **POSIX:** `lsof -ti:<port> 2>/dev/null | xargs -r kill -9`
-
-Re-verify the port is free before continuing.
-
-### Step 4.5: Environment File Sanity
-
-The env file is **per-repo** — don't hardcode `.env.local`. Detect it: scan `package.json` `scripts/*` for `.env*` literals and known port vars (`PORT=`, `VITE_PORT=`); check framework config (`next.config.*`, `vite.config.*`).
-
-When a dependency on an env file exists:
-
-1. Check whether `<cwd>/<envfile>` exists. If yes, no-op.
-2. If absent, `git worktree list --porcelain` and check each sibling for the same filename.
-3. If found, surface via `AskUserQuestion`:
-
-   > "`<envfile>` is missing in this worktree but exists at `<sibling>/<envfile>`. Copy it before starting services?"
-
-   - Option 1: "Yes — copy from `<sibling>`"
-   - Option 2: "No — I'll provide it another way"
-
-4. If not found anywhere, report and ask how to proceed.
-
-Skip silently when no env file is referenced. The point is to catch the common worktree-bootstrap miss, not to mandate any specific file.
-
-### 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 `AskUserQuestion`:
-- 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 5.5: Fresh-Worktree Install Probe
-
-Before launching `npm run dev` (or equivalent) in a Node service, check whether `node_modules/` is present and current. Stale or missing `node_modules/` causes silent runtime failures that look like the service is broken when actually the install is just missing.
-
-For each Node service the user selected:
-
-1. If `<service-dir>/node_modules/` is missing entirely → install is required.
-2. If `<service-dir>/package-lock.json` is newer than `<service-dir>/node_modules/.package-lock.json` → install is stale.
-3. Otherwise → install is current, no action needed.
-
-When install is required or stale, propose via `AskUserQuestion`:
-
-> "`<service-name>` needs a fresh `npm install` before starting (node_modules is missing/stale). Run `npm install --prefer-offline --no-audit --no-fund` now?"
-
-- Option 1: "Yes — install now"
-- Option 2: "No — skip; I know it's fine"
-
-**Never symlink `node_modules/` from a sibling worktree.** webpack's `resolve.symlinks: true` default rewrites paths to the shared real location; asset-identity tracking fails with `Can't handle conflicting asset info for sourceFilename`. Run a real per-worktree install.
-
-For non-Node services (Go, Rust, Python), skip this probe — their build systems handle dependency caching differently.
-
-### 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** — first confirm the PID is alive (`kill -0 <pid> 2>/dev/null`), then run the two-stage readiness probe per [`_shared/dev-server-readiness.md`](../_shared/dev-server-readiness.md) against `/tmp/muggle-prepare-<service-name>.log`. Cap log-tail at 60s. Halt on whatever it surfaces; do not re-implement the ready-signal patterns here.
-
-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.
-```
+Run the stages in this order. The sequence number is display-only — it lives only in this table for at-a-glance ordering; detail files and cross-references use slugs. Each row links to its detail file; read the file when you reach the stage.
+
+| # | Stage | Summary |
+|:--|:------|:--------|
+| 1 | [rebase-check](./steps/rebase-check.md) | Rebase onto default branch (gated) |
+| 2 | [scope](./steps/scope.md) | Frontend / backend / full stack |
+| 3 | [viability-check](./steps/viability-check.md) | Exclude services that can't run locally |
+| 4 | [identify-services](./steps/identify-services.md) | Pick required services + startup mode |
+| 5 | [check-running](./steps/check-running.md) | Detect what's already listening |
+| 6 | [env-file](./steps/env-file.md) | Env file present + correct |
+| 7 | [start-commands](./steps/start-commands.md) | Determine per-service start command |
+| 8 | [fresh-install](./steps/fresh-install.md) | Auto-install deps if missing/stale |
+| 9 | [start-services](./steps/start-services.md) | Launch + two-stage readiness |
+| 10 | [smoke-test](./steps/smoke-test.md) | HTTP + body sniff + log tail; clean-restart on fail |
+| 11 | [readiness-report](./steps/readiness-report.md) | Final ready table |
 
 ## 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:**
+Triggered when the user says "stop services", "tear down", "clean up", "I'm done testing", another skill signals run complete, or this skill is re-invoked with "tear down and start fresh".
 
 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`
+2. Skip services marked `external: true`
+3. For each managed service: `kill <pid>` (SIGTERM)
+4. Wait ~2 s, verify with `kill -0`
+5. If still alive: `kill -9 <pid>`
+6. `rm -f /tmp/muggle-prepare-*.log`
+7. `rm -f /tmp/muggle-test-prepare.json`
 
 Report:
 
@@ -315,23 +101,21 @@ Stopped 3 services:
 
 ## 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`
+`muggle-test-feature-local`, `muggle-do`, and local-mode `muggle-test` MUST invoke this skill before any workflow step. Idempotent — fast exit when healthy. Treat success as short-lived; re-invoke if more than a few minutes pass before testing. Never bypass on "the user knows their stack is up" — that assumption is why this skill exists.
 
-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).
+After a test run, the caller can re-invoke for cleanup or leave services running for the next run.
 
 ## 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.
+- **Verify first, offer to start second** — check what's already running before proposing to start anything.
+- **The user may prefer to start services themselves** — always offer that option.
+- **Never start a process the user didn't approve.**
 - **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.
+- **Never kill a process the user started independently** — `external: true` survives cleanup.
+- **Never assume start commands** — verify via indicator file; confirm with user.
+- **Bail early on non-viable services** — don't start what can't run locally.
+- **Idempotent** — already-tracked alive services are kept; [smoke-test](./steps/smoke-test.md) still runs against them.
+- **Port-listening is never enough** — smoke-test (HTTP + body sniff + log tail) is mandatory before the final report.
+- **Clean Restart is the recommended fix** — first option in the smoke-test diagnose-and-fix loop; lint/build/missing-deps issues need nuke-and-reinstall.
+- **Fresh install is automatic** — [fresh-install](./steps/fresh-install.md) notifies, doesn't ask.

package/plugin/skills/muggle-test-prepare/steps/check-running.md

@@ -0,0 +1,31 @@
+# Check what's already running
+
+Run port detection and (when an app declares a backend URL) backend-health probe per [`../../_shared/dev-server-readiness.md`](../../_shared/dev-server-readiness.md). Cross-reference hits against selected service directories.
+
+> "**backend-api** is already listening on port 3001 (PID 54321) — looks good."
+
+If **all** required services are running, skip straight to [smoke-test](./smoke-test.md) — don't trust port-listening alone.
+
+If some are running, acknowledge and continue to [start-commands](./start-commands.md) only for the missing ones. For already-running services:
+- Option 1: "It's fine, keep it"
+- Option 2: "Restart it"
+
+Mark kept services as `external: true` in the tracking file so cleanup leaves them alone.
+
+## Port already held
+
+When the user wants a port held by a process they did **not** select (typically a stale dev server from a sibling worktree):
+
+> "Port 3999 is held by PID 87421 (you didn't select this process). How do you want to proceed?"
+
+- Option 1: "Use the next available port" (recommended — non-destructive)
+- Option 2: "Force-kill PID 87421 and claim port 3999"
+- Option 3: "Abort"
+
+**Option 1**: probe `3999 + N` for `N = 1, 2, …` until nothing listens. Record the new port and any env file edit (`PORT=` in `.env.local` etc.). Dev server may need restart to pick up.
+
+**Option 2 — force-kill (destructive):**
+- **Windows PowerShell:** `Get-NetTCPConnection -LocalPort <port> -ErrorAction SilentlyContinue | ForEach-Object { try { Stop-Process -Id $_.OwningProcess -Force -ErrorAction SilentlyContinue } catch { } }`
+- **POSIX:** `lsof -ti:<port> 2>/dev/null | xargs -r kill -9`
+
+Re-verify the port is free before continuing.

package/plugin/skills/muggle-test-prepare/steps/env-file.md

@@ -0,0 +1,18 @@
+# Environment file sanity
+
+The env file is **per-repo** — don't hardcode `.env.local`. Detect by scanning `package.json` `scripts/*` for `.env*` literals and known port vars (`PORT=`, `VITE_PORT=`); check framework config (`next.config.*`, `vite.config.*`).
+
+When a dependency on an env file exists:
+
+1. Check `<cwd>/<envfile>` exists — if yes, no-op.
+2. If absent, `git worktree list --porcelain` and check each sibling for the same filename.
+3. If found:
+
+   > "`<envfile>` is missing in this worktree but exists at `<sibling>/<envfile>`. Copy it before starting services?"
+
+   - Option 1: "Yes — copy from `<sibling>`"
+   - Option 2: "No — I'll provide it another way"
+
+4. If not found anywhere, report and ask.
+
+Skip silently when no env file is referenced.

package/plugin/skills/muggle-test-prepare/steps/fresh-install.md

@@ -0,0 +1,20 @@
+# Fresh install (clean-start default)
+
+Detect stack by indicator file, decide if install is missing/stale, run automatically (notify, don't ask). Only opt-out is aborting the skill.
+
+| Indicator | Stack | Stale check | Install command |
+|:----------|:------|:------------|:----------------|
+| `package.json` | Node | `node_modules/` missing OR `package-lock.json` newer than `node_modules/.package-lock.json` | `npm install --prefer-offline --no-audit --no-fund` |
+| `pyproject.toml` w/ `[tool.poetry]` | Poetry | `poetry.lock` newer than `.venv/pyvenv.cfg` (or `.venv/` missing) | `poetry install --no-interaction` |
+| `pyproject.toml` (PEP 621) + `uv.lock` | uv | `uv.lock` newer than `.venv/pyvenv.cfg` | `uv sync` |
+| `requirements.txt` | pip | `requirements.txt` newer than `.venv/pyvenv.cfg` (or `.venv/` missing) | `pip install -r requirements.txt` |
+| `Gemfile` | Bundler | `Gemfile.lock` newer than `vendor/bundle/` mtime | `bundle install` |
+| `composer.json` | Composer | `composer.lock` newer than `vendor/autoload.php` | `composer install --no-interaction` |
+| `pom.xml` | Maven | always (heavy — opt-in via `AskUserQuestion`) | `mvn -DskipTests install` |
+| `build.gradle*` | Gradle | always (heavy — opt-in via `AskUserQuestion`) | `gradle build -x test` |
+| `go.mod` | Go | skip — `go run`/`go build` handle deps |  |
+| `Cargo.toml` | Rust | skip — `cargo run`/`cargo build` handle deps |  |
+
+Notify one-liner: `Installing <service-name> (<stack>: <missing|stale>)…`.
+
+**Never symlink dep dirs** (`node_modules/`, `.venv/`, `vendor/bundle/`) from a sibling worktree — webpack rewrites paths via `resolve.symlinks: true` and Python/Ruby tooling has analogous issues. Run a real per-worktree install.

package/plugin/skills/muggle-test-prepare/steps/identify-services.md

@@ -0,0 +1,28 @@
+# Identify required services & startup mode
+
+List folder names in the **parent directory** of the current working directory:
+
+```bash
+ls -d "$(dirname "$PWD")"/*/ | xargs -I{} basename {}
+```
+
+Present folder names only (not contents). `AskUserQuestion` with `multiSelect: true`:
+
+> "Which of these need to be running for your tests?"
+
+Pre-check the ones matching the testing scope from [scope](./scope.md). Always include:
+- "Just the current project (no other services needed)"
+- "None of these — I'll tell you what I need"
+
+Include the current working directory as a candidate. If the user provides manual paths, verify they exist.
+
+**Immediately after selection**, ask startup mode:
+
+> "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"
+
+**Option 2**: skip [start-commands](./start-commands.md), [fresh-install](./fresh-install.md), [start-services](./start-services.md). Wait for ready signal, then [check-running](./check-running.md), run [smoke-test](./smoke-test.md) against everything (the user-started case is exactly where the smoke test matters most), then [readiness-report](./readiness-report.md).
+
+**Option 1**: proceed through the normal flow.

package/plugin/skills/muggle-test-prepare/steps/readiness-report.md

@@ -0,0 +1,26 @@
+# Final readiness report
+
+Only after every service passes [smoke-test](./smoke-test.md) or is skipped.
+
+```
+Service              PID      Port     Status         Smoke Test
+─────────────────────────────────────────────────────────────────
+backend-api          12345    3001     Running        ✓
+auth-service         12346    8080     Running        ✓
+frontend             12347    3000     Running        ✓
+─────────────────────────────────────────────────────────────────
+All services verified. Ready for E2E.
+```
+
+Surface skipped services so the caller knows the gap:
+
+```
+Skipped: payment-gateway — HTTP 500 on /
+```
+
+If you launched the services:
+
+```
+Logs: /tmp/muggle-prepare-*.log
+Cleanup: say "stop services" or re-invoke this skill.
+```

package/plugin/skills/muggle-test-prepare/steps/rebase-check.md

@@ -0,0 +1,3 @@
+# Rebase check
+
+Gated by `autoRebase`. Fire per [`../../_shared/rebase-before-e2e.md`](../../_shared/rebase-before-e2e.md) when `behind > 0`. Otherwise skip silently.

package/plugin/skills/muggle-test-prepare/steps/scope.md

@@ -0,0 +1,11 @@
+# Scope (what are you testing?)
+
+`AskUserQuestion`:
+
+> "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"
+
+Scopes the rest of the workflow. Record under `testing_scope` in the tracking file. Use it later to pre-check matching service candidates in [identify-services](./identify-services.md).

package/plugin/skills/muggle-test-prepare/steps/smoke-test.md

@@ -0,0 +1,26 @@
+# Comprehensive smoke test
+
+Runs for **every** service in the tracking file, including `external: true`. Port-listening is not proof a service works — a stale dev server binds and returns 200 with a webpack error overlay.
+
+All three probes must pass:
+
+1. **HTTP** — `GET <serviceUrl>`, 3 s timeout, accept `2xx`/`3xx` (one redirect).
+2. **Body sniff** — match response body against broken-build markers in [`../../_shared/dev-server-readiness.md`](../../_shared/dev-server-readiness.md) → "Body sniff patterns".
+3. **Log tail** — scan last 200 lines of `/tmp/muggle-prepare-<service-name>.log` for failure patterns after the latest ready signal. Skip for `external: true` (no log).
+
+Use the primitives in `dev-server-readiness.md`. Don't re-implement.
+
+## Diagnose-and-fix loop
+
+On failure, show the concrete signal (HTTP code, sniff hit, or log line) and `AskUserQuestion`:
+
+> "**<service-name>** isn't healthy: `<signal>`. How do you want to proceed?"
+
+- Option 1: **Clean restart** (Recommended) — kill + [fresh-install](./fresh-install.md) + [start-services](./start-services.md) + re-run this step
+- Option 2: **Restart only** — kill + start-services + re-run this step
+- Option 3: **I'll fix it manually** — pause; re-run on user signal
+- Option 4: **Skip** — append to `excluded_services` with reason, continue
+
+Loop per service until pass or skip. Cap at **3 iterations** — then force a manual-intervention pause.
+
+For `external: true`, only Options 3 and 4 apply.

package/plugin/skills/muggle-test-prepare/steps/start-commands.md

@@ -0,0 +1,29 @@
+# Determine start commands
+
+For each required service not already running, figure out how to start it. Read **only** the indicator file that exists.
+
+| Indicator | Stack | Default command | What to check |
+|:----------|:------|:----------------|:--------------|
+| `package.json` | Node.js | `npm run dev` | Read `scripts`: prefer `dev` > `start` > `serve` |
+| `Makefile` | Various | `make dev` | Existence; propose `make dev` or `make run` |
+| `Cargo.toml` | Rust | `cargo run` | Existence |
+| `go.mod` | Go | `go run .` | Existence |
+| `pyproject.toml` | Python | Check for framework | Read `[project.scripts]` or `[tool.poetry.scripts]` if present |
+| `requirements.txt` | Python | `python app.py` | Existence |
+| `docker-compose.yml` | Docker | `docker compose up` | Existence |
+
+If no indicator found, ask the user for the start command.
+
+Present all 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
+────────────────────────────────────────────────────────────────
+```
+
+- Option 1: "Looks good, start them"
+- Option 2: "I need to edit some commands"

package/plugin/skills/muggle-test-prepare/steps/start-services.md

@@ -0,0 +1,21 @@
+# 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** — confirm PID alive (`kill -0 <pid> 2>/dev/null`), then run the two-stage readiness probe per [`../../_shared/dev-server-readiness.md`](../../_shared/dev-server-readiness.md) against the log. Cap log-tail at 60 s. Halt on whatever surfaces.
+
+If a PID dies immediately, show the last 20 log lines:
+
+> "**backend-api** exited right after starting. Here's the tail of its log:"
+
+- 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 wasn't known upfront, re-scan listening ports after startup. Record in tracking file. If not found within ~10 s, mark port unknown.

package/plugin/skills/muggle-test-prepare/steps/viability-check.md

@@ -0,0 +1,21 @@
+# Viability check
+
+Some services can't run on a developer's machine by design — production secrets, HSMs, specific certificates, cloud-only infra. Don't waste time trying to start them.
+
+If the user volunteered this in their initial message, acknowledge and skip the question. Otherwise:
+
+> "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 option 2, collect names and exclude from discovery.
+
+If an excluded service is a hard dependency for the app under test, suggest remote testing:
+
+> "Since **payment-gateway** can't run locally, you might get better coverage by merging and running `/muggle-test` against your preview environment. 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 remote, hand off to `/muggle-test` in remote mode and exit.