Git Conventions

---
description: "Branch naming, commit message format, PR workflow, worktree conventions, versioning policy"
when_to_use: "When creating branches, writing commit messages, creating PRs, or making versioning decisions"
version: "1.0.0"
---

# Git Conventions

## Invocation Boundary

`git commit`, `git push`, and `gh pr create` are invoked only when the human
explicitly types `/commit-push-pr` or `/sync` (or one of their listed Trigger
Phrases). The slash commands themselves are not invoked autonomously — wait for
the human trigger. The `Version bump:` AskUserQuestion in `/commit-push-pr` is
non-skippable; refuse to proceed without an explicit human selection.

See CLAUDE.md Critical Rule 13.

## Branch Naming

Pattern: `{type}/{short-description}`

Types:
- `feature/` — New functionality
- `fix/` — Bug fixes
- `refactor/` — Code restructuring without behavior change
- `docs/` — Documentation only
- `test/` — Test additions or fixes
- `chore/` — Tooling, dependencies, config

Examples:
- `feature/auth-flow`
- `fix/login-timeout`
- `refactor/extract-merger-module`

Keep branch names under 50 characters. Use hyphens, not underscores.

## Commit Messages

Follow conventional commits format:

```
type(scope): short description

Longer explanation if needed. Focus on WHY, not WHAT.
The diff already shows what changed.

Closes #123
```

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

Scope is optional but helpful: `feat(auth): add OAuth2 token refresh`

Rules:
- Subject line under 72 characters
- Imperative mood ("add" not "added" or "adds")
- No period at the end of the subject line
- Blank line between subject and body
- Body explains motivation, not mechanics
- Never append Co-Authored-By trailers, AI attribution lines, or "Generated with" footers

## When to Commit

Commit after each logical unit of work:
- A function is complete and tested
- A refactor is done and tests pass
- A bug is fixed and verified

Don't batch unrelated changes into one commit. Don't commit broken code.

## Branching Strategy

```
feature-branch ──PR──▶ develop ──PR──▶ main (release)
```

- `develop` — active development. Contributors fork, branch from `develop`, and PR back to `develop`.
- `main` — production releases. Maintainer-only, merged from `develop`.
- `gh-pages` — auto-deployed docs. Maintainer-only.

All feature/bugfix branches are created from and merged back into `develop`. Never PR directly to `main`.

## PR Workflow

1. Push your branch
2. Create PR with `gh pr create --base develop` (feature/bugfix branches target `develop`)
3. When on `develop`, PR targets `main`: `gh pr create --base main` (release merges only)
4. PR title follows same format as commit subject: `type(scope): description`
5. PR body includes: what changed, why, how to test, anything reviewers should know
6. Request review if the project has reviewers configured
7. Do not add AI-generated footers (e.g., "Generated with Claude Code") to PR descriptions

## Squash vs Merge

- Squash when: the branch has many small "wip" commits that don't individually matter
- Merge when: each commit in the branch is a meaningful, atomic change
- Rebase when: you need a linear history and commits are clean

Default preference: squash merge for feature branches, regular merge for release branches.

## Worktree Conventions

When using `git worktree` for parallel work:

- Worktrees go in a sibling directory, not inside the repo
- Naming: `{repo}-{branch-name}` for the worktree directory
- Always clean up worktrees when done: `git worktree remove {path}`
- Don't leave stale worktrees — they hold refs and can cause confusion

Agents that use worktree isolation (code-simplifier, test-writer, bug-fixer, etc.)
create and clean up their own worktrees automatically.

## Shared-State Files

These files are modified ONLY on the develop branch (via /sync), never on feature branches:

- `docs/spec/PROGRESS.md` — project progress tracker
- `docs/spec/SPEC.md` — feature specification
- `README.md` — project documentation
- `package.json` version field — release versioning

This prevents merge conflicts when running parallel feature branches.

## Versioning Policy

Follow [semver](https://semver.org/) when the project publishes releases:

| What changed | Bump | Example |
|---|---|---|
| Bug fix, patch to existing behavior | **patch** | Fixed edge case in date parser |
| New feature, command, or API surface | **minor** | Added CSV export option |
| Breaking change to public API or CLI | **major** | Renamed config key, removed flag |
| Only docs, CI, tests, internal refactor | **no bump** | Updated README, added test |

**Publish from the primary branch (usually `main`),** not from feature or development branches. What is published must always match what is on the release branch.

**When to bump:** Include the version change in the same PR as the work — no separate "bump version" commits after the fact.

**How to publish:**
1. Merge the release PR into `main`
2. Pull locally: `git checkout main && git pull`
3. Publish using your ecosystem's tool (`npm publish`, `cargo publish`, `twine upload`, etc.)
4. Sync develop: `git checkout develop && git merge main && git push origin develop`

**Rule of thumb:** If the change affects what users see, install, or depend on, it needs a version bump. If it only affects the project's internal development workflow, it does not.

### Per-PR bump declarations

Every PR targeting `develop` declares its intended version bump in the PR
description:

```
Version bump: {major|minor|patch|none}
```

- `major` — breaking change to public API, CLI, or scaffold contract
- `minor` — new feature, command, agent, or flag
- `patch` — bug fix or user-visible behavior change with no new surface
- `none` — docs, CI, tests, internal refactor (nothing consumers notice)

`/sync` aggregates declarations from all PRs merged since the last version
tag and picks the highest: `major > minor > patch > none`. If all merged
PRs are `none`, no release is cut — `/sync` updates shared-state files but
does not bump the version or open a PR to `main`.

This is how release batching works: internal-only work accumulates on
develop without triggering publishes, and multiple user-facing PRs group
into a single well-documented release.

### Edge cases

- **Release PRs (develop → main):** `/sync` excludes these from scanning.
  They ARE the release, not an input to one. Known limitation: any
  develop→main PR is excluded regardless of content. Safe in practice
  because that direction is only used for releases.
- **Revert PRs:** Declare the same bump level as the PR being reverted.
  Reverting a `patch` is itself a `patch`. A `patch` + matching revert
  in the same release group produces a net-zero user-visible change but
  still bumps the version — something shipped internally and was
  un-shipped, which is part of the release's history. Do not cancel
  them out.
- **Missing declarations:** Treated as `none` with a warning that
  propagates to the release PR body and CHANGELOG entry. Do not manually
  backfill old PR bodies — let them flow through as `none` so
  under-documentation is visible rather than silent.
- **No tags yet (first release):** `/sync` prompts to create a starting
  tag (default `v0.1.0`, customizable, cancelable). The tool does NOT
  silently invent a tag.
- **Hotfix merged directly to main:** Bypasses `/sync` entirely. Requires
  manual version management. Known limitation; out of scope.

**Optional:** GitHub labels (`release:major`, `release:minor`, etc.) can
replace body-text declarations for maintainers who prefer them. Deferred
to a future phase; not scaffolded by default.

## Gotchas

- Never force-push to main/master. Force-push to feature branches only when you
  own the branch and have communicated with collaborators.
- If a rebase goes wrong, `git reflog` is your friend. The old state is still there.
- Don't commit generated files (build output, node_modules, .pyc) — check .gitignore.
- When working in worktrees, remember that stashes are shared across the repo.
  A stash in one worktree is visible in another.
- Commit messages are documentation. Future you will read them. Write for that person.