@mutmutco/kilo-plugin 3.79.0

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,90 @@
+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.
+# 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_BUDGET_SHA is rendered by the CLI from its blessed run-with-budget pin — not an operator knob.
+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:
+    if: ${{ github.event_name != 'push' || github.ref_name == '{{GATE_FULL_RUN_BRANCH}}' || 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 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}}
+      # MMI-Hub#3329: the deterministic doc ref-gate — every file:line ref, command name,
+      # relative link, and pin comment in docs/** + README.md + architecture.md must resolve.
+      # This is the gate that makes the docs-janitor's unattended write surface safe (topology D,
+      # MMI-Hub epic #3325). Fleet-portable via the released CLI; runs from the repo root.
+      # MMI-Hub#3406: check the GENERATED index before resolving refs. docs/index.md is produced by
+      # `mmi-cli docs index --write`, and a stale one silently re-hosts child docs' relative links and
+      # backticked paths at the index's own depth — where they no longer resolve. Every finding it
+      # causes points at docs/index.md, so the ref-gate blames the artifact while the real fault is
+      # that nobody regenerated it. Worse, a copied `../../x.md` can escape the repo root, which used
+      # to crash the ref-gate outright rather than report (fixed in 3.44.0). Checking staleness first
+      # names the actual cause and the one-command fix.
+      - name: Doc index freshness
+        run: npx -y @mutmutco/cli@latest docs index --check
+        working-directory: '.'
+      - name: Doc ref-gate
+        run: npx -y @mutmutco/cli@latest docs refs
+        working-directory: '.'

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 secrets list
+# Consume them keyless in a command — injected into its env, never printed (raw `secrets get` was removed, #2844):
+mmi-cli secrets use GOOGLE_CLIENT_ID -- <cmd>
+mmi-cli 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 org oauth plan      # the canonical JS origins + redirect URIs + SSM cred params
+mmi-cli 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 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": "org", "classes": ["deployable"] },
+    { "target": ".github/workflows/agent-pr.yml", "source": "self", "ownership": "org", "classes": ["deployable"] },
+    { "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,93 @@
+---
+name: browser-automation
+description: Use DOM-first Playwright MCP for browser work.
+---
+
+# 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 skill-lesson --skill browser-automation --title "<what misfired>" --body "<what; evidence; proposed amendment>"`

package/skills/doctor/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: doctor
+description: One hygiene pass — board drift fix, secrets diff, stale-worktree sweep, and plugin-heal.
+---
+
+# /doctor — one hygiene pass
+
+A single sweep that clears the residue a working repo accumulates: board invariant drift, secret-catalog
+gaps, merged/closed worktrees and branches left behind, and a stale plugin/CLI. Run it when a session
+opens messy or before a handoff. Each step wraps a real `mmi-cli` command — inspect first, fix on a go.
+
+## Step 0 — toolchain integrity
+
+```bash
+mmi-cli doctor --self
+```
+
+Checks CLI/plugin version parity against the published version, and that the active `gh` token can
+actually resolve this repo. It reads npm and GitHub, so it is not offline-safe. It does not check PATH or
+hook wiring — no such check exists (#3485). On a hard gap:
+
+```bash
+mmi-cli plugin heal      # reinstall + re-enable the MMI plugin; then restart Claude Code / reopen the workspace
+```
+
+## Step 1 — board drift
+
+```bash
+mmi-cli board doctor            # detect: transfer ghosts, closed-not-Done, assignee/status mismatch, stray priority:* labels
+mmi-cli board doctor --fix      # apply the automatic fixes once the findings look right
+```
+
+`board doctor` (no `--fix`) exits nonzero when it finds drift and prints each finding. Review, then re-run
+with `--fix` to apply. Never hand-move a board item — the fixer does the mechanical writes.
+
+## Step 2 — secret-catalog diff (deployable repos)
+
+```bash
+mmi-cli secrets diff --stage dev        # required-vs-vault gap + catalog drift; values never shown
+```
+
+Runs the project-side view: declared-missing / orphan / off-scheme secrets for a stage, before any deploy.
+Repeat `--stage rc` / `--stage main` for a repo that promotes. A clean diff exits 0. **Values are never
+printed** — this only names keys. Skip for a repo with no runtime-secret contract.
+
+## Step 3 — stale worktree + branch sweep
+
+```bash
+mmi-cli worktree gc                      # dry-run (default): merged/closed-PR local+remote branches, linked worktrees, stale refs
+mmi-cli worktree gc --apply              # remove only the listed clean items
+mmi-cli worktree gc sweep-deferred       # retry any IDE-locked worktree removals queued from a prior land
+```
+
+`gc` inspects merged/closed PRs and lists exactly what is safe to delete; `--apply` removes only those. It
+never touches a branch with an open PR. Pair with `mmi-cli wave status` to see worktrees, open PRs, and
+local stages at a glance before sweeping.
+
+## Step 4 — report
+
+One line per step: toolchain OK/healed, board findings fixed, secret gaps by stage, worktrees/branches
+swept. Name anything that needs a human decision (an unowned drift, a secret only the master can grant).
+
+## Notes
+
+- `/doctor` is the hygiene pass; `/resume` is the lighter read-only session open. Reach for `/doctor` when
+  the repo is messy, not on every session.
+- `secrets diff` and `board doctor` read live state — never cache their output; re-run to confirm a fix.
+
+## 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 `gc` dry-run that proposed deleting a live
+branch, or a secrets diff that flagged a key that is present.) 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 doctor --title "<what misfired>" --body "<what; evidence; proposed amendment>"`

package/skills/epic/SKILL.md

@@ -0,0 +1,87 @@
+---
+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.
+
+## 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 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",
+    "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**.
+
+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 issue create --type task --batch tmp/epic-children.json
+```
+
+`--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.
+
+## Step 3 — confirm the tree
+
+```bash
+mmi-cli 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 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 skill-lesson --skill epic --title "<what misfired>" --body "<what; evidence; proposed amendment>"`

package/skills/hotfix/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: hotfix
+description: Promote an already-merged development fix to main and production through the gated Hub train.
+---
+
+# /hotfix — promote a development fix to main + prod
+
+A hotfix is promotion, not authoring. The fix must land on `development` through a normal issue,
+worktree, PR, review, and CI gate first. Hub then ports that merged PR or SHA to a main-base hotfix PR,
+preserves the cherry-pick audit trail, and performs the PATCH release. Never author directly from `main`.
+Never author the fix on a branch off `main`. The main-base branch is only the orchestrated port of a fix
+that is already merged to `development`.
+
+There is no back-merge: `development` already contains the fix, and `rc` absorbs it at the next `/rcand`.
+The release hotfix-coverage guard blocks a later candidate that omits the production fix.
+
+## Merge floor (#3167 — non-negotiable)
+
+- **Never squash-merge a tagged commit.** The hotfix PR itself may squash (step 2 — the tag lands *after*,
+  on the merged `main` HEAD, and the `-x` trailer must survive the squash message). But any merge that
+  carries an already-tagged commit — an alignment PR, a later `main → development` roll-forward — lands as a
+  true merge, never squash: a squash re-mints the SHA and orphans the tag from the branch lineage.
+- **A refused release train is a stop, never a license to finish by hand.** A conflict on the port, a red
+  authority probe, a failed required check, a refused `hotfix release` — each ends the run. Fix the cause on
+  `development` through a normal PR and re-run the orchestrator; never hand-cherry-pick, bare-push, or
+  bypass the gate to finish.
+- **Version probes anchor on the latest Release tag, not a branch.** `hotfix status` derives the PATCH from
+  the latest Release tag; branch manifests and stale local tags are not version sources.
+
+## Authority and preflight
+
+Production changes require the authorized human's explicit approval in the current turn. Verify authority
+and CLI health before starting:
+
+```bash
+mmi-cli org access role <owner/repo> --json
+mmi-cli doctor --apply --no-repo-writes
+```
+
+Stop on a red authority or CLI-version result. The worktree must be clean; move scratch into `tmp/` or
+gitignore it rather than widening the hotfix diff.
+
+## 1. Start from the merged development fix
+
+Use the orchestrator with an explicit source every time:
+
+```bash
+mmi-cli hotfix start --from <development-pr-number-or-merge-sha> --json
+```
+
+`hotfix start` resolves the PATCH version, branches from `origin/main`, performs the cherry-pick with `-x`,
+prepares Hub distribution artifacts when applicable, pushes the branch, and opens the main-base
+PR. Do not duplicate those steps with raw branch commands, manual cherry-picks, or raw GitHub PR creation.
+
+If the port conflicts, stop and report the conflict. Any behavior change needed to resolve it lands on
+`development` first through another normal PR, then starts another hotfix port from that merged fix.
+
+## 2. Verify the hotfix PR
+
+Run the repo's local gate against the hotfix branch, then obtain the independent reviewer required by the
+active agent doctrine. Review the actual main-base diff and the original issue acceptance criteria.
+
+Wait for required CI through Hub:
+
+```bash
+mmi-cli pr checks-wait <hotfix-pr-number>
+mmi-cli pr merge <number> --squash
+```
+
+The main-base PR is the production gate. Do not bypass checks or protected-branch authority. After the
+authorized merge, verify the merged main commit still carries the cherry-pick provenance; if the PR was
+squashed, the source trailer must survive in the squash message so future coverage checks remain exact.
+Because Hub's default branch is `development`, the main-base hotfix PR does not close a separate tracking
+issue. The development PR should already have closed the work item; do not add raw GitHub issue operations.
+
+## 3. Run the gated release
+
+Derive the tag from `mmi-cli hotfix status`, then release with the same declared source:
+
+```bash
+mmi-cli hotfix status
+mmi-cli hotfix release <vX.Y.Z> --carries <development-pr-number-or-merge-sha>
+```
+
+For MMI-Hub, pass a fresh 2-4 line neutral summary file with `--announce-summary-file`; never reuse a
+stale file and never put a product or brand name in the summary. Hub release scope never includes another
+repo's board or `ds-propagate.yml`. The orchestrator creates the tag and GitHub Release, selects the
+registry-declared deploy path, watches the release-triggered or central deployment, verifies distribution,
+and announces best-effort. Do not hand-dispatch a second publish/deploy path: duplicate release events can
+race or double-publish.
+
+For a private package, trust the authenticated publish job and its logged package/version result; a bare
+unauthenticated `npm view` cannot distinguish private from missing.
+
+## 4. Verify and report
+
+Report the tag and Release URL, production run and URL, source development PR/SHA, hotfix PR, and these
+branch facts:
+
+- `main`: the tag commit is on `origin/main`.
+- `development`: the source fix was already merged before the hotfix began.
+- `rc`: intentionally untouched; the next release coverage gate prevents regression.
+
+Do not open a manifest-alignment or back-merge PR. This is explicitly NOT a back-merge: the next normal
+release folds version manifests and branch alignment.
+
+## Retro
+
+If this skill's instructions themselves misfired, file one deduplicated lesson and continue:
+
+```bash
+mmi-cli skill-lesson --skill hotfix --title "<what misfired>" --body "<what; evidence; proposed amendment>"
+```