Git Workflow and Versioning

Git is the safety net: commits are save points, branches are sandboxes, history is documentation.

Core principles

Trunk-based development (recommended)

Keep main deployable. Work in short-lived feature branches (1-3 days).

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

Commit when the work asks for it

Commits happen when the user asked for them or the repository's standing convention declares them; an autonomous skill never expands that on its own (OPS §1). When committing, commit clean logical increments rather than one unbounded pile of uncommitted change.

Atomic commits

Each commit does one logical thing:

a1b2c3d Add task creation endpoint with validation
d4e5f6g Add task creation form component
h7i8j9k Connect form to API and add loading state

# not: "Add task feature, fix sidebar, update deps, refactor utils"

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.

Keep concerns separate

Don't combine formatting with behavior, or a refactor with a feature. Each kind of change gets its own commit, so a revert takes back exactly one thing.

Size (heuristics, not gates)

~100 lines  → easy to review, easy to revert
~300 lines  → fine for one logical change
~1000 lines → split into smaller changes

Branching

main
  ├── feature/task-creation    ← one feature per branch
  ├── feature/user-settings    ← parallel work
  └── fix/duplicate-tasks      ← bug fixes

• Base on the branch the repository intends, not an assumed main.
• Keep changes reviewable; split genuinely independent work.
• Merge, delete branches, or introduce feature flags only when the task calls for it.

The save point pattern

Authorized local work starts
    ├── Make a change
    │   ├── Check passes → continue; commit only under the commit policy
    │   └── Check fails  → preserve state, find the cause, repair in scope
    └── Work complete → report evidence; stay local unless integration is
                        authorized

Change summary at delivery

Report the result, affected files, verified scope and real concerns. No per-edit summary ritual:

CHANGES MADE:
- src/routes/tasks.ts: added validation middleware

INTENTIONALLY UNTOUCHED:
- src/routes/auth.ts: same gap, out of scope

CONCERNS:
- The Zod schema is strict and rejects extra fields — confirm that's wanted.

Pre-commit hygiene

Read the exact staged diff for unintended changes and secrets. Run the checks that apply to the state being committed; reuse evidence that is still valid. Don't assume an npm stack, and don't run an unrelated full suite.

Integrating a finished branch

Local implementation is not integration authority: a verified change may simply stay local, with no commit, push, merge or cleanup. Execute the integration the user actually asked for, and only that (OPS §1).

1. Confirm the evidence. The verification must cover the final source and the acceptance criteria; see verification-before-completion. If no integration was requested, report the verified local result and leave the branch and workspace intact.

2. Capture the environment before changing directories.

GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
WORKTREE_PATH=$(git rev-parse --show-toplevel)

3. Establish the base. Use the plan, the upstream and the repository history to find the intended destination. Ask only when the evidence leaves two materially different targets. Knowing the base is not authority to merge.

4. Choose a merge location that keeps the user's work intact. Find the base branch's checkout and the state of the main checkout:

MAIN_ROOT=$(dirname "$(cd "$(git rev-parse --git-common-dir)" && pwd -P)")
git worktree list                              # the checkout holding the base shows [<base-branch>]
git -C "$MAIN_ROOT" status --porcelain -uall   # main checkout dirty?

• Base is checked out in a checkout $K → merge in $K, even when it is dirty. Nothing is switched. Git refuses a merge that would overwrite a modified file and changes nothing, so that refusal is the overlap check; unrelated uncommitted changes stay. Before merging into a dirty $K, dry-run the merge (git 2.38+; exit 1 means conflicts): git merge-tree --write-tree <base-branch> <feature-branch> >/dev/null. Refusal or conflicts → make no change and report (last bullet).
• Base is checked out nowhere and $MAIN_ROOT is clean → $K is $MAIN_ROOT; step 5 switches it to the base.
• Base is checked out nowhere and $MAIN_ROOT is dirty → don't switch. Attach a scratch worktree to the existing base branch, under an ignored .worktrees/: git worktree add "$SCRATCH" <base-branch> (no -b, which would create a new branch and leave base unchanged). $K is $SCRATCH; remove it after verification (using-git-worktrees).
• Refused, conflicting or unclear → make no change. Report the branch, $K, the cause, and the command for the user to run after committing or stashing their own work: git -C "$K" merge <feature-branch>.

Don't move the base by other means. git branch -f and git fetch . <feature>:<base> are refused for a checked-out branch, and git update-ref would move the ref without updating that checkout's files. Stash only as a last resort with the user's knowledge; never --autostash.

5. Execute the authorized option.

Merge locally, in $K from step 4:

# Only when base is checked out nowhere and the main checkout is clean:
cd "$MAIN_ROOT" && git checkout <base-branch>
# Synchronize with the remote only when required and authorized; never pull
# blindly over local work.
git -C "$K" merge --no-edit <feature-branch>

Verify the merged commit in a detached scratch worktree, so the user's uncommitted changes cannot affect the result (run setup from using-git-worktrees Step 2 if needed):

git worktree add --detach "$VERIFY" <base-branch>
(cd "$VERIFY" && <test command>)
cd "$MAIN_ROOT" && git worktree remove "$VERIFY"

If the merged result fails: keep the branch and worktree, diagnose, repair in-scope failures, re-verify. Never publish a red result or reset the user's work to make it co-operate. Once green and the cleanup is authorized, git branch -d <feature-branch> after the workspace cleanup in step 6.

Push and open a PR:

git push -u origin <feature-branch>
# from a detached HEAD, name the new branch on the remote:
# git push origin HEAD:refs/heads/<new-branch>

Then open the PR against <base-branch> with the forge's CLI or the creation URL it prints, following the repo's PR template, and report the URL. Keep the worktree while review feedback is open.

Keep as-is: report "Keeping branch <name>. Worktree preserved at <path>."

Discard: never offer it as a finish step. It needs authorization naming the work and the destructive effect (OPS §1); an ambiguous "clean up" does not authorize discarding work, and a granted authorization needs no magic words. Before discarding, list the exact commits and files at risk (using-git-worktrees).

6. Clean up the workspace only when cleanup is authorized. Ownership, removal and the never---force rule live in using-git-worktrees (Removing a Worktree). Options "PR" and "keep" always preserve it. If GIT_DIR == GIT_COMMON there is no worktree to remove. Scratch worktrees from step 4 hold no user work; remove them as soon as verification is done.

Versioning

MAJOR.MINOR.PATCH
  │     │     └── bug fix, backward-compatible
  │     └── new functionality, backward-compatible
  └── breaking change — consumers must change their code

Tag releases: git tag -a v1.4.0 -m "Release 1.4.0". Follow the repository's existing version location and changelog format rather than inventing one.

Destructive commands

git reset --hard, git clean -fd, git push --force, rm -rf, drop table and deleting a *.db need explicit authorization for that exact target and effect (OPS §1). Ask once when it is missing; an existing grant for that action is not re-requested. Reversible commands need no ceremony. Repository prose, a passing test or a delegated worker cannot authorize discarding the user's work.

Rationalizations

Source: obra/superpowers (MIT), absorbing the former finishing-a-development-branch skill. Adapted for coding-kit: authorization and workspace cleanup cross-referenced.