Merge pull request #1124 from obra/add-worktree-consent-step

enhance worktree consent during implementation (PRI-974)

skills/executing-plans/SKILL.md

@@ -65,6 +65,6 @@ After all tasks complete and verified:
 ## Integration
 
 **Required workflow skills:**
-- **superpowers:using-git-worktrees** - Ensures isolated workspace (creates one or verifies existing)
+- **superpowers:using-git-worktrees** - Detects workspace environment and offers worktree isolation on request
 - **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** - Ensures isolated workspace (creates one or verifies existing)
+- **superpowers:using-git-worktrees** - Detects workspace environment and offers worktree isolation on request
 - **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 - 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)")"
+```
 
-## 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)
+> "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). 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.
+**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
+
+**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.
+
+### 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 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) |
+| Already in linked worktree | Skip creation, go to Step 4 (Step 1) |
-| In a submodule | Treat as normal repo (Step 0 guard) |
+| In a submodule | Treat as normal repo (Step 1 guard) |
-| Native worktree tool available | Use it (Step 1a) |
+| Normal repo, user wants in-place | Work in place, go to Step 4 (Step 2 default) |
-| No native tool | Git worktree fallback (Step 1b) |
+| 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)
+- **subagent-driven-development** - Calls this to detect the workspace and optionally set up worktree isolation on request
-- **executing-plans** - Ensures isolated workspace (creates one or verifies existing)
+- **executing-plans** - Calls this to detect the workspace and optionally set up worktree isolation on request
-- Any skill needing isolated workspace
+- Any skill that may use worktree isolation
 
 **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 0 and `finishing-a-development-branch`
+See `using-git-worktrees` Step 1 and `finishing-a-development-branch`
-Step 1 for how each skill uses these signals.
+Step 2 for how each skill uses these signals.
 
 ## Codex App Finishing