Add AGENTS.md and GitHub Copilot instructions

.github/AGENTS.md

@@ -0,0 +1,15 @@
+# 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_pip.yaml` — wheel build pipeline
+- `pre-commit.yml` — lint/format checks
+- `openssf-scorecard.yml` — security scanning
+
+## Policy
+- Treat workflow YAML as canonical for platform/Python matrices.
+- Avoid doc claims about CI coverage unless present in workflow config.

.github/copilot-instructions.md

@@ -0,0 +1,45 @@
+# GitHub Copilot Instructions — mkl_fft
+
+## Identity
+You are an expert Python/C/Cython developer working on `mkl_fft` at Intel.
+Prioritize correctness, API compatibility, 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/SciPy FFT compatibility by default.
+- For behavior changes: update/add tests in `mkl_fft/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.
+- **C templates:** edit only `mkl_fft/src/*.c.src`; do not manually edit generated `.c` files.
+- Prefer stable local entry points:
+  - `python -m pip install -e .`
+  - `pytest mkl_fft/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_fft/__init__.py`, `mkl_fft/interfaces/*.py`, `mkl_fft/_pydfti.pyx`
+- Tests: `mkl_fft/tests/`
+
+## Intel-specific constraints
+- Build-time MKL: `mkl-devel`; runtime MKL integration via `mkl-service`
+- Performance claims require reproducible benchmark context
+- Do not introduce ISA-specific assumptions outside explicit build configuration

AGENTS.md

@@ -0,0 +1,47 @@
+# AGENTS.md — mkl_fft
+
+Entry point for agent context in this repo.
+
+## What this project is
+`mkl_fft` is a NumPy/SciPy-compatible FFT interface backed by Intel® oneMKL.
+It provides accelerated FFT transforms while aiming to preserve upstream API behavior.
+
+## Key components
+- **Package:** `mkl_fft/`
+- **Cython bindings:** `mkl_fft/_pydfti.pyx`
+- **Template-based C backend:** `mkl_fft/src/*.c.src`
+- **Interface adapters:** `mkl_fft/interfaces/`
+- **Tests:** `mkl_fft/tests/`
+- **Vendored helpers:** `_vendored/`
+- **Packaging:** `conda-recipe/`, `conda-recipe-cf/`
+
+## Build/runtime basics
+- Build system: `pyproject.toml` + `setup.py`
+- Build deps: `cython`, `numpy`, `mkl-devel`
+- Runtime deps: `numpy`, `mkl-service`
+
+## Development guardrails
+- Preserve NumPy/SciPy FFT API compatibility unless change is explicitly requested.
+- Edit template sources (`*.c.src`), not generated C artifacts.
+- Pair behavior changes with tests and keep diffs minimal.
+- 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/workflows: `.github/workflows/*.{yml,yaml}`
+- Public API: `mkl_fft/__init__.py`, `mkl_fft/interfaces/`
+- Tests: `mkl_fft/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_fft/AGENTS.md` — package-level implementation context
+- `mkl_fft/interfaces/AGENTS.md` — NumPy/SciPy interface adapters
+- `mkl_fft/src/AGENTS.md` — C template backend rules
+- `mkl_fft/tests/AGENTS.md` — test scope/conventions
+- `conda-recipe/AGENTS.md` — Intel-channel conda packaging
+- `conda-recipe-cf/AGENTS.md` — conda-forge recipe context
+- `_vendored/AGENTS.md` — vendored tooling boundaries

_vendored/AGENTS.md

@@ -0,0 +1,8 @@
+# AGENTS.md — _vendored/
+
+Vendored utilities used by build/code-generation flows.
+
+## Guardrails
+- Prefer updating upstream source when feasible; keep local vendored diffs minimal.
+- Do not refactor vendored code opportunistically in unrelated PRs.
+- If vendored logic affects generated sources, validate downstream build/test paths.

conda-recipe-cf/AGENTS.md

@@ -0,0 +1,10 @@
+# AGENTS.md — conda-recipe-cf/
+
+Conda-forge recipe context for `mkl_fft`.
+
+## Scope
+- conda-forge specific recipe files under this directory.
+
+## Guardrails
+- Keep conda-forge recipe semantics separate from Intel-channel recipe.
+- Align changes with `conda-package-cf.yml` workflow behavior.

conda-recipe/AGENTS.md

@@ -0,0 +1,11 @@
+# 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 packaging intent.
+- Keep recipe updates synchronized with CI workflow behavior.

mkl_fft/AGENTS.md

@@ -0,0 +1,16 @@
+# AGENTS.md — mkl_fft/
+
+Core package implementation for MKL-backed FFT operations.
+
+## Key files
+- `__init__.py` — public package API surface
+- `_pydfti.pyx` — Cython bindings for DFTI interactions
+- `_mkl_fft.py` / `_fft_utils.py` — runtime FFT helper logic
+- `interfaces/` — NumPy/SciPy adapter modules
+- `src/` — C template backend (`*.c.src`)
+- `tests/` — package tests (see local AGENTS in tests)
+
+## Guardrails
+- Preserve NumPy/SciPy-compatible behavior by default.
+- Keep adapter, binding, and backend changes coordinated with tests.
+- Prefer minimal isolated edits around changed API paths.

mkl_fft/interfaces/AGENTS.md

@@ -0,0 +1,11 @@
+# AGENTS.md — mkl_fft/interfaces/
+
+Adapter layer for `numpy.fft` / `scipy.fft` style interfaces.
+
+## Scope
+- Interface modules mapping user-facing calls to MKL-backed implementation.
+
+## Guardrails
+- Preserve function signatures and behavioral expectations unless explicitly requested.
+- Keep compatibility with upstream NumPy/SciPy semantics in mind.
+- Any user-visible behavior change here should include tests in `mkl_fft/tests/`.

mkl_fft/src/AGENTS.md

@@ -0,0 +1,11 @@
+# AGENTS.md — mkl_fft/src/
+
+C template backend for FFT internals.
+
+## Scope
+- Template sources (`*.c.src`) used to generate C implementation artifacts.
+
+## Guardrails
+- Edit template files (`*.c.src`) rather than generated `.c` files.
+- Keep template changes tightly scoped and validated by tests.
+- Coordinate with Cython/binding/API layers when changing function behavior.

mkl_fft/tests/AGENTS.md

@@ -0,0 +1,11 @@
+# AGENTS.md — mkl_fft/tests/
+
+Test suite for FFT API compatibility and regressions.
+
+## Expectations
+- Behavior changes should include test updates in the same PR.
+- Bug fixes require regression tests.
+- Keep tests deterministic and avoid brittle performance-dependent assertions.
+
+## Entry point
+- `pytest mkl_fft/tests`