intellij-community Agent Skills & AI Rules

<!-- Generated by community/.ai/render-guides.mjs; edit community/.ai/* -->

**Critical:** These guidelines MUST be followed at all times.

## Project Invariants

- A module or plugin directory can hold its own AGENTS or CLAUDE instructions. Follow them when they are present.
- `*.iml` files are the source of truth. They generate the `BUILD.bazel` files.
- Register a new or edited JPS module `.iml` with `bun build/jps-module.mjs register <path-to-iml> --fix-iml-eof`, then run `./build/jpsModelToBazelCommunityOnly.cmd`. Never edit `.idea/modules.xml` by hand. The command keeps `modules.xml` in canonical order.
- User-visible strings belong in `*.properties` for localization.

## Language

- Read [Code Style](./.agents/skills/code-style/SKILL.md) before writing or reviewing Kotlin or Java.
- Read [Rust Code Style](./.agents/skills/rust-code-style/SKILL.md) before writing or reviewing Rust.

## Writing

Write every user-visible artifact in [ASD-STE100 Simplified Technical English](https://www.asd-ste100.org/), and keep it short. This covers a comment, KDoc, a commit message, documentation, a spec, and a report to the user. Use the active voice and a simple tense, state one topic per sentence, write positively, and use no noun cluster longer than three words. The five that catch most of the damage here:

- Keep a sentence at or under 25 words.
- Make an aside its own sentence. Do not put it between dashes.
- Keep the articles. Write "the session", not "session".
- One term per concept. Never introduce a synonym for a term the area already defines.
- Say what you left out and why. Do not pad a report to look complete.

Each kind of text has one home. Rationale and evidence for a change go in the commit message, not in a code comment. Document a declaration in KDoc on it, not in a `README.md`.

## Workspace Isolation

Do not create a Git worktree or a clone, and do not install a workspace manager, on your own initiative. Read [Workspace Isolation](./.ai/workspace-isolation.md) before any workspace-isolation action. It also covers the explicit-request exception.

## Module-specific rules

Read the referenced rules before you edit or review a file under these roots. They override the general guidance here.

- **Product DSL** (`platform/build-scripts/product-dsl/`): follow its `AGENTS.md`.
- **IJ Proxy MCP server** (`build/mcp-servers/ij-proxy/`):
  - Tests: run `bun run build` and `bun test`.
  - Bazel: do not run a Bazel build or test here.
- **Eel / IJent** (`platform/eel*/`, `platform/ijent/`): read `platform/eel/AGENTS.md` first.
- **PyCharm** (`./python`): start a PY-NNNNN issue at `./python/.ai/index.md`.

## Mandatory Rules

### After Code Changes

- **Run the affected tests:** `./tools/bt.cmd --module <module> --filter <FQN>`, or `node --test <file>` for a `*.test.mjs` file. An FQN is required. Always name the test module. When bt refuses the module, run the `tests.cmd` command that it prints. Neither runner needs a separate `bazel build` step. A module rule can override the runner. Skip this when the plugin has no tests. See [TESTING](./.agents/skills/testing/SKILL.md).
- **Bazel compilation without tests:** to verify compilation only, run `bazel build <target>` for the affected modules. Skip this when you changed only `.js`, `.mjs`, `.md`, `.txt`, or `.json` files.
- After you change a Bazel or Starlark source (`BUILD`, `BUILD.bazel`, `MODULE.bazel`, `WORKSPACE`, `WORKSPACE.bazel`, or `*.bzl`), run `bazel run //:format.check`. If it reports a diff, run `bazel run //:format`, inspect the changes, and run the check again.
- After you change an `*.iml`, a `BUILD.bazel`, or a `.idea/` file, run `./build/jpsModelToBazelCommunityOnly.cmd`.

### After Writing Code

- Use `lint_files` to check the files for warnings when ijproxy or JetBrains MCP is available. Fix every warning that belongs to your changes. You can ignore an unrelated warning.

## Repository-wide rules

Keep IDE-serialized `.iml` files in canonical form. Do not:

- add a comment
- auto-format
- normalize the structure or the whitespace
- add a trailing newline at the end of the file
- remove an empty tag
- reorder an element or an attribute

## Tools

Never use the `code-search` skill. The search tools below replace it. Recipes, the Windows rules, and the full tool inventory: [Tools Reference](./.ai/tools.md).

### Search & navigation (ijproxy preferred)

Use `search_symbol` for a class, a method, or a field. Use `search_file` to find a file by glob. Use `search_text` and `search_regex` for a string, a comment, or another match that is not a symbol.

These are `mcp__ijproxy__<name>`. Look them up in the harness deferred-tool catalog before you use a shell or a non-ijproxy fallback.

### IDE-backed semantic tools

Available through ijproxy or JetBrains MCP: `lint_files`, `get_symbol_info`, `rename`, `reformat_file`, the threading and lock checks, and the project, VCS and run-configuration tools. Prefer a real refactoring over a manual search and replace.

### Tooling rules

- Prefer ijproxy for a content or symbol **search** and for a semantic operation. Fall back to JetBrains MCP, then to `./tools/fd.cmd` (files) and `./tools/rg.cmd` (text and regex), only when ijproxy is unavailable. Pass `-H` to see a dot-directory such as `.agents/`.
- Do not shell out for a file **search**, inside the repo or outside it. This is enforced: the `Glob` and `Grep` tools are denied, and so are the `grep` and `find` commands in every pipeline position.
- Prefer a spelling the allowlist knows, because a novel one asks for a prompt. Add a new entry to `.ai/tool-permissions.json`, never to a harness allowlist.
- Shell is allowed where this guide documents it, and for git, build, and test. Prefer `git_status` when that tool is available. Outside the working copy it is task-scoped: read what this repo's tooling produced, or what the user or a skill named, and never survey the machine.

### Skills

The harness can list skill *names* only, without a description. When a task looks like something a skill covers, read the index for what each name does before you improvise:

- Skill index: [`.agents/skills/INDEX.md`](./.agents/skills/INDEX.md)

## Individual Preferences

**Local Preferences:** @./.ai/local.md