Legacy codebase modernisation
Understand the seams before you start cutting along them
A migration of a service nobody fully remembers — a framework upgrade, a module split, a runtime change — cut into reviewable steps that each land as real files and are checked by someone other than the author.
What actually goes wrong today
Stated plainly, because the approach below only makes sense as an answer to something specific.
- 01
The code carries years of decisions that were never written down, so the first job is not changing it, it is finding out what "it" currently is. That is unbounded reading.
- 02
One long chat session cannot hold the whole surface. It re-reads the same files, forgets the constraint it found four turns ago, and then proposes a migration along a seam that does not exist.
- 03
A flat swarm of agents given the same migration task produces a lot of expensive prose and several incompatible plans, because nothing in it is responsible for deciding.
- 04
Mechanical migration scripts do exist for the well-trodden paths, but most real migrations are 80% mechanical and 20% "this module reaches into that one and nobody knows why".
How the hierarchy and the router do it
Concretely, stage by stage: which mode the stage uses, who owns it, and why the router prices it the way it does.
- 01
The CEO sizes the brief first, on a nano model, and decides how much company it deserves. A migration gets a research stage rather than a one-shot answer.
- 02
Specialists read the actual files with read_file, list_dir and search_files, all confined to the run workspace, and each one records what it found rather than what it assumes.
- 03
A debate stage gives the competing seams names. Two positions are argued over N rounds, then the chair rules and records the decision — including the position that lost and why, which is the part a single agent always drops.
- 04
The CTO turns the surviving position into a file-level plan: which files change, in what order, and what would falsify the approach. A frontier model earns its price here because a wrong plan is the expensive mistake.
- 05
Developer agents write real files into the workspace, one bounded step at a time. The review-loop stage has QA critique the result and, if the verdict objects, sends work back to the employees who actually wrote the files, up to a hard iteration cap.
- 06
Cost-aware routing keeps the reading honest: research is summarisation and belongs on a cheap tier band, while the plan and the revision passes escalate. The run budget is a hard ceiling, not a warning.
What you actually end up with
Artifacts, not assurances. Every one of these is something you can open, diff, review or throw away.
A migration written as a sequence of changes that exist on disk, with the reasoning attached to each step, rather than a design document that has to be re-derived before anyone can act on it.
The debate record is the useful artifact six months later: it names the seam that was chosen, the one that was rejected, and what evidence decided it.
Spend per run is bounded and attributable, and every route decision is recorded per turn, so "why did this cost $4" has an answer.
Which part of the company is involved
Six of the thirteen roles, four of the eight departments. The rest of the office stays idle, and that is what keeps the run affordable.
Sizes the brief on a nano model and picks the pipeline. On a migration it chooses reading before writing.
Reads the real surface area with the confined read tools, in parallel, each with its own knowledge snapshot.
Contested seams get positions, rebuttals over N rounds, and a recorded ruling that names the losing option.
The file-level plan. This is the turn where a frontier model earns its price, and where the band is set highest.
Writes real files into the run workspace, one bounded step at a time, up to eight tool round trips per turn.
Reviewers critique in parallel; if the verdict objects, the developers who wrote the files revise — up to a hard cap.
Modes used
Intake runs single, research runs parallel, contested decisions run as a debate, and anything that produces files ends in a review-loop.
Where the money goes
Reading and summarising sit on cheap bands. The plan, the implementation turns and the review escalate, because those are the turns where being wrong is the expensive mistake.
What is recorded
Per-turn cost, the route decision and the models the router rejected, the files touched, and the debate ruling including the position that lost.
Two other jobs in the same shape
A feature in a service nobody on the team owns
Add the endpoint without first reading the whole service
Land a feature in a codebase you have not worked in — where the real risk is not writing the code, it is putting it in the wrong layer and inventing an abstraction that does not match the house style.
Read itTechnical documentation that is generated from the repository
Write docs against files that exist, on the turn they are read
Produce and refresh reference documentation — module maps, API surfaces, decision records — from the source itself, with the generated pages landing as markdown in a workspace you review before it merges.
Read itRun this in mock mode first
Node 24, one install, no API keys. The pipeline, the stages, the file writes and the review loop all run against scripted employees, so you can watch the shape of the work before it costs anything.
Nothing in the orchestrator authenticates, so bind it to localhost. The tools are confined to the run workspace, but that workspace is a normal directory on the machine and the orchestrator is not inside an operating-system sandbox — give it a checkout you would be willing to lose.