| name | smart-commits |
| description | Intelligent multi-commit workflow — Analyze all pending changes (staged, unstaged, untracked), group related edits into logical units, and create multiple focused commits. Use when the user asks to: (1) commit their changes, (2) create commits from their work, (3) split changes into multiple commits, (4) organize or clean up their git history, or when there are many modified files that should not be a single commit. |
Smart Commits
Analyze all pending changes in the working tree, group related edits into logical commits, and execute them as a clean sequence.
Workflow
- Assess all changes
- Group into logical units
- Present the plan
- Execute commits sequentially
Step 1: Assess Changes
Run these in parallel:
git status — see all modified, staged, and untracked filesgit diff — unstaged changes with full contextgit diff --cached — already-staged changesgit log --oneline -5 — recent commit style reference
Read the diffs carefully. Understand what each file change actually does, not just that it changed.
Step 2: Group Into Logical Units
Analyze the changes and cluster them by intent — what goal does each edit serve?
Grouping rules:
- Changes to the same feature/component belong together
- A new file and the imports/references that wire it in belong together
- Test changes go with the code they test
- Config changes go with the feature that needs them
- Pure formatting/linting changes get their own commit
- Dependency additions/removals get their own commit
- Unrelated bug fixes each get their own commit
Single-commit case: If all changes serve one clear purpose, use one commit. Do not force artificial splits.
Step 3: Present the Plan
Show the proposed commit sequence before executing:
Proposed commits:
1. Add user avatar upload endpoint
- src/api/avatar.ts (new)
- src/api/routes.ts (modified — added avatar route)
- src/types/user.ts (modified — added avatarUrl field)
2. Update profile page to display avatars
- src/components/Profile.tsx (modified)
- src/styles/profile.css (modified)
3. Add avatar upload tests
- tests/api/avatar.test.ts (new)
Wait for user confirmation. Adjust if requested.
Step 4: Execute Commits
For each group, in order:
- Stage only the files for that commit:
git add <file1> <file2> ...
- Commit with a descriptive message using a HEREDOC
- Verify with
git status before moving to the next group
Note: git add -p (interactive) is not supported. Stage full files in the most relevant commit.
Commit Message Rules
Format:
<what changed> in <where/scope>
<why — one or two lines only if subject isn't self-explanatory>
Style:
- Imperative mood, 50–72 character subject line
- Be specific: "Add retry logic to payment webhook handler" not "Update handler"
- Be direct: state what was done without filler
- No period at end of subject line
- Body only when the "why" isn't obvious
- NEVER include "Co-Authored-By", "Generated by AI", or any AI attribution
- NEVER use filler like "various improvements" or "minor changes"
Good examples:
Add rate limiting to /api/auth endpoints
Prevent brute-force login attempts with 5 req/min per IP limit
using the existing Redis instance.
Fix currency rounding in invoice total calculation
Extract shared validation logic into FormValidator utility
Bad examples:
Update files ← too vague
Fix bug ← which bug?
Refactoring and cleanup ← says nothing
Add feature and fix styling ← should be separate commits
Edge Cases
- All changes are one unit — one commit is fine, don't force splits
- User has already staged files — respect their staging, incorporate into the plan
- Binary/generated files — ask before including lock files or build artifacts
- Sensitive files (
.env, credentials) — warn and exclude by default
