git-manager

name	git-manager
source	botcore
description	Orchestrates git workflows including branching strategies, release management, conflict resolution, changelog generation, and multi-agent parallel development. Covers trunk-based development, GitHub Flow, stacked PRs, conventional commits, semantic versioning, git worktrees, monorepo strategies, and git hooks automation. Use when choosing branching strategies, setting up release pipelines, resolving merge conflicts, configuring git hooks, managing changelogs, coordinating parallel agent work with worktrees, or adopting monorepo patterns. Triggers: git workflow, branching strategy, release management, merge conflict, changelog, git hooks, worktree, monorepo, semantic versioning, trunk-based, GitHub Flow, stacked PRs, git automation, parallel development.
version	1.0.0
triggers	["git workflow","branching strategy","release management","merge conflict","changelog","git hooks","worktree","monorepo","semantic versioning","trunk-based development","GitHub Flow","stacked PRs","git automation","parallel development","release-please","changesets","husky","lefthook","lint-staged"]
portable	true

Managing Git

Git workflow orchestration -- branching strategies, release management, conflict resolution, changelog generation, and multi-agent parallel development patterns.

Capabilities

1. Branching Strategy Selection -- Evaluate and recommend trunk-based development, GitHub Flow, GitFlow, or stacked PRs based on team size and deployment cadence
2. Release Management -- Configure automated releases with semantic versioning, release-please, changesets, or semantic-release
3. Conflict Resolution -- Systematic merge conflict resolution including prevention strategies and agentic conflict handling
4. Changelog Generation -- Automated changelogs from conventional commits using release tooling
5. Parallel Development -- Git worktree setup for multi-agent and multi-feature parallel work
6. Monorepo Git Patterns -- Affected-only CI, sparse checkout, code ownership, and cross-package coordination
7. Git Hooks Automation -- Configure Husky, Lefthook, or lint-staged for pre-commit, pre-push, and commit-msg enforcement
8. Agentic Git Workflows -- Safe patterns for AI agents performing git operations with isolation and rollback

Routing Logic

Request Type	Load Reference
Branching strategy selection or comparison	references/branching-strategies.md
Release pipelines, versioning, changelogs	references/release-management.md
Merge conflict resolution or prevention	references/conflict-resolution.md
Git worktrees, parallel agent work	references/worktrees-parallel.md
Monorepo git patterns and tooling	references/monorepo-strategies.md
Git hooks setup (Husky, Lefthook, lint-staged)	references/git-hooks.md

Core Principles

1. Prefer Trunk-Based Development

Short-lived branches merged frequently to main. This is a prerequisite for true CI/CD. Feature flags replace long-lived feature branches. Reserve GitFlow only for projects with strict versioned releases and multiple supported versions.

2. Automate Everything That Can Be Automated

Commit message linting, version bumps, changelog generation, release notes, and tag creation should all be automated. Manual release processes introduce human error and slow delivery.

3. Conventional Commits Are the Foundation

All release tooling (release-please, semantic-release, changesets) depends on structured commit messages. Enforce the Conventional Commits specification via commit-msg hooks. See the commit-writer skill for message formatting.

4. Isolate Agent Work

AI agents performing git operations must work in isolated environments -- worktrees, separate branches, or sandboxed clones. Never allow agents to force-push to main or perform destructive operations without explicit human approval.

5. Resolve Conflicts Early

Merge frequently. Keep branches short-lived (hours to days, not weeks). Use consistent formatting (Prettier, Black, gofmt) to eliminate cosmetic conflicts. When conflicts arise, understand intent before choosing a resolution strategy.

6. One Concern Per Branch

Each branch addresses a single feature, fix, or refactor. Mixed-concern branches create review bottleneck, merge complexity, and unclear changelogs. Use stacked PRs for dependent changes.

Strategy Selection Guide

Use this decision tree to choose a branching strategy:

Is your team deploying continuously to production?
├─ Yes: Trunk-Based Development
│   ├─ Team > 10 devs? → Add short-lived feature branches (1-2 days max)
│   └─ Need incremental reviews? → Add stacked PRs
├─ No, but deploying regularly (weekly/biweekly):
│   └─ GitHub Flow (feature branches + PR merge to main)
└─ No, versioned releases with multiple supported versions:
    └─ GitFlow or modified GitFlow

Factor	Trunk-Based	GitHub Flow	GitFlow
Deploy cadence	Continuous	Regular	Versioned releases
Team size	Any (with feature flags)	Small to medium	Medium to large
Branch lifespan	Hours	Days	Days to weeks
CI/CD maturity	High (required)	Medium	Low to medium
Complexity	Low	Low	High
Best for	SaaS, microservices	Web apps, APIs	Mobile, libraries, enterprise

