| name | commit-style |
| description | Use before any git commit. Defines Conventional-Commit subject lines with scope tags, body detail requirements, explicit staging discipline, the no-AI-authorship rule, and PR-vs-direct-commit guidance. Adapt the scope list to the current project. |
Commit Style
A portable commit convention for agentic coding. The structure is fixed; the
scope vocabulary is per-project — adapt the scope list to whatever the repo
actually contains (its packages, layers, or subsystems).
Subject line
Format: <type>(<scope>): <imperative summary>
<type> is one of:
feat — new user-visible feature or capability.fix — bug fix (subject names the bug, not the solution).refactor — internal restructure with no behaviour change.perf — performance improvement.ui — visual-only change (no logic).docs — documentation only.test — fixtures or test scripts only.chore — tooling, deps, config.restructure — large structural changes (rare).
<scope> names the part of the codebase touched. Pick from the project's own
scope list — define it once per repo (e.g. a service id, a layer like api /
frontend / core, a shared contract, docs, skills, repo). Mark the
load-bearing scope that everything depends on (often contract or core) so
changes to it get extra review.
Imperative form, lowercase first word. Keep the subject under 72 chars.
Body — required for all non-trivial commits
Always include a body. One blank line after the subject, then:
What changed — bullet list of concrete changes (files / components /
behaviour). Be specific: name the module, function, or file touched.
Why — one or two sentences. What problem does this solve, or what goal does
it serve?
Impact notes (include when relevant):
Tests: N pass / 0 fail — when the suite was run.Contract change — if a shared interface / data shape changed (everyone is
affected).Breaking: <what> — if an API or data-shape contract changed.
Trailer
Do NOT add Co-Authored-By: Claude or any AI authorship trailer. Never.
Staging
- Stage files explicitly by path — never
git add . or git add -A.
- Run
git diff --cached --stat before committing to verify the staged set.
- Never commit: build artifacts (
__pycache__/, node_modules/, dist/,
build/), databases (*.sqlite), secrets (.env), captured fixtures
containing PII, *.log, .DS_Store.
When to PR vs commit direct to branch
- Direct commit: single-concern change on a feature branch, already reviewed
in conversation.
- PR (required): anything touching a shared contract/interface, core
orchestration, an audit log, or 5+ files — so it can be reviewed before merging
to
main.
- Work on a branch, never directly on
main. Branch names: <area>/<thing>
(e.g. core/cache, frontend/login, docs/readme).
- Force-push only on your own branch, never on
main.
What NOT to do
- Skip hooks (
--no-verify) — investigate the failing hook instead.
- Amend a published commit.
- Lump unrelated changes into one commit.
- Change a shared contract quietly inside an unrelated commit — that is its own
reviewed
contract change.
