Compare commits

..

3 Commits

Author SHA1 Message Date
Drew Ritter
b1e9711034 docs: drop brittle step-number chain from multi-repo row
Addresses review feedback on #1123. Replaces "(same Step 0→1a→1b flow,
matching branch names)" with plain-language instruction that doesn't
forward-reference section numbers that could rot under future edits.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-13 11:44:02 -07:00
Drew Ritter
d4464920ff feat: add multi-repo worktree guidance (#710) 2026-04-13 11:44:02 -07:00
Drew Ritter
a490478f8a fix: replace hardcoded /Users/jesse with generic placeholders (#858) 2026-04-13 11:43:54 -07:00
2 changed files with 14 additions and 14 deletions

View File

@@ -251,7 +251,7 @@ Report with branch state:
**If `GIT_DIR == GIT_COMMON` (or in a submodule):** You are in a normal repo checkout.
Has the user already indicated their worktree preference in your instructions? If not, ask for consent before creating a worktree:
If the user has not already made their preferences about worktree isolation clear — check global and project agent instruction files (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.cursorrules`, or equivalent) — ask for consent before creating a worktree:
> "Would you like me to set up an isolated worktree? It protects your current branch from changes."
@@ -289,7 +289,7 @@ Follow this priority order:
```
If found, use it (backward compatibility with legacy global path).
3. **Check your instructions for a worktree directory preference.** If specified, use it without asking.
3. **Check your project's agent instruction file** (CLAUDE.md, GEMINI.md, AGENTS.md, .cursorrules, or equivalent) for a worktree directory preference. If specified, use it without asking.
4. **Default to `.worktrees/`.**

View File

@@ -36,23 +36,25 @@ 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. Proceed to Step 1 to create an isolated workspace.
**If `GIT_DIR == GIT_COMMON` (or in a submodule):** You are in a normal repo checkout.
**Do not stop to ask the user whether they want a worktree.** Invoking this skill IS the request for isolation — your authorization to create one comes from that invocation, not from a separate "yes" reply. If the user has already declared in their instructions that they prefer to work in place, honor that and skip to Step 3. Otherwise, create the worktree.
If the user has not already made their preferences about worktree isolation clear — check global and project agent instruction files (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.cursorrules`, or equivalent) — ask for consent before creating a worktree:
> "Would you like me to set up an isolated worktree? It protects your current branch from changes."
Honor any existing declared preference without asking. If the user declines consent, work in place and skip to Step 3.
## Step 1: Create Isolated Workspace
**You have two mechanisms. Try them in this order.**
### 1a. Native Worktree Tools (preferred — STOP HERE if available)
### 1a. Native Worktree Tools (preferred)
Do you have a tool with a name like `EnterWorktree`, `WorktreeCreate`, a `/worktree` command, or a `--worktree` flag? **If YES: use it now and skip to Step 3.** Skill invocation is your authorization — you do not need a separate user reply.
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.
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 — cleanup becomes impossible.
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.
**Even if `.worktrees/` already exists, even under time pressure, even if `git worktree add` feels faster — use your native tool.** No exceptions.
Only proceed to Step 1b if you have confirmed you have NO native worktree tool available.
Only proceed to Step 1b if you have no native worktree tool available.
### 1b. Git Worktree Fallback
@@ -62,7 +64,7 @@ Only proceed to Step 1b if you have confirmed you have NO native worktree tool a
Follow this priority order. Explicit user preference always beats observed filesystem state.
1. **Check your instructions for a declared worktree directory preference.** If the user has already specified one, use it without asking.
1. **Check global and project agent instruction files** (`~/.claude/CLAUDE.md`, `~/.config/gemini/AGENTS.md`, project-level `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.cursorrules`, or equivalent) for a declared worktree directory preference. If specified, use it without asking.
2. **Check for an existing project-local worktree directory:**
```bash
@@ -166,6 +168,7 @@ 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 |
## Common Mistakes
@@ -197,8 +200,6 @@ Ready to implement <feature-name>
## Red Flags
**Never:**
- Stop to ask the user for consent when the skill has already been invoked. Invoking the skill IS the request — treat it as your authorization to proceed.
- Fall back to a plain feature branch because a native worktree tool feels "restricted to explicit user requests." Skill invocation is the explicit request the tool requires.
- Create a worktree when Step 0 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
@@ -207,7 +208,6 @@ Ready to implement <feature-name>
- Proceed with failing tests without asking
**Always:**
- Treat skill invocation as implicit authorization to create a worktree
- Run Step 0 detection first
- Prefer native tools over git fallback
- Follow directory priority: existing > global legacy > instruction file > default