Git conventions

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 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.