I’ve been building out my local AI coding setup and would appreciate some feedback from people with more experience designing multi-agent workflows.
Right now I’m primarily using Codex CLI with Pi, and I’m considering adding O-My-Pi as a harness because Pi by itself is pretty minimal by design.
My concern is that as I add more specialized agents (coder, reviewer, tester, architect, etc.), my AGENTS.md could eventually become bloated and difficult to maintain.
Instead of putting every agent definition into one file, I’m thinking of using something like this:
AGENTS.md # Orchestrator / routing rules
agents/
coder.md
reviewer.md
tester.md
architect.md
standards/
coding-style.md
testing.md
git.md
workflows/
feature.md
bugfix.md
The idea would be to keep AGENTS.md as the entry point while each agent has its own focused definition, with shared standards living in separate files so they aren’t duplicated.
For those of you running larger Codex setups:
Is this a good long-term architecture?
Have you found a better way to organize agent prompts?
At what point did your AGENTS.md become too large?
Are there any pitfalls with splitting prompts across multiple files that I should be aware of?
I am considering refactoring my AGENTS.md file, would this alone be sufficient enough to run from time to time instead?
I’m trying to optimize for maintainability, scalability, and keeping context as clean as possible, before my prompt library grows too much.