tomevault-io Git Commit Guidelines
This skill enforces git commit best practices for the Packmind project, combining gitmoji for visual commit type identification with Conventional Commits format.
TRIGGER CHECKLIST - Read This First
TRIGGER THIS SKILL WHEN:
- User asks you to commit changes
- User asks you to create a commit
- You are about to run
git commit - User says "commit this" or similar
TRIGGER IMMEDIATELY - before running any git commit command.
Failure Examples - What NOT To Do
Failure 1: Committing Without User Permission
User: "Fix the bug in the login function"
AI: [Fixes the bug]
AI: [Runs git commit directly without asking] ❌
CORRECT BEHAVIOR:
AI: [Fixes the bug]
AI: [Asks user: "Ready to commit. Here's the proposed message: ..."]
AI: [Waits for user approval]
AI: [Then commits]
Failure 2: Using Close/Fix Before Issue References
AI: git commit -m "Fix login bug
Closes #123" ❌
CORRECT BEHAVIOR:
AI: git commit -m "Fix login bug
#123" ✓
Failure 3: Skipping Quality Gate
AI: [Makes changes]
AI: [Commits immediately without running quality-gate] ❌
CORRECT BEHAVIOR:
AI: [Makes changes]
AI: [Runs npm run quality-gate]
AI: [Fixes any issues]
AI: [Then proposes commit]
Failure 4: Missing Gitmoji
AI: git commit -m "feat(auth): add login validation" ❌
CORRECT BEHAVIOR:
AI: git commit -m "✨ feat(auth): add login validation" ✓
Commit Message Format
<gitmoji> <type>(<scope>): <subject>
<body>
<issue-reference>
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Format Rules
| Element | Rule |
|---|---|
| Language | Required. All commit messages MUST be written in English |
| Gitmoji | Required. Must match the commit type |
| Type | Required. One of: feat, fix, refactor, docs, test, chore, style, perf, security, remove, move, deps |
| Scope | Optional. Component or module affected (e.g., auth, api, ui) |
| Subject | Required. Imperative mood, no period, max 72 chars |
| Body | Optional. Bullet points with - prefix for multiple changes |
| Issue Reference | Optional. Use #123 format. NEVER prefix with "Close", "Fix", or "Resolve" |
| Co-Author | Required for AI-assisted commits |
Gitmoji Reference Table
| Gitmoji | Type | Description | Example |
|---|---|---|---|
| ✨ | feat | New feature | ✨ feat(auth): add OAuth2 support |
| 🐛 | fix | Bug fix | 🐛 fix(api): handle null response |
| ♻️ | refactor | Code refactoring | ♻️ refactor(core): extract helper function |
| 📝 | docs | Documentation | 📝 docs: update API reference |
| ✅ | test | Adding/updating tests | ✅ test(auth): add login tests |
| 🔧 | chore | Maintenance tasks | 🔧 chore: update dependencies |
| 🎨 | style | Code formatting | 🎨 style: apply prettier formatting |
| ⚡️ | perf | Performance improvement | ⚡️ perf(query): optimize database calls |
| 🔒️ | security | Security fix | 🔒️ security: sanitize user input |
| 🗑️ | remove | Removing code/files | 🗑️ remove: delete deprecated endpoint |
| 🚚 | move | Moving/renaming files | 🚚 move: relocate utils to shared |
| 📦 | deps | Dependencies | 📦 deps: upgrade React to v19 |
7-Step Commit Workflow
Step 1: Complete Work
Ensure all changes are complete and the feature/fix is working.
Step 2: Run Quality Gate
npm run quality-gate
MANDATORY: This must pass before committing. Fix any issues found.
Step 3: Review Changes
Run these commands to understand what will be committed:
git status
git diff --staged
If changes aren't staged, stage them first:
git add <files>
Step 4: Prepare Commit Message
Compose the commit message following the format above:
- Choose the appropriate gitmoji based on the change type
- Write a clear subject line in imperative mood
- Add body with bullet points if multiple changes
- Include issue reference WITHOUT "Close/Fix/Resolve" prefix
- Add Co-Authored-By footer
Step 5: Ask User for Permission (MANDATORY)
NEVER skip this step. Present the commit to the user:
Ready to commit. Here's the proposed message:
<full commit message>Do you want me to proceed with this commit?
Wait for explicit user approval.
Step 6: Create Commit
Use HEREDOC format to preserve formatting:
git commit -m "$(cat <<'EOF'
✨ feat(scope): subject line here
- First change description
- Second change description
#123
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
EOF
)"
NEVER use --no-verify
Step 7: Verify Commit
After committing, verify it was successful:
git log -1 --pretty=format:"%h %s"
git status
Example Scenarios
Example 1: Simple Bug Fix
✨ Staged changes: Fixed null check in user service
✅ Commit message:
🐛 fix(user): handle null user in getProfile
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Example 2: New Feature with Issue Reference
✨ Staged changes: Added export functionality to reports
✅ Commit message:
✨ feat(reports): add CSV export functionality
- Add export button to report toolbar
- Implement CSV generation service
- Add download trigger
#456
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Example 3: Refactoring with Multiple Changes
✨ Staged changes: Refactored authentication module
✅ Commit message:
♻️ refactor(auth): extract token validation logic
- Move validation to dedicated service
- Add unit tests for edge cases
- Update imports across modules
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Example 4: Documentation Update
✨ Staged changes: Updated README with new setup instructions
✅ Commit message:
📝 docs: update installation instructions
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Example 5: Test Addition
✨ Staged changes: Added tests for payment service
✅ Commit message:
✅ test(payment): add unit tests for refund flow
- Test successful refund scenario
- Test partial refund handling
- Test refund validation errors
#789
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Example 6: Dependency Update
✨ Staged changes: Upgraded TypeScript to v5.3
✅ Commit message:
📦 deps: upgrade TypeScript to 5.3
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Example 7: File Move/Rename
✨ Staged changes: Moved utility functions to shared package
✅ Commit message:
🚚 move: relocate date utils to shared package
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Example 8: Security Fix
✨ Staged changes: Fixed XSS vulnerability in comment input
✅ Commit message:
🔒️ security(comments): sanitize HTML in user input
#security-audit
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Important Guidelines
DO
- ✅ Always write commit messages in English
- ✅ Always run
npm run quality-gatebefore committing - ✅ Always ask for user permission before committing
- ✅ Always use gitmoji matching the commit type
- ✅ Always include
Co-Authored-Byfor AI-assisted commits - ✅ Always verify the commit was successful with
git log -1 - ✅ Use imperative mood in subject line ("add" not "added")
- ✅ Keep subject line under 72 characters
- ✅ Use bullet points with
-for multi-line bodies - ✅ Reference issues with just
#123format
DO NOT
- ❌ Never write commit messages in languages other than English (e.g., French, Spanish, etc.)
- ❌ Never commit without user approval
- ❌ Never use
--no-verifyflag - ❌ Never use "Close", "Fix", or "Resolve" before issue numbers
- ❌ Never skip quality-gate check
- ❌ Never use
git commit --amendunless explicitly requested - ❌ Never force push to main/master
- ❌ Never commit files containing secrets (.env, credentials.json)
- ❌ Never forget the gitmoji prefix
- ❌ Never use past tense in subject ("fixed" → "fix")
Quick Reference Card
┌─────────────────────────────────────────────────────────────┐
│ GIT COMMIT QUICK REFERENCE │
├─────────────────────────────────────────────────────────────┤
│ FORMAT: │
│ <gitmoji> <type>(<scope>): <subject> │
│ │
│ GITMOJI: │
│ ✨ feat 🐛 fix ♻️ refactor 📝 docs │
│ ✅ test 🔧 chore 🎨 style ⚡️ perf │
│ 🔒️ security 🗑️ remove 🚚 move 📦 deps │
│ │
│ WORKFLOW: │
│ 1. npm run quality-gate │
│ 2. git status && git diff --staged │
│ 3. Prepare message with gitmoji │
│ 4. ASK USER PERMISSION │
│ 5. git commit (use HEREDOC) │
│ 6. git log -1 (verify) │
│ │
│ RULES: │
│ • Always write in English │
│ • Always ask permission before committing │
│ • Never use Close/Fix/Resolve before #issue │
│ • Never use --no-verify │
│ • Always include Co-Authored-By footer │
└─────────────────────────────────────────────────────────────┘
REMEMBER: This skill is MANDATORY when creating commits. Always run quality-gate, always ask for permission, and always use gitmoji. These steps ensure code quality and maintain a clean, informative git history.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.