Conventional Commit

Follow the Conventional Commits specification for all commits.

Preconditions

Validate branch

Run git rev-parse --abbrev-ref HEAD.

If on main or master, stop and ask the user to create a feature branch.

Branch names should follow: <TICKET_PREFIX>-<number>-<kebab-case-description> (e.g., ENG-1333-migrate-review-flow). If invalid, ask the user to rename the branch.

Conventional Commits Spec

The commit message format:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types (required)

Scope (optional)

A noun describing the section of codebase affected, in parentheses:

• feat(parser): add ability to parse arrays
• fix(auth): resolve token expiration bug

Breaking Changes

Append ! after type/scope OR add BREAKING CHANGE: footer:

feat(api)!: remove deprecated endpoints

BREAKING CHANGE: The /v1/users endpoint has been removed. Use /v2/users instead.

Breaking changes correlate with MAJOR in SemVer.

Steps

1. Review current state

   git status
   git diff
   git log -1 --oneline
   

2. Group changes logically – prefer multiple small commits over one large commit

3. Create commits

   For each logical group:

   • Stage relevant files or hunks
   • Commit using Conventional Commit format

   Option A: Use git commit directly (recommended for agents):

   git commit -m "feat(auth): add OAuth2 support"
   

   Multi-line with body:

   git commit -m "feat(api): add pagination to list endpoints" \
     -m "Implements cursor-based pagination for all list endpoints." \
     -m "BREAKING CHANGE: Response format changed from array to object with data/meta keys."
   

   Option B: Use git-cz non-interactive mode (streamich/git-cz, not standard cz):

   npx git-cz --non-interactive --type=feat --scope=auth --subject="add OAuth2 support"
   

   With body/breaking changes:

   npx git-cz --non-interactive \
     --type=feat \
     --scope=api \
     --subject="add pagination to list endpoints" \
     --body="Implements cursor-based pagination for all list endpoints" \
     --breaking="Response format changed from array to object with data/meta keys"
   

   Note: The standard npx cz (commitizen/cz-cli) is interactive-only and cannot be used by agents. Use git commit or npx git-cz --non-interactive instead.

4. Push the branch

   git push -u origin HEAD  # if no upstream
   git push                 # otherwise
   

Commit Message Guidelines

• Description: Use imperative mood (“add” not “added” or “adds”)
• Description: Lowercase, no period at end
• Body: Explain what and why, not how
• Footer: Reference issues (Fixes #123, Closes #456)

Notes

• Do not commit secrets, credentials, or environment files
• Describe intent and impact, not implementation detail
• When in doubt, split commits
• This skill does not perform rebases, squashes, or force pushes

References

• Conventional Commits Specification
• git-cz (non-interactive mode)