commitizen-aware

name	commitizen-aware
description	This skill should be used when working in the `commitizen-tools/commitizen` repository as a contributor (not as a downstream `[tool.commitizen]` user). It surfaces the conventions from the repo's own AGENTS.md — uv + poe tasks, conventional commits enforced by commitizen itself, ruff/mypy linting, pytest, and PR guidelines — so any task (review, quick-fix, refactor) in commitizen follows them.

Commitizen-Aware

Loaded by: repo-detect hook (SessionStart) when commitizen-tools/commitizen is detected in git remote or file structure. Applies to: Any skill execution within a commitizen-tools/commitizen contributor checkout — review, quick-fix, refactoring, or otherwise.

When to apply

This is a knowledge layer, not a review checklist. It is loaded automatically by the repo_detect hook at session start when a commitizen repo is detected. It mirrors and supplements the repo's own AGENTS.md, condensed for agent context.

It can also be triggered manually via a memory entry with triggers: [commitizen-aware] (see Memory-triggered skill loading).

Once loaded, treat every convention as background — do not re-read each task.

Read AGENTS.md first

The single source of truth for contributor conventions lives in the repo itself.

1. First action: read AGENTS.md (83 lines — short enough to read in full).
2. Conflict resolution: if anything in this skill contradicts AGENTS.md, the repo file wins. This skill is an onramp and supplement, not a competing authority.
3. PR-specific guidance: when working on a pull request, also read docs/contributing/pull_request.md and .github/pull_request_template.md (both explicitly named in AGENTS.md line 25).

Contributor conventions

1. Defer to AGENTS.md

This skill is an onramp — a condensed version of AGENTS.md formatted for agent startup context. It is not a replacement. Any time a convention here conflicts with what AGENTS.md says, follow AGENTS.md. See the Read AGENTS.md first section above.

2. Environment — uv + prek + poe

Bootstrap the dev environment:

uv sync --frozen --group base --group test --group linters
uv run poe setup-pre-commit   # installs git hooks (uses prek, a pre-commit runner)

Do not call pre-commit directly — commitizen uses prek as its pre-commit runner (AGENTS.md line 51). prek is compatible with the same hooks.

Available poe tasks (AGENTS.md lines 40–44):

• uv run poe format — runs ruff check --fix then ruff format
• uv run poe lint — runs ruff check then mypy
• uv run poe test — runs pytest -n auto
• uv run poe ci — commit check + pre-commit hooks via prek + test with coverage
• uv run poe all — format + lint + check-commit + coverage

Before pushing: always run at least uv run ruff check --fix . && uv run ruff format .. CI will fail if the formatter modifies any files (AGENTS.md line 46).

3. Cross-platform

Tests run on Linux, macOS, and Windows (Python 3.10–3.14 matrix). Avoid POSIX-only assumptions in any new code:

• Paths: use pathlib — never string-concatenate with "foo/bar".
• Subprocesses: be careful with shell-quoting differences across platforms.
• Line endings: do not assume \n only.

This is one of the most distinctive aspects of commitizen compared to many Python projects — treat cross-platform correctness as a first-class constraint, not an afterthought.

4. Common CI failure patterns

From AGENTS.md lines 54–59:

• "Format Python code...Failed": run uv run poe format and commit the result.
• mypy [arg-type] on TypedDict: dynamically-constructed dicts (e.g., from pytest.mark.parametrize) passed to TypedDict-typed params need # type: ignore[arg-type].
• "pathspec 'vX.Y.Z' did not match": .pre-commit-config.yaml pins a tag of this repo. Rebase onto master to pick up the tag.
• VersionProtocol + issubclass: this Protocol has non-method members (properties), so issubclass() raises TypeError. Use hasattr checks for runtime validation.

5. Commits, PRs, conventions

• Commit messages must follow Conventional Commits — enforced by commitizen itself (AGENTS.md line 24).
• Pull requests must follow docs/contributing/pull_request.md and .github/pull_request_template.md (AGENTS.md line 25).
• Preserve public behavior: no breaking changes to CLI flags, exit codes, or public APIs unless explicitly requested (AGENTS.md line 22).
• Behavior changes require tests or doc updates (AGENTS.md line 23).

6. Coding rules

From AGENTS.md lines 75–78:

• Types: preserve or improve existing type hints.
• Errors: prefer error types from commitizen/exceptions.py; keep messages clear for CLI users.
• Output: use commitizen/out.py; do not add noisy logging.

7. When unsure

• Read tests and documentation first to understand expected behavior (AGENTS.md line 82).
• When behavior is ambiguous, assume backward compatibility with current tests and docs is required (AGENTS.md line 83).

8. What to read before changing

From AGENTS.md lines 62–72:

Changing...	Read first
CLI flags/arguments	commitizen/cli.py, docs/commands/<cmd>.md, tests/test_cli/
Bump logic	commitizen/bump.py, commitizen/commands/bump.py, docs/commands/bump.md
Changelog generation	commitizen/changelog.py, commitizen/changelog_formats/, docs/commands/changelog.md
Version schemes	commitizen/version_schemes.py, tests/test_version_schemes.py
Version providers	commitizen/providers/, tests/test_providers.py, docs/config/version_provider.md
Config resolution	commitizen/config/, tests/test_conf.py, docs/config/
Tag handling	commitizen/tags.py, tests/test_tags.py
Pre-commit / CI	.pre-commit-config.yaml, .github/workflows/, pyproject.toml (poe tasks)

Composing with other skills

This skill pairs with strict-review.

Review scenario — run strict-review's 9-item base checklist as usual, then apply commitizen-aware conventions as project-specific supplements:

• Convention 5 (commits / PRs) reinforces base item 8 (commit hygiene).
• Convention 6 (coding rules) reinforces base items 5–6 (style / correctness).
• Convention 4 (CI failure patterns) translates findings into evidence-based fix suggestions.

Quick-fix / refactor scenario — use conventions 2, 3, 5, and 6 as background knowledge. Flag violations you notice, but do not run the full strict-review checklist unless the task calls for it.