Dependency notes — rules for AI agents

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

Depos: Set Up AI Instructions copies the rules below into the repository as .depos/AGENT-RULES.md and, in VS Code and JetBrains IDEs, 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. Depos does not call any AI service: agents use their own tools, and Depos gives them the files and the rules.

The pointer in AGENTS.md and CLAUDE.md

The pointer sits between two markers, so the command finds and replaces it the next time it runs, and leaves the rest of the file alone. Visual Studio writes only .depos/AGENT-RULES.md; there, or in an instruction file the command does not offer, paste the pointer yourself. This is the block as VS Code and JetBrains IDEs write it:

<!-- depos:start -->
Dependency notes live in `.depos/DEPENDENCY-NOTES.md` for npm, `.depos/cargo/DEPENDENCY-NOTES.md` for Rust, `.depos/maven/DEPENDENCY-NOTES.md` for Maven, `.depos/gradle/DEPENDENCY-NOTES.md` for Gradle, `.depos/mix/DEPENDENCY-NOTES.md` for Mix, `.depos/gleam/DEPENDENCY-NOTES.md` for Gleam, `.depos/zig/DEPENDENCY-NOTES.md` for Zig, `.depos/python/DEPENDENCY-NOTES.md` for Python, `.depos/ruby/DEPENDENCY-NOTES.md` for Ruby, `.depos/go/DEPENDENCY-NOTES.md` for Go, `.depos/nuget/DEPENDENCY-NOTES.md` for .NET/NuGet, `.depos/vcpkg/DEPENDENCY-NOTES.md` for vcpkg, `.depos/conan/DEPENDENCY-NOTES.md` for Conan, and `.depos/composer/DEPENDENCY-NOTES.md` for PHP/Composer; people write below `## <package>`, agents under `### Agent notes`.
Rules and the field list are in `.depos/AGENT-RULES.md`; read a package's section before adding, bumping or removing it.
Update the notes in the same commit as the dependency manifest; a removed package keeps its section with `- status: removed …`.
<!-- depos:end -->

It sends the agent on to .depos/AGENT-RULES.md: the rules below. The copy in a repository is the one its agents follow. This page shows the rules of the current release, as Depos writes them.

Org mode

If your tools include get_dependency_note from the Depos notes MCP server, this repository's notes live in the organization's Depos. Then:

• Read notes with get_dependency_note and list_dependency_notes, not from the notes files. The files can be out of date.
• Before you add a package, call check_package. Do not add a package that is Denied. Tell the user about a package that is Not listed.
• Write with set_agent_fields only: the same keys and rules as ### Agent notes below. It replaces all fields, so send the full list. Never edit the notes files.
• If set_agent_fields is not offered, you can only read. Tell the user what you would change.

Without these tools, follow the rest of this file.

Before you touch a dependency

Its notes are beside the manifest you are changing: npm uses .depos/DEPENDENCY-NOTES.md, Rust uses .depos/cargo/DEPENDENCY-NOTES.md, Maven uses .depos/maven/DEPENDENCY-NOTES.md, Gradle uses .depos/gradle/DEPENDENCY-NOTES.md, Mix uses .depos/mix/DEPENDENCY-NOTES.md, Gleam uses .depos/gleam/DEPENDENCY-NOTES.md, Zig uses .depos/zig/DEPENDENCY-NOTES.md, Python uses .depos/python/DEPENDENCY-NOTES.md, Ruby uses .depos/ruby/DEPENDENCY-NOTES.md, PHP/Composer uses .depos/composer/DEPENDENCY-NOTES.md, Go uses .depos/go/DEPENDENCY-NOTES.md, .NET/NuGet uses .depos/nuget/DEPENDENCY-NOTES.md, vcpkg uses .depos/vcpkg/DEPENDENCY-NOTES.md, and Conan uses .depos/conan/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
  • Gemfile, gems.rb, or a gemspec: the literal, case-sensitive gem name — ## rails, ## rspec
  • 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
  • composer.json: the lower-cased package or platform key in require or require-dev — ## monolog/monolog, ## php, ## ext-mbstring
  • vcpkg.json: the lower-cased port name in dependencies or a feature's dependencies — ## fmt, ## openssl
  • conanfile.py or conanfile.txt: the lower-cased package name before the first / of the reference — ## zlib, ## openssl
• 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 Depos; 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; Depos 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