Workflow: Setting Up a Git Project

Step 1: Choose Branching Strategy

Use the decision tree above. Document the chosen strategy in the project's CONTRIBUTING.md or AGENTS.md.

Step 2: Configure Commit Enforcement

# Option A: Husky + commitlint (Node.js projects)
npm install -D husky @commitlint/cli @commitlint/config-conventional
npx husky init
echo 'npx commitlint --edit "$1"' > .husky/commit-msg

# Option B: Lefthook (polyglot projects)
brew install lefthook   # or: go install github.com/evilmartians/lefthook@latest
lefthook install
# Configure in lefthook.yml

Step 3: Configure Release Automation

Choose one based on project needs:

Tool	Best For	How It Works
release-please	Single packages, Google-style	Maintains a release PR, bumps on merge
changesets	Monorepos, multi-package	Contributors add changeset files, batch release
semantic-release	Fully automated, CI-driven	Releases on every qualifying merge to main

Step 4: Set Up Branch Protection

Main branch rules:
- Require PR reviews (1-2 reviewers)
- Require status checks to pass
- Require up-to-date branches before merge
- Require signed commits (optional but recommended)
- Restrict force pushes (always)
- Restrict deletions (always)

Step 5: Configure Git Hooks

See references/git-hooks.md for detailed setup. At minimum:

• commit-msg -- Validate conventional commit format
• pre-commit -- Run linter and formatter on staged files
• pre-push -- Run type checks and fast tests

Agentic Git Safety Rules

When an AI agent performs git operations, enforce these guardrails:

1. Never force-push -- Use --force-with-lease only when explicitly approved
2. Never commit to main directly -- Always work on a branch
3. Never skip hooks -- Do not use --no-verify
4. Never amend shared commits -- Only amend local, unpushed commits when explicitly requested
5. Always verify before destructive ops -- reset --hard, clean -f, branch -D require human confirmation
6. Use worktrees for parallel work -- Each agent session gets its own worktree
7. Create atomic commits -- One logical change per commit
8. Include Co-Authored-By -- Agent commits must attribute the AI co-author
9. Prefer staging specific files -- Use git add <file> over git add . or git add -A
10. Review diff before committing -- Always run git diff --staged before git commit

Quick Reference: Common Operations

Create a Feature Branch

git checkout main && git pull origin main
git checkout -b feat/short-description
# ... make changes ...
git add <specific-files>
git commit -m "feat(scope): add feature description"
git push -u origin feat/short-description

Resolve a Merge Conflict

git fetch origin
git merge origin/main          # or: git rebase origin/main
# Fix conflicts in editor (look for <<<<<<<, =======, >>>>>>>)
git add <resolved-files>
git merge --continue           # or: git rebase --continue

Create a Worktree for Parallel Work

git worktree add ../project-hotfix hotfix/issue-123
cd ../project-hotfix
# Work independently, then clean up:
git worktree remove ../project-hotfix

Stacked PRs Workflow

# PR 1: Base change
git checkout -b stack/part-1
# ... changes ...
git push -u origin stack/part-1

# PR 2: Builds on PR 1
git checkout -b stack/part-2
# ... changes ...
git push -u origin stack/part-2
# Create PR targeting stack/part-1 (not main)

Checklist

• Branching strategy chosen and documented
• Conventional commits enforced via commit-msg hook
• Release automation configured (release-please, changesets, or semantic-release)
• Branch protection rules applied to main
• Pre-commit hooks running linter and formatter
• Pre-push hooks running type checks and fast tests
• Agent git operations follow safety rules (no force-push, no direct main commits)
• Worktree strategy defined for parallel agent work
• Changelog generation automated from commit history
• Merge conflict prevention measures in place (short branches, consistent formatting)

When to Escalate

• Strategy disagreement -- Team cannot agree on branching model; facilitate a decision meeting with trade-off analysis
• Persistent merge conflicts -- Same files conflict repeatedly; review code ownership boundaries and module architecture
• Release pipeline failure -- Automated versioning produces wrong results; audit commit history for non-conventional messages
• Agent destructive operation -- Agent requests force-push, reset --hard, or branch deletion; require explicit human approval
• Monorepo scaling issues -- CI times exceed tolerance; evaluate sparse checkout, affected-only builds, or repo splitting
• Cross-team branch contention -- Multiple teams blocking each other on shared branches; consider trunk-based development with feature flags
• Security incident in hooks -- Hooks executing arbitrary code or blocking critical operations; review hook permissions and sandboxing