@mutmutco/opencode-mmi 2.48.0

package/skills/stage/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: stage
+description: Spin a local, gitignored, auto-decommissioned test environment for the current branch (force-kills any previous stage); --live deploys an on-demand personal cloud dev stage served only to your IP. Use when the user wants to run, preview, smoke-test, or spin up the current branch locally, set up a local/Playwright env, wants a personal cloud dev stage, or invokes /stage [--live [--down]].
+---
+
+# /stage — local test environment
+
+A throwaway **local** environment to exercise the current branch — a dev server / local stack, plus
+Playwright or other tools where the project uses them. It is **off the promotion train**: any developer,
+no version effect, no deploy. It lives in a **gitignored** workspace, **force-kills the previous stage**
+before starting, and **auto-decommissions** when done.
+
+Use `/stage` as the normal path for local previews, smoke tests, and Playwright targets. If the user
+already asked to run or preview the app, that is enough authorization to start it; when intent is unclear,
+ask before creating or destroying a stage. Manual dev-server commands are allowed when the user explicitly
+wants a bypass or when a bounded diagnostic needs one, but say why. If the stage path itself fails, diagnose
+from `mmi-cli stage --json`, `tmp/stage/state.json`, process/port/container evidence, and file Hub/org-default
+friction instead of silently working around it.
+
+The stage recipe comes from one of two sources, picked automatically:
+
+- **Registry-derived default** (plumbing-free product repos): a `tenant-container` repo that ships
+  `docker-compose.yml` + `.env.example` and has a Hub registry `portRange` needs **no committed `.mmi`**.
+  `mmi-cli stage` derives a default compose stage — copy `.env.example` → `.env`, run `docker compose build
+  --no-cache`, run `docker compose up -d`, choose a free port from the registry range, and report the local
+  URL (e.g. `http://127.0.0.1:3700/`). The commands are shell-aware (PowerShell `Copy-Item` +
+  `$env:KEY='value'`; bash POSIX), and `--apply` runs them cross-shell.
+- **Local recipe** (optional): repo configuration under `stage` — `{ build, up, healthUrl, tools[] }` in a
+  local `.mmi/config.json`. That file must not carry board, deploy, secret, or project registry facts. A
+  POSIX-only recipe (`cp -n … && VAR=value …`) is treated as **stale** on a PowerShell host: `/stage` ignores
+  it and uses the registry-derived default instead of failing in the wrong shell.
+
+## Step 0 — inspect the plan
+
+```bash
+mmi-cli stage --json
+```
+
+The JSON reports `source` (`derived` / `local` / `none`) and, when derived, the local `url`. `source: none`
+means neither a usable local recipe nor a derivable default exists — the message names the missing fact
+(deployModel, `docker-compose.yml`, `.env.example`, or registry `portRange`). That gap does not mean the
+repo's Hub registry/project setup is missing.
+
+## Step 1 — run the stage
+
+A stage is **per worktree**. The CLI force-stops only the previous stage **in this worktree**, runs
+`stage.build`, starts `stage.up`, records `tmp/stage/state.json`, picks a free port from the registry
+range (skipping ports reserved by sibling worktrees), and polls `stage.healthUrl` when configured.
+Use `--port` to pin a port when needed:
+
+```bash
+mmi-cli stage run --apply
+mmi-cli stage run --apply --port 5180
+```
+
+Use a larger bound when the repo's local stack is known to be slow:
+```bash
+mmi-cli stage run --apply --timeout-ms 120000
+```
+
+All stage artifacts (build output, screenshots, Playwright traces, local DB files) stay under `tmp/stage/`
+— never tracked.
+
+A local stage is bound to the worktree that started it. Concurrent worktrees on one machine each keep
+their own stage on separate ports — you do not need to stop one before starting another. Saga continuity
+keys on branch; use a distinct North Star slug per parallel grind or feature. Stage JSON/state records
+the starting `cwd` plus git branch/commit when available.
+
+### Step 1a — post-smoke panel (when criteria exist)
+
+When grinding or the user supplied **acceptance criteria** (from the issue body at Gate 1 — not
+ad-hoc chat text), run a **Budget-routing panel** on observable stage signals before teardown:
+
+1. **Panel** (parallel):
+   - **requirements-match** (budget tier) — does the staged URL/behavior meet the criteria?
+   - **runtime-health** (budget tier) — console errors, failed `healthUrl`, broken UI signals
+     *(smoke observability — not the grind `correctness` hard lens)*
+   - **tests-actually-test** (budget tier) — if Playwright ran, did it exercise the changed path?
+2. **Synthesize** → `PanelReport` per `skills/grind/templates/synthesize-panel.md`.
+3. Feed the result back to the active `/grind` loop or report to the human. A non-empty
+   `PanelReport.blockers` means the stage failed smoke — do not claim the grind criterion met.
+   This panel is **not** a security clearance — grind Phase 2 still runs the `security` hard lens.
+
+Skip when `/stage` is ad-hoc preview with no criteria.
+
+## Step 2 — stop when done
+
+```bash
+mmi-cli stage stop --apply
+```
+
+Stop the stage when the work is done, before switching context, or before replacing it with another stage.
+If the user clearly wants the preview to stay up, leave it running and report that. The next `/stage` also
+stops the previous recorded stage before starting, so a stale server does not linger between runs. For the
+registry-derived Docker Compose default, stop also runs the recorded compose teardown (`docker compose down`)
+from the original stage working directory.
+
+## /stage --live — personal cloud dev stage
+
+dev.x stages are **not standing environments**: without `--live` the dev stage is dark. `--live`
+deploys the **current branch** to the project's dev runtime and serves it **only to your public IP** —
+gated at the **Cloudflare edge** (#1761). The CLI detects your IP, dispatches the central
+`tenant-deploy.yml` (stage=dev), then `tenant-control.yml` `cf-gate-allow` (an ephemeral Cloudflare WAF
+rule scoped to your dev host + IP). The box no longer IP-gates dev. No SSH from your machine; everything
+moves through the central workflows.
+
+```bash
+mmi-cli stage --live           # dry-run plan
+mmi-cli stage --live --apply   # deploy + gate your IP at the Cloudflare edge
+```
+
+Tear it down when done — the runtime stops and the Cloudflare edge gate is removed:
+
+```bash
+mmi-cli stage --live --down --apply
+```
+
+Personal dev stages only — rc/live environments still move exclusively through the promotion train.
+
+## Step 3 — report
+
+The stage URL, what's running (server + tools), the workspace path (`tmp/stage/`), and the teardown command.
+
+## Notes
+
+- `/stage` is local — no AWS, no deploy, no board or version effect. The one cloud exception is
+  `--live`: an on-demand **dev** stage of your branch, gated to your IP at the Cloudflare edge (above).
+- `/stage-live` is not an org command: remote rc/live environments move only through `/rcand`, `/release`, and `/hotfix`.
+- Everything is gitignored; `/stage` never produces a tracked change.
+- **Playwright MCP output goes to `tmp/`**, never the repo root: if you drive the Playwright MCP server,
+  pass `--output-dir tmp/playwright-mcp` (or point its output there). `.playwright-mcp/` is kept gitignored
+  by the org `.gitignore` managed block (`mmi-cli doctor`) as a safety net, so a stray default capture is
+  never tracked.
+- `tools[]` is declarative for now; stage hardening starts/stops the main configured process. Repos with
+  extra local services should encode them behind `stage.up` until a tool runner is added.
+- **Stale Docker bundle:** the registry-derived Docker Compose default builds with `docker compose build
+  --no-cache` before `up`. If the browser still serves an old bundle, run `mmi-cli stage stop --apply`, rerun
+  `/stage`, then inspect `tmp/stage/state.json` identity, container image labels, and compose build inputs.
+- **Stale `.env`:** when `.env` already exists from a prior `/stage` run, `stage run` does **not** refresh it
+  from an updated `.env.example` — it warns on stderr and keeps the stale file. Delete `.env` (or merge in the
+  new keys by hand) when `.env.example` changes, then re-run `/stage`.
+
+## Retro — one check before you finish
+Before your final report, answer one question honestly: did **this skill's own instructions** misfire
+this run — ambiguous wording, a misleading message, or an environment failure it should have warned
+about? (Process only — never the user's code or task; e.g. a teardown that left a port bound, or a
+Playwright output path aimed at the repo root.) If yes, file **one** lesson and move on; a clean run is
+silent (hard cap: one per run). It lands on the Hub board (deduped) and is fixed only via a reviewed PR —
+never edit the skill live; the retro is advisory, so if the call fails, note it and continue:
+`mmi-cli skill-lesson --skill stage --title "<what misfired>" --body "<what; evidence; proposed amendment>"`