docs: add hierarchical AGENTS and copilot instructions

Author: napetrov

.github/AGENTS.md

@@ -0,0 +1,7 @@
+# AGENTS.md — .github/
+
+CI workflows, automation, and templates.
+
+- Keep required checks and matrix in workflow files only.
+- Keep instruction docs long-lived (no mutable values).
+- Treat workflow/job renames as breaking for tooling.

.github/copilot-instructions.md

@@ -0,0 +1,22 @@
+# GitHub Copilot Instructions — dpnp
+
+## Source of truth
+This file is canonical for Copilot behavior in this repository.
+
+`AGENTS.md` files provide directory scope/guardrails for AGENTS-aware tools and
+should not duplicate Copilot policy text.
+
+## Mandatory flow
+Read root `AGENTS.md`, then nearest local `AGENTS.md` for edited files; most specific wins.
+
+## Authoring rules
+- Keep suggestions minimal and scoped.
+- Use source-of-truth files for mutable details.
+- Do not invent or hardcode versions, flags, or matrix values.
+
+## Source-of-truth files
+- Build/config: `CMakeLists.txt`, `pyproject.toml`, `setup.py`, `setup.cfg`
+- CI/checks: `.github/workflows/`
+- Style/lint: `.pre-commit-config.yaml`, `.clang-format`, `.flake8`
+- API/package paths: `dpnp/`, `doc/`
+- Examples/benchmarks context: `examples/`, `benchmarks/`

.github/instructions/build.instructions.md

@@ -0,0 +1,9 @@
+---
+applyTo: "{CMakeLists.txt,pyproject.toml,setup.py,setup.cfg,**/CMakeLists.txt}"
+---
+
+# Build Instructions for GitHub Copilot
+
+- Reuse existing build/config patterns.
+- Keep mutable build details in source-of-truth files.
+- Avoid introducing parallel build paths unless requested.

.github/instructions/testing.instructions.md

@@ -0,0 +1,9 @@
+---
+applyTo: "{dpnp/tests/**,tests_external/**}"
+---
+
+# Testing Instructions for GitHub Copilot
+
+- Add regression tests for bug fixes.
+- Keep tests deterministic and scoped to changed behavior.
+- Prefer smallest test surface proving correctness.

AGENTS.md

@@ -0,0 +1,19 @@
+# AGENTS.md
+
+This file is for AGENTS-aware tools.
+
+Scope:
+- Repository context for AGENTS-aware agents.
+- Directory routing to local AGENTS files.
+
+For Copilot policy (flow, source-of-truth, edit hygiene), see:
+- `.github/copilot-instructions.md` (canonical for Copilot behavior)
+
+Directory map:
+- `.github/AGENTS.md`
+- `dpnp/AGENTS.md`
+- `doc/AGENTS.md`
+- `examples/AGENTS.md`
+- `benchmarks/AGENTS.md`
+- `scripts/AGENTS.md`
+- `tests_external/AGENTS.md`

benchmarks/AGENTS.md

@@ -0,0 +1,7 @@
+# AGENTS.md — benchmarks/
+
+Benchmark scripts and performance evaluation.
+
+- Keep runs reproducible and inputs explicit.
+- Separate harness changes from algorithm changes.
+- Preserve output contracts used by downstream analysis.

doc/AGENTS.md

@@ -0,0 +1,7 @@
+# AGENTS.md — doc/
+
+Documentation sources and build artifacts.
+
+- Keep docs aligned with current public behavior.
+- Prefer concise examples; avoid stale version-specific claims.
+- Update docs when user-visible behavior changes.

dpnp/AGENTS.md

@@ -0,0 +1,7 @@
+# AGENTS.md — dpnp/
+
+Core package implementation and Python/Cython-facing behavior.
+
+- Preserve API behavior and compatibility by default.
+- Keep dtype/shape/error behavior explicit.
+- For test policy, follow `.github/instructions/testing.instructions.md`.

examples/AGENTS.md

@@ -0,0 +1,7 @@
+# AGENTS.md — examples/
+
+User-facing usage examples.
+
+- Keep examples runnable and minimal.
+- Prefer clarity over micro-optimization.
+- Reflect current public APIs.

scripts/AGENTS.md

@@ -0,0 +1,7 @@
+# AGENTS.md — scripts/
+
+Developer and maintenance scripts.
+
+- Keep scripts automation-friendly and deterministic.
+- Avoid local-machine assumptions.
+- Document required env vars/inputs in-script.