StarPunk/CLAUDE.md

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/migration/ - Migration guides for upgrading between versions and configuration changes
• docs/projectplan/ - Project roadmaps, implementation plans, feature scope definitions
• docs/releases/ - Release-specific documentation, release notes, version information
• docs/reports/ - Implementation reports from developers (dated: YYYY-MM-DD-description.md)
• docs/reviews/ - Architectural reviews, design critiques, retrospectives
• docs/security/ - Security-related documentation, vulnerability analyses, best practices
• 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.