feat: worktree-based parallel development for /qq:execute

[tykisgod]

Summary

/qq:execute should support git worktree-based isolation for parallel feature development. Multiple Claude Code sessions can work on orthogonal features simultaneously, each in its own worktree.

Workflow

1. execute detects current branch (if main → prompt to create feature branch)
2. Create worktree + sub-branch from current branch
3. AI writes code in worktree
4. Compile via batch mode (no Unity Editor needed in worktree)
5. Test via batch mode
6. All pass → merge back to source branch
7. Ask: delete worktree? (default yes)

Why worktrees (not just branches)

Multiple Claude Code sessions can't share one working directory. Worktrees give each session its own file system while sharing the same .git object database.

Unity-specific considerations

• Library/ regeneration: first batch-mode compilation in a new worktree generates Library/ (~5-10 min one-time cost). Subsequent compilations are incremental (~15-30s).
• Unity Accelerator: running on localhost can cache imported assets, dramatically speeding up Library/ generation for new worktrees.
• No symlink: Unity officially does not support symlinked Library/ folders — will cause corruption.
• Batch mode fallback: unity-compile-smart.sh already falls back to batch mode when no Editor is detected. No script changes needed.

Changes needed

execute SKILL.md

• Add worktree creation step before implementation
• Main branch detection + warning
• Merge-back step after completion
• Worktree cleanup prompt

commit-push SKILL.md

• Detect if in a worktree → offer merge back to source branch
• After merge, prompt to delete worktree

Compile/test in worktree

• Already works via batch mode fallback in existing scripts
• No changes to unity-compile-smart.sh or unity-test.sh needed

Example

# User on branch dev/vehicle-system, starts 3 Claude Code sessions:

# Session 1:
/qq:execute damage-system.md
# → creates worktree ../project-wt-damage on branch dev/vehicle-damage
# → implements, compiles (batch), tests (batch)
# → merges back to dev/vehicle-system
# → deletes worktree

# Session 2 (parallel):
/qq:execute fire-effect.md
# → creates worktree ../project-wt-fire on branch dev/vehicle-fire
# → same flow, independent

# Session 3 (parallel):
/qq:execute explosion.md
# → creates worktree ../project-wt-explosion on branch dev/vehicle-explosion
# → same flow, independent

Not in scope

• Ephemeral worktrees (Claude Code's isolation: "worktree") — Library/ cost makes these impractical for Unity
• Shared Library/ via symlink — officially unsupported by Unity
• Auto-opening Unity Editor in worktrees — batch mode is sufficient

[m13v]

the biggest pain we hit with worktree-based parallel agents was the initial setup cost per worktree. on a large Swift project (not Unity but similar pain), derived data regen added 5-10 min per agent spawn. ended up keeping a pre-warmed template worktree that already has expensive build artifacts, then shallow-clone from that for each new agent.

the other gotcha is file locking during git gc. when multiple worktrees share the same .git/objects directory, gc can cause transient failures in parallel operations. worth adding retry logic around git commands, especially merge-back. we lost about a day debugging flaky merges before realizing gc was the culprit.

[m13v]

we documented our parallel agent orchestration patterns (including worktree management and crash recovery) here if it helps: https://github.com/m13v/tmux-background-agents/blob/main/SKILL.md