| name | commit-forge |
| description | Write clean, atomic git commits with conventional format. Use when committing code, staging changes, or user says "commit", "commit this", "stage and commit", or is done with a task and needs to commit. NOT for git troubleshooting or branch management. |
Commit Forge
Atomic, descriptive git commits. Every commit is one logical change that leaves the codebase working.
Hard Rules
- NEVER commit without the user explicitly asking
- NEVER add co-author tags to commits
- NEVER skip hooks (
--no-verify, --no-gpg-sign)
- NEVER force push to main/master
- NEVER use
git add . or git add -A - stage specific files by name
- PREFER creating a new commit over amending an existing one
Commit Message Format
type(scope): short description (max 72 chars)
Optional body - what and why, not how.
Optional footer - breaking changes, issue refs.
Types
| Type | Use For |
|---|
feat | New feature or capability |
fix | Bug fix |
docs | Documentation only |
refactor | Code restructuring, no behavior change |
test | Adding or fixing tests |
chore | Maintenance, deps, config, CI |
style | Formatting, no logic change |
perf | Performance improvement |
Scope
Use short, lowercase scope matching the area of change. Read the repo's existing commits (git log --oneline -20) to match the project's conventions.
Examples
feat(auth): add JWT refresh token rotation
fix(parser): handle empty broker email attachments
refactor(cli): extract table renderer to shared package
chore: update go dependencies
test(api): add integration tests for driver matching
Process
Step 1: Review Changes
git status
git diff
git diff --staged
Understand what changed before staging anything.
Step 2: Stage Selectively
Stage files that belong to one logical change:
git add src/auth/handler.go
git add src/auth/handler_test.go
If the diff contains multiple unrelated changes, split into separate commits.
Step 3: Verify Before Commit
Auto-detect and run the repo's checks:
| Indicator | Command |
|---|
Makefile with test target | make test |
package.json with test script | npm test / pnpm test |
go.mod exists | go test ./... |
Cargo.toml exists | cargo test |
pyproject.toml / setup.py | pytest |
Only run if tests exist and are fast. Skip if the user explicitly says to commit without testing.
Step 4: Commit
Write a message that answers "what changed and why" - not "how."
git commit -m "feat(auth): add rate limiting to login endpoint"
For complex changes, use a body:
git commit -m "refactor(api): split monolithic handler into middleware chain
Request validation, auth, and response formatting were tangled
in a single 400-line handler. Split into composable middleware
for independent testing and reuse."
Step 5: Verify
git log --oneline -3
git show --stat
Confirm the commit looks right.
What Makes a Good Commit
| Good | Bad |
|---|
| One logical change | Multiple unrelated changes |
| All tests pass | Breaks something |
| Message says why | Message says "update stuff" |
| Can be reverted cleanly | Reverting would break other things |
| Specific files staged | git add . |
What Makes a Bad Commit Message
- "fix stuff" / "update" / "changes" / "WIP"
- Using "and" to describe two unrelated things
- Describing how instead of what/why
- Over 72 characters in the subject line
Checklist
Before committing:
