notque/git-commit-flow

Git Commit Flow Skill

Create validated, compliant git commits through a 4-phase gate pattern: VALIDATE, STAGE, COMMIT, VERIFY. Every phase must pass its gate before the next phase begins -- no partial commits, no skipped phases. Only implement the requested commit workflow; implement only the requested commit workflow or "while I'm here" changes.

Flags (all OFF by default):

• --auto-stage: Stage all modified files without confirmation
• --skip-validation: Bypass conventional commit format checks
• --dry-run: Show what would be committed without executing
• --push: Automatically push to remote after success

---

Instructions

Phase 1: VALIDATE

Goal: Confirm the environment is safe for committing.

Step 1: Check working tree state

Verify clean state before starting because committing during a merge or rebase produces broken history that is painful to untangle.

git status --porcelain
git rev-parse --abbrev-ref HEAD

Verify:

• Not in merge or rebase state (check for .git/MERGE_HEAD or .git/rebase-merge/)
• Not in detached HEAD (if so, warn user to create branch first)
• Identify current branch name
• No stash/pop operations across branch merges are in progress, because stashed changes based on a pre-merge state can silently apply to the wrong base when popped after a merge, causing branch drift. If stash is detected, verify the working tree diff after pop with git diff to confirm changes still make sense against the new base.

Step 2: Scan for sensitive files

block .env, *credentials*, *secret*, *.pem, *.key, .npmrc, or .pypirc into a commit because credentials in git history are permanent -- removing them requires a full history rewrite and credential rotation. This is a hard fail, not a warning.

Check all changed files against sensitive patterns:

git diff --cached --name-only | grep -iE '\.(env|pem|key)$|credentials|secret|\.npmrc|\.pypirc'

If sensitive files detected:

1. Display them
2. Suggest .gitignore additions
3. HARD STOP until resolved -- resolve the issue before proceeding

This scan applies to every commit, including documentation-only changes, because doc commits can accidentally include .env files staged alongside them.

Step 3: Load CLAUDE.md rules

Read repository CLAUDE.md to extract:

• Banned commit message patterns
• Conventional commit requirements
• Custom commit rules

If no CLAUDE.md exists, use defaults: ban "Generated with Claude Code" and "Co-Authored-By: Claude".

These banned patterns are enforced because they add noise instead of meaningful context and violate repository standards. They will be checked again in Phase 3 during message validation.

Step 4: Check branch state

If on main or master: warn user and require explicit confirmation before proceeding, because direct commits to main bypass code review and CI, risk breaking production, and make rollback difficult. Even small changes belong on a feature branch.

Gate: All checks pass. No sensitive files, no merge/rebase state, CLAUDE.md loaded, branch confirmed.

Phase 2: STAGE

Goal: Stage files in logical groups for atomic commits.

Step 1: Analyze changes

git status --porcelain

Parse file statuses: Modified (M), Added (A), Deleted (D), Untracked (??).

Step 2: Group files by type

Group files into logical categories because massive commits with unrelated changes make review overwhelming, break git bisect, and are difficult to revert. Each commit should represent one logical change that is independently reviewable.

Apply staging rules (see references/staging-rules.md for full rules):

