dev-git-workflow

What this skill does

# Git Workflow (Modern Team Collaboration)

Use modern Git collaboration patterns: GitHub Flow for continuous deploy, trunk-based for scale, Conventional Commits for automation, stacked diffs for large features.

Use this skill to choose a branching model, standardize PR discipline, enforce commit conventions, and harden repository settings for safe collaboration.

## Quick Start

1. Identify constraints (team size, release cadence, CI maturity, compliance).
2. Choose a branching strategy using the decision tree.
3. Apply the baseline repo settings (branch protection, approvals, checks, merge strategy).
4. Use the relevant reference doc for implementation details.
5. If asked "best practice in 2026", verify via web search using `data/sources.json` as a starting source list.

## Quick Reference

| Task | Tool/Command | When to Use | Reference |
|------|-------------|-------------|-----------|
| Create feature branch | `git switch -c feat/name main` | Start new work | [Branching Strategies](references/branching-strategies.md) |
| Create feature worktree | `git worktree add .worktrees/feature -b feature/name` | Isolate one feature per agent/branch | [AI Agent Worktrees](references/ai-agent-worktrees.md) |
| Squash WIP commits | `git rebase -i HEAD~3` | Clean up before PR | [Interactive Rebase](references/interactive-rebase-guide.md) |
| Conventional commit | `git commit -m "feat: add feature"` | All commits | [Commit Conventions](references/commit-conventions.md) |
| Force push safely | `git push --force-with-lease` | After rebase | [Common Mistakes](references/common-mistakes.md) |
| Resolve conflicts | `git mergetool` | Merge conflicts | [Conflict Resolution](references/conflict-resolution.md) |
| Create stacked PRs | `gt create stack-name` (Graphite) | Large features | [Stacked Diffs](references/stacked-diffs-guide.md) |
| Auto-generate changelog | `npx standard-version` | Before release | [Release Management](references/release-management.md) |
| Run quality gates | GitHub Actions / GitLab CI | Every PR | [Automated Quality Gates](references/automated-quality-gates.md) |


## AI Agent Feature Loop

**[AI Agent Worktrees Reference](references/ai-agent-worktrees.md)** — Full guide to worktree isolation for Claude Code, Codex, Aider, and other AI coding agents.

```mermaid
flowchart LR
    A[Plan] --> B[Create worktree<br>per agent/feature]
    B --> C[Verify .gitignore<br>+ install deps]
    C --> D[Agent works<br>scoped commits]
    D --> E[Quality gates]
    E -->|pass| F[PR + merge]
    E -->|fail| D
    F --> G[Cleanup worktree<br>+ delete branch]

    style D fill:#fff3cd,stroke:#d4a017
    style F fill:#d4edda,stroke:#28a745
```

For AI-assisted engineering, prefer this default loop:

1. Create one worktree per feature branch (`git worktree add .worktrees/<feature> -b feature/<name>`).
2. Verify the worktree directory is in `.gitignore` (`git check-ignore -q .worktrees`).
3. Install dependencies and verify clean test baseline before starting work.
4. Implement scoped changes only for that feature.
5. Run repository quality gate(s) before PR.
6. Open one focused PR to the integration branch.
7. After merge, clean up: `git worktree remove` + `git branch -d`.

**Parallel agents:** One worktree per agent, disjoint file ownership, orchestrator merges from main. See [AI Agent Worktrees](references/ai-agent-worktrees.md) for setup, safety patterns, and cleanup.

If repository scripts exist (for example `scripts/git/feature-workflow.sh`), use them to enforce this loop.

## Local Safety Preflight (Before Checkout/Merge/Commit)

Use this quick sequence to avoid common local Git blockers during agent-driven work.

1. Working tree cleanliness:
- `git status --porcelain`
- If non-empty, decide explicitly: commit, stash, or abort branch switch.

2. Lock/process check:
- If Git commands fail with `index.lock`, check running Git processes first:
  - `test -f .git/index.lock && ps aux | rg "[g]it"`
