Branching

Branching

Full reference: .github/BRANCHING_STRATEGY.md (worktree deep-dive, .gitignore policy, lifecycle walkthrough). This skill is the actionable summary.

The core rule

Never commit directly to main/master/trunk/develop/production/ release/*. Always: branch → commit → push → PR → merge. This repo enforces it locally via git config core.hooksPath .github/hooks (already set here) — don't rely on the admin bypass.

Branch naming

{type}/{description}, lowercase, hyphens not underscores, short and specific.

Good: feature/user-authentication, fix/email-validation-crash. Bad: update, Feature/UserAuth, fix_everything.

Worktrees

A worktree is a second working directory backed by the same repo, so you can have several branches checked out at once without stashing or re-cloning.

Reach for one when:

• Running long tests/builds on one branch while you keep coding another.
• Reviewing a PR branch without disturbing your in-progress work.
• Running agents in parallel — give each agent/task its own worktree so concurrent runs never fight over one working tree or index. This is the highest-value case for an agent harness.

Skip it for a single quick edit on an already-clean, already-scoped branch — a plain branch switch is cheaper. That exception does not apply once either mandatory condition below is true.

Mandatory, not a preference, before starting new feature/fix implementation work (not Q&A, not read-only investigation) when either is true:

• git status --porcelain is non-empty (a dirty tree), or
• the current branch is unrelated to the task (someone else's topic branch, a chore/* tree, anything not already scoped to this work).

In that state, git checkout -b directly in the current checkout is disallowed — isolate first:

git fetch origin
git worktree add -b feature/<short-name> .worktrees/feature-<short-name> origin/main
cd .worktrees/feature-<short-name>

❌ git checkout -b feature/foo on top of a chore/* branch carrying 100 modified files. ✅ git worktree add -b feature/foo .worktrees/feature-foo origin/main.

This check runs before the first file edit, on its own — it is not something to ask the user about. A prompt like "let's build X" authorizes starting the work, not skipping isolation. Only ask the user when choosing between multiple clean strategies (e.g. a branch name); never ask whether a dirty tree should be isolated — just do it.

A consumer project without full harness-hook wiring has no automatic signal for this rule — tools/harness-session-start.sh is an optional, standalone script (no hook installation required) that prints this same warning at session start when the tree is dirty; wire it into a project's own session-start step if useful (issue #249, item 7).

The rules that bite:

• One branch per worktree — git refuses to check the same branch out in two worktrees at once.
• Keep them in .worktrees/{branch-name}/ (gitignored — it's in .github/.gitignore.template), not scattered sibling directories.
• Hooks are shared by default — worktrees share one .git config and core.hooksPath, so trunk protection and the pre-push hook apply in all of them; you won't accidentally sidestep them by moving to a worktree (short of deliberately enabling per-worktree config).
• Remove with git, not rm -rf — git worktree remove <dir> (or git worktree prune if you already deleted it by hand), so git's bookkeeping stays consistent.

Full mechanics (submodule caveat, cleanup): .github/BRANCHING_STRATEGY.md.

If a secret was committed

Act immediately — rotate the secret regardless of whether history cleanup succeeds; treat anything that touched git history as compromised.

1. Preferred: BFG Repo Cleaner on a fresh mirror clone: bfg --delete-files .env then git push --force. See .github/BRANCHING_STRATEGY.md for the full command sequence.
2. Fallback: git filter-repo --path .env --invert-paths (the modern, maintained replacement for filter-branch).
3. Rotate the secret. Tell everyone with a clone to re-clone, not pull.