mnm-onboard

name	mnm--onboard
description	Guide the user through first-run bootstrap of the MnM Governed Workflows plugin — calls setup_workspace, writes agent files, prompts /reload-plugins, and runs a verification push_local_state. Use when the user installs the plugin, runs /mnm--onboard explicitly, or asks how to "get started with MnM".

MnM Onboarding

You are guiding a user through first-run setup of the MnM Governed Workflows plugin. Execute these steps in order — do not skip or reorder.

Step 1: Confirm authentication

Before any MCP call, verify the user is authenticated. Attempt:

mcp__mnm__authenticate

If it returns already_authenticated, continue. If it returns an auth URL, wait for the user to complete the OAuth flow, then call mcp__mnm__complete_authentication with the returned code.

If the user has multiple company memberships, the OAuth flow will return invalid_request with available_companies[]. Ask the user which company_id to use and re-attempt authentication with that value.

Step 2: Call setup_workspace

mnm.setup_workspace

The response shape:

{
  "agents": [
    { "name": "mnm--<id>", "content": "...", "sha": "...", "target_path": "~/.claude/agents/mnm--<id>.md" }
  ],
  "session_tools": [...]
}

Step 3: Write every agent file

For each entry in agents[], use the Write tool with file_path = target_path and content = content. Expand ~ to the user's home directory resolved from the Claude Code harness environment (on Windows: $HOME maps to C:\Users\<username>).

Do not batch the writes in a single tool call — call Write once per agent. Report progress as you go.

Step 4: Prompt /reload-plugins — MANDATORY

After all writes succeed, emit exactly this message to the user:

Action required — I've written N agent files to ~/.claude/agents/. Claude Code does not hot-reload these mid-session. Please run /reload-plugins now and then send me any short message (even "ok") so I can continue.

STOP. Do not proceed to Step 5 until the user confirms.

Step 5: Persist plugin version cache

After the user confirms, call:

mnm.push_local_state  with  { plugin_version: "<version from plugin.json>" }

The response is { target_relative_path: "last-session.json", content: { lastPluginVersion: "<version>" } }. Write content to ${CLAUDE_PLUGIN_DATA}/last-session.json so the SessionStart hook can detect plugin upgrades on the next session and prompt re-sync.

Step 6: Offer next steps

Tell the user onboarding is complete and list two options:

1. "Launch the hello-world workflow" — call mnm.list_governed_workflows, pick the hello-world entry, then mnm.launch_governed_workflow, then walk through each step with mnm.launch_governed_step.
2. "Install a custom workflow" — direct them to docs/superpowers/specs/2026-04-20-governed-workflows-mvp-design.md.

Error handling

• AGENTS_STALE from launch_governed_step after onboarding means the user skipped Step 4. Ask them to run /reload-plugins and retry.
• MISSING_TOOLS means the plugin is misconfigured — surface error.data.required[] verbatim and stop.
• Any other error: surface error.code and error.hints[] verbatim; do not attempt to recover silently.