@mutmutco/opencode-mmi 2.48.0

package/skills/hotfix/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: hotfix
+description: Emergency PATCH to main + prod by cherry-picking a fix that already landed on development — pick to a hotfix branch, merge to main, tag vX.Y.Z, prod-deploy. No back-merge; rc absorbs it at the next /rcand. Train-authority gated (Hub train master-only). Use when an authorized user needs an urgent production fix, a hotfix or emergency patch to main, or invokes /hotfix.
+---
+
+# /hotfix — promote a development fix to main + prod, fast
+
+A hotfix is **promotion, not authoring**: the fix lands on `development` first via a normal PR, then
+`/hotfix` cherry-picks exactly those commits onto `main`, tags `vX.Y.Z`, and deploys prod. One train,
+one origin. **There is no back-merge**: `development` already has the code by construction, and `rc`
+absorbs the fix at the next `/rcand`. A release cut from a stale rc is blocked by the `/release`
+hotfix-coverage guard (built into `mmi-cli release`), so the fix cannot be silently reverted.
+**Train-authority gated (D14)** — verify with `mmi-cli access role {owner}/{repo} --json` (fail
+closed; the Hub repo is master-only); prod change → the authorized human's explicit per-turn go.
+PATCH-level only — cherry-pick promotion makes it tempting to rush a feature to prod; don't.
+
+## Step 0 — the fix lands on development first (precondition)
+
+The fix is authored, reviewed, and merged on `development` like any other change — normal PR, normal
+gate, normal issue auto-close and board automation. **Never author the fix on a branch off `main`.**
+If `main` has diverged and the dev fix doesn't apply cleanly, the port happens during the cherry-pick
+(Step 1) — `development` stays the single origin of every fix.
+
+Record the dev-side SHA(s) to promote — for a squash-merged PR that's one commit:
+
+```bash
+git fetch origin
+FIX=$(gh pr view <dev-pr-number> --json mergeCommit --jq .mergeCommit.oid)
+```
+
+## Step 1 — branch from main, cherry-pick with -x (the audit trail)
+
+Precondition: a clean working tree — the branch + cherry-pick + dist bump won't run dirty. Like the other
+train commands, the clean-tree check rejects UNTRACKED scratch too, not just modified tracked files — if it
+stops with `working tree must be clean before …`, run `git status` and gitignore the `??` scratch (or move it
+to a gitignored path like `tmp/`) (#1472).
+
+```bash
+git checkout -b hotfix/vX.Y.Z origin/main
+git cherry-pick -x "$FIX"        # repeat per commit, oldest first, if promoting more than one
+```
+
+**`-x` is mandatory, not cosmetic.** It records `(cherry picked from commit <sha>)` in each commit
+message; the `/release` hotfix-coverage guard reads that trailer to prove — by dev-SHA ancestry, immune
+to conflict-resolved diffs — that the fix is in the release candidate. A pick without `-x` degrades the
+guard to a diff (patch-id) comparison, which a conflicted port breaks.
+
+Conflict on the pick → resolve it **here, on the hotfix branch**: port the fix's intent to `main`'s
+code. Never "fix forward" on main with new logic that dev doesn't have — if the port changes behavior,
+land that change on `development` first and re-pick.
+
+## Step 2 — verify
+
+Run the gate green locally on the hotfix branch. The pick must prove itself against `main`'s code, not
+just dev's — the dev PR's test rides along in the cherry-pick; make sure it passes here too.
+
+### Step 2a — verify panel (compressed, always Paranoid)
+
+After local checks pass, run a **compressed Paranoid panel** on the cherry-pick diff — same
+fresh-eyes discipline as `/grind`, scoped for surgical prod promotion:
+
+1. **Panel** (parallel, verifier tier): `security` + `correctness` (each **double-pass**) +
+   **tests-actually-test** — do the picked/adjusted tests prove the fix on `main`'s code?
+2. **Synthesize** → `PanelReport` per `skills/grind/templates/synthesize-panel.md`.
+3. **Gate:** `PanelReport.blockers` must be empty. Cap **2** panel rounds — on cap, stop and
+   report; do not open the Step 3 PR.
+
+Pin verifiers to the verbatim diff — never builder/session context. No `--explore`, no WIP hand-off
+path on this panel.
+
+## Step 2b — bump the distribution (Hub only, unconditional)
+
+Only in the repo that hosts the org plugin set (`.claude-plugin/marketplace.json` and
+`.agents/plugins/marketplace.json` present). The Claude marketplace `source` is pinned to `ref: main`,
+and the Codex marketplace is refreshed from this repo, so the hotfix ships its PATCH version across the
+whole set — spine dogfood (`scripts/spine-dogfood.mjs`), Claude/Codex/Cursor plugin manifests, OpenCode adapter,
+standalone npm packages, and the committed CLI bundle — **every time, changed or not** (#976; `mmi-cli hotfix start` does
+exactly this). Stage exactly the files the helper updated — `changed-files` prints them, so the list can't go
+stale:
+```bash
+VER=$(node scripts/next-version.mjs hotfix); VER=${VER#v}               # X.Y.Z for this hotfix
+node scripts/release-distribution.mjs prepare "$VER"
+git commit -m "[hotfix] publish mmi tooling $VER" -- $(node scripts/release-distribution.mjs changed-files)
+```
+This bump commit is `main`-side version metadata — the hotfix-coverage guard exempts it (it touches
+only the distribution manifest set), so it needs no dev twin to pass `/release`. Non-Hub repos skip
+this step (no plugin to publish); their release version fold happens at the next `/release`.
+
+## Step 3 — land on main via PR (the gate)
+
+```bash
+git push -u origin hotfix/vX.Y.Z
+gh pr create --base main --title "[hotfix] vX.Y.Z — <summary>" --body "Promotes <dev-pr-or-sha> from development. ..."
+mmi-cli pr merge <number> --squash      # rejected if you're not an admin/bypass actor — that's the gate
+```
+
+> **Squash caveat:** squashing the hotfix PR collapses the picked commits into one fresh commit, and the
+> `(cherry picked from commit …)` trailers survive only if they ride into the squash message. Verify the
+> merged commit on `main` still carries the trailer (`git log -1 origin/main`); if it was lost, re-state
+> it in the squash message — otherwise the `/release` guard falls back to patch-id and a conflicted port
+> will need an explicit human ack.
+
+Because Hub's default branch is `development`, the `main` hotfix PR closes nothing — and in this flow it
+*shouldn't*: the work item already closed when the fix merged to `development`. If a separate
+hotfix-tracking issue exists, close it explicitly:
+`gh issue close <issue-number> --comment "Promoted to main via hotfix PR #<pr-number>; tagging vX.Y.Z next."`
+
+## Step 3b — a fix found mid-hotfix (continuation branch)
+
+A friction or bug surfaced *while* the hotfix is in flight follows the same one-origin rule — it does not
+get patched onto the hotfix branch directly:
+
+1. Land the fix on `development` via a normal PR (its own work item, its own gate).
+2. Cherry-pick it with `-x` onto a **continuation branch** `hotfix/vX.Y.Z-<slug>` cut from `origin/main`
+   — one branch per fix, `<slug>` naming the fix (e.g. `hotfix/v2.20.1-train-gate`).
+3. Verify (Step 2), bump the distribution if Hub (Step 2b), then merge it to `main` via PR (Step 3) — with
+   the `(cherry picked from commit …)` trailer preserved in the squash message, same caveat as above.
+
+```bash
+git fetch origin main && git switch -c hotfix/vX.Y.Z-<slug> origin/main
+git cherry-pick -x <dev-sha>
+git push -u origin hotfix/vX.Y.Z-<slug>
+gh pr create --base main --title "[hotfix] vX.Y.Z — <fix summary>" --body "Continuation pick of <dev-pr-or-sha>."
+mmi-cli pr merge <number> --squash
+```
+
+`mmi-cli hotfix release` matches both `hotfix/vX.Y.Z` and `hotfix/vX.Y.Z-*` heads and pins the **newest
+merged** PR for the tag, so every continuation pick ships in `vX.Y.Z`. Re-run the Step 2b
+release-distribution prepare on each continuation (usually byte-identical) so the bump rides whichever
+branch ends up newest.
+
+## Step 4 — tag + prod deploy + Release
+
+`mmi-cli hotfix release vX.Y.Z` runs this step for **hub-serverless** (MMI-Hub) and **tenant-container**
+(and **solo-container**) repos — it branches on `deployModel` from the Hub registry. For other models the
+orchestrator tags + creates the GitHub Release but does not dispatch a central deploy (follow the repo's
+own prod path). Manual fallback below when not using the orchestrator:
+
+```bash
+git fetch origin
+TAG=$(node scripts/next-version.mjs hotfix)           # -> vX.Y.(Z+1)
+git tag "$TAG" origin/main
+git push origin "$TAG"
+gh release create "$TAG" --target main --generate-notes --latest
+git merge-base --is-ancestor "$TAG^{commit}" origin/main && echo "tag is on main"
+```
+
+> Hub `deploy.yml` requires `target_commitish == "main"` for prod deploy (#1400). Use `--target main`
+> (not a commit SHA) — the tag still pins the release artifact. `mmi-cli hotfix release` passes
+> `--target main` automatically; manual fallback must match.
+
+**Hub hotfixes announce to Slack (#883).** Hub scope is **only** `mutmutco/MMI-Hub` — never another repo's
+board, `ds-propagate.yml`, or product design-system state. Resolve the real tag (`TAG=$(node scripts/next-version.mjs hotfix)`)
+and print `$TAG` in summaries and reports — never a placeholder.
+
+For MMI-Hub, write a curated summary — 2-4 very short plain lines, one change per line, dev-readable,
+in neutral Hub-subsystem terms — **never** a product or brand name (FoFu, Katip, etc.) in the summary,
+Slack post, chat, or report — to a fresh temp file (`f=$(mktemp tmp/release-summary.XXXXXX)`, so a stale
+prior summary is never reused), then run the orchestrator with it:
+`mmi-cli hotfix release "$TAG" --announce-summary-file "$f"`. After the Release is created, the CLI posts
+the summary to the org alerts channel as the MMI-Future Slack app (token + channel from SSM at run time);
+without the file it distills the generated notes (product brands are stripped there too). Best-effort only —
+a Slack failure never fails the hotfix, and a resumed (already-existing) Release does not re-announce.
+
+For `tenant-container` repos, dispatch the Hub central deployer and watch the exact run:
+```bash
+gh workflow run tenant-deploy.yml --repo mutmutco/MMI-Hub \
+  -f slug={slug} -f repo={owner}/{repo} -f ref=main -f stage=main
+gh run watch "$(gh run list --repo mutmutco/MMI-Hub --workflow tenant-deploy.yml --limit 1 --json databaseId -q '.[0].databaseId')" \
+  --exit-status
+```
+
+For `hub-serverless` (MMI-Hub), the Release event auto-fires `deploy.yml` for prod and `publish.yml` for
+the plugin/CLI/OpenCode npm packages. Do **not** dispatch `tenant-deploy.yml`; watch the release-triggered runs instead:
+```bash
+gh run watch "$(gh run list --workflow deploy.yml --event release --limit 1 --json databaseId -q '.[0].databaseId')" --exit-status
+gh run watch "$(gh run list --workflow publish.yml --event release --limit 1 --json databaseId -q '.[0].databaseId')" --exit-status
+```
+
+```bash
+node scripts/release-distribution.mjs publish "$TAG"  # Hub only — manual fallback when publish.yml could not ship npm
+npm exec --package @mutmutco/cli -- mmi-cli --version
+```
+
+Any follow-up `release-distribution.mjs verify "$TAG"` must run from a checkout **at the tag** (`git
+checkout "$TAG"`, or a worktree at the tag) — verify checks the working tree and refuses any other
+commit once the tag exists, so a `development` checkout that hasn't seen the bump can't masquerade as a
+broken release.
+
+## Step 5 — no residue — NOT a back-merge, NOT a forward bump
+
+`development` already has the fix (Step 0), so **no branch merges back** — and nothing else needs to
+happen either (#976). Tags are repo-global, so `next-version.mjs` sees `vX.Y.Z` from any branch — version
+math doesn't drift. The version manifests Step 2b bumped on `main` stay `main`-only by design:
+`development` sitting behind on manifests is the steady state, and the next `/release` re-aligns it
+structurally (its version fold rewrites the manifests on the release commit; its back-merge carries them
+to `development`). Never open a manifest-alignment PR against `development`.
+
+`rc` is **never touched**: it gets the fix from `development` at the next `/rcand`. The `/release`
+hotfix-coverage guard (fail closed) blocks any candidate that misses a prod hotfix, so "untouched" can't
+become "reverted".
+
+## Step 6 — report
+
+`vX.Y.Z` + Release URL · prod deploy run + URL · per-branch verification, not merge ceremony:
+- `main`: tag SHA is on `origin/main` (`merge-base --is-ancestor` from Step 4).
+- `development`: the promoted dev SHA(s) — already ancestors by construction; cite the dev PR.
+- `rc`: untouched by design; note that `/release` enforces coverage automatically inside `mmi-cli release`.
+- Any hotfix-tracking issue explicitly closed in Step 3 (the `main` PR can't auto-close — the repo
+  default branch is `development`).
+
+## 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 misleading authority or gate message, or an
+ambiguous cherry-pick or no-back-merge step.) 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 hotfix --title "<what misfired>" --body "<what; evidence; proposed amendment>"`

package/skills/mmi/SKILL.md

@@ -0,0 +1,372 @@
+---
+name: mmi
+description: Your work board — shows your assigned + claimable work (and what others have claimed) on this repo's GitHub Project, and helps you continue, claim, advance, or file an item. Use when a dev starts work, asks what to work on, what's assigned or claimable, wants to claim or advance an item, file a bug or feature, asks "what's on my board", or invokes /mmi.
+---
+
+# /mmi — start of work
+
+Shows a dev their workboard for this repo: what they're working on, what's free to pick up, and what others
+have claimed. Read-only by default — render the board, then get out of the way.
+
+Status values: `Todo · In Progress · In Review · Done` (GitHub enforces who can move what — don't re-explain
+it on every move). Closed/finished items auto-archive after they go quiet; archived ones aren't on the board.
+
+## Step 0 — identity, greet, eager preflight when stale
+
+`/mmi` is the dev's hello-to-work — the most common command they run. Three pacing rules before anything else:
+
+1. **Resolve login, then greet immediately** (before `board read` or doctor — still the first lines in
+   the response so the dev never stares at silent tool output). One emoji max in the whole response.
+   The greeting addresses the dev, never claims to *be* them (not "I'm @<login>"):
+   - **SessionStart banner** — if context carries `current human: <login>`, use that login.
+   - **Else** one fast call: `mmi-cli whoami --json` (cached Hub session in `hub-session.json` when
+     valid — no network; `gh` fallback only when the cache lacks `login`; exit 0 on `unknown`). Do
+     **not** call `gh api user` separately — `whoami` already covers it. Do **not** wait on `board read`
+     for identity — `viewer` is for work items only (Step 1).
+   - Known login → `👋 Welcome back, @<login> — pulling up your board…`
+   - `source: unknown` → generic `👋 Welcome back — pulling up your board…`
+2. **Run doctor preflight synchronously before `board read` when a heal may be needed (#1871).** A healthy
+   setup stays **completely silent and fast** — no background task, no "setup looks good" line. When the
+   CLI or plugin is behind, the dev must see the wait **up front**, not after a silent multi-minute gap.
+
+```bash
+mmi-cli doctor --preflight   # silent when healthy; upfront ↻ notice + eager heal when version/plugin update needed
+mmi-cli board read --json    # Step 1 — only after preflight (or greet-first on the all-green path)
+```
+
+`doctor --preflight` detects a stale npm global, plugin clone, or installed-plugin record and runs the
+same self-heal as interactive `doctor` — but prints `↻ Updating mmi tooling, one moment…` **before** the
+wait and a clear `↻ MMI tooling updated — …` line when done (reload/restart guidance included). A behind
+npm global runs `npm install -g @mutmutco/cli@latest` (effective next invocation); a behind plugin clone
+fast-forwards (effective next session). On a Claude surface it also self-heals a **stale or duplicate
+installed plugin** — it drives `claude plugin marketplace remove mmi` → `claude plugin marketplace remove
+mutmutco` → `claude plugin marketplace add mutmutco/MMI-Hub` → `claude plugin install mmi@mutmutco` (a
+fresh reinstall, never `claude plugin update`, which nests into itself past MAX_PATH on Windows and wipes
+the marketplace clone, #1126), collapses duplicate `mmi@mutmutco` rows in
+`~/.claude/plugins/installed_plugins.json` to one user-scope entry, and quarantines stale MMI-only cache
+dirs under Claude/Codex plugin caches while preserving the active/released version. Plugin updates still
+take effect after a reload: **restart Claude Code / run `/reload-plugins`** (native), or **reopen the
+workspace** (VS Code extension).
+
+- **All green** → `doctor --preflight` prints nothing; proceed straight to `board read`.
+- **Stale tooling** → relay the `↻` lines from stderr to the dev, then `board read`.
+- **`mmi-cli: command not found`** → plugin PATH provisioning has not applied, or the standalone CLI is not installed.
+  In Claude Code, reopen the session; if it persists, install the MMI plugin:
+  `/plugin marketplace add mutmutco/MMI-Hub` → `/plugin install mmi@mutmutco` → `/reload-plugins`.
+  In Codex, install the plugin from the configured marketplace at the released `main` ref (the
+  marketplace default branch can lag the release — #1458):
+  `codex plugin marketplace add mutmutco/MMI-Hub --ref main` if missing → `codex plugin add mmi@mutmutco`.
+  For editor-agnostic access, install the standalone CLI:
+  ```powershell
+  npm install -g @mutmutco/cli
+  ```
+  In PowerShell from an `MMI-Hub` checkout, or when diagnosing a stale plugin cache, use the repo-local fallback:
+  ```powershell
+  node cli/dist/index.cjs doctor --json
+  ```
+- **Slash commands disappeared — `/mmi` (or any `/…`) shows nothing** → the plugin is stale, duplicated, or
+  disabled, so the command surface is gone and you can't reach a slash recovery command. Recover from the
+  shell with the repo-local doctor, which detects and (on a Claude surface) self-heals it:
+  ```powershell
+  node cli/dist/index.cjs doctor      # from an MMI-Hub checkout — auto-heals + prints the reload action
+  ```
+  If `claude` isn't on PATH for the auto-heal, run the surface-correct commands by hand (never `/plugin` in
+  VS Code — it isn't an updateable path there):
+  ```bash
+  # Claude Code (native or VS Code extension)
+  claude plugin marketplace remove mmi && claude plugin marketplace remove mutmutco && claude plugin marketplace add mutmutco/MMI-Hub && claude plugin install mmi@mutmutco
+  # then: restart Claude Code / run /reload-plugins  (VS Code: reopen the workspace)
+
+  # Codex — pin --ref main: the marketplace default branch can lag the released plugin (#1458),
+  # so `marketplace upgrade` reinstalls the stale build. Remove → re-add at main → add reinstalls clean.
+  codex plugin marketplace remove mmi && codex plugin marketplace remove mutmutco && codex plugin marketplace add mutmutco/MMI-Hub --ref main && codex plugin add mmi@mutmutco   # then restart Codex
+
+  # Cursor — no per-user CLI; refresh the Team Marketplace from the IDE:
+  # Cursor Dashboard → Settings → Plugins → Update next to the MMI Team Marketplace, then restart Cursor
+  ```
+- **A gate is ✗** → walk them through the printed fix; don't just echo it:
+  - **GitHub auth** (the usual one) — the saga *and* the board both use their `gh` token. Give them the
+    command to run **in their own terminal** (the browser step is theirs — an agent can't log in as them):
+    ```bash
+    gh auth login --hostname github.com --git-protocol https --web --scopes "project"
+    ```
+    The `project` scope is what lets `/mmi` read + move the board, granted here once. When they're back,
+    re-run `mmi-cli doctor` to confirm green.
+  - **Hub registry / board META** — `mmi-cli project get <owner/repo>` or `mmi-cli board read` reports
+    missing project/board coords → a master-admin registers or backfills the repo's `PROJECT#<slug>` META.
+    There's no reliable project to read until that is fixed, so stop here.
+
+A broken setup surfaces from `doctor --preflight`, a failed `board read`, or a gate that still fails after
+heal — handle it then. A `command not found` from **either** command routes into the recovery paths above.
+Don't block the all-green path on doctor noise.
+
+## Authority (org-wide)
+
+`/mmi` is the usual session start — agents should know the dev's role before any later train, vault, or
+tenant request surfaces. After the board read (Step 1), you already have `viewer` in the JSON; for train
+authority on this or another repo, run:
+
+```bash
+mmi-cli access role <owner/repo> --json   # { role, train } — Hub-verified from registry projectAdmins
+```
+
+When `role` is `project-admin` and `train` is true on **that** repo, the dev holds D14 authority there —
+guide or execute via the matching skill (`/secrets`, `/rcand`, `/release`, `/hotfix`, `tenant control`).
+**Do not** redirect them to the master. Hub train is master-only; org-tier vault and access grants stay
+master-only. Full matrix: `AGENTS.md` § Authority.
+
+## Config
+
+The project this repo is on lives in the Hub registry (`PROJECT#<slug>`: `projectOwner`, `projectNumber`,
+`projectId`, `statusFieldId`, `statusOptions{}`, and optional Priority field ids), set by `/bootstrap`
+(repos and projects are not 1:1 — a repo attaches to a chosen project). Refresh the registry META if a
+lookup misses; do not read or repair committed repo-local board config.
+
+## Step 1 — read the board (one call, caller-scoped)
+
+SessionStart injects a **bounded board slice** (assigned + top claimable items, max five lines,
+3s timeout, fail-soft) and, when task relevance is high-confidence, up to **two North Star context
+cards** (title + compact intent, PRIOR-not-instruction framing — silent when ambiguous). For the
+complete partition — secondary repos, taken items, bundle details — run the full command below.
+
+```bash
+mmi-cli board read --json
+```
+
+This is the **only foreground call** on the happy path for **work items** (not identity — Step 0 already
+resolved login). Its JSON carries `viewer`, `repo`, and the project title — do **not** run separate
+`gh api user` / `gh repo view` calls; they just delay the board. If `repo` is missing from the JSON,
+keep the board header generic. The CLI resolves the project from the Hub registry; to inspect it
+directly, `mmi-cli project get --json`.
+
+Use the returned `primary` group for current-repo items and `secondary` for other repos on the same Project.
+Within each group, render `userOwned`, `claimable`, and `taken`.
+
+CLI partition:
+- **Yours** — assignee includes the viewer AND `Status ∈ {Todo, In Progress, In Review}`.
+- **Free to claim** — `Status == Todo` AND unassigned AND the viewer has repo write permission
+  (`repos/<owner>/<repo>.permissions.push == true`). Issue filing stays available to any authenticated
+  org member; claiming work is gated by write access.
+- **Taken** — assigned to someone else (any active status). Render id + status + owner ONLY — no title.
+
+Do not cache claimable state. Every `/mmi` board is a fresh Project v2 read. Partial reads exit nonzero by
+default; use `--allow-partial` only when the dev explicitly accepts an incomplete board. If the read fails
+for a missing `read:project` scope, surface that verbatim — the dev grants it once at `gh auth login`.
+
+## Step 2 — show the board
+
+This render is the product: welcoming, guiding, clear — and gone in one glance. Plain **markdown**,
+never a fenced code block (monospace hard-wraps long titles and the structure is lost). The shape:
+
+- **Short refs.** `[RepoName#N](issue-url) · short title` — repo name + number only, no `owner/`
+  prefix, no `[type]` brackets. The ref is the clickable link; the title follows after `·`, trimmed
+  to its essence (drop boilerplate prefixes, keep it under ~8 words).
+- **Flat `-` lists** under bold head lines — never `##` headings (too heavy for a three-section
+  board), never nested bullet trees, never tables, never a literal `•` glyph (it breaks GFM list
+  parsing).
+- **Three heads, each with one factual clause** appended after an em dash — a fact the dev can act
+  on ("two train fixes in flight"), not cheerleading. Encouragement lives once, in the close.
+  - **On your plate** — the dev's items, status noted inline after the title (`· in review`) when
+    not In Progress. In Review means *awaiting admin review & merge* — caption it that way, never
+    "ready to move".
+  - **Up for grabs** — claimable items.
+  - **Taken** — id · status · owner ONLY, never the title. No commentary clause; it's reference.
+- **Skip empty sections silently** — no "nothing here" filler. Empty board entirely → one warm line:
+  nothing assigned, point at Up for grabs or filing a new item.
+- **Close with one grounding line** — no question, no hype, no pressure: `Pick one and claim it
+  when you're ready.` plus the standing quiet affordance `Or file a new item — say the word.`
+- **One screen total.** Greeting + sections + optional Leverage (Step 6) + close.
+
+Full example (greeting printed earlier, before the read):
+
+> 👋 Welcome back, @dev — here's your board on **MMI-Hub**.
+>
+> **On your plate** — two train fixes in flight:
+> - [MMI-Hub#834](https://github.com/mutmutco/MMI-Hub/issues/834) · automated hotfix apply path
+> - [MMI-Hub#841](https://github.com/mutmutco/MMI-Hub/issues/841) · rcand stuck on required checks
+>
+> **Up for grabs** — ready when you are:
+> - [MMI-Hub#821](https://github.com/mutmutco/MMI-Hub/issues/821) · redesign tenant env-writer
+> - [MMI-Hub#839](https://github.com/mutmutco/MMI-Hub/issues/839) · revisit hotfix back-merge policy
+>
+> **Taken**
+> - MMI-Hub#827 · In Progress · @otherdev
+>
+> **Leverage**
+> - #834 and #841 are both train-lane — I can run them side by side, one PR each.
+>
+> Pick one and claim it when you're ready. Or file a new item — say the word.
+
+Only an admin merges (a project-admin on their own project, the master-admin everywhere); the dev who
+opened the PR waits on that review, they don't move it themselves.
+
+## Step 3 — stop (act only on request)
+
+Render the board and stop. Don't prompt for a choice, don't recommend a next move, don't ask "what now?".
+The dev drives: when they say claim / continue / file — or accept a Leverage offer (Step 6) — do it.
+Otherwise the board alone is the answer.
+
+**Status moves happen automatically** as the work flows (claim, PR open, merge, release). The dev never
+moves an item by hand, so **never suggest a status move** — not "advance to Test", not "mark this PR",
+not "ready to move?". The board reflects state; it doesn't ask the dev to change it.
+
+The one standing affordance is **filing a new item** — always available, no item needed. The Step 2
+close line already carries it (`Or file a new item — say the word.`); never turn it into a status
+nudge. If the dev takes it, run the guided flow in Step 5.
+
+## Step 4 — load the full item before working it
+
+The moment the dev commits to an item (continue or claim), read the **whole** work item before planning or
+acting — never from the board title alone. Body **and every comment**, end-to-end; treat later comments as
+potentially **superseding** the body. Only then greet into the work or propose a plan.
+
+```bash
+# One shot — status, assignees, type, body, and every comment for one board item:
+mmi-cli board show <owner/repo#N>          # add --json for machine-readable output
+```
+Fallback for an item not on the board (or raw `gh`) — use `--json`, not `--comments`: in a non-TTY
+shell (every agent/CI context) `gh issue view --comments` prints only the comments and hides the body,
+and prints nothing at all on a zero-comment issue.
+```bash
+gh issue view <N> --repo <owner/repo> --json title,body,comments \
+  --jq '.title, .body, (.comments[] | "--- @\(.author.login):", .body)'
+```
+
+> **Never reach for standalone `jq`** — it isn't installed on Windows dev machines, so each attempt burns a
+> failed call (#230). `mmi-cli board read|show` is already human-readable (drop `--json`); to parse JSON use
+> `gh`'s **built-in** `--jq` (as above) or `mmi-cli … --json` piped to `node`.
+
+(Triggers only when a dev commits to an existing item — no-op for the *report a bug / request a feature /
+something else* paths.)
+
+## Step 5 — act
+
+- **Claim:** when the dev takes an item, assign them + set `In Progress` in one go. This is the only status
+  write `/mmi` makes, and only as the mechanical side of claiming — never as a standalone "move" the dev
+  is offered. Every later transition (In Review on PR open, Done on merge) flows automatically from the
+  work, not from here.
+  ```bash
+  mmi-cli board claim <owner/repo#N> --json
+  ```
+  The command validates `Todo` + unassigned, assigns the viewer, and moves the Project v2 `Status` to
+  `In Progress`. A partial claim exits nonzero unless the dev explicitly accepted `--allow-partial`.
+  Claiming several items (batch/parallel act-paths) takes them in **one call** — `board claim <ref> <ref> …`
+  — which shares the setup cost and reports per-item results (any per-item failure → nonzero exit).
+- **File a new item (guided by type → template):** don't free-type an issue. Walk the dev through it:
+  1. **Pick the type** — `bug` · `feature` · `task` (the repo's three `.github/ISSUE_TEMPLATE/` forms;
+     each carries its own label). Offer the choice with the structured-question UI, one line each:
+     bug = something's broken · feature = new capability · task = chore/improvement.
+  2. **Fill that type's template.** Read its fields from `.github/ISSUE_TEMPLATE/<type>.yml` and gather
+     answers from the dev for each — draft where you can, ask where you can't (the template form is
+     interactive and won't drive in a non-TTY agent shell, so collect the fields, then create directly).
+  3. **Submit via `mmi-cli issue create`** — the canonical create path. It maps `--type` to the label,
+     requires `--priority` (which sets the board Priority **field**, never a `priority:*` label — #416),
+     prints `{number,url}` JSON, and fails loud on a misfire (never use
+     `gh issue create --json` — that
+     flag does not exist on `create`, errors, and silently misfires):
+     ```bash
+     mmi-cli issue create --type <bug|feature|task> --title "<title>" --body "<filled template>" \
+       --priority <high|medium|low>
+     ```
+     For long markdown, use `--body-file <path>` or pipe UTF-8 markdown with `--body-file -`; never fall
+     back to `gh issue create`.
+     The command starts bounded related-issue discovery off-path. It auto-comments only high-confidence,
+     idempotent links. To inspect candidates manually before writing anything else:
+     ```bash
+     mmi-cli issue discover-related --repo <owner/repo> --number <number> --title "<title>" --body "<body>" --json
+     ```
+  It lands on the board as Todo automatically — confirm the link from the JSON. (Templates differ per
+  repo; read the actual `.yml` set rather than assuming bug/feature/task.)
+- **File a friction report (org-tooling pain):** `mmi-cli report --title "<one-line>" --body "<what hurt>"`
+  files it on the Hub board with your GitHub identity and dedups against the open reports (a confident
+  duplicate becomes a +1 comment, not a new issue). Never read Hub coordinates or keys from a repo-local
+  `.env`, call a repo-local report script, or POST the Hub API directly — the CLI carries the endpoint
+  and your `gh` identity intrinsically.
+- Surface any `gh`/`mmi-cli` error verbatim.
+
+## Step 6 — Leverage (offer where it fits)
+
+`/mmi` is an agentic coding board — every item is written by an LLM agent, so the board can do more than
+hand over one item at a time. Between the Taken section and the close, render an optional **Leverage**
+block: **up to two** offers, one line each, under a bold `**Leverage**` head (see the Step 2 example).
+**Default to silence:** if nothing below crisply fits, omit the whole block — never pad it. Never use a
+question-UI, never pressure — the dev acts or ignores.
+
+Pick up to two, in priority order:
+
+1. **Split + fan out** — a single item plainly too large for one PR (body is multi-part, an umbrella or
+   epic). Offer to slice it into child issues. (First because it *creates* the items the rest act on.)
+2. **Batch** — 2+ claimable items that are one coherent unit (shared title-prefix family, same subsystem)
+   **and** touch overlapping/adjacent paths. Coupled → one worktree, **one PR**.
+3. **Parallel** — 2+ items that are mutually independent and touch **disjoint paths**. Independent → N
+   worktrees, **one PR each**, run concurrently.
+4. **Background** — a single long-running item (broad refactor, large build/sweep). Kick it off in the
+   background so the dev isn't blocked.
+
+Disjoint paths is the deciding signal between batch (overlap → one PR) and parallel (disjoint → N PRs).
+When unsure which fits, prefer the more conservative offer — a marginal call is worse than a quiet board.
+Two offers must not overlap (never the same item in both); a second marginal offer is worse than one
+crisp one.
+
+Bundling detail boundary: start from the metadata board. Only if there are multiple viable
+`userOwned`/`claimable` candidates, fetch bodies/comments with:
+
+```bash
+mmi-cli board read --json --bundle-details
+```
+
+That detail path may fetch bodies/comments only for `userOwned` and `claimable` issues. `taken` stays
+metadata-only, always. Do not fetch Done items, do not cache claimables, and do not pass `--allow-partial`
+unless the dev explicitly accepts an incomplete Leverage read. If detail lookup exits nonzero, render
+the board without a Leverage block.
+
+Offer lines — one line each, no UI, no "(Recommended)", phrased as available leverage:
+
+- **Batch** — `These read like one change — I can take #66–#70 together in a single PR if you'd like.`
+- **Parallel** — `#17 and #18 are independent — I can run them side by side, one PR each, if that helps.`
+- **Background** — `#22 looks long-running — I can take it in the background so you're not blocked.`
+- **Split** — `#60 looks large — I can slice it into child issues and fan them out, if you want.`
+
+Act-paths run only on the dev's explicit go. Every path branches from `development` and lands by PR.
+PR land cleans up at the branch boundary (`git worktree remove` + `git worktree prune`); batch/session
+work should keep all related sequential issues in the same branch/PR where possible instead of merging and
+destroying the worktree after each issue:
+
+- **Batch:** one worktree, claim each item (the Step 5 claim loop), make the coupled edits, open **one** PR
+  (`Closes #…, #…`).
+- **Session/sequential:** multiple related same-repo items handled one after another in the same session
+  reuse the active worktree until the session or execution group ends; do not churn one worktree per
+  issue unless a branch/PR boundary, true parallelism, or explicit user ask requires it.
+- **Parallel:** one isolated worktree per item, cut from `development`, run concurrently, **one PR per
+  item**. If two would touch the same file, serialize them or fold into a batch instead.
+- **Background:** run off the hot path (a background task or CI job); poll with `/loop`, test with `/stage`
+  if useful; it still lands via its own worktree + PR. Bound it — never block silently.
+- **Stage/worktree:** a local `/stage` is tied to the worktree that started it. Stop/destroy and recreate
+  it before moving to another worktree, or warn first when intent is unclear.
+- **Split:** keep the original as the umbrella; file each child as a **native sub-issue** of it with
+  `mmi-cli issue create --parent <umbrella-ref> …` (or `mmi-cli issue link-child <umbrella> <child>` for a
+  child that already exists). The parent then renders a sub-issue checklist with each child's state and the
+  child renders its parent — no title prefix or body task-list to maintain. Refs are `#NN`, `owner/repo#NN`,
+  or a URL, and it works cross-repo (a Hub umbrella can track product-repo children). Get the dev's go before
+  filing the children; each child then becomes a parallel item. **When the last child merges, close the
+  umbrella** — its `Done` follows automatically.
+
+## Notes
+
+- Reads/moves use **your** `gh` token (needs `read:project`/`project`, granted once at `gh auth login`).
+- Promotion (`/rcand`, `/release`, `/hotfix`) and the local test env (`/stage`) are their own skills — `/mmi`
+  is the board + start-of-work, not the train.
+- **Board verbs:** `board read` · `board show <id>` · `board claim <id>` · `board move <id> <status>` ·
+  `board done <id>`. `move`/`done` exist for an agent's own mechanical bookkeeping when **no PR rides the
+  automation** — e.g. setting `Done` on a no-PR `task` or closed-out item that won't auto-advance. They are
+  tools, not a dev-facing offer: the "never suggest a status move" rule (Step 3) still governs the human
+  flow. Each verb hides the `gh project item-edit` + option-id wiring, so reach for the verb, not raw `gh`.
+
+## 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 board read that misreported what's
+claimable, or a claim that moved the wrong item.) 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 mmi --title "<what misfired>" --body "<what; evidence; proposed amendment>"`