What happened
On PR #205, a human author changed package.json to use Yarn's patch: protocol for the @backstage/cli-node dependency. The review agent (run 34983244011) found a valid but speculative medium finding about a potentially missing ESM patch hunk, but missed the definite CI-breaking issue: all 9 Verify Plugin Export jobs (run 34983241884) failed because verify-plugin-export.yaml line 97 runs npm install -g ./rhdh-cli/rhdh-cli.tgz, and npm cannot resolve Yarn-specific patch: specifiers in package.json dependencies.
What could go better
The review agent had no context about the Verify Plugin Export CI pipeline. AGENTS.md documents build/test commands and code conventions but says nothing about CI workflows, packaging constraints, or the fact that the packed tarball must be installable via npm. Without this context, the agent cannot reason about package manager compatibility. Confidence is high that this is the root cause of the miss — the agent demonstrated strong logical reasoning on the patch file contents (finding the ESM hunk gap) but lacked the domain knowledge about downstream consumption to flag the npm incompatibility.
Proposed change
Add a ## CI & Packaging section to AGENTS.md documenting the key constraint:
## CI & Packaging
- The `verify-plugin-export.yaml` workflow builds the CLI with `yarn pack`,
then installs the resulting tarball via `npm install -g`. Dependencies in
`package.json` must therefore use npm-compatible version specifiers — do not
use Yarn-specific protocols (`patch:`, `portal:`, `workspace:`) in the
`dependencies` or `devDependencies` fields.
- The Verify workflow runs against 9 plugin workspaces (adoption-insights,
bulk-import, extensions, global-header, homepage, orchestrator, quickstart,
scorecard, theme) from the `rhdh-plugin-export-overlays` repo.
This gives the review agent enough context to flag package manager compatibility issues when reviewing package.json changes.
Validation criteria
On the next PR that modifies package.json dependency specifiers in a way that would break npm install, the review agent should flag the npm incompatibility. Verify by checking review findings on the next 3 PRs that touch package.json — the agent should demonstrate awareness of the npm installability constraint.
Generated by retro agent from #205
What happened
On PR #205, a human author changed
package.jsonto use Yarn'spatch:protocol for the@backstage/cli-nodedependency. The review agent (run 34983244011) found a valid but speculative medium finding about a potentially missing ESM patch hunk, but missed the definite CI-breaking issue: all 9 Verify Plugin Export jobs (run 34983241884) failed becauseverify-plugin-export.yamlline 97 runsnpm install -g ./rhdh-cli/rhdh-cli.tgz, and npm cannot resolve Yarn-specificpatch:specifiers inpackage.jsondependencies.What could go better
The review agent had no context about the Verify Plugin Export CI pipeline. AGENTS.md documents build/test commands and code conventions but says nothing about CI workflows, packaging constraints, or the fact that the packed tarball must be installable via npm. Without this context, the agent cannot reason about package manager compatibility. Confidence is high that this is the root cause of the miss — the agent demonstrated strong logical reasoning on the patch file contents (finding the ESM hunk gap) but lacked the domain knowledge about downstream consumption to flag the npm incompatibility.
Proposed change
Add a
## CI & Packagingsection toAGENTS.mddocumenting the key constraint:This gives the review agent enough context to flag package manager compatibility issues when reviewing
package.jsonchanges.Validation criteria
On the next PR that modifies
package.jsondependency specifiers in a way that would breaknpm install, the review agent should flag the npm incompatibility. Verify by checking review findings on the next 3 PRs that touchpackage.json— the agent should demonstrate awareness of the npm installability constraint.Generated by retro agent from #205