holocron/plugins/git/.apm/skills/git-commits/SKILL.md

name, description, metadata, allowed-tools

name	description	metadata	allowed-tools
git-commits	Use when creating, amending, squashing, or cherry-picking commits, including writing and validating the Conventional Commits message. Not history inspection -> `git-history`. Not branch lifecycle -> `git-branches`.	version category source_keys 0.1.6 git conventional-commits-spec commitlint-config-conventional org-commit-conventions context7-git-htmldocs	Bash

Gotchas

• Run git as rtk git <subcommand>, never bare git — org convention, in && chains too. Run it bare only when rtk would break it: output a script parses, or a command that opens an interactive editor (rebase -i in references/rewrite-history.md). Say why inline.
• Refuse to force-push main/master. A rewrite diverges the branch and the reflex is to force it back — safe only where nobody else has based work on it.
• reset --hard is a confirmation gate, not a default. It overwrites the working tree, and uncommitted edits it discards were never in git, so no reflog recovers them. Name what will be lost and offer a stash first.
• Never add --no-verify — using it when a hook fails bypasses the QA gate the pipeline depends on. Only on the user's explicit demand, with a warning.

Dispatch

Read exactly one flow file. Each is self-contained.

Condition	Flow	Read
Composing a new commit from staged changes	create	references/create-commit.md
Amending, squashing, folding a fixup, rebasing onto a new base, or resetting HEAD	rewrite	references/rewrite-history.md
Replaying an existing commit onto the current branch	cherry-pick	references/cherry-pick.md

Gates on every flow

1. Confirmation. No history rewrite executes without explicit approval from the user or the calling agent. Cherry-pick needs the destination branch confirmed first.
2. Atomicity. The result must be one logical, independently reviewable and reversible change that leaves the repository buildable and testable. This binds an amend or a squashed result as much as a fresh commit — say so before writing it, not after.
3. Secrets. Before any commit or amend, scan the staged diff for anything resembling an API key, token, password, connection string, or environment-specific config. Stop and flag it rather than committing it.
4. Validation. Check the message against commitlint config-conventional before committing. If a type, footer, or breaking-change edge case is not obvious, read references/conventional-commits-spec.md — it carries the constraint table, the 11-type set, and the footer token rules.
5. SemVer impact. Report the bump the commit implies: feat → MINOR, fix/perf/revert → PATCH, any breaking change → MAJOR, everything else → none. Callers decide releases from this, so never omit it.
6. Conflicts. If a rebase or cherry-pick halts, offer resolution or an abort. Do not resolve automatically without confirmation.

Output

For an agent caller, return:

{
  "operation": "create|amend|squash|cherry-pick",
  "status": "success|conflict|rejected",
  "message": "commit message or error description",
  "commit_hash": "abc1234",
  "semver_impact": "MAJOR|MINOR|PATCH|none",
  "breaking_change": false,
  "confirmation_required": false,
  "details": {
    "type": "feat",
    "scope": "api",
    "description": "add user authentication",
    "body": "optional body text, or null",
    "footers": ["Fixes: #123", "Refs: #456", "Co-authored-by: Bob <bob@example.com>"]
  }
}

details.footers is an array of the resolved trailer lines, empty when there are none — never a single joined string, and never omitted. Downstream agents index it.

For a human caller, show the same fields as a prose preview with a confirmation prompt.