Skip to content

refactor: Decompose Orchestrator god object into focused modules #17

@nigel-dev

Description

@nigel-dev

Description

src/lib/orchestrator.ts has grown to 976 lines and continues to expand. It handles scheduling, job launching, merge train control, PR creation, notifications, checkpoint management, environment preparation, and tmux orchestration — a textbook god object.

This makes the codebase harder to understand, test, and extend. Each new feature (touchSet prediction, run history, smart retry) would further bloat this file.

Use Case

  • Testability: Individual modules can be unit-tested in isolation without mocking the entire orchestrator.
  • Maintainability: New contributors can understand one module without reading 976 lines.
  • Extensibility: Phase 2/3 features (touchSet, history, retry policies) have clear homes.

Proposed Solution

Extract into focused modules while keeping the Orchestrator class as a thin coordinator:

New Module Responsibility Approximate Lines
src/lib/plan-manager.ts Plan validation, lifecycle (start/resume/cancel), state transitions ~200
src/lib/job-launcher.ts Worktree setup, prompt file writing, tmux session creation, OMO mode handling ~250
src/lib/reconciler.ts The reconcile loop, dependency checking, job scheduling ~200
src/lib/merge-train.ts Already exists — ensure orchestrator delegates fully

The Orchestrator class becomes a ~150-line coordinator that wires these modules together.

Incremental approach (recommended):

  1. Extract JobLauncher first (most self-contained, easiest to test).
  2. Extract Reconciler next (the core loop).
  3. Extract PlanManager last (most entangled with state).
  4. Each extraction should be a separate PR with tests.

Files Involved

  • src/lib/orchestrator.ts — the 976-line god object
  • src/lib/merge-train.ts — already extracted (good pattern to follow)
  • src/lib/orchestrator-singleton.ts — may need minor updates

Additional Context

From the master audit report (Section 7: Architecture): "orchestrator.ts is 891 lines (was 829 at original audit) — god object handling scheduling, merging, PR creation, notifications, checkpoints. Has grown, not shrunk." Now at 976 lines.

This refactor should happen after the plan correctness bugs (#10, #11, #12, #13, #15) are fixed, so the expected behavior is locked in with tests first.

Metadata

Metadata

Assignees

No one assigned

    Labels

    P2: mediumShould fix — improves reliability or DXenhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions