@mutmutco/pi-plugin 3.132.0

package/skills/bootstrap/seeds/README.template.md

@@ -0,0 +1,37 @@
+# {{REPO_NAME}}
+
+> One paragraph: what this repo **is** — the product/service and who it's for. (Write fresh — D35: do
+> not carry a legacy README over verbatim; the old docs are archived under `docs/Archive/`.)
+
+## What's here
+
+(One bullet per top-level dir/module: what it is, in one line — a map, not a tour.)
+
+## Who runs it
+
+(Owner/operator — who runs this day to day.) Access follows the MMI Future three-level model: read for
+org members, developer as GitHub `write`, project-admin as `write` plus train-branch allowlist. Authority
+detail → [org-architecture §4](https://github.com/mutmutco/MMI-Hub/blob/development/docs/org-architecture.md);
+access runbook → [repo-access](https://github.com/mutmutco/MMI-Hub/blob/development/docs/Guides/repo-access.md).
+
+## Agent context
+
+Read this section at the start of agent work in this repo.
+
+- **Structure search:** `mmi-cli oracle repo-index search <path|symbol|meaning>` — Hub cloud pointer hits
+  (Hub#4133). Prefer this over inventing wiki pages or trusting stale inventories under `docs/`.
+- **Durable WHY:** `docs/decisions/` — one file per decision, prose only for what was chosen and
+  rejected; never a description of current state. Do not maintain living current-state under `docs/`.
+- **Current state:** code + compute-at-read CLI (`mmi-cli oracle org project get`, `board`, `status`,
+  `org schedules`, …) — registry facts, resolved live. Optional generated `docs/index.md` is a
+  **routing** index only (`mmi-cli oracle docs index --check`), not product truth.
+- **GitHub wikis are retired org-wide** — this repo does not publish to a `.wiki.git`; do not create one.
+- **Stack:** (languages, frameworks, major services)
+- **Run locally:** (install, dev server, `/stage` if non-obvious)
+- **Verify before done:** (exact commands — test, lint, typecheck, repo gate script)
+- **Architecture:** deep build/deploy shape → `architecture.md`
+- **Gotchas:** (ports, env from vault not files, Windows/shell quirks specific to this repo)
+
+## Start
+
+(The one human-readable command/steps to get this running locally.)

package/skills/bootstrap/seeds/architecture.template.md

@@ -0,0 +1,34 @@
+# {{REPO_NAME}} — Architecture
+
+> How this repo is **built** — a short, stable entry, not a runtime inventory. Pair with `README.md`
+> (what it *is*). State current truth, inspect don't narrate: no change-comments or version-era labels
+> (history is in git). (Write fresh — D35.)
+
+## What this repo produces
+
+(What ships from this repo — the product/service/library, in one or two bullets.)
+
+## Layout
+
+```
+(top-level dir)     (what it is, one line)
+(top-level dir)     (what it is, one line)
+```
+
+## Stack
+
+(Languages, frameworks, datastores, major services — inspect the lockfile/manifest, don't assume.)
+
+## Build & deploy
+
+- **Class + release track + stages:** `mmi-cli oracle org project get` (registry SSOT — full = development/rc/main,
+  direct = development/main, trunk = main; never copied here, so it cannot go stale).
+- **Deploys run centrally** via the Hub (`tenant-deploy.yml`); this repo carries no deploy files, unless
+  noted otherwise below.
+- (Build/test commands, CI gate, deploy target.)
+
+## Conventions
+
+Follows the org spine (carried by the MMI plugin per machine). Repo-specific agent guidance:
+`README.md` § Agent context — no agent guide is committed to the repo (the org `mmi-no-agent-files-org`
+ruleset blocks every agent-guide path).

package/skills/bootstrap/seeds/decisions-readme.template.md

@@ -0,0 +1,45 @@
+# Decision records
+
+Prose in this tree is only for **why** — why we chose a shape, what we rejected, what constraint
+bound us. It never describes current implementation and never claims to be current. Code (and
+generated refs) are the only truth about *what is*.
+
+## One file per decision
+
+`docs/decisions/YYYY-MM-DD-<slug>.md`
+
+- **Date** in the filename is the day the decision was recorded (UTC calendar date).
+- **Slug** is a short kebab-case label for the subject (`single-aws-account`, `cowork-plugin-boundary`).
+
+## Frontmatter
+
+```yaml
+---
+date: YYYY-MM-DD
+sha: <git commit sha at which this was true>
+status: decided | superseded
+subjects:
+  - <topic or path this decision binds>
+---
+```
+
+| Field | Meaning |
+| --- | --- |
+| `date` | Same calendar day as the filename prefix. |
+| `sha` | The commit that embodies or records the decision — a pin in history, not a claim that the tree still looks like that. |
+| `status` | `decided` (in force) or `superseded` (replaced by a later record; leave the old file in place). |
+| `subjects` | Short list of topics, paths, or surfaces the decision constrains. |
+
+## Body
+
+1. `# <Title>` — the decision in one line (what was chosen, not how it works today).
+2. `## Why` — the rationale and the binding constraints.
+3. `## Rejected alternatives` — each alternative as a bullet: what it was, why it lost.
+
+Do not narrate live topology, versions, box coordinates, or "how to run it." If a reader needs
+current state, they read the code or a generated ref — not this file.
+
+## Ownership
+
+Bootstrap seeds this README once (`ownership: repo`) and never clobbers it. Individual decision
+files are authored in the same PR as the change and merged by a human. There is no scheduled docs-janitor backstop (Hub#4119/#4164).

package/skills/bootstrap/seeds/docker-compose.template.yml

@@ -0,0 +1,26 @@
+services:
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+      # Build-time secret opt-in:
+      # secrets:
+      #   - NODE_AUTH_TOKEN
+    restart: unless-stopped
+    # The box control document writes registry coords + stage-scoped SSM secret values into the
+    # release ./.env before `docker compose up`; env_file is what delivers them into the container.
+    env_file: .env
+    environment:
+      NODE_ENV: production
+      MMI_STAGE: ${MMI_STAGE:-dev}
+      MMI_PORT: ${MMI_PORT:-3000}
+      PORT: ${PORT:-3000}
+      MMI_EDGE_DOMAIN: ${MMI_EDGE_DOMAIN:-}
+    ports:
+      - "${MMI_PORT:-3000}:${PORT:-3000}"
+
+# Build-time secret opt-in. Requires registry META:
+# requiredBuildSecrets: ["NODE_AUTH_TOKEN=@github-packages-token"]
+# secrets:
+#   NODE_AUTH_TOKEN:
+#     environment: NODE_AUTH_TOKEN

package/skills/bootstrap/seeds/gate.template.yml

@@ -0,0 +1,85 @@
+name: gate
+# Org-standard green-before-merge gate for product repos (#1333). Runs on PRs, train-branch pushes,
+# and v* tags so /release and /hotfix can discover required contexts on the tagged SHA.
+#
+# Runner: self-hosted mmi-runner (mmi-live) — see docs/Guides/gh-runner-runbook.md in MMI-Hub.
+# #4118: if GATE_CMD runs tsgo or other memory-heavy typecheck / browser work, pin this job to
+#   runs-on: [self-hosted, linux, x64, mmi-heavy]
+# instead — standard lanes are MemoryMax=1200M and will cgroup-OOM those workloads.
+# Stack-aware (#1550): the runtime is rendered into the setup-step `if:` — both the Node and Python
+# setup steps live in the file but only the one matching GATE_RUNTIME runs. Knobs (override at
+# bootstrap with --var):
+#   GATE_RUNTIME       — node | python (selects which setup step fires)
+#   GATE_CMD           — the check command ({{GATE_CMD}})
+#   GATE_INSTALL_CMD   — the dependency-install command ({{GATE_INSTALL_CMD}})
+#   GATE_WORKDIR       — app working directory when not the repo root ({{GATE_WORKDIR}})
+#   GATE_CACHE_DEP_PATH— npm lockfile path for the setup-node cache ({{GATE_CACHE_DEP_PATH}})
+#   GATE_PY_VERSION    — Python version for setup-python ({{GATE_PY_VERSION}})
+#   GATE_MAX_SECONDS   — run-with-budget wall-clock ceiling in seconds ({{GATE_MAX_SECONDS}}); 300 default,
+#                        tighten per repo (org project set --var gate={"maxSeconds":N}) once measured (#3178)
+#   GATE_PUSH_BRANCHES_YAML — YAML list of push branches that trigger the workflow file (rendered by
+#                        bootstrap from the release track; not usually hand-passed)
+#   GATE_FULL_RUN_BRANCH — train branch whose PUSHES run the full gate job (development on full/direct;
+#                        main on trunk). `main` is ALWAYS included in the job `if:` below so a required-
+#                        checks ruleset on main cannot be silently skipped by a future bootstrap (#4113).
+# GATE_BUDGET_SHA is rendered by the CLI from its blessed run-with-budget pin — not an operator knob.
+# (seed touch: keep kilo mirror + BOM digests in lockstep after classifier land.)
+on:
+  pull_request:
+  push:
+    branches: {{GATE_PUSH_BRANCHES_YAML}}
+    tags: ['v*']
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
+# #3001: cancel superseded runs — agent push-bursts queue a full fresh run per push.
+# Per-PR group only (a repo-wide group hits GitHub's one-pending-slot limit and cancels
+# innocent queued runs — MMC-ZuberShade#880). Pushes group by ref: each tag and the train
+# branch supersede only themselves.
+concurrency:
+  group: gate-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  gate:
+    # #4113: bake `main` into the template permanently. GATE_FULL_RUN_BRANCH selects the train push
+    # that runs the full job; main must never become skippable via bootstrap vars alone while the
+    # org ruleset still requires `gate` on main.
+    if: ${{ github.event_name != 'push' || github.ref_name == '{{GATE_FULL_RUN_BRANCH}}' || github.ref_name == 'main' || github.ref_type == 'tag' }}
+    runs-on: [self-hosted, linux, x64, mmi-live]
+    defaults:
+      run: { working-directory: {{GATE_WORKDIR}} }
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - if: ${{ '{{GATE_RUNTIME}}' == 'node' }}
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with: { node-version: 24, cache: npm, cache-dependency-path: {{GATE_CACHE_DEP_PATH}} }
+      - if: ${{ '{{GATE_RUNTIME}}' == 'python' }}
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with: { python-version: '{{GATE_PY_VERSION}}' }
+      # MMI-Hub#3446: assert the runtime toolchain is on PATH BEFORE the install step. A runner whose
+      # node/npm (or python) is missing, or whose setup step raced, fails `{{GATE_INSTALL_CMD}}` with a
+      # bare `command not found` (exit 127) that reads like a broken diff and abandons a correct PR in an
+      # autonomous merge loop. This names the RUNNER instead — a distinguishable infra failure that
+      # `mmi-cli devops pr checks-wait` classifies as rerunnable (title `CI runner toolchain`), mirroring the
+      # disk (#3366) and browser (#808) preflights. No test ran; the diff is not implicated.
+      - name: Toolchain preflight
+        if: ${{ '{{GATE_RUNTIME}}' == 'node' }}
+        run: |
+          node -v && npm -v || { echo "::error title=CI runner toolchain::RUNNER NOT PROVISIONED — node/npm not on PATH after setup-node. This is the runner, not your diff; no install or test ran. Re-run the job (a fresh lane usually clears it); if it persists the mmi-runner node toolchain needs attention (docs/Guides/gh-runner-runbook.md in MMI-Hub)."; exit 1; }
+      - name: Toolchain preflight
+        if: ${{ '{{GATE_RUNTIME}}' == 'python' }}
+        run: |
+          python3 --version || { echo "::error title=CI runner toolchain::RUNNER NOT PROVISIONED — python3 not on PATH after setup-python. This is the runner, not your diff; no install or test ran. Re-run the job; if it persists the mmi-runner python toolchain needs attention (docs/Guides/gh-runner-runbook.md in MMI-Hub)."; exit 1; }
+      - run: {{GATE_INSTALL_CMD}}
+      # #3178: the check runs under the org wall-clock budget — a hung suite dies at the ceiling instead
+      # of squatting a runner lane for GitHub's 6h default. ci-audit + the release train enforce this step.
+      - uses: mutmutco/MMI-Hub/.github/actions/run-with-budget@{{GATE_BUDGET_SHA}}
+        with:
+          command: {{GATE_CMD}}
+          max-seconds: {{GATE_MAX_SECONDS}}
+          working-directory: {{GATE_WORKDIR}}

package/skills/bootstrap/seeds/google-login.template.md

@@ -0,0 +1,33 @@
+# Google login — {{REPO_NAME}}
+
+This repo has a Google OAuth client provisioned by the org — one client spanning local/`/stage`, dev, rc, and
+prod. Adding Google login here is **self-serve**: you do not need master-admin help.
+
+## Reach the creds (from SSM — never in git, never printed)
+```bash
+# Confirm they resolve for your repo (names only, no value):
+mmi-cli vault secrets list
+# Consume them keyless in a command — injected into its env, never printed (raw `secrets get` was removed, #2844):
+mmi-cli vault secrets use GOOGLE_CLIENT_ID -- <cmd>
+mmi-cli vault secrets use GOOGLE_CLIENT_SECRET -- <cmd>
+```
+The canonical keys are the stageless `GOOGLE_CLIENT_ID` + `GOOGLE_CLIENT_SECRET` pair at the project vault
+root. The project-admin can manage them for their own repo; runtime and CI read them keylessly. Never bake a secret into an
+image or commit it. The remote fileless deploy writes no release `.env`; **do not commit or hand-edit a `.env`**.
+The only `.env` you may create is the gitignored one `/stage` makes from `.env.example` for local dev.
+
+## The one rule that makes every environment work
+Build the OAuth `redirect_uri` from the **incoming request** — never a hardcoded base URL:
+- callback path: `/api/auth/callback`
+- derive scheme + host from `X-Forwarded-Proto` / `X-Forwarded-Host` (set by the Caddy proxy), falling back
+  to the `Host` header.
+
+The client's loopback redirect URIs are registered **port-agnostic**, so any local port works; dev/rc/prod
+URIs are registered for both `mutatismutandis.co` and `mutmut.co`, so the deploy train works unchanged.
+
+## Reference implementation + full guide
+Inspect this repo's expected URIs and confirm the client is port-agnostic:
+```bash
+mmi-cli vault org oauth plan      # the canonical JS origins + redirect URIs + SSM cred params
+mmi-cli vault org oauth verify    # probes an arbitrary :9123 loopback — no redirect_uri_mismatch = good
+```

package/skills/bootstrap/seeds/manifest.json

@@ -0,0 +1,26 @@
+{
+  "_comment": "Bootstrap seed manifest (#201) — the machine-readable contract of what /bootstrap and `mmi-cli devops bootstrap --apply` (#202) stamp into a target repo. Consumed by the CLI (loadBootstrapSeeds). ownership: 'org' = org-delivered, OVERWRITTEN on upgrade (the org owns it); 'repo' = created ONCE on a fresh bootstrap, never clobbered on upgrade (the repo owns its content). source: 'self' = copy MMI-Hub's own current file verbatim; 'seed:<file>' = render the named template in this dir with {{PLACEHOLDERS}}; 'managed-block' = merge the org-managed .gitignore block in place (preserves the repo's own ignore lines) — this is how the org-managed .gitignore block reaches every repo now that the fanout pipeline is retired (Hub#3010); the doctor SessionStart heal keeps it current thereafter. NOTE: this manifest seeds org-managed PRODUCT assets only — it never seeds AGENTS.md / CLAUDE.md / .claude/settings.json (personal agent guides) or a legacy repo-local control-plane marker. classes: which repo classes receive this seed.",
+  "placeholders": ["OWNER", "REPO", "REPO_SLUG", "REPO_NAME", "CLASS", "GATE_CMD", "GATE_PUSH_BRANCHES_YAML", "GATE_FULL_RUN_BRANCH", "GATE_RULESET_BRANCH_REFS_JSON", "PROJECT_OWNER", "PROJECT_NUMBER", "PROJECT_ID", "STATUS_FIELD_ID", "STATUS_TODO", "STATUS_IN_PROGRESS", "STATUS_IN_REVIEW", "STATUS_DONE", "STACK", "REGION"],
+  "seeds": [
+    { "target": ".github/ISSUE_TEMPLATE/bug.yml", "source": "self", "ownership": "org", "classes": ["deployable", "content"] },
+    { "target": ".github/ISSUE_TEMPLATE/feature.yml", "source": "self", "ownership": "org", "classes": ["deployable", "content"] },
+    { "target": ".github/ISSUE_TEMPLATE/task.yml", "source": "self", "ownership": "org", "classes": ["deployable", "content"] },
+    { "target": ".github/ISSUE_TEMPLATE/config.yml", "source": "self", "ownership": "repo", "classes": ["deployable", "content"] },
+    { "target": "scripts/next-version.mjs", "source": "self", "ownership": "org", "classes": ["deployable"] },
+    { "target": ".github/workflows/gate.yml", "source": "seed:gate.template.yml", "ownership": "repo", "classes": ["deployable"] },
+    { "target": ".github/workflows/agent-pr.yml", "source": "self", "ownership": "org", "classes": ["deployable"], "waivers": { "jerv-jervcode": "pins this workflow's EXACT step shapes in its own scripts/workflow-boundary-core.mjs — a literal repositories: Jerv-JervCode token scope, and whole-step equality for the surface and verdict legs. #4040 widened the org seed to the same hardened boundary (pull_request_target off the trusted base, an immutable BASE..HEAD compare with a file-count equality wall, a per-repo App token scope, and a certified-head merge), so the two now agree on substance. They cannot agree on bytes: a seed serving 16 repos resolves its token scope and its required contexts at run time, which exact-step equality rejects by construction. The waiver is permanent by design, not a deferral — lifting it would mean weakening the strictest repo to match a fleet file." } },
+    { "target": ".github/rulesets/mmi-product-required-checks.json", "source": "seed:mmi-product-required-checks.template.json", "ownership": "org", "classes": ["deployable"] },
+    { "target": ".gitignore", "source": "managed-block", "ownership": "org", "classes": ["deployable", "content"] },
+    { "target": "README.md", "source": "seed:README.template.md", "ownership": "repo", "classes": ["deployable", "content"] },
+    { "target": "architecture.md", "source": "seed:architecture.template.md", "ownership": "repo", "classes": ["deployable", "content"] },
+    { "target": "docs/decisions/README.md", "source": "seed:decisions-readme.template.md", "ownership": "repo", "classes": ["deployable", "content"] },
+    { "target": "docs/Guides/google-login.md", "source": "seed:google-login.template.md", "ownership": "repo", "classes": ["deployable"], "projectTypes": ["web-app"] },
+    { "target": "docker-compose.yml", "source": "seed:docker-compose.template.yml", "ownership": "repo", "classes": ["deployable"], "deployModels": ["tenant-container"] },
+    { "target": "Dockerfile", "source": "seed:Dockerfile.template", "ownership": "repo", "classes": ["deployable"], "deployModels": ["tenant-container"] }
+  ],
+  "labels": [
+    { "name": "bug", "color": "d73a4a", "description": "Something is broken or behaving wrong" },
+    { "name": "feature", "color": "a2eeef", "description": "New capability or enhancement" },
+    { "name": "task", "color": "0052cc", "description": "Task, chore, or improvement" }
+  ]
+}

package/skills/bootstrap/seeds/mmi-product-required-checks.template.json

@@ -0,0 +1,23 @@
+{
+  "_comment": "Repository-level ruleset requiring the product gate job (#1333). Apply via GitHub repo rulesets (master-admin) after bootstrap seeds gate.yml — the job name gate must match this context.",
+  "name": "mmi-product-required-checks",
+  "target": "branch",
+  "enforcement": "active",
+  "conditions": {
+    "ref_name": {
+      "include": {{GATE_RULESET_BRANCH_REFS_JSON}},
+      "exclude": []
+    }
+  },
+  "rules": [
+    {
+      "type": "required_status_checks",
+      "parameters": {
+        "strict_required_status_checks_policy": false,
+        "required_status_checks": [
+          { "context": "gate" }
+        ]
+      }
+    }
+  ]
+}

package/skills/browser-automation/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: browser-automation
+description: Use DOM-first Playwright MCP for browser work.
+---
+
+**Host-native invocation:** Claude `/mmi:browser-automation` · Codex `$mmi:browser-automation` · jervcode/Kimi `/skill:browser-automation` · Kilo `skill` tool. A backticked `/name` in this doc names the matching workflow (this skill or a sibling), not a literal command.
+
+# Browser automation — DOM-first Playwright MCP
+
+Org standard for agent browser work on Claude Code. **Playwright** is the engine; agents interact through **structure-first** MCP tools, not pixels-first defaults.
+
+## Doctrine (non-negotiable)
+
+1. **Accessibility tree first** — semantic structure the agent can reason about (`browser_snapshot`, a11y refs).
+2. **DOM second** — selectors, snapshots, network when the tree is not enough.
+3. **Vision last** — screenshots only when tree + DOM cannot answer the question.
+4. **Prefer HTTP/OpenAPI** — call APIs directly when discovery or the task allows; do not drive UI for data you can fetch.
+
+**Never** pass `--caps=vision` (or equivalent vision-first defaults) on Playwright MCP org-wide. Vision caps burn tokens, hide structure, and break on theme/layout drift.
+
+## When to use what
+
+| Need | Use |
+|------|-----|
+| Local dev server + smoke on current branch | **`/stage`** — gitignored stack under `tmp/stage/`; see `skills/stage/SKILL.md` |
+| Personal cloud dev preview of your branch | **`/stage --live`** — IP-gated dev stage; not rc/prod |
+| Interactive UI debug, one-off flow, agent-driven clicks | **Playwright MCP** (this skill) — DOM-first, artifacts under `tmp/` |
+| Durable hosted automation outside dev machines | **Stagehand + Browserbase** (production path) — explicit choice, not the default for every local task |
+
+`/stage` and Playwright MCP **complement** each other. `/stage` spins the app; MCP drives the browser against a URL (often the stage URL).
+
+## MCP configuration (no vision)
+
+### Claude Code
+
+Enable the official Playwright plugin (`playwright@claude-plugins-official`) via `/plugin`. Follow its DOM-first tools; do not enable vision-first modes for routine agent work. Point MCP output at `tmp/playwright-mcp` when the server accepts `--output-dir`.
+
+Editor-host MCP configs (Cursor `.cursor/mcp.json`, Codex `config.toml`) are retired org surfaces (#2741/#2808) — bootstrap no longer seeds them; do not reintroduce them.
+
+## Playwright availability
+
+Check the configured/global CLI before adding a temporary local dependency. On Windows PowerShell:
+
+```powershell
+Get-Command playwright
+playwright --version
+```
+
+`node -e "require.resolve('playwright')"` only proves a Node module is installed in the current package; it
+can fail while the global or editor-configured Playwright CLI works. Use the available CLI for smoke checks
+and MCP setup. Temporary per-worktree installs are fallback-only, and should stay untracked.
+
+## Agent workflow (MCP)
+
+1. **Goal** — what observable outcome proves success?
+2. **Navigate** — open the target URL (often from `/stage` JSON: `mmi-cli stage --json`).
+3. **Snapshot** — a11y tree / DOM snapshot before interacting.
+4. **Act** — click, type, select using refs from the latest snapshot.
+5. **Re-snapshot** after navigation or major DOM changes (refs go stale).
+6. **Vision only if stuck** — one screenshot to disambiguate; then return to tree/DOM.
+
+Core MCP loop:
+
+```
+browser_navigate → browser_snapshot → browser_click / browser_type → browser_snapshot
+```
+
+## Artifacts and hygiene
+
+- **All Playwright MCP output → `tmp/playwright-mcp/`** (pass `--output-dir tmp/playwright-mcp` when the MCP server supports it).
+- **Never** leave traces, screenshots, or reports at the repo root.
+- `.playwright-mcp/` at repo root is gitignored as a **safety net only** — not the canonical path.
+- The housekeeping gate refuses tracked browser artifacts (`.playwright-mcp/`, `playwright-report/`, `test-results/`).
+
+## Anti-patterns (org-wide avoid)
+
+- `--caps=vision` or screenshot-first wrappers for routine tasks
+- Skyvern, Magnitude, LaVague, or other vision-first agent browsers as org defaults
+- Committing `.playwright-mcp/`, `playwright-report/`, or `test-results/` from agent runs
+- Replacing `/stage` with ad-hoc MCP servers for branch smoke (use `/stage` for the stack, MCP for the browser)
+
+## Related
+
+- **`/stage`** — `skills/stage/SKILL.md`
+- **`/grind`** (optional external tool) — use DOM-first browser checks in verification when criteria need UI proof
+
+## 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 MCP snippet, or an artifact path it should have warned
+about? (Process only — never the user's code or task.) 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 learning skill-lesson --skill browser-automation --title "<what misfired>" --body "<what; evidence; proposed amendment>"`

package/skills/epic/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: epic
+description: Decompose a vision or umbrella issue into linked child issues via one batch create.
+---
+
+# /epic — decompose an umbrella into children
+
+Turn one large item — a vision issue, an epic, an umbrella issue — into a set of native sub-issues in a
+single pre-validated batch, each already linked to its parent. This is the slice-and-fan-out act done by
+hand today: draft the children, validate them all, create them, confirm the tree.
+
+## Opening branch — create a new umbrella when none exists
+
+When the request is a product intent rather than an existing issue, gather the intent first, read the
+repo's live issue templates, draft the umbrella from the matching feature/task template, and show that
+draft for the user's go. Only then create one issue with the `epic` label and an explicit Priority field;
+re-read it from the board to prove the body, label, and priority landed. Stop there unless the user also
+asked for and approved child decomposition.
+
+## Step 0 — load the umbrella whole
+
+Read the parent end-to-end before slicing — body **and every comment**, treating later comments as
+superseding:
+
+```bash
+mmi-cli oracle board show <owner/repo#N>       # status, body, and every comment for the umbrella
+```
+
+Slice by deliverable, not by phase: each child must be independently claimable and land in its own PR.
+Keep the parent as the umbrella — do not close it until the last child merges.
+
+## Step 1 — draft the batch file
+
+Write a JSON array (one object per child) to a scratch path under `tmp/`. Each row:
+
+```json
+[
+  { "type": "task", "title": "C1: extract the shared frame", "body": "…", "priority": "high",
+    "surface": "cli", "parent": "owner/repo#42" },
+  { "type": "feature", "title": "C2: wire the new command", "body": "…", "priority": "medium",
+    "parent": "owner/repo#42" }
+]
+```
+
+- `type` — `bug` · `feature` · `task` (required; maps to the repo's issue-template label).
+- `title` — required, non-empty; keep it a short, greppable deliverable.
+- `parent` — the umbrella ref (`#N`, `owner/repo#N`, or URL); links each child as a native sub-issue on
+  create, so you do not need a separate `link-child` pass. Cross-repo is fine (a Hub umbrella can parent
+  product-repo children).
+- `priority` — `urgent|high|medium|low` (defaults to `medium`); sets the board Priority **field**.
+- `repo` — optional per-row target repo (`owner/repo`); defaults to `--repo`, then the current repo.
+  This is how one batch fans children out across repos under a single umbrella.
+- `surface` — required when the target repo uses `surface:*` taxonomy; accepts the value with or without
+  the prefix. A top-level `--surface <value>` may supply the default for every applicable row.
+
+The batch **pre-validates every row before creating any** — one bad row fails the whole set with an
+aggregate error, so you fix all of them once. Get the user's go on the drafted set before writing.
+
+## Step 2 — create the children
+
+```bash
+mmi-cli oracle issue create --type task --batch tmp/epic-children.json --surface cli
+```
+
+`--type` is required by the create command but each row's own `type` governs; pass any valid type as the
+placeholder. It prints per-row `{number,url}` results and fails loud on any misfire. Add
+`--idempotency-key <key>` when a retried loop must not duplicate.
+
+The idempotency lookup is find-before-create, not an atomic reservation. Run one batch writer at a time:
+never submit concurrent creates with the same key. Size the calling command's wall-clock budget for the
+whole sequential batch. If the command times out, its outcome is unknown — confirm the process has ended,
+wait for writes to quiesce, inspect the children, then retry the missing rows with the same key.
+
+## Step 3 — confirm the tree
+
+```bash
+mmi-cli oracle issue children <owner/repo#N>        # each child: number/title/state/repo/boardStatus/linkedPrs
+```
+
+Verify every intended child is linked and on the board as Todo. To link a child that already existed (not
+part of the batch), use the inverse-friendly single link:
+
+```bash
+mmi-cli oracle issue link-child <parent> <child>
+```
+
+Each child is now a parallel item — fan them out one worktree + PR each. **When the last child merges,
+close the umbrella** (its board `Done` follows automatically).
+
+## Notes
+
+- Native sub-issues, not a body task-list: the parent renders a sub-issue checklist and each child renders
+  its parent — nothing to hand-maintain.
+- Never free-type children with raw `gh issue create` — the batch path carries validation, board attach,
+  and structured output.
+
+## 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 batch schema that rejected a valid row, or a
+link that attached to the wrong parent.) 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 learning skill-lesson --skill epic --title "<what misfired>" --body "<what; evidence; proposed amendment>"`