Add python prek hooks for git pre-commit

.github/workflows/ci.yml

@@ -9,30 +9,43 @@ on:
 jobs:
   test:
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
       - name: Install uv
         uses: astral-sh/setup-uv@v4
         with:
           version: "latest"
 
-      - name: Set up Python
+      - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v5
         with:
-          python-version: "3.12"
+          python-version: ${{ matrix.python-version }}
 
       - name: Install dependencies
         run: uv sync --dev
 
       - name: Run tests with coverage
         run: uv run pytest --cov=python_package_template --cov-report=term-missing --cov-report=xml
 
-      - name: Lint with ruff
-        run: uv run ruff check .
-
-      - name: Type check with mypy
-        run: uv run mypy .
+      - name: Run pre-commit hooks
+        run: uv run prek run --all-files
 
       - name: Security audit with pip-audit
         run: uv run pip-audit
+
+      - name: Check changelog updated
+        if: github.event_name == 'pull_request'
+        run: |
+          if git diff origin/main...HEAD --name-only | grep -q CHANGELOG.md; then
+            echo "CHANGELOG.md has been updated."
+          else
+            echo "::error::CHANGELOG.md has not been updated for this branch."
+            echo "Please add your changes to CHANGELOG.md under the section '[version] - date - PR' before merging."
+            exit 1
+          fi

.gitignore

@@ -4,11 +4,15 @@ REVIEW.md
 *.lock
 !uv.lock
 
+# Exclude all dot files/directories by default, then whitelist the ones we need.
+# There are too many possible .* files depending on which LLM agents and tools
+# you happen to use, so a whitelist approach is simpler and safer.
 /.*
 !.gitignore
 !.github
 !.env.example
-
+!.pre-commit-config.yaml
+!.pymarkdown.json
 
 # AI Agent Outputs & State Files
 agent_artifacts/

.pre-commit-config.yaml

@@ -0,0 +1,50 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-yaml
+        name: Check YAML files
+      - id: check-toml
+        name: Check TOML files
+      - id: end-of-file-fixer
+        name: Fix end of files
+      - id: check-added-large-files
+        name: Check for large files
+        args: ['--maxkb=1000']
+      - id: trailing-whitespace
+        name: Trim trailing whitespace
+
+  - repo: local
+    hooks:
+      - id: ruff
+        name: Lint with ruff
+        entry: uv run ruff check . --fix
+        language: system
+        pass_filenames: false
+        always_run: true
+
+      - id: ruff-format
+        name: Format with ruff
+        entry: uv run ruff format .
+        language: system
+        pass_filenames: false
+        always_run: true
+
+      - id: mypy
+        name: Type check with mypy
+        entry: uv run mypy .
+        language: system
+        pass_filenames: false
+        always_run: true
+
+      - id: pymarkdownlnt
+        name: Lint Markdown with pymarkdownlnt
+        entry: uv run pymarkdown -c .pymarkdown.json scan
+        language: system
+        types: [markdown]
+
+      - id: shellcheck
+        name: Lint shell scripts with shellcheck
+        entry: uv run shellcheck
+        language: system
+        files: \.(sh|bash)$

.pymarkdown.json

@@ -0,0 +1,7 @@
+{
+  "plugins": {
+    "md024": {
+      "enabled": false
+    }
+  }
+}

AGENTS.md

@@ -1,63 +1,96 @@
 # Agent Instructions: python-package-template
 
 ## Quick Start
+
 1. **Setup:** Run `uv sync --dev` before major work sessions
 2. **Activate:** Ensure `.venv` is active; run `uv venv` if missing
 3. **Code:** Use `python3` or `uv run python`; always add type hints and tests
 
 ## Tech Stack
-| Component | Tool |
-|-----------|------|
-| Environment & Dependencies | uv |
-| Data Validation | Pydantic |
-| CLI Framework | Typer |
-| Testing | pytest |
-| Linting & Formatting | ruff |
-| Type Checking | mypy |
-| Security Audit | pip-audit |
+
+| Component            | Tool      |
+| -------------------- | --------- |
+| Environment & Deps   | uv        |
+| Data Validation      | Pydantic  |
+| CLI Framework        | Typer     |
+| Testing              | pytest    |
+| Linting & Formatting | ruff      |
+| Type Checking        | mypy      |
+| Security Audit       | pip-audit |
+| Markdown Lint        | pymarkdownlnt |
+| Git Hooks            | prek      |
 
 ## Project Structure
-```
+
+```text
 python_package_template/
