MPS

# Agents Guide for This Project

This project is a mixed JetBrains MPS + plain Java/Kotlin codebase.

Developers typically use two environments against the same checkout:
- IntelliJ IDEA for editing, debugging, testing, and inspecting Java/Kotlin code, including code generated by MPS.
- JetBrains MPS for editing languages, models, generators, and other MPS artifacts.

Agents must adapt to the tools available in the current session. Use this file as the cross-environment entry point.

For detailed MPS node, model, language, generator, validation, and MCP workflows, load the `mps-mcp-workflow` skill. If your agent runtime does not explicitly confirm that project skills are auto-loaded, read `.agents/skills/mps-mcp-workflow/SKILL.md` before changing MPS artifacts.

## ⚠️ WARNING: Never Read Raw MPS Model Files

**If you are opening or reading `.mps`, `.mpl`, or other MPS XML files directly, you are way off track and must stop immediately.**

MPS model files are binary-like serialized XML that cannot be safely understood or edited as plain text. Reading them gives you opaque node IDs and no semantic insight — you will misinterpret the content and likely corrupt the model if you try to edit it.

**What to do instead:**
- Use MPS MCP tools (`mps_mcp_*`) to inspect, navigate, and edit MPS models.
- If MPS MCP tools are not available in your session, ask the user to start MPS and enable the MPS MCP server before continuing with any MPS work.
- Do not attempt to parse, edit, or reason from raw `.mps` XML.

## Project Nature: JVM + MPS

Treat this repository as having two kinds of source of truth:
- Plain Java/Kotlin and related project files, usually edited and validated through IntelliJ IDEA tooling.
- MPS models and language definitions, edited and validated through MPS-aware tooling.

Prefer the highest-level source of truth:
- If behavior is defined by an MPS language, model, or generator, prefer fixing the MPS artifact rather than only patching generated Java.
- If behavior is implemented in hand-written Java/Kotlin, use IDEA-oriented tools and workflows.

## Choose Tools By Task

Prefer IntelliJ IDEA MCP tools for:
- `.java`, `.kt`, `.kts`, XML, Ant, module, project, and run configuration files
- inspections, symbol lookup, refactoring, build, tests, and run configurations
- debugging or testing JVM code
- understanding how generated code is consumed by hand-written code

Prefer MPS MCP tools for:
- `.mps` models and language definitions
- structure, editor, constraints, typesystem, behavior, and generator work
- model navigation, concept analysis, node editing, and model validation
- generation-related issues whose root cause is in MPS artifacts

Plain file tools (Read, Grep, Glob, Bash) are fine for reading generated output, non-MPS configuration, and plain-text docs — but never for editing `.mps` files.

For cross-cutting tasks:
- inspect both the JVM side and the MPS side before editing
- validate the MPS model and the affected JVM code path
- avoid fixing only generated output when the defect originates in the generator or model

If a task clearly requires model-aware editing and MPS MCP tools are not available:
- do not hand-edit serialized MPS model files as plain text unless the user explicitly asks for that
- restrict changes to plain JVM, build, docs, and configuration files
- explain the limitation and ask whether to proceed with a workaround or wait for MPS-aware tooling

## Rules For Java/Kotlin Work

When working on plain Java/Kotlin code:
- Use IDEA MCP tools as the default toolset for navigation, inspections, builds, tests, and refactorings.
- Prefer targeted validation first: inspect the affected file, build the affected module, run the smallest relevant test or run configuration.
- Follow existing module and test structure rather than introducing new build or test conventions.
- If a failure appears in generated code, first determine whether the root cause is in hand-written JVM code or in MPS generation logic.

Typical JVM-side areas in this repository include:
- `core/`
- `editor/`
- `workbench/`
- `platform/`
- `plugins/`
- `startup/`
- `testbench/`
- `jps/`
- `IdeaPlugin/`

## Rules For MPS Work

When working on MPS artifacts:
- Use MPS MCP tools whenever available.
- Resolve nodes, concepts, models, and modules precisely before editing.
- Validate frequently with `mps_mcp_check_root_node_problems` after structural changes, reference updates, or generator changes.
- Rebuild or regenerate when needed so downstream JVM code and project state remain consistent.

Use the `mps-mcp-workflow` skill whenever the task involves MPS project structure, MPS modules or models, language syntax, concept relationships, generators, or MPS-specific changes. In practice, serious MPS work in this repository depends on that workflow skill together with MPS MCP tools.

### MCP Project Resolution (subdirectory & multiple projects)

