Thread Orchestrator Skill

This skill provides orchestration capabilities for managing multiple Claude agent threads with git worktree isolation.

When to Use

Activate this skill when the user wants to:

• Run multiple Claude agents in parallel with isolated worktrees
• Coordinate complex workflows across multiple threads
• Manage thread lifecycle (create, start, stop, resume)
• Handle inter-thread communication via events
• Monitor and manage PR feedback loops

Core Capabilities

Thread Lifecycle Management

• Create threads with different modes (automatic, semi-auto, interactive, sleeping)
• Create threads with isolated git worktrees
• Start, stop, pause, and resume threads
• Query thread status and view logs
• Delete completed threads

Git Worktree Isolation

• Each thread can have its own isolated git worktree
• Multiple threads can work on different branches simultaneously
• Automatic worktree cleanup when threads complete
• Push changes from worktree to remote

Event-Driven Coordination

• Publish events to the blackboard
• Subscribe to events from other threads
• Send direct messages between threads
• Share artifacts between threads

PR Shepherd Integration

• Watch PRs with isolated worktrees
• Automatic CI failure detection and fix
• Review change request handling
• Worktree-per-PR isolation

Essential Commands

Thread Operations

# Initialize claude-threads in project
ct init

# Create a thread
ct thread create <name> --mode <mode> --template <template>

# Create thread with isolated worktree
ct thread create <name> --mode automatic --worktree
ct thread create <name> --worktree --worktree-base develop

# List threads
ct thread list [status]

# Start/stop/resume threads
ct thread start <id>
ct thread stop <id>
ct thread resume <id>

# View thread status and logs
ct thread status <id>
ct thread logs <id>

Worktree Management

# List all active worktrees
ct worktree list

# Show worktree details
ct worktree status <id>

# Cleanup orphaned worktrees
ct worktree cleanup

Orchestrator Control

# Start/stop orchestrator daemon
ct orchestrator start
ct orchestrator stop
ct orchestrator status
ct orchestrator restart

PR Shepherd

# Watch PR with worktree isolation
ct pr watch <pr_number>

# Check status
ct pr status [pr_number]
ct pr list

# Stop watching
ct pr stop <pr_number>

# Run as daemon
ct pr daemon

Event Operations

# List recent events
ct event list

# Publish event
ct event publish <type> '<json>'

Thread Modes

Mode	Use Case
automatic	Fully autonomous background tasks
semi-auto	Autonomous with user approval for critical steps
interactive	Step-by-step user confirmation
sleeping	Scheduled or event-triggered tasks

Workflow Patterns

Parallel Epic Development

# Create threads with isolated worktrees
ct thread create epic-7a --mode automatic --template bmad-developer.md --worktree --context '{"epic_id": "7A"}'
ct thread create epic-8a --mode automatic --template bmad-developer.md --worktree --context '{"epic_id": "8A"}'

# Start orchestrator
ct orchestrator start

# Monitor
ct thread list running
ct worktree list

PR Fix Pipeline

# Watch PR - creates isolated worktree
ct pr watch 123

# Shepherd automatically:
# - Creates worktree for PR branch
# - Spawns fix threads when CI fails
# - Pushes fixes from worktree
# - Cleans up when PR merges

ct pr status 123

Coordinated Review

# Create reviewer thread that triggers on development completion
ct thread create reviewer --mode semi-auto --template reviewer.md --trigger DEVELOPMENT_COMPLETED

# Events flow: STORY_COMPLETED -> DEVELOPMENT_COMPLETED -> reviewer wakes

Event Types

Event	Description
THREAD_STARTED	Thread began execution
THREAD_COMPLETED	Thread finished
THREAD_BLOCKED	Thread encountered a blocker
WORKTREE_CREATED	Isolated worktree created
WORKTREE_PUSHED	Changes pushed from worktree
WORKTREE_DELETED	Worktree cleaned up
STORY_STARTED	Developer starting story
STORY_COMPLETED	Story implementation done
DEVELOPMENT_COMPLETED	All stories finished
REVIEW_COMPLETED	Code review done
PR_CREATED	Pull request opened
CI_PASSED / CI_FAILED	CI status update
PR_APPROVED	PR approved
PR_MERGED	PR merged successfully

Configuration

In .claude-threads/config.yaml:

threads:
  max_concurrent: 5
  default_max_turns: 80

orchestrator:
  poll_interval: 1
  idle_poll_interval: 10
  idle_threshold: 30

worktrees:
  enabled: true
  max_age_days: 7
  auto_cleanup: true
  default_base_branch: main
  auto_push: true

pr_shepherd:
  max_fix_attempts: 5
  ci_poll_interval: 30
  auto_merge: false

State Locations

• Database: .claude-threads/threads.db
• Logs: .claude-threads/logs/
• Config: .claude-threads/config.yaml
• Templates: .claude-threads/templates/
• Worktrees: .claude-threads/worktrees/

Error Handling

If a thread becomes blocked:

# Check status
ct thread status <id>

# View logs
ct thread logs <id>

# Resume manually
ct thread resume <id>

# Or restart
ct thread stop <id> && ct thread start <id>

Base + Fork Pattern (Memory Efficient)

For PR lifecycle management, use the base + fork pattern:

# Create base worktree when watching a PR (once)
ct worktree base-create 123 feature/my-pr main

# Fork from base for each sub-agent (shares git objects, ~1MB vs ~100MB)
ct worktree fork 123 conflict-fix fix/conflict conflict_resolution

# After sub-agent completes, merge fork back
ct worktree merge-back conflict-fix

# Cleanup fork
ct worktree remove-fork conflict-fix

# When PR is done, cleanup base
ct worktree base-remove 123

Benefits

• Forks share git objects with base (memory efficient)
• Fast creation and removal
• Centralized push from base worktree
• Easy coordination of parallel fixes

Coordination Patterns

Pattern 1: Sequential Chain

A ─► B ─► C ─► Done

Use: Tasks with dependencies

Pattern 2: Parallel Fan-Out

    Orchestrator
    ┌─┬─┬─┬─┬─┐
    ▼ ▼ ▼ ▼ ▼ ▼
    1 2 3 4 5 6

Use: Independent parallel tasks (max 5)

Pattern 3: Fan-Out/Fan-In (PR Lifecycle)

PR Shepherd
├── Fork → Conflict Resolver → Merge Back
├── Fork → Comment Handler 1 → Merge Back
└── Fork → Comment Handler 2 → Merge Back
Then: Push from base

Cross-Instance Orchestration

Connect external Claude Code instances:

# On orchestrator machine
ct api start --token $TOKEN

# On worker machine
ct remote connect orchestrator:31337 --token $TOKEN
ct spawn epic-7a --template bmad-developer.md

Best Practices

1. Use worktrees for parallel development to avoid conflicts
2. Use base + fork pattern for PR sub-agents (memory efficient)
3. Start orchestrator before creating automatic threads
4. Monitor events for workflow progress
5. Use PR Shepherd for automatic CI/review handling
6. Clean up orphaned worktrees periodically
7. Publish events for all significant state changes
8. Use checkpoints for long-running agents

Documentation

• ARCHITECTURE.md - System architecture
• AGENT-COORDINATION.md - Coordination patterns
• WORKTREE-GUIDE.md - Worktree management
• EVENT-REFERENCE.md - Event types
• MULTI-INSTANCE.md - Distributed deployment