name	project-conventions
description	Project-specific conventions for boilerplate-python. Covers mise commands, Python coding rules (ruff, mypy, pytest), test structure, and commit workflow. Use when writing, reviewing, or modifying .py files, running builds/tests, or creating commits.
license	AGPL-3.0

Project Conventions — boilerplate-python

Commands: mise Only

All tasks go through mise run:

Task	Command
Setup	`mise run setup`
Install	`mise run install`
Build	`mise run build`
Test	`mise run test`
Coverage view (HTML)	`mise run test:view`
Format	`mise run fmt`
Format check	`mise run fmt:check`
Ruff lint	`mise run ruff:check`
Type check (mypy)	`mise run mypy`
Lint	`mise run lint`
Lint (GitHub Actions)	`mise run lint:gh`
Pre-commit (required)	`mise run pre-commit`
Pre-push	`mise run pre-push`
Docs	`mise run docs`
Docs (live)	`mise run docs:live`
Clean	`mise run clean`
Audit (deps)	`mise run audit`
Badges (init)	`mise run badges:init`
Claude Code (install)	`mise run claudecode:install`
CodeQL (install)	`mise run codeql:install`
CodeQL (analyze)	`mise run codeql`
Dev (start)	`mise run dev:up`
Dev (stop)	`mise run dev:down`
Dev (exec)	`mise run dev:exec`
Dev (status)	`mise run dev:status`
Traefik setup	`mise run traefik:setup`

Python Coding Rules

Type annotations: mandatory everywhere (mypy enforced via pyproject.toml)
Docstrings: Google-style
Comments: concise English only
Line length / quotes / lint ignores: defined in [tool.ruff] in pyproject.toml
Formatter: ruff format + dprint (TOML/YAML/JSON/Markdown)
Linter: ruff check + mypy

Test Structure

Tests in tests/ mirroring src/ directory structure
Framework: pytest
Coverage outputs go to target/ (configured in [tool.coverage] in pyproject.toml)

Commit Convention

Conventional Commits: <type>: <description> or <type>(<scope>): <description>

Allowed types: feat, update, fix, style, refactor, docs, perf, test, build, ci, chore, remove, revert

Workflow

Write tests (for new features / bug fixes)
Implement
Run mise run test — all tests must pass
Stage only the relevant files
Run mise run pre-commit (runs fmt:check, ruff:check, mypy, lint:gh)
If errors, fix → re-stage → re-run mise run pre-commit

Reference Files

Topic	File
Testing patterns	`references/testing-patterns.md`
Project structure	`references/module-and-project-structure.md`

Project Conventions — boilerplate-python

Commands: mise Only

All tasks go through mise run:

Task

Command

Setup

mise run setup

Install

mise run install

Build

mise run build

Test

mise run test

Coverage view (HTML)

mise run test:view

Format

mise run fmt

Format check

mise run fmt:check

Ruff lint

mise run ruff:check

Type check (mypy)

mise run mypy

Lint

mise run lint

Lint (GitHub Actions)

mise run lint:gh

Pre-commit (required)

mise run pre-commit

Pre-push

mise run pre-push

Docs

mise run docs

Docs (live)

mise run docs:live

Clean

mise run clean

Audit (deps)

mise run audit

Badges (init)

mise run badges:init

Claude Code (install)

mise run claudecode:install

CodeQL (install)

mise run codeql:install

CodeQL (analyze)

mise run codeql

Dev (start)

mise run dev:up

Dev (stop)

mise run dev:down

Dev (exec)

mise run dev:exec

Dev (status)

mise run dev:status

Traefik setup

mise run traefik:setup

Python Coding Rules

Type annotations: mandatory everywhere (mypy enforced via pyproject.toml)

Docstrings: Google-style

Comments: concise English only

Line length / quotes / lint ignores: defined in [tool.ruff] in pyproject.toml

Formatter: ruff format + dprint (TOML/YAML/JSON/Markdown)

Linter: ruff check + mypy

Test Structure

Tests in tests/ mirroring src/ directory structure

Framework: pytest

Coverage outputs go to target/ (configured in [tool.coverage] in pyproject.toml)

Commit Convention

Conventional Commits: <type>: <description> or <type>(<scope>): <description>

Allowed types: feat, update, fix, style, refactor, docs, perf, test, build, ci, chore, remove, revert

Workflow

Write tests (for new features / bug fixes)

Implement

Run mise run test — all tests must pass

Stage only the relevant files

Run mise run pre-commit (runs fmt:check, ruff:check, mypy, lint:gh)

If errors, fix → re-stage → re-run mise run pre-commit

Reference Files

Topic

File

Testing patterns

references/testing-patterns.md

Project structure

references/module-and-project-structure.md

project-conventions