Prompt file imported from jabrena/plinth (
.cursor/commands/create-worktree.md). Copyright stays with the author.
create-worktree
Always create a new branch and linked Git worktree for isolated or parallel work without changing the current checkout.
Usage
/create-worktree <issue-or-change|type description> [<target-path>] [<base-reference>]
Accepted Inputs
- An issue/change identifier, or an explicit branch type and description
- Optional preferred target path
- Optional base reference
- Supported branch types:
feat,fix,docs,refactor, andchore - Preferred branch format:
<type>/<issue-or-change>-<kebab-case-description>when an issue or OpenSpec change is available, otherwise<type>/<kebab-case-description> - Fresh-name rule: if the preferred branch name or target path already exists, derive the next unused suffix such as
-2,-3, and continue with the fresh branch/worktree
Owning Agent
@plinth-tech-lead
Associated Capabilities
- Git branch naming and validation
- Git linked worktrees
- Parallel OpenSpec child-change coordination
Workflow
- Resolve the preferred branch name from the issue/change identifier or explicit branch details.
- Resolve an absolute preferred target path and the base reference.
- Resolve the repository default branch and the current branch.
- Verify the current checkout is
mainor the repository default branch before creating the worktree branch. - If the current branch is not
mainor the default branch, stop and ask whether to switch to the default branch, choose a different base, or continue explicitly from the current branch. - Verify the repository and selected base reference are valid before creating anything.
- Derive a fresh branch name and fresh target path when the preferred branch exists, is checked out in another worktree, or the preferred target path exists.
- Verify the final branch name does not exist, is not checked out in another worktree, and the final target path does not exist.
- Run the equivalent of
git worktree add -b <branch> <target-path> <base-reference>. - Report the created branch, absolute worktree path, base reference, and cleanup command.
Output
- Created local branch
- Created linked worktree
- Exact branch name, absolute path, and base reference
- Cleanup command:
git worktree remove <absolute-worktree-path>
Safeguards
- Never reuse the current checkout or an existing worktree for the requested work.
- When the preferred branch or path conflicts with existing state, choose a fresh unused branch name and target path instead of reusing or overwriting existing state.
- Stop and ask when the current branch is not
mainor the repository default branch. - Stop if the base reference is invalid.
- Leave existing branches, worktrees, directories, and files unchanged on conflict.
- Do not commit, push, remove worktrees, delete branches, or use force.
