# Claude Agent Instructions

This file contains operational instructions for Claude agents working on this project.

## Python Environment

- We use **uv** for Python virtual environment management
- All Python commands must be run with `uv run` prefix
- Example: `uv run pytest`, `uv run flask run`

## Agent-Developer Protocol

When invoking the agent-developer, always remind it to:

1. **Document work in reports**
   - Create implementation reports in `docs/reports/`
   - Include date in filename: `YYYY-MM-DD-description.md`

2. **Update the changelog**
   - Add entries to `CHANGELOG.md` for user-facing changes
   - Follow existing format

3. **Version number management**
   - Increment version numbers according to `docs/standards/versioning-strategy.md`
   - Update version in `starpunk/__init__.py`

4. **Follow git protocol**
   - Adhere to git branching strategy in `docs/standards/git-branching-strategy.md`
   - Create feature branches for non-trivial changes
   - Write clear commit messages

## Key Documentation References

- **Architecture**: See `docs/architecture/overview.md`
- **Implementation Plan**: See `docs/projectplan/v1/implementation-plan.md`
- **Feature Scope**: See `docs/projectplan/v1/feature-scope.md`
- **Coding Standards**: See `docs/standards/python-coding-standards.md`
- **Testing**: See `docs/standards/testing-checklist.md`

## Project Philosophy

"Every line of code must justify its existence. When in doubt, leave it out."

Keep implementations minimal, standards-compliant, and maintainable.