/git-commit

name: git-commit
description: Commit work the right way by gathering full repo state, respecting the project's commitlint/pre-commit/branch rules, staging only understood files, and writing a conventional-commit message whose body explains why. Use when committing, branching, or pushing changes.
argument-hint: "(optional) ticket/issue ref, scope, or what to commit"

Turn a set of changes into a clean, conventional commit (and push, if asked). Work from the actual repo state and the project's own rules, never from assumptions about what the change "probably" is.

Hard rules: never break these

• **No co-authors, ever.** Never add a `Co-Authored-By:` trailer. Never mention Claude, Claude Code, or any AI in a commit message, body, or branch name. The message must read as if a human engineer wrote it.
• **Commit only when asked.** Do not commit mid-task, opportunistically, or "to be safe." Wait for an explicit instruction to commit. One commit per request unless the user asks for more.
• **Confirm before `git commit` and `git push`.** State exactly what you're about to commit (files + message) or push (branch + remote) and get a yes first. These are not reversible-for-free; treat them as outward-facing.
• **Never `git add -A` or `git add .`.** Stage files explicitly by path, and only files you've inspected and understood.
• **Never commit ignored or generated content.** No `node_modules`, build output, `.env`/secrets/keys, lockfile churn you didn't intend, or generated artifacts (plans, reports, analyses, summaries, scratch notes). Source-code changes only; anything else needs an explicit ask.

Step 1: Gather full context

Build a complete picture before touching anything. Run these (read-only) and actually read the output:

• `git status`: what's modified, staged, untracked.
• `git diff` (unstaged) and `git diff --staged` (staged): the actual changes, line by line.
• `git branch --show-current` and `git branch -a`: where you are and what exists.
• `git log --oneline -15`: the repo's established message and scope style; match it.
• `git status --ignored`: confirm nothing sensitive or generated is sneaking in, and that `.gitignore` already covers `node_modules`, build dirs, env files, etc.

If something is untracked that *should* be ignored (secrets, env, build output, dependencies), flag it and suggest a `.gitignore` entry rather than committing it.

Step 2: Discover and honor the project's rules

Repos enforce their own conventions; find and obey them before writing anything:

• **Commit-message linting**: look for `commitlint.config.{js,cjs,mjs,ts}`, `.commitlintrc*`, a `commitlint` key in `package.json`, or equivalents in other ecosystems. Read the allowed types/scopes and subject limits and conform exactly.
• **Pre-commit / hooks**: check `.pre-commit-config.yaml`, `.husky/`, `.git/hooks/`, `lefthook.yml`, or framework equivalents. The commit must pass these. Don't bypass with `--no-verify`; if a hook fails, fix the cause (formatting, lint, tests) and report it.
• **Branch-name rules**: some repos lint branch names too (in commitlint config, hooks, or CONTRIBUTING). Conform.
• **Contributor docs**: skim `CONTRIBUTING*` and any PR/commit template for additional expectations.

When the repo's rules conflict with the defaults below, the repo wins.

Step 3: Stage logically

• Group **related** changes into one commit; split **unrelated** changes into separate commits. A commit should be one coherent idea.
• Stage by explicit path (`git add path/to/file`), reviewing each. Use `git add -p` to split mixed files into logical hunks.
• Leave out incidental churn, debug leftovers, and anything from the "never commit" list.

Step 4: Branch (when needed)

If the work doesn't belong on the current branch (e.g. you're on `main`/`master` or a release branch), create one off the up-to-date main branch. Naming convention:

| Prefix | When to use | | ----------- | ----------------------------------------------- | | `feat/` | New feature | | `fix/` | Bug fix | | `chore/` | Maintenance, dependencies, config | | `docs/` | Documentation only | | `refactor/` | Code change that isn't a fix or feature | | `test/` | Adding or updating tests |

Use short, kebab-case descriptions: `feat/task-dependency-api`, `fix/refresh-token-expiry`, `docs/update-contributing`, `chore/upgrade-prisma`. Honor any stricter rule found in Step 2.

Step 5: Write the commit message

**Subject line**: `type(scope): summary`

• Use a Conventional Commits type: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert` (or whatever the repo's commitlint permits).
• Scope is optional but helps: `feat(auth): …`.
• Imperative mood, lowercase after the colon, no trailing period. Keep it **≤ 72 characters** (aim for ~50).
• Mark breaking changes with `!`: `feat(api)!: drop v1 token endpoint`.

**Body: explain *why*, not *what*.** The diff already shows what changed; the body exists for future code archaeology. Wrap at ~72 columns. Cover, in prose:

• **Why this change was needed**: the motivation, the trigger, the constraint.
• **The problem it solves**: the business or technical pain being addressed.
• Include a terse *what* only when the change is non-obvious from the diff.

**Footer**

• Reference tickets/issues exactly as the project does. Inline in the subject when natural (`fix(auth): handle token expiry (#42)`) and/or as footers: `Closes #42`, `Refs JIRA-1234`, `ClickUp: CU-abc`.
• If the user mentions any Jira/issue/ClickUp/tracker ID, it **must** appear in the commit.
• Breaking changes get a `BREAKING CHANGE: <description>` footer.

Template (adapt, don't pad with empty sections):

type(scope): concise imperative subject (#123)

Why: the motivation or constraint tha