Worktrees
Guide for managing git worktrees in pokayokay.
When Worktrees Are Created
| Task Type | Default | Override |
|---|---|---|
| feature | Worktree | --in-place |
| bug | Worktree | --in-place |
| spike | Worktree | --in-place |
| chore | In-place | --worktree |
| docs | In-place | --worktree |
| test | Inherits the story worktree (tasks in the same story share it) | explicit flag |
Key Principles
- Story-based reuse — Tasks in the same story share a worktree for related changes
- Auto dependency install — Dependencies install automatically on worktree creation
- Clean completion — Use
finishing-branchto choose merge, PR, keep, or discard with verification evidence - Isolation — All worktrees live in
.worktrees/(auto-ignored by git)
Quick Start Checklist
- Task type determines worktree vs in-place (see table above)
- Story worktrees are reused across related tasks
- Dependencies auto-install based on detected lockfiles
- On completion: use
finishing-branchto verify and choose merge, PR, keep, or discard - Troubleshoot with
git worktree listif issues arise
When NOT to Use
- Starting a work session — Use
work-session; worktree creation happens automatically during/work - Using git worktrees outside pokayokay — This skill is pokayokay-specific; for general git worktrees use git directly
References
| Reference | Description |
|---|---|
| worktree-management.md | Lifecycle, completion options, dependency install, troubleshooting |
| cleanup-strategies.md | Cleanup criteria, detection, disk management, scheduled cleanup |
| parallel-worktrees.md | Parallel execution worktree isolation, conflict prevention |