Dependency notes — rules for AI agents

Pacmon keeps a note for each direct dependency in .pacmon/, beside its manifest. People write under the dependency's heading; AI coding agents write under ### Agent notes.

Pacmon: Set Up AI Instructions copies the rules below into the repository as .pacmon/AGENT-RULES.md, and adds a three-line pointer to the instruction files you pick: AGENTS.md, CLAUDE.md, .cursor/rules/dependency-notes.md, .github/copilot-instructions.md. An agent that reads those files finds the rules there. Pacmon does not call any AI service: agents use their own tools, and Pacmon gives them the files and the rules.

The copy in a repository is the one its agents follow. This page shows the rules of the current release, as Pacmon writes them.

Before you touch a dependency

Its notes are beside the manifest you are changing: npm uses .pacmon/DEPENDENCY-NOTES.md, Rust uses .pacmon/cargo/DEPENDENCY-NOTES.md, Maven uses .pacmon/maven/DEPENDENCY-NOTES.md, Gradle uses .pacmon/gradle/DEPENDENCY-NOTES.md, Mix uses .pacmon/mix/DEPENDENCY-NOTES.md, Gleam uses .pacmon/gleam/DEPENDENCY-NOTES.md, Zig uses .pacmon/zig/DEPENDENCY-NOTES.md, Python uses .pacmon/python/DEPENDENCY-NOTES.md, Go uses .pacmon/go/DEPENDENCY-NOTES.md, and .NET/NuGet uses .pacmon/nuget/DEPENDENCY-NOTES.md. In a monorepo, use the nearest file for the same ecosystem, walking up. Read two things first: the free text between # Dependency Notes and the first section (this repository's own rules), then the dependency's ## <name> section.

• Adding a package: open its section in the same commit, with at least purpose:. Say what you considered and why this one, in alternatives: or log:.
• Upgrading: read its constraint: and verify: lines, then run what verify: says. Log the attempt with its outcome even if you reverted it — the next agent must not repeat it.
• Removing: keep the section and add - status: removed <YYYY-MM> — <reason>. Do not delete it.
• Trivial packages (@types/*, tiny helpers): purpose: and, if it applies, bump-with: are enough.

Where you write

## <the dependency's note key>

Text written by people. Do not touch it.

### Agent notes

- key: value
- key: value

• The heading is the dependency's note key, spelled as its manifest spells it:
  • package.json: the package name with its @scope/ — ## @types/node
  • .NET project files and Directory.Packages.props: the case-insensitive NuGet package ID as written — ## Newtonsoft.Json
  • Cargo.toml: the key in the dependency table; for a renamed dependency, the key, not its package — ## serde
  • pom.xml: groupId:artifactId — ## org.slf4j:slf4j-api
  • build.gradle(.kts): group:name without the version, or the catalog alias as written — ## org.slf4j:slf4j-api, ## libs.junit.jupiter
  • mix.exs: the dependency tuple's first application atom — ## phoenix, ## ecto_sql
  • gleam.toml: the key in [dependencies] or [dev_dependencies] — ## gleam_stdlib, ## gleeunit
  • build.zig.zon: the direct field name in the top-level .dependencies struct — ## known_folders
  • pyproject.toml or a requirements file: the normalized distribution name, lower-case with ., _, and - treated alike — ## requests, ## importlib-metadata
  • go.mod: the module path in require, including any major-version suffix; a tool belongs to the module that contains it — ## github.com/spf13/cobra, ## github.com/jackc/pgx/v5
• The text right under the heading is written by people. Never edit or delete it. Treat it as one of your sources — alongside the code, the git history, the registry and your own reasoning. If your block disagrees with it, the human text wins: fix your block and add a log: line saying so.
• ### Agent notes is yours. Lower-case keys, one fact per line, keys may repeat (several constraint: or log: lines are normal). Keys outside the vocabulary below are flagged by Pacmon; if something fits none of them, write it as note: — never invent a key.
• One ## name section per direct dependency, in alphabetical order. ## is reserved for dependencies; inside a section the only heading is ### Agent notes.
• Never write an empty field or a dash placeholder. If you have nothing true to say, leave the field out.
• Write judgments, not measurements.
• Revise, do not accumulate: correct a line instead of adding a contradicting one. log: is the exception — it is the history.
• Field keys are English. Write the values in the language given by lang: in the file's frontmatter.
• Never remove the frontmatter or the header comment at the top of the file. If you are asked to draft the first human line, keep it short: it shows next to the dependency in its manifest.

Fields

Fill these whenever you can:

Add these only when they are true and non-obvious:

A section whose status: starts with removed is kept on purpose for a package that left its manifest; Pacmon does not flag it as an orphan.

Example

## express

Do not upgrade to v5 — the auth middleware is incompatible (SEC-1301).
Rate-limit settings live in `src/middleware/limits.ts`.

### Agent notes

- purpose: HTTP framework; serves the public REST API and the webhook receiver
- constraint: stay on ^4 — v5 changes router path matching (path-to-regexp v8) and the session API
- verify: `vitest src/api` and the login e2e (`pnpm e2e:auth`)
- log: 2026-03 agent tried 5.0.1, 14 auth tests failed, reverted (PR #402)
- verified: 4.18.2