Project Plugin Assignments

IdeA installs plugin packages globally, but enables their capabilities per project and assigns agent-facing capabilities per agent. Project choices are stored in the project-owned .ideai/project-plugins.json file.

The normal workflow is:

Install the plugin globally in IdeA.
Enable the installed plugin for the target project.
Assign selected plugin skills and MCP tools to each target agent.
Relaunch the agent so its capability snapshot includes the new assignments.

Installation alone does not enable a plugin in a project. Enabling a plugin does not automatically grant all of its capabilities to every agent.

Version 1 Schema

The current schema version is 1. A complete example is:

{
  "version": 1,
  "plugins": [
    {
      "pluginId": "com.example.unity-plugin",
      "enabled": true
    }
  ],
  "agents": [
    {
      "agentId": "2a0e42e2-3c5f-4f30-a679-034b460cd59e",
      "skills": [
        {
          "pluginId": "com.example.unity-plugin",
          "skillId": "unity.build-debug"
        }
      ],
      "tools": [
        {
          "pluginId": "com.example.unity-plugin",
          "serverId": "unity-editor",
          "toolName": "unity_build"
        }
      ]
    }
  ]
}

The top-level fields are:

version: required schema version. It must currently be 1; unsupported versions are rejected.
plugins: project activation entries. Each entry contains the stable global pluginId and an enabled boolean.
agents: per-agent assignments. Each entry identifies an IdeA project agent by agentId and contains ordered skills and tools arrays.

An agent skill reference contains:

pluginId: the id from the owning plugin's idea-plugin.json.
skillId: the stable contributes.skills[].id within that plugin.

An agent MCP tool reference contains:

pluginId: the id from the owning plugin's idea-plugin.json.
serverId: the stable contributes.mcpServers[].id within that plugin.
toolName: the exact tool name advertised by that MCP server. The UI accepts this name as text because a dynamic MCP tool catalogue is not yet available.

Missing plugins, agents, skills, or tools arrays default to empty arrays when IdeA reads the document. Prefer writing them explicitly for clarity and forward-compatible review.

Assignment And Injection Order

Array order is significant. IdeA keeps plugin skill assignments in the order in which they were added. At agent launch, IdeA resolves the agent's native skills first, in agent-manifest order, then its plugin skills in the order stored in agents[].skills. Unavailable assignments are skipped without reordering the remaining skills.

The resolved skill catalogue is injected into the agent's orchestration context before the agent persona. Each supported harness receives the same ordered IdeA-native capability snapshot. The skill body remains read-only package content and is available through idea_skill_read only when that skill was resolved for the launched agent.

Tombstones

Plugin activation entries and agent assignments are intentionally retained when a plugin, skill, or MCP server is temporarily missing. These dangling entries are tombstones: they preserve project intent across uninstall/reinstall or a temporary manifest change.

A tombstone is inert. IdeA skips it when resolving capabilities, and the project settings UI marks stale skill or server references as missing or obsolete. The UI lets users remove those references explicitly. Reinstalling and activating a matching plugin makes a retained assignment resolvable again.

Disabling a plugin also keeps its assignments. They become effective again only after the plugin is enabled and runtime-active for the project.

UI And API Validation

Prefer the project plugin settings UI or its backing API commands over manual editing. They apply the following rules:

Enabling requires the plugin package to be installed globally. Disabling a missing plugin is allowed so a retained activation can be cleared.
Assigning a skill requires an existing project agent, an enabled and runtime-active plugin, and a matching contributes.skills[].id.
Assigning a tool requires an existing project agent, an enabled and runtime-active plugin, a matching contributes.mcpServers[].id, and a non-empty toolName.
Assign and unassign operations are idempotent. Assigning an existing reference does not duplicate it; unassigning a missing reference is harmless.
Unassign operations remain available for tombstones, so stale references can be removed even when their plugin capability no longer resolves.

The project settings read API returns both the persisted document and the currently installed plugin manifests. The UI uses this catalogue to offer only skills and MCP servers from plugins enabled for the project, while still surfacing persisted tombstones.

Manual Editing

The file is project-owned and may be edited manually, for example in version control or automation. Stop or relaunch affected agents around the edit, keep the document valid JSON, preserve version: 1, use the real project agent UUID, and copy plugin, skill, and server ids exactly from the plugin manifest.

Manual editing bypasses the mutation checks described above. A syntactically valid document may therefore contain duplicates, unknown agents, disabled or missing plugins, unknown capability ids, or an invalid tool name. Such entries may remain inert or fail later operations. Use the UI/API whenever possible to receive immediate validation and idempotent updates.

Reloading Plugins And Relaunching Agents

These actions solve different problems:

Reload the plugin after rebuilding or replacing its installed package. Reload refreshes the plugin manifest, runtime bundle, contributions, and packaged skill Markdown. It does not change project activation or agent assignments.
Relaunch the agent after enabling or disabling a project plugin, changing its skill/tool assignments, or manually editing .ideai/project-plugins.json. Agent capabilities are resolved into a launch-time snapshot, so an already running agent does not acquire assignment changes retroactively.

When both package content and assignments changed, reload the plugin first, confirm it is enabled for the project, update the assignments, then relaunch the agent.

6.3 KiB Raw Blame History