Commit

Git Workflow - Atomic Commits

ultrathink

Commit code changes using atomic commits with conventional commit format. Each commit is one independent logical change that can be reverted without breaking other functionality.

Voice

Follow ~/.claude/rules/voice.md for all authored text. Commit-specific rules:

• Lowercase after colon, no period at end
• Specific verbs: add, fix, extract, drop, rename, move, split, wire, swap
• PR bodies: start with what changed and why, plain bullet list, no filler
• PR titles: same format as commit messages
• No **Bold:** description lists in PR bodies
• Backtick all filenames, paths, commands, config keys, and code references
• Never mention Claude/Anthropic/AI

Git State (auto-populated)

• Current branch: !git branch --show-current
• Status: !git status --short
• Staged changes: !git diff --cached --stat
• Unstaged changes: !git diff --stat
• Full diff: !git diff HEAD
• Recent commits: !git log --oneline -10

Arguments

• $ARGUMENTS containing --analyze: Only run Phase 1 analysis, output groupings without committing
• $ARGUMENTS containing --push: Run Phases 1-3 on current branch, then push directly (no branch, no PR)
• $ARGUMENTS containing --pr: Continue through Phase 4 (push and create PR)
• $ARGUMENTS containing --merge: Run Phase 5 only (merge specified PR and cleanup) - expects PR# as next arg
• No arguments: Run Phases 1-3 (analyze, commit, verify)

Workflow

Phase 1 - Analysis

Analyze the git state above. Group changes by layer + type. Verify independence.

Track each commit group as a task. Subject: affected files. Description: the commit message.

Output analysis in `` tags.

Phase 2 - Execution

GPG detection: Before the first commit, check git config:

git config --get commit.gpgsign

• true: Use git commit -S -m for all commits
• Empty/unset: Use git commit -m (no -S flag). Log once: "GPG not configured, commits will not be signed."

Branch creation (with --pr flag):

BASE_BRANCH=$(git branch --show-current)
git checkout -b type/description-in-kebab-case

Store BASE_BRANCH for use in Phase 4. This ensures:

• Commits go to feature branch, not the working branch
• PR targets the correct base branch (not always main)

For each commit group (TaskUpdate status: in_progress -> completed):

git add [files]

Validate the message before committing: run ${CLAUDE_SKILL_DIR}/scripts/validate-commit-msg.sh "message". The script checks conventional format, lowercase description, no trailing period, and max 72 chars. If it fails, fix the message before proceeding.

git commit [-S] -m "type(scope): description"

Output in `` tags.

Phase 3 - Verification

For each commit, verify:

• Atomic: Single concern, independently revertable
• Clear: Specific about what changed
• Signed: Used -S flag (if GPG available)

If verification fails:

git reset --soft HEAD~1
# Fix and recommit

Phase 3.5 - Push (with --push)

Push all commits directly to the current branch. No branch creation, no PR.

git push

If the branch has no upstream, set it:

git push -u origin HEAD

After push, output summary and stop. Do NOT continue to Phase 4.

Phase 4 - Pull Request (with --pr)

Push branch and create PR targeting BASE_BRANCH from Phase 2:

git push -u origin HEAD
gh pr create --base "$BASE_BRANCH" --title "type(scope): description" --body "$(cat ` (creates new commit) |
| Need to find old state | `git reflog` then `git reset --hard ` |

## Gotchas

- Don't amend published commits. Use `git revert` instead.
- GPG agent can timeout during batch commits. If signing fails mid-batch, check `gpg-agent` status before retrying.
- `--push` fails silently if no upstream is set. Use `git push -u origin HEAD` for new branches.
- Empty commits happen when all changes in a group were already staged. Verify with `git diff --cached --stat` before committing.
- PR body format: plain bullets, no `**Bold:** description` pattern. Start with what changed and why.

## Constraints

- Execute actual bash commands (not suggestions)
- Use Bash tool for all git operations
- Stop and report errors immediately
- Group by layer: data -> backend -> UI -> config -> docs
- Commit in dependency order
- Verify independently revertable
- Sign commits with `-S` flag when GPG is available
- Be terse in confirmations
- Never mention Claude, Claude Code, Anthropic, or AI in commits, PR bodies, or any output
- Never use co-authored-by or "generated by" attributions
- All text must pass as human-written. Re-read before submitting. If it sounds like a chatbot wrote it, rewrite it.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ramonclaudio](https://github.com/ramonclaudio)
- **Source:** [ramonclaudio/skills](https://github.com/ramonclaudio/skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.