# 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-Architect Protocol

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

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

2. Give it the map of the documentation folder as described in the "Understanding the docs/ Structure" section below

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

## Documentation Navigation

### Understanding the docs/ Structure

The `docs/` folder is organized by document type and purpose:

- **`docs/architecture/`** - System design overviews, component diagrams, architectural patterns
- **`docs/decisions/`** - Architecture Decision Records (ADRs), numbered sequentially (ADR-001, ADR-002, etc.)
- **`docs/deployment/`** - Deployment guides, infrastructure setup, operations documentation
- **`docs/design/`** - Detailed design documents, feature specifications, phase plans
- **`docs/examples/`** - Example implementations, code samples, usage patterns
- **`docs/projectplan/`** - Project roadmaps, implementation plans, feature scope definitions
- **`docs/reports/`** - Implementation reports from developers (dated: YYYY-MM-DD-description.md)
- **`docs/reviews/`** - Architectural reviews, design critiques, retrospectives
- **`docs/standards/`** - Coding standards, conventions, processes, workflows

### Where to Find Documentation

- **Before implementing a feature**: Check `docs/decisions/` for relevant ADRs and `docs/design/` for specifications
- **Understanding system architecture**: Start with `docs/architecture/overview.md`
- **Coding guidelines**: See `docs/standards/` for language-specific standards and best practices
- **Past implementation context**: Review `docs/reports/` for similar work (sorted by date)
- **Project roadmap and scope**: Refer to `docs/projectplan/`

### Where to Create New Documentation

**Create an ADR (`docs/decisions/`)** when:
- Making architectural decisions that affect system design
- Choosing between competing technical approaches
- Establishing patterns that others should follow
- Format: `ADR-NNN-brief-title.md` (find next number sequentially)

**Create a design doc (`docs/design/`)** when:
- Planning a complex feature implementation
- Detailing technical specifications
- Documenting multi-phase development plans

**Create an implementation report (`docs/reports/`)** when:
- Completing significant development work
- Documenting implementation details for architect review
- Format: `YYYY-MM-DD-brief-description.md`

**Update standards (`docs/standards/`)** when:
- Establishing new coding conventions
- Documenting processes or workflows
- Creating checklists or guidelines

### 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.