Back to all posts
• 7 min read

Hybrid Orchestration: Migrating 11 Decentralized JetBrains MPS Repositories with AI Agents

How we migrated the 11-repository ViMoTest ecosystem to JetBrains MPS 2026.1 using a hybrid submodule orchestration layer, dual-mode dependency resolution, shared runtime bundles, headless Ant model migrations, and the native Model Context Protocol (MCP).

Migrating a multi-repository ecosystem of Domain-Specific Languages (DSLs) in the JetBrains Meta Programming System (MPS) to a new major platform release is traditionally a slow, manual process.

In the ViMoTest ecosystem, our toolset spans 11 independent Git repositories: foundational Gradle scripts, Portable Document Format (PDF) export utilities, C# and C++ base languages, an action language compiler, a requirements DSL, the core ViMoTest language, and End-to-End (E2E) sample suites.

When we set out to migrate the entire stack to MPS 2026.1, we wanted to keep every repository completely independent while giving Artificial Intelligence (AI) coding agents a fast, deterministic workspace to execute and verify the migration from start to finish.

The resulting hybrid orchestration repository turned a multi-day manual release marathon into a repeatable, zero-touch workflow. Here is how it is architected and why it works so well.


1. The Architectural Dilemma: Decentralized Repos vs. Monorepo

Each of our 11 repositories has its own Git commit history, standalone Continuous Integration and Continuous Delivery (CI/CD) pipelines, issue tracker, and semantic GitHub Releases. Merging everything into a single monorepo would break independent release cycles and complicate open-source contributions.

However, keeping the repositories purely separated creates major friction during a platform upgrade:

  1. Strict Topological Dependencies: Downstream languages cannot compile or run migrations until upstream language plugins are built and packaged.
  2. Release Deadlocks: In a purely remote setup, testing an upstream fix in a downstream repository requires tagging and waiting for a GitHub Release first.
  3. Massive Disk Overhead: Unpacking a full MPS 2026.1 distribution and JetBrains Runtime (JBR) inside 11 separate repositories consumes more than 24 GB of disk space.

To get the best of both worlds, we built an open-source hybrid orchestration layer in vimotest/mps-vimotest-orchestration using Git submodules, a declarative dependency graph (repos.json), and a lightweight Python Command-Line Interface (CLI) called ./orchestrate.


2. Four Pillars of the Hybrid Orchestration Layer

Pillar 1: Topological Dependency Graph (repos.json)

All 11 repositories are mounted as Git submodules in a flat workspace and ordered strictly by their upstream dependencies:

TierRepositoriesRole in the Dependency Chain
Tier 1mps-gradle-scripts, mps-gradle-setup-sample, textGenGen-fum, Editor2PDFShared Gradle build automation, generator tooling, and utilities
Tier 2vimotest-requirements-dsl, CsBaseLanguage, CppBaseLanguageRequirements language and target C# / C++ base languages
Tier 3mps-alfi, mps-alfi-samplesAction language implementation and cross-language generators
Tier 4mps-vimotest, mps-vimotest-samplesCore ViewModel testing language and E2E verification suites

Running ./orchestrate status or ./orchestrate next inspects the live state of every submodule and tells the developer (or the AI agent) which repository is ready to be migrated next.

Pillar 2: Dual-Mode Dependency Resolution (local vs. remote)

We never hardcode relative sibling paths (such as ../mps-alfi/build/artifacts/...) inside any repository’s build.gradle. Every repository must remain 100% buildable on its own.

Instead, downstream repositories resolve their upstream plugin Uniform Resource Locators (URLs) through standard Gradle project properties with a fallback to the official GitHub Release asset:

def alfiPluginUrl = project.findProperty("alfiPluginUrl") ?: "https://github.com/vimotest/mps-alfi/releases/download/2026.1.0/alfi.zip"
def cppBaseLanguagePluginUrl = project.findProperty("cppBaseLanguagePluginUrl") ?: "https://github.com/Fumapps/CppBaseLanguage/releases/download/2026.1.0/CppBaseLanguage.zip"
def csBaseLanguagePluginUrl = project.findProperty("csBaseLanguagePluginUrl") ?: "https://github.com/Fumapps/CsBaseLanguage/releases/download/2026.1.0/CsBaseLanguage.zip"

ext.customMpsPlugins = [
    "alfi": alfiPluginUrl,
    "CppBaseLanguage": cppBaseLanguagePluginUrl,
    "CsBaseLanguage": csBaseLanguagePluginUrl
]

This simple convention enables two complementary verification modes in ./orchestrate:

  • Local Sibling Mode (./orchestrate build <repo>): As soon as an upstream repository finishes building its plugin archive locally, the orchestrator automatically injects -P<pluginProperty>=file:///... into downstream Gradle builds. We get monorepo-like instant feedback with zero coupling.
  • Remote Release Mode (./orchestrate build <repo> --mode remote): Once upstream 2026.1.0 releases are published on GitHub, remote mode clears local plugin caches and runs the build without property overrides. This guarantees that standalone Continuous Integration (CI) pipelines and external users can resolve the published release artifacts cleanly.

