tabbyml/pochi/worktree-isolation

Worktree Isolation

A worktree gives you a clean checkout of an exact committed revision without touching anything in the user's current workspace.

When to use one

Decide using both the required source state and whether the current checkout is safe:

• The current checkout contains the intended source and is safe to edit → stay where you are. A commit-based worktree cannot contain the user's uncommitted changes, so stay if the task targets them.
• The task must modify another committed branch, commit, or pull-request revision, or the work could disturb the current checkout → create a worktree from that exact committed base.
• The intended base or whether local changes are required inputs remains ambiguous → ask with askFollowupQuestion before editing; never guess.

For read-only inspection or review, prefer the current checkout, git show, or gh pr diff; create a worktree only when a full checkout is genuinely required. If the revision you need is not available locally, obtain it through an authorized workflow or report the limitation—never quietly substitute HEAD.

Hard rules

These hold no matter how you reached this skill:

1. Worktrees are created only by the trusted script below. Never run git worktree add, create the branch, or prepare the destination yourself — the script owns setup and the optional initialization phase.
2. Preparing or using a worktree must never modify, discard, or migrate any existing tracked or untracked changes in the user's workspace.
3. Do not commit in the worktree unless the user explicitly asks for a commit.
4. Leave the worktree and its branch in place when you finish — even after a failure, do not remove a partially created worktree. Cleanup is the user's decision.
5. Initialization is opt-in. By default the script must not copy .worktreeinclude files or run project scripts.

Creating it

Resolve the script relative to this SKILL.md and run exactly one command with the current repository as cwd:

• POSIX: sh <skill-directory>/scripts/create-worktree.sh --topic <short-topic> --base <committed-base>
• Windows: powershell -ExecutionPolicy Bypass -File <skill-directory>/scripts/create-worktree-windows.ps1 -Topic <short-topic> -Base <committed-base>

Pass the exact committed base the task requires; use HEAD only when the current commit really is the intended base. Do not pass shell fragments.

Without an initialization flag, these commands only create the worktree and return initialized: false. If the task cannot proceed without project initialization, inspect the main worktree's .worktreeinclude and the target revision's .pochi/init.sh or .pochi/init.ps1 before creating the worktree. Only after deciding that both the copied files and executed commands are necessary and safe, add the platform-specific initialization flag to the creation command:

• POSIX: add --init
• Windows: add -Initialize

Initialization first copies the .worktreeinclude files, then runs the platform's initialization script when present. If either step fails, the script returns ok: false and leaves the worktree in place.

The script prints a JSON result: {ok, root, branch, base, initialized, error}. If ok is false, stop and report the error.

Working in it

From the returned root on, that path is your workspace: run every file read, search, edit, review, and command there, and never mix original-workspace paths into worktree operations (or vice versa).

In your final result, report the worktree path and branch, and state that they were retained for the user to clean up explicitly.