git-commit
Draft conventional commit messages, commit local changes, push to main on origin, merge branches into main, and clean/prune git worktrees and stale local branches. Use when the user asks to commit, pu
SKILL.md.claude/skills/git-commit/SKILL.md
GitHubGit Commit (Project Aegis)
End-to-end git commit workflow for cmano-clone. Trunk is main (see .graphite_repo_config).
Result vocabulary (use in operator output): READY (draft ready), COMPLETE (commit/push/cleanup done), FAIL (hook/push/conflict stopped), BLOCKED (needs explicit user decision, e.g. force-push or dirty worktree loss).
When to use which path
| User intent | Path |
|---|---|
| Draft or refine a message only | Phase 1 |
| Commit locally (any branch) | Phase 2 |
Land on remote main (direct trunk) |
Phase 3 |
Merge a branch into main, then push |
Phase 4 |
| Remove stale worktrees / branches | Phase 5 |
Graphite stacks: If the current branch is Graphite-tracked (gt log short shows it in a stack), use gt submit / gt sync instead of raw git push — see graphite-github-substitute-plan.md. This skill's push-to-main path is for direct trunk work on main or when the user explicitly requests trunk push.
Hard rules
- Only commit or push when the user explicitly asks (this skill invocation counts as explicit).
- NEVER update git config.
- NEVER
--force,--hard, or force-push tomain/masterunless the user explicitly requests it — warn first; verdict BLOCKED until they confirm. - NEVER skip hooks (
--no-verify,--no-gpg-sign) unless the user explicitly requests it. - NEVER commit secrets (
.env, credentials, keys, tokens). - NEVER use interactive git (
-iflags: rebase -i, add -i). - NEVER amend unless: user asked to amend, HEAD commit is yours and unpushed, and hook did not reject the prior commit.
- If a hook rejects a commit, fix and create a new commit — do not amend a failed commit; report FAIL.
- Before commit/submit on code changes: run GitNexus
detect_changes()(see AGENTS.md). - Before running
git commit/git push/ destructive worktree remove: present the planned message, staged paths (or branch list), and ask "May I write this commit / proceed?" when the user has not already given a clear execute intent (e.g. bare/git-commitwith uncommitted work = execute intent; ambiguous multi-path cleanup = ask first).
Phase 0 — Parse intent
Map the user phrase to a mode from argument-hint:
| Mode | Triggers |
|---|---|
message |
"draft message", "suggest commit message" |
commit |
"commit", "/commit", "/git-commit" |
push-main |
"push main", "ship to main" |
merge |
"merge and commit", "merge into main" |
worktrees |
"clean worktrees", "prune worktrees" |
branches |
"delete merged branches", "prune stale branches" |
If intent is ambiguous, list the modes and ask which to run. Do not default to force-delete.
Phase 1 — Commit message
Analyze changes, then produce a conventional commit message (do not commit unless the user also asked to commit).
Gather context (run in parallel)
git status
git diff
git diff --staged
git log -5 --oneline
Use staged diff when something is staged; otherwise use working-tree diff.
Message format
<type>[optional scope]: <description>
[optional body — why, not what]
[optional footer: Closes #123, BREAKING CHANGE: ...]
| Type | Use for |
|---|---|
feat |
New behavior |
fix |
Bug fix |
docs |
Documentation only |
test |
Tests only |
refactor |
Restructure, no behavior change |
perf |
Performance |
build / ci |
Build or CI |
chore |
Maintenance |
qa |
QA gauntlet / test-ops artifacts |
Style: imperative, present tense, ≤72 chars in subject, one logical change per commit.
Scope hints (this repo)
data— ProjectAegis.Data / catalogsim— ProjectAegis.Simdelegation— ProjectAegis.Delegation*unity— unity/ProjectAegisproduction— production/ sprint docsgauntlet/qa— production/qa/gauntletci— Buildkite / GitHub Actions
Present the draft message. Verdict READY when the message is drafted and no commit was requested.
Phase 2 — Local commit
Checklist
- [ ] git status + diff reviewed
- [ ] No secrets in diff
- [ ] GitNexus detect_changes() run (code changes)
- [ ] Message drafted (Phase 1)
- [ ] User asked to commit (or skill invoked for commit)
Stage and commit
# Stage explicit paths only — avoid git add -A unless user wants everything
git add path/to/changed/files
git commit -m "$(cat <<'EOF'
type(scope): short description
Optional body explaining why.
EOF
)"
Verify:
git status
git log -1 --stat
Verdict COMPLETE on success; FAIL if hooks reject (then fix and new commit).
Phase 3 — Commit and push main
Direct trunk landing: work happens on main, commit locally, push to origin/main.
Preconditions
git branch --show-current # must be main (or user approved committing on main)
git fetch origin
git status # warn if behind/ahead of origin/main
If not on main:
git checkout main
git pull --ff-only origin main # stop if merge required and user didn't ask to merge
Workflow
- Complete Phase 2 on
main. - Push:
git push origin main
- Confirm:
git status
git log origin/main -1 --oneline
Do not git push --force to main. If push is rejected (non-fast-forward), stop with FAIL / BLOCKED — user must merge/rebase explicitly.
Phase 4 — Merge and commit
Merge another branch into main, commit the merge, push to remote.
Identify branches
git branch --show-current
git branch -a
git log --oneline main..OTHER_BRANCH
git log --oneline OTHER_BRANCH..main
Confirm with the user which branch merges into main if ambiguous.
Merge workflow
git fetch origin
git checkout main
git pull --ff-only origin main
git merge OTHER_BRANCH -m "$(cat <<'EOF'
merge(scope): integrate OTHER_BRANCH into main
Brief summary of what the merged work delivers.
EOF
)"
If merge conflicts:
- List conflicted files:
git diff --name-only --diff-filter=U - Resolve in working tree.
git addresolved files.git commit(no-i); reuse merge message if Git opened one.
Push after successful merge:
git push origin main
Graphite alternative
When merging stack work prefer Graphite merge order (bottom PR first) and gt sync after merge — not manual merge — unless user explicitly wants a local merge commit.
Verdict COMPLETE after push; BLOCKED if conflicts need user choices.
Phase 5 — Worktree and branch cleanup
Project worktrees often live under .worktrees/.
Inspect
git worktree list
git branch -vv
git fetch origin --prune
Safe worktree prune (recommended order)
git worktree prune
# Remove a specific secondary worktree (never the primary checkout)
git worktree remove .worktrees/NAME
# git worktree remove --force ... # only if user confirms dirty tree loss
Local branch cleanup (merged / stale)
Safe delete criteria (all must hold as applicable):
- Not
main/master/ current branch. - Merged into
origin/main(git branch --merged origin/main), or - Upstream is gone, or
- Upstream exists and local is 0 ahead (no unique commits), or
- No upstream and tip is ancestor of current/
origin/main.
git branch -d branch/name # prefer -d
# git branch -D branch/name # only if classified stale and -d refuses; confirm with user if unsure
Never remove the primary checkout worktree (repo root).
Bulk cleanup: process nested + standalone trees if both exist; do not run concurrent writers on the same .git.
Verdict COMPLETE when only intended branches/worktrees remain; list what was kept and why.
Quick reference
| Task | Command / section |
|---|---|
| Draft message | Phase 1 — parallel status, diff, log |
| Commit | Phase 2 — HEREDOC git commit -m |
| Push main | Phase 3 — git push origin main |
| Merge to main | Phase 4 |
| Worktrees | Phase 5 — git worktree remove + prune |
| Stale branches | Phase 5 — merged / gone / 0-ahead only |
| Graphite PR | gt submit --stack --no-interactive |
Follow-Up Actions
After a successful commit or submit:
/sprint-status— confirm sprint story status if production docs changed- Graphite:
gt submit/gt syncfor stacked work (prefer over raw push) - GitNexus: re-run
detect_changes/ re-analyze if code landed /skill-test static git-commit— re-validate this skill after edits- Next skill with static failures:
/skill-test static allthen/skill-improve [name]