Skip to content

fix(using-git-worktrees): default to global worktree location to avoid CLAUDE.md double-loading#639

Open
stablegenius49 wants to merge 1 commit intoobra:mainfrom
stablegenius49:pr-factory/issue-279-global-worktree-default
Open

fix(using-git-worktrees): default to global worktree location to avoid CLAUDE.md double-loading#639
stablegenius49 wants to merge 1 commit intoobra:mainfrom
stablegenius49:pr-factory/issue-279-global-worktree-default

Conversation

@stablegenius49
Copy link

Problem

Project-local worktrees (.worktrees/ inside the repo) can cause nested worktrees to load both the worktree's CLAUDE.md and the parent repo's CLAUDE.md, creating conflicting instructions.

Closes #279

Solution

  • Default to global worktree location: ~/.config/superpowers/worktrees/<project-name>/
  • Reuse existing conventions when present (both global and project-local)
  • Only ask user if they need project-local after recommending global
  • Update quick reference, example workflow, and best practices to reflect new default

Changes

  • Updated "Directory Selection Process" to prioritize global location by default
  • Updated Quick Reference table with new priority order
  • Updated Example Workflow to use global location
  • Added note in Overview about avoiding CLAUDE.md double-loading

Testing

  • No automated tests for skill documentation (manual verification)
  • Diff is documentation-only, reversible

Checklist

  • Diff is small and reversible
  • No risky/destructive operations
  • Respects contribution rules (documentation improvement)

…d CLAUDE.md double-loading\n\n- Prioritize global location (~/.config/superpowers/worktrees/<project>/) to avoid nested worktrees loading parent CLAUDE.md\n- Keep support for project-local worktrees when explicitly requested or already in use\n- Update quick reference, example workflow, and common mistakes to reflect new default\n- Closes obra#279
IgorTavcar added a commit to IgorTavcar/superpowers that referenced this pull request Mar 9, 2026
Uses ~/.config/superpowers/worktrees/<project>/ instead of project
subdirectory to avoid CLAUDE.md double-loading from nested worktrees.

Upstream PR: obra#639

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Copy link
Contributor

@mvanhorn mvanhorn left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Summary

Clean change - defaulting to global worktree location to avoid CLAUDE.md double-loading makes sense. The priority reordering (CLAUDE.md > existing > global default > ask) is logical.

Findings

The existing ### For Global Directory safety section (line 88-90) is a one-liner: "No .gitignore verification needed - outside project entirely." Now that global is the default path, it might be worth expanding this in a follow-up to mention git worktree prune for cleaning stale refs - if a user deletes the global directory manually instead of using git worktree remove, the next git worktree add to the same path would fail with "already registered as a worktree."

One small inline suggestion on the Quick Reference table to mirror the "(verify ignored)" safety note the project-local rows have.

Recommendation

Looks good to merge. The suggestion is a minor improvement, not a blocker.


Review assisted by Claude Code

| Both exist | Use `.worktrees/` |
| Neither exists | Check CLAUDE.md → Ask user |
| CLAUDE.md specifies location | Use that location |
| Global worktree dir exists | Reuse global location |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Consider adding a safety note parallel to the project-local rows' "(verify ignored)". If the user previously deleted the global worktree directory without git worktree remove, stale refs in .git/worktrees/ would cause git worktree add to fail.

Suggested change
| Global worktree dir exists | Reuse global location |
| Global worktree dir exists | Reuse global location (prune stale refs) |

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

using-git-worktrees: Project-local .worktrees/ causes duplicate CLAUDE.md loading

2 participants