What happened
On PR #4211, the review agent raised ~10 naming and convention findings across 3 review rounds. All were dismissed by the human reviewer because the new packages explicitly replicate the upstream backstage/backstage#34476 schema as a stopgap, so upstream conventions intentionally take precedence over workspace-local patterns.
Specific examples dismissed as matching upstream:
- Interface names omit version suffix (
AiModelServerApiEntity vs workspace convention AgentAiResourceEntityV1alpha1)
apiVersion field inherits broad string type instead of pinning a literal union- Type guard omits
apiVersion check (dedicated kinds don't need it per upstream pattern)
moduleId uses short form ('ai-model-server') matching upstream 'ai-model' convention
The current workspace AGENTS.md documents build commands, architecture, Backstage backend conventions, and PR conventions, but has no guidance on upstream-tracking packages or when upstream conventions override workspace conventions.
What could go better
The review agent has no way to distinguish workspace-convention deviations that are bugs from deviations that are intentional upstream alignment. Without this context, it correctly flags each deviation — but every finding is a false positive for upstream-tracking packages. This cost the human reviewer time responding to ~10 non-actionable findings across 3 rounds.
I'm confident this pattern will recur: the ai-integrations workspace already replicates upstream schemas as stopgaps (this PR and potentially future upstream features), and the review agent will continue flagging convention deviations on each one. The existing AGENTS.md already documents workspace-specific conventions (e.g., targetPluginId usage, config visibility), so adding upstream-precedence guidance fits the established pattern.
Related but distinct from #4232 (which documents the AiResource discriminated-union package placement convention, not naming/API convention precedence).
Proposed change
Add an "Upstream-Tracking Packages" section to workspaces/ai-integrations/AGENTS.md documenting:
- Some packages in this workspace replicate upstream
backstage/backstage schemas as stopgaps while upstream PRs are pending. These packages reference the upstream PR in their changeset or linked issue.
- When a package explicitly tracks an upstream PR, upstream naming conventions (interface names, version suffixes, type guard patterns, moduleId format, apiVersion typing) take precedence over workspace-local conventions.
- Reviewers should not flag convention deviations that match the cited upstream code — these are intentional for migration parity.
- The upstream PR number must be documented in the changeset description or linked issue so agents can identify upstream-tracking packages.
Validation criteria
On the next 3 PRs in the ai-integrations workspace that track an upstream Backstage PR and reference it in the changeset or issue, the review agent should produce zero naming-convention findings for patterns that match the cited upstream code. Currently the baseline is ~3-4 such findings per review round.
Generated by retro agent from #4211
What happened
On PR #4211, the review agent raised ~10 naming and convention findings across 3 review rounds. All were dismissed by the human reviewer because the new packages explicitly replicate the upstream
backstage/backstage#34476schema as a stopgap, so upstream conventions intentionally take precedence over workspace-local patterns.Specific examples dismissed as matching upstream:
AiModelServerApiEntityvs workspace conventionAgentAiResourceEntityV1alpha1)apiVersionfield inherits broadstringtype instead of pinning a literal unionapiVersioncheck (dedicated kinds don't need it per upstream pattern)moduleIduses short form ('ai-model-server') matching upstream'ai-model'conventionThe current workspace AGENTS.md documents build commands, architecture, Backstage backend conventions, and PR conventions, but has no guidance on upstream-tracking packages or when upstream conventions override workspace conventions.
What could go better
The review agent has no way to distinguish workspace-convention deviations that are bugs from deviations that are intentional upstream alignment. Without this context, it correctly flags each deviation — but every finding is a false positive for upstream-tracking packages. This cost the human reviewer time responding to ~10 non-actionable findings across 3 rounds.
I'm confident this pattern will recur: the ai-integrations workspace already replicates upstream schemas as stopgaps (this PR and potentially future upstream features), and the review agent will continue flagging convention deviations on each one. The existing AGENTS.md already documents workspace-specific conventions (e.g.,
targetPluginIdusage, config visibility), so adding upstream-precedence guidance fits the established pattern.Related but distinct from #4232 (which documents the AiResource discriminated-union package placement convention, not naming/API convention precedence).
Proposed change
Add an "Upstream-Tracking Packages" section to
workspaces/ai-integrations/AGENTS.mddocumenting:backstage/backstageschemas as stopgaps while upstream PRs are pending. These packages reference the upstream PR in their changeset or linked issue.Validation criteria
On the next 3 PRs in the ai-integrations workspace that track an upstream Backstage PR and reference it in the changeset or issue, the review agent should produce zero naming-convention findings for patterns that match the cited upstream code. Currently the baseline is ~3-4 such findings per review round.
Generated by retro agent from #4211