Added AGENTS.md

Add AI agent instructions using the AGENTS.md open standard
Adds structured AI agent documentation across the MongoDB Java Driver
using the AGENTS.md convention — an open standard for providing
codebase context to AI coding agents.

- Root AGENTS.md with build commands, style rules, testing policy, API
  design guidelines, safety-critical code boundaries, and dependency rules
- Per-module AGENTS.md files (bson, driver-core, driver-sync, etc.) with
  module-specific packages, dependencies, and patterns
- CLAUDE.md files that reference AGENTS.md (for Claude Code compatibility)
- `.agents/references/` for passive knowledge (contextually loaded):
  project-guide, style-reference, api-design, testing-guide, spec-tests
- `.agents/skills/` for procedural workflows:
  evergreen (CI validation), sync-agents-docs (documentation sync checklist)
- `scripts/symlink-claude-md.sh` for maintaining CLAUDE.md symlinks

- References over skills for static knowledge: references are loaded
  contextually based on description relevance rather than requiring
  explicit invocation. This avoids bloating every conversation with all
  documentation while still surfacing it when needed.
- Flat file layout for references (.agents/references/api-design.md)
  rather than directory-per-reference (.agents/references/api-design/REFERENCE.md):
  simpler structure; supplementary files use name-prefixing
  (e.g. testing-guide-examples.md) instead of subdirectories.
- Markdown links (See [name](path)) rather than @ syntax for referencing
  from AGENTS.md: @ auto-includes file contents on every load, which
  defeats contextual loading. Links let agents follow them on demand.
- Skills retained only for procedural workflows that have tool constraints
  (allowed-tools) or explicit trigger conditions (disable-model-invocation),
  not for passive knowledge lookup.

JAVA-6143

Author: rozza

.agents/references/api-design.md

@@ -0,0 +1,47 @@
+---
+name: api-design
+description: API stability annotations, design principles, and patterns for the MongoDB Java Driver. Use when adding or modifying public API surface — new classes, methods, interfaces, or changing method signatures.
+---
+# API Design
+
+## API Stability Annotations
+
+- `@Alpha` — Early development, may be removed.
+  Not recommended for production use.
+- `@Beta` — Subject to change or removal.
+  It's not recommended for Libraries to depend on these APIs.
+- `@Evolving` — May add abstract methods in future releases.
+  Safe to use, but implementing/extending bears upgrade risk.
+- `@Sealed` — Must not be extended or implemented by consumers.
+  Safe to use, but not to subclass.
+- `@Deprecated` — Supported until next major release but should be migrated away from.
+
+## API Lifecycle
+
+- **@Deprecated:** Deprecate in minor release, remove in next major. Always include `@deprecated Use {@link Replacement}` with a migration path.
+- **@Alpha:** Early development, subject to incompatible changes or removal. Exempt from compatibility guarantees. Not for production use by applications; libraries must not depend on Alpha APIs.
+- **@Beta:** Subject to incompatible changes or removal. Exempt from compatibility guarantees. Safe for applications (at the cost of extra upgrade work), but libraries should not depend on Beta APIs.
+- **@Sealed:** Use when the driver provides internal implementations but consumers must not subclass (e.g., `ReadPreference`, `WriteConcern`).
+
+## Module Ownership
+
+- Public API lives in `driver-sync`, `driver-reactive-streams`, and language wrappers (`driver-kotlin-sync`, `driver-kotlin-coroutine`, `driver-scala`)
+- `driver-core` owns shared internals, query builders (`Filters`, `Updates`, `Aggregates`), and the async execution layer
+- Sync wrappers delegate to async core — never add sync-only logic that diverges from the async path
+
+## Design Principles
+
+These guide the driver's API surface:
+
+- **Deep modules:** Prefer simple interfaces with powerful implementations over shallow wrappers.
+- **Information hiding:** Bury complexity behind simple interfaces.
+- **Pull complexity downward:** Make the implementer work harder so callers work less.
+- **General-purpose over special-case:** Fewer flexible methods over many specialized ones.
+- **Define errors out of existence:** Design APIs so errors cannot happen rather than detecting and handling them.
+
+## Key Patterns
+
+- **Static factory methods:** `Filters.eq()`, `Updates.set()`, `Aggregates.match()` — prefer these over constructors for public API
+- **Fluent builders:** `MongoClientSettings.builder()` is the primary entry point — use for any class with more than 2–3 configuration options
+- **Abstract core with pluggable transports:** `driver-core` defines operations; transport modules (`driver-sync`, `driver-reactive-streams`) execute them
+- **Immutable value objects:** `MongoNamespace`, `WriteConcern`, `ReadPreference` are immutable — modifications return new instances

