docs(worktrees): support the OS temp directory as a worktree location

[muunkky]

Closes #666. Taking the second pass you invited when you closed #668.

Who is submitting this PR? (required)

Field	Value
Your model + version	Claude Opus 4.8 (claude-opus-4-8), 1M context
Harness + version	Claude Code 2.1.207
All plugins installed	gitban (muunkky.github.io/gitban-site), frontend-design, skill-creator, claude-patent-creator-standalone. Not superpowers itself.
Human partner who reviewed this diff	Cameron Rout (@muunkky)

What problem are you trying to solve?

#666 asks for one thing: let worktrees live in the OS temp directory, so short-lived ones get reaped without anyone having to remember them. Today the skill offers .worktrees/ at the project root and nothing else.

There's a trap in doing it naively, and it's the actual content of this change. finishing-a-development-branch decides what it owns by path:

If WORKTREE_PATH is under .worktrees/ or worktrees/: Superpowers created this worktree — we own cleanup

Otherwise: The host environment owns this workspace — leave it in place.

So if the skill starts putting worktrees at, say, $TMPDIR/superpowers-worktrees/, superpowers creates them and then disowns them at cleanup — the worktree is never removed and the branch delete fails with it still attached.

What does this PR change?

Documents the temp directory as a location, with the path shape that keeps cleanup working. Ten added lines in using-git-worktrees, nothing removed.

"${TMPDIR:-/tmp}/superpowers/worktrees/<branch-name>"

The worktrees/ component is the whole point: the existing ownership check matches on it, so the temp worktree stays superpowers-owned and gets removed normally. No lifecycle system, no registry, no daemon — and no change to finishing-a-development-branch.

Also notes what the issue itself raises: this suits short-lived branches, $TMPDIR is reaped on a schedule you don't control, and a directory that vanishes mid-branch needs git worktree prune (which the cleanup path already runs).

Is this change appropriate for the core library?

Yes — a configuration option in a core skill, and it's what #666 asked for.

What alternatives did you consider?

The obvious one is to extend the ownership rule in finishing-a-development-branch to name a temp path explicitly. That would be more robust: it wouldn't depend on people keeping the worktrees/ component in the path. I didn't do it because it turns out not to be necessary — a path under worktrees/ already satisfies the rule as written — and reusing the existing check beats adding a second one.

The price: if someone sets a temp location without that component, cleanup silently disowns the worktree. That's a real footgun and it's the reason the guidance spells the path out rather than saying "use $TMPDIR".

I also didn't touch option 2 from the issue body (~/.config/superpowers/worktrees/). The rototill removed that path deliberately and tests/claude-code/test-worktree-path-policy.sh asserts it doesn't come back.

Does this PR contain multiple unrelated changes?

No. One file, one option.

Existing PRs

• I have reviewed all open AND closed PRs for duplicates or prior art
• Related PRs: feat(worktree): add lifecycle management with automatic garbage collection #668 (closed), refactor: modernize finishing-a-development-branch (discard demotion, worktree-path fix, rationalization table) #1933 (merged)

#668 is the prior attempt. You closed it as "a massive amount of complexity for what should be a straightforward configuration option" — a JSON registry, CLI manager, GC daemon, post-merge hooks and LaunchAgents. This is the straightforward option: ten lines of guidance, no new machinery, no new files.

#1933 rewrote the ownership block in finishing-a-development-branch and has since merged. I've re-checked this against dev after that landed: the rule still matches on .worktrees/ or worktrees/, so the path shape here still works and this PR still doesn't need to touch that file.

Also related: #1542 asks for a RAM-backed worktree location. Not building for it — one problem per PR — but it's the same "configurable non-default location" shape, so the convention here is the one it would inherit.

Environment tested

Harness	Harness version	Model	Model version/ID
Claude Code	2.1.207	Claude Opus 4.8	claude-opus-4-8 (1M context)

tests/claude-code/test-worktree-path-policy.sh passes. I checked the ownership claim by reading the rule on current dev, not by running a macOS reap — I'm on Linux and haven't reproduced the $TMPDIR cleanup timing the issue describes.

Evaluation

No eval sessions. This adds a documented option below the existing priority order and changes no existing instruction — the default is still .worktrees/ — so there's no prior behaviour to compare against. If you'd rather see a baseline, I can run one.

Rigor

• If this is a skills change: I used superpowers:writing-skills and completed adversarial pressure testing
• This change was tested adversarially, not just on the happy path
• I did not modify carefully-tuned content (Red Flags table, rationalizations, "human partner" language) without extensive evals

First box unticked: I didn't use writing-skills and have no pressure-test results.

The adversarial part I did do is the failure mode above — I went looking for how this breaks, found the disown-at-cleanup path, and checked that the path-policy test still passes and the deleted global path stays deleted.

Human review

• A human has reviewed the COMPLETE proposed diff before submission