When to Use
Use this skill when:
- Creating commits
- Creating or naming branches
- Reviewing commit history in a PR
- Cleaning up staged changes
Critical Rules
- Commit messages MUST follow Conventional Commits — enforced by GitHub ruleset, rejected on push if invalid
- Branch names MUST follow
type/description format — enforced by GitHub ruleset, rejected on push if invalid
- Keep one logical change per commit
- Message should explain why, not only what
- NEVER include
Co-Authored-By trailers
- NEVER commit generated/temp/local files
Commit Message Format (enforced by GitHub ruleset)
Regex: ^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\([a-z0-9\._-]+\))?!?: .+
<type>(<optional-scope>): <description>
<type>(<optional-scope>)!: <description> ← breaking change
Allowed Types
| Type |
Purpose |
feat |
New feature |
fix |
Bug fix |
docs |
Documentation only |
refactor |
Code refactoring (no behavior change) |
chore |
Maintenance, dependencies |
style |
Formatting, whitespace |
perf |
Performance improvement |
test |
Adding or fixing tests |
build |
Build system changes |
ci |
CI/CD pipeline changes |
revert |
Revert a previous commit |
Rules
- Type MUST be lowercase, one of the listed values
- Scope is optional, lowercase, allows
a-z, 0-9, ., _, -
! before : marks a breaking change
- Description MUST start after
: (colon + space)
- Description should be imperative mood ("add", not "added" or "adds")
Valid Examples
feat(cli): add --json flag to session list command
fix(store): prevent duplicate observation insert on retry
docs(contributing): update workflow documentation
refactor(internal): extract search query sanitizer
chore(deps): bump github.com/charmbracelet/bubbletea to v0.26
style(tui): fix alignment in session detail view
perf(store): optimize FTS5 query for large datasets
test(sync): add coverage for conflict resolution
ci(workflows): split e2e into separate job
fix!: change session ID format
Invalid Examples (push will be rejected)
Fix bug ← no type prefix
feat: Add login ← description should be lowercase
FEAT(cli): add flag ← type must be lowercase
feat (cli): add flag ← no space before scope
feat(CLI): add flag ← scope must be lowercase
update docs ← no conventional commit format
Branch Naming Format (enforced by GitHub ruleset)
Regex: ^(feat|fix|chore|docs|style|refactor|perf|test|build|ci|revert)\/[a-z0-9._-]+$
<type>/<description>
Allowed Types
feat, fix, chore, docs, style, refactor, perf, test, build, ci, revert
Rules
- Type MUST be one of the listed values
- Description MUST be lowercase
- Only
a-z, 0-9, ., _, - allowed in description
- No uppercase, no spaces, no special characters
Valid Examples
feat/json-export-command
fix/duplicate-observation-insert
docs/api-reference-update
refactor/extract-query-sanitizer
chore/bump-bubbletea-v0.26
ci/split-e2e-job
Invalid Examples (push will be rejected)
feature/add-login ← "feature" not allowed, use "feat"
fix/Add-Login ← uppercase not allowed
my-branch ← no type prefix
fix_something ← missing "/" separator
Pre-Commit Checklist
1---2name: engram-commit-hygiene3description: >4 Commit and branch naming standards for Engram contributors, enforced by GitHub rulesets.5 Trigger: Any commit creation, review, or branch cleanup.6license: Apache-2.07metadata:8 source: https://skillmd.com/skills/gentleman-programming-engram/engram-commit-hygiene9 author: gentleman-programming10 version: "2.0"11---1213## When to Use1415Use this skill when:16- Creating commits17- Creating or naming branches18- Reviewing commit history in a PR19- Cleaning up staged changes2021---2223## Critical Rules24251. **Commit messages MUST follow Conventional Commits** — enforced by GitHub ruleset, rejected on push if invalid262. **Branch names MUST follow `type/description` format** — enforced by GitHub ruleset, rejected on push if invalid273. Keep one logical change per commit284. Message should explain **why**, not only what295. **NEVER** include `Co-Authored-By` trailers306. **NEVER** commit generated/temp/local files3132---3334## Commit Message Format (enforced by GitHub ruleset)3536**Regex:** `^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\([a-z0-9\._-]+\))?!?: .+`3738```39<type>(<optional-scope>): <description>40<type>(<optional-scope>)!: <description> ← breaking change41```4243### Allowed Types4445| Type | Purpose |46|------|---------|47| `feat` | New feature |48| `fix` | Bug fix |49| `docs` | Documentation only |50| `refactor` | Code refactoring (no behavior change) |51| `chore` | Maintenance, dependencies |52| `style` | Formatting, whitespace |53| `perf` | Performance improvement |54| `test` | Adding or fixing tests |55| `build` | Build system changes |56| `ci` | CI/CD pipeline changes |57| `revert` | Revert a previous commit |5859### Rules60- Type MUST be lowercase, one of the listed values61- Scope is optional, lowercase, allows `a-z`, `0-9`, `.`, `_`, `-`62- `!` before `:` marks a breaking change63- Description MUST start after `: ` (colon + space)64- Description should be imperative mood ("add", not "added" or "adds")6566### Valid Examples67```68feat(cli): add --json flag to session list command69fix(store): prevent duplicate observation insert on retry70docs(contributing): update workflow documentation71refactor(internal): extract search query sanitizer72chore(deps): bump github.com/charmbracelet/bubbletea to v0.2673style(tui): fix alignment in session detail view74perf(store): optimize FTS5 query for large datasets75test(sync): add coverage for conflict resolution76ci(workflows): split e2e into separate job77fix!: change session ID format78```7980### Invalid Examples (push will be rejected)81```82Fix bug ← no type prefix83feat: Add login ← description should be lowercase84FEAT(cli): add flag ← type must be lowercase85feat (cli): add flag ← no space before scope86feat(CLI): add flag ← scope must be lowercase87update docs ← no conventional commit format88```8990---9192## Branch Naming Format (enforced by GitHub ruleset)9394**Regex:** `^(feat|fix|chore|docs|style|refactor|perf|test|build|ci|revert)\/[a-z0-9._-]+$`9596```97<type>/<description>98```99100### Allowed Types101102`feat`, `fix`, `chore`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `revert`103104### Rules105- Type MUST be one of the listed values106- Description MUST be lowercase107- Only `a-z`, `0-9`, `.`, `_`, `-` allowed in description108- No uppercase, no spaces, no special characters109110### Valid Examples111```112feat/json-export-command113fix/duplicate-observation-insert114docs/api-reference-update115refactor/extract-query-sanitizer116chore/bump-bubbletea-v0.26117ci/split-e2e-job118```119120### Invalid Examples (push will be rejected)121```122feature/add-login ← "feature" not allowed, use "feat"123fix/Add-Login ← uppercase not allowed124my-branch ← no type prefix125fix_something ← missing "/" separator126```127128---129130## Pre-Commit Checklist131132- [ ] Commit message matches conventional commits format133- [ ] Branch name matches `type/description` format134- [ ] Diff matches commit scope (no unrelated changes)135- [ ] No secrets, credentials, or `.env` files136- [ ] No binaries, coverage outputs, or local artifacts137- [ ] No `Co-Authored-By` trailers138- [ ] Tests relevant to the change pass