feat: add multi-repo worktree guidance (#710)

commands/brainstorm.md

@@ -0,0 +1,5 @@
+---
+description: "Deprecated - use the superpowers:brainstorming skill instead"
+---
+
+Tell your human partner that this command is deprecated and will be removed in the next major release. They should ask you to use the "superpowers brainstorming" skill instead.

commands/execute-plan.md

@@ -0,0 +1,5 @@
+---
+description: "Deprecated - use the superpowers:executing-plans skill instead"
+---
+
+Tell your human partner that this command is deprecated and will be removed in the next major release. They should ask you to use the "superpowers executing-plans" skill instead.

commands/write-plan.md

@@ -0,0 +1,5 @@
+---
+description: "Deprecated - use the superpowers:writing-plans skill instead"
+---
+
+Tell your human partner that this command is deprecated and will be removed in the next major release. They should ask you to use the "superpowers writing-plans" skill instead.

docs/superpowers/plans/2026-04-06-worktree-rototill.md

@@ -249,13 +249,11 @@ 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. Ask for consent before creating a workspace:
 
-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? This protects your current branch from changes. (y/n)"
 
-> "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.
+If yes, proceed to Step 1. If no, work in place — skip to Step 3 with no worktree.
 
 ## Step 1: Create Isolated Workspace
 
@@ -289,7 +287,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/`.**
 

skills/using-git-worktrees/SKILL.md

@@ -36,25 +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.
+**If `GIT_DIR == GIT_COMMON` (or in a submodule):** You are in a normal repo checkout. Ask for consent before creating a workspace:
 
-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? This protects your current branch from changes. (y/n)"
 
-> "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.
+If yes, proceed to Step 1. If no, work in place — skip to Step 3 with no worktree.
 
 ## Step 1: Create Isolated Workspace
 
 **You have two mechanisms. Try them in this order.**
 
-### 1a. Native Worktree Tools (preferred)
+### 1a. Native Worktree Tools (preferred — STOP HERE if available)
 
-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.
+The user has asked for an isolated workspace (Step 0 consent). Check your available tools — do you have `EnterWorktree`, `WorktreeCreate`, a `/worktree` command, or a `--worktree` flag? **If YES: the user's consent to create a worktree is your authorization to use it. Use it now 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.
+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 worktrees it didn't create, and cleanup becomes impossible.
 
-Only proceed to Step 1b if you have no native worktree tool available.
+**Even if `.worktrees/` already exists, even under time pressure, even if `git worktree add` feels faster — use your native tool.** There are no exceptions.
+
+**Only proceed to Step 1b if you have confirmed you have NO native worktree/isolation tool.**
 
 ### 1b. Git Worktree Fallback
 
@@ -62,25 +62,25 @@ Only proceed to Step 1b if you have no native worktree tool available.
 
 #### Directory Selection
 
-Follow this priority order. Explicit user preference always beats observed filesystem state.
+Follow this priority order:
 
-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:**
+1. **Check existing directories:**
    ```bash
    ls -d .worktrees 2>/dev/null     # Preferred (hidden)
    ls -d worktrees 2>/dev/null      # Alternative
    ```
-   If found, use it. If both exist, `.worktrees` wins.
+   If found, use that directory. If both exist, `.worktrees` wins.
 
-3. **Check for an existing global directory:**
+2. **Check for existing global directory:**
    ```bash
    project=$(basename "$(git rev-parse --show-toplevel)")
    ls -d ~/.config/superpowers/worktrees/$project 2>/dev/null
    ```
    If found, use it (backward compatibility with legacy global path).
 
-4. **If there is no other guidance available**, default to `.worktrees/` at the project root.
+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/`.**
 
 #### Safety Verification (project-local directories only)
 
@@ -109,7 +109,7 @@ git worktree add "$path" -b "$BRANCH_NAME"
 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.
+**Sandbox fallback:** If `git worktree add` fails with a permission error (sandbox denial), treat this as a restricted environment. Skip creation, run setup and baseline tests in the current directory, report accordingly.
 
 ## Step 3: Project Setup
 
@@ -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 worktree in each repo (same Step 0→1a→1b flow, matching branch names) |
 
 ## Common Mistakes
 

skills/writing-plans/SKILL.md

@@ -13,7 +13,7 @@ Assume they are a skilled developer, but know almost nothing about our toolset o
 
 **Announce at start:** "I'm using the writing-plans skill to create the implementation plan."
 
-**Context:** If working in an isolated worktree, it should have been created via the `superpowers:using-git-worktrees` skill at execution time.
+**Context:** If working in an isolated worktree, it should have been created via the using-git-worktrees skill at execution time.
 
 **Save plans to:** `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md`
 - (User preferences for plan location override this default)