Add AGENTS.md and GitHub Copilot instructions

[napetrov]

What

Add structured AI agent instructions following Intel's AGENTS spec v4:

• AGENTS.md — project context for agents (RNG interface, archetype, structure, source-of-truth mapping)
• .github/copilot-instructions.md — agent behavior policy (precedence, contribution expectations, Intel-specific constraints)

Why

Standardizes how AI coding assistants (GitHub Copilot, Claude, etc.) understand and work with this repo, reducing hallucinations and enforcing Intel engineering standards automatically.

Key guidance added

• Preserve numpy.random API compatibility by default
• RNG specifics: BRNG selection and distribution methods must preserve statistical properties
• Release GIL (with nogil:) for MKL RNG calls (thread-safe in MKL)
• No hardcoded versions, flags, or BRNG names outside __init__.py
• Statistical validation required for RNG changes
• Local dev: conda create -n dev python numpy cython mkl-devel pytest && pip install -e .

Token budget

• AGENTS.md: 217 words (limit 220)
• Based on mkl_fft pattern

Checklist

• AGENTS.md exists at repo root
• .github/copilot-instructions.md exists
• Required headings present
• No placeholder text
• No mutable details hardcoded
• Precedence hierarchy documented
• Word count within limits

[napetrov]

Updated PR with a more useful multi-level AGENTS hierarchy (commit b0e4a38):

• expanded root AGENTS into entry-point + directory map
• added local AGENTS in .github, mkl_random/, mkl_random/tests/, conda-recipe/, conda-recipe-cf/, examples/
• updated copilot-instructions mandatory flow to use nearest AGENTS per edited file

This keeps instructions concise at root and more actionable in each working directory.

[ndgrigorian]

@napetrov
interfaces has been added, and main namespace updated, shifting to mkl_random.MKLRandomState + (deprecated) mkl_random.RandomState.

RandomState in numpy_random interface aligned to numpy's numpy.random.RandomState, and mkl_random.interfaces.numpy_random is fully aligned to numpy.random namespace (aside from get_state and set_state, which cannot be)

patch will also be coming soon

otherwise if above comment fixed, LGTM

[jharlow-intel]

Thanks for putting this together! The layered AGENTS setup with a Copilot entry point matches what mkl-service and mkl_umath already have, and the guardrails around statistical correctness and numpy.random compatibility are spot on. It predates the meson move, though, so a few things need updating; details inline.

• Heads-up: #190 adds AGENTS.md files at the same paths (root, .github, conda-recipe*, mkl_random, tests) for the current meson layout, so these two will conflict. Could we fold the parts #190 doesn't have, like copilot-instructions.md and examples/AGENTS.md, into a single PR?

[jharlow-intel]

This needs a refresh before merge, since it predates the switch to meson-python: master builds from meson.build and there's no setup.py anymore, so the build-system and source-of-truth lists here and in copilot-instructions.md point agents at the wrong files. The editable install also needs --no-build-isolation with meson-python (mkl-service's AGENTS.md uses python -m pip install --no-deps --no-build-isolation .). While you're in there, .github/AGENTS.md is missing build-with-standard-clang, build_pip, coverity, openssf-scorecard, pre-commit, and zizmor, and src/ no longer has support scripts (Anton's point).