- 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>
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 runprefix - Example:
uv run pytest,uv run flask --app app.py run --debug - There is no
pyproject.toml: create the environment withuv venv --python 3.14 && uv pip install -r requirements-dev.txt - Tests need
SESSION_SECRETset:SESSION_SECRET=test uv run pytest. The full suite takes about 6 minutes, 5 of them intests/test_migration_race_condition.py; add--ignore=tests/test_migration_race_condition.pywhile iterating, but run everything before a release - Local login without OIDC:
DEV_MODE=trueandDEV_ADMIN_MEin.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:
-
Review
docs/DOCUMENTATION.mdfor documentation organization standards -
Review documentation in docs/ before working on the task it is given
- docs/architecture, docs/decisions, docs/standards are of particular interest
-
Search for authoritative documentation for any web standard it is implementing on https://www.w3.org/
-
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:
-
Review
docs/DOCUMENTATION.mdfor documentation organization standards -
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}/
- Create implementation reports in
-
Update the changelog
- Add entries to
CHANGELOG.mdfor user-facing changes - Follow existing format
- Add entries to
-
Version number management
- Increment version numbers according to
docs/standards/versioning-strategy.md - Update version in
starpunk/__init__.py(both__version__and__version_info__)
- Increment version numbers according to
-
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, prefixesfeat/,fix/,ci/,docs/) - Write clear commit messages (
feat: ... (vX.Y.Z))
- Adhere to git branching strategy in
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.