gopherguides Worktree
Plugin Resource Resolution
<PLUGIN_ROOT> is notation. Replace it with a concrete absolute plugin root before every resource read or command:
- Codex: Start from the directory containing the absolute selected
SKILL.mdpath, then ascend two directories (skills/<name>-> plugin root). - Claude Code: Bind it to the injected
${CLAUDE_PLUGIN_ROOT}value.
Manage git worktrees for isolated per-issue/per-PR work. Three sub-actions, each in its own sibling file.
Before requesting decisions, read
<PLUGIN_ROOT>/lib/driver-interaction.md and follow its
cross-platform capability-binding rules.
Read <PLUGIN_ROOT>/lib/decision-gates.md before resolving action,
target, consent, or cleanup choices.
Action selection
| User intent | Sibling | Slash command |
|---|---|---|
| Create one worktree for an issue or PR | create.md |
/create-worktree <num> |
| Remove a specific worktree (interactively) | remove.md |
/remove-worktree |
| Batch-clean all completed worktrees | prune.md |
/prune-worktree |
Match the user's request to one of the three rows, then read the corresponding sibling for the full procedure.
If the request does not identify one action, follow the shared missing-intent gate. Request create, remove, or prune intent and stop before mutating worktrees.
Conventions (apply to all three actions)
- Worktree path:
../<reponame>-issue-<num>-<title-slug>/— sibling to the source repo, never inside it - Branch name:
issue-<num>-<title-slug> - Title slug: lowercase, alnum + hyphens, derived from
gh issue view --json title - Identifier rule:
issue-<NUM>-prefix is the trusted issue marker on a branch —fix/2fa-logincontains a number but is NOT an issue branch - Default branch:
git remote show origin | grep 'HEAD branch'(handles repos withmainvsmastervs custom) - State file:
<PLUGIN_ROOT>/scripts/worktree-state.shregisters the active worktree so the pre-tool-use hook blocks accidental edits to the source repo
Prerequisites (all three)
ghCLI installed and authenticated- Run from inside a git repository (any worktree of the repo, not just the main checkout)
Further Reading
create.md— full create procedure (PR vs issue detection, env-file copy, state registration)remove.md— interactive selection + safety-check matrix (issue closed? branch merged? uncommitted changes?)prune.md— batch evaluation, classification, confirmation, removal