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

code

<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:

code

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:

code

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)

bash

# 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

bash

# 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:

bash

# 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

bash

# 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:

code

feat(plugins): add parallel worker support

Workers can now run concurrently with independent configs.

code

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:

bash

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.