Org-scoped Git worktrees

Parallel agent or branch checkouts must land in one discoverable place. Dev-Centr’s today standard is owner-scoped linked worktrees — not a global hive bucket, and not a second full clone pretending to be a worktree.

This page is the practitioner how-to. Normative agent schema: agent-rules folder-schema.md (Git worktrees section). Operational skill: skill git-worktrees. Long-range placement redesign (repo-local ideals, relative paths, what Git still lacks): Git worktrees long-range.

Path

$CODE_ROOT/<host>/<owner>/.worktrees/<repo>-<purpose-slug>

Examples:

  • $CODE_ROOT/github.com/dev-centr/.worktrees/agent-rules-docs-pass

  • $CODE_ROOT/github.com/dev-centr/.worktrees/hive-watch-tray-fix

Piece Rule

Owner scope

Same <owner> folder as the main clone (org or user under <host>/)

Directory

Hidden .worktrees (not worktrees)

Leaf name

<repo>-<purpose-slug> — kebab-case purpose after the repo name

Branch (common)

agent/<purpose> — optional convention; path policy wins

Add a linked worktree

  1. Resolve the main clone (owned / .forks / .clones per hive-layout).

  2. Ensure $CODE_ROOT/<host>/<owner>/.worktrees exists.

  3. Linked add only:

git -C <main-clone> worktree add <path> [-b <branch>] <start-point>

Example:

git -C "$CODE_ROOT/github.com/dev-centr/agent-rules" worktree add \
  "$CODE_ROOT/github.com/dev-centr/.worktrees/agent-rules-docs-pass" \
  -b agent/docs-pass main

Then verify:

git -C <main-clone> worktree list

Forbidden (new worktrees)

  • Full-clone into .worktrees (git clone …/.worktrees/…) — that is a second independent repo, not a linked worktree.

  • $CODE_ROOT/.worktrees/<…>

  • $CODE_ROOT/worktrees/<…>

  • Non-hidden …/<owner>/worktrees/<…> when creating new ones (prefer .worktrees)

Why owner-scoped (compatibility bridge)

Agents invent layouts under pressure: siblings next to the clone, random /tmp trees, hive-root buckets, or "worktree" folders that are actually dirty standalone clones. Owner-scoped .worktrees keeps every checkout for an org (or user) under one folder agents and humans can grep, without sprinkling purpose checkouts through the repo tree itself.

That is today’s hive standard for agent compatibility. It is not the long-range ideal. Repo-local <repo>/.worktrees/<purpose> (shorter names, tighter mental association) needs Git help — relative path storage, git worktree add --local, auto exclude — before it becomes the default without path breakage. Until then, stay on owner-scoped linked trees. See Git worktrees long-range.

Move / migrate

  1. Prefer git -C <main-clone> worktree move <old> <new> when Git supports it and both paths share a volume.

  2. Else remove / relocate only with a clear plan — do not leave detached .git files pointing at dead paths.

  3. After move, git worktree list; prune stale entries if needed.

  4. Do not delete unique commits or dirty state to force a move — stop and report.

Related