redhat-developer / redhat-developer/rhdh-cli

Add CI packaging constraints to AGENTS.md so review agent catches npm/Yarn incompatibilities

Open Beginner friendly
#209 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation ready-for-triage ready-to-code
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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.