[agents] Update AGENTS.MD with review-derived guidance

AGENTS.md

@@ -12,6 +12,83 @@ guide for package-specific conventions and workflows.
 - `cuda_core/`: High-level Pythonic CUDA APIs built on top of bindings.
 - `cuda_python/`: Metapackage and docs aggregation.
 
+# Review-derived repository guidance
+
+These rules come from recurring cuda-python PR review comments. Apply them
+across the repository, in addition to any package-specific `AGENTS.md`.
+
+## Public API and design
+
+- For new public APIs, major behavior changes, or broad feature work, make sure
+  the API surface is sketched in an issue or design discussion before coding.
+  Reviewers repeatedly block large feature PRs that arrive without design
+  context, especially before 1.0 API stabilization.
+- Keep public APIs minimal and intentional. Avoid exposing private helpers just
+  to make tests or examples easier; prefer improving the public path or keeping
+  helpers private.
+- When adding public behavior, update docs, examples, release notes, and API
+  index pages in the same PR unless the PR explicitly documents why those
+  updates are deferred.
+- User-facing errors and warnings should name the user-actionable concept, not
+  a private helper. Include diagnostics when something cannot be discovered,
+  and avoid silent success-shaped fallbacks.
+
+## Tests and CI behavior
+
+- Add targeted regression tests for behavioral fixes. Do not add elaborate
+  tests that mostly prove an implementation detail or require large module
+  stubbing unless that is the only practical way to cover the bug.
+- Do not weaken tests just to pass a platform or CI configuration. Avoid broad
+  platform skips such as "skip all WSL" or "skip all Windows"; query CUDA
+  driver/device capability or the specific missing library/feature instead.
+- Preserve real user workflows in tests. Do not change global CUDA state, skip
+  real loading paths, or disable release-note/doc checks merely to reduce CI
+  load unless reviewers have agreed to that behavior change.
+- Before pushing, run the narrowest relevant `pixi run ...`, `pytest`, docs, or
+  workflow validation command available for the touched package. If local
+  validation is impossible, state the exact reason in the PR.
+
+## Generated code and CUDA compatibility
+
+- Do not hand-edit generated binding artifacts as a shortcut. Fix the generator
+  source or templates and regenerate/sync outputs so the next generation does
+  not reintroduce the same review issue.
+- Lint or formatting changes that touch generated files should either be made
+  in the generator (`cython-gen`, `cybind`, templates, or sync source) or should
+  exclude generated outputs from the check.
+- Keep builds working across the supported CUDA major versions. Do not cimport
+  or call newly generated Cython symbols directly unless the older supported
+  CUDA-major build is gated or has a wrapper/fallback path.
+- In Cython/CUDA code, preserve CUDA stream ordering, handle ownership, and
+  context-manager semantics. Cleanup paths should not mask a user's original
+  exception, and `__enter__` should not expose invalid handles.
+
+## Workflows, packaging, and metadata
+
+- GitHub workflow logic should parse structured data with `jq` or GitHub's
+  `--jq` support. Avoid substring `grep` checks for labels, milestones, or
+  JSON fields when exact matching is possible.
+- Use the correct GitHub Actions context (`env`, `vars`, `github`, `inputs`)
+  deliberately; a wrong context often evaluates to an empty string and silently
+  breaks release or validation workflows.
+- Keep workflow permissions minimal and explicit, and include all triggers
+  needed for metadata checks to rerun when labels or milestones change.
+- Packaging changes should keep version constraints, wheel/sdist behavior,
+  release tags, and metapackage dependencies aligned across all affected
+  packages. Use exact version or lower-bound choices intentionally.
+
+## Documentation style
+
+- For Sphinx/Numpy-style docs, document class construction in the class
+  docstring and signature rather than separately documenting `__init__` or
+  `__new__`, unless the surrounding docs already use that convention.
+- Add docs entries for new public classes/functions in the relevant
+  `docs/source/api*.rst` or autosummary index, and build docs when changing
+  generated API pages.
+- Prefer concise comments that explain non-obvious compatibility, security, or
+  workflow choices. Remove duplicated error text, stale TODOs, and comments that
+  merely restate the code.
+
 # Pull requests
 
 When creating pull requests with `gh pr create`, always assign at least one

