Add AGENTS.md and GitHub Copilot instructions

.github/AGENTS.md

@@ -0,0 +1,14 @@
+# AGENTS.md — .github/
+
+CI/CD workflows and repo automation.
+
+## Workflows (source of truth)
+- `conda-package.yml` — Intel channel conda build/test pipeline
+- `conda-package-cf.yml` — conda-forge-oriented build/test pipeline
+- `build-with-clang.yml` — clang compatibility checks
+- `build-docs.yml` — docs build pipeline
+
+## Policy
+- Treat workflow YAML as canonical for platform/Python matrices.
+- Keep artifact naming and channel usage aligned with workflow files.
+- Avoid doc claims about CI coverage unless present in workflow config.

.github/copilot-instructions.md

@@ -0,0 +1,45 @@
+# GitHub Copilot Instructions — mkl_random
+
+## Identity
+You are an expert Python/C/Cython developer working on `mkl_random` at Intel.
+Prioritize correctness, numerical/statistical integrity, and minimal diffs.
+
+## Source of truth
+This file is canonical for Copilot/agent behavior.
+`AGENTS.md` files provide project context.
+
+## Precedence
+copilot-instructions > nearest AGENTS > root AGENTS
+Higher-precedence file overrides lower-precedence context.
+
+## Mandatory flow
+1. Read root `AGENTS.md`. If absent, stop and report.
+2. For each edited file, locate and follow the nearest `AGENTS.md`.
+3. If no local file exists, inherit from root `AGENTS.md`.
+
+## Contribution expectations
+- Keep changes atomic and single-purpose.
+- Preserve `numpy.random` compatibility by default, including compatibility aliases during namespace transitions.
+- For behavior changes: update/add tests in `mkl_random/tests/` in the same change.
+- For bug fixes: include a regression test.
+- Run `pre-commit run --all-files` when `.pre-commit-config.yaml` is present.
+
+## Authoring rules
+- Never invent versions, build flags, CI matrices, or channel policies.
+- Use source-of-truth files for mutable details.
+- Do not hardcode BRNG behavior outside intended API/configuration points.
+- Prefer stable local entry points:
+  - `python -m pip install -e .`
+  - `pytest mkl_random/tests`
+
+## Source-of-truth files
+- Build/config: `pyproject.toml`, `setup.py`
+- Dependencies: `pyproject.toml`, `conda-recipe/meta.yaml`, `conda-recipe-cf/meta.yaml`
+- CI: `.github/workflows/*.{yml,yaml}`
+- API: `mkl_random/__init__.py`, `mkl_random/mklrand.pyx`, `mkl_random/interfaces/*.py` (when present)
+- Tests: `mkl_random/tests/`
+
+## Intel-specific constraints
+- Build-time MKL: `mkl-devel`; runtime MKL: `mkl`
+- Preserve statistical properties for distribution/BRNG-related changes
+- Do not claim performance/statistical improvements without reproducible validation

AGENTS.md

