t1k:worktree

Field	Value
Module	`t1k-maintainer`
Version	`3.2.1`
Effort	`low`
Tools	—

Keywords: branch, isolation, monorepo, parallel, rebase, workspace, worktree

How to invoke

/t1k:worktree
<subcommand> [args] — subcommands: create, session, sync, envsync, diff, status, list, remove, info, merge

Git Worktree Manager

Manage git worktrees across the full lifecycle: create, session, sync, envsync, diff, status, remove, merge.

All commands: node $HOME/.claude/skills/t1k-worktree/scripts/worktree.cjs <command> [args] [--json] [--dry-run]

Commands

Command	Usage	Description
`create`	`create [project] <feature> --prefix <type>`	Create worktree with branch. Anchored on the MAIN worktree: invoked from a secondary worktree it still lands in `<repo-parent>/worktrees/<repo>-<feature>`, and the created branch carries no upstream (first `push -u` sets it).
`remove`	`remove <name-or-path> [--force]`	Remove worktree + branch. Safe by default: aborts if the worktree has uncommitted changes, and never force-deletes an unmerged branch (it is kept). `--force` discards uncommitted changes; it still never force-deletes a branch.
`session`	`session <name-or-path>`	Get session command for worktree
`sync`	`sync [--worktree <name>]`	Rebase worktrees from base branch
`envsync`	`envsync [--source <path>] [--exclude <name>] [--dry-run]`	Sync .env files across worktrees
`diff`	`diff [--worktree <name>]`	Diff status per worktree vs base
`status`	`status`	Combined overview of all worktrees
`info`	`info`	Repo info, worktree location
`list`	`list`	List all worktrees
`merge`	`merge [--target <branch>] [--delete] [--no-reset]`	Merge worktree branch to base via PR

Decision tree — which reference do I load?

Load only the reference you need (each is self-contained):

Intent	Load
Create a new worktree (or check if one exists first)	`references/workflow-create.md`
Open or switch to an existing worktree session	`references/workflow-session.md`
Rebase worktrees onto latest base branch	`references/workflow-sync.md`
Sync .env files across worktrees / check compose drift	`references/workflow-envsync.md`
Inspect changes, ahead/behind, status	`references/workflow-diff-status.md`
Merge worktree branch back to base via PR	`references/workflow-merge.md`
Before/after reporting format for any command	`references/reporting-protocol.md`

Shared clones — when another session is in the same repo

A kit clone on a developer machine is shared infrastructure: several Claude sessions routinely work in one theonekit-* clone at once, and every worktree of a repo shares the main clone’s single HEAD.

Never git checkout / switch / branch -f in the main clone to do your work. It yanks whichever session owns the other worktrees out from under itself — its next commit lands on your branch, and recovery needs cherry-pick + git branch -f. hooks/shared-clone-worktree-guard.cjs blocks this; the audited override is T1K_SHARED_CLONE_CHECKOUT_APPROVED=1.
list first (already MANDATORY below) tells you which branches other sessions hold — before git refuses you, not after.
A branch already checked out elsewhere cannot be claimed twice, and that worktree belongs to another session, so do not work inside it. Take a detached worktree and publish explicitly:
Terminal window
```
git -C <clone> worktree add --detach <path> origin/<branch>
git -C <path> push origin HEAD:<branch>
```
Read without moving HEAD: git -C <clone> show <ref>:<path>, log, diff.
remove as soon as your work is pushed. A stale worktree keeps its branch claimed against every other session.

Operational notes

Intent routing (MANDATORY): Always run list --json before asking the user anything — a matching worktree name means jump straight to the session workflow.

Safety: Rebase auto-aborts on conflict to prevent data loss.

Reporting: Every command MUST show before/after state. End with a summary line. Full format: references/reporting-protocol.md.