redhat-developer / redhat-developer/rhdh-cli
Add CI packaging constraints to AGENTS.md so review agent catches npm/Yarn incompatibilities
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 6
- Forks
- 14
- Avg merge
- 2d 14h
- Merged PRs (30d)
- 25
Description
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 https://github.com/redhat-developer/rhdh-cli/pull/205
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Open AGENTS.md and compare its existing build and test guidance with .github/workflows/verify-plugin-export.yaml, especially line 97. Add the proposed CI & Packaging guidance, then confirm that it covers the npm installation constraint and the nine plugin workspaces; validation is checking review findings on the next three package.json dependency changes.
Written by the indexing model from the issue text.
Assessment
- Domain
- build-system, ci-cd, documentation
- Issue type
- Documentation
- Difficulty
- 1/5
- Estimated time
- Under an hour
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 88/100