The `mps_mcp_*` tools act on the MPS project open in the running MPS instance, and the IDEA MCP tools act on the project open in IDEA. One checkout can expose several projects to the same MCP server — for example, this repository plus the IntelliJ platform sources opened alongside it (see Platform sources below), or a VCS root containing several MPS project subdirectories. Pass the intended project's path on **every** call, starting with the first one (for IDEA tools, the absolute `projectPath`; for MPS tools, the project's `mpsProjectBaseDirectory`); the path must be at or inside the project that owns the code, not a parent directory. If you do not know it yet, pass the session's current working directory on the first call; if that is rejected, take the path from the rejection message, which lists the open projects, then reuse it for the session — `mps_mcp_list_open_projects` reports the same value when it can run. See the `projectPath` Critical Directive in `mps-mcp-workflow/SKILL.md`. Note that some repositories keep the MPS project in a subdirectory (e.g. `tools/BigProject` in mbeddr / MPS-extensions), in which case the MPS project base directory is below the repository root. When more than one project is open and it is not obvious from your request or the current editor focus which one a query or change should target, ask the user which project to use rather than guessing — the open projects share a single module repository, so the wrong choice silently returns the wrong nodes or gets a cross-project write refused.

## Rules For Generated Code

Generated code may be useful for inspection, debugging, or understanding runtime behavior, but it is often not the correct place to apply a fix.

Generated artifacts are recreated on every Make/Rebuild. Typical generated locations:
- `source_gen/` — Java/Kotlin sources produced by MPS generators
- `classes_gen/` — compiled classes produced from generated sources

Default rule:
- do not edit generated sources if the real source of truth is an MPS model or generator

Allowed exceptions:
- the user explicitly asks for a generated-source change
- the repository treats a generated directory as checked-in maintained source
- the change is a temporary diagnostic step and is clearly called out as such

Before editing generated code, identify:
- where the code comes from
- whether it will be overwritten by generation
- whether the correct fix belongs in the generator, model, or hand-written JVM code

## Validation Expectations

Match validation to the kind of change, and prefer focused validation before broad suites. [`.agents/quality-gates.md`](.agents/quality-gates.md) is the single source of truth: it covers the JDK, build and test commands, run-configuration timeouts and monitoring, and the MPS-side checks.

## Environment Notes

Common assumptions for this repository:
- developers often open the same checkout in both IntelliJ IDEA and MPS
- MPS is frequently started from source using project run configurations such as `MPS` and `MPS (2nd inst.)`. Note: the run configuration may time out in the IDE tool after launching the long-running GUI, which is expected.
- To reliably verify that MPS has started, use `ps aux | grep -i mps` (with `executeInShell: true`) to confirm the process is alive, or check `log/idea.log` for recent activity (e.g., repository saving, exiting dumb mode).

### Git Configuration

Current environment uses:
- `origin`: `git@github.com:JetBrains/MPS-development.git` (master branch)

### Platform sources

This project builds on top of the IntelliJ platform, bundled as jar files. Platform Java/Kotlin classes live in `com.intellij...` packages; MPS code lives in `jetbrains.mps...`. When platform sources are needed, follow the procedure in [`.agents/tools.md`](.agents/tools.md); never modify, compile, or re-branch them.

## Global rules

These rules are **mandatory** — always follow them, not just when a skill is active.

- [`.agents/git.md`](.agents/git.md) — commit format, branch naming, merge hygiene, history rewrite safety
- [`.agents/conventions.md`](.agents/conventions.md) — package naming, API change policy
- [`.agents/tools.md`](.agents/tools.md) — MCP usage policy
- [`.agents/workflow.md`](.agents/workflow.md) — editing strategy, merge conflict checklist
- [`.agents/quality-gates.md`](.agents/quality-gates.md) — quality standards

## Skills

A skill is a set of local instructions stored in a `SKILL.md` file under `.agents/skills/<skill-name>/`. Start with `mps-mcp-workflow` for the overview and a directory of every other skill. The `mps-*` skills here are hand-propagated copies of their blueprints in `plugins/mcp-tools/resources/jetbrains/mps/agents/mcp/skills/`, which is the source of truth: never run `mps_mcp_initialize_project_for_agents` here, and never delete these copies to let it run — edit the blueprint and re-propagate, by copying each changed skill folder over both catalogs. `SkillCatalogReplicationTest` in the mcp-tools test suite fails when the three trees differ.

In other checkouts, the installed guide (`plugins/mcp-tools/resources/jetbrains/mps/agents/mcp/templates/AGENTS_template.md`) states how to compare the `MPS_MCP_SKILL_VERSION.txt` stamps with `mpsBuild` from `mps_mcp_list_open_projects`. **This checkout is exempt:** the catalogs are hand-propagated blueprints and can be newer than the running plugin, so a missing `MPS_MCP_SKILL_VERSION.txt` is expected. Do not treat that absence as staleness, do not run the initializer, and do not delete the copies. `SkillCatalogReplicationTest` remains the freshness check.