MendixToolkit

Mendix-aware overlay for Claude Code. Adds a conversational Mendix executor (the Agent Army v1), domain-aware reviewers, project-parameterized inventory, doctrine rules, the shadow-write engine, and Maia/Studio-Pro integration on top of NewClaude. Last major redesign 2026-04-29.

---

What this gets you

You type a Mendix imperative — "build a customer detail page like RequestSource_Dashboard," "audit ContentPortal_Home," "add a Status attribute to Customer."

The user-prompt-submit.ps1 auto-routing hook spots the Mendix-shape pattern and routes the request to mendix-doer — the conversational executor. It runs the entire skill chain end-to-end: discover → orchestrate → preflight gates (allowlist + Studio Pro state + MCP health) → route to the right gated-write skill → fan out 4 reviewers in parallel (mendix-domain-model-reviewer, mendix-microflow-reviewer, mendix-design-system-reviewer, mendix-theme-reviewer) → loop fix-and-recheck up to 3 iterations on BLOCK → run /mx-page-audit + /mx-test-page for UI changes → return one shaped report with cited verdicts.

Stops only at genuine decisions you have to make:

• Project not on the testbed allowlist (refusal).
• Studio Pro is open on a non-testbed (live) project.
• HIGH-risk migration (entity rename, cardinality flip, type change with data).
• 3-iteration cap hit on persistent BLOCKs.
• The phrasing was actually a question, not a request — falls back to mendix-expert.

To opt out per-prompt: include cancel routing. Globally: $env:MENDIX_DOER_AUTO=0.

---

Architecture at a glance

Three orchestration tiers

| Tier | Agent | What it does | |---|---|---| | Conversational executor | mendix-doer (machine-level) | The "do it for me" layer. Auto-routed by hook on imperative-shape Mendix prompts. Runs the 8-phase pipeline end-to-end. | | Planner | mendix-orchestrator (project-local) | Senior-partner planning. Fans out parallel research; synthesizes a multi-step plan with risk classification + rollback path. Spawned by the doer in Phase 2; also callable directly for non-trivial questions. | | Reviewers (×4, parallel) | mendix-domain-model-reviewer · mendix-microflow-reviewer · mendix-design-system-reviewer · mendix-theme-reviewer | Each reads its diff + relevant rules + relevant MCP tools, returns a fixed-shape PASS / FLAG / BLOCK verdict block with cited findings. Spawned in one parallel Agent batch by the doer post-write. |

Knowledge tier

