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

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

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>

Best Practices

1. Use worktrees for parallel development to avoid conflicts
2. Start orchestrator before creating automatic threads
3. Monitor events for workflow progress
4. Use PR Shepherd for automatic CI/review handling
5. Clean up orphaned worktrees periodically