Atomic Commits

Creates well-structured, semantic commits following Conventional Commits specification. Automatically analyzes changes and creates atomic, focused commits.

Core Principles

1. Atomic: Each commit represents ONE logical change
2. Semantic: Type prefix describes the nature of the change
3. Scoped: Optional scope indicates the affected module/component
4. Descriptive: Message explains WHAT and WHY, not HOW

Workflow

Step 1: Analyze Changes

Run these commands to understand the current state:

git status
git diff --staged
git diff

Step 2: Identify Commit Types

For each logical change, determine the appropriate type:

Type	When to Use
feat	New feature for the user
fix	Bug fix for the user
docs	Documentation only changes
style	Formatting, missing semicolons (no code change)
refactor	Code change that neither fixes a bug nor adds a feature
perf	Performance improvement
test	Adding or fixing tests
build	Build system or external dependencies
ci	CI configuration files and scripts
chore	Other changes that don't modify src or test files
revert	Reverts a previous commit

Step 3: Determine Scope

Analyze changed files to suggest scope:

• api/ → scope: api
• core/database.py → scope: db
• agents/faq_agent/ → scope: faq-agent
• tests/ → scope: tests
• Multiple areas → consider splitting into multiple commits

Step 4: Create Atomic Commits

If changes span multiple concerns, split them:

git add -p  # Stage hunks interactively (but explain to user)

Or stage specific files:

git add <specific-files>
git commit -m "<type>(<scope>): <description>"

Step 5: Validate Message Format

Before committing, validate the message follows the pattern:

<type>(<scope>): <description>

[optional body]

[optional footer(s)]

Rules:

• Type is required and lowercase
• Scope is optional, lowercase, in parentheses
• Description starts lowercase, no period at end
• Max 72 characters for first line
• Body wrapped at 72 characters
• Breaking changes: add "!" after type/scope or "BREAKING CHANGE:" in footer
• NEVER add auto-generated labels like "Generated with Claude Code", "Co-Authored-By", or any AI attribution
• Commit messages must be clean and professional, as if written by the developer

Commit Message Template

<type>(<scope>): <short description>

<body - explain WHAT and WHY>

<footer>

Breaking Changes

For breaking changes, use one of:

feat(api)!: change authentication method

feat(api): change authentication method

BREAKING CHANGE: API now requires Bearer token instead of API key

Multi-Commit Strategy

When changes are complex, create separate commits for:

1. Preparation: Refactoring needed before the feature
2. Core: The main feature/fix implementation
3. Tests: New or updated tests
4. Docs: Documentation updates

Example sequence:

refactor(auth): extract token validation to separate function
feat(auth): add OAuth2 support
test(auth): add OAuth2 integration tests
docs(auth): update authentication guide

Interactive Mode

When asked to commit, always:

1. Show the user what will be committed (files and diff summary)
2. Suggest the commit type and scope
3. Propose a commit message
4. Ask for confirmation before executing

References

See CONVENTIONS.md for detailed type definitions. See EXAMPLES.md for real-world examples.