1---
2name: commit-forge
3description: 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.
4---
5
6# Commit Forge
7
8Atomic, descriptive git commits. Every commit is one logical change that leaves the codebase working.
9
10## Hard Rules
11
12- **NEVER** commit without the user explicitly asking
13- **NEVER** add co-author tags to commits
14- **NEVER** skip hooks (`--no-verify`, `--no-gpg-sign`)
15- **NEVER** force push to main/master
16- **NEVER** use `git add .` or `git add -A` - stage specific files by name
17- **PREFER** creating a new commit over amending an existing one
18
19## Commit Message Format
20
21```
22type(scope): short description (max 72 chars)
23
24Optional body - what and why, not how.
25
26Optional footer - breaking changes, issue refs.
27```
28
29### Types
30
31| Type | Use For |
32|------|---------|
33| `feat` | New feature or capability |
34| `fix` | Bug fix |
35| `docs` | Documentation only |
36| `refactor` | Code restructuring, no behavior change |
37| `test` | Adding or fixing tests |
38| `chore` | Maintenance, deps, config, CI |
39| `style` | Formatting, no logic change |
40| `perf` | Performance improvement |
41
42### Scope
43
44Use short, lowercase scope matching the area of change. Read the repo's existing commits (`git log --oneline -20`) to match the project's conventions.
45
46### Examples
47
48```
49feat(auth): add JWT refresh token rotation
50
51fix(parser): handle empty broker email attachments
52
53refactor(cli): extract table renderer to shared package
54
55chore: update go dependencies
56
57test(api): add integration tests for driver matching
58```
59
60## Process
61
62### Step 1: Review Changes
63
64```bash
65git status
66git diff
67git diff --staged
68```
69
70Understand what changed before staging anything.
71
72### Step 2: Stage Selectively
73
74Stage files that belong to one logical change:
75
76```bash
77git add src/auth/handler.go
78git add src/auth/handler_test.go
79```
80
81If the diff contains multiple unrelated changes, split into separate commits.
82
83### Step 3: Verify Before Commit
84
85Auto-detect and run the repo's checks:
86
87| Indicator | Command |
88|-----------|---------|
89| `Makefile` with test target | `make test` |
90| `package.json` with test script | `npm test` / `pnpm test` |
91| `go.mod` exists | `go test ./...` |
92| `Cargo.toml` exists | `cargo test` |
93| `pyproject.toml` / `setup.py` | `pytest` |
94
95Only run if tests exist and are fast. Skip if the user explicitly says to commit without testing.
96
97### Step 4: Commit
98
99Write a message that answers "what changed and why" - not "how."
100
101```bash
102git commit -m "feat(auth): add rate limiting to login endpoint"
103```
104
105For complex changes, use a body:
106
107```bash
108git commit -m "refactor(api): split monolithic handler into middleware chain
109
110Request validation, auth, and response formatting were tangled
111in a single 400-line handler. Split into composable middleware
112for independent testing and reuse."
113```
114
115### Step 5: Verify
116
117```bash
118git log --oneline -3
119git show --stat
120```
121
122Confirm the commit looks right.
123
124## What Makes a Good Commit
125
126| Good | Bad |
127|------|-----|
128| One logical change | Multiple unrelated changes |
129| All tests pass | Breaks something |
130| Message says why | Message says "update stuff" |
131| Can be reverted cleanly | Reverting would break other things |
132| Specific files staged | `git add .` |
133
134## What Makes a Bad Commit Message
135
136- "fix stuff" / "update" / "changes" / "WIP"
137- Using "and" to describe two unrelated things
138- Describing how instead of what/why
139- Over 72 characters in the subject line
140
141## Checklist
142
143Before committing:
144
145- [ ] Changes are atomic (one logical unit)
146- [ ] Specific files staged (not `git add .`)
147- [ ] Tests pass (if applicable)
148- [ ] Message follows `type(scope): description` format
149- [ ] No co-author tags
150- [ ] No sensitive files staged (.env, credentials, keys)