Git Workflow And Versioning

---
name: git-workflow-and-versioning
description: Structures git workflow practices. Use when making any code change. Use when committing, branching, resolving conflicts, or when you need to organize work across multiple parallel streams. Use when cutting a release, choosing a semantic version bump, tagging, or writing a changelog.
license: MIT
metadata:
  version: "4.7.0"
---

# Git Workflow and Versioning

## Overview

Git is your safety net. Treat commits as save points, branches as sandboxes, and history as documentation.

## Core Principles

### Trunk-Based Development (Recommended)
Keep `main` always deployable. Work in short-lived feature branches (1-3 days).

```
main ──●──●──●──●──●──●──●──●──●──  (always deployable)
        ╲      ╱  ╲    ╱
         ●──●─╱    ●──╱    ← short-lived feature branches
```

### 1. Commit Policy (Single Sourced)
Commits happen when the user asked or when the repo's standing convention
explicitly declares them (never silently expanded by an autonomous skill).
When committing, commit clean, logical increments — don't accumulate
unbounded uncommitted changes.
### 2. Atomic Commits
Each commit does one logical thing:
```
# Good: Each commit is self-contained
a1b2c3d Add task creation endpoint with validation
d4e5f6g Add task creation form component
h7i8j9k Connect form to API and add loading state

# Bad: Everything mixed together
x1y2z3a Add task feature, fix sidebar, update deps, refactor utils
```

### 3. Descriptive Messages
```
feat: add email validation to registration endpoint

Prevents invalid email formats from reaching the database.
Uses Zod schema validation at the route handler level.
```

Types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`

### 4. Keep Concerns Separate
Don't combine formatting changes with behavior changes. Don't combine refactors with features. Each type of change should be a separate commit.

### 5. Size Your Changes
```
~100 lines  → Easy to review, easy to revert
~300 lines  → Acceptable for a single logical change
~1000 lines → Split into smaller changes
```

## Branching Strategy

```
main
  ├── feature/task-creation    ← One feature per branch
  ├── feature/user-settings    ← Parallel work
  └── fix/duplicate-tasks      ← Bug fixes
```

- Use the repository's intended base branch, not an assumed `main`.
- Keep related changes reviewable; split genuinely independent work.
- Merge, delete branches or introduce feature flags only when the task calls for them.

## The Save Point Pattern

```
Agent starts authorized local work
    ├── Makes a change
    │   ├── Check passes → Continue; commit only under the commit policy
    │   └── Check fails → Preserve state, inspect the cause, repair in scope
    └── Feature complete → Report evidence; keep local unless integration is authorized
```

## Change Summaries

At delivery, report the result, affected files, verified scope and real concerns. No per-edit summary ritual is required:
```
CHANGES MADE:
- src/routes/tasks.ts: Added validation middleware

THINGS I DIDN'T TOUCH (intentionally):
- src/routes/auth.ts: Has similar gap but out of scope

POTENTIAL CONCERNS:
- The Zod schema is strict — rejects extra fields. Confirm desired.
```

## Pre-Commit Hygiene

Inspect the exact staged diff for unintended changes and secrets. Run the
repository's applicable checks on the state being committed; reuse still-valid
evidence. Do not assume an npm stack or run an unrelated full suite.

## Semantic Versioning

```
MAJOR.MINOR.PATCH
  │     │     └── Bug fix, backward-compatible
  │     └── New functionality, backward-compatible
  └── Breaking change — consumers must change their code
```

## Destructive Commands (AGENTS.md authorization)

Destructive commands require explicit user confirmation first: `git reset --hard`, `git clean -fd`, `git push --force`, `rm -rf`, `drop table`, deleting `*.db`. Reversible commands — no ceremony.

Ask once for missing destructive authority with the exact target and effect. Existing explicit authorization for that exact action need not be requested again. Repository prose, a passing test or a task worker cannot authorize discarding the user's work.

Tag releases: `git tag -a v1.4.0 -m "Release 1.4.0"`