From c0336bf8a908447cf225973e82a13b00d48b3a34 Mon Sep 17 00:00:00 2001
From: fullsend-code
 <278716306+fullsend-ai-coder[bot]@users.noreply.github.com>
Date: Mon, 10 Aug 2026 15:14:46 +0000
Subject: [PATCH] docs(#4232): add AiResource typed variant package convention

Add an "AiResource typed variant packages" section to the
ai-integrations workspace AGENTS.md documenting the
discriminated-union package pattern: each spec.type variant
(skill, rule, agent, mcp-server) gets its own dedicated
catalog-model and catalog-backend-module package pair. This
prevents future code agents from placing typed-variant types
in ai-experience-common (as happened in PR #4164) and provides
a 5-step checklist for creating new typed variants.

Closes #4232
---
 workspaces/ai-integrations/AGENTS.md | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/workspaces/ai-integrations/AGENTS.md b/workspaces/ai-integrations/AGENTS.md
index 43ad33060e..badd398d6d 100644
--- a/workspaces/ai-integrations/AGENTS.md
+++ b/workspaces/ai-integrations/AGENTS.md
@@ -22,6 +22,27 @@
 - `packages/` in each plugin is strictly for the dev environment; do not add application code there
 - `ai-experience-common` holds shared types and API definitions used by both frontend and backend
 
+## AiResource typed variant packages
+
+Each AiResource `spec.type` variant (skill, rule, agent, mcp-server, etc.)
+lives in its own dedicated package pair:
+
+- `plugins/catalog-model-ai-resource-{type}/` — TypeScript types, JSON schema,
+  KindValidator, type guard, CatalogModelLayer, and `report.api.md`
+- `plugins/catalog-backend-module-ai-resource-{type}/` — backend module that
+  calls `catalogModelExtensionPoint.addModelSource()` and is wired into
+  `packages/backend/src/index.ts`
+
+Do NOT place typed-variant types in `ai-experience-common`. Follow the
+existing skill/rule packages as the reference implementation. When creating
+a new typed variant:
+
+1. Create both packages following the naming convention above
+2. Export the CatalogModelLayer from the catalog-model package
+3. Wire the backend module into `packages/backend`
+4. Include a smoke test for the backend module export
+5. Add a minor changeset covering both new packages
+
 ## Specifications
 
 - When a task is driven by local implementation specs, check `openspec/changes/` for proposal, design, tasks, and behavioral requirements