-  ├── config.py          (Pydantic models)
-  ├── hello.py           (Business logic)
-  └── cli.py             (Typer CLI)
-tests/                   (Pytest suite)
-pyproject.toml           (Dependencies & tool config)
+  config.py          (Pydantic models)
+  hello.py           (Business logic)
+  cli.py             (Typer CLI)
+tests/               (Pytest suite)
+pyproject.toml       (Dependencies & tool config)
 ```
 
 ## Essential Directives
 
 ### Code Standards
-- **Type Hints:** Required on ALL function signatures and class members. Enforce strictly with mypy. Avoid using `# type: ignore` comments to suppress mypy errors; fix the underlying type issues instead.
+
+- **Type Hints:** Required on ALL function signatures
+  and class members. Enforce strictly with mypy.
+  Avoid using `# type: ignore` comments to suppress
+  mypy errors; fix the underlying type issues instead.
 - **Docstrings:** Google-style format for all public APIs.
 - **Logging:** Use `logging` module only; never `print()`.
 - **Relative Paths:** Never use absolute paths in code.
 
 ### Dependency & Configuration Management
-- **Adding/Removing Dependencies:** Use `uv add` / `uv remove` commands.
-- **Editing pyproject.toml:** Avoid manual edits during development. Only update `pyproject.toml` as the **final change** after all work is tested and finalized.
+
+- **Adding/Removing Dependencies:** Use `uv add` /
+  `uv remove` commands.
+- **Editing pyproject.toml:** Avoid manual edits during
+  development. Only update `pyproject.toml` as the
+  **final change** after all work is tested.
 - **Before Major Work:** Always run `uv sync --dev` first.
 
 ### Testing & Quality
-- **Test Coverage:** Every code change requires corresponding tests in `tests/`.
-- **Validation Before Commit:** Run the full suite: `uv run pytest`, `uv run ruff check .`, `uv run mypy .`, `uv run pip-audit`.
+
+- **Test Coverage:** Every code change requires
+  corresponding tests in `tests/`.
+- **Validation Before Commit:** Run the full suite:
+  `uv run pytest`, `uv run ruff check .`,
+  `uv run mypy .`, `uv run pip-audit`.
+- **Pre-commit Hooks:** Use `uv run prek install` to
+  set up Git hooks that automatically run checks.
 
 ### Operational Constraints
-- **No Interactive Prompts:** Mock or bypass any interactive commands.
-- **No Git Operations:** Don't stage/commit unless explicitly requested.
-- **Code Review Mode:** Analyze only; record findings in `./REVIEW.md` without making modifications. At the top of the review, identify the reviewer including the name of the IDE/CLI used and the primary model that performed the review.
+
+- **No Interactive Prompts:** Mock or bypass any
+  interactive commands.
+- **Staging & Commit Protocol:** When you have completed
+  work and updated files, stage the changes with
+  `git add` and then display a suggested commit message
+  for the user's review. DO NOT actually commit.
+- **Code Review Mode:** Analyze only; record findings
+  in `./REVIEW.md` without making modifications.
 
 ### File Maintenance
-- **Keep Instructions Current:** Update "Tech Stack," "Project Structure," and "Workflow Commands" if `pyproject.toml`, structure, or core logic changes.
+
+- **Keep Instructions Current:** Update "Tech Stack,"
+  "Project Structure," and "Workflow Commands" if
+  `pyproject.toml`, structure, or core logic changes.
+- **Pre-commit Config:** Keep `.pre-commit-config.yaml`
+  in sync with CI workflow when test requirements change.
 
 ## Workflow Commands
