gt-flow — Sensible Graphite stacking with honest "overkill" guard and zero-lost-code contract

Graphite (gt) and Git worktrees are not mutually exclusive. They are compatible (Graphite has provided explicit support since v1.8.4+), but they are not seamless in all cases. This skill gives you the precise mental model, official guardrails, decision criteria (including coupling), and safe execution patterns so you get the benefits of both without losing code or creating unrecoverable state.

This skill is the single source of truth for "should we use gt here, and exactly how (single worktree, multiple worktrees, or hybrid), so nothing gets lost".

It combines official Graphite guidance (learn-to-stack, how-to-structure-your-stacks, ai-ingestion/llms, comparing-git-and-gt, multiple-worktrees, create-stack, squash-fold-split, and the worktree support notes) with the hard-won realities of agentic execution in this repo (execute-plan dual-mode, git-worktrees, split-to-prs, worktree handoff between agent sessions and primary authenticated shell, and frequent concurrent agent lanes).

Quick Mental Model (gt vs worktrees vs plain git)

Tool	What it solves	Working directory model	Branch relationship tracking
Plain Git	Basic branching + history	Usually 1 working tree	None (you track it mentally)
Graphite (`gt`)	Stacked/dependent PRs + automated restacking + nice stack UX	Designed for 1 tree (strong support for many since 1.8.4+)	Explicit "stack" graph (parent/child)
Git worktrees	Multiple physical checkouts from one `.git` (isolation, parallel processes, no heavy switch cost)	Many working trees	None (Git doesn't track stacks)

Graphite adds the stack graph + cross-stack commands (gt sync + restack, gt modify, gt submit --stack, etc.).
Worktrees give physical isolation (separate dirs, separate node_modules/build state/IDE/dev servers) while sharing the object store.
They compose well when you follow the guardrails below. Graphite will actively protect you from mutating a branch checked out in another worktree.