The approach of having everything next to the code seems good in theory but it's just a nightmare in practice for big projects.
Imagine your git history filled with commits from project managers where every little change in requirements and docs has its own commit.
We've tried that and ended up having to rebase our branches multiple times a day while we lost the overview of code changes completely.
The main issue that code can live in multiple branches while development but you can't apply that to docs and requirements where you need to have one centralized source of truth for everyone.
I think we will start to see more adaptation from collaboration tools to provide/accept the info in text format making it suitable for agents as a working solution. Meanwhile, I've seen that having two repos (One for Code and one for docs) is the best solution for the current tools available
The issue you describe seems to be related to the tools you're using and how you use them, not to the core idea itself.
I've worked in several gamedev companies where everything was in a Perforce repository. In fact in one company EVERYTHING was in it, not just code and game data, but also documents, concept art, plans, everything. If it wasn't in P4, it didn't exist.
Yet nobody thought it was a pain (after learning to use P4V at least :-P but that's a different topic) because P4 a) can handle big files just fine and b) you don't really care about the history of the entire repository, but only about the part you're working on. For example personally i had my history tab display just the engine's code directory (and even then i rarely checked it since i don't really care what Joe working on the animation code did, my main interest was on the stuff i worked - and P4V showed me both if someone else is working on the same files i am and if my files have been modified, with easy GUI tools to see both diffs and the file's development history visually - the timeline feature is honestly great for that).
Perforce has some fundamental issues in how it works that creates problems, probably because of some deeply ingrained assumptions stemming from the 90s when it was first made that were never addressed, but it also has a lot of features (especially on the P4V GUI client) that makes working on a huge monolithic repository where everything goes in pretty much seamless.
Sure, it would be better if you get the right tools for it and teach people how to use it.
At the end Google was able to get all of their source code in one mono git repository and it worked for them but they invest really heavily in their unique tooling.
However, I still think it would be much simpler to extend the tooling for current project management platform to give AI agents the text-based user interface that they needed. This would be much simpler task than developing the tooling for huge repo to include all the chaos of humans communications alongside the code itself.
“ every little change in requirements and docs has its own commit”
I think this would be a great thing to have and know who changed what and when. It seems it’s more of a problem of the tools being able to help the user see only what he needs to see in a certain context.
It's a great thing if those changes live in their own repo and not mixed with changes to the code itself. Actually Jira has been doing that for a while now by offering the history view with a timeline for each change, also GitHub shows edit version for files as well.
The main role for projects management is handle the chaotic way of humans communication across different organization without developer being involved in that messy cycle.
But having everything in the same repo will remove this decoupling and will let developers get involved in that chaos as it's part of the repo history.
Maybe what I'm saying is stupid or malinformed, but why not having the doc as a separate repo, and set it as a submodule to the repo where the code lives? Agent should be able to push code to the submodule independently from the code, and it should not be problematic for the main repository
I think this would a greatoption.
Projects can start with two repos; one for code and one for docs. Then it would possible for code repo to add the docs one as submodule at anytime.
Actually I would suggest that to one of the projects that I'm currently involved in
Imagine your git history filled with commits from project managers where every little change in requirements and docs has its own commit. We've tried that and ended up having to rebase our branches multiple times a day while we lost the overview of code changes completely.
The main issue that code can live in multiple branches while development but you can't apply that to docs and requirements where you need to have one centralized source of truth for everyone.
I think we will start to see more adaptation from collaboration tools to provide/accept the info in text format making it suitable for agents as a working solution. Meanwhile, I've seen that having two repos (One for Code and one for docs) is the best solution for the current tools available