Skip to content

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.