Semantic Git

Semantic Git

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

This skill is zagi-aware and is designed to work well with AI IDEs (Cursor, etc.)

Tooling

• Preferred: `zagi` (a better git interface for agents).
• Assume zagi is installed if:
• git is aliased to zagi in the shell or
• a zagi binary is available.
• When in doubt, treat git as if it may be zagi-compatible and avoid using exotic flags.
• Even when zagi is available, generate plain `git` commands and let any git → zagi integration handle them.
• Fallback: plain git when zagi is not available.

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.
• Command transparency: Always show the exact git commands that will be run (which may be handled by zagi via alias/wrapper), and ask whether the user wants:
• to run them manually, or
• to have the agent run them.

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 a single CI command if it 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 a conventional commit message based on changes. 5. Generate commands:

• Construct explicit shell commands using git (which may be an alias or wrapper such as zagi), for example:

     git add path/to/file1 path/to/file2
     GIT_AUTHOR_DATE="YYYY-MM-DD HH:MM:SS" \
     GIT_COMMITTER_DATE="YYYY-MM-DD HH:MM:SS" \
     git commit -m "feat: add feature"

• Always print these commands to the user in order.

6. Ask for execution preference:

• Ask the user whether they want:
• to copy-paste and run the commands themselves, or
• to have the agent run them.
• Only execute commands after explicit user approval.

7. Commit:

• When executing, run exactly the printed commands.
• Respect any user instructions about backdating timestamps or additional flags.

8. Next commit:

• Before staging the next set of changes, confirm with the user that the previous commit is complete and understood.

Automation Mode

If user requests "continue to X" or "automate until X":

• Proceed with atomic commits automatically, but still print commands.
• For each commit:
• Show the staging and commit commands.
• Optionally execute them automatically, as per the user’s automation request.
• Resume asking for confirmation when X is 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.
• When uncertain how to proceed with implementation.
• When requirements are unclear.
• When a destructive git operation is proposed (reset --hard, checkout ., clean -f, push --force); prefer safer alternatives and explain the risks.

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
• references/co-authors.md – Handling Co-Authored-By trailers and zagi co-author stripping

CI Verification

CI verification ensures code passes all checks before committing.

CI Command Detection

Preferred: Single CI Command

Check for common CI command patterns:

• pnpm ci or pnpm run ci
• npm run ci
• just ci or make ci
• task ci or run ci

If found, run the single command. If it fails, stop and report errors.

Fallback: Individual Checks

If no single CI command exists, run checks individually:

Type Checking:

• TypeScript: pnpm typecheck or tsc --noEmit
• Python: mypy . or pyright
• Check package.json/justfile/makefile for typecheck script

Testing:

• pnpm test or npm test
• pytest or python -m pytest
• cargo test
• Check for test scripts in package.json/justfile/makefile

Linting:

• pnpm lint or npm run lint
• ruff check or pylint
• cargo clippy
• Check for lint scripts in package.json/justfile/makefile

Error Handling

If any check fails: 1. Stop immediately - Do not proceed to staging 2. Report errors clearly - Show which check failed and why 3. Wait for user - Do not attempt to fix automatically unless directed 4. Do not stage or commit - Changes must pass all checks first

Integration with Task Managers

Justfile

ci: typecheck lint test

Makefile

ci: typecheck lint test

package.json

{
  "scripts": {
    "ci": "pnpm typecheck && pnpm lint && pnpm test"
  }
}

Common Patterns

Node.js/TypeScript:

pnpm ci  # or
pnpm typecheck && pnpm lint && pnpm test

Python:

just ci  # or
mypy . && ruff check . && pytest

Rust:

cargo clippy && cargo test

Verification Before Staging

Always verify CI passes before staging changes: 1. Run CI checks 2. Confirm all checks pass 3. Only then stage atomic changes 4. Proceed with commit workflow

Co-authors and trailers

Some environments (including AI IDEs like Cursor) automatically add Co-Authored-By trailers to commit messages. This reference explains how to let zagi handle stripping those trailers without changing the commit flow in the semantic-git skill.

Co-author stripping with zagi

When using zagi (directly or via a git → zagi alias), prefer configuring the environment so that zagi removes unwanted Co-Authored-By lines for you.

Configure your shell with:

export ZAGI_STRIP_COAUTHORS=1

This lets zagi strip automatically-added Co-Authored-By: trailers from commit messages, while the semantic-git skill continues to:

• Generate plain git commands
• Rely on any git → zagi integration in the shell
• Avoid mutating commit messages itself purely to manage co-authors

