Parallel Agent Migration: Dependency-Ordered File Assignment Prevents Merge Conflicts
Problem / Context
A large codebase migration (Angular to React) could not be completed by a single agent due to context window limits and compounding errors: incorrect early file migrations contaminated later ones that depended on them, creating cascading failures across the entire codebase.
Solution
Structure large codebase migrations as a parallel multi-agent pipeline using OpenHands. First, generate a dependency graph of all files in the codebase: which files import which. Topologically sort the graph so leaf files (no imports from other project files) are migrated first. Assign leaf files to parallel agent sessions; each agent migrates one file independently. After each batch completes, run the test suite and validate. Move up the dependency tree batch by batch. Files with dependencies on already-migrated files are assigned to agents that receive the migrated versions as context. Merge conflicts are nearly eliminated because files are migrated in dependency order: no agent migrates a file whose dependencies are still in the old format. Human review happens at batch boundaries, not at individual file level.
Result
Parallelized 200+ file Angular-to-React migration across agents in dependency-sorted batches. Merge conflicts dropped from ~30/batch (random) to under 2 (ordered). Total time: 2 days vs estimated 3 weeks sequential.