This file provides working guidelines for AI coding agents (e.g., GitHub Copilot, Claude Code, Cursor, etc.) contributing to this repository.

• All changes must be submitted to the main branch via a pull request. Never push commits directly to main.

Do this on every change, whatever you came here to do. It is not a release-time task — the README's pre-commit snippets are the first thing a new user copies, and a stale pin is invisible: the snippet keeps working, it just installs an older release than the README describes.

1. Find the latest released version.

   curl -s https://pypi.org/pypi/commit-check/json | python -c "import json,sys; print(json.load(sys.stdin)['info']['version'])"

   The releases page answers the same question, provided you read only published releases. A draft is not one, and you cannot tell by looking for a tag: a draft can be saved against a tag that already exists, and publishing to PyPI is a separate step from publishing the GitHub release. Read the published release, or ask PyPI as above.

   Both have to be true before a version can be pinned: the tag must exist, because that is what pre-commit resolves rev: against, and PyPI must have the version, because that is what installs.

2. Check every pin in the README.

   grep -n "rev: v" README.md

   Each one must name that version. Update any that do not, in the same pull request — do not open a follow-up issue for it.

3. Say so in the pull request description when you moved them, so the bump is not a silent diff in an unrelated change.

The one exception is a pull request that prepares an unpublished release: there the pins are written ahead of the tag, on purpose, and the pull request merges before the release is published. pyproject.toml sets readme = "README.md", so this file is the long description PyPI shows, and the publish workflow builds from whatever main holds at that moment. A README bumped after the release ships the old pin to PyPI, where it cannot be corrected without another release. Check it afterwards: rev: on the release's PyPI page must name that release.

.pre-commit-config.yaml is a different case and is not covered by this rule. That pin is this repository running its own hooks, and pre-commit resolves it against real tags when CI runs — so pointing it at a version that is not published yet breaks the build. Bump it only after the release exists.

• Branch names. This repository does not enforce branch naming (cchk.toml sets conventional_branch = false); CI only checks that the branch is rebased onto main (require_rebase_target = "main"). Prefer the Conventional Branch form <type>/<kebab-case-description> anyway, using any type in the tool's defaults (e.g. feat/, fix/, chore/, docs/, claude/). Example: chore/add-agent-guidelines.
• Follow the Conventional Commits spec for commit messages: <type>: <description> (e.g., feat: ..., fix: ..., chore: ..., docs: ...).
• No force push. Never use git push --force or git push --force-with-lease.
• Additive commits only. When addressing review feedback, add new commits on top. Never rebase, squash commits (e.g., do not use git rebase -i to squash history after the PR is open).

• Stage only the files you changed: git add <file>....
• Never use git add . / git add -A / git add --all, and never stage unrelated or generated files.