commit-forge

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:

• Changes are atomic (one logical unit)
• Specific files staged (not git add .)
• Tests pass (if applicable)
• Message follows type(scope): description format
• No co-author tags
• No sensitive files staged (.env, credentials, keys)