Add AGENTS.md review guidance: --embed-package on frontend plugins risks breaking singleton API references

Start with AGENTS.md and the existing “Overlay vs Patch” and “Major Version Bumps in Patches” sections, then review plugins-list.yaml entries for frontend-plugin and backend --embed-package usage. Add the requested guidance on Module Federation singleton identity and review criteria, and validate it against the next three review-agent runs affecting frontend entries.

What happened

In PR #3524, --embed-package flags were added for orchestrator-form-api, orchestrator-form-react, and orchestrator-common to two frontend plugin entries in plugins-list.yaml. The review agent (run 33641873741) approved it by verifying that backend plugins in the same file already use --embed-package, concluding the pattern was safe. A domain expert (davidfestal) later identified the solution as invalid, and the PR was closed without merging.

The root cause: frontend dynamic plugins use Module Federation (Scalprum/Webpack). When --embed-package bundles a web-library that defines a createApiRef singleton (like orchestratorFormApiRef), each frontend plugin gets its own copy of the singleton object. Two copies means two different object references in Backstage's ApiHolder Map — the provider plugin (orchestrator-form-widgets) registers with one ref, the consumer (orchestrator) looks up another, and the API lookup fails silently at runtime. This does not affect backend plugins, which load as separate Node.js modules with no shared singleton registry.

What could go better

The review agent had no guidance distinguishing frontend and backend --embed-package semantics. AGENTS.md documents overlay vs patch mechanics and major version bump risks, but does not explain that frontend plugins share a browser runtime via Module Federation where singleton identity matters, while backend plugins run in isolated Node.js modules where duplication is safe.

Without this guidance, the agent applied pattern-matching logic: "backend plugins in this file already embed packages, so the same pattern is safe for frontend plugins." This is a reasonable heuristic that happens to be wrong for this specific architectural reason. Confidence is high that adding explicit guidance would prevent this class of false positive — the review agent demonstrably follows AGENTS.md constraints when they exist (it correctly applied major-version-bump review criteria in other PRs).

Note: existing issue #3539 covers a related but distinct concern (embed-package libraries not getting standalone metadata entries). This proposal addresses the runtime singleton identity problem, which is a separate failure mode not covered by any open issue.

Proposed change

Add a new section to AGENTS.md under "Working with Workspaces" (near the existing "Overlay vs Patch" and "Major Version Bumps in Patches" sections) titled "Embedding packages in frontend vs backend plugins."

The section should explain:

1. Backend plugins load as separate Node.js modules. Embedding creates isolated copies of dependencies — safe because no shared singleton registry exists across backend modules.

2. Frontend plugins use Module Federation (Scalprum/Webpack). Each plugin runs in the same browser runtime but in a separate Webpack container. Embedding a dependency creates a private copy inside the container.

3. The singleton identity problem: When a web-library defines a createApiRef singleton (via Backstage's createApiRef), two frontend plugins that both embed that library will each get a separate object reference. Backstage's ApiHolder uses a Map keyed by object identity, so the provider's ref and the consumer's ref are different objects — the API lookup returns undefined at runtime.

4. Review criteria for --embed-package on frontend plugins:

   • When a PR adds --embed-package for a web-library to a frontend-plugin entry in plugins-list.yaml, check whether that library defines any createApiRef calls, React contexts, or other singleton patterns.
   • If it does, and multiple frontend plugins in the same workspace would embed the same library, flag the change as a potential runtime failure and request human review.
   • This does NOT apply to -common or -node suffixed packages that contain only types, interfaces, and constants (no createApiRef or context providers).
   • Embedding web-libraries in a single frontend plugin (not shared across plugins) is safe.
   • When the PR claims to fix a build-pipeline issue (e.g., BODY DRIFT, sync-midstream scrubbing), verify the fix doesn't introduce a runtime regression in the plugin architecture.

Validation criteria

The next time a PR proposes adding --embed-package for a web-library to frontend plugin entries in plugins-list.yaml, the review agent should either: (a) flag the singleton identity risk and request human review, or (b) verify the embedded package contains no createApiRef or context provider patterns before approving. Validate against the next 3 review agent runs that touch plugins-list.yaml frontend entries with --embed-package changes.

Generated by retro agent from https://github.com/redhat-developer/rhdh-plugin-export-overlays/pull/3524