worktree-coordination

# Worktree Coordination Skill

## 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 <file-path>
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 <file-path>
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 <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:
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:
1. Release all file locks held by this instance
2. Unregister from coordination registry

## File Lock States

```
┌─────────────────────────────────────────────────────────┐
│  FILE: src/auth/oauth.ts