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
   • •Use test: for test only changes
2. •Run CI checks: Verify types, tests, and linting pass before staging
   • •Prefer single CI command if exists (e.g., pnpm ci, npm run ci, just ci)
   • •If no CI command, run checks individually (typecheck, test, lint)
   • •If any check fails, stop and report - do not proceed
3. •Stage atomic changes: Group related files together (implementation + tests)
4. •Suggest commit message: Generate conventional commit message based on changes
5. •Confirm with user: Always ask for confirmation before committing
6. •Commit: Execute commit only after user approval
7. •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