commit-style

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.