Commit

Conventional Commit

Create focused git commits using the Conventional Commits format.

Commit Format

Use this structure:

<type>[optional scope][!]: <description>

[optional body]

[optional footer(s)]

Types

Prefer these types:

• feat: a new user-facing or externally observable capability
• fix: a bug fix
• docs: documentation-only changes
• style: formatting or style-only changes that do not affect behavior
• refactor: code restructuring that neither fixes a bug nor adds a feature
• perf: performance improvement
• test: adding or updating tests only
• build: build system, packaging, or dependency changes
• ci: CI configuration or workflow changes
• chore: maintenance work that does not fit another type
• revert: revert a previous commit

Use the most specific accurate type. Do not use feat unless the change adds a new capability. Do not use fix unless it corrects broken behavior.

Scope

Add a scope when it improves clarity:

• Use a package, app, module, route, domain, or subsystem name.
• Keep scope lowercase and short, such as api, auth, ui, deps, billing.
• Omit scope if the change is broad or no concise scope is obvious.

Description

Write the description in imperative mood, lowercase unless a proper noun requires capitalization.

Name the observable behavior or outcome rather than a generic action or implementation detail. Mention the implementation mechanism only when it distinguishes the change. Include a measurement only when observed verification supports it. Put the cause, rationale, trade-offs, and supporting implementation detail in the commit body.

Examples:

Weak:   feat(auth): add password reset flow
Better: feat(auth): let users reset forgotten passwords

Weak:   perf(server): negotiate permessage-deflate on websocket
Better: perf(server): reduce websocket frame size with compression

When verification measured the result, prefer the verified outcome:

perf(server): cut websocket frame size by 70%

Keep the subject line concise, ideally 72 characters or less.

Breaking Changes

Mark breaking changes with ! after the type or scope and include a footer:

feat(api)!: require project id for exports

BREAKING CHANGE: Export requests must now include a project id.

Only mark a breaking change when existing consumers, persisted data, public APIs, commands, configuration, or documented behavior require migration.

Safe Workflow

Before committing:

1. Run git status --short to inspect modified, staged, and untracked files.
2. Run git diff and git diff --staged to understand unstaged and staged changes.
3. Run git log --oneline -n 10 to learn the repository's existing commit style.
4. Identify which changes belong in this commit. Do not stage unrelated user changes.
5. Do not commit secrets, credentials, local environment files, generated artifacts, or unrelated formatting churn.
6. If there are suspicious files such as .env, private keys, tokens, or credential JSON files, stop and ask before committing them.

When staging:

• Stage only files directly related to the requested commit.
• Preserve unrelated worktree changes.
• Prefer explicit paths with git add <path>.
• Avoid broad staging with git add . unless all changes have been reviewed and clearly belong together.

When committing:

• Decide whether the commit needs a body by applying the Commit Body criteria below.
• Use git commit -m "<conventional subject>" when the subject fully communicates the change and its rationale is self-evident.
• Use multiple -m flags when adding a body or footer.
• Do not bypass hooks with --no-verify unless the user explicitly asks.
• Do not amend unless the user explicitly asks.
• Do not push unless the user explicitly asks.

After committing:

1. Run git status --short to verify the commit succeeded and confirm any remaining changes are intentional.
2. Report the commit hash and message.
3. Mention any uncommitted changes left behind.

Message Selection

Choose the message from the actual diff, not from the user's phrasing alone.

Use this decision process:

1. If the diff is documentation only, use docs.
2. If the diff is tests only, use test.
3. If the diff changes build tooling, package metadata, lockfiles, or dependencies, use build unless it is purely CI.
4. If the diff changes CI files or automation workflows, use ci.
5. If the diff fixes incorrect behavior, use fix.
6. If the diff adds a new capability, use feat.
7. If the diff restructures code without behavior change, use refactor.
8. If the diff improves runtime performance, use perf.
9. If none apply and the work is maintenance, use chore.

If multiple unrelated changes are present, ask whether to split them into separate commits unless the user already specified grouping.

Commit Body

A commit body explains the reasoning or context behind the change. Consider one for every commit, but include it only when it adds durable information beyond the subject and diff.

Use a body when it helps a future reader understand one or more of:

• why the change was needed
• why this approach was chosen over an obvious alternative
• constraints, assumptions, or tradeoffs that shaped the implementation
• non-obvious behavior changes, side effects, or migration context

Write the body as concise prose focused on cause and intent. A body is unnecessary when the rationale is self-evident from the subject and diff.

Example:

fix(cache): avoid stale project permissions

Role updates were leaving cached permissions valid until their TTL expired. Include the role version in the cache key so permission changes take effect immediately without requiring broad cache invalidation.

Footers

Use footers for metadata such as issues, breaking changes, or co-authors:

Closes #123
Refs #456
BREAKING CHANGE: The config file now uses `projectId` instead of `id`.

Output Style

When done, respond briefly:

Committed `<hash>` with `type(scope): description`.

If no commit was created, explain why and list the blocker.