Directing AI Agents Across Thirty-Three Repositories
Thirty-three repositories, and I cannot hold more than two in my head. How one instruction file per repo turns multi-repo agent work into routing, and why I keep refactoring those files.
There are thirty-three repositories in my workspace, and I cannot hold more than two of them in my head at once.
They sit side by side in one folder without being a monorepo. Each is its own independent project with its own stack and history and conventions. A blog built in Astro. Film tooling in Python. A chiptune engine. A few daily-practice command-line tools. Infrastructure. They share an owner and almost nothing else. The Python repo and the Flutter repo would not recognize each other's rules.
The naive way to point an agent at this is to give it the whole workspace and hope, and it does not work.
One big context is the wrong shape
An agent turned loose on all thirty-three repos inherits the union of every project's conventions and belongs to none of them. It writes Python with the Node repo's instincts and uses the wrong deploy script because two of them are named almost the same. It reaches for a path that was real in one project and stale in another. More context did not make it smarter, it made it average across projects that should never be averaged.
The fix is a boundary, one per repository, and less context inside it rather than more.
The instruction file is the unit of work
Each repo carries its own instruction file. It says what this project is, what the stack is, what the conventions are, what is dead, and what bites. The agent reads that file first, and inside that repo it behaves like it has worked there for months. It knows this one uses a virtual environment in one folder and that one uses a different folder, and which deploy needs which flag, and the gotcha that took me a day to find the first time, because I wrote the gotcha down.
Move to the next repo and the agent reads a different file and becomes a different specialist. The workspace root holds almost nothing, just the cross-cutting scripts that manage remotes and sync, and a single note at the top that says, before you touch anything, go into the specific repo and read its file first.
So the orchestration is routing, and no one mind holds everything. The right work goes to the right repo and carries that repo's instruction file as its working memory, and breadth stops costing much once each stream brings its own context with it. I can have a migration running in one repo, a bug in another, and a draft in a third, each scoped so it cannot bleed into the others.
The files are the memory I do not have
Those instruction files are the externalized version of the context I cannot hold. I do not remember which of thirty-three repos puts its virtual environment where, which path went stale in a refactor last spring, which script still points at an old directory. I am not going to pretend I do, the file remembers so I do not have to.
When I get a repo wrong I do not try to remember harder next time. I write the correction into that repo's file, so neither I nor the next agent makes the same mistake again. The files are a system, and like every system I run they leak, so I keep refactoring them, often by pointing an agent at a repo and asking it where its own instructions have drifted out of date with the code. That review is some of the highest-leverage work I do, and it is never finished, because the repos keep moving.
This is the best way I have found so far, which is a different thing from the best way. There are better methods than mine right now, some I have not learned yet and some that do not exist yet, and the meta question of how to work is never closed for long. The instruction-file approach is a stage I am passing through, the way cursor completion was a stage before it. I grow into a method and then outgrow it, and the next one is usually already there when I do. Anything I write down about how I work is a photograph of a stage, and next year I will be doing it differently.
Multi-repo agent work is a context problem more than a scale problem, and the unit that matters is the boundary around what the agent should know. Draw the boundaries well and I can work across thirty-three projects without holding thirty-three projects, and when they are drawn badly the agent is confidently wrong in a different way in every folder. The rest of how I work this way lives at AI-assisted engineering.