# Agents.md

# Project Context — Python (General)

This repository is a general Python project. Ensure a virtual environment exists, create it with `uv` if missing, keep `requirements.txt` accurate, and then follow the user's instructions.

---

## Environment

- Virtual env: prefer `uv` to manage the venv and installs.
  - Create: `uv venv` (optionally `--python <version>`).
  - Use: activate `.venv` or run commands via `uv run <cmd>`.
- Dependencies:
  - If `requirements.txt` exists: `uv pip install -r requirements.txt`.
  - When packages are added/removed, update `requirements.txt` to stay accurate.
    - Default policy: freeze exact versions unless the user specifies otherwise (e.g., `uv pip freeze > requirements.txt`).
- Never assume the environment is active.
  - Before asking the user to run a command manually, verify whether the virtual environment is active.
  - If not active, instruct explicitly how to activate it:
    - Unix/macOS: `source .venv/bin/activate`
  - Prefer `uv run <command>` to avoid activation issues.

---

## Directory & File Safety Rules

When writing files or creating directories:

- If instructed to create or write into a folder with a specific name:
  - **First verify whether a directory with that name already exists.**
  - Do NOT create it blindly.
  - If it exists, reuse it unless the user explicitly requests overwriting.
  - If a file would be overwritten, clarify intent unless overwrite is explicitly requested.

- Avoid duplicating folder structures.
- Do not create parallel directories with similar names (e.g., `src` and `src_new`) unless explicitly requested.
- Maintain consistent project structure conventions.
- Respect existing naming conventions.

---

## Command Execution Policy

When suggesting commands to the user:

1. Ensure the command is compatible with the project’s tooling (`uv` preferred).
2. Avoid global installs.
3. Avoid OS-specific assumptions unless specified.
4. If the command modifies the environment (e.g., installing packages):
   - Make sure `requirements.txt` is updated accordingly.
5. If the user is inside a container or remote environment, do not assume local execution context.
6. Never assume shell state (activated venv, exported variables, current directory). Always be explicit.

---

## Operating Model

- Ask quick clarifying questions if versions, entry points, or expected behaviors are ambiguous.
- Prefer small, incremental changes with brief plans for multi-step work.
- Do not commit secrets.
- Avoid committing large build artifacts unless requested.
- Do not introduce new tooling (linters, formatters, frameworks) unless:
  - The user requests it.
  - It is strictly necessary to complete the task.
- Avoid unnecessary architectural refactors.
- Prioritize minimal, reversible changes.

---

## Code Modification Principles

- Follow existing code style and architecture.
- Avoid unnecessary refactors.
- Keep changes minimal and scoped.
- Preserve backward compatibility unless explicitly told otherwise.
- If introducing new files:
  - Place them in logically consistent locations.
  - Avoid breaking import paths.
- Do not remove or rename files unless explicitly instructed.

---

## Reproducibility

- The environment must remain reproducible from scratch using:
  - `uv venv`
  - `uv pip install -r requirements.txt`
- No hidden dependencies.
- No reliance on undeclared system packages unless clearly documented.
- Ensure all runtime dependencies are declared.

---

## Typical Tasks

Agents operating in this repository may:

- Implement features.
- Fix bugs.
- Run tests.
- Update documentation.
- Improve structure when explicitly requested.
- Keep the environment reproducible and synced with declared requirements.

---

## Safety & Determinism Rules

- Do not perform destructive actions (e.g., delete directories, drop databases) unless explicitly instructed.
- Do not overwrite configuration files without confirmation.
- Always prefer deterministic operations.
- If uncertain about intent, ask before acting.

---