worktree-coordination（工作树协调）

Worktree Coordination Skill

CC 2.1.47 Worktree Fixes: Claude Code 2.1.47 resolved three critical worktree issues: skills/agents not discovered in worktrees, background tasks failing in worktrees, and Windows worktree session matching. Worktrees are now first-class citizens — no workarounds needed.

Agent Teams (CC 2.1.33+): When CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 is set, native Agent Teams provides built-in teammate lifecycle management, peer-to-peer messaging, and shared task lists. This skill's custom file locking and coordination registry are superseded by Teams' native coordination. Use this skill only for non-Teams worktree scenarios (e.g., multiple independent Claude Code sessions without a shared team).

Native Worktree Support (CC 2.1.49)

CC 2.1.49 added native worktree creation via the EnterWorktree tool and --worktree (-w) CLI flag:

# CLI flag — creates worktree and switches session into it
claude --worktree          # auto-named worktree
claude -w my-feature       # named worktree

# Tool — available to agents and skills
EnterWorktree(name="my-feature")  # creates .claude/worktrees/my-feature/

Key behaviors:

• Worktrees are created inside .claude/worktrees/ with a new branch based on HEAD
• On session exit, user is prompted to keep or remove the worktree
• Skills, agents, and hooks are fully discovered in worktrees (fixed in CC 2.1.47)

When to use native vs this skill: Use EnterWorktree for single-session isolation (quick feature branches). Use this skill's coordination registry for multi-session scenarios where multiple Claude instances need file locking and decision sharing.

Worktree Lifecycle Hooks (CC 2.1.50)

CC 2.1.50 added WorktreeCreate and WorktreeRemove hook events, enabling automated lifecycle management:

• WorktreeCreate: Fires when a worktree is created via EnterWorktree or --worktree flag. Use for auto-registration, config copying.
• WorktreeRemove: Fires when a worktree is cleaned up. Use for lock cleanup, registry removal.

These hooks are the preferred approach for lifecycle management — they replace file-watching workarounds.

Agent Isolation (CC 2.1.50)

Agents can now declare isolation: worktree in frontmatter to automatically run in an isolated worktree:

isolation: worktree  # Agent gets its own worktree automatically

This is preferred over manual EnterWorktree calls for agents that modify files.

Commands

/worktree-status

Show status of all active Claude Code instances.

Usage: /worktree-status [--json] [--clean]

Actions:

1. Run cc-worktree-status to see all active instances
2. Check for stale instances (no heartbeat > 5 min)
3. View file locks across all instances

Output includes:

• Instance ID and branch
• Current task (if set)
• Health status (ACTIVE/STALE)
• Files locked by each instance

/worktree-claim

Explicitly lock a file for this instance.

Usage: /worktree-claim src/auth/login.ts

Actions:

1. Check if file is already locked
2. If locked by another instance, show who holds it
3. If available, acquire lock

/worktree-release

Release lock on a file.

Usage: /worktree-release src/auth/login.ts

/worktree-sync

Sync shared context and check for conflicts.

Usage: /worktree-sync [--check-conflicts] [--pull-decisions]

Actions:

1. --check-conflicts: Run merge-tree against other active branches
2. --pull-decisions: Show recent architectural decisions from other instances

/worktree-decision

Log an architectural decision visible to all instances.

Usage: /worktree-decision "Using Passport.js for OAuth" --rationale "Better middleware support"

Automatic Behaviors

File Lock Check (PreToolUse Hook)

Before any Write or Edit operation:

1. Check if file is locked by another instance
2. If locked → BLOCK with details about lock holder
3. If unlocked → Acquire lock and proceed

Heartbeat (Lifecycle Hook)

Every 30 seconds (requires CC 2.1.47+ for reliable execution in worktrees):

1. Update this instance's heartbeat timestamp
2. Clean up stale instances (no heartbeat > 5 min)
3. Release orphaned locks

Cleanup (Stop Hook)

When Claude Code exits (requires CC 2.1.47+ for reliable execution in worktrees):

