Skip to content
Skills Library
Programming · Automation

using-git-worktrees

/using-git-worktrees

Use when starting feature work that should not touch the current checkout, before executing an implementation plan, or when the user asks for a worktree or isolated workspace. Detects existing isolation, then prefers a native worktree tool, then falls back to git worktree.

Repository
refract ↗
Licence
MIT
Last repository change
13.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when starting feature work that should not touch the current checkout, before executing an implementation plan, or when the user asks for a worktree or isolated workspace. Detects existing isolation, then prefers a native worktree tool, then falls back to git worktree.

Original author description

Use when starting feature work that should not touch the current checkout, before executing an implementation plan, or when the user asks for a worktree or isolated workspace. Detects existing isolation, then prefers a native worktree tool, then falls back to git worktree.

How it works

  1. Role
  2. Constraints
  3. Step 0: Detect Existing Isolation
  4. Step 1: Create the Workspace
  5. Step 2: Project Setup
  6. Step 3: Verify Clean Baseline
  7. Step 4: Hand Off
  8. Wave Mode
  9. Output Format
Original SKILL.md headings · 169 lines, 964 words
SKILL.md preview
---
name: using-git-worktrees
description: "Use when starting feature work that should not touch the current checkout, before executing an implementation plan, or when the user asks for a worktree or isolated workspace. Detects existing isolation, then prefers a native worktree tool, then falls back to git worktree."
---

# Using Git Worktrees

## Role

This skill owns workspace isolation. It ends with a ready workspace on an
attached branch. `coordinating-multi-model-work` owns everything after that,
including Refract registration.

Order of preference: detect existing isolation, then use a native worktree
tool, then fall back to `git worktree`. Never fight the harness.

## Constraints

- Create at most one worktree per request, except in wave mode.
- Use absolute paths for every command after creation.
- Write ignore rules only to `$(git rev-parse --git-common-dir)/info/exclude`.
  A committed `.gitignore` imposes one contributor's layout on everyone.
- Install dependencies and run tests with the project's own documented
  commands. When none can be found, ask.

## Step 0: Detect Existing Isolation

```bash
GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
BRANCH=$(git branch --show-current)
# Prints a path only inside a submodule. Treat a submodule as a normal repo.
git rev-parse --show-superproject-working-tree 2>/dev/null
```

| Result | Action |
|---|---|
| `GIT_DIR != GIT_COMMON`, not a submodule, on a branch | Report "Already isolated at `<path>` on `<branch>`." Go to Step 2. |
| Same, detached HEAD | Report it. Ask the user for a branch name, because coordination needs an attached branch. Go to Step 2. |
| `GIT_DIR == GIT_COMMON`, or a submodule | Normal checkout. Continue below. |

In a normal checkout, honor any worktree preference already declared in the
user's instructions. Otherwise ask once:

> "Would you like me to set up an isolated worktree? It protects your current
> branch from changes."

If the user declines, work in place and go to Step 2.

## Step 1: Create the Workspace

### 1a. Native tool

With consent given, use a native worktree tool when one exists: a tool such as
`EnterWorktree` or `WorktreeCreate`, a `/worktree` command, or a `--worktree`
flag. Native tools own placement, branching, and cleanup. Running
`git worktree add` beside one creates state the harness cannot see or manage.
Then go to Step 2.

### 1b. Git fallback

Use this only when no native tool exists.

**Branch name.** Derive a kebab-case name from the task, or from the plan slug
when one exists. Confirm it with the user. When the branch already exists,
ask whether to reuse it or pick another name.

**Directory.** Take the first rung that matches:

1. A worktree directory declared in the user's instructions.
2. An existing `.worktrees/` at the project root.
3. An existing `worktrees/` at the project root.
4. Default: `.worktrees/` at the project root.

**Ignore check.** A project-local directory must be ignored before creation:

```bash
git check-ignore -q "$LOCATION"
```

When it is not ignored, append it to the exclude file named in Constraints.

**Create:**

```bash
git worktree add "$LOCATION/$BRANCH_NAME" -b "$BRANCH_NAME"
```

Outside wave mode, on a permission or sandbox error, tell the user the sandbox
blocked worktree creation, then run Steps 2 and 3 in the current directory.

