diff --git a/README.md b/README.md index b128307..90f036a 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,7 @@ exports `activate(ctx)`. - [Services](docs/services.md): workspace, tasks, tooling, events, config, terminal and windows facades. - [Packaging And Distribution](docs/packaging-distribution.md): build output, archive layout, hot reload and dependency rules. - [Codex Skills And IdeA Plugins](docs/codex-skills-and-idea-plugins.md): separate IdeA-native plugin skills from Codex plugin discovery. +- [Project Plugin Assignments](docs/project-plugin-assignments.md): enable plugins per project and assign skills and MCP tools to agents. The installable example lives in [`examples/hello-plugin`](examples/hello-plugin). It demonstrates a menu command, storage, background-task feedback, a React layout diff --git a/docs/codex-skills-and-idea-plugins.md b/docs/codex-skills-and-idea-plugins.md index 8767531..f136079 100644 --- a/docs/codex-skills-and-idea-plugins.md +++ b/docs/codex-skills-and-idea-plugins.md @@ -40,7 +40,9 @@ loading. For multi-harness IdeA agent skills, declare `contributes.skills` in `idea-plugin.json`, ship the referenced Markdown files inside the package, install the plugin in IdeA, enable it in the target project, and assign the -skills to the target agents. +skills to the target agents. See +[Project Plugin Assignments](project-plugin-assignments.md) for the project +settings schema and the complete install, enable, assign, and relaunch workflow. For Codex-specific plugin skills, install the Codex plugin through the Codex plugin mechanism for the intended scope, then assign or enable those skills diff --git a/docs/manifest.md b/docs/manifest.md index 56f2727..9eb579a 100644 --- a/docs/manifest.md +++ b/docs/manifest.md @@ -177,6 +177,10 @@ Skill contribution rules: - Installing a plugin globally is not enough: a project must enable the plugin, then assign the skill to the target agent. +See [Project Plugin Assignments](project-plugin-assignments.md) for the +`.ideai/project-plugins.json` schema, validation rules, assignment order, and +agent relaunch requirements. + `contributes.layouts` is the only surface for plugin layouts. The same layout contribution can be mounted inside an IdeA layout cell or opened in a detached OS window. Do not add a separate manifest contribution type for windows. diff --git a/docs/project-plugin-assignments.md b/docs/project-plugin-assignments.md new file mode 100644 index 0000000..dae1e9a --- /dev/null +++ b/docs/project-plugin-assignments.md @@ -0,0 +1,154 @@ +# 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.