1. Release all file locks held by this instance
2. Unregister from coordination registry

File Lock States

┌─────────────────────────────────────────────────────────┐
│  FILE: src/auth/oauth.ts                                │
├─────────────────────────────────────────────────────────┤
│  Status: LOCKED                                         │
│  Holder: cc-auth-a1b2c3                                 │
│  Branch: feature/user-authentication                    │
│  Task:   Implementing OAuth2 login flow                 │
│  Since:  2 minutes ago                                  │
├─────────────────────────────────────────────────────────┤
│  Action: Wait for release or use /worktree-release     │
└─────────────────────────────────────────────────────────┘

Registry Schema

Located at .claude/coordination/registry.json:

{
  "instances": {
    "cc-auth-a1b2c3": {
      "worktree": "/Users/dev/worktrees/feature-auth",
      "branch": "feature/user-authentication",
      "task": "Implementing OAuth2",
      "files_locked": ["src/auth/oauth.ts"],
      "started": "-01-08T14:30:00Z",
      "last_heartbeat": "-01-08T14:45:32Z"
    }
  },
  "file_locks": {
    "src/auth/oauth.ts": {
      "instance_id": "cc-auth-a1b2c3",
      "acquired_at": "-01-08T14:35:00Z",
      "reason": "edit"
    }
  },
  "decisions_log": [
    {
      "id": "dec-001",
      "instance_id": "cc-auth-a1b2c3",
      "decision": "Use Passport.js for OAuth",
      "rationale": "Better middleware support",
      "timestamp": "-01-08T14:40:00Z"
    }
  ]
}

CLI Commands

Available in bin/:

# Create new coordinated worktree
cc-worktree-new <feature-name> [--base <branch>]

# Check status of all worktrees
cc-worktree-status [--json] [--clean]

# Sync context and check conflicts
cc-worktree-sync [--check-conflicts] [--pull-decisions]

Best Practices

1. One task per worktree - Each Claude Code instance should focus on one feature/task
2. Claim files early - Use /worktree-claim before starting work on shared files
3. Log decisions - Use /worktree-decision for choices that affect other instances
4. Check conflicts - Run cc-worktree-sync --check-conflicts before committing
5. Clean up - Exit Claude Code properly to release locks (Ctrl+C or /exit)

Troubleshooting

"File is locked by another instance"

1. Check who holds it: /worktree-status
2. If instance is STALE: cc-worktree-status --clean
3. If legitimately held: Coordinate with other instance or work on different files

"Instance not registered"

The heartbeat hook will auto-register on first tool use. If issues persist:

1. Confirm you are running CC 2.1.47+ (background tasks in worktrees required this fix)
2. Check .claude-local/instance-id.txt exists
3. Verify .claude/coordination/ is symlinked correctly

Platform Support (CC 2.1.47+)

CC 2.1.47 fixes that improved worktree support:

• Skills and agents are now discovered correctly from worktrees (previously only from main checkout)
• Background tasks (Task tool) complete successfully from worktrees
• Windows worktree session matching works with drive letter casing differences

Related Skills

• ork:git-workflow - Git workflow patterns used within each coordinated worktree
• ork:commit - Create commits with proper conventional format in each worktree
• stacked-prs - Manage dependent PRs that may span multiple worktrees
• ork:architecture-decision-record - Document decisions shared via /worktree-decision

Key Decisions

Capability Details

status-check

Keywords: worktree, status, instances, active, who Solves:

• How to see all active Claude Code instances
• Check which files are locked
• Find stale instances

file-locking

Keywords: lock, claim, release, conflict, blocked Solves:

• How to prevent file conflicts between instances
• Claim a file before editing
• Release a lock when done

decision-sync

Keywords: decision, sync, share, coordinate Solves:

• Share architectural decisions across instances
• See what other instances decided
• Coordinate approach between worktrees

conflict-prevention

Keywords: conflict, merge, overlap, collision Solves:

• Check for merge conflicts before committing
• Avoid overlapping work
• Coordinate parallel development