feat(tooling): add pre-commit hooks support (#609)

* feat(tooling): add pre-commit hooks support

Author: jabrena

.github/workflows/maven.yaml

@@ -57,6 +57,25 @@ jobs:
         env:
           SKILL_CHECK_NO_BANNER: 1
 
+  pre-commit:
+    name: Pre-commit
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          submodules: true
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.x"
+      - name: Install pre-commit
+        run: pip install pre-commit
+      - name: Run pre-commit (all files)
+        run: pre-commit run --all-files
+      - name: Validate HEAD commit message
+        run: |
+          git log -1 --pretty=%B > /tmp/commit-msg.txt
+          pre-commit run conventional-pre-commit --hook-stage commit-msg --commit-msg-filename /tmp/commit-msg.txt
+
   examples:
     name: Build Examples
     runs-on: ubuntu-latest

.gitignore

@@ -8,3 +8,4 @@ target/
 dependency-reduced-pom.xml
 docs-local/
 .quarkus/
+.venv-precommit/

.pre-commit-config.yaml

@@ -0,0 +1,27 @@
+# https://pre-commit.com/
+# Install: pip install pre-commit && pre-commit install --install-hooks
+# Commit messages must match AGENTS.md (Conventional Commits + required scope).
+default_install_hook_types:
+  - pre-commit
+  - commit-msg
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-yaml
+
+  - repo: https://github.com/compilerla/conventional-pre-commit
+    rev: v4.4.0
+    hooks:
+      - id: conventional-pre-commit
+        stages: [commit-msg]
+        args:
+          - --force-scope
+          - feat
+          - fix
+          - docs
+          - style
+          - refactor
+          - test
+          - chore

AGENTS.md

@@ -66,6 +66,24 @@ npx skill-check skills
   - `fix(generator): resolve template parsing issue`
   - `docs(readme): update installation instructions`
 
+### Pre-commit hooks (recommended)
+
+This repository includes [pre-commit](https://pre-commit.com/) configuration at [`.pre-commit-config.yaml`](.pre-commit-config.yaml): YAML checks and a **commit-msg** hook that enforces the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) rules above (including a required **scope**).
+
+**Setup (once per clone):**
+
+```bash
+pip install pre-commit   # or: brew install pre-commit
+pre-commit install --install-hooks
+```
+
+The install registers both the default `pre-commit` stage and `commit-msg` hooks. To validate the latest commit message manually:
+
+```bash
+git log -1 --pretty=%B > /tmp/msg.txt
+pre-commit run conventional-pre-commit --hook-stage commit-msg --commit-msg-filename /tmp/msg.txt
+```
+
 ## Boundaries
 
 - ✅ **Always do:** Edit XML in `system-prompts-generator/src/main/resources/` to change rules, run `./mvnw clean verify` before promoting changes. When edit XML, follow PML Schema: [https://jabrena.github.io/pml/schemas/0.7.0/pml.xsd](https://jabrena.github.io/pml/schemas/0.7.0/pml.xsd).

CONTRIBUTING.md

@@ -1,5 +1,12 @@
 # Contributing
 
+## Conventions
+
+Read [AGENTS.md](./AGENTS.md) for the full contributor guide (tech stack, boundaries, and commands).
+
+- **Git:** use [Conventional Commits](https://www.conventionalcommits.org/) in the form `type(scope): description`, with types such as `feat`, `fix`, `docs`, `style`, `refactor`, `test`, and `chore` (see AGENTS.md).
+- **Pre-commit (recommended):** this repo includes [pre-commit](https://pre-commit.com/) in [`.pre-commit-config.yaml`](.pre-commit-config.yaml) (YAML checks and a commit-msg hook aligned with the rules above). Install once per clone: `pip install pre-commit` or `brew install pre-commit`, then `pre-commit install --install-hooks`. Details and manual checks are in AGENTS.md under **Pre-commit hooks**.
+
 ## Generator
 
 The entire set of cursor rules is autogenerated by XML files in the project `system-prompts-generator`.

README.md

@@ -74,7 +74,7 @@ Models are able to generate code, but they cannot run code with your local data.
 
 ## Contribute
 
-If you have great ideas, [read the following document](./CONTRIBUTING.md) to contribute.
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for conventions, generator workflows, tests, and how to open a pull request.
 
 ## Examples