Large codebase migrations are not typing problems; they are distributed state machine problems.
When you execute a multi-step, multi-PR refactor with an LLM, like the workflows I proposed in this migration-orchestration-skill, you're not just writing code. You're instantiating a distributed system. The orchestrator becomes the control plane, LLM subagents become asynchronous worker nodes, and the local repository becomes your shared database.
Most AI workflow documentation assumes a "happy path" where agents neatly read instructions, edit files, and check off a Markdown list. This is whiteboard architecture at its most naive. In reality, agents hallucinate, Git locks up, test suites hang, and state files corrupt. To build an orchestrator that actually finishes a migration, we must align our architecture with the mechanical realities of the environment.
The Context & The Constraint
The core business requirement is to safely sequence, verify, and commit a massive architectural change (e.g., migrating a monolith to partitioned micro-databases or rewriting React classes to hooks) without blocking concurrent human feature development.