| Agent | Use for | |---|---| | mendix-expert | "How does X work in Mendix?" — domain Q&A with citations | | mendix-researcher | Beast-mode external research; reads ~/.claude/wiki/pages/mendix/sources.md, caches into wiki/pages/mendix/feed/<source>/<date>.md. Driven by scheduled MxcliNightlyWatch + on-demand from doer. | | studio-pro-extensibility | Three-surface decision tree (Model SDK vs Web Ext API 11.10.0 vs C# Ext API 11.8.0 beta). Use when picking which extension surface to target. |

MCP servers

| Server | Transport | Tools | Purpose | |---|---|---|---| | mendix-context | stdio + HTTP (port 9123, scheduled task) | 9 | Theme catalog, OS2 class buckets, design properties, gold pages, testbed fingerprints. Used by mendix-design-system-reviewer for grounding. | | mendix-inventory | stdio (registered user-scope, project-parameterized via MENDIX_PROJECT_ROOT) | 31 | Deep context on entities/pages/microflows; change_impact, call_graph, entity_usage_map, scss_audit, project_health, spec_check, more. Salvaged 2026-04-29 from ClaudeOrchestrator/onesource-inventory; renamed and parameterized so it serves any Mendix project. | | playwright | stdio + HTTP (port 8931, scheduled task) | 21 | Browser automation for /mx-test-page testbed verification with the TEST APP ribbon fingerprint guard (URL :8082 + getComputedStyle(document.body, '::after').content contains "TEST APP"). |

Always-loaded doctrine rules

| File | Always-loaded purpose | |---|---| | mendix-os2.md | OS2 class system + 100% never-SmartHub rule + class lookup decision tree | | mendix-safety.md | The 7 safety pillars (Studio Pro lock check → byte-level snapshot → version >= 11.6 → pre-mx check clean → diff preview → post-mx check validation → auto-restore on fail). NO git on Mendix projects, ever. | | mendix-testbed.md | Allowlist (TestOSApp3 only by default) + the testbed fingerprint guard ("TEST APP" via body::after, NOT in AX tree) | | mendix-cli.md | mxcli rules: alpha-quality warning, capability matrix, Studio-Pro-must-be-closed precondition | | mendix.md | General Mendix doctrine | | mendix-mcp.md | How MCP tools are used (3-tier research, testbed grounding) | | mendix-verification-matrix.md | Per-change-type verification chains (SCSS / domain model / microflow / page / widget / cross-cutting). The doer's Phase 7 routes against this. | | onesource-mcp.md | Project-specific gotchas for the OneSource MCP (auth headers, env selection) |

Skills

Project-local (under .claude/skills/, load when MendixToolkit is cwd):

• /start-here — first-message orchestrator; health check + 3 ranked next steps
• /next-step — mid-session continuation
• /workflow — named recipe runner against WORKFLOWS.md

Deployable overlay (under claude/skills/, deployed to ~/.claude/skills/ via install.ps1):

• /mx-discover · /mx-impact · /mx-search · /mx-doctor · /mx-version — read-only inventory
• /mx-page-audit · /mx-test-page · /mx-design-review — verification
• /mx-feature-spec · /mx-handoff — spec/handoff generation
• /close-studio-pro — graceful Studio Pro shutdown + orphan-toolchain cleanup
• /mx-entity-add · /mx-scaffold-microflow · /mx-page-clone-from-template — gated writes (route through 7 safety pillars)
• /maia-mcp-bridge — closes the stdio↔Maia gap; emits HTTP wrapper + Studio-Pro Maia config sheet for any stdio MCP

Auto-routing + scheduled automation

• ~/.claude/hooks/user-prompt-submit.ps1 — detects Mendix imperatives, routes to mendix-doer. Conservative regex; questions pass through. Escape hatch: cancel routing per-prompt or $env:MENDIX_DOER_AUTO=0 per-session.
• \MendixToolkit\MxcliNightlyWatch scheduled task (daily 06:00) — runs Watch-MxcliNightly.ps1, diffs mendixlabs/mxcli releases against ~/.claude/state/mxcli-last-seen-tag.txt, appends to ~/.claude/wiki/pages/mendix-cli/changelog.md, toasts on breaking changes.
• \MendixToolkit\MendixContextHttp + \MendixToolkit\PlaywrightHttp at-logon scheduled tasks — keep the HTTP MCP servers up for Maia.
• \MendixToolkit\MendixThemeBackup weekly Sunday 09:00 — periodic theme tree snapshot.

---

Install

# 1. Install NewClaude first (the generic harness)
git clone https://github.com/jordnlvr/NewClaude.git C:\Workspace\NewClaude
cd C:\Workspace\NewClaude; .\bootstrap.ps1

# 2. Clone MendixToolkit
cd C:\Workspace
git clone https://github.com/jordnlvr/MendixToolkit.git
cd MendixToolkit

# 3. Run install (deploys overlay + registers stdio MCPs + installs mxcli)
pwsh .\install.ps1

# 4. Register the always-on HTTP MCP scheduled tasks (one-time)
pwsh .\setup-scheduled-mendix-context-http.ps1 -RunNow
pwsh .\setup-scheduled-playwright-http.ps1     -RunNow
pwsh .\setup-scheduled-theme-backup.ps1        -RunNow

# 5. Register MxcliNightlyWatch (daily 06:00 release-watcher)
#    (registered automatically by install.ps1 future versions; for now:)
$action = New-ScheduledTaskAction -Execute 'powershell.exe' `
    -Argument "-NoProfile -WindowStyle Hidden -ExecutionPolicy Bypass -File `"$env:USERPROFILE\.claude\lib\Watch-MxcliNightly.ps1`""
$trigger = New-ScheduledTaskTrigger -Daily -At '06:00'
Register-ScheduledTask -TaskName 'MxcliNightlyWatch' -TaskPath '\MendixToolkit\' `
    -Action $action -Trigger $trigger `
    -Settings (New-ScheduledTaskSettingsSet -StartWhenAvailable -ExecutionTimeLimit (New-TimeSpan -Minutes 5)) `
    -Principal (New-ScheduledTaskPrincipal -UserId $env:USERNAME -LogonType Interactive)

# 6. In Studio Pro 11.8+ → Maia Chat → Configure MCP Connections → Add Server (twice):
#    - mendix-context  | http://127.0.0.1:9123/mcp | HTTP Streamable
#    - playwright      | http://localhost:8931/mcp | HTTP Streamable

Verify

claude mcp list                                                       # mendix-context + playwright + mendix_inventory + doctrine ✓ Connected
Get-NetTCPConnection -LocalPort 9123,8931 -State Listen               # both bound
Get-ScheduledTask -TaskPath '\MendixToolkit\' | Format-Table TaskName, State
# expect: MendixContextHttp Running, PlaywrightHttp Running, MendixThemeBackup Ready, MxcliNightlyWatch Ready

# Hook unit-test (3 contrived prompts; all should respond as expected)
$h = "$env:USERPROFILE\.claude\hooks\user-prompt-submit.ps1"
'{"prompt":"build me a customer page"}' | & powershell -NoProfile -ExecutionPolicy Bypass -File $h
# expects: [mendix-doer auto-routing ...] hint
'{"prompt":"how does mxcli widget init work?"}' | & powershell -NoProfile -ExecutionPolicy Bypass -File $h
# expects: empty (question shape, not routed)

Day-to-day flows

In any Claude Code session — the doer auto-fires when you type Mendix imperatives. You only invoke skills directly when you want fine-grained control:

| Intent | What fires | |---|---| | Build / clone / scaffold / audit a page, microflow, or entity | mendix-doer (auto-routed) | | Plan a non-trivial Mendix change | mendix-orchestrator (call directly) | | Domain-model question ("does Mendix support X?") | mendix-expert | | Need fresh release notes / blog post / API change | mendix-researcher | | "Should I use Model SDK or Web Ext API?" | studio-pro-extensibility | | Specific skill, manual run | /mx-discover, /mx-impact, etc. | | Deterministic workflow (named recipe) | /workflow <name> |

For the full skill ecosystem and rationale, read HANDOVER.md.

Project layout

MendixToolkit/
├── README.md                    # this file
├── HANDOVER.md                  # the full story
├── PHASE-D-PLAN.md              # next-session work spec (3 unbuilt page-tier skills)
├── MISSION.md  · OPERATIONS.md  · WORKFLOWS.md  ·  IDEAS.md
├── install.ps1                  # per-machine deploy
├── update.ps1                   # git pull + install (with dirty-tree gate)
├── setup-scheduled-*.ps1        # one-time scheduled-task registrations
├── mx-close.ps1                 # Studio Pro graceful close + orphan cleanup
├── .claude/
│   ├── CLAUDE.md                # project-local Claude context (loads in this cwd)
│   ├── LEARNINGS.md             # append-only durable lessons (newest first)
│   ├── IDEAS.md                 # forward-looking thoughts
│   ├── skills/                  # /start-here · /next-step · /workflow (project-local)
│   ├── agents/mendix-orchestrator.md   # project-local planner
│   └── settings.json · settings.local.json
├── claude/                      # OVERLAY deployed to ~/.claude/ via install.ps1
│   ├── skills/                  # /mx-* + /maia-mcp-bridge + /close-studio-pro
│   ├── commands/                # slash command shortcuts
│   ├── agents/studio-pro-extensibility.md
│   ├── rules/                   # 8 always-loaded doctrine files (incl. mendix-verification-matrix.md)
│   └── lib/                     # shadow-write engine, theme-backup, close-studio-pro lib, mxcli setup, …
└── mcp-servers/
    ├── mendix-context-mcp/      # 9 tools: theme catalog, OS2 buckets, gold pages, design properti