+
 ```bash
-uv sync --dev                           # Install/sync all dependencies
-uv run pytest                           # Run tests
-uv run ruff check .                     # Lint
-uv run ruff format .                    # Auto-format
-uv run mypy .                           # Type check
-uv run pip-audit                        # Security audit
-uv run hello-world hello  # Test CLI
-```
+uv sync --dev                    # Install/sync deps
+uv run pytest                    # Run tests
+uv run ruff check .              # Lint
+uv run ruff format .             # Auto-format
+uv run mypy .                    # Type check
+uv run pip-audit                 # Security audit
+uv run prek install              # Install git hooks
+uv run prek run --all-files      # Run all hooks
+uv run hello-world hello         # Test CLI
+```

AGENTS_MANUAL_CHECKS.md

@@ -1,61 +1,87 @@
-# Agent Instructions: python-package-template (Token-Efficient)
+# Agent Instructions: python-package-template
 
 ## Quick Start
+
 1. **Setup:** Run `uv sync --dev` before major work sessions
 2. **Activate:** Ensure `.venv` is active; run `uv venv` if missing
 3. **Code:** Use `python3` or `uv run python`; always add type hints and tests
 
 ## Tech Stack
-| Component | Tool |
-|-----------|------|
-| Environment & Dependencies | uv |
-| Data Validation | Pydantic |
-| CLI Framework | Typer |
-| Testing | pytest |
-| Linting & Formatting | ruff |
-| Type Checking | mypy |
+
+| Component            | Tool      |
+| -------------------- | --------- |
+| Environment & Deps   | uv        |
+| Data Validation      | Pydantic  |
+| CLI Framework        | Typer     |
+| Testing              | pytest    |
+| Linting & Formatting | ruff      |
+| Type Checking        | mypy      |
+| Security Audit       | pip-audit |
+| Markdown Lint        | pymarkdownlnt |
+| Git Hooks            | prek      |
 
 ## Project Structure
-```
+
+```text
 python_package_template/
-  ├── config.py          (Pydantic models)
-  ├── hello.py           (Business logic)
-  └── cli.py             (Typer CLI)
-tests/                   (Pytest suite)
-pyproject.toml           (Dependencies & tool config)
+  config.py          (Pydantic models)
+  hello.py           (Business logic)
+  cli.py             (Typer CLI)
+tests/               (Pytest suite)
+pyproject.toml       (Dependencies & tool config)
 ```
 
 ## Essential Directives
 
 ### Code Standards
-- **Type Hints:** Required on ALL function signatures and class members. Write code that will pass mypy. Avoid using `# type: ignore` comments to suppress mypy errors; fix the underlying type issues instead.
+
+- **Type Hints:** Required on ALL function signatures
+  and class members. Enforce strictly with mypy.
+  Avoid using `# type: ignore` comments to suppress
+  mypy errors; fix the underlying type issues instead.
 - **Docstrings:** Google-style format for all public APIs.
 - **Logging:** Use `logging` module only; never `print()`.
 - **Relative Paths:** Never use absolute paths in code.
 
 ### Dependency & Configuration Management
-- **Adding/Removing Dependencies:** Use `uv add` / `uv remove` commands.
-- **Editing pyproject.toml:** Avoid manual edits during development. Only update `pyproject.toml` as the **final change** after all work is tested and finalized.
+
+- **Adding/Removing Dependencies:** Use `uv add` /
+  `uv remove` commands.
+- **Editing pyproject.toml:** Avoid manual edits during
+  development. Only update `pyproject.toml` as the
+  **final change** after all work is tested.
 - **Before Major Work:** Always run `uv sync --dev` first.
 
 ### Testing & Quality
-- **Test Coverage:** Every code change requires corresponding tests in `tests/`.
-- **Manual Validation:** After development is complete, **you will manually run** the full validation suite for final checks.
+
+- **Test Coverage:** Every code change requires
+  corresponding tests in `tests/`.
+- **Validation:** You do NOT run validation tools.
+  Write code with quality standards in mind (type
+  hints, docstrings, tests). The user will run
+  `pytest`, `ruff check`, `ruff format`, and `mypy`
+  manually for final validation.
 
 ### Operational Constraints
-- **No Interactive Prompts:** Mock or bypass any interactive commands.
-- **No Git Operations:** Don't stage/commit unless explicitly requested.
-- **Code Review Mode:** Analyze only; record findings in `./REVIEW.md` without making modifications. At the top of the review, identify the reviewer including the name of the IDE/CLI used and the primary model that performed the review.
+
+- **No Interactive Prompts:** Mock or bypass any
+  interactive commands.
+- **Staging & Commit Protocol:** When you have completed
+  work and updated files, stage the changes with
+  `git add` and then display a suggested commit message
+  for the user's review. DO NOT actually commit.
+- **Code Review Mode:** Analyze only; record findings
+  in `./REVIEW.md` without making modifications.
 
 ### File Maintenance
-- **Keep Instructions Current:** Update "Tech Stack," "Project Structure," and "Workflow Commands" if `pyproject.toml`, structure, or core logic changes.
 
-## Workflow Commands (Run Manually)
+- **Keep Instructions Current:** Update "Tech Stack,"
+  "Project Structure," and "Workflow Commands" if
+  `pyproject.toml`, structure, or core logic changes.
+
+## Workflow Commands
+
 ```bash
 uv sync --dev                           # Install/sync all dependencies
-uv run pytest                           # Run tests (USER RUNS)
-uv run ruff check .                     # Lint (USER RUNS)
-uv run ruff format .                    # Auto-format (USER RUNS)
-uv run mypy .                           # Type check (USER RUNS)
-uv run hello-world hello  # Test CLI
-```
+uv run hello-world hello                # Test CLI
+```