| 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:
- "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.
- "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.
