getsentry · dcramer · Jun 12, 2026 · Jun 12, 2026 · Jun 12, 2026 · Jun 12, 2026
diff --git a/.gitignore b/.gitignore
@@ -9,6 +9,9 @@ docs/.astro/
 agents.lock
 .agents/.gitignore
 
+# Local QA credentials
+.env.qa.local
+
 # openspec local install artifacts (per-machine, not project source)
 openspec/
 .agents/skills/openspec-*/

diff --git a/AGENTS.md b/AGENTS.md
@@ -6,7 +6,7 @@ Use **pnpm**: `pnpm install`, `pnpm build`, `pnpm test`
 
 ## What This Project Is
 
-dotagents is shared tooling for coding agents. It manages skills, MCP servers, and hooks declared in `agents.toml`, and handles symlinks and config generation so tools like Claude Code can be configured from a single source of truth.
+dotagents is shared tooling for coding agents. It manages skills, subagents, plugins, MCP servers, and hooks declared in `agents.toml`, and handles symlinks and config generation so tools like Claude Code can be configured from a single source of truth.
 
 See `specs/SPEC.md` for the full design.
 
@@ -21,7 +21,10 @@ packages/
 │       ├── index.ts          # Library entry point (re-exports lib symbols with @deprecated)
 │       ├── scope.ts          # Project/user scope resolution
 │       ├── cli/              # CLI entry point + commands (init, install, add, remove, sync, list, mcp, doctor, trust)
-│       ├── agents/           # Agent definitions, MCP/hook config writers
+│       ├── targets/          # Target agent definitions plus MCP/hook config writers
+│       ├── subagents/        # Subagent identity, store, and runtime writer
+│       ├── plugins/          # Plugin schema/store and target-specific runtime projection
+│       ├── agents/           # Compatibility re-export barrel for older internal imports
 │       ├── config/           # agents.toml schema, loader, writer
 │       ├── lockfile/         # agents.lock schema, loader, writer
 │       ├── symlinks/         # Symlink creation/management

diff --git a/README.md b/README.md
@@ -1,16 +1,16 @@
 # dotagents
 
-Shared tooling for coding agents. Declare skills, MCP servers, hooks, and subagents in `agents.toml` — dotagents wires them into every agent tool on your team.
+Shared tooling for coding agents. Declare skills, MCP servers, hooks, subagents, and plugins in `agents.toml` — dotagents wires them into every agent tool on your team.
 
 ## Why dotagents?
 
 **One source of truth.** Skills live in `.agents/skills/` and symlink into `.claude/skills/` or wherever your tools expect them. Cursor shares Claude-compatible skills. No copy-pasting between directories.
 
-**One command to install.** `agents.toml` is committed, managed skills and canonical installed subagents under `.agents/` are gitignored. Collaborators run `dotagents install` to fetch or refresh local agent state.
+**One command to install.** `agents.toml` is committed, managed skills, canonical installed subagents, and managed plugin bundles under `.agents/` are gitignored. Collaborators run `dotagents install` to fetch or refresh local agent state.
 
 **Shareable.** Skills are directories with a `SKILL.md`. Host them in any git repo, discover them automatically, install with one command.
 
-**Multi-agent.** Configure Claude, Cursor, Codex, VS Code, and OpenCode from a single `agents.toml` -- skills, MCP servers, hooks, and subagents where supported. Pi reads `.agents/skills/` directly.
+**Multi-agent.** Configure Claude, Cursor, Codex, Grok, VS Code, and OpenCode from a single `agents.toml` -- skills, MCP servers, hooks, subagents, and plugins where supported. Pi reads `.agents/skills/` directly.
 
 ## Quick Start
 
@@ -31,9 +31,9 @@ npx @sentry/dotagents add getsentry/skills find-bugs code-review commit
 npx @sentry/dotagents add getsentry/skills --all
 ```
 
-This creates an `agents.toml` at your project root and an `agents.lock` tracking installed skills and subagents.
+This creates an `agents.toml` at your project root and an `agents.lock` tracking installed skills, subagents, and plugins.
 
-After cloning a project that already has `agents.toml`, run `install` to fetch skills and subagents. Run it again to refresh managed local state:
+After cloning a project that already has `agents.toml`, run `install` to fetch skills, subagents, and plugins. Run it again to refresh managed local state:
 
 ```bash
 npx @sentry/dotagents install
@@ -47,7 +47,7 @@ npx @sentry/dotagents install
 | `add <source> [skills...]` | Add skill dependencies |
 | `remove <name\|source> [-y]` | Remove a skill or all skills from a source |
 | `install` | Install all dependencies from `agents.toml` |
