| name | atomic-commits |
| description | Creates semantic atomic commits using Conventional Commits. Use always when committing changes, staging files, or when asked to commit code. Analyzes diffs, suggests scope, and can split changes into granular commits. |
| allowed-tools | Bash, Read, Glob, Grep, AskUserQuestion |
Atomic Commits
Creates well-structured, semantic commits following Conventional Commits specification. Automatically analyzes changes and creates atomic, focused commits.
Core Principles
- Atomic: Each commit represents ONE logical change
- Semantic: Type prefix describes the nature of the change
- Scoped: Optional scope indicates the affected module/component
- 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:apicore/database.py→ scope:dbagents/faq_agent/→ scope:faq-agenttests/→ 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:
- Preparation: Refactoring needed before the feature
- Core: The main feature/fix implementation
- Tests: New or updated tests
- 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:
- Show the user what will be committed (files and diff summary)
- Suggest the commit type and scope
- Propose a commit message
- Ask for confirmation before executing
References
See CONVENTIONS.md for detailed type definitions. See EXAMPLES.md for real-world examples.