Git Automation

Automate complex Git workflows with atomic commit enforcement, Beads integration, and real-time synchronization.

When to use this skill

Use this skill when:

• Creating commits with proper message formatting

• Managing feature branches and releases

• Syncing Git state with task tracking systems

• Implementing atomic commits across multiple files

• Detecting and auto-committing completed work

• Validating changes before committing

Core Concepts

Atomic Commits

An atomic commit is a single, self-contained change that:

• Fixes ONE issue or implements ONE feature

• Can be reverted without breaking other changes

• Passes all tests and validation

• Has a clear, descriptive commit message

Benefits:

• Easy to understand changes

• Simpler debugging and rollbacks

• Better code history

• Easier to cherry-pick changes

Enforcement Rules:

• Maximum ONE issue/task per commit

• Strict validation before commit

• Dependency checking

• No bypassing atomic commit requirement

Conventional Commits

Format: {type}({scope}): {issue_id} {title}

Types:

• feat : New feature

• fix : Bug fix

• refactor : Code refactor

• docs : Documentation

• test : Test additions/updates

• chore : Build, dependencies, tooling

Examples:

feat(auth): TASK-42 Add JWT token validation fix(api): ISSUE-123 Handle null responses correctly docs(readme): Update installation instructions test(utils): Add tests for date formatting

Beads Integration

Real-time synchronization with Beads task tracking:

• Sync Git commits with task status

• Auto-update task status on commit

• Track issue references in commits

• Validate task completion before merge

Step-by-Step Workflow

1. Create a Feature Branch

Create branch from main

git checkout main && git pull git checkout -b feat/TASK-42-description

Branch naming: {type}/{issue-id}-{short-description}

2. Make Changes

Edit files for a single feature/fix:

Edit files

vim src/feature.ts

Stage changes

git add src/feature.ts

Check status

git status

3. Validate Before Committing

Ensure quality before commit:

Run tests

npm test

Check linting

npm run lint

Type check

npm run type-check

Validate changes meet atomic commit rules

(Max files, single issue, proper formatting)

4. Create Atomic Commit

Commit with proper format

git commit -m "feat(module): TASK-42 Add new feature"

The commit will:

1. Validate message format

2. Check file count (< 50 files)

3. Verify single issue reference

4. Update Beads task status

5. Run pre-commit hooks

5. Sync with Beads (if using task tracking)

Auto-sync happens on commit, but manual sync available:

git beads-sync TASK-42

Updates: task status, linked commits, dependencies

6. Create Pull Request & Merge

Push to remote

git push -u origin feat/TASK-42-description

Create PR (on GitHub/GitLab)

Reference task: "Closes TASK-42"

Wait for reviews and CI

Merge when approved

git merge feat/TASK-42-description

Common Scenarios

Scenario 1: Single File Bug Fix

Task: BUGFIX-89 "Fix null pointer in auth service"

git checkout main && git pull git checkout -b fix/BUGFIX-89-null-pointer vim src/auth/service.ts npm test # Verify fix works git add src/auth/service.ts git commit -m "fix(auth): BUGFIX-89 Handle null user object"

Commit validates:

• ✅ Single file (< 50 limit)

• ✅ Proper message format

• ✅ Single issue reference

• ✅ Tests passing

Scenario 2: Feature with Multiple Files

Task: FEAT-156 "Add user preferences UI"

git checkout -b feat/FEAT-156-user-prefs vim src/components/Preferences.tsx vim src/api/preferences.ts vim src/styles/preferences.css npm test git add src/components/Preferences.tsx src/api/preferences.ts src/styles/preferences.css git commit -m "feat(ui): FEAT-156 Add user preferences panel"

Commit validates:

• ✅ Multiple related files (same feature)

• ✅ All files for single feature

• ✅ Single issue reference

• ✅ Tests passing

Scenario 3: Refactor with Tests

Task: TECH-203 "Refactor date utilities"

git checkout -b refactor/TECH-203-date-utils vim src/utils/date.ts vim src/utils/tests/date.test.ts npm test # Validate refactor doesn't break anything git add src/utils/date.ts src/utils/tests/date.test.ts git commit -m "refactor(utils): TECH-203 Simplify date formatting"

Commit validates:

• ✅ Logic and tests together

• ✅ No functionality change

• ✅ All tests pass

• ✅ Proper message format

Safety Features

Pre-Commit Validation

Before every commit:

• Syntax check: No syntax errors in code

• Lint check: Code follows style rules

• Type check: TypeScript types are valid

• Secret scan: No credentials committed

• Size check: No huge files

• Atomic check: Single issue per commit

Auto-Commit Detection

Automatically commit when:

• Beads task marked as completed

• Agent workflow finishes successfully

• Manual trigger requested

Safety checks:

• Dry-run mode by default

• Requires confirmation for first auto-commit

• Validates working tree is clean

• Backs up before committing

• Logs all auto-commits

Dependency Validation

Ensures commits don't break dependencies:

• Check package.json changes

• Verify lock file consistency

• Validate version constraints

• Test dependency installations

Advanced Workflows

Watch Mode (Continuous Auto-commit)

Watch for completed tasks every 30 seconds Auto-commit when task status → closed Validate each commit before pushing Stop on errors or after 1 hour

Use for:

• Long-running agent workflows

• Multiple concurrent tasks

• Automated CI/CD pipelines

Beads Real-Time Sync

Keeps Git and task tracking in sync:

• Commit detection → Update task status

• Task completion → Suggest auto-commit

• Branch creation → Link to task

• Pull request merge → Mark as done

Sync on:

• Commit (post-commit hook)

• Branch creation/deletion

• Tag creation

• PR open/close/merge

Version-Based Branching

Organize branches by release version:

main → Production v1.2.x → Stable releases develop → Development feat/... → Features (merge to develop) bugfix/... → Bug fixes (merge to v-branch) release/v1.2.0 → Release candidates

Tagging:

• Automatic tags on releases

• Version-based branch cleanup

• Release note generation

Troubleshooting

Commit Validation Fails

Problem: "Atomic commit validation failed"

Solution:

• Check commit has only one issue reference: git log -1

• Verify file count < 50: git diff --cached --name-only | wc -l

• Check message format: {type}({scope}): {issue} {title}

• Run validation: git validate --strict

Beads Sync Not Working

Problem: "Beads sync failed"

Solution:

• Check Beads is running: beads status

• Verify issue exists: beads issues list TASK-42

• Check credentials: echo $BEADS_API_KEY

• Retry manually: git beads-sync TASK-42

Auto-commit Not Triggering

Problem: "Auto-commit didn't run"

Solution:

• Check task actually completed: beads issues get TASK-42

• Verify changes exist: git status

• Run manually: git auto-commit --dry-run=false

• Check logs: cat .git/auto-commit.log

Best Practices

• One Issue Per Commit: Never mix multiple issues in one commit

• Clear Messages: Include issue ID and descriptive title

• Test Before Commit: Always run tests before committing

• Small Changes: Smaller atomic commits are easier to review

• Linked Tasks: Always reference task/issue ID in commits

• Clean History: Use atomic commits to keep history clean

• Validate Always: Don't bypass validation checks

• Backup Before Auto-commit: Enable backup before auto-commit

Related Skills

• Bun Development: Build system and development workflow

• Liaison Workflows: Task creation and workflow management

• Code Review: Quality assurance and peer review process

Keywords

git, commits, automation, workflow, atomic-commits, beads, sync, branches, validation, conventional-commits