From 67fb1df352f80e0d3adda2c7f0548e636bd083c5 Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sat, 16 May 2026 12:38:35 +0100 Subject: [PATCH] docs: prefer clean refactors over compat shims --- AGENTS.md | 4 +++- extensions/AGENTS.md | 8 ++++---- src/plugin-sdk/AGENTS.md | 3 ++- 3 files changed, 9 insertions(+), 6 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 2ebc0660d7a2..d403a6d26543 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -35,7 +35,9 @@ Skills own workflows; root owns hard policy and routing. - External official plugins own package/deps and are excluded from core dist; core uses registry-aware `facade-runtime` or generic contracts. - Externalizing a bundled plugin: update package excludes, official catalogs, docs, tests, and prove core runtime paths resolve installed plugin roots before root-dep removal. - Legacy config repair belongs in `openclaw doctor --fix`, not startup/load-time core migrations. Runtime paths use canonical contracts. -- New seams: backward-compatible, documented, versioned. Third-party plugins exist. +- Fix shape: prefer bounded owner-boundary refactors over local patches/shims when they remove stale abstractions, duplicate policy, or wrong ownership. +- Compat default: no new internal shims, aliases, fallback APIs, or legacy names just to reduce diff. Migrate callers and delete old paths. +- Public plugin API is the only compat exception: document/version breaks, aggressively deprecate unused SDK surface, and migrate ALL bundled/internal plugins to the modern API in the same change. - Channels are implementation under `src/channels/**`; plugin authors get SDK seams. Providers own auth/catalog/runtime hooks; core owns generic loop. - Hot paths should carry prepared facts forward: provider id, model ref, channel id, target, capability family, attachment class. Do not rediscover with broad plugin/provider/channel/capability loaders. - Do not fix repeated request-time discovery with scattered caches. Move the canonical fact earlier; reuse prepared runtime objects; delete duplicate lookup branches. diff --git a/extensions/AGENTS.md b/extensions/AGENTS.md index 1fc8789bd5e3..e1d8f357bf75 100644 --- a/extensions/AGENTS.md +++ b/extensions/AGENTS.md @@ -75,9 +75,9 @@ third-party plugins see. ## Expanding The Boundary -- If an extension needs a new seam, add a typed Plugin SDK subpath or additive - export instead of reaching into core. -- Keep new plugin-facing seams backwards-compatible and versioned. Third-party - plugins consume this surface. +- If an extension needs a new seam, add or replace a typed Plugin SDK subpath + instead of reaching into core. +- ALL bundled plugins must move to modern SDK seams in the same change. Do not + keep extension-local compat paths for internal callers. - When intentionally expanding the contract, update the docs, exported subpath list, package exports, and API/contract checks in the same change. diff --git a/src/plugin-sdk/AGENTS.md b/src/plugin-sdk/AGENTS.md index 66017d5c6196..6b8b7196a131 100644 --- a/src/plugin-sdk/AGENTS.md +++ b/src/plugin-sdk/AGENTS.md @@ -76,7 +76,8 @@ can affect bundled plugins and third-party plugins. ## Expanding The Boundary -- Additive, backwards-compatible changes are the default. +- SDK surface is too large. Do not add compat barrels, aliases, or fallback exports for convenience. Replace old entrypoints when cleaner. +- Public third-party API is the only compat exception: document/version breaks, migrate ALL bundled/internal plugins first, then aggressively deprecate unused exports. - When adding or changing a public subpath, keep these aligned: - docs in `docs/plugins/*` - `scripts/lib/plugin-sdk-entrypoints.json`