Open Orchestrator

Appearance

This workflow shows how to use Open Orchestrator for large refactoring efforts that touch multiple parts of your codebase.

The Scenario ​

You're migrating from one pattern to another:

  • Moving from callbacks to async/await
  • Implementing the repository pattern
  • Updating to a new API version

Step 1: Plan the Refactoring ​

Create a planning worktree with the feature template (plan mode enabled):

bash
owt new "Plan repository pattern refactoring" -t feature

Send planning task:

bash
owt send feat/plan-repository-pattern "Analyze the codebase and create a refactoring plan for:
[describe the refactoring goal]

Please identify:
1. All files that need changes
2. Dependencies between files
3. Suggested order of changes
4. Potential risks"

Step 2: Create Module-Specific Worktrees ​

Based on the plan, create worktrees for each area:

bash
# Data layer refactoring
owt new "Refactor data layer to repository pattern"

# Service layer refactoring
owt new "Refactor service layer for repositories"

# API layer refactoring
owt new "Refactor API layer for new services"

# Tests update
owt new "Update tests for repository pattern"

Step 3: Delegate with Dependencies ​

Send tasks with awareness of dependencies:

bash
# Data layer first (no dependencies)
owt send refactor/data-layer-repository-pattern "Implement repository pattern for data access:
- Create UserRepository
- Create ProductRepository
- Create OrderRepository
Keep existing interfaces for now"

# Service layer (depends on data layer patterns)
owt send refactor/service-layer-repositories "Once data layer is ready, update services:
- UserService to use UserRepository
- ProductService to use ProductRepository
- OrderService to use OrderRepository
Monitor refactor/data-layer progress first"

# API layer (depends on service layer)
owt send refactor/api-layer-new-services "Once service layer is updated:
- Update controllers to use new service interfaces
- Ensure API contracts remain unchanged
Monitor refactor/service-layer progress first"

# Tests (can start parallel, update as layers complete)
owt send feat/update-tests-repository "Update test suite:
- Add unit tests for new repositories
- Update service tests for new patterns
- Keep integration tests passing"

Step 4: Monitor via Control Plane ​

Track progress using the Control Plane:

bash
owt

The sectioned view shows which layers are in flight, idle, or need your attention. Attach to any worktree by pressing a, review progress, and return with Alt+s.

Step 5: Coordinate Progress ​

As layers complete, unblock dependents:

bash
# When data layer completes
owt send refactor/service-layer-repositories "Data layer complete. Repository patterns:
- UserRepository: findById, findAll, save, delete
- ProductRepository: findById, findAll, save, delete
Begin service layer updates"

# When service layer completes
owt send refactor/api-layer-new-services "Service layer complete. New interfaces:
- UserService.getUser(id)
- ProductService.listProducts()
Begin API layer updates"

Step 6: Incremental Testing ​

Run tests as each layer completes:

bash
# Test data layer
owt send feat/update-tests-repository "Run repository tests: npm test -- --grep Repository"

# Test service layer
owt send feat/update-tests-repository "Run service tests: npm test -- --grep Service"

# Full test suite
owt send feat/update-tests-repository "Run full test suite and report failures"

Step 7: Merge ​

When all layers are done, merge in dependency order:

bash
# Merge data layer first
owt merge refactor/data-layer-repository-pattern

# Then service layer
owt merge refactor/service-layer-repositories

# Then API layer
owt merge refactor/api-layer-new-services

# Finally tests
owt merge feat/update-tests-repository

The two-phase merge catches conflicts early by merging base into feature first.

Handling Merge Conflicts ​

Large refactorings often have conflicts. Use sync:

bash
# Sync all with main periodically
owt sync --all

If conflicts arise, attach to the worktree from the Control Plane and resolve them.

Rollback Strategy ​

If something goes wrong:

bash
# Each worktree is independent - can abandon one
owt delete refactor/api-layer-new-services --force

# Start fresh
owt new "Refactor API layer (take 2)"
owt send refactor/api-layer-take-2 "Start over with API layer refactoring"

Tips for Large Refactorings ​

  1. Plan first -- Use the feature template with plan mode to understand scope
  2. Layer dependencies -- Know what depends on what
  3. Test incrementally -- Don't wait until the end
  4. Sync regularly -- Keep up with main branch
  5. Monitor the Control Plane -- Watch for blocked or errored worktrees
  6. Keep tests passing -- Run tests after each layer

Pattern: Strangler Fig ​

For large legacy migrations, use the strangler fig pattern:

bash
# Create parallel implementation
owt new "Implement new auth system alongside old"

# Build new alongside old
owt send feat/implement-new-auth "Implement new auth system that can run parallel to old"

# Gradually migrate
owt send feat/implement-new-auth "Add feature flag to switch between old and new auth"

See Also ​