More polishing of agents and skills

Author: rozza

.agents/skills/api-design/SKILL.md

@@ -2,15 +2,18 @@
 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 for production use.
-- `@Beta` — Subject to change or removal. Libraries should not depend on these.
-- `@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.
+- `@Alpha` — Early development, may be removed.
+  Not for production use.
+- `@Beta` — Subject to change or removal.
+  Libraries should not depend on these.
+- `@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.
 
 ## Design Principles

.agents/skills/evergreen/SKILL.md

@@ -2,12 +2,12 @@
 name: evergreen
 description: Evergreen CI infrastructure, configuration validation. Use when modifying .evergreen/ config, preparing to submit changes or understanding the Evergreen test matrix.
 ---
-
 # Evergreen
 
 ## Evergreen (MongoDB Internal CI)
 
-Primary CI runs on MongoDB's Evergreen system. Configuration lives in `.evergreen/`.
+Primary CI runs on MongoDB’s Evergreen system.
+Configuration lives in `.evergreen/`.
 
 - Do not modify `.evergreen/` configuration without review
 - Evergreen runs the full test matrix across MongoDB versions, OS platforms, and JDK versions
@@ -30,4 +30,5 @@ To test your changes on Evergreen before merging, create a patch build:
 evergreen patch -u
 ```
 
-This uploads your uncommitted and committed local changes as a patch build on Evergreen, allowing you to run the full CI test matrix against your branch.
+This uploads your uncommitted and committed local changes as a patch build on Evergreen, allowing you to run the full CI
+test matrix against your branch.

.agents/skills/project-guide/SKILL.md

@@ -2,7 +2,6 @@
 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

.agents/skills/spec-tests/SKILL.md

@@ -2,14 +2,12 @@
 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, or when working with the test data in testing/resources/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.
+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
 
@@ -40,4 +38,4 @@ testing/
 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
+4. Ensure tests run with `./gradlew check` or the module’s test task

.agents/skills/style-reference/SKILL.md

@@ -2,7 +2,6 @@
 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, or language-specific formatter configuration. Spotless auto-enforces most rules.
 ---
-
 # Style Reference
 
 ## Java Style Rules

.agents/skills/testing-guide/SKILL.md

@@ -2,7 +2,6 @@
 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
@@ -49,7 +48,7 @@ description: Testing frameworks, conventions, and commands for the MongoDB Java
 ## 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-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

AGENTS.md

@@ -1,13 +1,10 @@
 # AGENTS.md - MongoDB Java Driver
 
-Official MongoDB JVM driver monorepo (Java, Kotlin, Scala).
 All changes require human review.
-Breaking changes to public API require a major version bump — always warn if binary
-compatibility is affected.
+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.
+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
@@ -23,8 +20,7 @@ Each module has its own `AGENTS.md`.
 
 ## Build
 
-Gradle with Kotlin DSL. Build JDK: 17+. Source baseline: Java 8. Versions in
-`gradle/libs.versions.toml`.
+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)
@@ -36,8 +32,7 @@ Gradle with Kotlin DSL. Build JDK: 17+. Source baseline: Java 8. Versions in
 
 `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.
+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,15 +43,14 @@ rules.
 
 - Every code change must include tests.
   Do not reduce coverage.
-- JUnit 5 primary. Spock is legacy — do not add new Spock tests.
-- Unit tests must not require a running MongoDB instance.
-- Descriptive method names or `@DisplayName`. Clean up in `@AfterEach`.
+- See [`.agents/skills/testing-guide`](.agents/skills/testing-guide/SKILL.md) for framework details and running specific
+  tests.
+- See [`.agents/skills/spec-tests`](.agents/skills/spec-tests/SKILL.md) for MongoDB specification test conventions.
 
 ## 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.
+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
 
@@ -68,14 +62,10 @@ stability annotations and design principles.
 - 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.
+See [`.agents/skills/evergreen`](.agents/skills/evergreen/SKILL.md) for CI validation and patch builds.
 
 ## Before Submitting
 
 ```bash
-./gradlew doc check scalaCheck   # Docs + formatting (spotlessApply) + static checks + all tests
+./gradlew spotlessApply doc check scalaCheck   # formatting + Docs + static checks + all tests
 ```
-
-Note: `check` includes `spotlessApply` for all modules.
-`buildSrc` uses `spotlessCheck` instead (no auto-fix).