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.

status mendix safety license

---

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 properties
    └── mendix-inventory/        # 31 tools: deep_context, change_impact, call_graph, scss_audit, …
                                 # (project-parameterized via MENDIX_MPR / MENDIX_PROJECT_ROOT / MENDIX_THEME_DIR)

Related repos

Repo	What	Status
NewClaude	Generic Claude harness deployer (rules, agents, hooks, skills NOT specific to Mendix)	Active. Install before MendixToolkit.
OS2_Project	Active hub for ContentPortal (Mendix module in OneSource v1) — PRD, prototypes, history, tools	Active. Open this repo when working on ContentPortal.
claude-orchestrator	Archive-mode since 2026-04-29. Active work moved to OS2_Project + MendixToolkit. Contains the Doctrine MCP, beast-mode research dumps, the forensic audit (FORENSIC-AUDIT-DRAFT.md) + transition ADR (RETIRED.md).	Read for forensic context; don't add new work.

License

Internal use. No public license at this time.

Cross-references

• The conversational executor: ~/.claude/agents/mendix-doer.md (deployed from a parallel session — see ~/.claude/plans/delegated-seeking-moth.md for the v1 plan)
• The forensic audit that drove the 2026-04-29 retirement of ClaudeOrchestrator: FORENSIC-AUDIT-DRAFT.md
• LEARNINGS log (newest first): .claude/LEARNINGS.md