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:

1. •Check commit has only one issue reference: git log -1
2. •Verify file count < 50: git diff --cached --name-only | wc -l
3. •Check message format: {type}({scope}): {issue} {title}
4. •Run validation: git validate --strict

Beads Sync Not Working

Problem: "Beads sync failed"

Solution:

1. •Check Beads is running: beads status
2. •Verify issue exists: beads issues list TASK-42
3. •Check credentials: echo $BEADS_API_KEY
4. •Retry manually: git beads-sync TASK-42

Auto-commit Not Triggering

Problem: "Auto-commit didn't run"

Solution:

1. •Check task actually completed: beads issues get TASK-42
2. •Verify changes exist: git status
3. •Run manually: git auto-commit --dry-run=false
4. •Check logs: cat .git/auto-commit.log

Best Practices

1. •One Issue Per Commit: Never mix multiple issues in one commit
2. •Clear Messages: Include issue ID and descriptive title
3. •Test Before Commit: Always run tests before committing
4. •Small Changes: Smaller atomic commits are easier to review
5. •Linked Tasks: Always reference task/issue ID in commits
6. •Clean History: Use atomic commits to keep history clean
7. •Validate Always: Don't bypass validation checks
8. •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