Commit

Commit

Workflow

Step 1 — Check for changes

Run in parallel:

• git status --short
• git diff
• git diff --staged

If there's nothing to commit, stop and say so. Review both unstaged and already staged diffs before writing the message.

Step 2 — Stage thoughtfully

Add specific files by name rather than git add . or git add -A. Broad staging risks accidentally committing .env files, credentials, or build artifacts. Scan git status for anything that looks like a secret before staging.

Step 3 — Write a conventional commit

Format: <type>(<scope>): <subject>

• Subject line: ≤ 72 chars, ideally ≤ 50. Imperative mood ("add X", not "added X").
• Body: optional. Only include if the why isn't obvious from the diff. 1–2 sentences max, never a bullet list.
• If the subject line is self-explanatory, omit the body entirely.

Common types: feat, fix, chore, docs, refactor, test, style, perf

# No body needed — subject is self-explanatory
git commit -m "fix(auth): handle expired token on page refresh"

# Body only when the why is non-obvious
git commit -m "$(cat <<'EOF'
feat(auth): add refresh token rotation

Single-use tokens prevent session hijacking after a token is stolen —
the old token is invalidated on first use.
EOF
)"

Step 4 — Handle pre-commit hook failures

If a hook fails (lint, typecheck, tests), the commit did NOT happen. Fix the issue, re-stage the modified files, then create a NEW commit. Never use --amend after a hook failure — that would modify the previous commit, potentially losing work.

Step 5 — Verify the commit

Do not claim success until git log -1 --oneline shows the new commit. Include the commit hash in the final response.

Step 6 — Ask about pushing

Use AskUserQuestion: "Push to remote?" with options:

• "Push now"
• "Do not push"

Before pushing, check branch/upstream with git status -sb. If no upstream is configured, ask before setting one. After an approved push, verify with git status -sb; do not claim the push succeeded if the branch is still ahead.

Safety

• Never commit .env, *.pem, *credentials*, *secret*, *token* files
• Never force push without an explicit request
• Never amend commits on shared branches (main, master, develop)
• Never add AI/Claude attribution to commit messages

Verification Gate

Do not finish until:

• staged and unstaged diffs were reviewed
• the commit exists in git log -1 --oneline
• the final response includes the commit hash
• if pushed, git status -sb confirms the branch is not ahead of upstream

Conventional Commit Types