file_utils: Instructions file for Codex

AGENTS.md — Conventions for AI agents working in this repo

This file documents the working conventions any AI agent (or human) must follow when making changes in the file_utils MCP project. Read it before starting work. See SPEC.md for the design and TODO.md for the phased implementation plan.

---

1. Always use uv

This project is managed with uv. Do not call python, pip, or pytest directly — always go through uv so the correct environment and dependencies (from pyproject.toml) are used.

uv installs to C:\Users\<you>\.local\bin (added to PATH by the installer). A newly opened terminal will have uv / uvx on PATH; an already-open terminal may need to be reopened first. If uv is not yet installed, install it with the official Astral installer:

powershell -ExecutionPolicy ByPass -Command "irm https://astral.sh/uv/install.ps1 | iex"

Common commands:

Task	Command
Run the server	uv run server.py
Run the test suite	uv run --extra dev pytest
Run tests quietly	uv run --extra dev pytest -q
Add a dependency	uv add <package>
Sync the environment	uv sync --extra dev

Note: system commands are issued in cmd, not PowerShell (except the one-off uv install command above, which uses PowerShell explicitly).

---

2. Check in changes after each completed task

After each task/phase from TODO.md is complete and verified (tests green via uv run --extra dev pytest), commit the changes to version control before moving on. Keep commits scoped to one logical task so history maps cleanly onto the phased plan.

Typical flow once a task is done:

git add -A
git commit -m "Phase N: <short description of what was completed>"

Guidelines:

• Commit only after the relevant tests pass.
• Use a clear, present-tense message referencing the phase/task.
• Update the corresponding checkbox in TODO.md in the same commit.
• Do not bundle unrelated changes into a single commit.