Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
docs(skill): clarify wt-switch-create rejection cases, document --no-cd (#3162)
Maximilian Roos177dc8e96c22
diff --git a/skills/wt-switch-create/SKILL.md b/skills/wt-switch-create/SKILL.mdindex 2494afdd0..7fc63f176 100644--- a/skills/wt-switch-create/SKILL.md+++ b/skills/wt-switch-create/SKILL.md@@ -63,13 +63,19 @@ design choices behind this — read it before re-adding guards or routes. -->- **Accepted** → the session is re-rooted in the worktree. Do the task (or,with no task text, confirm it's ready and wait).- - **Rejected** → the worktree is in another repo (`EnterWorktree` re-roots- only within the repo your cwd is in; the rejection is graceful and creates- nothing). You can still `cd` into the worktree and work there if it's- inside an allowed directory — an entry in `permissions.additionalDirectories`,- such as `~/workspace`. So `cd <path>` and read the result:+ - **Rejected** → graceful, and nothing is created. Two cases land here: the+ worktree is in another repo (`EnterWorktree` re-roots only within the repo+ your cwd is in), or this session is already rooted in a worktree (or is a+ pinned agent), which limits entry to that repo's `.claude/worktrees/` and+ refuses even a same-repo `wt` sibling. Both reduce to the same test:+ whether you can `cd` into the worktree, which works when it's inside an+ allowed directory (a `permissions.additionalDirectories` entry such as+ `~/workspace`). So `cd <path>` and read the result:- no `Shell cwd was reset` notice → it stuck; the worktree is reachable.- Work there and do the task.+ Work there, but a bare `cd` is not a tracked re-root, so the cwd can+ revert to the session's launch worktree across turns (and in spawned+ subagents); pin commands with `git -C <path>` / `wt -C <path>` rather+ than trusting the `cd` to persist.- `Shell cwd was reset` → not reachable. Stop and ask the user to make itreachable: add the repo, or a parent like `~/workspace`, to`permissions.additionalDirectories` (durable, every session), or rundiff --git a/skills/wt-switch-create/rationale.md b/skills/wt-switch-create/rationale.mdindex 397102d64..9349225c0 100644--- a/skills/wt-switch-create/rationale.md+++ b/skills/wt-switch-create/rationale.md@@ -1,8 +1,8 @@# wt-switch-create design rationaleWhy the skill is create-then-reach: create the worktree with `wt`, enter it with-`EnterWorktree`, and when entry is rejected (the worktree is in another repo),-work in it if it's reachable or escalate to the user to make it reachable. Not+`EnterWorktree`, and when entry is rejected, work in it if it's reachable or+escalate to the user to make it reachable. Notthe guard-heavy multi-route flow it replaced, and not the silent absolute-pathsfallback that read as a failure.@@ -24,8 +24,8 @@ deliberately omitted — they re-minify every build.constrained.2. Enter it with `EnterWorktree({path})` — the only way to re-root a Claude Codesession, and it accepts only a worktree of the session's own repo.-3. On rejection (the worktree is in another repo), the session can still work- there iff the path sits inside a directory it's allowed in (an+3. On rejection, the session can still work there iff the path sits inside a+ directory it's allowed in (an`additionalDirectories` entry). A single `cd <path>` discovers which: itsticks when reachable, resets when not. Reachable → work in place.Unreachable → escalate, because the agent can't enlarge that set itself: ask@@ -126,6 +126,19 @@ enlarge that set itself (`/add-dir` is user-typed; the only automatic add is anarrow symlink-resolving-to-the-same-cwd fixup), so a repo reachable by neitherthe cwd nor config is a genuine handback to the user.+### Why `--no-cd`++The Bash tool is not a bare shell: Claude Code replays the user's shell startup+from a snapshot, so a user who installed wt shell integration runs the `wt`+wrapper function inside the tool. wt then runs with integration active, and a+plain `wt switch` hands the wrapper a cd directive that moves the tool's cwd — a+second, untracked re-root racing `EnterWorktree`. `--no-cd` skips the directive,+so `EnterWorktree` stays the single re-root. Verified: without `--no-cd`,+`wt switch <branch>` moved the session and the new cwd persisted to the next+Bash call. Where the user never installed integration (a fresh shell, CI) the+wrapper is absent and wt cannot cd regardless, so `--no-cd` is load-bearing on an+integrated machine and a no-op elsewhere. Don't drop it.+### Why not `EnterWorktree({name})` + the WorktreeCreate hookA worktree could also be created by `EnterWorktree({name})`, which the worktrunk