docs: add hierarchical AGENTS and Copilot instruction scaffolding

.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,45 @@
+# GitHub Copilot Instructions — dpnp
+
+## Source of truth
+This file is canonical for Copilot behavior in this repository.
+
+For project context and directory routing, read root `AGENTS.md` first.
+
+`AGENTS.md` files provide directory scope/guardrails and should not duplicate Copilot policy text.
+
+## Precedence hierarchy (conflict resolution)
+When guidance conflicts across files, apply in this order:
+1. `.github/copilot-instructions.md` (this file)
+2. Applicable `.github/instructions/*.instructions.md` files
+3. Nearest local `AGENTS.md` for edited path
+4. Root `AGENTS.md`
+
+## Mandatory flow
+1. Read root `AGENTS.md`.
+2. For each edited file, read its nearest local `AGENTS.md`.
+3. If multiple directories changed, apply each scope's local AGENTS to corresponding files.
+4. Most specific AGENTS wins for each file.
+
+## Contribution expectations
+- Keep diffs minimal and scoped to the task.
+- Preserve NumPy-compatible API behavior by default.
+- For behavior/API changes: update tests, and docs/examples when user-visible (API signature/behavior, errors, examples output).
+- For bug fixes: add regression test coverage.
+
+## Test and validation requirements
+- Add unit/integration tests for changed code paths.
+- For bug fixes: include regression tests.
+- Keep tests deterministic and scoped to changed behavior.
+
+## Authoring rules
+- Use source-of-truth files for mutable details.
+- Do not invent or hardcode versions, flags, or matrix values.
+- Prefer single-purpose commits; avoid opportunistic refactors.
+
+## Source-of-truth files
+All paths relative to project root:
+- 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,11 @@
+---
+applyTo: "{CMakeLists.txt,pyproject.toml,setup.py,setup.cfg,**/CMakeLists.txt}"
+---
+
+# Build Instructions for GitHub Copilot
+
+All paths below are relative to project root.
+
+- 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,20 @@
+---
+applyTo: "{dpnp/tests/**,tests_external/**}"
+---
+
+# Testing Instructions for GitHub Copilot
+
+## Test coverage requirements
+- Add unit/integration tests for all changed code paths.
+- For bug fixes: include regression tests that cover the fixed scenario.
+
+## Test quality
+- Keep tests deterministic and scoped to changed behavior.
+- Prefer smallest test surface proving correctness.
+
+## Validation workflow
+Ensure tests pass locally before PR submission:
+```bash
+pytest dpnp/tests/        # core tests
+pytest tests_external/    # integration tests
+```

AGENTS.md

@@ -0,0 +1,29 @@
+# AGENTS.md
+
+Entry point for agent context in this repo.
+
+## What this repository is
+`dpnp` is the Data Parallel Extension for NumPy: a NumPy-compatible Python API with accelerated execution backends and cross-platform packaging/CI.
+
+For detailed documentation, build instructions, and contribution guidelines, see:
+- `README.md` (project overview and quickstart)
+- `CONTRIBUTING.md` (if exists, or refer to project docs)
+
+## How to work in this repo
+- Keep changes small and single-purpose (bug fix, perf, docs, or infra).
+- Preserve NumPy-compatible API behavior by default; call out intentional behavior changes in PR text.
+- Pair user-visible changes with tests and docs/examples updates.
+- Avoid duplicating mutable details (versions/flags/matrix) in instruction docs.
+
+For Copilot behavior policy (flow, source-of-truth, edit hygiene), see:
+- `.github/copilot-instructions.md` (canonical for Copilot behavior)
+
+## Directory map
+Below directories have local `AGENTS.md` for deeper context:
+- `.github/AGENTS.md` — CI/workflow/automation context
+- `dpnp/AGENTS.md` — core NumPy-compatible implementation guardrails
+- `doc/AGENTS.md` — documentation updates and consistency
+- `examples/AGENTS.md` — runnable user-facing examples
+- `benchmarks/AGENTS.md` — reproducible performance evaluation
+- `scripts/AGENTS.md` — maintenance/developer scripts
+- `tests_external/AGENTS.md` — external/integration validation scope

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 NumPy-compatible package implementation and Python/Cython-facing behavior.
+
+- Preserve NumPy API 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.

tests_external/AGENTS.md

@@ -0,0 +1,7 @@
+# AGENTS.md — tests_external/
+
+External/integration validation surface.
+
+- Keep tests focused on external/integration behavior.
+- Gate feature/platform-specific assertions where needed.
+- For regression policy, follow `.github/instructions/testing.instructions.md`.