diff --git a/AGENTS.md b/AGENTS.md index 30deedf5bf1..21244765491 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -123,6 +123,17 @@ conservative at the waist. without E2E proof, and plugins that touch core files.** Plugins live in their own directory and work within the ABCs/hooks we provide; if a plugin needs more, widen the generic plugin surface, don't special-case it in core. +- **Third-party products / other people's projects integrated into the core + tree.** Observability backends, vendor SaaS integrations, analytics dashboards, + and similar "someone else's product" plugins do NOT land under `plugins/` in + this repo. They place an ongoing maintenance burden on us to keep them working + against a fast-moving core, for a backend we don't own. Ship them as a + **standalone plugin repo** users install into `~/.hermes/plugins/` (or via a + pip entry point), and promote them in the Nous Research Discord + (`#plugins-skills-and-skins`). This is a coupling-and-maintenance decision, not + a quality bar — the plugin can be excellent and still be a close. PRs that add + such a directory to the tree are closed with a pointer to publish it as its own + repo. ### Before you call it a bug — verify the premise (and when NOT to close) @@ -783,6 +794,24 @@ landing in this tree. PRs that add a new directory under provider as its own repo. Existing in-tree providers stay; bug fixes to them are welcome. +**No new third-party-product plugins in-tree (policy, June 2026):** the +same rule applies beyond memory providers. Plugins that integrate +someone else's product or project — observability/metrics backends, +vendor SaaS connectors, analytics dashboards, paid-service tie-ins — +must ship as **standalone plugin repos** that users install into +`~/.hermes/plugins/` (or via pip entry points). They register through +the existing plugin discovery path and use the ABCs/hooks/ctx surface +we expose; nothing special is needed in core. The reason is +maintenance load: every product we absorb into the tree becomes our +burden to keep working against a fast-moving core, for a backend we +don't own. Promote standalone plugins in the Nous Research Discord +(`#plugins-skills-and-skins`). PRs that add such a directory under +`plugins/` are closed with a pointer to publish it as its own repo — +this is a coupling decision, not a quality judgment. (The +`observability/`, `kanban/`, `disk-cleanup/`, etc. directories already +in the tree are existing precedent, not an invitation to add more +third-party-product plugins alongside them.) + ### Model-provider plugins (`plugins/model-providers//`) Every inference backend (openrouter, anthropic, gmi, deepseek, nvidia, …) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 045d8097f88..7f56b971d1e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -85,6 +85,23 @@ This isn't a quality bar — it's a coupling-and-maintenance decision. Memory pr --- +## Third-Party Product Integrations: Ship as a Standalone Plugin + +The same rule extends to **any plugin that integrates someone else's product or project** — observability/metrics backends, vendor SaaS connectors, analytics dashboards, paid-service tie-ins, and similar third-party integrations. **These do not land in this repo.** + +The reason is maintenance load, not quality. Every external product absorbed into the core tree becomes ours to keep working against a fast-moving codebase, for a backend we don't own and can't control. Hermes ships a lot and the core moves quickly; coupling third-party products into it creates an open-ended burden on the maintainers. + +Publish these as a **standalone plugin repo** instead: + +- Implement the relevant ABC and use the existing plugin discovery path (`~/.hermes/plugins/`, project `.hermes/plugins/`, or a pip entry point) — see [Build a Hermes Plugin](https://hermes-agent.nousresearch.com/docs/guides/build-a-hermes-plugin) +- Register lifecycle hooks (`pre_tool_call`, `post_tool_call`, `pre_llm_call`, `post_llm_call`, `on_session_start`, `on_session_end`), tools (`ctx.register_tool`), and CLI subcommands (`ctx.register_cli_command`) through the surface we already expose — no core changes needed +- If your plugin needs a capability the framework doesn't expose, that's a feature request to **widen the generic plugin surface** (a new hook or `ctx` method) — never special-case your plugin in core +- Promote it in the [Nous Research Discord](https://discord.gg/NousResearch) `#plugins-skills-and-skins` channel so users can find and install it + +A well-built third-party-product plugin can clear automated review and still be closed for this reason — it's a placement decision, not a verdict on the code. PRs that add such a directory under `plugins/` will be closed with a pointer to publish it as its own repo. + +--- + ## Development Setup ### Prerequisites diff --git a/infographic/standalone-plugin-policy/infographic.png b/infographic/standalone-plugin-policy/infographic.png new file mode 100644 index 00000000000..c3295188906 Binary files /dev/null and b/infographic/standalone-plugin-policy/infographic.png differ diff --git a/website/docs/guides/build-a-hermes-plugin.md b/website/docs/guides/build-a-hermes-plugin.md index eacbec0174f..90361a76348 100644 --- a/website/docs/guides/build-a-hermes-plugin.md +++ b/website/docs/guides/build-a-hermes-plugin.md @@ -32,6 +32,10 @@ Hermes has several distinct pluggable interfaces — some use Python `register_* See the full [Pluggable interfaces table](/user-guide/features/plugins#pluggable-interfaces--where-to-go-for-each) for a consolidated view of every extension surface including config-driven (TTS, STT, MCP, shell hooks) and drop-in directory (gateway hooks) styles. ::: +:::caution Third-party-product plugins ship standalone — not into the core tree +Plugins that integrate **someone else's product or project** — observability/metrics backends, vendor SaaS connectors, analytics dashboards, paid-service tie-ins — are built and distributed as **standalone plugin repos**, not merged into `NousResearch/hermes-agent`. Users install them into `~/.hermes/plugins/` or via a pip entry point; everything in this guide works the same way from a standalone repo. This is a coupling-and-maintenance decision (the core moves fast and we don't own your backend), not a quality bar — a plugin can be excellent and still belong in its own repo. Promote it in the Nous Research Discord `#plugins-skills-and-skins` channel. See [CONTRIBUTING.md](https://github.com/NousResearch/hermes-agent/blob/main/CONTRIBUTING.md) for the policy. +::: + ## What you're building A **calculator** plugin with two tools: