Add CI packaging constraints to AGENTS.md so review agent catches npm/Yarn incompatibilities
Nobody has claimed this yet.
Assessment
- Difficulty
- 1/5
- Estimated time
- Under an hour
- Newbie friendliness
- 88/100
- Issue type
- Documentation
- Clarity
- Clearly specified
- Activity status
- Active
- Domain
- build-system, ci-cd, documentation
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.
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
- Dominant language
- TypeScript
- Stars
- 6
- Forks
- 14
- Avg merge
- 2d 14h
- Merged PRs (30d)
- 25
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.
More from redhat-developer/rhdh-cli
-
documentation ready-for-triage ready-to-code
Difficulty 1/5 1-3 hours Newbie friendliness 88/100
redhat-developer/rhdh-cli#206 · 3 comments ·
-
documentation ready-for-triage ready-to-code
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
redhat-developer/rhdh-cli#199 · 3 comments ·
-
bug ready-for-triage triaged
Difficulty 3/5 1-2 days Newbie friendliness 72/100
redhat-developer/rhdh-cli#203 · 2 comments ·
All issues in redhat-developer/rhdh-cli
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
Eynzof/Hermes-CN-Desktop#610 ·
-
bug clawsweeper:linked-pr-open clawsweeper:needs-live-repro clawsweeper:no-new-fix-pr impact:message-loss issue-rating: 🐚 platinum hermit P2 regression
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
-
enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
-
calcite-components needs triage refactor
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
Esri/calcite-design-system#15203 ·
-
Difficulty 1/5 Under an hour Newbie friendliness 78/100
fullcalendar/fullcalendar#8106 ·