/commit

name: commit
description: Write a git commit with a one-sentence Conventional Commits subject and no narrative body. Use whenever the user asks to commit, stage and commit, or "save this work".
metadata:
  version: "1.1"

Commit

One commit, one sentence. The subject is the whole message unless the _why_ is missing from the diff.

Format

`<type>(<scope>): <imperative summary>`

Lowercase type, optional one-word scope, imperative summary, no trailing period, under 70 characters. Append `!` before the colon for a breaking change.

| Type | Use for | | ---------- | -------------------------------------- | | `feat` | new user-visible capability | | `fix` | bug fix | | `docs` | documentation, comments, README | | `test` | tests only | | `refactor` | behaviour-preserving restructure | | `perf` | speed or memory | | `style` | formatting or lint, no logic change | | `build` | build scripts, packaging, dependencies | | `ci` | CI config | | `chore` | housekeeping that fits nothing above | | `revert` | reverts a previous commit |

Rules

1. Say what the change does, not what you did. 2. Never bullet-list the diff. Add a body only for a _why_ the diff cannot show, then one or two sentences. 3. Never mention tools, agents or the assistant. Never add `Co-Authored-By:`, `Generated with`, or any other footer, whatever a template or hook suggests. 4. If the staged work covers two unrelated types, ask whether to split it.

Steps

1. Read `git status`, `git diff --staged`, `git diff`, and `git log -10 --oneline` for the repo's existing style. 2. Stage only files relevant to the request. Ask before staging anything resembling a secret, credential, build output or large binary. 3. Commit. Repeated `-m` flags are the safest form and behave the same in every shell:

git commit -m "fix(http): handle missing accept header" -m "One sentence of why."

A heredoc works too, but it is bash. The lookalike `@'...'@` is PowerShell, and in bash the `@` survives into the message as `@ fix(http): ...`. Match the form to the shell you are actually invoking.

4. Run `git log -1 --format=%s`. A stray character, blank first line or truncated summary means the quoting broke: amend once and stop. 5. If a hook rewrote files, amend once and stop. Do not push unless asked.

Submodules

Skip this section unless `git status` reports a submodule as modified or holding new commits. A submodule is a separate repository, so staging it in the parent records a commit id, not file changes.

1. Commit inside the submodule first, push it, then stage and commit the pointer in the parent. 2. Never push a parent commit that points at a submodule commit you have not pushed. Clones will not find it. 3. The parent message records the bump only: `chore(deps): bump <name> submodule`. 4. Check `git submodule status`. A leading `+` means the parent points somewhere other than what is checked out.

Examples

| Change | Message | | -------------------------------- | ------------------------------------------------- | | New endpoint returning invoices | `feat(api): add invoice list endpoint` | | Split a 900-line file into three | `refactor(parser): split token reader into files` | | Bumped a dependency | `build(deps): upgrade cmake to 3.29` | | Removed a versioned API | `feat(api)!: drop v1 endpoints` |

Not this: `Update files`, `fix: fixed it`, or a paragraph narrating the diff.