Three Approaches

Choose how to get from current state to unified architecture

A — Incremental ⭐ Recommended
Step 1
Merge BugFix+Doc into Orchestrator
No behaviour change
Step 2
Add pipelines/ YAML support to Orchestrator
New feature, backwards compat
Step 3
Refactor watcher: per-repo queues + LLM pools
Deploy independently
Step 4
Update Actions workflows, delete thin wrappers
Cleanest end state
✅ Each step is safe and tested before next
✅ Can pause between steps if needed
⚠️ Slightly more total work (4 PRs vs 1)
✅ Tests stay green throughout
B — Big Bang
Do everything in one PR: merge orchestrators, add pipeline YAML support, redesign watcher with queues/pools, update all workflows, delete old files.
✅ One PR, clean history
❌ Hard to debug if tests break mid-way
❌ Risky: big diff, many moving parts
❌ Can't pause safely
C — Watcher-forward
Start by redesigning watcher (queues, pools, pipeline-file dispatch), but keep BugFix/DocOrchestrators as separate classes temporarily. Merge them in a second PR.
✅ Concurrency model works right away
❌ Temporary state is messier (3 orchestrator classes)
→ Ends up same as A but in different order
Recommendation: Option A (Incremental). Each step can be reviewed and deployed independently. Steps 1–2 require no config changes for existing users; step 3 adds new config keys (fully optional with defaults); step 4 is the cleanup.