Write Conventional Commit

Generate and apply Conventional Commits that follow the 1.0.0 specification.

Workflow

Step 1: Inspect commit scope

Run from repository root:

git status --short
git diff --staged --name-only
git diff --name-only

Use staged changes when available. If nothing is staged and the user asked to commit now, stage intentionally relevant files first and state what was staged.

Step 2: Classify intent into commit type

Pick the best type from change intent, not from file extension.

Common types:

feat: add a user-facing feature
fix: fix a bug
refactor: code change without new feature or bug fix
perf: improve performance
docs: documentation only
test: add/update tests
build: build/dependency tooling
ci: CI/CD configuration
chore: maintenance that does not fit above
revert: revert a previous commit

If uncertain between feat and fix, prefer:

fix when correcting broken behavior
feat when adding new behavior

Step 3: Choose optional scope

Scope is optional and should be short and stable.

Prefer one of:

top-level package/app (api, billing, auth)
subsystem (migrations, deps, release)
user-visible surface (checkout, search)

Avoid broad scopes like misc.

Step 4: Detect breaking changes

Mark breaking changes when diff indicates incompatible API/contract behavior.

Signals include:

removed/renamed public endpoints, fields, events, CLI flags
required inputs changed incompatibly
output schema changed incompatibly

When breaking:

Add ! after type or type+scope (feat!: or feat(api)!:)
Add footer: BREAKING CHANGE: <what changed and how to migrate>

Use both when possible for clarity.

Step 5: Compose message in spec format

Use this structure exactly:

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

[optional body]

[optional footer(s)]

Formatting rules:

Header type must be lowercase noun.
Put a colon and single space after header prefix.
Keep description concise and specific.
Put one blank line between header and body.
Put one blank line between body and footers.
Footer tokens follow git trailer style (Token: value), except references may use Token #value.
Use BREAKING CHANGE: as the canonical breaking footer token.

Step 6: Create commit (when requested)

If user wants the commit executed, run non-interactively:

git commit -m "<header>" -m "<body>" -m "<footer1>" -m "<footer2>"

Only include -m blocks that are needed.

For multiline body/footer with precise formatting, use:

git commit -F /tmp/commit-msg.txt

Then report:

final commit header
commit hash
whether breaking change was marked

Quality checks

Before finalizing, verify:

Header matches <type>[scope][!]: description
Type reflects intent correctly
Scope is helpful or omitted
Breaking changes are explicitly marked when applicable
Body explains why when context is not obvious
Footers are valid trailers and references are accurate

Output behavior

When user asks only for message suggestions, provide 1 recommended message and up to 2 alternatives.

When user asks to commit directly, proceed with staging/commit commands and then return commit result.

Reference

Read references/conventional-commits-1.0.0.md for the normative checklist and examples.