commit

**Invoke commit-message skill first** to load formatting conventions:

Skill(git-commit:commit-message)

Do not proceed without loading the skill.

Context

• Branch: !git branch --show-current
• Status: !git status --short
• Staged: !git diff --cached --stat
• Unstaged: !git diff --stat
• Recent commits: !git log --oneline -5

Project Configuration

Projects can define commit requirements in their CLAUDE.md using ``:

<git-commit-config>
<validator-args>
<flag name="require-trailers" value="Task"/>
</validator-args>

<extra-instructions>
Project-specific commit guidance goes here.
</extra-instructions>
</git-commit-config>

Before starting the pipeline, check project CLAUDE.md for <git-commit-config>:

• <validator-args> — Pass all defined flags directly to the validator. Each <flag name="X" value="Y"/> becomes --X "Y" in the command.

• <extra-instructions> — Highest priority guidance for this commit process. Follow these instructions throughout the pipeline. They override defaults.

Commit Pipeline

**One git command per Bash call.** Every Bash invocation must start with `git` or `node`. Never chain commands with `&&`, `||`, or `;`. Never pipe input to git commands. This ensures each call matches `allowed-tools` patterns and runs without manual approval. **Context drift prevention.** Steps like Quality Gate may require fixing code, running tests, or debugging — work that can span many turns. Before executing any git command, verify you haven't lost the pipeline:

1. Am I in the commit pipeline? (If not, return to step 1)
2. Which step am I on?
3. Were prior steps completed?

If uncertain, re-read staged changes with git diff --cached to re-anchor.

1. Identify Atomic Units

Review the diff and identify separate logical changes:

git diff HEAD          # All changes
git diff --cached      # Staged only

**One logical change per commit.** Look for boundaries:

• Different files serving different purposes
• Formatting/style changes mixed with logic changes
• Refactoring mixed with new behavior
• Unrelated bug fixes bundled together

Each independent change becomes its own commit.

2. Plan Commit Order

For each identified unit, classify and order:

• Style (1st) — Formatting, whitespace, naming
• Refactor (2nd) — Code restructuring, no behavior change
• Fix (3rd) — Bug corrections
• Feature (4th) — New functionality
• Docs (any) — Documentation only
• Test (any) — Adding or fixing tests
• Chore (any) — Build, tooling, dependencies

Commit style/refactor first — keeps behavior-changing commits clean.

3. Quality Gate

**Before committing, ensure code quality checks pass.**

1. Review context: Were lint/test/build commands run earlier in this session for the changed files? If yes and they passed, proceed.

2. If not verified: Run appropriate quality checks for the project. Use your knowledge of the codebase to determine what checks apply. Scope to changed files when possible for faster feedback.

3. On failure: Fix issues before proceeding. Do not commit broken code.

4. On success: Continue to self-review.

After returning from fixes: Re-read <pipeline-awareness> above. Verify you're resuming at step 4, not starting over or skipping steps.

4. Self-Review Before Commit

Before each commit, verify:

• Diff contains only intended changes (no debug code, temp files)
• Changes match the commit message you're about to write
• No unrelated changes bundled together
• Sensitive data excluded (.env, credentials, secrets)

git diff --cached      # Review exactly what will be committed

5. Stage Files

For each logical unit:

git add <files>

Do not use git add -p or pipe input to interactive commands — these break tool permission matching. Stage by explicit file path. If a file contains mixed changes, split it in a prior refactoring commit or accept the broader staging.

6. Validate Message

**Before committing, validate the message against conventions:**

node ${CLAUDE_PLUGIN_ROOT}/scripts/validate-commit-message.js [validator-args] --msg "<commit-message>"

• If <validator-args> exists in project config, include those flags
• Fix any ERROR issues before proceeding
• WARN issues are recommendations — address if reasonable
• Do not commit until validation passes without errors

7. Commit

Before executing git commit, display the full message as a blockquote.

Then commit:

git commit -m "<validated-message>"

8. Verify

After committing, run each as a separate Bash call:

git log -1 --stat

git status

Breaking Changes

When a commit breaks backward compatibility:

1. **Prefer incremental migration:** - Add new code without removing old - Migrate callers from old to new - Remove old code when no callers remain

2. If breaking in single commit:
   • Start body with BREAKING: prefix
   • Explain what breaks and migration path
   • Link to migration docs if available

Output

After completing all commits, show:

• List of created commits with subjects
• Current branch status
• Any remaining uncommitted changes