@@ -0,0 +1,46 @@
+# AGENTS.md — mkl_random
+
+Entry point for agent context in this repo.
+
+## What this project is
+`mkl_random` is a NumPy-compatible random module backed by Intel® oneMKL RNG.
+It provides accelerated random sampling with API compatibility goals relative to `numpy.random`.
+
+## Key components
+- **Python package:** `mkl_random/`
+- **Cython layer:** `mkl_random/mklrand.pyx`
+- **C/C++ backend sources:** `mkl_random/src/` (`*.cpp`, `*.h`, support scripts)
+- **Tests:** `mkl_random/tests/`
+- **Packaging:** `conda-recipe/`, `conda-recipe-cf/`
+- **Examples:** `examples/`
+
+## Build/runtime basics
+- Build system: `pyproject.toml` + `setup.py`
+- Build deps: `cython`, `numpy`, `mkl-devel`
+- Runtime deps: `numpy`, `mkl`
+
+## Development guardrails
+- Preserve `numpy.random` API compatibility unless change is explicitly requested.
+- Keep namespace/API transitions explicit (e.g., `mkl_random.MKLRandomState` with compatibility aliases where applicable).
+- RNG changes must preserve statistical correctness and reproducibility expectations.
+- If patching/integration entry points are touched, keep patch semantics and rollback behavior explicit.
+- Keep diffs minimal and pair behavior changes with tests.
+- Avoid hardcoding mutable versions/matrices/channels in docs.
+
+## Where truth lives
+- Build/config: `pyproject.toml`, `setup.py`
+- Dependencies: `pyproject.toml`, `conda-recipe*/meta.yaml`
+- CI matrices/workflows: `.github/workflows/*.{yml,yaml}`
+- Public API: `mkl_random/__init__.py`, `mkl_random/interfaces/*.py` (when present)
+- Tests: `mkl_random/tests/`
+
+For behavior policy, see `.github/copilot-instructions.md`.
+
+## Directory map
+Use nearest local `AGENTS.md` when present:
+- `.github/AGENTS.md` — CI workflows and automation policy
+- `mkl_random/AGENTS.md` — package-level implementation context
+- `mkl_random/tests/AGENTS.md` — testing scope and conventions
+- `conda-recipe/AGENTS.md` — Intel-channel conda packaging
+- `conda-recipe-cf/AGENTS.md` — conda-forge recipe context
+- `examples/AGENTS.md` — runnable examples and expected behavior

conda-recipe-cf/AGENTS.md

@@ -0,0 +1,10 @@
+# AGENTS.md — conda-recipe-cf/
+
+Conda-forge recipe context for `mkl_random`.
+
+## Scope
+- conda-forge specific `meta.yaml` and build scripts in this directory.
+
+## Guardrails
+- Keep conda-forge recipe semantics separate from Intel-channel recipe.
+- Align recipe changes with `conda-package-cf.yml` workflow behavior.

conda-recipe/AGENTS.md

@@ -0,0 +1,12 @@
+# AGENTS.md — conda-recipe/
+
+Intel-channel conda packaging context.
+
+## Scope
+- `meta.yaml` — package metadata and dependency pins
+- `build.sh` / `bld.bat` — platform build scripts
+
+## Guardrails
+- Treat recipe files as canonical for build/runtime dependency intent.
+- Keep recipe updates synchronized with CI workflow expectations.
+- Do not infer platform/Python matrix from docs; read workflow YAML.

examples/AGENTS.md

@@ -0,0 +1,11 @@
+# AGENTS.md — examples/
+
+Runnable usage examples for `mkl_random`.
+
+## Intent
+- Demonstrate practical usage patterns (parallel MC, random states, etc.).
+- Serve as quick sanity checks, not exhaustive correctness/performance tests.
+
+## Guardrails
+- Keep examples concise and runnable.
+- If API behavior in examples changes, keep comments/output expectations consistent.

mkl_random/AGENTS.md

@@ -0,0 +1,18 @@
+# AGENTS.md — mkl_random/
+
+Core package implementation for MKL-backed random functionality.
+
+## Key files
+- `__init__.py` — public package exports/API wiring
+- `mklrand.pyx` — Cython bindings to MKL RNG support
+- `_init_helper.py` — platform/runtime loading helpers
+- `src/` — C/C++ support sources and headers
+- `tests/` — package tests (see local AGENTS in tests)
+
+## Guardrails
+- Preserve `numpy.random`-compatible behavior by default.
+- Keep namespace compatibility explicit (`MKLRandomState` + compatibility aliases where needed).
+- RNG algorithm/distribution changes must preserve statistical correctness.
+- Keep BRNG/distribution behavior explicit and test-covered.
+- If patching/integration shims are modified, ensure behavior remains reversible and test-covered.
+- Prefer minimal, isolated edits around touched API paths.

mkl_random/tests/AGENTS.md

@@ -0,0 +1,12 @@
+# AGENTS.md — mkl_random/tests/
+
+Test suite for RNG behavior, API compatibility, and regressions.
+
+## Expectations
+- Behavior changes in package code should include test updates in the same PR.
+- Add regression tests for bug fixes.
+- Keep tests deterministic when possible (fixed seeds / stable assertions).
+- For statistical assertions, use robust criteria and document rationale.
+
+## Entry point
+- `pytest mkl_random/tests`