docs(#3487): add review guidance for Plugin YAML installation OCI tags

[fullsend-ai-coder]

Add an "Installation Example Version Tags" subsection under "Working with Catalog Entities > Plugin YAML" in AGENTS.md. The guidance instructs reviewers to cross-check OCI version tags in spec.installation blocks against the corresponding Package metadata spec.dynamicArtifact fields, warns about rebase-induced staleness after workspace version bumps, and recommends updating tags to match current Package metadata.

This addresses the gap exposed by PR #3444, where installation examples with bs_1.52.0 tags were merged despite Package metadata having been bumped to bs_1.54.4 after a rebase.

---

Closes #3487

Post-script verification

• Branch is not main/master (agent/3487-plugin-yaml-oci-tag-guidance)
• Secret scan passed (gitleaks — a44f48d2155dfbce297f4ee7646868526f3b4488..HEAD)
• Pre-commit hooks passed (authoritative run on runner)
• Tests ran inside sandbox

[openshift-ci]

Hi @fullsend-ai-coder[bot]. Thanks for your PR.

I'm waiting for a redhat-developer member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work.

Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[fullsend-ai-review]

🤖 Finished Review · ✅ Success · Started 9:29 PM UTC · Completed 9:34 PM UTC

Commit: d57288a · View workflow run →

Runtime: claude · Model: opus → claude-opus-4-6 · Cost: $0.69

[fullsend-ai-review]

Review — approve

Scope: Documentation-only — adds 10 lines to AGENTS.md under Working with Catalog Entities > Plugin YAML.

What this PR does

Adds an #### Installation Example Version Tags subsection that codifies review criteria for cross-checking OCI version tags in Plugin YAML spec.installation blocks against Package metadata spec.dynamicArtifact fields. This addresses a gap exposed by PR #3444, where bs_1.52.0 tags were merged despite Package metadata having been bumped to bs_1.54.4 after a rebase.

Verification

• Field accuracy confirmed: spec.installation exists in multiple Plugin YAML files (e.g., ai-resource.yaml, analytics-provider-segment.yaml, home-page.yaml). The described OCI tag format (bs_<backstage-version>__<plugin-version>) matches actual Package metadata spec.dynamicArtifact values.
• Stale tag scenario confirmed: catalog-entities/extensions/plugins/ai-resource.yaml currently contains bs_1.52.0__0.5.0 and bs_1.52.0__0.4.0 while the corresponding Package metadata in workspaces/ai-integrations/metadata/ has bs_1.54.4__0.5.0 and bs_1.54.4__0.4.0 — the exact mismatch this guidance targets.
• Placement is correct: The new #### subsection sits under ### Plugin YAML, after the field descriptions and plugins/all.yaml note, before ### Package YAML. The heading level and numbered-list format are consistent with existing review criteria sections (e.g., "Major Version Bumps in Patches").
• No injection patterns detected in PR body, commit message, or added content.

Assessment

No findings. The guidance is accurate, appropriately scoped, and addresses a documented real-world gap. The recommended severity level (medium for stale tags) is proportionate — stale OCI tags cause users to install outdated or non-existent plugin versions but don't pose security risks.

---

Protected paths detected — this PR modifies files under one or more
protected paths. The review agent cannot approve PRs that touch these paths.
A human reviewer must approve this PR.

Protected files in this PR:

• AGENTS.md