OpenParable
Skip to content
← Back to skills

Engram Commit Hygiene

Development
engram-commit-hygiene

Engram Commit Hygiene is an Agent Skill for development published in the Gentleman-Programming/engram repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Commit and branch naming standards for Engram contributors, enforced by GitHub rulesets. Trigger: Any commit creation, review, or branch cleanup.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/Gentleman-Programming/engram/blob/HEAD/skills/commit-hygiene/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/engram-commit-hygiene, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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

  1. Commit messages MUST follow Conventional Commits — enforced by GitHub ruleset, rejected on push if invalid
  2. Branch names MUST follow type/description format — enforced by GitHub ruleset, rejected on push if invalid
  3. Keep one logical change per commit
  4. Message should explain why, not only what
  5. NEVER include Co-Authored-By trailers
  6. 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

TypePurpose
featNew feature
fixBug fix
docsDocumentation only
refactorCode refactoring (no behavior change)
choreMaintenance, dependencies
styleFormatting, whitespace
perfPerformance improvement
testAdding or fixing tests
buildBuild system changes
ciCI/CD pipeline changes
revertRevert 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

  • Commit message matches conventional commits format
  • Branch name matches type/description format
  • Diff matches commit scope (no unrelated changes)
  • No secrets, credentials, or .env files
  • No binaries, coverage outputs, or local artifacts
  • No Co-Authored-By trailers
  • Tests relevant to the change pass