155 lines
6.3 KiB
Markdown
155 lines
6.3 KiB
Markdown
# 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:
|
|
|
|
1. Install the plugin globally in IdeA.
|
|
2. Enable the installed plugin for the target project.
|
|
3. Assign selected plugin skills and MCP tools to each target agent.
|
|
4. 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:
|
|
|
|
```json
|
|
{
|
|
"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.
|