Commit

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:

1. Show the generated commit message
2. Ask: "Commit with this message? (y/n)"
3. If yes: proceed to execute commit
4. 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.