jetbrains-plugin-development

What this skill does

# JetBrains IDE Plugin Development (IntelliJ Platform SDK)

This skill carries the IntelliJ Platform SDK domain knowledge needed to write, debug, and modify
JetBrains IDE plugins competently. It is opinionated toward 2024.1+ targets (Kotlin coroutines,
IntelliJ Platform Gradle Plugin 2.x, light services with `@Service`, dynamic plugin defaults) and
calls out where pre-2024.1 patterns are still required.

## How to use this skill

1. Read the **mental model** below — it is small but governs almost every decision.
2. Pick the reference file from the **Capability index** that matches the task and read it before editing.
3. For end-to-end shapes — how the registrations, classes, and `plugin.xml` of a feature line up — open the matching folder under `examples/`.
4. Before declaring any plugin-modifying task done, walk the **Pre-flight checklist**.

Do not invent extension point names, attribute names, or API signatures. The Platform is highly
specific about strings (`language="JAVA"` vs `"java"`, EP IDs, attribute spellings); a wrong
character is enough to silently disable a feature. When unsure, surface the question to the user
with the relevant reference cited — and verify the spelling in the IDE's `plugin.xml` editor,
which auto-completes valid EP names from the loaded plugin set and underlines unknown ones.

## Mental model — five invariants you must hold

These five invariants explain almost every "why doesn't this work?" question.

1. **`plugin.xml` is the contract.** A class is invisible to the IDE until it is registered.
   `@Service`, `@Service(cs)` annotations and a few `META-INF/` filename conventions are the
   only exceptions; everything else (extensions, listeners, actions, EPs you define, dependencies)
   must appear in `plugin.xml` (or a `config-file` of an `<depends optional>` block).
2. **Extensions are stateless; services hold state.** EP implementations are constructed once
   per scope and shared across all calls and threads. Storing mutable state on an extension
   leaks across projects, threads, and dynamic reloads. Put state in a service
   (`@Service` / `@Service(Service.Level.PROJECT)`), and have extensions look it up on demand.
3. **Threading is non-negotiable.** Reading platform model state (PSI, VFS, Document, project model)
   needs a Read Lock. Writing needs a Write Lock and **must** start on the EDT (or via the
   suspending `writeAction`/`backgroundWriteAction`). Long work belongs on a background thread
   with progress and cancellation. EDT freezes are user-visible; lock violations are immediate
   exceptions or data corruption. New code on 2024.1+ uses Kotlin coroutines
   (`Dispatchers.EDT`, `readAction { }`, `writeAction { }`, `cs.launch { }`).
4. **`Disposer` is how lifecycle works.** Resources tie into a `Disposable` parent and the
   platform calls `dispose()` post-order when the parent goes away. Services are usually the
   right parent. Never use `Application` or `Project` directly as a parent — that traps
   resources past plugin unload and leaks the classloader. `CoroutineScope` injection on a
   `@Service` is the modern alternative to `Disposable`.
5. **Dynamic plugin reload imposes hard constraints.** The default since 2020.1 is
   `require-restart="false"`. To stay reloadable: every EP your plugin contributes to and
   defines must be dynamic, no static caches of plugin classes, no `object` singletons holding
   state, no listeners parented to `Application`/`Project`, no `overrides="true"` services.

## Capability index

Use this section as a router. Do not bulk-read every reference. Start with the single most specific reference below, then add companion references only when the task crosses that boundary.

Reference filenames are prefixed by category for fast scanning: `01_core`, `02_runtime`,
`03_lifecycle`, `04_threading`, `05_file_model`, `06_code_insight`, `07_language`,
`08_ui`, `09_project`, `10_execution`, and `11_distribution`.

