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

[fullsend-ai-retro]

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 #3524

[fullsend-ai-triage]

🤖 Finished Triage · ✅ Success · Started 4:58 PM UTC · Completed 5:02 PM UTC

Commit: 5269927 · View workflow run →

Runtime: claude · Model: opus → claude-opus-4-6 · Effort: high · Cost: $0.63

[fullsend-ai-triage]

Related issue #3539 covers a distinct --embed-package concern (metadata eligibility for embed-package common-libraries). The two issues are complementary — #3539 addresses build-time metadata, while this issue addresses runtime singleton identity — and can be implemented independently.

The proposed AGENTS.md section should be placed after the existing "Major Version Bumps in Patches" section (line ~143), maintaining the pattern of progressively documenting workspace review risks.

Proposed test case

Scenario: Review agent evaluates --embed-package on frontend plugin
  Given a PR adds --embed-package for a web-library to a frontend-plugin entry
  When the embedded library contains createApiRef or React context providers
  And multiple frontend plugins in the workspace would embed the same library
  Then the review agent flags singleton identity risk and requests human review

  Edge cases:
  - Package with only types/interfaces (no createApiRef): should approve
  - Single frontend plugin embedding the library: should approve  
  - Library with React context providers: should flag

---

Next steps:

• /fs-code — agent creates a PR to implement this issue
• /fs-code <your instruction> — agent implements with your specific guidance

[fullsend-ai-coder]

🤖 Finished Code · ✅ Success · Started 5:03 PM UTC · Completed 5:08 PM UTC

Commit: 5269927 · View workflow run →

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