# CLAUDE.md

## Project Purpose

This is a meta repo for dependency management. It defines shared dependencies and configurations consumed by the main application repo at `~/git/cca`. When making changes here, consider the downstream impact on that repo.

## Versioning

The patch version in `pyproject.toml` is **automatically bumped** by the `bump-version.yml` GitHub Action whenever `pyproject.toml` changes are pushed to `master`. Do not bump the version manually in PRs.

## Dependency pins

**Always pin runtime dependencies with a three-segment compatible-release specifier: `name~=X.Y.Z`.** Do not use `>=`, `<`, `==`, or a two-segment `~=X.Y`.

The weekly `upgrade-deps.yml` job (`.github/scripts/check_outdated_deps.py`) only recognizes `~=X.Y.Z` pins — its parser skips any dependency that isn't a `~=` compatible-release pin. So a dep written as `>=a,<b` (or `~=X.Y`) is **invisible to the auto-upgrader**: it never gets a bump PR and silently rots at whatever version was last installed.

That is exactly what happened to `tiktoken`: it was pinned `tiktoken>=0.6.0,<0.8.0`, the upgrader never saw it, and it froze at 0.7.0 — which has no cp313 wheel, so it forced a Rust source build that fails in the slim base images and broke the Python 3.13 image rollout. Keeping it a `~=X.Y.Z` pin means the job tracks it to the latest release, which always ships current cp3xx wheels.

Related knobs in `[tool.upgrade-deps]`: `groups` (coupled packages bumped in one PR, e.g. langchain) and `pin-major` (packages held within their current major until a deliberate migration, e.g. stripe).

## gstack

Use the `/browse` skill from gstack for all web browsing. Never use `mcp__claude-in-chrome__*` tools.

Available gstack skills:
- `/plan-ceo-review` — CEO-perspective plan review
- `/plan-eng-review` — Engineering plan review
- `/review` — Code review
- `/ship` — Ship workflow
- `/browse` — Headless browser for web browsing, QA testing, and site dogfooding
- `/qa` — QA testing
- `/setup-browser-cookies` — Set up browser cookies for authenticated browsing
- `/retro` — Retrospective
