Files
StarPunk/CLAUDE.md
T
PhilandClaude Opus 5.5 ceef048003 docs: documentation review for v2.14.0
Architecture, README, standards, CLAUDE.md, settings reference, indexes,
backlog, release plans and CHANGELOG checked against the code at v2.14.0:
backfeed, notifications, counts line and web actions documented; test
policy (changed area locally, full suite in CI); stale versions, statuses
and links fixed; legacy and superseded docs moved.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-10 14:51:57 -07:00

3.8 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. Locally, run only the tests for the area you changed (SESSION_SECRET=test uv run pytest tests/test_<area>.py); CI runs the full suite (about 6 minutes) on every vX.Y.Z tag, so don't run the whole suite yourself unless asked
  • 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/, chore/, 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//chore/ branch → bump __version__ and __version_info__ → CHANGELOG.md entry → design note in docs/design/vX.Y.Z/ (or ADR amendment) → tests for the changed area → 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 full test suite 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.