|
|
@@ -1,21 +1,21 @@
|
|
|
---
|
|
|
name: using-git-worktrees
|
|
|
-description: 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
|
|
|
+description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - detects environment, offers worktree isolation when appropriate
|
|
|
---
|
|
|
|
|
|
# Using Git Worktrees
|
|
|
|
|
|
## Overview
|
|
|
|
|
|
-Ensure work happens in an isolated workspace. Prefer your platform's native worktree tools. Fall back to manual git worktrees only when no native tool is available.
|
|
|
+Detect the workspace environment. Work in place by default. Offer worktree isolation when the user would benefit, but only create one when they explicitly ask.
|
|
|
|
|
|
-**Core principle:** Detect existing isolation first. Then use native tools. Then fall back to git. Never fight the harness.
|
|
|
+**Core principle:** Detect first. Default to working in place. Create worktrees only on explicit user request. Never fight the harness.
|
|
|
|
|
|
-**Announce at start:** "I'm using the using-git-worktrees skill to set up an isolated workspace."
|
|
|
+**Announce at start:** "I'm using the using-git-worktrees skill to check the workspace."
|
|
|
|
|
|
-## Step 0: Detect Existing Isolation
|
|
|
+## Step 1: Detect Existing Isolation
|
|
|
|
|
|
-**Before creating anything, check if you are already in an isolated workspace.**
|
|
|
+**Before anything else, check if you are already in an isolated workspace.**
|
|
|
|
|
|
```bash
|
|
|
GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
|
|
|
@@ -30,35 +30,55 @@ BRANCH=$(git branch --show-current)
|
|
|
git rev-parse --show-superproject-working-tree 2>/dev/null
|
|
|
```
|
|
|
|
|
|
-**If `GIT_DIR != GIT_COMMON` (and not a submodule):** You are already in a linked worktree. Skip to Step 3 (Project Setup). Do NOT create another worktree.
|
|
|
+**If `GIT_DIR != GIT_COMMON` (and not a submodule):** You are already in a linked worktree. Skip to Step 4 (Project Setup). Do NOT create another worktree.
|
|
|
|
|
|
Report with branch state:
|
|
|
- On a branch: "Already in isolated workspace at `<path>` on branch `<name>`."
|
|
|
- Detached HEAD: "Already in isolated workspace at `<path>` (detached HEAD, externally managed). Branch creation needed at finish time."
|
|
|
|
|
|
-**If `GIT_DIR == GIT_COMMON` (or in a submodule):** You are in a normal repo checkout.
|
|
|
+**If `GIT_DIR == GIT_COMMON` (or in a submodule):** You are in a normal repo checkout. Proceed to Step 2.
|
|
|
|
|
|
-Has the user already indicated their worktree preference in your instructions? If not, ask for consent before creating a worktree:
|
|
|
+## Step 2: Offer Workspace Options
|
|
|
|
|
|
-> "Would you like me to set up an isolated worktree? It protects your current branch from changes."
|
|
|
+**The default path is to work in place on your current branch.** Do NOT create a worktree unless the user explicitly asks for one.
|
|
|
|
|
|
-Honor any existing declared preference without asking. If the user declines consent, work in place and skip to Step 3.
|
|
|
+```bash
|
|
|
+# Report current state to the user
|
|
|
+echo "Current branch: $BRANCH"
|
|
|
+echo "Repository: $(basename "$(git rev-parse --show-toplevel)")"
|
|
|
+```
|
|
|
+
|
|
|
+**Check the user's most recent message first.** If they already asked for a worktree, named the worktree skill, or asked for an isolated workspace in the message that invoked you, that IS the explicit ask — proceed directly to Step 3 without re-prompting.
|
|
|
+
|
|
|
+Otherwise, tell the user their options and **wait for a reply**:
|
|
|
+
|
|
|
+> "You're on `<branch>` in `<repo>`. I can set up an isolated worktree, or we can work directly here. What do you prefer?"
|
|
|
+
|
|
|
+**Routing:**
|
|
|
+- **User explicitly asks for a worktree** → proceed to Step 3
|
|
|
+- **User says work in place** → skip to Step 4
|
|
|
+- **User gives no clear worktree preference** → skip to Step 4 (default is in-place)
|
|
|
+- **Silence or unrelated reply** → ask once more, then skip to Step 4 if still unclear
|
|
|
+
|
|
|
+The default is always Step 4. Step 3 requires an explicit "yes, create a worktree" from the user.
|
|
|
+
|
|
|
+## Step 3: Create Worktree
|
|
|
|
|
|
-## Step 1: Create Isolated Workspace
|
|
|
+**You only reach this step because the user explicitly asked for a worktree in Step 2.**
|
|
|
|
|
|
-**You have two mechanisms. Try them in this order.**
|
|
|
+You have two mechanisms. Try them in this order.
|
|
|
|
|
|
-### 1a. Native Worktree Tools (preferred)
|
|
|
+### 3a. Native Worktree Tools (preferred)
|
|
|
|
|
|
-The user has asked for an isolated workspace (Step 0 consent). Do you already have a way to create a worktree? It might be a tool with a name like `EnterWorktree`, `WorktreeCreate`, a `/worktree` command, or a `--worktree` flag. If you do, use it and skip to Step 3.
|
|
|
+Do you already have a way to create a worktree? It might be a tool with a name like `EnterWorktree`, `WorktreeCreate`, a `/worktree` command, or a `--worktree` flag. If you do, use it and skip to Step 4.
|
|
|
|
|
|
Native tools handle directory placement, branch creation, and cleanup automatically. Using `git worktree add` when you have a native tool creates phantom state your harness can't see or manage.
|
|
|
|
|
|
-Only proceed to Step 1b if you have no native worktree tool available.
|
|
|
+Only proceed to Step 3b if you have no native worktree tool available.
|
|
|
|
|
|
-### 1b. Git Worktree Fallback
|
|
|
+### 3b. Git Worktree Fallback
|
|
|
|
|
|
-**Only use this if Step 1a does not apply** — you have no native worktree tool available. Create a worktree manually using git.
|
|
|
+**Only use this if Step 3a does not apply** — you have no native worktree tool available. Create a worktree manually using git.
|
|
|
|
|
|
#### Directory Selection
|
|
|
|
|
|
@@ -111,7 +131,7 @@ cd "$path"
|
|
|
|
|
|
**Sandbox fallback:** If `git worktree add` fails with a permission error (sandbox denial), tell the user the sandbox blocked worktree creation and you're working in the current directory instead. Then run setup and baseline tests in place.
|
|
|
|
|
|
-## Step 3: Project Setup
|
|
|
+## Step 4: Project Setup
|
|
|
|
|
|
Auto-detect and run appropriate setup:
|
|
|
|
|
|
@@ -130,7 +150,7 @@ if [ -f pyproject.toml ]; then poetry install; fi
|
|
|
if [ -f go.mod ]; then go mod download; fi
|
|
|
```
|
|
|
|
|
|
-## Step 4: Verify Clean Baseline
|
|
|
+## Step 5: Verify Clean Baseline
|
|
|
|
|
|
Run tests to ensure workspace starts clean:
|
|
|
|
|
|
@@ -145,20 +165,30 @@ npm test / cargo test / pytest / go test ./...
|
|
|
|
|
|
### Report
|
|
|
|
|
|
+If working in a worktree:
|
|
|
```
|
|
|
Worktree ready at <full-path>
|
|
|
Tests passing (<N> tests, 0 failures)
|
|
|
Ready to implement <feature-name>
|
|
|
```
|
|
|
|
|
|
+If working in place:
|
|
|
+```
|
|
|
+Working in place on <branch> at <path>
|
|
|
+Tests passing (<N> tests, 0 failures)
|
|
|
+Ready to implement <feature-name>
|
|
|
+```
|
|
|
+
|
|
|
## Quick Reference
|
|
|
|
|
|
| Situation | Action |
|
|
|
|-----------|--------|
|
|
|
-| Already in linked worktree | Skip creation (Step 0) |
|
|
|
-| In a submodule | Treat as normal repo (Step 0 guard) |
|
|
|
-| Native worktree tool available | Use it (Step 1a) |
|
|
|
-| No native tool | Git worktree fallback (Step 1b) |
|
|
|
+| Already in linked worktree | Skip creation, go to Step 4 (Step 1) |
|
|
|
+| In a submodule | Treat as normal repo (Step 1 guard) |
|
|
|
+| Normal repo, user wants in-place | Work in place, go to Step 4 (Step 2 default) |
|
|
|
+| Normal repo, user asks for worktree | Create worktree (Step 3) |
|
|
|
+| Native worktree tool available | Use it (Step 3a) |
|
|
|
+| No native tool | Git worktree fallback (Step 3b) |
|
|
|
| `.worktrees/` exists | Use it (verify ignored) |
|
|
|
| `worktrees/` exists | Use it (verify ignored) |
|
|
|
| Both exist | Use `.worktrees/` |
|
|
|
@@ -168,19 +198,25 @@ Ready to implement <feature-name>
|
|
|
| Permission error on create | Sandbox fallback, work in place |
|
|
|
| Tests fail during baseline | Report failures + ask |
|
|
|
| No package.json/Cargo.toml | Skip dependency install |
|
|
|
-| Plan touches multiple repos | Create a matching worktree in each repo, same branch name |
|
|
|
+| User gives no worktree preference | Work in place (Step 2 default) |
|
|
|
+| Plan touches multiple repos | Offer a matching worktree per repo, same branch name |
|
|
|
|
|
|
## Common Mistakes
|
|
|
|
|
|
+### Creating a worktree without being asked
|
|
|
+
|
|
|
+- **Problem:** Agent creates a worktree because the skill was invoked, without the user requesting one
|
|
|
+- **Fix:** Step 2 defaults to working in place. Only Step 3 creates, and only after explicit user request.
|
|
|
+
|
|
|
### Fighting the harness
|
|
|
|
|
|
- **Problem:** Using `git worktree add` when the platform already provides isolation
|
|
|
-- **Fix:** Step 0 detects existing isolation. Step 1a defers to native tools.
|
|
|
+- **Fix:** Step 1 detects existing isolation. Step 3a defers to native tools.
|
|
|
|
|
|
### Skipping detection
|
|
|
|
|
|
- **Problem:** Creating a nested worktree inside an existing one
|
|
|
-- **Fix:** Always run Step 0 before creating anything
|
|
|
+- **Fix:** Always run Step 1 before creating anything
|
|
|
|
|
|
### Skipping ignore verification
|
|
|
|
|
|
@@ -200,15 +236,19 @@ Ready to implement <feature-name>
|
|
|
## Red Flags
|
|
|
|
|
|
**Never:**
|
|
|
-- Create a worktree when Step 0 detects existing isolation
|
|
|
+- Create a worktree without the user explicitly asking for one
|
|
|
+- Create a worktree when Step 1 detects existing isolation
|
|
|
- Use `git worktree add` when you have a native worktree tool (e.g., `EnterWorktree`). This is the #1 mistake — if you have it, use it.
|
|
|
-- Skip Step 1a by jumping straight to Step 1b's git commands
|
|
|
+- Skip Step 3a by jumping straight to Step 3b's git commands
|
|
|
- Create worktree without verifying it's ignored (project-local)
|
|
|
- Skip baseline test verification
|
|
|
- Proceed with failing tests without asking
|
|
|
+- Infer worktree consent from the task description or plan — only an explicit user request counts
|
|
|
|
|
|
**Always:**
|
|
|
-- Run Step 0 detection first
|
|
|
+- Run Step 1 detection first
|
|
|
+- Default to working in place (Step 2 → Step 4)
|
|
|
+- Only create a worktree after explicit user request
|
|
|
- Prefer native tools over git fallback
|
|
|
- Follow directory priority: existing > global legacy > instruction file > default
|
|
|
- Verify directory is ignored for project-local
|
|
|
@@ -218,9 +258,9 @@ Ready to implement <feature-name>
|
|
|
## Integration
|
|
|
|
|
|
**Called by:**
|
|
|
-- **subagent-driven-development** - Ensures isolated workspace (creates one or verifies existing)
|
|
|
-- **executing-plans** - Ensures isolated workspace (creates one or verifies existing)
|
|
|
-- Any skill needing isolated workspace
|
|
|
+- **subagent-driven-development** - Calls this to detect the workspace and optionally set up worktree isolation on request
|
|
|
+- **executing-plans** - Calls this to detect the workspace and optionally set up worktree isolation on request
|
|
|
+- Any skill that may use worktree isolation
|
|
|
|
|
|
**Pairs with:**
|
|
|
- **finishing-a-development-branch** - REQUIRED for cleanup after work complete
|
Jesse Vincent