tomevault-io Commit
Purpose
Create standardized, semantic git commits using the Conventional Commits specification. Analyze the actual diff to determine appropriate type, scope, and message. Enforces project-specific rules: no AI attribution, no ticket references, no emojis.
Quick Reference
- Creates: Git commit with conventional message
- Requires: Staged or unstaged changes
- Stop hook:
task claude:validate-skill -- --skill commit
Conventional Commit Format
<type>(<scope>): <subject>
<optional body - 1-2 sentences or omit>
Commit Types
| Type | Purpose |
|---|---|
feat |
New feature |
fix |
Bug fix |
docs |
Documentation only |
style |
Formatting/style (no logic) |
refactor |
Code refactor (no feature/fix) |
perf |
Performance improvement |
test |
Add/update tests |
build |
Build system/dependencies |
ci |
CI/config changes |
chore |
Maintenance/misc |
revert |
Revert commit |
Project Rules (MUST VERIFY)
- Title ≤ 50 characters
- Title is SPECIFIC (avoid vague: "improve", "enhance", "update")
- NO AI attribution (see policy below)
- NO ticket references in body (no "Fixes #123", "Part of NOD-XXX")
- NO emojis in commit message
- Body: 1-2 sentences max, or omit if title is clear
- Focus on WORK done, not file operations
AI Attribution Policy
STRICTLY FORBIDDEN - Never include ANY of the following in commit messages:
Co-Authored-By: Claude,Co-Authored-By: GPT, or any AI name- 🤖 emoji or any AI-related emojis
- "Generated by", "Created with", or similar phrases
- Any reference to AI tools (Claude, ChatGPT, Copilot, etc.)
Commits must appear as human-authored work. This is a strict project requirement.
Changelog Awareness
When writing commit messages, consider if the change is changelog-worthy. This helps during PR review and release notes generation.
Important: The type alone doesn't determine this. Any type can be changelog-worthy depending on impact.
Changelog-worthy (user-facing)
Focus on user/product impact:
- What capability was added or fixed?
- How does this affect the product or end users?
Examples:
feat(plugins): add validator ban detection
fix(app): prevent duplicate notifications
docs: add API authentication guide
chore(deps): upgrade axios to fix security vulnerability
Internal/dev-only (not in changelog)
Focus on developer/process impact:
- What tooling or process changed?
- No user-facing impact
Examples:
chore(skills): add commit validation
test(plugins): add integration tests
ci: add parallel test execution
docs: update development setup instructions
Workflow
0. Branch Validation (REQUIRED)
# MUST check branch first - refuse to commit on main/master
BRANCH=$(git branch --show-current)
if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
echo "ERROR: Cannot commit directly to $BRANCH"
echo "Create a feature branch: git checkout -b <branch-name>"
# STOP - do not proceed
fi
1. Analyze Changes
# Check status first
git status --porcelain
# If files are staged, use staged diff
git diff --staged
# If nothing staged, use working tree diff
git diff
2. Stage Files (if needed)
If nothing is staged, ask user what to stage:
# Stage specific files
git add path/to/file1 path/to/file2
# Stage by pattern
git add *.test.*
git add src/components/*
Never commit secrets (.env, credentials.json, private keys).
3. Generate Commit Message
Analyze the diff to determine:
- Type: What kind of change is this?
- Scope: What area/module is affected? (e.g., plugins, skills, config)
- Description: One-line summary of what changed (present tense, imperative mood)
4. User Review
ALWAYS confirm before committing:
- Show the generated commit message
- Ask: "Commit with this message? (y/n)"
- If yes: proceed to execute commit
- If no: ask "Any changes I should make?" and revise based on feedback
5. Execute Commit
# Single line
git commit -m "<type>(<scope>): <description>"
# Multi-line with body (use HEREDOC)
git commit -m "$(cat <<'EOF'
<type>(<scope>): <description>
<body - 1-2 sentences explaining why>
EOF
)"
Examples
Good:
feat(plugins): add parallel worker support
Workers can now run concurrently with independent configs.
fix(skills): handle missing validation file gracefully
Bad:
chore(config): update configuration(vague - what update?)feat(api): improve API performance(vague - how?)docs(plans): add implementation plan(focus on file, not work)
Git Safety Protocol
- NEVER commit directly to main/master - always use a feature branch
- NEVER update git config
- NEVER run destructive commands (--force, hard reset) without explicit request
- NEVER skip hooks (--no-verify) unless user asks
- NEVER force push to main/master
- If commit fails due to hooks, fix the issue and create NEW commit (don't amend)
Branch Check (MUST RUN FIRST)
Before any commit operation, verify you're not on main:
BRANCH=$(git branch --show-current)
if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
echo "ERROR: Cannot commit directly to $BRANCH. Create a feature branch first."
exit 1
fi
Automation
See skill.yaml for patterns and procedure.
See sharp-edges.yaml for common pitfalls.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.