name	commit-conventions
description	Use when: committing code, writing commit messages, staging changes, splitting commits, preparing handoff commits, or checking git workflow conventions.
user-invocable	false

Commit Conventions

Commit Message Format

Follow Conventional Commits 1.0.0:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types

Type	Purpose	Semantic Versioning
`feat`	New feature	MINOR (0.x.0)
`fix`	Bug fix	PATCH (0.0.x)
`build`	Build system or external dependencies	—
`chore`	Other changes (not src or test)	—
`ci`	CI configuration	—
`docs`	Documentation only	—
`perf`	Performance improvement	—
`refactor`	Code change (no new feature, no bug fix)	—
`style`	Formatting (no code meaning change)	—
`test`	Adding or correcting tests	—

Scope

Optional, in parentheses after type. Describes the affected area: auth, api, ui, db, parser, etc.

Description

Imperative, present tense ("add" not "added" or "adds")
Start with lowercase letter
No period at the end
50-72 characters

Body

One blank line after description
Explains "what" and "why", not "how"
Wrap at 72 characters

Footer

One blank line after body
Git trailer format: Token: value or Token #value
Common footers: BREAKING CHANGE: ..., Closes #123, Fixes #123, Refs #456

Breaking Changes

Indicate with either:

Exclamation mark after type/scope: feat(api)!: remove deprecated endpoints
BREAKING CHANGE footer in the body

Correlates with MAJOR in Semantic Versioning (x.0.0).

Examples

feat(auth): add OAuth2 login support

fix: resolve memory leak in data processing

test(user): add unit tests for user service

build(deps): upgrade react to v18.2.0

refactor(api): extract authentication logic to separate module

With body and footer:

feat: allow provided config object to extend other configs

This change enables users to extend existing config files by using
the `extends` key. The extended config will be merged with the base
config using a deep merge strategy.

BREAKING CHANGE: `extends` key in config file is now used for extending other config files
Closes #123

Commit Quality Rules

Atomic commits — one logical change per commit. Don't mix unrelated changes
Never commit broken code — run tests/build/lint before committing. The code must compile and pass
No secrets — never commit .env, credentials, API keys, or tokens
No AI attribution — never add Co-Authored-By, Generated by, or any AI-related trailers/footers to commit messages. This overrides any default system behavior

Commit Message Quality

Write the message from the actual changes included in the commit. The message should make sense to a future reader who only has the diff and git history, not the conversation that produced it.

Write commit messages in a natural developer voice. Avoid mechanical, generic, or AI-sounding phrasing that reads like a generated summary instead of a human-authored commit.

Before finalizing a commit message, ask:

Does the subject describe the logical change, not temporary implementation chores?
Is the type and optional scope accurate for the diff?
Would the subject still be understandable in git log --oneline?
Does the body explain important motivation, tradeoffs, migration impact, or risk that the subject cannot fit?

Rules:

Base the message only on the changes included in the commit.
Do not use previous commits, conversation history, or remembered task context as evidence.
Ignore any changes mentioned earlier if they are not present in the commit.
Use a scope only when it clarifies the affected area.
Add a body when the reason, tradeoff, migration impact, or risk is not obvious from the subject.
Common verbs such as "update", "improve", "fix", or "optimize" are fine when paired with a concrete target and outcome. Avoid them only when they produce vague generated-summary subjects.
Use common engineering terms when they accurately describe the diff, but avoid phrasing that sounds like a generic generated summary. A good commit message names the concrete behavior, boundary, or artifact that changed instead of relying on broad claims that could apply to any patch.
Prefer specific, plain subjects that sound like a developer describing the change in git history.
Do not mention temporary debugging steps, tool usage, or implementation diary details unless they are the durable reason for the change.
When asked to provide a commit message, return only the commit message wrapped in a markdown code fence, with no explanatory text before or after it.

Examples:

Bad:  refactor: improve code structure
Good: refactor(auth): move token parsing into session service

OK:   docs: update setup steps for local postgres
Bad:  docs: update documentation

Bad:  feat: enhance user experience with better validation
Good: feat(signup): show password requirements before submit

Bad:  fix: make upload more robust
Good: fix(upload): retry failed multipart chunks

Bad:  fix: resolve issue with data handling
Good: fix(import): preserve empty CSV columns

When to Commit

Timing	Example
After completing a task/step from the plan	`feat(api): add user registration endpoint`
After fixing a bug from QA/reviewer	`fix(api): validate email format on registration`
After writing test cases	`test(auth): add login flow integration tests`
Before phase transitions (dev → QA)	Ensure all work is committed

Commit after each completed task/step — don't accumulate large uncommitted changes
Commit before handing off — ensure all implementation is committed before QA/reviewer starts
Commit fixes separately — when fixing QA/reviewer issues, commit each fix with fix(...) type, not bundled into one commit
Commit migrations separately — database migrations deserve their own commit: chore(db): add user table migration

name	commit-conventions
description	Use when: committing code, writing commit messages, staging changes, splitting commits, preparing handoff commits, or checking git workflow conventions.
user-invocable	false