mx-handoff

name

mx-handoff

description

Generate copy-paste-ready Studio Pro instruction sheets for the rare moments when only a human can perform the action (drag a widget, set a CSS class, configure a layout). Reads the project's theme catalog and widget conventions to produce EXACT instructions -- specific paths, classes, widgets, bindings -- not vague guidance. Auto-invoke when an automated path is blocked and a human-in-loop step is required. Also invocable as /mx-handoff <task-description>.

mx-handoff

The "human in the loop, but make it precise" primitive. When automation hits a wall (mxcli widget commands are alpha; Maia can't do everything; some clicks just need a person), this skill produces an instruction sheet Neo can execute mechanically -- no inference, no guessing, no context-switching to figure out which class to apply.

North star

If a human must touch the UI, hand them a script, not a description.

The friction this skill exists to remove: "go set the theme class on the container in CustomerDetail" -> Neo opens Studio Pro, hunts for the container, can't remember the right class, asks Claude, pastes the class, Claude says "make sure it's on the OUTER container," repeat. Total: 10 minutes of friction. Replace with: a 7-step copy-paste sheet that takes 90 seconds.

When to invoke

Auto-invoke when:

• An automated workflow hits a step only Studio Pro UI can perform (e.g., drag a specific widget into a layout slot Maia can't target).
• Neo asks "what do I need to click in Studio Pro to do X."
• A /mx-page-from-prototype or similar high-level skill needs a human handoff for one step.

Do not invoke for:

• Tasks that can be done via mxcli or Maia. Try those first; this skill is the last resort.
• General "how does Studio Pro work" questions. Use the mendix-expert subagent for those.

What it does

1. Verify project + testbed.
   • Resolve project root (containing *.mpr).
   • Check against ~/.claude/rules/mendix-testbed.md allowlist. Refuse if not allowed.
2. Inventory the relevant context (parallel reads):
   • Theme catalog: scan theme/<theme-name>/ for class definitions. Build a quick "available classes" lookup.
   • Page templates: list well-built reference pages in the project.
   • Widget conventions: any project-specific widget rules in .claude/rules/ or local CLAUDE.md.
3. Translate the task into exact mechanical steps. Each step must include:
   • WHERE in Studio Pro (Project Explorer path: Module -> Pages -> PageName).
   • WHAT to click / drag (widget palette path: Containers -> CardActionable).
   • EXACT values (class names, entity bindings, attribute names) -- never "the right class," always "card card-primary p-3 mx-customer-row."
   • WHEN to save (Ctrl+S after each non-trivial change, not at the very end).
4. Produce the sheet:

## /mx-handoff: <task summary>

**Project:** <root path>
**Theme:** <theme name>
**Estimated time:** <e.g., "90 seconds">

### Steps

1. Open Studio Pro.
2. Open project: <full project root path>
3. In Project Explorer, navigate to: <Module> -> Pages -> <PageName>
4. Open page: <PageName>
5. <specific click / drag / set>
   - Path in widget palette: <Containers -> CardActionable> (or whatever)
   - Drop location: <e.g., "row 2, column 1, inside the existing dataView for entity Customer">
   - Set CSS class to: `<exact class string>`
   - Bind to: <Module.Entity.Attribute>
6. Save: Ctrl+S
7. <repeat for each widget...>
8. Close Studio Pro (so the safety pillars allow follow-up CLI ops).
9. Reply "done" -- I'll run /mx-doctor + Playwright suite to verify.

### Verification I will run after you reply "done"

- /mx-doctor (mx check + mxcli lint)
- /mx-impact <new widget binding> (sanity-check no surprises)
- Playwright test: <test name if applicable>

### If you get stuck

- Studio Pro can't find the widget? It may not be in the standard palette -- check Add-ons -> Widgets.
- Class doesn't exist in your theme? Tell me the closest class you DO see; I'll either correct the instruction or create the class via theme work.
- Page won't save (validation error)? Read me the error verbatim; do NOT click "Save anyway."

5. Stop and wait for "done."
6. On "done", run the listed verification automatically. Report results.

Hard rules

• Every value must be exact. "Set the right class" is banned; "Set CSS class to card card-primary p-3" is the standard. If you don't know the exact value, find it (read theme/, ask /mx-search) before producing the sheet.
• Refuse to produce a sheet against a non-allowlisted project. Use the mendix-testbed refusal block.
• Always include the Studio-Pro-close step before automated follow-ups. Otherwise the next CLI op will trip the lock check.
• Always include the post-handoff verification list. The human knows what's about to happen.
• Never invent class names. If the theme doesn't define the class you'd want, propose creating the class in a separate step; do not put unverified classes in the handoff.
• Cap each handoff at one logical task. "Add a card" is one task; "redesign the page" is many. Refuse multi-task handoffs and ask Neo to scope it down.

Anti-patterns this skill exists to prevent

• Vague instructions: "configure the container appropriately."
• Class hallucination: telling Neo to set card-primary-large-v2 when the theme has no such class.
• Forgetting Save: skipping Ctrl+S so the change is lost when Studio Pro is closed.
• Forgetting to close Studio Pro: causing the next mx-shadow-write op to fail the lock check.
• No verification follow-up: leaving Neo to wonder if the change worked.

Cross-reference

• Allowlist: ~/.claude/rules/mendix-testbed.md.
• Health check (run after handoff): ~/.claude/skills/mx-doctor/SKILL.md.
• Impact check (run after binding changes): ~/.claude/skills/mx-impact/SKILL.md.
• Mendix specialist: ~/.claude/agents/mendix-expert.md.
• Theme backup (run before any theme-class work): ~/.claude/lib/Backup-MendixTheme.ps1.