cuda_bindings/AGENTS.md

@@ -35,6 +35,12 @@ subpackage in the `cuda-python` monorepo.
   defined in `build_hooks.py`; update those rules when introducing new symbols.
 - **Platform split files**: keep `_linux.pyx` and `_windows.pyx` variants
   aligned when behavior should be equivalent.
+- **Lint at the source**: if formatting or lint fixes affect generated files,
+  make the fix in the generation source (`cython-gen`, `cybind`, templates, or
+  sync source) or exclude generated outputs from the check. Otherwise the next
+  regeneration will reintroduce the same issue.
+- **Cython copies**: prefer typed assignment for wrapper-owned C struct copies
+  over raw `memcpy` when the generated Cython/C types can define the copy size.
 
 ## Testing expectations
 
@@ -65,3 +71,10 @@ subpackage in the `cuda-python` monorepo.
   `docs/source/module/` and tests in `tests/`.
 - Prefer changes that are easy to regenerate/rebuild rather than patching
   generated output directly.
+- Preserve compatibility with the supported CUDA major-version matrix. If a new
+  CUDA header symbol is unavailable in an older supported build, gate it or call
+  through an existing Python wrapper instead of directly cimporting the new
+  generated Cython symbol.
+- For external contributions touching generated `cuda_bindings` code, ask for a
+  reproducer and environment details, then route fixes through the generation
+  source rather than accepting one-off generated edits.

cuda_core/AGENTS.md

@@ -63,3 +63,21 @@ This file describes `cuda_core`, the high-level Pythonic CUDA subpackage in the
   call-site consistency.
 - Prefer explicit error propagation over silent fallback paths.
 - If you change public behavior, update tests and docs under `docs/source/`.
+- For new public APIs or broad feature work, sketch the API and behavior in an
+  issue/design discussion before opening a large implementation PR. Reviewers
+  often block major `cuda_core` features until API shape, examples, and
+  docs/release-note coverage are clear.
+- Feature availability checks should query CUDA driver/device capabilities
+  instead of hard-coding broad platform skips. Prefer properties such as
+  capability flags over assumptions like "Windows", "Linux", or "WSL".
+- Keep CUDA 12.x and 13.x build compatibility in mind. Do not directly cimport
+  newly generated binding symbols unless older supported CUDA-major builds are
+  gated or have a wrapper/fallback path.
+- Resource and context-manager code must preserve stream ordering, ownership,
+  and exception semantics. `close()`/cleanup paths should use the stream that
+  established the resource ordering, and `__exit__` should avoid masking a
+  user's original exception where practical.
+- Tests should cover the behavior users exercise, not just private helpers.
+  Avoid large module-stubbing tests for simple implementation choices; prefer
+  focused regressions around the public API or the smallest stable internal
+  boundary.

cuda_pathfinder/AGENTS.md

@@ -48,6 +48,16 @@ Windows.
 - **Prefer focused abstractions**: if a change is platform-specific, route it
   through existing platform abstraction points instead of branching in many call
   sites.
+- **No default-location fallbacks without triage**: pathfinder intentionally
+  avoids guessing fallback install locations because that can hide broken
+  environments. Add explicit search steps or diagnostics rather than silent
+  fallback paths.
+- **Validate environment roots before trusting them**: `CUDA_HOME`,
+  `CUDA_PATH`, and related roots should be checked for the needed headers or
+  libraries, not just for being set.
+- **Keep skip logic feature-specific**: tests that depend on libraries or
+  driver capabilities should skip based on the missing library/capability, not
+  broad platform labels.
 
 ## Testing expectations
 

cuda_python/AGENTS.md

@@ -22,3 +22,9 @@ monorepo.
   compatibility between metapackage versioning and subpackage constraints.
 - If you update docs structure, ensure `docs/build_all_docs.sh` still collects
   docs from `cuda_python`, `cuda_bindings`, `cuda_core`, and `cuda_pathfinder`.
+- Packaging PRs should keep release tags, dependency pins, wheel/sdist behavior,
+  and docs aggregation aligned with the component packages. Use exact versions
+  or lower bounds intentionally and document the compatibility reason in the PR.
+- Do not move substantial development-environment guidance here unless it is the
+  supported local-development path; generic "install with package manager"
+  instructions tend to get rejected in review.