Commit

Git Commit Messages

Draft well-formed commit messages that follow the conventions of whatever repository this runs in.

This file holds the decision logic. Everything that varies between repositories — scope names, the formatter to run first, which extra types are in use — is read from .claude/git-workflow.md or inferred from the repo, never written into the skill. See references/repo-config.md for the config keys and the one-time bootstrap.

Workflow

1. Adapt to the repo (next section) — read the config if there is one, otherwise infer.
2. Run the repo's formatter if one is configured, so formatting noise lands with the change instead of in a follow-up commit.
3. Run git status and git diff --staged, or git diff when nothing is staged.
4. Work out what actually changed — which files, what was added or removed, and why.
5. Choose a type and scope for each logical group.
6. Group files into commits, one purpose per commit.
7. Draft each message.
8. Run the Validation checklist on every message.
9. Return a preview and wait for the user's OK before running git commit.

Adapt to the repo

Resolve every repo-specific value in this order: the config file, then inference from the repo, then the generic default.

Never invent a formatter. Run one only when the config names it. A repo with a pre-commit hook (lefthook, husky, pre-commit) formats on its own and needs nothing here.

Read the scope vocabulary the repo already uses before deriving a new one:

git log --pretty=%s -300 | sed -nE 's/^[a-z]+\(([^)]+)\).*/\1/p' | sort | uniq -c | sort -rn

Matching what the repo has done for 300 commits beats a scope you derived correctly but that nobody else uses.

If the repo does not use this format at all, the repo wins. A history of sentence-style subjects, a [component] Subject prefix, or any other consistent convention is a decision someone made, and a lone Conventional-Commits message in the middle of it is the odd one out — not an improvement. Follow what the history shows, apply the parts of this skill that still hold (imperative subject, body that explains why, no attribution, issue trailers), and say in one line that you matched the existing style. Switching a repo's convention is the user's call; offer it, don't do it.

Output format

For each commit, return:

### Commit N

**Files:**
- path/to/file1.ts
- path/to/file2.ts

**Message:**
type(scope): subject

- Body bullet.

Rules for previews:

• List every staged file that belongs to each commit.
• When proposing several commits, make it unambiguous which files go in each.
• Group related files together — same feature, same scope.
• Present the preview and wait for approval; never commit unprompted.

Message format

type(scope): subject in imperative mood

- Body bullet in past tense with period.
- Another change description.

Closes #123

The Closes #123 trailer is optional — include it only when this single commit is the complete fix for a tracked issue (Rule 9).

Types

cicd and ai are house additions to Conventional Commits. Use them when the repo has files of that kind; a repo whose history never uses them keeps to the base set.

chore vs cicd: if it affects how code gets to production (build, CI, release, deploy) it is cicd. If it affects how developers work locally (deps, formatting, linting, editor) it is chore.

Scope

Scope is derived from context and varies by type.

When a change spans several scopes, omit the scope entirely.

Deriving a path-based scope

Use the deepest meaningful package directory — the directory that owns a package.json, Cargo.toml, go.mod, pyproject.toml, or equivalent, named by the workspace globs in pnpm-workspace.yaml, package.json workspaces, go.work, or the Cargo workspace members. The scope is that directory's name, not its full path: apps/api/ gives api, packages/core/ gives core.

Files outside any package — top-level docs/, root configs, CI definitions — have no package scope, so omit it. A single-package repo has no useful path scopes at all; omit the scope or use functional ones the history already shows.

The ai type

ai covers anything that directly configures, instructs, or extends AI capabilities.

Excluded — use another type instead:

• Code that calls an AI API is feat or fix.
• AI library dependencies are chore.
• Documentation about AI features is docs.

File → type quick lookup

Check the changed paths against these patterns before choosing a type.

If every changed file matches an ai pattern, use the ai type. When AI files are mixed with non-AI files, split them into separate commits.

Rules

