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

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/executing-plans/SKILL.md

@@ -65,6 +65,6 @@ After all tasks complete and verified:
 ## Integration
 
 **Required workflow skills:**
-- **superpowers:using-git-worktrees** - Detects workspace environment and offers worktree isolation on request
+- **superpowers:using-git-worktrees** - Ensures isolated workspace (creates one or verifies existing)
 - **superpowers:writing-plans** - Creates the plan this skill executes
 - **superpowers:finishing-a-development-branch** - Complete development after all tasks

skills/subagent-driven-development/SKILL.md

@@ -265,7 +265,7 @@ Done!
 ## Integration
 
 **Required workflow skills:**
-- **superpowers:using-git-worktrees** - Detects workspace environment and offers worktree isolation on request
+- **superpowers:using-git-worktrees** - Ensures isolated workspace (creates one or verifies existing)
 - **superpowers:writing-plans** - Creates the plan this skill executes
 - **superpowers:requesting-code-review** - Code review template for reviewer subagents
 - **superpowers:finishing-a-development-branch** - Complete development after all tasks

skills/using-git-worktrees/SKILL.md

@@ -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 - detects environment, offers worktree isolation when appropriate
+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
 ---
 
 # Using Git Worktrees
 
 ## Overview
 
-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.
+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.
 
-**Core principle:** Detect first. Default to working in place. Create worktrees only on explicit user request. Never fight the harness.
+**Core principle:** Detect existing isolation first. Then use native tools. Then fall back to git. Never fight the harness.
 
-**Announce at start:** "I'm using the using-git-worktrees skill to check the workspace."
+**Announce at start:** "I'm using the using-git-worktrees skill to set up an isolated workspace."
 
-## Step 1: Detect Existing Isolation
+## Step 0: Detect Existing Isolation
 
-**Before anything else, check if you are already in an isolated workspace.**
+**Before creating anything, check if you are already in an isolated workspace.**
 
 ```bash
 GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
@@ -30,77 +30,57 @@ 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 4 (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 3 (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. Proceed to Step 2.
+**If `GIT_DIR == GIT_COMMON` (or in a submodule):** You are in a normal repo checkout. Ask for consent before creating a workspace:
 
-## Step 2: Offer Workspace Options
+> "Would you like me to set up an isolated worktree? This protects your current branch from changes. (y/n)"
 
-**The default path is to work in place on your current branch.** Do NOT create a worktree unless the user explicitly asks for one.
+If yes, proceed to Step 1. If no, work in place — skip to Step 3 with no worktree.
 
-```bash
-# Report current state to the user
-echo "Current branch: $BRANCH"
-echo "Repository: $(basename "$(git rev-parse --show-toplevel)")"
-```
+## Step 1: Create Isolated Workspace
 
-**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.
+**You have two mechanisms. Try them in this order.**
 
-Otherwise, tell the user their options and **wait for a reply**:
+### 1a. Native Worktree Tools (preferred — STOP HERE if available)
 
-> "You're on `<branch>` in `<repo>`. I can set up an isolated worktree, or we can work directly here. What do you prefer?"
+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.**
 
-**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
+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.
 
-The default is always Step 4. Step 3 requires an explicit "yes, create a worktree" from the user.
+**Even if `.worktrees/` already exists, even under time pressure, even if `git worktree add` feels faster — use your native tool.** There are no exceptions.
 
-## Step 3: Create Worktree
+**Only proceed to Step 1b if you have confirmed you have NO native worktree/isolation tool.**
 
-**You only reach this step because the user explicitly asked for a worktree in Step 2.**
+### 1b. Git Worktree Fallback
 
-You have two mechanisms. Try them in this order.
-
-### 3a. Native Worktree Tools (preferred)
-
-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 3b if you have no native worktree tool available.
-
-### 3b. Git Worktree Fallback
-
-**Only use this if Step 3a does not apply** — you have no native worktree tool available. Create a worktree manually using git.
+**Only use this if Step 1a does not apply** — you have no native worktree tool available. Create a worktree manually using git.
 
 #### 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)
 
@@ -129,9 +109,9 @@ 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 4: Project Setup
+## Step 3: Project Setup
 
 Auto-detect and run appropriate setup:
 
@@ -150,7 +130,7 @@ if [ -f pyproject.toml ]; then poetry install; fi
 if [ -f go.mod ]; then go mod download; fi
 ```
 
-## Step 5: Verify Clean Baseline
+## Step 4: Verify Clean Baseline
 
 Run tests to ensure workspace starts clean:
 
@@ -165,30 +145,20 @@ 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, 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) |
+| 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) |
 | `.worktrees/` exists | Use it (verify ignored) |
 | `worktrees/` exists | Use it (verify ignored) |
 | Both exist | Use `.worktrees/` |
@@ -198,25 +168,19 @@ 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 |
-| User gives no worktree preference | Work in place (Step 2 default) |
-| Plan touches multiple repos | Offer a matching worktree per repo, same branch name |
+| Plan touches multiple repos | Create a worktree in each repo (same Step 0→1a→1b flow, matching branch names) |
 
 ## 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 1 detects existing isolation. Step 3a defers to native tools.
+- **Fix:** Step 0 detects existing isolation. Step 1a defers to native tools.
 
 ### Skipping detection
 
 - **Problem:** Creating a nested worktree inside an existing one
-- **Fix:** Always run Step 1 before creating anything
+- **Fix:** Always run Step 0 before creating anything
 
 ### Skipping ignore verification
 
@@ -236,19 +200,15 @@ Ready to implement <feature-name>
 ## Red Flags
 
 **Never:**
-- Create a worktree without the user explicitly asking for one
-- Create a worktree when Step 1 detects existing isolation
+- 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 3a by jumping straight to Step 3b's git commands
+- Skip Step 1a by jumping straight to Step 1b'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 1 detection first
-- Default to working in place (Step 2 → Step 4)
-- Only create a worktree after explicit user request
+- Run Step 0 detection first
 - Prefer native tools over git fallback
 - Follow directory priority: existing > global legacy > instruction file > default
 - Verify directory is ignored for project-local
@@ -258,9 +218,9 @@ Ready to implement <feature-name>
 ## Integration
 
 **Called by:**
-- **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
+- **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
 
 **Pairs with:**
 - **finishing-a-development-branch** - REQUIRED for cleanup after work complete

skills/using-superpowers/references/codex-tools.md

@@ -84,8 +84,8 @@ BRANCH=$(git branch --show-current)
 - `GIT_DIR != GIT_COMMON` → already in a linked worktree (skip creation)
 - `BRANCH` empty → detached HEAD (cannot branch/push/PR from sandbox)
 
-See `using-git-worktrees` Step 1 and `finishing-a-development-branch`
-Step 2 for how each skill uses these signals.
+See `using-git-worktrees` Step 0 and `finishing-a-development-branch`
+Step 1 for how each skill uses these signals.
 
 ## Codex App Finishing
 

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)