diff --git a/skills/executing-plans/SKILL.md b/skills/executing-plans/SKILL.md index a5918627..ea286496 100644 --- a/skills/executing-plans/SKILL.md +++ b/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 diff --git a/skills/subagent-driven-development/SKILL.md b/skills/subagent-driven-development/SKILL.md index 7eff5bdd..f1c230ac 100644 --- a/skills/subagent-driven-development/SKILL.md +++ b/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 diff --git a/skills/using-git-worktrees/SKILL.md b/skills/using-git-worktrees/SKILL.md index eb27d447..6d450c4f 100644 --- a/skills/using-git-worktrees/SKILL.md +++ b/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 `` on branch ``." - Detached HEAD: "Already in isolated workspace at `` (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 `` in ``. 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 Tests passing ( tests, 0 failures) Ready to implement ``` +If working in place: +``` +Working in place on at +Tests passing ( tests, 0 failures) +Ready to implement +``` + ## 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/` | @@ -168,19 +198,25 @@ Ready to implement | 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 ## 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 ## Integration **Called by:** -- **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 +- **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 **Pairs with:** - **finishing-a-development-branch** - REQUIRED for cleanup after work complete diff --git a/skills/using-superpowers/references/codex-tools.md b/skills/using-superpowers/references/codex-tools.md index 539b2b1c..6828f64a 100644 --- a/skills/using-superpowers/references/codex-tools.md +++ b/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` -Step 1 for how each skill uses these signals. +See `using-git-worktrees` Step 1 and `finishing-a-development-branch` +Step 2 for how each skill uses these signals. ## Codex App Finishing