.agents/references/project-guide.md

@@ -0,0 +1,65 @@
+---
+name: project-guide
+description: Project structure, dependency graph, and guide for finding the right project to work in. Use when starting a task and unsure which project owns the relevant code, or when you need to understand cross-project dependencies.
+---
+# Project Guide
+
+## Project Structure
+
+| Project | Purpose |
+| --- | --- |
+| `bson` | BSON library (core serialization) |
+| `bson-kotlin` | Kotlin BSON extensions |
+| `bson-kotlinx` | Kotlin serialization BSON codec |
+| `bson-record-codec` | Java record codec support |
+| `bson-scala` | Scala BSON extensions |
+| `driver-core` | Core driver internals (connections, protocol, operations) |
+| `driver-sync` | Synchronous Java driver |
+| `driver-legacy` | Legacy MongoDB Java driver API |
+| `driver-reactive-streams` | Reactive Streams driver |
+| `driver-kotlin-coroutine` | Kotlin Coroutines driver |
+| `driver-kotlin-extensions` | Kotlin driver extensions |
+| `driver-kotlin-sync` | Kotlin synchronous driver |
+| `driver-scala` | Scala driver |
+| `mongodb-crypt` | Client-side field-level encryption |
+| `bom` | Bill of Materials for dependency management |
+| `testing` | Shared test resources and MongoDB specifications |
+| `buildSrc` | Gradle convention plugins and build infrastructure |
+| `driver-benchmarks` | JMH and custom performance benchmarks (not published) |
+| `driver-lambda` | AWS Lambda test application (not published) |
+| `graalvm-native-image-app` | GraalVM Native Image compatibility testing (not published) |
+
+## Dependency Graph (simplified)
+
+```
+bson
+ ├── bson-kotlin
+ ├── bson-kotlinx
+ ├── bson-record-codec
+ ├── bson-scala
+ └── driver-core
+      ├── driver-sync
+      │    ├── driver-legacy
+      │    ├── driver-kotlin-sync
+      │    └── driver-lambda
+      ├── driver-reactive-streams
+      │    ├── driver-kotlin-coroutine
+      │    └── driver-scala
+      └── driver-kotlin-extensions
+```
+
+## Finding the Right Module
+
+- **BSON serialization/codecs:** `bson` (or `bson-kotlin`/`bson-kotlinx`/`bson-scala` for language-specific)
+- **Query builders, filters, aggregates:** `driver-core` (`com.mongodb.client.model`)
+- **Sync Java API:** `driver-sync`
+- **Reactive API:** `driver-reactive-streams`
+- **Kotlin coroutines:** `driver-kotlin-coroutine`
+- **Kotlin DSL builders:** `driver-kotlin-extensions`
+- **Scala driver:** `driver-scala`
+- **Connection, protocol, auth internals:** `driver-core` (`com.mongodb.internal.*`)
+- **Build plugins, formatting, test infra:** `buildSrc`
+
+Each module has its own `AGENTS.md` with module-specific packages, patterns, and notes.
+Modules marked "(not published)" (`driver-lambda`, `graalvm-native-image-app`, `driver-benchmarks`) are
+test/example apps — not normal development targets and intentionally have no `AGENTS.md`.

.agents/references/spec-tests.md

