Thread Orchestrator Skill

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>

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

Converted and distributed by TomeVault — claim your Tome and manage your conversions.