Files
StarPunk/CLAUDE.md
T
PhilandClaude Opus 5.5 75946be7b2 maint: Dependency upgrades and High backlog items (v2.11.0)
- All dependencies to current releases (97 known vulnerabilities -> 0),
  Python 3.14, uv pinned, requirements-test.txt, lxml/dateutil pinned
- CSRF tokens on admin forms, logout and IndieAuth consent
- IndieAuth client and crosspost link-card fetches via safe_get
- FLASK_DEBUG/FLASK_ENV default off/production; image sets them
- Foreign keys enforced on pooled connections; migration 018 removes orphans
- Rate limits shared across processes (rate_limits, migration 019)
- datetime.utcnow() and sqlite3 default adapters replaced
- compose.yaml fixed; duplicate dev_auth.py and test.ini removed

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 13:09:52 -07:00

3.7 KiB

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 --app app.py run --debug
  • There is no pyproject.toml: create the environment with uv venv --python 3.14 && uv pip install -r requirements-dev.txt
  • Tests need SESSION_SECRET set: SESSION_SECRET=test uv run pytest. The full suite takes about 6 minutes, 5 of them in tests/test_migration_race_condition.py; add --ignore=tests/test_migration_race_condition.py while iterating, but run everything before a release
  • Local login without OIDC: DEV_MODE=true and DEV_ADMIN_ME in .env, then /dev/login
  • Setup details: docs/standards/development-setup.md

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 (both __version__ and __version_info__)
  5. Follow git protocol

    • Adhere to git branching strategy in docs/standards/git-branching-strategy.md
    • Create feature branches for non-trivial changes, in their own git worktree (<prefix>/vX.Y.Z-description, prefixes feat/, fix/, ci/, docs/)
    • Write clear commit messages (feat: ... (vX.Y.Z))

Release Process

Follow "Release process" in docs/standards/git-branching-strategy.md. In short: work in a worktree on a feat//fix/ branch → bump __version__ and __version_info__ → CHANGELOG.md entry → design note in docs/design/vX.Y.Z/ (or ADR amendment) → full test suite → commit → git merge --no-ff into main ("Merge branch '' for vX.Y.Z release") → annotated tag vX.Y.Z → push main and the tag. CI (.gitea/workflows/build-container.yml) runs the tests and publishes the image; production is then updated from the separate Ansible deployment repository. Back up the database before deploying a release with a migration.

Merging to main, tagging, pushing and deploying happen only when the project owner asks for a release.

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.