mrlyk Using Git Worktrees
One CLI call creates or reuses the single task worktree. Run the command, then act on the JSON result.
Create
superharness task worktree create {task-id} --json
Full and Lite share the same worktree kind: branch superharness/{task-id}, one checkout per task. The CLI resolves the layout (a non-empty persisted worktree_path is authoritative and reused exactly; otherwise flat-v1 from .superharness/worktree.yaml), verifies the directory is git-ignored (appending to .gitignore when needed — commit that change), copies minimal .superharness/ state (spec, config, workflow, worktree.yaml, active task directory), writes worktree_path back to both task.json copies (parent-thread hooks locate the active task by matching it against the session cwd), symlinks node_modules from the primary checkout when possible, and returns reused: true when a compatible worktree already exists.
superharness task worktree path {task-id} --json answers path-only lookups. A generic worktree without a task directory is the only manual case: git worktree add <worktree_dir>/<name> -b superharness/<name>.
Verify Baseline
Run the post_create and verify commands from the JSON result and read the output. If verification fails, report the failures and ask whether to proceed.
Recovery and Cleanup
reused: true never re-copies or resets anything. An in_progress task may leave intentional uncommitted work: inspect git status, the diff, recent commits, and the task's focused verification before assigning ownership, dispatch a recovery agent for the same task, and ask the user when ownership is unclear. Never reset or stash a dirty recovery checkout.
Cleanup goes through superharness task worktree prune {task-id} --json, which removes the worktree only after the task is completed, the checkout is clean, and the registered branch matches superharness/{task-id}; anything else is preserved with a reason.
Integration
Called by:
- superharness:subagent-driven-development - Setup, REQUIRED before dispatching any implementer (full profile)
- superharness:go - lite profile only, when the concurrency check finds another active task on this checkout
- Any skill needing isolated workspace
Pairs with:
- superharness:finishing-a-development-branch - REQUIRED for cleanup after work complete