- [01_core_gradle_project.md](references/01_core_gradle_project.md): Project setup, IntelliJ Platform Gradle Plugin 2.x, sandbox IDE, generated helper tasks, multi-module project shape.
- [01_core_plugin_xml.md](references/01_core_plugin_xml.md): `plugin.xml`, required descriptor elements, file naming conventions, and descriptor blocks for listeners/actions.
- [01_core_dependencies.md](references/01_core_dependencies.md): `<depends>`, optional dependency config files, `sinceBuild`, `untilBuild`, and platform branch targeting.
- [01_core_extensions.md](references/01_core_extensions.md): Using, ordering, iterating, defining, or discovering extension points.
- [01_core_extension_diagnostics.md](references/01_core_extension_diagnostics.md): Plugin loading lifecycle and diagnosing extensions that are registered but ignored.
- [01_core_split_mode_remote_development.md](references/01_core_split_mode_remote_development.md): Split Mode, Remote Development, frontend/backend/shared modules, RPC boundaries, and split sandbox runs.
- [02_runtime_services.md](references/02_runtime_services.md): Light services, constructor rules, state holders, service-scoped `CoroutineScope`, and persistent-state handoff.
- [02_runtime_listeners_message_bus.md](references/02_runtime_listeners_message_bus.md): Declarative listeners, `MessageBus`, `Topic`, manual subscriptions, and listener lifetime.
- [02_runtime_actions.md](references/02_runtime_actions.md): `AnAction`, `update`, `ActionUpdateThread`, action groups, keymaps, and action skeletons.
- [02_runtime_typed_handlers_editor_actions.md](references/02_runtime_typed_handlers_editor_actions.md): `TypedHandlerDelegate`, `EditorActionHandler`, typing interception, autopopup routing, and multi-caret editor actions.
- [02_runtime_legacy_component_migration.md](references/02_runtime_legacy_component_migration.md): Migrating `ApplicationComponent`, `ProjectComponent`, or `ModuleComponent` to services, extensions, listeners, and startup activities.
- [02_runtime_deprecated_api_migrations.md](references/02_runtime_deprecated_api_migrations.md): Deprecated listener, coroutine-scope, action, and Plugin DevKit migration checks.
- [03_lifecycle_disposer.md](references/03_lifecycle_disposer.md): `Disposable` trees, safe parent selection, cleanup patterns, `Alarm`, and disposal triggers.
- [03_lifecycle_leak_diagnostics.md](references/03_lifecycle_leak_diagnostics.md): Disposer leak debugging, `LeakHunter`, sandbox checks, and leak-prone patterns.
- [04_threading_model.md](references/04_threading_model.md): EDT/BGT mental model, lock rules, dumb mode overview, and threading invariants.
- [04_threading_read_write_actions.md](references/04_threading_read_write_actions.md): Classic read/write actions, `ReadAction.nonBlocking`, `WriteCommandAction`, `invokeLater`, modality, and annotations.
- [04_threading_background_work_progress.md](references/04_threading_background_work_progress.md): `Task.Backgroundable`, progress indicators, cancellation, synchronous progress, and fire-and-forget work.
- [04_threading_coroutines_2024.md](references/04_threading_coroutines_2024.md): 2024.1+ coroutine APIs, `Dispatchers.EDT`, suspending read/write actions, progress, and `runBlockingCancellable`.
- [04_threading_thread_to_coroutine_migration.md](references/04_threading_thread_to_coroutine_migration.md): Replacing `Thread`, `ExecutorService`, and `Task.Backgroundable` with coroutine-based code.
- [04_threading_diagnostics.md](references/04_threading_diagnostics.md): Threading symptoms, common mistakes, best practices, and import map for suspending APIs.
- [05_file_model_vfs.md](references/05_file_model_vfs.md): `VirtualFile`, file lookup, refresh, listeners, VFS lifecycle, and identity.
- [05_file_model_documents.md](references/05_file_model_documents.md): `Document`, document lookup, reads, writes, synchronization with PSI, listeners, and guarded ranges.
- [05_file_model_psi_basics.md](references/05_file_model_psi_basics.md): `PsiElement`, PSI lookup, tree walking, modifications,