Files
StarPunk/CLAUDE.md
T
PhilandClaude Opus 5.5 0716984958 docs: Bring all documentation up to date for v2.10.1
- architecture/: overview, technology stack, auth (OIDC + built-in
  IndieAuth), syndication (POSSE) rewritten; new database.md,
  deployment.md and indieweb-protocols.md; legacy stack marked historical
- decisions/: reconstructed ADR-060 and ADR-063; 31 status corrections
  (superseded auth ADRs, proposed -> accepted); INDEX rebuilt
- design/: reconstructed the v1.6.0 documents the webmention code cites;
  reports for 18 v2 releases without a design folder; INDEX rebuilt
- projectplan/: BACKLOG rewritten (shipped items removed, open issues from
  the reviews added); RELEASE.md for v2.0.0-v2.10.1; INDEX
- standards/: development setup (uv, tests, DEV_MODE), testing (CI test
  stage), git and release flow, versioning, coding standards, cookies
- README, CLAUDE.md, .env.example (every setting the code reads, with
  defaults) brought up to date
- 137 broken links repaired (old absolute paths, moved files); stale ADR
  references in code comments corrected (comments only)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 12:40:19 -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.11 && 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.