1. Subject: imperative mood, lowercase after the colon, no trailing period, at most 72 characters.
2. Body: past tense, capital start, period at the end. One physical line per bullet — never hard-wrap a bullet mid-sentence at ~72 columns; only the subject has a length limit, so let the terminal soft-wrap. Keep each bullet to a sentence or two. "No hard-wrapping" is about newlines, not about length, and is not licence to write a paragraph on one line. A bullet that runs past about two sentences is carrying reasoning that belongs in the pull request description, where there is room for it and where a reader is looking for it. git log shows these one after another with no headings, so a wall of long bullets is unreadable exactly where commit messages are most often read.
3. Attribution: follow the repo's attribution policy. The default is none — no "Co-Authored-By", no "Generated with", no AI or tool attribution of any kind.
4. AI-only changes: when every changed file configures AI (see the ai type), use ai.
5. No mechanical cleanup or implementation narration: don't mention consequences obvious from the primary change (removed unused imports, unwrapped single-child fragments, re-indentation), and don't describe how the diff achieves the change ("added a helper that maps X to Y" when the diff is the helper). Focus on intent and why, not mechanism.
6. Plain language for everyone: write the subject and body so a non-technical reader and a brand-new contributor can follow the change without prior context. Lead with the everyday-terms "what changed and why it matters", spell out an acronym or internal name (a table, a service, a flag) the first time it appears, and don't lean on unstated background. Keep the precise technical terms — add the plain-language point on top, don't trade it away. Commit messages outlive their context: they are read in git blame, changelogs, and release notes long after the surrounding work is forgotten. Plain first, exact term right after, in the same sentence. Not a plain paragraph followed by a technical one, and not a technical sentence with a glossary at the end — the reader should never have to hold an unexplained term while waiting for its meaning. Write "nothing touching which organisation can see what (row-level security)", not "no RLS changes". The failure mode to watch for is the invented compound noun. "Id-keyed profile pages", "wire-shape change", "boot-time provider selection" all read as established terms to the person who just wrote them and as nothing at all to everybody else. When you catch yourself coining one, say it as a sentence instead and give an example.
7. No tautology: the subject must not repeat the type as a verb. The type already conveys the action — fix: fix the login becomes fix: resolve login failure; refactor: refactor auth becomes refactor: simplify auth flow.
8. No bare # tokens in the body: on GitHub, and in any changelog generated from commit messages, #<token> renders as an issue reference — so a hex colour or a fragment id becomes a broken issue link. Write b05220 → 95400f, not #b05220 → #95400f.
9. Issue-closing trailer: when one commit is the complete fix for a tracked issue, add a Closes #<issue> line as the last line, after a blank line, and the host auto-closes the issue when the commit lands on the default branch (Fixes and Resolves are equivalent keywords). This deliberate reference is the one sanctioned exception to Rule 8. Only tag the commit that finishes the issue: if the fix spans several commits, leave the trailer off each partial commit and put Closes #<issue> in the pull request description instead, so the issue closes once on merge rather than on the first partial commit. Skip it entirely for a commit that touches no tracked issue.

Body sizing

One bullet per topic, not per file. Files are an implementation detail and the diff already lists them. A topic is a distinct concern a reader needs to understand: a behavior change, a follow-up worth flagging, a side effect that lives outside the diff. A ten-file rename across one package is one topic; a one-file change that fixes a bug and changes an API shape and defers a TODO is three.

The diff shows what changed; the message answers why. When in doubt, fewer bullets. Each bullet earns its place by carrying information the diff doesn't.

Skip a bullet that:

• Restates the subject in different words.
• Lists files — git log --stat shows them.
• Narrates implementation steps the diff already shows.
• Recaps the investigation, which belongs in the pull request description.
• Reports test counts or "all green" results, unless the change itself is a test-infrastructure fix.

Keep a bullet that:

• Explains why when it isn't obvious from the diff — a non-local invariant, a regression cause, an external constraint.
• Flags a side effect a future reader might miss — an API shape change, an env var added, a performance trade-off.
• Notes follow-up work intentionally deferred.

Validation checklist

Run this on every message before returning the preview.

1. Length — count the subject; reject anything over 72 characters.
2. Scope — confirm the scope matches the package the files live in, or is omitted for root-level and mixed changes, and that it matches the vocabulary the repo already uses.
3. Tautology — the subject does not repeat the type word.
4. Mood — the subject is imperative ("add", "fix", "migrate"), not past tense ("added", "fixed").
5. Body — every bullet starts with a capital, uses past tense, and ends with a period.
6. Body wrapping — each bullet is a single physical line, with no hard wrap mid-sentence.
7. Attribution — no attribution trailers unless the repo's config asks for them.
8. Issue trailer — if this one commit fully closes a tracked issue, a Closes #<issue> trailer sits alone on the last line; if the fix spans commits, the trailer is absent.

Examples

feat(api): add health check endpoint

fix(web): handle an empty result list without throwing

test(api): make the attachment-download test self-sufficient

- The old version reused an account from the seed data, so a parallel test that truncated accounts made this one fail in setup. Synthetic fixture ids survive the truncate and clean up after themselves.

feat(api): add company search with filters

- Returned summary projections rather than whole records to keep the payload small.

refactor(core): move the retry policy into the client

- Callers were each choosing their own backoff, so a slow provider was retried three different ways depending on the entry point.

chore: update workspace dependencies

- Bumped the formatter to 2.4.10 for the stable ordering of import groups.

cicd(deploy): build workspace packages before the service image

- The shared package now builds first so the service's imports resolve inside the container.

ai(skills): add a portable commit-message skill

fix(auth): stop expired sessions from silently renewing

Closes #412