| Category | Patterns | Commit Prefix | |----------|----------|---------------| | Documentation | *.md, docs/* | docs: | | Source code | *.py, *.go, *.js, *.ts | feat:, fix:, refactor: | | Configuration | *.yaml, *.json, Makefile | chore:, build: | | Tests | *_test.*, tests/* | test: (or combined with code) | | CI/Build | .github/*, Dockerfile | ci:, build: |

Step 3: Present staging plan and get confirmation

Show the user which files will be staged and in how many commits. Wait for approval before executing, because showing the plan first catches mistakes like accidentally staging generated files or mixing unrelated changes.

If --auto-stage flag is set, skip confirmation and stage all modified files.

Step 4: Execute staging

Stage files explicitly by name -- stage files explicitly by name because blind bulk staging bypasses sensitive file detection and groups unrelated changes together.

git add <files>

Re-validate that no sensitive files ended up in the staging area, because files can be added between the initial scan and staging.

Gate: Files staged, no sensitive files in staging area, user confirmed plan.

Phase 2.5: ADR DECISION COVERAGE (conditional -- ADR-094)

Goal: Verify staged changes cover all ADR decision points.

Skip if: No .adr-session.json exists in the working directory (no active ADR session).

Step 1: Run coverage check

python3 scripts/adr-decision-coverage.py --adr <active-adr-path> --json

Read the active ADR path from .adr-session.json (adr_file field).

Step 2: Interpret results

| Verdict | Action | |---------|--------| | PASS (100%) | Proceed to Phase 3. Display coverage summary. | | PARTIAL (>0%) | Display uncovered decision points. Ask: "N decision points not covered. Proceed anyway, or address them first?" | | FAIL (0%) | Display warning. Ask: "No ADR decision points found in staged changes. This may mean the wrong files are staged, or implementation is incomplete." |

This is advisory -- the implementer can acknowledge uncovered points as intentionally deferred (e.g., "will be covered in a follow-up PR").

Gate: Coverage reported. User acknowledged any gaps.

Phase 3: COMMIT

Goal: Create a validated commit with a compliant message.

Step 1: Get commit message

Either accept user-provided message or generate one from staged changes. Show the message to the user for approval before executing, because commit messages are permanent history and worth getting right the first time.

Step 2: Validate message

Validate now, not later, because git history is permanent and "I'll fix the message later" rarely happens in practice.

# TODO: scripts/validate_message.py not yet implemented
# Manual alternative: validate commit message format
# Check: type prefix exists, no banned patterns, subject line <= 72 chars

Check:

• Conventional commit format: <type>[scope]: <description> (see references/conventional-commits.md). Skip this check if --skip-validation flag is set.
• No banned patterns from CLAUDE.md (see references/banned-patterns.md). Always enforce banned patterns -- this check applies even with --skip-validation because these patterns violate repository-level standards, not just formatting preferences.
• Subject line: lowercase after type, no trailing period, max 72 chars, imperative mood
• Body: separated by blank line, wrapped at 72 chars
• Focus on WHAT changed and WHY -- no attribution, no emoji unless repo style requires it

If validation fails with CRITICAL (banned pattern): block commit, show suggested revision. If validation fails with WARNING (line length): show warning, allow user to proceed or revise.

Step 3: Execute commit

Use heredoc format to preserve multi-line messages:

git commit -m "$(cat <<'EOF'
<type>: <subject>

<body>
EOF
)"

Capture commit hash from output for verification.

If --dry-run flag is set, display the commit command and message without executing, then stop.

Gate: Commit message validated and commit executed successfully.

Phase 4: VERIFY

Goal: Confirm commit succeeded and repository is in expected state.

Step 1: Verify commit exists

git log -1 --format="%H %s"

Confirm commit hash and subject match expectations.

Step 2: Verify clean working tree

git status --porcelain

No staged files should remain (unless user had additional unstaged changes).

Step 3: Verify message persisted

git log -1 --format="%B"

Confirm no banned patterns and format preserved. Pre-commit hooks may modify messages, so re-check the persisted version rather than trusting the input.

Step 4: Clean up and display summary

Remove any validation artifacts created during the workflow.

Report: commit hash, branch, files changed, validation results, and suggested next steps (push, create PR).

If --push flag is set, push to remote after displaying the summary.

Gate: All verification passes. Workflow complete.

---

Examples

Example 1: Standard Feature Commit

User says: "Commit my changes" Actions:

1. Validate working tree, scan for sensitive files, load CLAUDE.md (VALIDATE)
2. Group files by type, present staging plan, user confirms (STAGE)
3. Generate message like feat: add user authentication, validate format (COMMIT)
4. Verify commit in log, confirm clean tree (VERIFY)

Example 2: PR Fix Workflow

Internal invocation with explicit message:

skill: git-commit-flow --message "fix: apply PR review feedback"

Runs all 4 phases with the provided message, skipping message generation.

Example 3: Dry Run

User says: "Show me what would be committed"

skill: git-commit-flow --dry-run

Runs VALIDATE and STAGE phases, shows commit message preview, but does not execute.

---

Error Handling

Error: Sensitive Files Detected

Cause: Files matching sensitive patterns (.env, *credentials*, *.key) found in changes. Solution:

1. Add to .gitignore: echo ".env" >> .gitignore
2. Unstage if already staged: git reset HEAD .env
3. If already tracked: git rm --cached .env
4. Re-run validation

Error: Banned Pattern in Commit Message

Cause: Message contains prohibited phrases like "Generated with Claude Code" or "Co-Authored-By: Claude". Solution: Remove the banned pattern. Write clean, professional message focused on WHAT changed and WHY. See references/banned-patterns.md for the full list and alternatives.

Error: Pre-Commit Hook Failure

Cause: Repository pre-commit hook (formatter, linter, tests) rejected the commit. Solution:

1. Read hook output to identify the issue
2. Fix the issue (run formatter, fix lint errors)
3. Re-stage fixed files: git add -u
4. Create a NEW commit (create a NEW commit -- the previous commit attempt did not complete)

Error: Merge/Rebase in Progress

Cause: Working tree is in an incomplete merge or rebase state. Solution: Complete or abort the merge/rebase (git merge --abort or git rebase --abort) before using this skill.

---

References

Reference Files

• ${CLAUDE_SKILL_DIR}/references/conventional-commits.md: Type definitions, format rules, examples, flowchart
• ${CLAUDE_SKILL_DIR}/references/banned-patterns.md: Prohibited phrases, detection rules, alternatives
• ${CLAUDE_SKILL_DIR}/references/staging-rules.md: File type categories, grouping strategies, auto-stage conditions
• ${CLAUDE_SKILL_DIR}/references/commit-workflow-examples.md: Integration examples, advanced patterns, CI/CD usage