From fb096f01656af3120bc4362168868f8043469b46 Mon Sep 17 00:00:00 2001
From: Mark Harris <mharris@nvidia.com>
Date: Tue, 10 Feb 2026 15:35:57 +1100
Subject: [PATCH 1/2] Add AGENTS.md for AI agent guidance (#453)

Provide persistent instructions for AI coding agents (Cursor, Copilot,
Codex, etc.) covering git commit conventions, Python and C++ code style,
license headers, whitespace rules, testing, and PR/issue workflows.

Fixes #453

Signed-off-by: Mark Harris <mharris@nvidia.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
---
 AGENTS.md | 83 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 83 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..cc33bcb42
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,83 @@
+# AGENTS.md — AI Agent Guidelines for fVDB
+
+This file provides persistent instructions for AI coding agents (Cursor, Copilot,
+Codex, etc.) working on this codebase. Human contributors should also refer to
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Git Commits
+
+- All commits **must** include a DCO sign-off (`git commit --signoff` / `-s`).
+- All commits **must** be SSH-signed (`git commit --gpg-sign` / `-S`).
+- **Never** skip hooks or signing: do not use `--no-verify` or `--no-gpg-sign`.
+
+## Python Code Style
+
+- Format Python code with **black** using the exact flags from CI:
+
+  ```
+  black --target-version=py311 --line-length=120 --extend-exclude='wip/' .
+  ```
+
+- **Do not** run `black` with default settings — the default line-length (88) does
+  not match this project's setting (120).
+- There is currently no `[tool.black]` section in `pyproject.toml`; a future PR may
+  add one so that plain `black .` picks up the correct settings automatically.
+
+## C++ Code Style
+
+- Format C++ source files under `src/` with **clang-format 18** using the
+  repository's `.clang-format` style file:
+
+  ```
+  clang-format -i --style=file src/**/*.{h,cpp,cc,cu,cuh}
+  ```
+
+- Applicable extensions: `.h`, `.cpp`, `.cc`, `.cu`, `.cuh`.
+
+## License Headers
+
+Every source file **must** include the Apache-2.0 SPDX identifier.
+
+Python files:
+
+```python
+# Copyright Contributors to the OpenVDB Project
+# SPDX-License-Identifier: Apache-2.0
+```
+
+C++ files:
+
+```cpp
+// Copyright Contributors to the OpenVDB Project
+// SPDX-License-Identifier: Apache-2.0
+```
+
+## Whitespace
+
+- No trailing whitespace (CI enforces this; `.wlt` files and `wip/` are excluded).
+- Use spaces, not tabs (binary and a few config files are excluded from this check).
+
+## Testing
+
+- Run relevant tests before pushing:
+
+  ```
+  python -m pytest tests/ -v
+  ```
+
+- The `wip/` directory is excluded from test collection (see `norecursedirs` in
+  `pyproject.toml`).
+
+## Opening Issues
+
+- Set appropriate labels (e.g. `bug`, `enhancement`, `documentation`).
+- Reference any related issues or PRs.
+- For bugs: provide clear reproduction steps, expected vs actual behavior, and
+  environment details.
+
+## Opening Pull Requests
+
+- Reference the issue being fixed (e.g. "Fixes #NNN").
+- Include a test plan with specific commands to verify the change.
+- Ensure all CI checks pass before requesting review (DCO, codestyle, tests).
+- Keep PRs focused on a single concern.

From 49e6a2887f35e447d7cf4210fee21563e63c4571 Mon Sep 17 00:00:00 2001
From: Mark Harris <mharris@nvidia.com>
Date: Wed, 11 Feb 2026 10:23:57 +1100
Subject: [PATCH 2/2] Couple more style points.

Signed-off-by: Mark Harris <mharris@nvidia.com>
---
 AGENTS.md | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index cc33bcb42..1c4779f1b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -10,6 +10,11 @@ Codex, etc.) working on this codebase. Human contributors should also refer to
 - All commits **must** be SSH-signed (`git commit --gpg-sign` / `-S`).
 - **Never** skip hooks or signing: do not use `--no-verify` or `--no-gpg-sign`.
 
+## General Style
+
+- Avoid excessive use of emoji and non-ascii characters in code and documentation except
+  where it is helpful to user experience or user interfaces.
+
 ## Python Code Style
 
 - Format Python code with **black** using the exact flags from CI:
@@ -81,3 +86,8 @@ C++ files:
 - Include a test plan with specific commands to verify the change.
 - Ensure all CI checks pass before requesting review (DCO, codestyle, tests).
 - Keep PRs focused on a single concern.
+
+**Do not commit unless directed:**
+- `.vscode/settings.json` - local IDE settings
+- `.cursor/` - local Cursor config
+- Test-specific matrices or configs with hardcoded paths