Merge pull request #165 from IntelPython/add-copilot-instructions

Add Copilot instructions for AGENTS.md workflow

Author: napetrov

.github/copilot-instructions.md

@@ -0,0 +1,45 @@
+# GitHub Copilot Instructions — mkl_umath
+
+## Identity
+You are an expert Python/C/Cython developer working on `mkl_umath` at Intel.
+Prioritize correctness, numerical 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 rules override 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 runtime patching API (`use_in_numpy()`, `restore()`, `is_patched()`) unless explicitly requested.
+- For behavior changes, update tests in `mkl_umath/tests/` in the same step.
+- For bugs, include a regression test.
+- Do not modify generated artifacts directly when template/source files are the intended edit points.
+
+## Authoring rules
+- Never invent versions, compilers, or CI matrix values.
+- Use source-of-truth files for dependencies and build config.
+- Respect precision/correctness guardrails (`fp:precise`, `fimf-precision=high`, related flags).
+- Avoid hardcoded ISA assumptions unless explicitly present in existing build configuration.
+- Never include secrets or credentials in code/docs.
+
+## Source-of-truth files
+- Build: `CMakeLists.txt`, `pyproject.toml`, `setup.py`
+- Dependencies/packaging: `conda-recipe*/meta.yaml`
+- CI: `.github/workflows/*.{yml,yaml}`
+- API: `mkl_umath/__init__.py`, `mkl_umath/src/_patch.pyx`
+- Core implementation: `mkl_umath/src/*.{c,c.src,pyx}`
+- Tests: `mkl_umath/tests/`
+
+## Intel-specific constraints
+- oneMKL is required; `icx` and `clang` toolchains are both valid when compiler-specific flags are gated correctly.
+- Patching behavior must remain compatible with NumPy integration semantics.
+- Performance optimizations must not compromise numerical correctness.

AGENTS.md

@@ -19,7 +19,7 @@ It provides:
 
 ## Build dependencies
 **Required:**
-- Intel® C Compiler (icx)
+- Compiler toolchain: Intel `icx` or `clang` (with Intel-only flags gated when using clang)
 - Intel® OneMKL (mkl-devel)
 - Intel® TBB (tbb-devel)
 - NumPy, Cython, scikit-build, cmake, ninja
@@ -30,7 +30,7 @@ conda install -c https://software.repos.intel.com/python/conda \
   mkl-devel tbb-devel dpcpp_linux-64 numpy-base \
   cmake ninja cython scikit-build
 export MKLROOT=$CONDA_PREFIX
-CC=icx pip install --no-build-isolation --no-deps .
+CC=${CC:-icx} pip install --no-build-isolation --no-deps .  # clang is also supported in CI
 ```
 
 ## CI/CD
@@ -72,9 +72,9 @@ mkl_umath.restore()       # Restore original NumPy loops
 - **NumPy source:** Requires Intel-optimized NumPy from Intel channel (`software.repos.intel.com/python/conda`). PyPI NumPy may cause runtime failures or incorrect results.
 - **Precision flags:** `fp:precise`, `fimf-precision=high` enforce IEEE 754 compliance. Removing them breaks numerical correctness in scientific computing.
 - **Patching order:** If using multiple Intel patches (e.g., `mkl_random` + `mkl_umath`), apply `mkl_umath` last. Verify with `is_patched()` after each.
-- **Compiler:** Intel `icx` is the supported compiler. `build-with-clang.yml` validates compatibility, but icx is recommended for production.
+- **Compiler/toolchain:** `icx` and `clang` are both supported; when using clang, keep Intel-only flags behind compiler guards.
 - **Build validation:**
-  - After setup: `which icx` → should point to conda env or oneAPI location
+  - After setup: `which ${CC:-icx}` → should resolve to the intended compiler toolchain
   - Verify: `echo $MKLROOT` → should be set
   - Check: `python -c "import numpy; print(numpy.__version__)"` → confirm Intel NumPy