**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 --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 --filter `, or `node --test ` 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 ` 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__`. 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