worktree-management

name	worktree-management
description	Scaffolding worktree lifecycle, diagnostics, and recovery. TRIGGER when: debugging worktree isolation, recovering a stuck worktree, or managing task isolation. SKIP: ordinary branch/commit/merge operations (use git-operations).

Worktree Management Skill

Purpose

Scaffolding.tool-specific worktree lifecycle management, diagnostics, and recovery procedures.

Live worktrees: !git worktree list 2>/dev/null || true

CRITICAL: Only gitops Touches Git

Other agents (developer, architect) do NOT commit. The worktree flow is:

1. Agent writes code/tests in worktree
2. gitops commits, merges to main, pushes, cleans up

If a worktree has no new commits after an agent finishes, the changes are uncommitted — gitops must commit them BEFORE merge.

Parallel Teammates: Isolation + Serialized Merge

When Agent Teams is enabled (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, see docs/agent-teams.md), multiple writer teammates may run concurrently. The worktree model makes this safe ONLY if both hold:

• Per-teammate isolation: every writer gets its OWN worktree .scaffolding/worktrees/{task_id[:12]} AND its OWN unique SCAFFOLDING_TASK_ID. No two writers share a working tree or a /tmp/scaffolding-mtime-${TASK_ID}.json staleness store — sharing would trip file-staleness-check.sh between them and produce unattributable interleaved changes.
• Serialized merge: gitops remains the SOLE committer and merges worktree branches to main ONE AT A TIME through the merging→merged states below. Parallel work is allowed; parallel committing/merging is not — only one merge is ever in flight.

Worktree Lifecycle

create_worktree() --> agent executes (no commit) --> gitops: commit
    --> gitops: merge_to_main() --> gitops: push --> gitops: cleanup

States (WorktreeStatus enum)

Status	Meaning
ready	Created, waiting for task execution
merging	Merge in progress
merged	Successfully merged to main
conflict	Merge conflict detected
cleanup	Being removed
removed	Fully cleaned up

File Locations

Resource	Path
Worktrees directory	.scaffolding/worktrees/
Worktree metadata	.scaffolding/worktrees/{task_id[:12]}/worktree.json
Branch naming	scaffolding/{task_id[:12]}

Diagnostics

List All Worktrees

git worktree list
ls -la .scaffolding/worktrees/

Find Uncommitted Changes

for d in .scaffolding/worktrees/*/; do
  changes=$(cd "$d" && git status --porcelain 2>/dev/null | wc -l)
  if [ "$changes" -gt 0 ]; then
    echo "UNCOMMITTED: $d ($changes files)"
  fi
done

Recovery Procedures

Force Remove Corrupt Worktree

git worktree remove --force .scaffolding/worktrees/{task_id[:12]}
git branch -D scaffolding/{task_id[:12]}
rm -rf .scaffolding/worktrees/{task_id[:12]}
git worktree prune

Recover Uncommitted Work

cd .scaffolding/worktrees/{task_id[:12]}
git add -A && git stash
cd /project/root && git stash pop

Post-Finish Cleanup

After a merge or discard finishing action, clean up the worktree:

git worktree remove .scaffolding/worktrees/{task_id[:12]} 2>/dev/null
rm -rf .scaffolding/worktrees/{task_id[:12]}
git worktree prune

Note: Only needed for merge and discard actions. PR and keep actions leave the worktree intact.