name: semantic-git
description: Manage Git commits using conventional commit format with atomic staging. Use when committing changes, staging files, or creating commit messages.

Semantic Git

Manage Git commits using conventional commit format with atomic commits and concise messages.

When to Use

• Committing changes to git
• Staging files for commit
• Creating commit messages
• Managing atomic commits
• Before pushing changes

Core Principles

• Atomic commits: Stage and commit related changes together. Tests go with implementation code.
• User confirmation: Always confirm with user before committing and before moving to the next commit.
• Conventional format: Use conventional commit message format (feat, fix, etc.) unless directed otherwise.
• Concise messages: Keep messages brief and to the point. Omit description unless change is complicated.

Commit Message Format

<type>[optional scope]: <subject>

[optional body]

[optional footer(s)]

Types

• feat: A new feature
• fix: A bug fix
• docs: Documentation only changes
• style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc.)
• refactor: A code change that neither fixes a bug nor adds a feature
• perf: A code change that improves performance
• test: Adding missing tests or correcting existing tests
• build: Changes that affect the build system or external dependencies
• ci: Changes to CI configuration files and scripts
• chore: Maintenance tasks (updating build tasks, dependencies, etc.; no production code change)
• revert: Revert a previous commit

Breaking Changes

Use ! after the type/scope to indicate breaking changes:
- feat!: add new API
- fix(api)!: change response format

Subject Line

• Use imperative mood: "add feature" not "added feature" or "adds feature"
• First letter lowercase (unless starting with proper noun)
• No period at the end
• Keep under 72 characters when possible

Body and Footer

• Omit body unless change is complicated or requires explanation
• When needed, be concise and reference issues, PRs, or documentation
• Use footer for breaking changes: BREAKING CHANGE: <description>

Workflow

1. Implement atomic change: Code + tests together
2. Use test: for test only changes
3. Run CI checks: Verify types, tests, and linting pass before staging
4. Prefer single CI command if exists (e.g., pnpm ci, npm run ci, just ci)
5. If no CI command, run checks individually (typecheck, test, lint)
6. If any check fails, stop and report - do not proceed
7. Stage atomic changes: Group related files together (implementation + tests)
8. Suggest commit message: Generate conventional commit message based on changes
9. Confirm with user: Always ask for confirmation before committing
10. Commit: Execute commit only after user approval
11. Next commit: Before staging next set of changes, confirm with user

Automation Mode

If user requests "continue to X" or "automate until X":
- Proceed with atomic commits automatically
- Resume asking for confirmation when X point reached
- X can be: specific file, feature completion, test passing, etc.

Stop and Ask Protocols

Stop and ask user before:
- Adding type ignores (@ts-ignore, # type: ignore, etc.)
- Adding suppressions (ESLint disable, pylint disable, etc.)
- Using any type or similar type escapes
- Uncertain how to proceed with implementation
- Requirements are unclear

Examples

Simple feature or behaviour change:

feat: add user authentication

Feature with scope:

feat(api): add user endpoint

Bug fix:

fix: resolve memory leak in cache

Breaking change:

feat!: migrate to new API version

Test-only change:

test: improve unit tests for auth service

Refactor (no behavior change):

refactor: extract validation logic into separate function

Complex change (with body):

feat(api): add pagination support

Implements cursor-based pagination for large datasets.
See docs/api/pagination.md for details.

References

For detailed guidance, see:
- references/conventional-commits.md - Commit format and examples
- references/ci-verification.md - CI check patterns and verification