Commit Forge

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)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: alxxpersonal
• Source: alxxpersonal/forge
• License: MIT

Install and usage instructions live in the source repository linked above.