Compare commits

..

8 Commits

Author SHA1 Message Date
Drew Ritter
72dd30d653 fix: update stale references and restore silence safety net (PRI-974)
Post-inversion cleanup:

- executing-plans, subagent-driven-development: update Integration
  description from "Ensures isolated workspace" to "Detects workspace
  environment and offers worktree isolation on request"
- codex-tools.md: update step references (Step 0→1, Step 1→2)
- using-git-worktrees Step 2: restore "silence → ask once more" instead
  of "silence → work in place" to preserve safety net for confused users

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-13 11:46:03 -07:00
Drew Ritter
856959aaeb 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>
2026-04-13 11:46:03 -07:00
Drew Ritter
100a56871c fix: promote consent to own Step 0.5 with structural enforcement (PRI-974)
Drill benchmark showed 0/4 consent compliance across both Claude Code
and Codex. Root cause: consent was buried inline in Step 0's conditional
branch. Agents anchor on the next bash command and skip prose.

Fix: promote consent to its own numbered section with imperative framing
("REQUIRED STOP", "Do NOT proceed without an answer") and exact output
template. Also adds explicit "no" path — users who want to work directly
on their current branch skip to Step 3 with no worktree creation.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-13 11:44:12 -07:00
Drew Ritter
b1e9711034 docs: drop brittle step-number chain from multi-repo row
Addresses review feedback on #1123. Replaces "(same Step 0→1a→1b flow,
matching branch names)" with plain-language instruction that doesn't
forward-reference section numbers that could rot under future edits.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-13 11:44:02 -07:00
Drew Ritter
d4464920ff feat: add multi-repo worktree guidance (#710) 2026-04-13 11:44:02 -07:00
Drew Ritter
a490478f8a fix: replace hardcoded /Users/jesse with generic placeholders (#858) 2026-04-13 11:43:54 -07:00
Drew Ritter
998c40be29 docs: soften Step 1a native-tool framing per PR #1121 review
Address obra's comment on explicit step numbers / prescriptive tone.
Drops "STOP HERE if available", the "If YES:" gate, and the "even if /
even if / NO EXCEPTIONS" reinforcement paragraph. Keeps the specific
tool-name anchors (EnterWorktree, WorktreeCreate, /worktree, --worktree),
which the original TDD data showed are load-bearing.

A/B verified against drill harness on the 3 creation/consent scenarios
(consent-flow, creation-from-main, creation-from-main-spec-aware):
baseline explicit wording scored 12/12 criteria, softened wording also
scored 12/12. The "agent used the most appropriate tool" criterion
passed in all 3 softened runs — agents still picked EnterWorktree via
ToolSearch without the imperative framing.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-13 11:43:45 -07:00
Drew Ritter
98263ce179 docs: address PR #1121 review — respect user preference, drop y/n
- Consent prompt: drop "(y/n)" and add escape valve for users who
  have already declared their worktree preference in global or
  project agent instruction files.
- Directory selection: reorder to put declared user preference
  ahead of observed filesystem state, and reframe the default as
  "if no other guidance available".
- Sandbox fallback: require explicitly informing the user that
  the sandbox blocked creation, not just "report accordingly".
- writing-plans: fully qualify the superpowers:using-git-worktrees
  reference.
- Plan doc: mirror the consent-prompt change.

Step 1a native-tool framing and the helper-scripts suggestion are
still outstanding — the first needs a benchmark re-run before softer
phrasing can be adopted without regressing compliance; the second is
exploratory and will get a thread reply.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-13 09:53:08 -07:00
3 changed files with 19 additions and 19 deletions

View File

@@ -249,11 +249,13 @@ 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. Ask for consent before creating a workspace:
**If `GIT_DIR == GIT_COMMON` (or in a submodule):** You are in a normal repo checkout.
> "Would you like me to set up an isolated worktree? This protects your current branch from changes. (y/n)"
If the user has not already made their preferences about worktree isolation clear — check global and project agent instruction files (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.cursorrules`, or equivalent) — ask for consent before creating a worktree:
If yes, proceed to Step 1. If no, work in place — skip to Step 3 with no worktree.
> "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.
## Step 1: Create Isolated Workspace

View File

@@ -66,15 +66,13 @@ The default is always Step 4. Step 3 requires an explicit "yes, create a worktre
You have two mechanisms. Try them in this order.
### 3a. Native Worktree Tools (preferred — STOP HERE if available)
### 3a. Native Worktree Tools (preferred)
Check your available tools — do you have `EnterWorktree`, `WorktreeCreate`, a `/worktree` command, or a `--worktree` flag? **If YES: use it now and skip to Step 4.**
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 worktrees it didn't create, and cleanup becomes impossible.
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.
**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 3b if you have confirmed you have NO native worktree/isolation tool.**
Only proceed to Step 3b if you have no native worktree tool available.
### 3b. Git Worktree Fallback
@@ -82,25 +80,25 @@ Native tools handle directory placement, branch creation, and cleanup automatica
#### Directory Selection
Follow this priority order:
Follow this priority order. Explicit user preference always beats observed filesystem state.
1. **Check existing directories:**
1. **Check global and project agent instruction files** (`~/.claude/CLAUDE.md`, `~/.config/gemini/AGENTS.md`, project-level `CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, `.cursorrules`, or equivalent) for a declared worktree directory preference. If specified, use it without asking.
2. **Check for an existing project-local worktree directory:**
```bash
ls -d .worktrees 2>/dev/null # Preferred (hidden)
ls -d worktrees 2>/dev/null # Alternative
```
If found, use that directory. If both exist, `.worktrees` wins.
If found, use it. If both exist, `.worktrees` wins.
2. **Check for existing global directory:**
3. **Check for an 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).
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/`.**
4. **If there is no other guidance available**, default to `.worktrees/` at the project root.
#### Safety Verification (project-local directories only)
@@ -129,7 +127,7 @@ git worktree add "$path" -b "$BRANCH_NAME"
cd "$path"
```
**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.
**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 4: Project Setup
@@ -199,7 +197,7 @@ Ready to implement <feature-name>
| 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 worktree per repo (same Step 1→2→3 flow, matching branch names) |
| Plan touches multiple repos | Offer a matching worktree per repo, same branch name |
## Common Mistakes

View File

@@ -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 using-git-worktrees skill at execution time.
**Context:** If working in an isolated worktree, it should have been created via the `superpowers: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)