# supaspin - rules for AI agents

Read and follow the global rules first. They are in Igor's global CLAUDE.md, which in turn pulls in
`~/.agents/AGENTS.md`:

@~/.claude/CLAUDE.md

The rules below are specific to this repository and add to the global ones.

## Versioning

The number is `MAJOR.MINOR.PATCH` (semantic versioning: `1.1.1` is major 1, minor 1, patch 1).

1. **Pick the number.** A bug fix or wording fix raises PATCH (1.1.0 -> 1.1.1). A new feature raises MINOR and resets
   PATCH (1.1.1 -> 1.2.0). MAJOR is Igor's decision only: never raise it, never write `!` after the commit type
   (`feat!:`) and never write a `BREAKING CHANGE:` line without asking him first (see the global rules).
2. **Write it in all three places, in the same commit as the change.** The file `VERSION`, the `VERSION = "x.y.z"`
   line near the top of `supaspin`, and the line `Version x.y.z` at the top of `README.md`. A unit test
   (`tests/test_supaspin.py`, class `Version`) fails if they differ. `supaspin --version` prints `supaspin x.y.z`.
3. **One plan = one branch = one commit = one pull request.** The version bump is part of that one commit.
4. **Tag every release.** After the pull request is merged, create the git tag `vX.Y.Z` (for example `v1.1.1`) on
   the commit on `main` that contains that number in `VERSION`. The tag name must equal `VERSION` with a `v` in
   front. A version without a tag is not released. Never move or delete a tag that was already published; if a
   release is wrong, ship a new PATCH instead. With the Gitea API: `POST /api/v1/repos/public/supaspin/tags` with
   `tag_name`, `target` (the commit) and `message`.

   The owner in an API address must be `public`. The repository used to sit under the user `igor` and Gitea still
   forwards the old address for anything a browser or git does, but it answers an API call to
   `/api/v1/repos/igor/supaspin/...` with a redirect that curl does not follow for a POST: the command returns an
   empty body and no error, which looks exactly like a rejected token. Opening or merging a pull request needs the
   same `public` owner.
5. **Check the result.** Reinstall from the merged `main` (`sudo bash install.sh`), then run `supaspin --version` and
   compare it with `VERSION` and the tag.
6. If you find a version in `VERSION` that has no tag, or a tag that does not match `VERSION`, tell Igor before doing
   anything else.