Pillar 3: Zero-Duplication Shared MPS Bundle (.mps-shared/)

Extracting MPS 2026.1 and JBR 25 independently across 11 submodules would waste over 22 GB of disk space and slow down setup.

Because our shared download-mps.gradle script guards extraction tasks with directory existence checks, ./orchestrate maintains a single canonical installation inside .mps-shared/2026.1. When preparing a submodule (./orchestrate prepare <repo>), the orchestrator:

  1. Symlinks heavy, read-only directories (lib, plugins, jbr, languages, and Operating System (OS) runtime files) to .mps-shared/2026.1.
  2. Creates an isolated bin/ directory (~1.1 MB) with repository-specific .vmoptions and a dedicated dependencies/ folder for that repository’s upstream plugins.
  3. Exports MPS_VM_OPTIONS pointing directly to the repository’s local mps64.vmoptions file so the native macOS Rust launcher (Contents/MacOS/mps) always loads the submodule’s isolated -Didea.plugins.path rather than resolving the symlink path back to .mps-shared/.

Total disk usage across all 11 repositories dropped from ~24 GB to ~2.2 GB, and workspace preparation now finishes in seconds.

Pillar 4: Headless Model Migration (mpsAntMigrate) & Native MCP Integration

In MPS, merely bumping ext.mpsVersion = "2026.1" and running code generation (mpsBuild) compiles existing models, but it does not run the MPS Migration Assistant. Without executing the underlying language and platform migration scripts, opening a project in the Graphical User Interface (GUI) still prompts the user with a Migration Assistant dialog, and .mps/migration.xml remains stuck at the old platform version.

At the same time, letting an AI agent edit raw .mps Extensible Markup Language (XML) files directly to force migrations is a recipe for broken concept identifiers and corrupted Abstract Syntax Trees (ASTs).

Our orchestration layer solves both sides of this problem by combining headless Ant model migration with native Model Context Protocol (MCP) tooling:

  1. Zero-Touch Headless Migration (./orchestrate migrate <repo> --build --test): A single command syncs the shared Gradle scripts, provisions the .mps-shared/2026.1 bundle, unpacks upstream plugins, and runs mpsAntMigrate via jetbrains.mps.build.ant.MigrationTask with autoplugindiscovery="true". This headlessly executes all pending platform and language migration scripts (such as UpdateConceptMethodCall), updates model ASTs cleanly, bumps .mps/migration.xml to project.migrated.version = "261", compiles the project, and runs the test suite.
  2. Interactive Structural Inspection via Native MCP (:63342): When custom language repairs or structural diagnostics are needed, MPS 2026.1 ships with the Projectional Agent Toolkit (jetbrains.mps.agents.mcp.tools), exposing a native MCP server inside the Integrated Development Environment (IDE) on port 63342. Launching ./orchestrate open <repo> and connecting an agent via @jetbrains/mcp-proxy lets the agent query concept nodes, inspect AST subtrees, and fix broken references directly through the live MPS repository APIs without ever touching raw XML persistence.

3. Real-World Pitfalls Caught by the Pipeline

Having a unified local-and-remote verification loop surfaced several subtle platform changes in MPS 2026.1 early:

  1. Modularized IntelliJ Platform Classpaths: In MPS 2026.1 (IntelliJ platform build 261), core interfaces such as PossiblyDumbAware moved into modularized platform Java Archives (JARs). Replacing brittle single-JAR lists in build models with <fileset dir="${artifacts.mps}/lib" includes="*.jar" /> eliminated compilation failures across all plugins.
  2. Gradle 8.10 vs. Java Development Kit (JDK) 25 Bytecode in CI: MPS 2026.1 runs on JBR 25 and compiles generated code to Java 25 bytecode (class file version 69.0), whereas Gradle 8.10.2 requires JDK 21 to evaluate Groovy build scripts in CI. Configuring our comparison test runner to execute compiled test bytecode on JDK 25 while keeping Gradle on JDK 21 solved the mismatch cleanly.
  3. Testbench Index Isolation (ModuleClassLoaderIsDisposedException): During consecutive headless test runs (mpsTest / mpsAntCheck), leftover IntelliJ index caches in build/system/index caused background indexer threads to reload modules and dispose classloaders mid-test. Having mpsAntCheck wipe build/system and build/config before each run made headless test execution 100% deterministic.
  4. Generator Reference Precision: Stricter model checks in MPS 2026.1 exposed a legacy generator rule in mps-alfi that emitted a MemberReference instead of a VariableReference for local optional value coalescing. Inspecting the model and fixing the reduction rule brought all 13 E2E sample test suites in mps-vimotest-samples to green.

Summary

You do not need to sacrifice repository independence to get monorepo speed during major platform upgrades. By combining Git submodules, property-driven local/remote dependency resolution, symlinked runtime bundles, headless Ant model migration (mpsAntMigrate), and native MCP agent tooling, we migrated and released all 11 repositories in the ViMoTest ecosystem to MPS 2026.1 with zero broken downstream releases and full end-to-end test confidence.

The complete orchestration setup, scripts, and configuration files are available on GitHub in the mps-vimotest-orchestration repository.