mirror of
https://github.com/obra/superpowers.git
synced 2026-04-21 00:49:06 +08:00
fix: invert worktree skill default to work-in-place, eliminating Step 0.5 (PRI-974)
Agents consistently skipped Step 0.5 (consent gate) because fractional numbering signals "optional afterthought" and the prose-only step was invisible to code-block anchoring. The fix inverts the structural gravity: the default path now works in place, and worktree creation is an off-ramp requiring explicit user request. - Renumber to clean integers: Step 1 (detect) → 2 (offer) → 3 (create) → 4 (setup) → 5 (verify) - Step 2 defaults to Step 4 (in-place); Step 3 only on explicit user ask - Step 2 includes a code block so agents register it during execution - Add "creating without being asked" to Common Mistakes - Add anti-inference red flag: consent from task/plan/skill invocation doesn't count Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -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,42 +30,53 @@ 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. Proceed to Step 0.5.
|
||||
**If `GIT_DIR == GIT_COMMON` (or in a submodule):** You are in a normal repo checkout. Proceed to Step 2.
|
||||
|
||||
## Step 0.5: Consent — REQUIRED STOP
|
||||
## Step 2: Offer Workspace Options
|
||||
|
||||
**You MUST ask the user before creating any workspace. Do NOT proceed to Step 1 without an answer.**
|
||||
**The default path is to work in place on your current branch.** Do NOT create a worktree unless the user explicitly asks for one.
|
||||
|
||||
Output exactly this, then STOP and wait for a response:
|
||||
```bash
|
||||
# Report current state to the user
|
||||
echo "Current branch: $BRANCH"
|
||||
echo "Repository: $(basename "$(git rev-parse --show-toplevel)")"
|
||||
```
|
||||
|
||||
> "I can set up an isolated worktree for this work, or work directly on your current branch. Which do you prefer?"
|
||||
Tell the user their options, then **wait for a reply**:
|
||||
|
||||
- **User wants a worktree** → proceed to Step 1
|
||||
- **User wants to work in place** → skip to Step 3 (no worktree, no directory change)
|
||||
> "You're on `<branch>` in `<repo>`. I can set up an isolated worktree, or we can work directly here. What do you prefer?"
|
||||
|
||||
Do NOT interpret silence or an unrelated reply as consent. If unclear, ask once more.
|
||||
**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** → skip to Step 4 (default is in-place)
|
||||
|
||||
## Step 1: Create Isolated Workspace
|
||||
The default is always Step 4. Step 3 requires an explicit "yes, create a worktree" from the user.
|
||||
|
||||
**You have two mechanisms. Try them in this order.**
|
||||
## Step 3: Create Worktree
|
||||
|
||||
### 1a. Native Worktree Tools (preferred)
|
||||
**You only reach this step because the user explicitly asked for a worktree in Step 2.**
|
||||
|
||||
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.
|
||||
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
|
||||
|
||||
@@ -118,7 +129,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:
|
||||
|
||||
@@ -137,7 +148,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:
|
||||
|
||||
@@ -152,20 +163,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) |
|
||||
| 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) |
|
||||
| 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) |
|
||||
| `.worktrees/` exists | Use it (verify ignored) |
|
||||
| `worktrees/` exists | Use it (verify ignored) |
|
||||
| Both exist | Use `.worktrees/` |
|
||||
@@ -175,19 +196,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
|
||||
|
||||
@@ -207,15 +234,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, plan, or skill invocation — only an explicit user reply 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
|
||||
|
||||
Reference in New Issue
Block a user