wehub-resource-sync
128 lines
7.0 KiB
Markdown
128 lines
7.0 KiB
Markdown
# `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 `cd`s 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:
|
|
|
|
```bash
|
|
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`](./ce-work.md) — offers this skill as its isolation option
|
|
- [`/ce-code-review`](./ce-code-review.md) — offers worktree isolation for concurrent review
|