## Step 2: Project Setup

Find the project's documented setup command in the README, a Makefile, or
package scripts. When none is documented, select by lockfile:

| File present | Command |
|---|---|
| `package-lock.json` | `npm ci` |
| `pnpm-lock.yaml` | `pnpm install --frozen-lockfile` |
| `yarn.lock` | `yarn install` |
| `uv.lock` | `uv sync` |
| `poetry.lock` | `poetry install` |
| `requirements.txt` only | `pip install -r requirements.txt` |
| `Cargo.toml` | `cargo build` |
| `go.mod` | `go mod download` |

Several package managers or no match: ask the user. No manifest at all: skip
setup.

## Step 3: Verify Clean Baseline

Run the project's documented test command: a `test` script, a `test` make
target, or the README instruction. When none is found, ask.

- **Tests fail:** report the failures and ask whether to proceed or
  investigate. Proceeding past a red baseline is the user's call.
- **Tests pass:** report ready.

## Step 4: Hand Off

When the work is coordinated, return to the Coordinator's setup. It passes this
worktree root to Refract as `path`, so the worktree gets its own project and
job queue. Plan anchors under `refs/plans/` live in the shared `.git` directory
and resolve from every worktree. In `untracked` plan mode, a new worktree starts
without `docs/plans/`; copy the plan directory in before resuming there.
`.git/info/exclude` is shared, so the copy stays excluded.

**Symlinked `docs`.** In worktree mode, check whether `docs` is a symlink to the
shared checkout's `docs`:

```bash
test -L <worktree path>/docs && readlink -f <worktree path>/docs
```

When it is, the Write and Edit tools refuse to create plan files under
`docs/plans/<slug>/`. Write `PLAN.md`, `.handover.md`, and the phase prompt
through the shell into `docs/plans/<slug>/` of the shared checkout, using the
resolved path above.

## Wave Mode

[waves.md](../coordinating-multi-model-work/references/waves.md) invokes this
mode for a multi-phase wave. The Coordinator already chose isolation, so skip
the Step 0 question and Step 1a: a native tool moves the session into one
worktree, while a wave needs several side by side. For each wave phase:

1. Select the directory and pass the ignore check from Step 1b.
2. Create the worktree from `wave_base`:

   ```bash
   git worktree add "$LOCATION/<slug>-phase-<NN>" -b "refract/<slug>/phase-<NN>" "$WAVE_BASE"
   ```

3. Run Step 2 in the new worktree. Skip Step 3; `wave_base` is the validated
   main checkpoint.

On any creation or setup failure, remove the worktrees and branches this wave
created, report the error once, and return failure so the Coordinator runs the
wave sequentially. Never fall back to the current directory in wave mode.
Emit one `# WORKSPACE` block per phase.

## Output Format

```text
# WORKSPACE
- Path: <absolute path>
- Branch: <name> | detached, branch pending
- Isolation: existing | native tool | git fallback | in place
- Setup: <command> -> <result> | skipped
- Baseline: <command> -> <N passed, M failed> | not run - <reason>
```

Versions

RepositoryScoreLicence
This page · sitien173/refract100MIT
jjuraszek/pi-gauntlet100MIT
event4u-app/agent-config100MIT
yusixian/anjian100MIT
GanyuanRan/Aegis100MIT
innei/ryugi100MIT
rootcastleco/rei-skills100MIT
davila7/claude-code-templates100MIT
Bbeierle12/Skill-MCP-Claude100MIT

Database snapshot: 13.11.2026 · package version 6481aaa79fa4 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 95dev_manage_git-worktrees
    Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification. Triggers: worktree, git worktree, isolated workspace, feature branch…
  • 100sr-using-git-worktrees
    Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback
  • 100git-worktree
    Use when work needs an isolated git worktree, such as parallel feature branches, reviewing a PR without disturbing the current checkout, or cleaning up old worktrees.
  • 100git-worktrees
    Isolated workspace creation for parallel development work. Use when starting feature work that needs isolation from the current workspace. Creates git worktrees with proper setup and safety verification.
  • 100worktree
    Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification
  • 100use-git-worktree
    This skill should be used when starting feature work that needs isolation from current workspace - creates isolated git worktrees with smart directory selection and safety verification

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.