-| `list` | Show installed skills and their status |
+| `list` | Show declared skills, plugins, and their status |
 | `sync` | Reconcile state offline: adopt local skills, prune stale managed ones, repair configs |
 | `mcp` | Manage MCP server declarations |
 | `trust` | Manage trusted sources |
@@ -92,14 +92,15 @@ Shorthand (`owner/repo`) resolves to GitHub by default. Set `defaultRepositorySo
 The `agents` field tells dotagents which tools to configure:
 
 ```toml
-agents = ["claude", "cursor", "codex", "opencode"]
+agents = ["claude", "cursor", "codex", "grok", "opencode", "pi"]
 ```
 
 | Agent | Config Dir | MCP Config | Hooks | Subagents |
 |-------|-----------|------------|-------|-----------|
 | `claude` | `.claude` | `.mcp.json` | `.claude/settings.json` | `.claude/agents/*.md` |
 | `cursor` | `.cursor` | `.cursor/mcp.json` | `.cursor/hooks.json` | `.cursor/agents/*.md` |
 | `codex` | `.codex` | `.codex/config.toml` | -- | `.codex/agents/*.toml` |
+| `grok` | `.grok` | -- | -- | -- |
 | `vscode` | `.vscode` | `.vscode/mcp.json` | `.claude/settings.json` | -- |
 | `opencode` | `.opencode` | `opencode.json` | -- | `.opencode/agents/*.md` |
 
@@ -127,11 +128,25 @@ Review the current diff and return findings with file references.
 
 dotagents can also import native runtime subagent files from `.claude/agents/`, `.cursor/agents/`, `.codex/agents/*.toml`, and `.opencode/agents/`. Input and matching-runtime output use the same native format: Markdown with YAML frontmatter for Claude, Cursor, and OpenCode; TOML for Codex. Claude and Codex identify agents by `name`, Cursor can derive `name` from the filename when omitted, and OpenCode uses the filename as the agent name. Multiple portable matches for the same subagent are rejected as ambiguous, while matching native runtime artifacts are merged. When the source format matches a target runtime, dotagents reuses the native source content for that runtime and only adds its managed-file marker. Other runtimes are generated from the portable `name`, `description`, and instructions. Subagent declarations intentionally cover only dependency source and runtime targets, not universal model/tool/permission behavior.
 
-[Pi](https://github.com/badlogic/pi-mono) reads `.agents/skills/` natively and needs no configuration.
+Plugins are declared with `[[plugins]]` entries. dotagents installs canonical bundles into `.agents/plugins/<name>/` and generates runtime plugin outputs such as `.claude-plugin/marketplace.json`, `.agents/plugins/<name>/.claude-plugin/plugin.json`, `.cursor-plugin/marketplace.json`, `.agents/plugins/<name>/.cursor-plugin/plugin.json`, `.agents/plugins/marketplace.json`, `.agents/plugins/<name>/.codex-plugin/plugin.json`, `.grok/plugins/<name>/`, `.opencode/skills/<skill>/`, `.opencode/agents/<agent>.md`, and Pi skill links under `.agents/skills/<skill>/` where supported:
+
+```toml
+[[plugins]]
+name = "review-tools"
+source = "getsentry/agent-plugins"
+path = "plugins/review-tools"
+targets = ["claude", "cursor", "codex", "grok", "opencode", "pi"]
+```
+
+The canonical plugin format is `.agents/plugins/marketplace.json` plus `.agents/plugins/<name>/plugin.json`, using a Codex-compatible marketplace baseline. Known input fields are validated, component paths must be relative filesystem paths, unknown manifest extension fields are preserved in installed bundles, marketplace extension fields are accepted but not projected, `targets` are limited to configured agents, and generated outputs are deterministic. dotagents rejects plugin sources that resolve to the same project's `.agents/plugins/<name>/` install destination, so same-repo plugins are never installed onto themselves.
+
+Plugin declarations are project-scope only for now. `dotagents --user install` rejects `[[plugins]]` entries because user-scope runtime plugin projections are not generated yet.
+
+[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.
 
 ## Documentation
 
-For the full guide -- including MCP servers, hooks, subagents, trust policies, wildcard skills, user scope, and CI setup -- see the [documentation site](https://dotagents.sentry.dev).
+For the full guide -- including MCP servers, hooks, subagents, plugins, trust policies, wildcard skills, user scope, and CI setup -- see the [documentation site](https://dotagents.sentry.dev).
 
 ## Contributing