# 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 Protocol (All Agents)

**IMPORTANT**: All agents must review `docs/DOCUMENTATION.md` before starting work. This file is the authoritative source for documentation organization and supersedes any other instructions.

## Agent-Architect Protocol

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

1. Review `docs/DOCUMENTATION.md` for documentation organization standards

2. Review documentation in docs/ before working on the task it is given
   - docs/architecture, docs/decisions, docs/standards are of particular interest

3. Search for authoritative documentation for any web standard it is implementing on https://www.w3.org/

4. If it is reviewing a developers implementation report and it accepts the completed work it should go back and update the project plan to reflect the completed work

## Agent-Developer Protocol

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

1. Review `docs/DOCUMENTATION.md` for documentation organization standards

2. **Document work in design folder**
   - Create implementation reports in `docs/design/{version}/`
   - Include date in filename: `YYYY-MM-DD-description.md`
   - All developer interaction (questions, responses, reports, reviews) goes in design/{version}/

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

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

5. **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

## Documentation

See `docs/DOCUMENTATION.md` for the authoritative documentation structure, navigation guidance, and key references.

## Project Philosophy

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

Keep implementations minimal, standards-compliant, and maintainable.