diff --git a/README.md b/README.md index 84d29b2..3a33c04 100644 --- a/README.md +++ b/README.md @@ -155,7 +155,7 @@ dotagents can also import native runtime subagent files from `.claude/agents/`, OpenCode reuses an existing project config from `.opencode/opencode.jsonc`, `.opencode/opencode.json`, `opencode.jsonc`, or `opencode.json`, in that order. New projects use `.opencode/opencode.jsonc`. -Plugins are declared with `[[plugins]]` entries. In project scope, dotagents installs canonical bundles into `.agents/plugins//` and generates runtime plugin outputs such as `.claude-plugin/marketplace.json`, `.github/plugin/marketplace.json`, `.cursor-plugin/marketplace.json`, `.agents/plugins/marketplace.json`, native Claude, Cursor, and Codex manifests, `.grok/plugins//`, `.opencode/skills//`, OpenCode MCP entries, and Pi skill links under `.agents/skills//`. During legacy migration, generalized bundles can also project Markdown agents into `.opencode/agents/`; standard extension agents are preserved but are not projected yet: +Plugins are declared with `[[plugins]]` entries. In project scope, dotagents installs canonical bundles into `.agents/plugins//`. It generates marketplaces for Claude, Cursor, Codex, and Copilot. Claude, Cursor, and Codex also receive native manifests when required. Grok receives a managed copy. OpenCode receives skill links and MCP entries. Pi receives skill links under `.agents/skills//`. During legacy migration, generalized bundles can also project Markdown agents into `.opencode/agents/`. Standard extension agents are preserved but are not projected yet: ```toml [[plugins]] @@ -169,6 +169,23 @@ The canonical portable format is an [Agent Plugins](https://agent-plugins.org/) Global plugins install canonical bundles under `~/.agents/plugins/`. Claude and Cursor marketplaces are generated under `~/.agents/`. Copilot uses `~/.agents/.github/plugin/marketplace.json`, and Codex uses `~/.agents/plugins/marketplace.json`. Grok plugins are copied into `~/.grok/plugins/`. OpenCode skills are linked into `~/.config/opencode/skills/`, and portable MCP servers are merged into `~/.config/opencode/opencode.json`. Pi skills are linked into `~/.agents/skills/`. `--user` remains a compatibility alias for `--global`. +### Plugin activation + +Dotagents plugin installation and native client installation are separate stages. `dotagents add` and `dotagents install` install the canonical bundle and write each selected runtime output. Marketplace-based clients still require native registration and installation. + +| Agent ID | Dotagents output | Native action | +| --- | --- | --- | +| `claude` | Generated marketplace and native manifest when required | Register the Dotagents root, then install `@dotagents` with the Claude CLI. | +| `cursor` | Generated marketplace and native manifest when required | Use Customize, a team marketplace, `~/.cursor/plugins/local`, or `cursor-agent --plugin-dir`. Cursor has no marketplace CLI command. | +| `codex` | Generated `.agents/plugins/marketplace.json` and native manifest when required | Register the correct source root, then install `@dotagents-local` with the Codex CLI. | +| `copilot` | Generated `.github/plugin/marketplace.json` | Register the Dotagents root, then install `@dotagents` with the Copilot CLI. | +| `grok` | Managed copy under `.grok/plugins/` | None. Grok reads the managed copy directly. | +| `opencode` | Managed skill links and MCP entries | None. OpenCode reads the generated projections directly. | +| `pi` | Managed skill links under `.agents/skills/` | None. Pi reads this directory directly. | +| `vscode` | No plugin adapter | None. VS Code does not receive Dotagents plugin output. | + +Native clients can cache registered marketplaces and installed plugins. A later Dotagents update or removal does not update those caches. The guide and CLI reference list project, global, update, and removal commands. + Pi plugin targets are global skill projections rather than isolated plugin installs: a Pi-targeted plugin skill is added to `.agents/skills/` and is therefore visible to other clients that consume that shared directory. [Pi](https://github.com/badlogic/pi-mono) reads `.agents/skills/` natively. Normal skills need no Pi-specific configuration; plugin bundles can target `pi` when their `skills/` components should be exposed there. diff --git a/docs/public/llms.txt b/docs/public/llms.txt index 4608a21..fd029e2 100644 --- a/docs/public/llms.txt +++ b/docs/public/llms.txt @@ -315,7 +315,80 @@ Generated project-scope plugin outputs: Generated plugin JSON is deterministic: object keys and plugin entries are sorted, output is two-space indented, and files end with one trailing newline. Generated marketplaces and Claude, Cursor, and Codex manifests use adjacent `.dotagents-managed` sidecars so client-owned JSON remains schema-native; legacy `metadata.managedBy` output remains recognizable during migration. Managed Grok copies and OpenCode and Pi component symlinks are pruned when their plugin or target is removed. Plugin sources that resolve to this project's `.agents/plugins//` install destination are rejected so dotagents never installs a same-repo plugin onto itself. Existing plugin install destinations are overwritten only when their on-disk `.dotagents-managed` marker proves ownership. -Global plugins install under `~/.agents/plugins/`. Claude and Cursor marketplaces are generated below `~/.agents/`. Copilot uses `~/.agents/.github/plugin/marketplace.json`. Codex uses `~/.agents/plugins/marketplace.json` with paths rooted at the user's home. Grok plugins are copied into `~/.grok/plugins/`. OpenCode skills use `~/.config/opencode/skills/`, portable plugin MCP servers use `~/.config/opencode/opencode.json`, and Pi skill projections use `~/.agents/skills/`. +Global plugins install under `~/.agents/plugins/`. Claude and Cursor marketplaces are generated below `~/.agents/`. Copilot uses `~/.agents/.github/plugin/marketplace.json`. Codex uses `~/.agents/plugins/marketplace.json` with paths rooted at the user's home. Grok plugins are copied into `~/.grok/plugins/`, OpenCode skills use `~/.config/opencode/skills/`, portable plugin MCP servers are merged into `~/.config/opencode/opencode.json`, and Pi skill projections use `~/.agents/skills/`. + +### Plugin activation + +Dotagents plugin installation and native client installation are separate stages. `dotagents add` and `dotagents install` install the canonical bundle and generate runtime output. Marketplace-based clients must register that output and install the plugin into native client state. + +| Agent ID | Project output | Native action | +| --- | --- | --- | +| `claude` | `.claude-plugin/marketplace.json` and a native manifest when required | Register the project root, then install `@dotagents`. | +| `cursor` | `.cursor-plugin/marketplace.json` and a native manifest when required | Use Customize, a team marketplace, a local plugin, or `cursor-agent --plugin-dir`. | +| `codex` | `.agents/plugins/marketplace.json` and a native manifest when required | Register the project root, then install `@dotagents-local`. | +| `copilot` | `.github/plugin/marketplace.json` | Register the project root, then install `@dotagents`. | +| `grok` | `.grok/plugins//` | None. Grok reads the managed copy directly. | +| `opencode` | `.opencode/skills/` links and managed MCP entries | None. OpenCode reads the projections directly. | +| `pi` | `.agents/skills/` links | None. Pi reads the links directly. | +| `vscode` | No plugin output | None. VS Code has no plugin adapter. | + +Project activation: + +```shell +claude plugin marketplace add ./ --scope project +claude plugin install @dotagents --scope project +codex plugin marketplace add ./ --json +codex plugin add @dotagents-local --json +copilot plugin marketplace add ./ +copilot plugin install @dotagents +``` + +Default global activation: + +```shell +claude plugin marketplace add "$HOME/.agents" --scope user +claude plugin install @dotagents --scope user +codex plugin marketplace add "$HOME" --json +codex plugin add @dotagents-local --json +copilot plugin marketplace add "$HOME/.agents" +copilot plugin install @dotagents +``` + +Codex uses `$HOME` because its default catalog is at `$HOME/.agents/plugins/marketplace.json`. Copilot registers the Dotagents root itself, the same as Claude, because its generated catalog is at `$HOME/.agents/.github/plugin/marketplace.json`. + +Custom global activation: + +```shell +claude plugin marketplace add "$DOTAGENTS_HOME" --scope user +claude plugin install @dotagents --scope user +codex plugin marketplace add "$DOTAGENTS_HOME" --json +codex plugin add @dotagents-local --json +copilot plugin marketplace add "$DOTAGENTS_HOME" +copilot plugin install @dotagents +``` + +Cursor has no marketplace CLI command. Cursor Agent can load `.agents/plugins/`, `$HOME/.agents/plugins/`, or `$DOTAGENTS_HOME/plugins/` with `--plugin-dir`. Cursor Desktop can load a canonical bundle from `~/.cursor/plugins/local/`. A team marketplace requires a Git repository that contains the generated marketplace and every referenced plugin path. + +Native clients can cache installed plugins. After Dotagents updates a plugin, use the native update or reinstall flow. Replace `` with `project` or `user`: + +```shell +claude plugin marketplace update dotagents +claude plugin update @dotagents --scope +codex plugin remove @dotagents-local --json +codex plugin add @dotagents-local --json +copilot plugin marketplace update dotagents +copilot plugin update @dotagents +``` + +After `dotagents remove`, remove cached native state separately. Replace `` with `project` or `user`: + +```shell +claude plugin uninstall @dotagents --scope +codex plugin remove @dotagents-local --json +copilot plugin uninstall @dotagents +``` + +Dotagents updates and removes Grok, OpenCode, and Pi projections directly. `dotagents doctor` checks canonical bundles and generated outputs. It does not check native marketplace registration, plugin installation, enablement, or caches. ### Trust @@ -506,7 +579,6 @@ Check selected-scope health: gitignore setup where applicable, installed skills | `copilot` | GitHub Copilot CLI | `.copilot` | Project: reads `.agents/skills/`; global: `$COPILOT_HOME/skills/` symlink | `.mcp.json` or `.github/mcp.json` | Not supported | Not supported | | `vscode` | VS Code Copilot | `.vscode` | (reads `.agents/skills/` natively) | `.vscode/mcp.json` | `.claude/settings.json` | Not supported | | `opencode` | OpenCode | `.opencode` | (reads `.agents/skills/` natively) | `.opencode/opencode.jsonc` by default | Not supported | `.opencode/agents/*.md` | - Claude uses `.claude/skills/`, and Cursor shares the same Claude-compatible skills symlink. Codex, VS Code, and OpenCode read `.agents/skills/` directly. [Pi](https://github.com/badlogic/pi-mono) reads `.agents/skills/` natively. Normal skills need no Pi-specific target or symlink configuration; plugin bundles can target `pi` when their `skills/` components should be exposed there. diff --git a/docs/src/content/docs/cli.mdx b/docs/src/content/docs/cli.mdx index 44fe30b..4f59f79 100644 --- a/docs/src/content/docs/cli.mdx +++ b/docs/src/content/docs/cli.mdx @@ -485,7 +485,80 @@ reinterpreting generated adapters as source input. | `path` | string | No | Optional explicit plugin path inside the source. | | `targets` | string[] | No | Optional subset of configured agents. | -Generated plugin outputs include Claude, Cursor, Codex, and Copilot marketplaces, native Claude, Cursor, and Codex manifests, Grok plugin directories, OpenCode skill links and portable MCP entries, and Pi skill links. OpenCode MCP keys use `plugin..`; dotagents expands `${PLUGIN_ROOT}` and `${PLUGIN_DATA}` and preserves unrelated entries in the shared config. Generalized legacy bundles can also project Markdown agents into OpenCode; standard extension agents are preserved but not projected yet. dotagents rejects plugin sources that resolve to the same project's `.agents/plugins//` install destination. Global plugins use `~/.agents/plugins//` and global harness projections. +Generated plugin outputs include marketplaces for Claude, Cursor, Codex, and Copilot. Claude, Cursor, and Codex also receive native manifests when required. Other outputs include Grok plugin directories, OpenCode skill links and portable MCP entries, and Pi skill links. OpenCode MCP keys use `plugin..`; dotagents expands `${PLUGIN_ROOT}` and `${PLUGIN_DATA}` and preserves unrelated entries in the shared config. Generalized legacy bundles can also project Markdown agents into OpenCode; standard extension agents are preserved but not projected yet. dotagents rejects plugin sources that resolve to the same project's `.agents/plugins//` install destination. Global plugins use `~/.agents/plugins//` and global harness projections. + +## Plugin activation + +`dotagents add` and `dotagents install` install canonical plugin bundles and write runtime outputs. These commands do not register marketplaces or install plugins in native client state. + +| Agent ID | Dotagents behavior | Required native action | +| --- | --- | --- | +| `claude` | Generates a marketplace and a native manifest when required. | Register the active scope root and install `@dotagents`. | +| `cursor` | Generates a marketplace and a native manifest when required. | Use Customize, a team marketplace, `~/.cursor/plugins/local`, or `cursor-agent --plugin-dir`. | +| `codex` | Generates `.agents/plugins/marketplace.json` and a native manifest when required. | Register the correct source root and install `@dotagents-local`. | +| `copilot` | Generates `.github/plugin/marketplace.json`. | Register the active scope root and install `@dotagents`. | +| `grok` | Copies the plugin into `.grok/plugins/`. | None. | +| `opencode` | Writes managed skill links and MCP entries. | None. | +| `pi` | Writes managed skill links under `.agents/skills/`. | None. | +| `vscode` | Has no plugin adapter. | None. | + +Project activation commands must run from the project root: + +```shell +claude plugin marketplace add ./ --scope project +claude plugin install @dotagents --scope project +codex plugin marketplace add ./ --json +codex plugin add @dotagents-local --json +copilot plugin marketplace add ./ +copilot plugin install @dotagents +``` + +Default global activation uses `~/.agents` for Claude and Copilot. Codex uses `$HOME` because its catalog is at `$HOME/.agents/plugins/marketplace.json`: + +```shell +claude plugin marketplace add "$HOME/.agents" --scope user +claude plugin install @dotagents --scope user +codex plugin marketplace add "$HOME" --json +codex plugin add @dotagents-local --json +copilot plugin marketplace add "$HOME/.agents" +copilot plugin install @dotagents +``` + +With a custom `DOTAGENTS_HOME`, all three clients register that custom root: + +```shell +claude plugin marketplace add "$DOTAGENTS_HOME" --scope user +claude plugin install @dotagents --scope user +codex plugin marketplace add "$DOTAGENTS_HOME" --json +codex plugin add @dotagents-local --json +copilot plugin marketplace add "$DOTAGENTS_HOME" +copilot plugin install @dotagents +``` + +Claude, Codex, and Copilot cache installed plugins. After Dotagents updates a plugin, refresh Claude, reinstall the Codex plugin, and update the Copilot plugin. Replace `` with `project` or `user`: + +```shell +claude plugin marketplace update dotagents +claude plugin update @dotagents --scope +codex plugin remove @dotagents-local --json +codex plugin add @dotagents-local --json +copilot plugin marketplace update dotagents +copilot plugin update @dotagents +``` + +Native uninstall commands are also separate from `dotagents remove`. Replace `` with `project` or `user`: + +```shell +claude plugin uninstall @dotagents --scope +codex plugin remove @dotagents-local --json +copilot plugin uninstall @dotagents +``` + +Cursor has no marketplace CLI command. Load a canonical project plugin with `cursor-agent --plugin-dir .agents/plugins/`. Use `$HOME/.agents/plugins/` for the default global root or `$DOTAGENTS_HOME/plugins/` for a custom root. Cursor Desktop can load a canonical bundle from `~/.cursor/plugins/local/`. Team marketplaces require a Git repository that contains the generated marketplace and its referenced plugin paths. + +Grok, OpenCode, and Pi read Dotagents-managed outputs directly, so Dotagents updates and removes those projections. VS Code receives no plugin output. + +`dotagents doctor` checks canonical bundles and generated runtime outputs. It does not check native marketplace registration, installation, enablement, or client caches. ## Scopes diff --git a/docs/src/content/docs/guide.mdx b/docs/src/content/docs/guide.mdx index 8542357..93838d2 100644 --- a/docs/src/content/docs/guide.mdx +++ b/docs/src/content/docs/guide.mdx @@ -65,6 +65,138 @@ dotagents --project install Commit `agents.toml`. Collaborators use the project-scoped `install` command to recreate managed local state. +## Plugin activation + +Dotagents plugin installation and native client installation are separate stages: + +1. Dotagents installs the canonical bundle under `.agents/plugins//` for project scope or the global plugin directory. +1. Dotagents writes the runtime output for each selected agent. +1. Marketplace-based clients register that output and install the plugin into native client state. + +`dotagents add` and `dotagents install` complete the first two stages. They do not register a native marketplace or install a plugin into a native client cache. + +| Agent ID | Project output | Native action | +| --- | --- | --- | +| `claude` | `.claude-plugin/marketplace.json` and a native manifest when required | Register the project root, then install `@dotagents`. | +| `cursor` | `.cursor-plugin/marketplace.json` and a native manifest when required | Use Customize, a team marketplace, a local plugin, or `cursor-agent --plugin-dir`. | +| `codex` | `.agents/plugins/marketplace.json` and a native manifest when required | Register the project root, then install `@dotagents-local`. | +| `copilot` | `.github/plugin/marketplace.json` | Register the project root, then install `@dotagents`. | +| `grok` | `.grok/plugins//` | None. Grok reads the managed copy directly. | +| `opencode` | `.opencode/skills/` links and `.opencode/opencode.jsonc` MCP entries | None. OpenCode reads the generated projections directly. | +| `pi` | `.agents/skills/` links | None. Pi reads the generated links directly. | +| `vscode` | No plugin output | None. VS Code has no Dotagents plugin adapter. | + +### Project activation + +Run these commands from the project root after `dotagents --project add` or `dotagents --project install`: + +```shell +claude plugin marketplace add ./ --scope project +claude plugin install @dotagents --scope project + +codex plugin marketplace add ./ --json +codex plugin add @dotagents-local --json + +copilot plugin marketplace add ./ +copilot plugin install @dotagents +``` + +Claude records project marketplace and plugin declarations in project scope. Codex records native plugin state for the current user, even when the source is a project directory. Copilot also records native plugin and marketplace state for the current user, under `COPILOT_HOME`, the Copilot CLI's own configuration and state directory (`~/.copilot` by default). + +### Global activation + +The default global Dotagents root is `~/.agents`. Claude and Copilot scan that root for their generated marketplace. Codex must scan `$HOME` because its generated catalog is at `$HOME/.agents/plugins/marketplace.json`: + +```shell +claude plugin marketplace add "$HOME/.agents" --scope user +claude plugin install @dotagents --scope user + +codex plugin marketplace add "$HOME" --json +codex plugin add @dotagents-local --json + +copilot plugin marketplace add "$HOME/.agents" +copilot plugin install @dotagents +``` + +If `DOTAGENTS_HOME` overrides the global root, all three clients register that custom root. Codex finds its catalog at `$DOTAGENTS_HOME/.agents/plugins/marketplace.json`: + +```shell +claude plugin marketplace add "$DOTAGENTS_HOME" --scope user +claude plugin install @dotagents --scope user + +codex plugin marketplace add "$DOTAGENTS_HOME" --json +codex plugin add @dotagents-local --json + +copilot plugin marketplace add "$DOTAGENTS_HOME" +copilot plugin install @dotagents +``` + +### Cursor activation + +Cursor has no marketplace command in its CLI. Choose one of these paths: + +- In Cursor Desktop, open Customize and install a plugin from the official marketplace or a team marketplace. Choose project or user scope. +- A team admin can import a Git repository that contains the generated `.cursor-plugin/marketplace.json` and every referenced plugin path. Managed Dotagents bundles are usually local and gitignored, so the imported repository must contain those bundles. +- For local Desktop use, link or copy the canonical bundle to `~/.cursor/plugins/local/`, then restart Cursor or run **Developer: Reload Window**. +- For Cursor Agent, load the current canonical bundle with `cursor-agent --plugin-dir `. + +Project, default global, and custom global Cursor Agent examples use these canonical paths: + +```shell +cursor-agent --plugin-dir .agents/plugins/ +cursor-agent --plugin-dir "$HOME/.agents/plugins/" +cursor-agent --plugin-dir "$DOTAGENTS_HOME/plugins/" +``` + +The generated global Cursor marketplace is at `~/.agents/.cursor-plugin/marketplace.json`. A custom root uses `$DOTAGENTS_HOME/.cursor-plugin/marketplace.json`. Cursor cannot register either local marketplace through a CLI command. + +### Update or remove a native plugin + +Run Dotagents `install` or `sync` first. Then refresh marketplace and installed-plugin state for each native client. + +For Claude, replace `` with `project` or `user`: + +```shell +claude plugin marketplace update dotagents +claude plugin update @dotagents --scope +``` + +Codex reads a registered local marketplace from its current source path, but it caches each installed plugin. Remove and add the plugin again after Dotagents updates it: + +```shell +codex plugin remove @dotagents-local --json +codex plugin add @dotagents-local --json +``` + +Copilot also caches each installed plugin. Refresh the marketplace catalog, then update the plugin: + +```shell +copilot plugin marketplace update dotagents +copilot plugin update @dotagents +``` + +Cursor team marketplaces require a manual refresh or configured auto refresh. Update or reinstall the plugin from Customize after the catalog refreshes. Local Desktop plugins use the current linked or copied files after Cursor reloads. Each `cursor-agent --plugin-dir` invocation loads the current directory. + +Remove native state separately when you remove a Dotagents declaration: + +```shell +claude plugin uninstall @dotagents --scope +codex plugin remove @dotagents-local --json +copilot plugin uninstall @dotagents +``` + +After the last plugin from a marketplace is removed, you can also remove its registration: + +```shell +claude plugin marketplace remove dotagents --scope +codex plugin marketplace remove dotagents-local --json +copilot plugin marketplace remove dotagents +``` + +Remove a Cursor local-plugin link or copy yourself. For team or marketplace installations, uninstall the plugin from Customize. Dotagents updates and removes Grok, OpenCode, and Pi projections directly. + +`dotagents doctor` checks canonical bundles and Dotagents-managed runtime outputs. It does not prove that a native marketplace is registered or that a plugin is installed and enabled. + ## What Gets Gitignored In project scope, dotagents keeps two generated files out of version control: