docs: split AGENTS.md into shared + pacquet-specific#11640
Merged
Conversation
Before: root AGENTS.md and pacquet/AGENTS.md each maintained their own
copy of the GitHub PR workflow, agent-footer rule, "never ignore test
failures," Conventional Commits list, and code-reuse philosophy.
Drift waiting to happen.
After:
- Root AGENTS.md owns the shared conventions (PR workflow, agent
footer, conventional commits, code reuse, never-ignore-tests,
PR-conflict script) and marks TS-only sections explicitly
(setup/build, testing, linting, changesets, Standard Style, Jest
gotchas).
- pacquet/AGENTS.md opens with "Read ../AGENTS.md first" and keeps
only pacquet-specific rules (cardinal rule, branded types, just
recipes, insta snapshots, miette diagnostics, Rust style notes,
the `bench:` commit type, things-not-to-do that are Rust-flavored).
- Root adds a one-line entry for `pacquet/` in the repo structure
list so first-time readers find the cross-link.
CLAUDE.md and pacquet/{CLAUDE,GEMINI}.md are unchanged — they're
symlinks to AGENTS.md and follow automatically.
|
Caution Review failedThe pull request is closed. ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (2)
📝 WalkthroughWalkthroughThis PR separates TypeScript CLI guidance from Rust pacquet guidance: AGENTS.md now explicitly scopes TypeScript-only sections and points to pacquet/AGENTS.md; pacquet/AGENTS.md is rewritten as a pacquet-scoped extension referencing the main doc and adding Rust-specific rules. ChangesAgent Guidance Documentation Restructuring
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Warning Review ran into problems🔥 ProblemsStopped waiting for pipeline failures after 30000ms. One of your pipelines takes longer than our 30000ms fetch window to run, so review may not consider pipeline-failure results for inline comments if any failures occurred after the fetch window. Increase the timeout if you want to wait longer or run a Comment |
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@pacquet/AGENTS.md`:
- Around line 1-6: Add a new explicit section titled "Agent capabilities / I/O /
integration" to pacquet/AGENTS.md that lists agent capabilities, expected inputs
and outputs, and integration touchpoints; include brief bullet-style entries
describing (1) agent capabilities (e.g., read/write repo files, run cargo/tests,
modify Cargo.toml), (2) input spec (PR metadata, file paths, test results,
environment variables), (3) output spec (patches, commit messages, test run
summaries, logs), and (4) integration points (CI hooks, signing conventions, PR
workflow, agent-authored file headers), so the pacquet agent contract is
unambiguous and follows the repo-wide conventions referenced in the intro.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: d09e1c9d-7d99-4336-863b-dc4955699325
📒 Files selected for processing (2)
AGENTS.mdpacquet/AGENTS.md
📜 Review details
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (8)
- GitHub Check: copilot-pull-request-reviewer
- GitHub Check: Doc
- GitHub Check: Lint and Test (macos-latest)
- GitHub Check: Lint and Test (windows-latest)
- GitHub Check: Lint and Test (ubuntu-latest)
- GitHub Check: Analyze (javascript)
- GitHub Check: Compile & Lint
- GitHub Check: Lint and Test (windows-latest)
🧰 Additional context used
📓 Path-based instructions (1)
pacquet/**/AGENTS.md
📄 CodeRabbit inference engine (pacquet/CLAUDE.md)
Document agent functionality and interactions in AGENTS.md
pacquet/**/AGENTS.md: Document agent responsibilities, capabilities, and interactions in AGENTS.md file
Maintain clear and up-to-date documentation of all agent definitions and their purposes
Include agent capabilities, input/output specifications, and integration guidelines in agent documentation
Files:
pacquet/AGENTS.md
🧠 Learnings (1)
📓 Common learnings
Learnt from: CR
Repo: pnpm/pnpm
Timestamp: 2026-05-14T16:32:25.956Z
Learning: Never ignore test failures - investigate and fix every failing test, even if it was already broken before your changes
Learnt from: CR
Repo: pnpm/pnpm
Timestamp: 2026-05-14T16:32:25.956Z
Learning: Before writing new code, search the codebase for similar functionality to avoid duplication, especially in packages/, fs/, crypto/, and text/ directories
Learnt from: CR
Repo: pnpm/pnpm
Timestamp: 2026-05-14T16:32:25.956Z
Learning: Prefer established open source packages over custom implementations for common tasks
Learnt from: CR
Repo: pnpm/pnpm
Timestamp: 2026-05-14T16:32:25.956Z
Learning: Add new dependencies to the most specific package that needs them, not to the root or shared packages unless multiple packages depend on it
Learnt from: CR
Repo: pnpm/pnpm
Timestamp: 2026-05-14T16:32:25.956Z
Learning: Follow the Conventional Commits specification for commit messages (feat, fix, docs, style, refactor, perf, test, chore)
Learnt from: CR
Repo: pnpm/pnpm
Timestamp: 2026-05-14T16:32:25.956Z
Learning: Create a changeset file in .changeset/ directory for any changes affecting published packages, explicitly including 'pnpm' with the appropriate version bump (patch, minor, or major)
Learnt from: CR
Repo: pnpm/pnpm
Timestamp: 2026-05-14T16:32:25.956Z
Learning: Rebuild the pnpm bundle with `pnpm --filter pnpm run compile` after changing any package before running e2e tests in pnpm/test/
Learnt from: CR
Repo: pnpm/pnpm
Timestamp: 2026-05-14T16:32:25.956Z
Learning: Run tests for specific projects or files instead of all tests in the repository to save time
Learnt from: CR
Repo: pnpm/pnpm
Timestamp: 2026-05-14T16:32:25.956Z
Learning: Keep GitHub PR titles and descriptions current when pushing new changes
Learnt from: CR
Repo: pnpm/pnpm
Timestamp: 2026-05-14T16:32:25.956Z
Learning: Reply to review comments with a description of the resolution including the commit hash, then mark the conversation as resolved
Learnt from: CR
Repo: pnpm/pnpm
Timestamp: 2026-05-14T16:32:25.956Z
Learning: Sign all agent-authored content with the agent name and model name (e.g., 'Written by an agent (Claude Code, claude-opus-4-7)') in GitHub comments, issues, and PRs
Learnt from: CR
Repo: pnpm/pnpm
Timestamp: 2026-05-14T16:32:25.956Z
Learning: Use shell/resolve-pr-conflicts.sh to resolve GitHub PR conflicts, which auto-resolves pnpm-lock.yaml via pnpm install
Learnt from: CR
Repo: pnpm/pnpm
Timestamp: 2026-05-14T16:32:51.682Z
Learning: Match how the same feature is implemented in pnpm/pnpm on the latest main branch - any change in this repo must reflect upstream behavior exactly
Learnt from: CR
Repo: pnpm/pnpm
Timestamp: 2026-05-14T16:32:51.682Z
Learning: When citing upstream pnpm code in comments, commit messages, PR descriptions, or documentation, link to a specific commit SHA (first 10 hex characters), never to branch names like main or master
Learnt from: CR
Repo: pnpm/pnpm
Timestamp: 2026-05-14T16:32:51.682Z
Learning: Follow the contributing guide in CONTRIBUTING.md covering commit message format, writing style, setup, and automated checks before committing
Learnt from: CR
Repo: pnpm/pnpm
Timestamp: 2026-05-14T16:32:51.682Z
Learning: Run just ready before declaring a task complete to run the same checks CI runs (typos, fmt, check, test, lint)
Learnt from: CR
Repo: pnpm/pnpm
Timestamp: 2026-05-14T16:32:51.682Z
Learning: Commit messages follow Conventional Commits format with scope naming the crate or area (e.g., fix(network):, feat(lockfile):); pacquet adds 'bench' type for benchmark-only changes
Learnt from: CR
Repo: pnpm/pnpm
Timestamp: 2026-05-14T16:32:51.682Z
Learning: Do not add features, flags, or behaviors that pnpm does not have
Learnt from: CR
Repo: pnpm/pnpm
Timestamp: 2026-05-14T16:32:51.682Z
Learning: Do not change lockfile format, store layout, .npmrc semantics, or CLI surface unless pnpm changed them first
Learnt from: CR
Repo: pnpm/pnpm
Timestamp: 2026-05-14T16:32:51.682Z
Learning: A dependency already declared in [workspace.dependencies] in root Cargo.toml may be added to any crate; do not add undeclared dependencies without explicit human request and approval
Learnt from: CR
Repo: pnpm/pnpm
Timestamp: 2026-05-14T16:32:51.682Z
Learning: Do not disable lints, tests, or CI checks to make a PR green
🪛 LanguageTool
AGENTS.md
[grammar] ~121-~121: Use a hyphen to join words.
Context: ...oth locations can use. - **Prefer open source packages over custom implementati...
(QB_NEW_EN_HYPHEN)
[grammar] ~121-~121: Use a hyphen to join words.
Context: ...eady available as a well-maintained open source package. Use established librarie...
(QB_NEW_EN_HYPHEN)
[uncategorized] ~122-~122: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ...on the right level.** When adding a new open source dependency, add it to the most specific...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
[grammar] ~130-~130: Use a hyphen to join words.
Context: ...ix: a bug fix - docs: documentation only changes - style`: formatting, mi...
(QB_NEW_EN_HYPHEN)
pacquet/AGENTS.md
[grammar] ~291-~291: Ensure spelling is correct
Context: ...-reuse-and-avoiding-duplication) apply. Pacquet-specific notes: - Shared helpers tend ...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🔇 Additional comments (1)
AGENTS.md (1)
5-11: LGTM!Also applies to: 50-55, 77-77, 103-103, 111-125, 137-137, 159-159, 179-179
Add a "Keep pnpm and pacquet in sync" section to root AGENTS.md spelling out the bidirectional obligation: any user-visible change (CLI surface, lockfile/manifest format, error codes, defaults, env-var handling, log emissions, store layout) must land in both stacks in the same PR, or the originating PR must spawn a tracking issue. Pure refactors / perf wins / TS-only test cleanups don't need mirroring. Cross-link from pacquet/AGENTS.md's "cardinal rule" so a pacquet-side reader knows the obligation goes both ways and where the pnpm-side version lives.
The root "Keep the dependency on the right level" bullet uses npm
vocabulary ("package," "shared package"). For a Rust reader that
required mentally translating "package" → "crate" and made the
workspace-vs-crate distinction less obvious. Restore the pacquet
phrasing alongside the existing pacquet-specific notes.
Drop the "open a tracking issue" fallback — it lets one side drift behind while the issue sits in the backlog. Instead, the PR author opens the PR with their side and flags in the description what still needs porting; someone else pushes the matching commits to the same PR before it lands. Both sides land together or not at all.
pacquet now lives in the same repo as pnpm, so the cardinal rule no
longer needs the "fetch pnpm/pnpm main, compare ls-remote SHAs, watch
your local clone for drift" mechanics. The reference TypeScript code
is just a few directories over (`pnpm/`, `pkg-manager/`, `resolving/`,
`lockfile/`, `store/`, etc.), and pnpm is the source of truth by
position in the repo, not by branch tracking.
Updates:
- Root `AGENTS.md`: rephrase the cross-link line to drop the "follow
pnpm's main" framing.
- `pacquet/AGENTS.md` cardinal rule: redirect "find the equivalent
code" from `https://github.com/pnpm/pnpm` to the in-repo
TypeScript workspaces, drop the "confirm you're on the freshest
main" paragraph, and reword the source-of-truth wording.
- Permalink citation rule: generalize from "upstream pnpm" to "any
GitHub repository, including this one" — citation SHAs now usually
point at this repo's history.
Without this caveat the parity rule reads as if every command needs porting today. pacquet only implements `install` right now; resolution and other commands (`update`, `add`, `remove`, `publish`, `exec`, `run`, `dlx`, `audit`, etc.) live only in TypeScript, so changes there don't need a pacquet-side port. The caveat also flags that the parity rule's scope will widen as pacquet ports more commands.
github-actions Bot
pushed a commit
to Eyalm321/pnpm
that referenced
this pull request
May 18, 2026
* docs: split AGENTS.md into shared + pacquet-specific
Before: root AGENTS.md and pacquet/AGENTS.md each maintained their own
copy of the GitHub PR workflow, agent-footer rule, "never ignore test
failures," Conventional Commits list, and code-reuse philosophy.
Drift waiting to happen.
After:
- Root AGENTS.md owns the shared conventions (PR workflow, agent
footer, conventional commits, code reuse, never-ignore-tests,
PR-conflict script) and marks TS-only sections explicitly
(setup/build, testing, linting, changesets, Standard Style, Jest
gotchas).
- pacquet/AGENTS.md opens with "Read ../AGENTS.md first" and keeps
only pacquet-specific rules (cardinal rule, branded types, just
recipes, insta snapshots, miette diagnostics, Rust style notes,
the `bench:` commit type, things-not-to-do that are Rust-flavored).
- Root adds a one-line entry for `pacquet/` in the repo structure
list so first-time readers find the cross-link.
CLAUDE.md and pacquet/{CLAUDE,GEMINI}.md are unchanged — they're
symlinks to AGENTS.md and follow automatically.
* docs(agents): require parity between pnpm and pacquet
Add a "Keep pnpm and pacquet in sync" section to root AGENTS.md spelling
out the bidirectional obligation: any user-visible change (CLI surface,
lockfile/manifest format, error codes, defaults, env-var handling, log
emissions, store layout) must land in both stacks in the same PR, or
the originating PR must spawn a tracking issue. Pure refactors / perf
wins / TS-only test cleanups don't need mirroring.
Cross-link from pacquet/AGENTS.md's "cardinal rule" so a pacquet-side
reader knows the obligation goes both ways and where the pnpm-side
version lives.
* docs(agents): restore Rust-specific dependency-level guidance
The root "Keep the dependency on the right level" bullet uses npm
vocabulary ("package," "shared package"). For a Rust reader that
required mentally translating "package" → "crate" and made the
workspace-vs-crate distinction less obvious. Restore the pacquet
phrasing alongside the existing pacquet-specific notes.
* docs(agents): hand off cross-stack porting via the same PR
Drop the "open a tracking issue" fallback — it lets one side drift
behind while the issue sits in the backlog. Instead, the PR author
opens the PR with their side and flags in the description what still
needs porting; someone else pushes the matching commits to the same
PR before it lands. Both sides land together or not at all.
* docs(agents): drop external-repo framing from the cardinal rule
pacquet now lives in the same repo as pnpm, so the cardinal rule no
longer needs the "fetch pnpm/pnpm main, compare ls-remote SHAs, watch
your local clone for drift" mechanics. The reference TypeScript code
is just a few directories over (`pnpm/`, `pkg-manager/`, `resolving/`,
`lockfile/`, `store/`, etc.), and pnpm is the source of truth by
position in the repo, not by branch tracking.
Updates:
- Root `AGENTS.md`: rephrase the cross-link line to drop the "follow
pnpm's main" framing.
- `pacquet/AGENTS.md` cardinal rule: redirect "find the equivalent
code" from `https://github.com/pnpm/pnpm` to the in-repo
TypeScript workspaces, drop the "confirm you're on the freshest
main" paragraph, and reword the source-of-truth wording.
- Permalink citation rule: generalize from "upstream pnpm" to "any
GitHub repository, including this one" — citation SHAs now usually
point at this repo's history.
* docs(agents): note pacquet's current scope is install-only
Without this caveat the parity rule reads as if every command needs
porting today. pacquet only implements `install` right now; resolution
and other commands (`update`, `add`, `remove`, `publish`, `exec`,
`run`, `dlx`, `audit`, etc.) live only in TypeScript, so changes there
don't need a pacquet-side port. The caveat also flags that the parity
rule's scope will widen as pacquet ports more commands.
1 task
This was referenced Jun 18, 2026
Merged
This was referenced Jun 25, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Splits the duplicated content between root
AGENTS.mdandpacquet/AGENTS.mdinto a single source of truth for each rule, and adds a bidirectional parity rule between the two stacks.Before: both files maintained their own copies of the GitHub PR workflow, the agent-footer rule, "never ignore test failures," the Conventional Commits type list, and the code-reuse philosophy. The two had already started to drift in phrasing — a few months of independent edits and they would have drifted in substance too. Neither file said anything about keeping pnpm and pacquet in sync; pacquet's "cardinal rule" only worked in one direction (pacquet must match pnpm), with nothing on the pnpm side saying TS changes also need a pacquet port.
After:
AGENTS.mdowns the shared conventions and marks TS-only sections explicitly (Setup & Build,Testing,Linting,Changesets,Code Style(Standard Style),Error Type Checking in Jest).AGENTS.mdhas a new "Keep pnpm and pacquet in sync" section spelling out that user-visible changes (CLI flags, lockfile/manifest format, error codes, log emissions, defaults, env-var handling, store layout, hook semantics) must land in both stacks in the same PR or spawn a tracking issue. Refactors/perf/TS-only test cleanups don't need mirroring.pacquet/AGENTS.mdopens with "Read../AGENTS.mdfirst" and keeps only pacquet-specific rules: the cardinal "match pnpm" rule, branded-string porting,justrecipes,instasnapshots,miettediagnostics, thebench:commit type, the method-chain preservation rule, and the things-not-to-do that are Rust-flavored.pacquet/in the repo-structure list so first-time readers find the cross-link.What moved to root (shared)
shell/resolve-pr-conflicts.sh)What is new
What stayed (or specialized) in
pacquet/AGENTS.mdpacquet/(+ a note that the Cargo workspace lives at the repo root)justrecipes)crates/fs,crates/testing-utils,crates/diagnostics)just ready, pre-push hook) + thebench:commit typeNote on symlinks
CLAUDE.md,pacquet/CLAUDE.md, andpacquet/GEMINI.mdare symlinks to their respectiveAGENTS.mdfiles. They follow automatically — no source changes needed.Verification
Written by an agent (Claude Code, claude-opus-4-7).
Summary by CodeRabbit
benchcommit type, avoid ignoring test failures, prefer native-error checks)