@mutmutco/kilo-plugin 3.79.0

package/skills/mmi/SKILL.md

@@ -0,0 +1,400 @@
+---
+name: mmi
+description: Show, claim, move, or file work on the repo board.
+---
+
+# 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.
+
+Explicit invocation is host-native: `/mmi:mmi` in Claude Code, `$mmi:mmi` in Codex, `/mmi`
+(canonical `/skill:mmi`) in Kimi Code CLI, and the `mmi` skill (listed in Kilo's `/` picker, invoked via
+the `skill` tool) in Kilo Code. The `/mmi` label used below names this workflow; it is not a
+universal literal command.
+
+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. **Keep the board fast: read first, run doctor only when evidence says it can change this render (#2112).**
+   The normal happy path is identity → board read. Do **not** block the board on `doctor --preflight` just to
+   check freshness. Run doctor synchronously only after a hard signal that the current setup may be broken:
+   `mmi-cli` is missing, `board read` reports missing auth/project scope, the command surface is absent, or a
+   cached/session-start health line explicitly says a heal is needed.
+
+```bash
+mmi-cli board read --json    # Step 1 — first useful render on the happy path
+mmi-cli doctor --preflight   # only after a hard setup signal — foreground, one at a time
+```
+
+Since #3485 `--preflight` **heals**: its heals are `npm install -g` and a marketplace remove → add →
+install, both machine-global. Since #3489 they are serialised behind a machine-wide lock, so two
+concurrent preflights no longer interleave inside the npm prefix or the marketplace clone — the second
+waits, and if the first is still installing after two minutes the second reports the heal as skipped
+rather than forcing it.
+
+Still run it in the foreground and wait. The lock stops corruption, not confusion: a backgrounded
+preflight that reports "skipped — lock busy" has healed nothing, and an agent that does not read that
+line will carry on believing its tooling was fixed.
+
+`doctor --preflight` detects a stale npm global or a stale/unresolved plugin install and runs the **env**
+half of the interactive `doctor --apply` self-heal (#3485) — it never touches the repo working tree, and
+never pays the train-branch sync or the gc sweep. It still belongs off the critical board path unless it
+has proof it must heal. When it prints `↻ Updating mmi tooling, one moment…`, relay that before waiting;
+when it prints `↻ MMI tooling updated — …`, relay the reload/restart guidance.
+
+What it actually heals, and nothing more:
+
+- a behind npm global → `npm install -g @mutmutco/cli@<released version>`, pinned, never the floating
+  `@latest`, which npm can resolve off a cached packument and reinstall the stale version right after a
+  publish (#3422). Effective on the next invocation.
+- a stale or unresolved Claude plugin → `claude plugin marketplace remove mmi` → `… 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). Effective after a reload: **restart Claude Code / run `/reload-plugins`**
+  (native), or **reopen the workspace** (VS Code extension).
+
+It does **not** dedup `installed_plugins.json` rows and does **not** quarantine cache dirs — that
+machinery was deleted in #2741 and `doctor` is doctrine-bound never to write to the harness-owned plugin
+cache. Stale cached versions are a detect-only row; the verb that deletes them is `mmi-cli plugin prune
+--apply`.
+
+- **Fast path** → `whoami` then `board read`; no foreground doctor.
+- **Hard setup signal** → run `doctor --preflight`, relay `↻` lines, then retry `board read` when appropriate.
+- **`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`.
+  On Codex, install the Hub-shipped plugin: `codex plugin marketplace add mutmutco/MMI-Hub` →
+  `codex plugin add mmi@mutmutco`, then trust the bundled hooks via `/hooks`. On Kimi Code CLI:
+  `/plugins install https://github.com/mutmutco/MMI-Hub` → `/reload`. On Cursor, run
+  `mmi-cli plugin heal`, then reload the Cursor window. On OpenCode and plain shell the standalone CLI
+  is the whole install:
+  ```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
+  ```
+- **The host-native skill entry is missing** — `/mmi:mmi` is absent in Claude, `$mmi:mmi` is absent in
+  Codex, or `/skill:mmi` is absent in Kimi (the auto-heal below is Claude-only; Codex and Kimi ship the
+  same skills but repair is a manual reinstall — see their recipes above) → the plugin is stale,
+  duplicated, or disabled, so the skill surface is gone and you can't reach this workflow through the
+  host UI. Recover from the shell with the repo-local doctor, which detects and 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 reinstall 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)
+  ```
+- **A gate is ✗** → walk them through the printed fix; don't just echo it:
+  - **GitHub auth** (the usual one) — the board uses its `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 org 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 org 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`, `runtime 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 org 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
+```
+For an item **not on the board**, `mmi-cli issue view <N> --comments` is the board-independent one-shot:
+it returns the body **and** every comment as JSON in a single call (add `--context` for `linkedPrs` and, on
+an epic, a `children` summary). Prefer it over raw `gh issue view --comments`, which in a non-TTY shell (every
+agent/CI context) prints only the comments, hides the body, and prints nothing at all on a zero-comment issue.
+```bash
+mmi-cli issue view <N> --repo <owner/repo> --comments   # body + every comment, one call
+```
+
+> **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
+> `mmi-cli … --json` piped to `node`, or `gh`'s **built-in** `--jq`.
+
+(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. Before filing, read the live
+     `issue create` entry from `mmi-cli commands --json`; flags change, and a missing documented flag means
+     the installed CLI is stale until a fresh local build proves otherwise. It maps `--type` to the label,
+     `--priority` sets the board Priority **field** (never a `priority:*` label — #416), and `--surface`
+     supplies the repository's required single surface label. It always prints `{number,url}` JSON. Never
+     use `gh issue create`; it bypasses these board contracts:
+     ```bash
+     mmi-cli issue create --type <bug|feature|task> --title "<title>" --body "<filled template>" \
+       --priority <high|medium|low> --surface <surface>
+     ```
+     For long markdown, materialize a temporary UTF-8 body file, pass its real path with
+     `--body-file <path>`, then remove it after the write succeeds. Do not pipe multiline markdown to
+     `--body-file -` on a guarded host.
+     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 via your Hub session and dedups against the open reports (a confident
+  duplicate becomes a +1 comment, not a new issue). The actual GitHub write runs server-side with the
+  Hub App's own token (#263), so no MMI-Hub repo access is required to file. 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 Hub session 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:
+
+- **PR metadata:** read the live `pr create` or `pr edit` entry from `mmi-cli commands --json` before the
+  write. For multiline Markdown, materialize a temporary UTF-8 body file, pass its real path with
+  `--body-file <path>`, and remove it after the write succeeds. Do not pipe the body to `--body-file -`;
+  host prose guards require the materialized-file path.
+- **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 <status> <id>`.
+  `move` exists 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 will not auto-advance. It is a tool, not a
+  dev-facing offer: the "never suggest a status move" rule (Step 3) still governs the human flow. The verb
+  hides the `gh project item-edit` + option-id wiring, so reach for it, 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>"`

package/skills/onboard/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: onboard
+description: Guided first session — readiness check, repo status, and the first command to run.
+---
+
+# /onboard — guided first session
+
+For a developer's first session in a repo (or a fresh checkout): confirm the repo is wired into the org,
+show what state it's in, and hand over the one concrete next command. Read-only — it diagnoses and points,
+it does not change anything.
+
+## Step 0 — readiness gate
+
+```bash
+mmi-cli onboard
+```
+
+`onboard` reports the five things a machine needs to be workable and the exact next command to fix the
+first gap:
+
+- **Track** — the repo's branch + origin (is this an org checkout at all).
+- **Board** — is the Project board reachable, and how many items are on it.
+- **Registry** — is the repo registered in the Hub (`PROJECT#<slug>` META).
+- **Secrets** — is a GitHub token available for the vault path.
+- **Plugin** — will this machine ever pick up a new MMI plugin release, and from which branch (#3485).
+
+The **Plugin** row is the one nothing else catches, and it is per machine, not per repo. Claude Code
+leaves auto-update **off** for third-party marketplaces, and a marketplace registered with no
+`source.ref` serves its catalog from the repo's default branch while pinning plugin content to `main`.
+Both are hand edits in the developer's own Claude config — org tooling deliberately does not write them
+(owner ruling on #3485) — so a machine nobody tells stays silently a release behind from day one. The row
+names both fixes verbatim; it never takes `Next command`, because a stale plugin does not stop the work in
+front of you.
+
+A `✗` on any line comes with a `Next command:` — run **that** first. Common ones:
+
+- Hub API URL not configured → `mmi-cli doctor` (fix wiring).
+- Repo not registered → a master-admin runs `/bootstrap` (or `mmi-cli org project set <owner/repo>`).
+- GitHub auth missing → the dev runs `gh auth login --hostname github.com --git-protocol https --web --scopes "project"`.
+
+## Step 1 — the picture
+
+Once the gates are green:
+
+```bash
+mmi-cli status        # branch, worktrees, your PRs, your claimed items, stage
+mmi-cli next          # the first claimable item + its claim command
+```
+
+## Step 2 — hand over the first move
+
+Close with one grounding line: gates green (or the one gate to fix), and the single first command —
+usually `mmi-cli board claim <n>` for the recommended item, or the readiness fix if a gate is red. Don't
+claim on the user's behalf; let them take the first item when ready.
+
+## Notes
+
+- `/onboard` is the first-session, readiness-first wrapper. Once a repo is known-good, `/resume` is the
+  faster daily open and `/mmi` is the board.
+- Everything here is read-only. The heavier setup (`/bootstrap`) is master-admin only.
+
+## 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 readiness gate that reported green while a
+board read actually failed, or a next command that pointed at the wrong fix.) 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 onboard --title "<what misfired>" --body "<what; evidence; proposed amendment>"`