assistance-engine/Agents.md

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.

---