docs: add AI agent instruction rules for Copilot, Antigravity, and VS Code

---

name: code_quality

description: Mandatory PEP 8, Ruff, Black, and testing rules for PyAETNA development

---

# PyAETNA Code Quality Rules

When developing, refactoring, or generating code for PyAETNA in Antigravity:

1. **Python Environment**:

   Always execute commands using `/dati/pyenvs/pyaetnaEnv/bin/python`.

2. **Formatting & Quality Compliance**:

   - Strictly follow the `pyproject.toml` configuration for `ruff` and `black`.

   - Never introduce code that violates `ruff check PyAETNA/ tests/`.

   - Ensure all unit tests pass with `/dati/pyenvs/pyaetnaEnv/bin/pytest tests/`.

3. **Pre-Commit Verification**:

   Verify that `git commit` passes the installed `.pre-commit-config.yaml` pre-commit hooks.

# PyAETNA AI Agent & Coding Guidelines

All AI agents (GitHub Copilot, VS Code Copilot, Antigravity, Claude Code, Cursor, etc.) working on the PyAETNA codebase **MUST** strictly adhere to the following environment and code quality requirements:

## 1. Python Environment

- Always use the dedicated virtual environment:

  `/dati/pyenvs/pyaetnaEnv/bin/python`

- Executable paths for tooling:

  - Python: `/dati/pyenvs/pyaetnaEnv/bin/python`

  - Ruff: `/dati/pyenvs/pyaetnaEnv/bin/ruff`

  - Black: `/dati/pyenvs/pyaetnaEnv/bin/black`

  - Pytest: `/dati/pyenvs/pyaetnaEnv/bin/pytest`

## 2. Code Quality & Formatting Enforcement

- **PEP 8 / Formatting**: All Python code edits must pass `ruff check` and `black --check`.

- **Ruff Linter**: All lint warnings configured in `pyproject.toml` must be resolved before completing a task.

- **Verification Command**: Before submitting any code changes or completing a task, always run:

  ```bash

  /dati/pyenvs/pyaetnaEnv/bin/ruff check PyAETNA/ tests/

  /dati/pyenvs/pyaetnaEnv/bin/pytest tests/

  ```

## 3. Code Standards & Rules

- Do NOT use single-character ambiguous variable names (e.g. `l`, `O`, `I`).

- Use flattened control structures (`if a and b:`) rather than nested `if` blocks.

- Prefix unused loop control variables with an underscore (e.g. `_inst_id`).

- Ensure all public functions and re-exported APIs in `__init__.py` or module roots are properly declared in `__all__`.

# PyAETNA Development & Quality Rules for AI Assistants

- **Python Environment**: `/dati/pyenvs/pyaetnaEnv/bin/python`

- **Linting & Formatting**: Follow `pyproject.toml` (`ruff check` and `black --check`).

- **Pre-commit**: Pre-commit hook is active in `.git/hooks/pre-commit`.

- **Validation**: Run `/dati/pyenvs/pyaetnaEnv/bin/ruff check PyAETNA/ tests/` and `/dati/pyenvs/pyaetnaEnv/bin/pytest tests/` before completing tasks.