/commit

name: commit
description: 'Use when asked to commit changes, create a typed branch, format history for a changelog, or rewrite messages of HEAD or an unpushed range. Not for pushing or a PR: use commit-push-pr.'

Git commit

Shape commit messages to repository conventions. Two modes: `create` (default) stages and commits working-tree changes as typed, atomic commits; `rewrite` rewords the messages of existing commits over `HEAD` or a short unpushed range while the tree stays byte-identical.

Contract

| Field | Bound contract | |---|---| | Trigger | Create: user asks to commit or save staged or unstaged changes, create a typed branch, or format history for changelog generation. Rewrite: user asks to clean up a finished commit message or bring messages of `HEAD` or a short unpushed range to handoff-ready form. | | Authority | Reversible local: create writes only the local index, a local feature branch, and local commits; rewrite writes only local commit messages, shows the exact commit set before mutation, and never creates or suggests a new commit; rollback is version control, and for rewrite the reflog and the original refs. No remote mutation. | | Side effect | Create: local working tree, local index, local branch refs, and local commit objects; rollback `git reset --hard <prior-HEAD>` discards new commits and `git branch -D <created-branch>` removes a branch this skill created. Rewrite: commit messages only; the tree stays byte-identical; each rewritten commit is re-signed with its author and committer dates preserved by position. Local history only. | | Done | Create: each logical concern is committed with a value-communicating message; `git status` confirms success; commit hashes and subjects are reported; history is parseable and auto-generates changelogs, SemVer bumps, and issue closes. Rewrite: `git diff <old>..<new>` is empty, each rewritten commit is signed with the intended dates by position, and `git log` alone carries the handoff with the diff hidden. |

Inputs

• `mode`: `create` (default) or `rewrite`.
• Current working tree state (`git status`, `git diff HEAD`): required in create mode, gathered by the skill.
• Current branch and recent commit history (`git branch --show-current`, `git log --oneline -10`): required, gathered by the skill.
• Resolved remote default branch (`git rev-parse --abbrev-ref origin/HEAD`): optional; falls back to `gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'`, then to `main`.
• Repo commit-message convention in already-loaded project instructions: optional; used directly without re-reading.
• An issue or tracker number, when one exists: optional; prefixed into the branch name and referenced in the commit footer.
• The target platform (GitHub or GitLab): required only when closing issues cross-repo or cross-project.
• User decision on creating a feature branch in detached HEAD state: required only in create mode when the repo is in detached HEAD.
• Rewrite: the target commit or range, `HEAD` (default) or a short unpushed range (`HEAD~N..HEAD`); the intended message text for each target, supplied by the user or derived from the existing message, never invented; confirmation when any target commit is already pushed to a shared remote, required before proceeding.

Procedure

1. Select the mode. `rewrite` when the user asks to clean up or reword existing commit messages; `create` otherwise. Done when: the mode is selected and its inputs are present or the missing one is reported. 2. Gather context: run `git status`, `git diff HEAD`, `git branch --show-current`, `git log --oneline -10`, and `git rev-parse --abbrev-ref origin/HEAD 2>/dev/null || echo DEFAULT_BRANCH_UNRESOLVED`. Strip the `origin/` prefix from the default branch. If it returned `DEFAULT_BRANCH_UNRESOLVED` or bare `HEAD`, try `gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'`; if that also fails, use `main`. Done when: working tree state, branch, recent history, and default branch are known. 3. Determine the commit message convention in priority order: (1) repo conventions in already-loaded project instructions, used directly; (2) a clear pattern in the recent commits from step 2 (conventional commits, ticket prefixes, emoji); (3) the seven-rule style: capitalized imperative subject, 50 chars target and 72 hard, no trailing period, blank line, body wrapped at 72 explaining what and why, never how. If source (1) or (2) uses conventional commits, format the subject as `<type>(<scope>): <subject>` (scope optional) and pick the most precise type from the allowed set with its SemVer effect: `feat` (MINOR), `fix` (PATCH), `docs`, `test`, `build`, `ci`, `chore`, `style` (formatting with no logic change), `ref` or `refactor` (refactoring with no behavior change), `perf`, `meta` (repository metadata), `license`, `revert` (none). Keep the subject ≤ 72 characters, imperative mood, no capital letter, no trailing period. Done when: the convention is determined and, if conventional, the type and SemVer effect are selected. 4. Mode rewrite (messages only; the tree stays byte-identical): 1. List the exact target set, `HEAD` or `HEAD~N..HEAD`, with `git log --format='%H %an <%ae> %ad %cn <%ce> %cd' <range>` so the set and per-position author and committer dates are visible. Done when: the exact commit set is listed with per-position dates. 2. Confirm none of the targets are pushed to a shared remote with `git branch -r --contains <sha>`. If any is pushed, stop and require explicit user confirmation before continuing; pushed history is otherwise untouched. Done when: all targets are confirmed unpushed or explicit confirmation is received. 3. Record each target's original tree SHA (`git rev-parse <sha>^{tree}`) and original author and committer dates, keyed by position in the range; re-signing must preserve these dates by position. Done when: every target's tree SHA and dates are recorded by position. 4. Rewrite each target's message to h