Git Workflow

Use git switch for branch operations, never git checkout.

checkout is overloaded: checkout -- silently destroys uncommitted work, and checkout <branch> is ambiguous when a file shares the name. switch only switches branches. Use git restore for file-level operations.

Safety: never discard unowned work

The single most important rule: uncommitted work is the only work that can be lost — and multiple agents (Cursor, Codex, Claude) may share one working tree. A git stash, git reset --hard, git checkout -- . / git restore, or git clean -fd that "tidies up" silently wipes a concurrent session's uncommitted changes. This happened on 2026-06-15 — a git stash hid another agent's uncommitted ingests (Remix/Bit/theSVG), recovered only via the reflog, then committed.

• Commit your own work promptly (a WIP branch is fine) so a teardown can't lose it.
• Before any tree-clearing op, run git status; if there are changes you did not author, do not stash/reset/clean — commit to a branch or use a worktree.
• Parallel agents → separate git worktrees, never a shared checkout.
• Recover lost uncommitted work from git reflog (resets) or git stash list (stashes) — it is rarely truly gone.

Enforced for Cursor by the git-guard.sh beforeShellExecution hook (config/cursor/hooks/), which requires human approval before destructive git ops. Cross-agent rule: AGENTS.md § Git Safety.

Trunk-Based Development

The target is 200 lines of changed code or less per PR, excluding generated files. Larger changes get split into stacked diffs. Feature branches branch off dev. Keep features small and scoped.

Git Worktrees

Worktrees are the mechanism for managing multiple branches without context switching. Each worktree is a separate checkout of the same repository, with its own working directory and HEAD, sharing the underlying object database.

git fetch origin && git switch dev && git pull --ff-only
mkdir -p ../wt

git worktree add -b feat/a ../wt/a dev
git worktree add -b feat/b ../wt/b feat/a   # stacked
git worktree add -b feat/c ../wt/c feat/b   # stacked

After feat/a merges, rebase downstream:

git -C ../wt/b fetch origin && git -C ../wt/b rebase origin/dev
git -C ../wt/c fetch origin && git -C ../wt/c rebase feat/b

Use worktrees for: multiple independent features, stacked dependent changes, large refactors that need phasing, or parallel work that would cause file conflicts.

Conventional Commits

Format: type(scope): description. Type is feat, fix, refactor, docs, test, chore, or similar. Imperative mood, lowercase, no period, under 72 characters.

Never use "and" in a commit message. If you need "and", it is two commits.

Commit Hygiene

Before committing, run git status -sb and review diffs with git diff. Group changes by intent, not by file type. Use git add -p to stage precisely. If your branch is behind upstream, fetch and rebase before committing. When pushing after a rebase, use --force-with-lease instead of --force.

Atomic Branch Operations

When other agents or coworkers are active in the monorepo, branch switches must be atomic: stash everything, do the work on the target branch, switch back, restore. The pattern chains commands with && so if any step fails, the chain stops.

git stash push -u -m "wip <reason>" \
  && git switch <target-branch> \
  && <do work> \
  && git switch - \
  && git stash pop

Use git switch - to return to the previous branch. For anything beyond a quick atomic operation, use worktrees instead.

Caveat (concurrent agents): git stash push -u stashes the entire working tree — including uncommitted work from other agents sharing the checkout. Only use the stash-pop pattern in a tree you own; with concurrent agents, use worktrees so no tree is shared (see § Safety above). The git-guard hook will ask for confirmation before a stash. Source: incident 2026-06-15

Concept Position

---

Timeline

• 2026-07-01 | Concepts category refresh added this page to the Agent harness and runtime primitives family, linked it to Concept System Map, and kept it standalone because it owns this reusable mental model: Use git switch for branch operations, never git checkout. Source: User request, 2026-07-01