@@ -0,0 +1,40 @@
+---
+name: spec-tests
+description: How to work with MongoDB specification tests — structure, rules, and adding new spec test support. Use when implementing or modifying behavior defined by the MongoDB Driver Specifications.
+---
+# MongoDB Specification Tests
+
+## Overview
+
+The driver implements the [MongoDB Driver Specifications](https://github.com/mongodb/specifications).
+Specification test data files live in `testing/resources/specifications/` — a git submodule.
+
+## Rules
+
+- **Do not modify spec test data files** (JSON/YAML in `testing/resources/specifications/`) — managed upstream
+- Test runners (Java code) may be modified to fix bugs or add support for new spec tests
+- Update the submodule via `git submodule update`
+
+## Structure
+
+Spec test data is organized by specification area:
+
+- CRUD, SDAM, auth, CSFLE, retryable operations, and more
+- Each spec area has JSON/YAML test data files defining inputs and expected outputs
+- Driver test runners parse these files and execute against the driver
+
+## Test Data Location
+
+```
+testing/
+  resources/
+    specifications/    # Git submodule — do not edit directly
+    logback-test.xml   # Shared logback configuration for tests
+```
+
+## Adding Spec Test Support
+
+1. Check `testing/resources/specifications/` for the relevant spec test data
+2. Find existing test runners in the module (look for `*SpecificationTest*` or similar)
+3. Extend existing patterns — each module handles spec tests slightly differently
+4. Ensure tests run with `./gradlew check` or the module’s test task

.agents/references/style-reference.md

@@ -0,0 +1,55 @@
+---
+name: style-reference
+description: Detailed code style rules for Java, Kotlin, Scala, and Groovy in the MongoDB Java Driver. Use when you need specific formatting rules beyond the basics in root AGENTS.md — e.g., line length, import ordering, brace style.
+---
+# Style Reference
+
+## Java Style Rules
+
+- **Max line length:** 140 characters
+- **Indentation:** 4 spaces (no tabs)
+- **Line endings:** LF (Unix)
+- **Charset:** UTF-8
+- **Star imports:** Prohibited (AvoidStarImport)
+- **Final parameters:** Required (FinalParameters checkstyle rule)
+- **Braces:** Required for all control structures (NeedBraces)
+- **Else placement:** `} else {` on the same line (Palantir Java Format default)
+- **Copyright header:** Every Java / Kotlin / Scala file must contain `Copyright 2008-present MongoDB, Inc.`
+- **Formatter:** Palantir Java Format
+
+## Kotlin Style Rules
+
+- **Formatter:** ktfmt dropbox style, max width 120
+- **Static analysis:** detekt
+
+## Scala Style Rules
+
+- **Formatter:** scalafmt
+- **Supported versions:** 2.11, 2.12, 2.13, 3 (default: 2.13)
+
+## Groovy Style Rules
+
+- **Static analysis:** CodeNarc
+
+## Javadoc / KDoc / Scaladoc
+
+- All public classes and interfaces **must** have class-level Javadoc (enforced by checkstyle)
+- Public methods should have Javadoc with `@param`, `@return`, and `@since` tags
+- Use `@since X.Y` to indicate the version when the API was introduced
+- Use `@mongodb.driver.manual <path> <label>` for MongoDB manual links
+- Use `@mongodb.server.release <version>` to indicate the minimum server version required
+- Scala modules use Scaladoc — follow Scaladoc conventions (`@param`, `@return`, `@since`, `@see`)
+- Internal packages (`com.mongodb.internal.*`, `org.bson.internal.*`) are excluded from doc generation
+- Run `./gradlew docs` to validate Javadoc/KDoc/Scaladoc builds cleanly
+
+## Prohibited Patterns
+
+- `System.out.println` / `System.err.println` — Use SLF4J logging
+- `e.printStackTrace()` — Use proper logging/error handling
+
+## Formatting Commands
+
+```bash
+./gradlew spotlessApply    # Auto-fix all formatting
+./gradlew spotlessCheck    # Check without modifying
+```

.agents/references/testing-guide-examples.md

@@ -0,0 +1,92 @@
+---
+name: testing-guide-examples
+description: Test skeleton templates for Java (JUnit 5), Scala (ScalaTest), and Kotlin (kotlin.test) in the MongoDB Java Driver. Use when writing new tests to match structural conventions.
+---
+# Test Skeletons
+
+Match these structural conventions when writing new tests.
+
+## Java — JUnit 5
+
+```java
+public class FeatureUnderTestTest extends OperationTest {
+
+    private ResourceType resource;
+
+    @BeforeEach
+    void setup() {
+        // Insert test data, acquire resources
+    }
+
+    @AfterEach
+    void cleanup() {
+        // Release resources to prevent leaks
+    }
+
+    @Test
+    @DisplayName("should do expected behavior")
+    void shouldDoExpectedBehavior() {
+        // given
+        // when
+        // then
+    }
+
+    @ParameterizedTest(name = "{index} => input={0}, expected={1}")
+    @MethodSource
+    @DisplayName("should handle varied inputs")
+    void shouldHandleVariedInputs(final int input, final int expected) {
+        assertEquals(expected, methodUnderTest(input));
+    }
+
+    private static Stream<Arguments> shouldHandleVariedInputs() {
+        return Stream.of(arguments(1, 1), arguments(2, 4));
+    }
+}
+```
+
+## Scala — ScalaTest with Mockito
+
+```scala
+class FeatureUnderTestSpec extends BaseSpec with MockitoSugar {
+
+  val wrapped = mock[JWrappedType]
+  val underTest = new ScalaWrapper(wrapped)
+
+  "ScalaWrapper" should "have the same methods as the wrapped type" in {
+    val wrappedMethods = classOf[JWrappedType].getMethods.map(_.getName).toSet
+    val localMethods = classOf[ScalaWrapper].getMethods.map(_.getName)
+    // Assert parity
+  }
+
+  it should "delegate to underlying method" in {
+    underTest.someMethod("arg")
+    verify(wrapped).someMethod("arg")
+  }
+}
+```
+
+## Kotlin — kotlin.test with Mockito-Kotlin
+
+```kotlin
+class FeatureUnderTestTest {
+
+    companion object {
+        internal val wrapped: com.mongodb.client.MongoCollection<MyType> = mock()
+        lateinit var collection: MongoCollection<MyType>
+
+        @JvmStatic
+        @BeforeAll
+        internal fun setUpMocks() {
+            collection = MongoCollection(wrapped)
+            whenever(wrapped.namespace).doReturn(MongoNamespace("db", "coll"))
+        }
+    }
+
+    @Test
+    fun shouldProduceCorrectBson() {
+        assertEquals(BsonDocument.parse("""{"expected": 1}"""), resultUnderTest.toBsonDocument())
+    }
+
+    data class MyType(val id: String, val name: String)
+}
+```

.agents/references/testing-guide.md

@@ -0,0 +1,69 @@
+---
+name: testing-guide
+description: Testing frameworks, conventions, and commands for the MongoDB Java Driver. Use when writing or running tests — covers framework selection per module, test naming conventions, integration test setup, and how to run specific test subsets.
+---
+# Testing Guide
+
+## Frameworks
+
+| Framework | Usage | Notes |
+| --- | --- | --- |
+| JUnit 5 (Jupiter) | Primary unit test framework | All new tests |
+| Spock (Groovy) | Legacy tests | Do not add new Spock tests |
+| Mockito | Mocking | Use `mockito-junit-jupiter` integration |
+| ScalaTest | Scala module testing | FlatSpec + ShouldMatchers |
+| Project Reactor | Reactive test utilities | `driver-reactive-streams` tests |
+
+## Assertions
+
+- **JUnit Jupiter Assertions** (`org.junit.jupiter.api.Assertions`) is the standard for all new tests
+- Hamcrest matchers appear in older tests but should not be used in new code
+- AssertJ is in the dependency catalog but is not used — do not introduce it
+- Spock tests use Spock's built-in `expect:`/`then:` assertions (no external assertion library)
+
+## Writing Tests
+
+- Every code change must include tests
+- Extend existing test patterns in the module you are modifying
+- Unit tests must not require a running MongoDB instance
+- Descriptive method names: `shouldReturnEmptyListWhenNoDocumentsMatch()` not `test1()`
+- Use `@DisplayName` for human-readable names
+- Clean up test data in `@AfterEach` / `cleanup()` to prevent pollution
+
+## Running Tests
+
+```bash
+# All tests (unit + integration)
+./gradlew check
+
+# Single module
+./gradlew :driver-core:test
+
+# Integration tests (requires MongoDB)
+./gradlew integrationTest -Dorg.mongodb.test.uri="mongodb://localhost:27017"
+
+# Specific test class
+./gradlew :driver-core:test --tests "com.mongodb.internal.operation.FindOperationTest"
+
+# Alternative JDK
+./gradlew test -PjavaVersion=11
+
+# Scala tests (all versions)
+./gradlew scalaCheck
+```
+
+## Module-Specific Notes
+
+- **driver-core:** Largest test suite — JUnit 5 + Spock + Mockito
+- **driver-sync:** JUnit 5 + Spock (heavy Spock usage, but don’t add new)
+- **driver-reactive-streams:** JUnit 5 + Spock + Project Reactor
+- **bson-scala / driver-scala:** ScalaTest, test per Scala version
+- **Kotlin modules:** JUnit 5 + mockito-kotlin
+
+## Integration Tests
+
+- Require a running MongoDB instance
+- Set connection URI: `-Dorg.mongodb.test.uri="mongodb://localhost:27017"`
+- Integration test source set configured via `conventions/testing-integration.gradle.kts`
+
+See [testing-guide-examples.md](testing-guide-examples.md) for Java, Scala, and Kotlin test skeletons.