Conventional Commits Reference

Detailed reference for conventional commit message format.

Format

<type>[optional scope]: <subject>

[optional body]

[optional footer(s)]

Type Categories

Primary Types

feat: A new feature

• Introduces new functionality
• Includes implementation and tests together
• Example: feat: add user registration

fix: A bug fix

• Fixes a bug in existing code
• Includes fix and tests together
• Example: fix: resolve null pointer in user service

Documentation

docs: Documentation only changes

• README, comments, API docs
• Example: docs: update API documentation

Code Quality

style: Changes that do not affect the meaning of the code

• White-space, formatting, missing semi-colons, etc.
• No logic changes
• Example: style: format code with prettier

refactor: A code change that neither fixes a bug nor adds a feature

• Restructuring without changing behavior
• Never use for behavior changes - use feat or fix instead
• Example: refactor: extract validation logic

perf: A code change that improves performance

• Optimizations that improve performance
• Example: perf: optimize database queries

test: Adding missing tests or correcting existing tests

• Only when no implementation code changes
• Adding, updating, or removing tests without code changes
• Example: test: add edge case tests for auth

Build and Infrastructure

build: Changes that affect the build system or external dependencies

• Webpack, Vite, tsconfig changes
• Example: build: update Vite config

ci: Changes to CI configuration files and scripts

• GitHub Actions, CI configs
• Example: ci: add test coverage job

chore: Maintenance tasks (no production code change)

• Updating build tasks, dependencies, etc.
• Prefer small, focused dependency bumps over blanket upgrades. When updating dependencies:
• Group small related updates together where possible
• Keep breaking or risky upgrades in their own commits
• Example commit subjects:
• chore: bump P to x.y.z
• chore: bump lockfile or chore: bump dependencies

revert: Revert previous commit

• Example: revert: revert "feat: add user auth"

Scope

Optional scope indicates what part of codebase is affected:

• feat(api): add endpoint
• fix(ui): resolve button styling
• refactor(auth): simplify login flow

For monorepos/subpackages: If work is in a subpackage, use the subpackage name as the scope, removing any project prefix:

• ✅ feat(api): add endpoint (not feat(project-api) or feat(@project/api))
• ✅ refactor(core): simplify login flow (not refactor(@myorg/core))

Use when it adds clarity. Omit if obvious from context or many areas are touched in the change.

Breaking Changes

Using !

Add ! after type/scope to indicate breaking change:

• feat!: change API response format
• fix(api)!: remove deprecated endpoint

BREAKING CHANGE Footer

For complex breaking changes, use footer:

feat!: migrate to new database schema

BREAKING CHANGE: Database schema changed. Run migration script before deploying.

Subject Guidelines

Imperative Mood

✅ Good:

• feat: add user authentication
• fix: resolve memory leak
• refactor: extract validation

❌ Bad:

• feat: added user authentication (past tense)
• fix: resolves memory leak (present tense)
• feat: adding user authentication (gerund)

Capitalization

• First letter lowercase (unless proper noun)
• feat: add User model (User is proper noun)
• feat: add user model (preferred)

Length

• Keep under 72 characters when possible
• Be concise but descriptive
• Omit unnecessary words

No Period

• No period at end of subject
• feat: add feature ✅
• feat: add feature. ❌

Body

When to Include

Include body only when:

• Change is complex and needs explanation
• Breaking changes need details
• References to issues, PRs, or docs are needed

Format

• Blank line after subject
• Wrap at 72 characters
• Use imperative mood
• Reference related issues: Closes #123
• Reference documentation: See docs/api.md

Example

feat(api): add pagination support

Implements cursor-based pagination for large datasets.
Improves performance for queries returning >1000 results.

Closes #456
See docs/api/pagination.md for usage.

Footer

Use for:

• Breaking changes: BREAKING CHANGE: <description>
• Issue references: Closes #123, Fixes #456
• Co-authors: Co-authored-by: Name <email>

Atomic Commits

Group Related Changes

✅ Good:

• Implementation + tests together
• Feature + related refactoring
• Fix + test for fix

❌ Bad:

• Multiple unrelated features
• Implementation without tests
• Tests without implementation (unless test-only change)

Examples

Feature with tests:

feat: add user authentication

- Add login endpoint
- Add password hashing
- Add authentication tests

Bug fix with tests:

fix: resolve memory leak in cache

- Fix cache cleanup logic
- Add test for cache expiration

Test-only change:

test: add edge case tests for auth

- Add tests for expired tokens
- Add tests for invalid credentials