Skip to content

ce-worktree.md

Latest commit

 

History

History
127 lines (75 loc) · 6.99 KB

ce-worktree.md

File metadata and controls

127 lines (75 loc) · 6.99 KB
Raw

ce-worktree

Ensure work happens in an isolated git worktree without disturbing the current checkout — by detecting existing isolation, deferring to the harness's native worktree tool, and only falling back to plain git.

ce-worktree is the isolation guardrail skill. Its value is judgment, not mechanics: most coding harnesses now create a worktree by default at session start, so the common case is that you are already isolated. The skill encodes the discipline to recognize that, defer to the harness's own worktree tooling, and only create a worktree with plain git as a last resort — so you never nest worktrees or create state the harness can't manage.

It is pure prose + inline git, with no bundled script, so it works verbatim on every supported target (Claude Code, Codex, Gemini, OpenCode, Pi).

TL;DR

Question Answer
What does it do? Ensures isolation exists. Detects an existing worktree first, prefers the harness's native worktree tool, falls back to git worktree add under .worktrees/<branch>
When to use it Starting work that should stay isolated; when ce-work or ce-code-review offers a worktree option
What it produces Either "you're already isolated, work in place" or a new isolated worktree
Skip when Single-task work that fits on a branch in the current checkout

The Problem

Asking an agent to "make a worktree" is increasingly the wrong default, because the agent is usually already in one:

  • Worktree-from-worktree — creating a worktree from inside a linked worktree resolves the new one against the main clone, landing it in a different directory tree the user isn't working in.
  • Phantom state — a behind-the-back git worktree add is invisible to the harness (Orca, Cursor, etc.) that owns worktree lifecycle: it can't list, navigate to, or clean it up.
  • Committed worktree contents — if .worktrees/ isn't gitignored, the worktree pollutes git status and risks being committed.
  • Cryptic branch names — auto-generated names like worktree-jolly-beaming-raven obscure what the worktree is for.

The Solution

ce-worktree runs isolation as an ordered decision, not a creation script:

  1. Detect existing isolation (compare --git-dir against --git-common-dir, with a submodule guard). Already isolated → report and work in place.
  2. Prefer the harness's native worktree tool (e.g. an EnterWorktree tool, a /worktree command, a --worktree flag) so the worktree stays managed.
  3. Inline git fallback only when neither applies: create .worktrees/<branch>, ensuring .worktrees is gitignored first, with a meaningful branch name.

What Makes It Novel

1. Detection before creation

The single most important behavior: before creating anything, determine whether the current directory is already a linked worktree. git rev-parse --git-dir and --git-common-dir differ inside both linked worktrees and submodules, so a git rev-parse --show-superproject-working-tree submodule guard disambiguates. When already isolated, the skill works in place rather than nesting.

2. Native-tool deference

If the harness provides a worktree primitive, the skill uses it instead of shelling out to git. This avoids creating phantom worktrees the harness can't see or clean up — the "don't fight the harness" rule.

3. Portable by construction

There is no bundled script and no ${CLAUDE_SKILL_DIR} dependence — only inline git the agent runs from the project directory. That is why the skill resolves identically on every target, and why it carries no ce_platforms gate.

4. Gitignore safety before creation

When the git fallback runs, the skill verifies .worktrees is gitignored (git check-ignore) before creating the worktree, so its contents are never committed.

5. Naming guidance for upstream callers

When ce-work or ce-code-review invoke the skill, they pass a meaningful branch name derived from the work (feat/crowd-sniff, fix/email-validation) — never an opaque auto-generated name.

Quick Example

You're in an Orca-managed worktree (the harness created it at session start) and ask ce-work to isolate the work. The skill runs Step 0: --git-dir and --git-common-dir differ, and the submodule guard returns empty → you are already isolated. It reports the worktree path and current branch and proceeds in place — no second worktree, no phantom state.

In a plain terminal checkout with no native worktree tool, the same invocation falls through to Step 2: it confirms .worktrees is gitignored, fetches the base branch, runs git worktree add -b feat/login .worktrees/feat/login origin/main, and cds in.

When to Reach For It

Reach for ce-worktree when:

  • You're starting work that should stay isolated from the current checkout
  • A skill (ce-work, ce-code-review) offered worktree as an option

Skip it when:

  • The work is single-task and fits on a branch in the current checkout
  • You are already isolated and have no need for a second, parallel workspace (the skill detects this for you)

Use as Part of the Workflow

ce-worktree is invoked from chain skills as their isolation step:

  • /ce-work — when starting work, the user can choose worktree isolation over branching in the current checkout
  • /ce-code-review — for reviewing PRs concurrently without disturbing in-progress work

Upstream callers pass meaningful branch names; the skill expects feat/..., fix/..., refactor/... shapes — not auto-generated random names.

Other worktree operations

List, remove, and switch use git directly — the skill provides no wrapper:

git worktree list                          # list worktrees
git worktree remove .worktrees/<branch>    # remove a worktree
cd .worktrees/<branch>                     # switch to a worktree
cd "$(git rev-parse --show-toplevel)"      # return to the current checkout root

FAQ

Why a skill instead of just git worktree add? The value isn't the git worktree add command — the agent knows that. It's the judgment: detect that you're probably already isolated, defer to the harness's worktree tooling, and don't nest or create phantom state. That discipline is shared by ce-work and ce-code-review, so it lives in one named skill rather than being duplicated and drifting.

I'm already in a worktree — will it make another? No. Step 0 detects existing isolation and works in place. A worktree-from-worktree is exactly the failure mode the skill prevents.

How do I clean up a worktree? cd "$(git rev-parse --show-toplevel)" to leave it, then git worktree remove .worktrees/<branch>. If the remote tracking branch is gone, prune with normal git commands such as git fetch --prune followed by git branch -d <branch> after verifying the branch is merged.

See Also

  • /ce-work — offers this skill as its isolation option
  • /ce-code-review — offers worktree isolation for concurrent review