Merge pull request #388 from xylar/add-ai-instructions

add AI agent instructions

Author: xylar

.github/copilot-instructions.md

@@ -0,0 +1,10 @@
+# Polaris Copilot Instructions
+
+Follow the repository's automated style configuration in
+`pyproject.toml` and `.pre-commit-config.yaml`.
+
+- Keep changes consistent with existing Polaris patterns.
+- For Python, follow the path-specific instructions in
+  `.github/instructions/python.instructions.md`.
+- Prefer changes that pass the configured pre-commit hooks without
+  adding ignores or suppressions.

.github/instructions/python.instructions.md

@@ -0,0 +1,15 @@
+---
+applyTo: "**/*.py"
+---
+
+# Python Instructions
+
+- Keep lines at 79 characters or fewer whenever possible.
+- Adhere to `ruff format` formatting.
+- Keep imports at module scope whenever possible. Avoid local imports
+  unless they are needed for circular-import avoidance, lazy loading, or
+  optional dependencies.
+- Avoid nested functions whenever possible.
+- Prefer public functions before private helper functions whenever
+  practical.
+- Prefer private module-level helper functions over nested helpers.

AGENTS.md

@@ -0,0 +1,33 @@
+# Polaris Agent Instructions
+
+These instructions apply to the whole repository unless a deeper
+`AGENTS.md` overrides them.
+
+## Source of truth
+
+- Follow the repo's automated style and lint configuration in
+  `pyproject.toml` and `.pre-commit-config.yaml`.
+- If an instruction here conflicts with automated tooling, follow the
+  automated tooling.
+
+## Python style
+
+- Keep Python lines at 79 characters or fewer whenever possible.
+- Use `ruff format` style. Do not preserve manual formatting that Ruff
+  would rewrite.
+- Keep imports at module scope whenever possible. Avoid local imports
+  unless they are needed to prevent circular imports, defer expensive
+  dependencies, or avoid optional dependency failures.
+- Avoid nested functions whenever possible. Prefer private module-level
+  helpers instead.
+- Put public functions before private helper functions whenever
+  practical.
+- Name private helper functions with a leading underscore when that fits
+  existing repo conventions.
+
+
+## Validation
+
+- Run relevant pre-commit hooks on changed files before finishing when
+  practical.
+- Prefer fixing lint and formatting issues rather than suppressing them.