Merge pull request #1123 from obra/feat-add-multi-repo-worktree

feat: add multi-repo worktree guidance (#710)
docs: drop brittle step-number chain from multi-repo row
2026-04-21 00:49:06 +08:00 · 2026-04-13 16:48:44 -07:00 · 2026-04-13 16:30:00 -07:00 · 2026-04-13 16:29:59 -07:00 · 2026-04-13 16:29:59 -07:00 · 2026-04-13 16:29:44 -07:00
2 changed files with 5 additions and 4 deletions
--- a/docs/superpowers/plans/2026-04-06-worktree-rototill.md
+++ b/docs/superpowers/plans/2026-04-06-worktree-rototill.md
@@ -251,7 +251,7 @@ Report with branch state:

 **If `GIT_DIR == GIT_COMMON` (or in a submodule):** You are in a normal repo checkout.

-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:
+Has the user already indicated their worktree preference in your instructions? If not, 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 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.
+3. **Check your instructions for a worktree directory preference.** If specified, use it without asking.

 4. **Default to `.worktrees/`.**

--- a/skills/using-git-worktrees/SKILL.md
+++ b/skills/using-git-worktrees/SKILL.md
@@ -38,7 +38,7 @@ Report with branch state:

 **If `GIT_DIR == GIT_COMMON` (or in a submodule):** You are in a normal repo checkout.

-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:
+Has the user already indicated their worktree preference in your instructions? If not, ask for consent before creating a worktree:

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

@@ -64,7 +64,7 @@ Only proceed to Step 1b if you have no native worktree tool available.

 Follow this priority order. Explicit user preference always beats observed filesystem state.

-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.
+1. **Check your instructions for a declared worktree directory preference.** If the user has already specified one, use it without asking.

 2. **Check for an existing project-local worktree directory:**
   ```bash
@@ -168,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
Author	SHA1	Message	Date
Jesse Vincent	1879a94ac7	Merge pull request #1123 from obra/feat-add-multi-repo-worktree feat: add multi-repo worktree guidance (#710)	2026-04-13 16:48:44 -07:00
Drew Ritter	ddbba8e469	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 16:30:00 -07:00
Drew Ritter	e3dd3b4c5a	fix: replace hardcoded /Users/jesse with generic placeholders (#858 )	2026-04-13 16:29:59 -07:00
Drew Ritter	f0728841d8	feat: add multi-repo worktree guidance (#710 )	2026-04-13 16:29:59 -07:00
Drew Ritter	e4a15b6d52	docs: drop instruction file enumeration per PR #1121 review Jesse flagged that the verbose CLAUDE.md/AGENTS.md/GEMINI.md/.cursorrules enumeration (a) chews tokens, (b) confuses models that anchor on exact strings, and (c) is repeated DRY-violatingly across 3+ locations. Replace with abstract "your instructions" framing in four spots: - skills/using-git-worktrees/SKILL.md Step 0 → Step 1 transition - skills/using-git-worktrees/SKILL.md Step 1b Directory Selection - docs/superpowers/plans/2026-04-06-worktree-rototill.md (both mirror locations) Same intent, harness-agnostic phrasing, ~half the tokens. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-04-13 16:29:44 -07:00