feat(source-control): machine-agnostic worktree setup skill (detect -> decide -> install)

[kyle-sexton]

Summary (epic)

Build a machine-agnostic worktree setup skill/action in the source-control plugin that (1) detects the machine/environment, (2) applies research-backed decision logic to choose the right worktree layout for that machine/project, and (3) installs the chosen convention. The convention must not be hardcoded to any one machine, user, org, or toolset — the skill decides per environment.

Component

plugins/source-control/skills/worktree/** (new setup action, or a sibling setup skill).

Why

Worktree placement is currently inconsistent across tools and undocumented-by-convention. Claude Code's native default (.claude/worktrees/ inside the repo) has real problems (see the double-load issue and the unify issue). The right layout is environment-dependent (does the machine have ghq? gwq? which drive is the dev drive? which OS?), so a static rule is wrong — the skill should detect and decide.

Decision logic to encode (from consensus research; see Sources)

Detect, then choose:

• Environment probes: OS; presence of ghq (+ ghq root); presence of gwq/wt; available drives / dev-drive; whether the repo is under a recursively-scanned tree (e.g. a chezmoi source dir) that would leak; Claude Code version (for hook-contract pinning).
• Layout options + tradeoffs (all evidence-tiered):
  • Central external root (outside every source tree, e.g. <dev-drive>:\worktrees\<owner>-<repo>-<branch>): avoids ghq-list pollution, avoids the CC nested double-load, avoids recursive-scanner leaks; requires creation via git worktree add/a manager rather than CC-native. Default recommendation for the "many repos, occasional short-lived worktrees" profile.
  • Per-repo sibling: locality, IDE-native, but pollutes ghq list when the clone lives under the ghq tree (verified) — disqualified where one-folder-per-repo matters.
  • Inside-repo .claude/worktrees/ / .worktrees/: rejected — CC double-load + recursive-scanner leak.
  • Bare-clone hub: niche/experimental, high setup, fights ghq normal clones — not recommended for this profile.
  • gwq central root: same external-root model, tool-assisted; adopt only if worktree volume grows.
• Windows constraints: keep repo and its worktrees on the same drive letter (cross-drive relative links are impossible — git stores absolute paths, defeating worktree.useRelativePaths); keep the base path short (MAX_PATH); set worktree.useRelativePaths=true when same-drive.
• Cross-tool reality: there is no git-level knob and no universal unifier; Cursor/Gemini native worktree paths cannot be relocated; document the honest per-tool map, and route manual/CLI worktrees through one root. Codex ($CODEX_HOME/.codex/worktrees) and the babysit fleet root stay exempt (helper-managed, lease-scoped).

Install actions the skill should perform (per chosen layout)

• Configure the CC WorktreeCreate hook (see the unify issue) with the computed root — after the two empirical gates pass.
• Set worktree.useRelativePaths=true where same-drive.
• Wire .worktreeinclude-equivalent local-file copying into the shared helper (the hook bypasses .worktreeinclude).
• Emit the per-tool map + exemptions as skill output (discoverable), not a drift-prone standalone doc.

Acceptance criteria

• setup detects: OS, ghq/gwq/wt presence, ghq root, dev drive, recursive-scanner source dirs, CC version.
• Chooses a layout via the encoded tradeoff logic and explains the choice + limitations to the user.
• Installs the convention idempotently; safe to re-run; reversible.
• No hardcoded machine/user/org/drive paths — all derived.
• Honors exemptions (Codex, babysit) and documents the per-tool map as skill output.
• Depends on the unify issue (shared helper) and supersedes the stale dotfiles doc (see retire-doc issue).

Sources (consensus research, this session)

• git worktree has no default-location config; git is layout-agnostic: https://git-scm.com/docs/git-worktree , https://git-scm.com/docs/git-config
• CC native worktree behavior, hooks, .worktreeinclude, worktree.baseRef: https://code.claude.com/docs/en/worktrees , https://code.claude.com/docs/en/hooks , https://code.claude.com/docs/en/settings
• CC nested .claude/ double-load bug: anthropics/claude-code #29599, #23565; exclusion gotcha #57512; missing subdirs in worktree #28041
• Cross-tool survey (Cursor ~/.cursor/worktrees, Gemini .gemini/worktrees, Codex desktop "Worktree root", gwq/wt): tool docs per survey
• ghq-native central-root manager gwq: https://github.com/d-kuro/gwq
• Windows: worktree.useRelativePaths (git 2.48), cross-drive relative-path impossibility (path.c relative_path()), MAX_PATH (core.longpaths + OS LongPathsEnabled)

[kyle-sexton]

Sub-issues of this worktree-convention epic:

• feat(source-control): unify native-hook + /worktree-skill worktree creation via one shared helper #399 — unify native-hook + /worktree-skill creation via one shared helper (blocks the install step here)
• fix(source-control): /worktree creates in-repo .claude/worktrees/ -> hits CC double-load bug; create out-of-tree #400 — /worktree creates in-repo .claude/worktrees/ → CC double-load bug; create out-of-tree
• chore(source-control): retire stale ghq-layout-sibling-pr-worktrees doc; plugin owns worktree convention #401 — retire stale ghq-layout-sibling-pr-worktrees doc; plugin owns the convention

Related repo-hygiene items surfaced in the same session: #393 #394 #395 #396 (git-tree-reset bugs), #397 (multi-repo clean + skip/dirty guard).

[kyle-sexton]

Decision brief (2-minute read)

Problem. The setup skill must persist a machine-computed worktree root somewhere both #399's shared helper and the native WorktreeCreate hook can read at creation time — but the concrete root is machine-local (drive letter, ghq presence, OS all differ per machine), so it cannot be a team-shared tracked value. This brief decides where that root config lives and how detect→decide→install behaves given that this repo's own setup skills cannot write plugin config directly.

Today. Verified against the current checkout (789ec6c):

• /worktree create calls EnterWorktree(name) as its final action (plugins/source-control/skills/worktree/context/create.md:55, SKILL.md:66), which in a git repo lands in Claude Code's native .claude/worktrees/<name> — the exact placement that triggers the fix(source-control): /worktree creates in-repo .claude/worktrees/ -> hits CC double-load bug; create out-of-tree #400 double-load bug. There is no external-root config surface for the interactive path anywhere in the skill.
• A machine-local directory-config precedent already ships: babysit_worktree_root is a userConfig key of "type": "directory" (plugins/source-control/.claude-plugin/plugin.json:106-110), defaulting to the plugin data dir's worktrees/. Babysit worktrees are helper-managed and lease-scoped, and feat(source-control): machine-agnostic worktree setup skill (detect -> decide -> install) #398's body already marks them exempt — so this is a pattern to reuse, not the same key.
• Two config-seam conventions coexist in this repo, and this repo's CLAUDE.md assigns them explicitly: userConfig (${user_config.KEY}) for "personal or administrator-provided scalars"; a tracked consumer-repo file (e.g. .claude/source-control.md, .work-item-tracker.json) for "tracked repository policy and team conventions."
• Load-bearing constraint on the install verb: plugins/source-control/skills/setup/SKILL.md:219-236,251-253 states the skill cannot hand-write userConfig/pluginConfigs (Claude Code owns them); for babysit it instead documents and walks two sanctioned reconfigure paths (interactive /plugin configure, headless uninstall+reinstall with --config).

Options (about where the root is stored, not which layout is chosen — the body already decided "central external root" with sources; that is not re-opened here):

1. RECOMMENDED — Store the root in a new userConfig directory key (e.g. worktree_root), mirroring babysit_worktree_root exactly. Both feat(source-control): unify native-hook + /worktree-skill worktree creation via one shared helper #399's helper and a WorktreeCreate hook resolve ${user_config.worktree_root}.

   • Rationale. The root is a machine-local scalar, which is precisely the userConfig bucket per this repo's CLAUDE.md. A tracked file holding a concrete path (D:\worktrees\…) would be wrong on every teammate's machine and every other OS — a repo-agnostic-rule violation. The type: "directory" precedent already works in this plugin.
   • The "install" asymmetry — state it plainly. The flagship verb is install, but the one value that matters most is the one setup cannot write: per the setup skill's own contract it may write the hook and git config (worktree.useRelativePaths=true when same-drive) directly, but the root must go through the two sanctioned userConfig paths. So "install the root" = detect → compute → recommend the value → walk the sanctioned reconfigure path (identical to how babysit config is handled today), not a file write. This still satisfies "idempotent, re-runnable, reversible": re-running re-detects and re-recommends; reversing = unset the key.
   • Unset/default behavior — the discriminating detail. When worktree_root is unset, the design must not silently fall back to CC's .claude/worktrees/ (that re-triggers fix(source-control): /worktree creates in-repo .claude/worktrees/ -> hits CC double-load bug; create out-of-tree #400). Align with feat(source-control): unify native-hook + /worktree-skill worktree creation via one shared helper #399's decided interim: refuse-with-guidance until configured, i.e. unset → the helper/hook decline and point at setup, never the buggy native default. Tie reversibility to the same answer: unset → safe refusal, not the bug.
   • Future-state risk (accepted, not fatal). userConfig cannot be rewritten non-interactively except on fresh install; a running session won't see a change until a fresh session. This limitation is inherent to pluginConfigs and is already accepted and documented for the babysit surface — not a reason to prefer a tracked file.

2. Tracked consumer-repo file (like .claude/source-control.md). Rejected as primary: a concrete machine path in a committed file breaks every other machine/OS and violates the repo-agnostic rule. Viable only for machine-agnostic policy (which layout was chosen + rationale), not the path — see Option 3.

3. Hybrid — tracked policy + userConfig path. Tracked file records the layout decision (which encoded option + why: team-reviewable); userConfig holds the machine-specific path. Cleanest team-vs-machine separation, but two surfaces to keep in sync for a tool that is solo today. Defer behind Option 1 with a trigger: adopt when a shared, reviewable layout policy becomes a real team need (record it, don't build it yet).

4. Bake the literal path into a WorktreeCreate hook written to user settings.json. Rejected: hardcodes an absolute path (drifts when drives/machines change), is more invasive and less reversible than a userConfig key, and is less plugin-form-safe than a plugin-shipped hook.

Flagged HOW sub-decision (verify, don't assert): hook shipped-by-plugin vs written-to-settings. A plugin-shipped WorktreeCreate hook that reads ${user_config.worktree_root} is more plugin-form-safe than setup writing a hook into user settings.json. But whether ${user_config.KEY} expands inside a settings.json hook is an unverified platform-behavior claim — confirm against current Claude Code hooks/settings docs before committing. The recommendation does not hinge on it: userConfig-as-storage stands on the in-repo precedent + this repo's design rule regardless of the hook mechanic. Note also that the hook-install step is downstream of #399's Gate 1/Gate 2 (real stdin field set; whether hook-relocated out-of-tree worktrees prompt under normal permissions).

Verification note. Repo-derived claims above (the type: directory precedent, the "setup cannot write pluginConfigs" limitation, the current .claude/worktrees/ landing) are sourced to the cited files. The two platform-behavior claims — ${user_config.KEY} expansion inside a settings.json hook, and headless reconfigure requiring uninstall+reinstall — are unverified here and must be confirmed against current official docs per this repo's fresh-docs mandate before implementation.

Related.

• feat(source-control): unify native-hook + /worktree-skill worktree creation via one shared helper #399 — shared helper; its brief left WHERE to feat(source-control): machine-agnostic worktree setup skill (detect -> decide -> install) #398 ("userConfig / tracked config") and set interim behavior to refuse-with-guidance. This decision resolves that to userConfig and matches the interim.
• fix(source-control): /worktree creates in-repo .claude/worktrees/ -> hits CC double-load bug; create out-of-tree #400 — the concrete high-priority double-load bug; the unset→refuse behavior above must avoid re-triggering it.
• chore(source-control): retire stale ghq-layout-sibling-pr-worktrees doc; plugin owns worktree convention #401 — retire the stale dotfiles worktree doc once the plugin owns the convention (this skill's output is the convention's home).
• source-control: babysit worktree pruner hard-depends on ghq (undeclared, author-personal repo-layout tool) #438 — babysit worktree pruner's ghq coupling; same convention family but explicitly exempt per feat(source-control): machine-agnostic worktree setup skill (detect -> decide -> install) #398's per-tool map (babysit_worktree_root stays a separate key).

[kyle-sexton]

HELD for operator (tower overnight decision resolver, Opus) — folder-placement convention lock, not autonomously decidable.

I verified the RECOMMENDED option (new worktree_root userConfig key mirroring the existing babysit_worktree_root precedent) and it is well-grounded and reversible. I am nonetheless holding, for one reason that overrides "reversible + veto-tagged":

• This epic adopts central-external-root as the default worktree layout and supersedes the documented sibling convention (its own sub-issue chore(source-control): retire stale ghq-layout-sibling-pr-worktrees doc; plugin owns worktree convention #401 exists to retire that doc). That is a folder-placement convention change — an independent operator-reserved (Class C) category, per the retained carve-outs on control-tower: closure-audit batch 2026-07-20 — operator decisions (fold-member consolidation, re-baseline additions, label normalization, title convention) #607 ("conventions… remain OPERATOR-ONLY"). Deciding the config mechanism adopts the convention in practice, so the "the fork is only the key location" framing does not remove it from that category.
• Precedent in this same overnight session: the tower's control-tower: closure-audit batch 2026-07-20 — operator decisions (fold-member consolidation, re-baseline additions, label normalization, title convention) #607 item-3 correction established that a specific instruction (there, the issue-metadata conventions: operationalize native types, sub-issues hierarchy, dependencies, priority re-baseline, close-reason + documented conventions (umbrella) #552 no-silent-relabel gate) is not overridden by the general decide-and-log delegation. The "convention lock = HOLD" instruction is the specific rule here.
• Authoring an epic with a decision brief and then labeling it needs-decision stages the call as the operator's, not as delegated.

Operator, this needs your ruling: confirm central-external-root + the worktree_root userConfig mechanism (RECOMMENDED, mirrors babysit_worktree_root), and separately whether #401 retires the sibling doc. Everything downstream (#399, #400) is blocked on this.

Note: two platform-behavior claims (userConfig expansion inside settings.json hooks; headless reconfigure) remain UNVERIFIED but gate only Phase B implementation, not your layout ruling.

This was generated by AI (tower overnight decision resolver, Opus).

[kyle-sexton]

OPERATOR RULING (in-session, 2026-07-21 ~16:5xZ, recorded by control tower): central-external-root placement RATIFIED, with the machine-computed root stored in a new worktree_root userConfig directory key mirroring the existing babysit_worktree_root key (plugin.json precedent). Per-repo sibling placement is disqualified (pollutes ghq list where the clone lives under the ghq tree — verified empirically). This resolves the convention lock the overnight resolver correctly held. #399's phased shared-helper plan (Phase A skill-first, Phase B hook behind the two empirical gates) proceeds against this ruling; #400 stays blocked-by #399 Phase A. Flipping #398 and #399 to status: ready.

This was generated by AI (control tower, session 6).