Further agents improvements - feedback from glean

Author: rozza

.gitignore

@@ -55,6 +55,9 @@ local.properties
 # security-sensitive files
 *.gpg
 
+# per-developer agent overrides
+.AGENTS.md
+
 # bin build directories
 **/bin
 

AGENTS.md

@@ -1,9 +1,14 @@
 # AGENTS.md - MongoDB Java Driver
 
 Official MongoDB JVM driver monorepo (Java, Kotlin, Scala).
-Implements the
-[MongoDB Driver Specifications](https://github.com/mongodb/specifications).
-Each module has its own `AGENTS.md` with module-specific guidance.
+All changes require human review.
+Breaking changes to public API require a major version bump — always warn if binary
+compatibility is affected.
+Also consult `.AGENTS.md` / `~/.AGENTS.md` if present for local agent settings.
+
+See [`.agents/skills/project-guide`](.agents/skills/project-guide/SKILL.md) for module
+structure and dependency graph.
+Each module has its own `AGENTS.md`.
 
 ## Core Rules
 
@@ -15,25 +20,24 @@ Each module has its own `AGENTS.md` with module-specific guidance.
   Only remove if provably incorrect.
 - No rewrites without explicit permission.
 - When stuck or uncertain: stop, explain, propose alternatives, ask.
-- All `com.mongodb.internal.*` / `org.bson.internal.*` is private API — never expose in
-  public APIs.
 
 ## Build
 
-- Gradle with Kotlin DSL. Build JDK: 17+. Source baseline: Java 8.
-- Versions: `gradle/libs.versions.toml`. Plugins:
-  `buildSrc/src/main/kotlin/conventions/`.
+Gradle with Kotlin DSL. Build JDK: 17+. Source baseline: Java 8. Versions in
+`gradle/libs.versions.toml`.
 
 ```bash
 ./gradlew check                        # Full validation (format + static checks + tests)
 ./gradlew :driver-core:test            # Single module tests
 ./gradlew integrationTest -Dorg.mongodb.test.uri="mongodb://localhost:27017"
 ```
 
-## Formatting
+## Style
 
-`check` runs `spotlessApply` automatically.
+`check` runs `spotlessApply` automatically — formatting is enforced.
 Do not reformat outside your changes.
+See [`.agents/skills/style-reference`](.agents/skills/style-reference/SKILL.md) for full
+rules.
 
 - No `System.out.println` / `System.err.println` — use SLF4J
 - No `e.printStackTrace()` — use proper error handling
@@ -48,16 +52,30 @@ Do not reformat outside your changes.
 - Unit tests must not require a running MongoDB instance.
 - Descriptive method names or `@DisplayName`. Clean up in `@AfterEach`.
 
-## Safety — Do Not Modify Without Review
+## API
+
+All `com.mongodb.internal.*` / `org.bson.internal.*` is private API — never expose in
+public APIs. See [`.agents/skills/api-design`](.agents/skills/api-design/SKILL.md) for
+stability annotations and design principles.
+
+## Do Not Modify Without Human Approval
 
-- Wire protocol / authentication handshakes
-- Security-critical encryption code
+- Wire protocol / authentication handshakes (`com.mongodb.internal.connection`)
+- Connection pool core code (`com.mongodb.internal.connection.pool`)
+- Security-critical encryption code / JNA bindings (`mongodb-crypt`)
 - Public API contracts (breaking changes need major version bump)
 - BSON specification compliance
-- Credentials, secrets, `.evergreen/` config, release scripts
+- Spec test data submodule (`testing/resources/specifications/`)
+- Release/versioning scripts, `.evergreen/` config, credentials/secrets
+
+See [`.agents/skills/evergreen`](.agents/skills/evergreen/SKILL.md) for CI validation
+and patch builds.
 
 ## Before Submitting
 
 ```bash
-./gradlew doc check scalaCheck
+./gradlew doc check scalaCheck   # Docs + formatting (spotlessApply) + static checks + all tests
 ```
+
+Note: `check` includes `spotlessApply` for all modules.
+`buildSrc` uses `spotlessCheck` instead (no auto-fix).

README.md

@@ -125,6 +125,18 @@ $ mongod --dbpath ./data/db --logpath ./data/mongod.log --port 27017 --logappend
 If you encounter `"Too many open files"` errors when running the tests then you will need to increase 
 the number of available file descriptors prior to starting mongod as described in [https://www.mongodb.com/docs/manual/reference/ulimit/](https://www.mongodb.com/docs/manual/reference/ulimit/)
 
+## AI Agent Configuration
+
+This repository uses [agentskills.io](https://agentskills.io) conventions for AI coding agent
+instructions. `AGENTS.md` is the canonical source of truth — tool-specific files like `CLAUDE.md`
+are generated references.
+
+### Adding a nested AGENTS.md
+
+1. Create an `AGENTS.md` in the target directory.
+2. Run `scripts/symlink-claude-md.sh` to generate the companion `CLAUDE.md`.
+3. Stage and commit both files.
+
 ## IntelliJ IDEA
 
 A couple of manual configuration steps are required to run the code in IntelliJ:

bson-kotlin/AGENTS.md

@@ -4,6 +4,17 @@ Kotlin extensions for the BSON library, providing idiomatic Kotlin codec support
 
 **Depends on:** `bson`
 
+- Work here if: modifying Kotlin-specific BSON codecs or inline reified functions
+
 ## Key Packages
 
 - `org.bson.codecs.kotlin` — Kotlin-specific codecs with inline reified functions
+
+## Build & Test
+
+```bash
+./gradlew :bson-kotlin:test
+./gradlew :bson-kotlin:check
+```
+
+For global rules see [root AGENTS.md](../AGENTS.md).

bson-kotlinx/AGENTS.md

@@ -4,7 +4,18 @@ Kotlinx serialization integration for BSON, providing a pluggable serialization
 
 **Depends on:** `bson`
 
+- Work here if: modifying the kotlinx-serialization BSON codec integration
+
 ## Key Packages
 
 - `org.bson.codecs.kotlinx` — Kotlinx serialization BSON format support
 - `org.bson.codecs.kotlinx.utils` — Helper utilities
+
+## Build & Test
+
+```bash
+./gradlew :bson-kotlinx:test
+./gradlew :bson-kotlinx:check
+```
+
+For global rules see [root AGENTS.md](../AGENTS.md).

bson-record-codec/AGENTS.md

@@ -5,6 +5,17 @@ Java record codec support for BSON serialization.
 
 **Depends on:** `bson`
 
+- Work here if: modifying Java record serialization support
+
 ## Key Packages
 
 - `org.bson.codecs.record` — `RecordCodecProvider` and record field accessors
+
+## Build & Test
+
+```bash
+./gradlew :bson-record-codec:test
+./gradlew :bson-record-codec:check
+```
+
+For global rules see [root AGENTS.md](../AGENTS.md).

bson-scala/AGENTS.md

@@ -5,23 +5,23 @@ macro-based codecs.
 
 **Depends on:** `bson`
 
-**Supported Scala versions:** 2.11, 2.12, 2.13, 3 (configured in root
-`gradle.properties`). Default: 2.13.
+**Supported Scala versions:** 2.11, 2.12, 2.13, 3 (default: 2.13, configured in root
+`gradle.properties`).
 
-See [README.md](./README.md) for full details on directory layout, formatting, and
-testing commands.
+- Work here if: modifying Scala BSON wrappers, macro codecs, or Scala collection support
 
 ## Key Packages
 
 - `org.mongodb.scala.bson` — Core Scala BSON wrappers
 - `org.mongodb.scala.bson.codecs` — Macro-based codecs (Scala 2/3)
-- `org.mongodb.scala.bson.collection` — Immutable/mutable collection support
-- `org.mongodb.scala.bson.annotations` — Field annotations
 
-## Before Submitting
+## Build & Test
 
 ```bash
-./gradlew spotlessApply                                           # Fix formatting
-./gradlew :bson-scala:scalaCheck                                  # Static checks + tests (default Scala version)
-./gradlew :bson-scala:scalaCheck -PscalaVersion=<version>         # Test specific Scala version
+./gradlew :bson-scala:test
+./gradlew :bson-scala:scalaCheck                          # Static checks + tests (default Scala version)
+./gradlew :bson-scala:scalaCheck -PscalaVersion=<version> # Test specific Scala version
 ```
+
+For global rules see [root AGENTS.md](../AGENTS.md).
+See [README.md](./README.md) for directory layout details.

bson/AGENTS.md

@@ -1,30 +1,27 @@
 # AGENTS.md - bson
 
-Core BSON (Binary JSON) library.
-This is the foundation module — all other modules depend on it.
+Core BSON (Binary JSON) library — the foundation module.
+All other modules depend on it.
 
 **Depends on:** None (foundation module)
 
-## Key Packages
+- Work here if: adding/modifying BSON types, codecs, JSON conversion, or binary I/O
+- Do not: expose `org.bson.internal` types in public API
 
-- `org.bson` — Core BSON value types (`BsonDocument`, `BsonValue`, `BsonReader`,
-  `BsonWriter`)
-- `org.bson.codecs` — Codec framework (`Encoder`, `Decoder`, `Codec`)
-- `org.bson.codecs.configuration` — Codec registry and provider infrastructure
-  (`CodecRegistry`, `CodecProvider`)
-- `org.bson.codecs.pojo` — POJO codec support with conventions and property modeling
-- `org.bson.codecs.jsr310` — Java 8+ date/time codec support
-- `org.bson.json` — JSON conversion (`JsonReader`, `JsonWriter`, `JsonMode`)
-- `org.bson.io` — Binary I/O (`ByteBuffer`, `OutputBuffer`)
-- `org.bson.types` — Legacy types (`ObjectId`, `Decimal128`, etc.)
-- `org.bson.internal` — Private API (vector support, encoding utilities)
+## Key Packages
 
-## Notes
+- `org.bson` — Core types (`BsonDocument`, `BsonValue`, `BsonReader`, `BsonWriter`)
+- `org.bson.codecs` — Codec framework (`Encoder`, `Decoder`, `Codec`, `CodecRegistry`)
+- `org.bson.codecs.pojo` — POJO codec support
+- `org.bson.json` — JSON conversion (`JsonReader`, `JsonWriter`)
+- `org.bson.internal` — Private API — do not expose
 
-- JUnit 5 + Spock (Groovy) tests in both unit and functional dirs
+## Build & Test
 
-## Key Patterns
+```bash
+./gradlew :bson:test
+./gradlew :bson:check
+```
 
-- Codec-based serialization with type-safe `BsonValue` hierarchy
-- `BsonDocument` implements `Map<String, BsonValue>`
-- All public types in `org.bson` — internal types in `org.bson.internal`
+For global rules see [root AGENTS.md](../AGENTS.md).
+For API design see [api-design skill](../.agents/skills/api-design/SKILL.md).

driver-core/AGENTS.md

@@ -6,40 +6,31 @@ Largest and most complex module.
 **Depends on:** `bson`, `bson-record-codec`, optionally `bson-kotlin`, `bson-kotlinx`,
 `mongodb-crypt`
 
-## Key Packages (Public API)
-
-- `com.mongodb.client.model` — Operation models: `Filters`, `Updates`, `Projections`,
-  `Aggregates`, `Sorts`, `Indexes`
-- `com.mongodb.client.model.search` — Atlas Search configuration
-- `com.mongodb.client.result` — Operation result types (`InsertOneResult`,
-  `DeleteResult`, etc.)
-- `com.mongodb.connection` — `ClusterSettings`, `ClusterDescription`
-- `com.mongodb.event` — Listeners for commands, connections, servers, cluster events
-- `com.mongodb.session` — `ClientSession` interface
-- `com.mongodb.bulk` — `WriteModel` hierarchy
-
-## Key Packages (Internal — Private API)
-
-- `com.mongodb.internal.connection` — Socket, wire protocol, command execution
-- `com.mongodb.internal.operation` — Concrete operations (find, insert, aggregate, etc.)
-- `com.mongodb.internal.authentication` — SASL, SCRAM, X.509, OIDC
-- `com.mongodb.internal.async` — Async operation framework
-- `com.mongodb.internal.binding` — Server binding strategies
-- `com.mongodb.internal.client` — MongoClient/MongoDatabase/MongoCollection
-  implementations
+- Work here if: modifying query builders (`Filters`, `Updates`, `Aggregates`),
+  connection handling, wire protocol, server selection, or operation execution
+- Do not: block in async code paths, modify wire protocol or auth without human approval
+
+## Key Packages
+
+- `com.mongodb.client.model` — `Filters`, `Updates`, `Projections`, `Aggregates`,
+  `Sorts`, `Indexes`
+- `com.mongodb.internal.connection` — Wire protocol, command execution (safety-critical)
+- `com.mongodb.internal.operation` — Concrete operations (find, insert, aggregate)
+- `com.mongodb.internal.authentication` — SASL, SCRAM, X.509, OIDC (safety-critical)
+
+## Build & Test
+
+```bash
+./gradlew :driver-core:test
+./gradlew :driver-core:check
+./gradlew :driver-core:generateMongoDriverVersion   # If MongoDriverVersion is missing
+```
 
 ## Notes
 
-- Most extensive test suite — JUnit 5 + Spock (Groovy) + Mockito.
+- Most extensive test suite — JUnit 5 + Spock + Mockito.
   Match surrounding patterns carefully.
-- `com.mongodb.internal.build.MongoDriverVersion` is auto-generated by the
-  `com.github.gmazzo.buildconfig` Gradle plugin — run
-  `./gradlew :driver-core:generateMongoDriverVersion` if missing
-- Never block in async code paths
-
-## Key Patterns
+- `MongoDriverVersion` is auto-generated by the `com.github.gmazzo.buildconfig` plugin
 
-- Static factory methods: `Filters.eq()`, `Updates.set()`, `Aggregates.match()`
-- Fluent builders: `MongoClientSettings.builder()` is the primary entry point for
-  configuring clients
-- Abstract core with pluggable transports
+For global rules see [root AGENTS.md](../AGENTS.md).
+For API design see [api-design skill](../.agents/skills/api-design/SKILL.md).

driver-kotlin-coroutine/AGENTS.md

@@ -4,12 +4,19 @@ Kotlin Coroutines driver providing `suspend` function-based async API.
 
 **Depends on:** `bson`, `driver-reactive-streams`, `bson-kotlin`
 
+- Work here if: modifying the Kotlin coroutine-based driver API
+- Do not: block in any code path — all suspend functions wrap `driver-reactive-streams`
+
 ## Key Packages
 
 - `com.mongodb.kotlin.client.coroutine` — Coroutine-based driver API (`MongoClient`,
   `MongoDatabase`, `MongoCollection`)
 
-## Notes
+## Build & Test
+
+```bash
+./gradlew :driver-kotlin-coroutine:test
+./gradlew :driver-kotlin-coroutine:check
+```
 
-- Suspend functions wrapping `driver-reactive-streams` — never block
-- Built on `kotlinx-coroutines`
+For global rules see [root AGENTS.md](../AGENTS.md).