What happened
On PR #4164, the code agent implemented the AgentAiResourceEntityV1alpha1 typed schema by placing all types, validators, JSON schema, and type guards in the shared ai-experience-common package. The human reviewer (review) identified this as architecturally wrong — the existing skill and rule AiResource variants each live in their own dedicated catalog-model-* package, and the agent variant should follow the same discriminated-union pattern. This required fix iteration 1 to create two entirely new packages (catalog-model-ai-resource-agent and catalog-backend-module-ai-resource-agent) and move all code — a 20-file, ~390-line restructuring. The issue body referenced "design D10: start from upstream @backstage/catalog-model alpha AiResource skill/rule types + validators" but the code agent did not infer the dedicated-package pattern from this reference. The review agent also missed the package placement issue, finding 5 other issues but not the architectural one.
What could go better
The code agent had no explicit guidance in the workspace AGENTS.md about the discriminated-union package pattern for AiResource typed variants. The issue specs referenced OpenSpec design documents (design D10), but the code agent either did not read them or did not extract the key pattern: each spec.type variant (skill, rule, agent, mcp-server) gets its own catalog-model-ai-resource-{type} package with a corresponding catalog-backend-module-ai-resource-{type} backend module. This is a high-confidence gap: the pattern is well-established in the workspace (skill and rule variants already exist as dedicated packages), the issue series has 29 stories (#4039 is issue 1), and future typed variants will follow the same pattern. Adding this convention to the workspace AGENTS.md would have prevented the entire fix-iteration-1 restructuring and saved ~23 minutes of agent compute plus ~24 hours of review cycle time. The review agent would also benefit from this context when checking future PRs.
Proposed change
Add a "Typed variant package pattern" section to workspaces/ai-integrations/AGENTS.md documenting the discriminated-union package convention:
## 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 packagesThis should be placed after any existing architectural guidance in the workspace AGENTS.md.
Validation criteria
On the next code agent PR that adds a new AiResource typed variant (e.g., from the 29-issue series), the code agent should create a dedicated catalog-model-ai-resource-{type} and catalog-backend-module-ai-resource-{type} package pair from the initial commit. The human reviewer should not need to request a package restructuring. Verify on the next 2-3 typed-variant PRs in the ai-integrations workspace.
Generated by retro agent from #4164
What happened
On PR #4164, the code agent implemented the
AgentAiResourceEntityV1alpha1typed schema by placing all types, validators, JSON schema, and type guards in the sharedai-experience-commonpackage. The human reviewer (review) identified this as architecturally wrong — the existingskillandruleAiResource variants each live in their own dedicatedcatalog-model-*package, and theagentvariant should follow the same discriminated-union pattern. This required fix iteration 1 to create two entirely new packages (catalog-model-ai-resource-agentandcatalog-backend-module-ai-resource-agent) and move all code — a 20-file, ~390-line restructuring. The issue body referenced "design D10: start from upstream @backstage/catalog-model alpha AiResource skill/rule types + validators" but the code agent did not infer the dedicated-package pattern from this reference. The review agent also missed the package placement issue, finding 5 other issues but not the architectural one.What could go better
The code agent had no explicit guidance in the workspace AGENTS.md about the discriminated-union package pattern for AiResource typed variants. The issue specs referenced OpenSpec design documents (design D10), but the code agent either did not read them or did not extract the key pattern: each
spec.typevariant (skill, rule, agent, mcp-server) gets its owncatalog-model-ai-resource-{type}package with a correspondingcatalog-backend-module-ai-resource-{type}backend module. This is a high-confidence gap: the pattern is well-established in the workspace (skill and rule variants already exist as dedicated packages), the issue series has 29 stories (#4039 is issue 1), and future typed variants will follow the same pattern. Adding this convention to the workspace AGENTS.md would have prevented the entire fix-iteration-1 restructuring and saved ~23 minutes of agent compute plus ~24 hours of review cycle time. The review agent would also benefit from this context when checking future PRs.Proposed change
Add a "Typed variant package pattern" section to
workspaces/ai-integrations/AGENTS.mddocumenting the discriminated-union package convention:This should be placed after any existing architectural guidance in the workspace AGENTS.md.
Validation criteria
On the next code agent PR that adds a new AiResource typed variant (e.g., from the 29-issue series), the code agent should create a dedicated
catalog-model-ai-resource-{type}andcatalog-backend-module-ai-resource-{type}package pair from the initial commit. The human reviewer should not need to request a package restructuring. Verify on the next 2-3 typed-variant PRs in the ai-integrations workspace.Generated by retro agent from #4164