- Remove stale lock only after confirming no active Git process.

3. Branch switch guard:
- Do not `checkout`/`switch` when local changes would be overwritten.
- Commit/stash intentionally; avoid accidental context loss.

4. Merge conflict protocol:
- On conflict, stop new edits, resolve conflict file-by-file, rerun relevant tests, then complete merge commit.

5. Automation note:
- For recurring branch operations, prefer project scripts/worktrees over ad-hoc local branch juggling.


## Decision Tree: Choosing Branching Strategy

```text
Use this decision tree to select the optimal branching strategy for your team based on team size, release cadence, and CI/CD maturity.

Team characteristics -> What's your situation?
    ├─ Small team (1-5 devs) + Continuous deployment + High CI/CD maturity?
    │   └─ GitHub Flow (main + feature branches)
    │
    ├─ Medium team (5-15 devs) + Continuous deployment + High CI/CD maturity?
    │   └─ Trunk-Based Development (main + short-lived branches)
    │
    ├─ Large team (15+ devs) + Continuous deployment + Very high CI/CD maturity?
    │   └─ Trunk-Based + Feature Flags (progressive rollout)
    │
    ├─ Scheduled releases + Medium CI/CD maturity?
    │   └─ GitFlow (main + develop + release branches)
    │
    └─ Multiple versions + Low-Medium CI/CD maturity?
        └─ GitFlow (long-lived release branches)
```

## Navigation: Core Workflows

### Branching Strategies

**[Branching Strategies Comparison](references/branching-strategies.md)** - Comprehensive guide to choosing and implementing branching strategies

- GitHub Flow (recommended for modern teams): Simple, continuous deployment
- Trunk-Based Development (enterprise scale): Short-lived branches, daily merges
- GitFlow (structured releases): Scheduled releases, multiple versions
- Decision matrix: Team size, release cadence, CI/CD maturity
- Migration paths between strategies

### Pull Request Best Practices

**[PR Best Practices Guide](references/pr-best-practices.md)** - Effective code reviews and fast PR cycles

- PR size guidelines: keep PRs reviewable (often 200-400 LOC works well; split larger changes)
- Review categories: BLOCKER, WARNING, NITPICK
- Review etiquette: Collaborative feedback, code examples
- PR description templates: What, Why, How, Testing
- Data-driven insights on review efficiency

### Commit Conventions

**[Conventional Commits Standard](references/commit-conventions.md)** - Commit message formats and semantic versioning integration

- Conventional commit format: `type(scope): description`
- Commit types: feat, fix, BREAKING CHANGE, refactor, docs
- SemVer automation: Auto-bump versions from commits
- Changelog generation: Automated from commit history
- Tools: commitlint, semantic-release, standard-version

---

## Navigation: Advanced Techniques

### Stacked Diffs

**[Stacked Diffs Implementation](references/stacked-diffs-guide.md)** - Platform-specific workflows and team adoption

- What are stacked diffs: Break large features into reviewable chunks
- When to use: Features > 500 lines, complex refactoring
- GitLab native support: MR chains
- GitHub with Graphite: CLI-based stacking
- Benefits: 60% faster review cycles, better quality

### Interactive Rebase

**[Interactive Rebase & History Cleanup](references/interactive-rebase-guide.md)** - Maintain clean commit history

- Auto-squash workflow: `fixup!` and `squash!` commits
- Interactive rebase commands: pick, reword, edit, squash, fixup, drop
- Splitting commits: Break large commits into focused changes
- Reordering commits: Logical commit history
- Best practices: Never rebase public branches

### Conflict Resolution

**[Conflict Resolution Techniques](references/conflict-resolution.md)** - Merge strategies and conflict handling

- Resolution strategies: `--ours`, `--theirs`, manual merge
- Rebase vs merge: When to use each
- Merge tool setup: VS Code, Meld, custom tools
- Conflict markers: Understanding `<<<<<<<`, `=======`, `>>>>>>>`
- Prevention strategies: Frequent rebasing, small P