Directing AI Agents Across Thirty-Three Repositories

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, but it is not a monorepo. Each is its own independent project with its own stack, its own history, its own 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. It does not work, and the reason it does not work is instructive.

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. It 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 the opposite of more context. It is a boundary, one per repository.

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. It knows which deploy needs which flag. It knows 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 not one large mind holding everything. It is routing. The right work, scoped to the right repo, carrying that repo's instruction file as its working memory. Breadth stops being expensive the moment 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

Here is the honest part. Those instruction files are the externalized version of the context I genuinely 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.

That changes what being wrong about a repo means. When I get one wrong, the fix is not to try to remember harder next time. It is to 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.

I should also say plainly that this is not the best way to do this. It is the best way I have found so far, which is a different thing. 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. You grow into a method and then you outgrow it, and the next one is usually already there when you do. Anything I write down about how I work is a photograph of a stage and not a destination, and the part I am most sure of is that next year I will be doing it differently.

The whole thing comes down to one idea. Multi-repo agent work is not a scale problem, it is a context problem, and the unit is not the agent, it is the boundary you draw around what it should know. Draw the boundaries well and you can work across thirty-three projects without holding thirty-three projects. Draw them badly and 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.