commit

What this skill does

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

```
Skill(git-commit:commit-message)
```

Do not proceed without loading the skill.

</prerequisite>

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

<project-config>
Projects can define commit requirements in their CLAUDE.md using `<git-commit-config>`:

```xml
<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. </project-config>

## Commit Pipeline

<command-format>
**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.
</command-format>

<pipeline-awareness>
**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. </pipeline-awareness>

### 1. Identify Atomic Units

Review the diff and identify **separate logical changes**:

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

<atomic-commit-rule>
**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. </atomic-commit-rule>

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

<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. </quality-gate>

### 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)
- [ ] Message has no filler tics ("this commit", "I", "we", "now"), no promotional adjectives, no scope-restating

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

### 5. Stage Files

For each logical unit:

```bash
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

<mandatory>
**Before committing, validate the message against conventions:**

```bash
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
  </mandatory>

### 7. Commit

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

Then commit:

```bash
git commit -m "<validated-message>"
```

### 8. Verify

After committing, run each as a **separate Bash call**:

```bash
git log -1 --stat
```

```bash
git status
```

## Breaking Changes

When a commit breaks backward compatibility:

<breaking-change-process>
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 </breaking-change-process>

## Output

After completing all commits, show:

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