Holorepo

In practice a holorepo is an ordinary repository on GitHub, or any Git host, with folders for documents next to the folders for code. A product manager’s spec, a researcher’s interview notes, and an engineer’s code are files in the same place. They share one history, and a change to any of them goes through the same review.

A monorepo is about how code is divided: one repository or many. A holorepo is about what counts as part of the product: the spec that explains a feature, the research that led to it, and the doc that teaches it belong with the code that builds it. A company can have one monorepo that is also a holorepo, or five products with a holorepo each.

Many repositories, a monorepo and a holorepo compared

	Many repositories	Monorepo	Holorepo
What one repository holds	The code for one app, service, or library	The code for many projects, often all of a company’s	One product’s code and what the team has written about it
Where plans, research, and docs live	Usually in other tools	Usually in other tools	In the repository, next to the code
Who writes in it	Engineers	Engineers	Everyone who works on the product

Most teams keep the code in a repository and everything else somewhere else: specs in a docs app, decisions in a wiki, research in slides, plans in a spreadsheet. Each of those tools works. The problems below come from the product being split across them.

1. The spec and the product drift apart

   A product manager writes a spec in a docs app. During code review an engineer finds a problem and the team agrees to build it differently. That conversation happens in the pull request, where the spec isn’t, so nobody changes the spec. Three months later someone in support reads it to answer a customer, and tells them something the product doesn’t do.

2. Research gets done twice, or not at all

   A researcher interviews twelve customers and presents what they learned in slides. The slides go in a shared drive. A year later a different person picks up the same feature, has never seen that folder, and either repeats the interviews or builds without them.

3. Understanding one feature means opening five tools

   The code is in GitHub, the spec is in a docs app, the decision is in a wiki, the research is in slides, and the help article is in a help center. Each has its own search box and its own list of who can see it. A new teammate asks for access five times, and then has to work out which of two documents with the same title is the current one.

   Without a holorepo: five searches

   • Docs appphone numberCheckout spec last edited in March
   • Slidesphone numberCheckout interviews you need to ask for access
   • Wikiphone numberCheckout decisions two pages have this title
   • Help centerphone numberPaying for an order
   • GitHubphone numbercheckout/form.tsx

   In a holorepo: one search

   • GitHubphone number

   • specs/checkout.md
   • research/2026-11-checkout-interviews.md
   • design/0042-ask-for-a-phone-number.md
   • docs/help/paying-for-an-order.md
   • apps/web/checkout/form.tsx

4. An agent sees the code and none of the reasons

   You ask an agent to add a feature. It reads the repository, so it learns how the code works. It doesn’t see the spec, the research that set the requirements, or the decision record that ruled out the obvious approach, because those are in other tools. So it builds the obvious approach.

5. You can’t see what was true when

   Each tool keeps its own history. To find out what the plan said in the week a decision was made, you compare a doc’s version history, a wiki page’s history, and the dates on the commits, and hope they line up. Nothing ties the change in the plan to the change in the code.

The same five problems, in a holorepo

Without a holorepo	In a holorepo
The spec is in another tool and drifts from the code	The spec is a file next to the code, and one pull request changes both
Research sits in slides nobody opens	Research write-ups are files in the repository, found by the same search as the code
Five tools, five searches, five access lists	One repository, one search, one access list
An agent reads only the code	An agent reads the spec, the research, and the decisions too
Every tool has its own history	One history, in order, for the code and everything written about it

You don’t need to move everything at once. Add a few folders to the repository your code is already in, and move each document in the next time you change it.

1. Start in the repository your product’s code is already in. Don’t create a new one. The point is that documents sit next to the code.

2. Add a few top-level folders. One for each kind of document your team already writes. Keep the names short and obvious.

   acme

   • README.mdwhere everything is
   • apps/the product’s code
   • packages/code the apps share
   • specs/what each feature should do, and why
   • research/interview write-ups and survey results
   • design/design docs and records of decisions
   • docs/help docs, technical docs, release notes
   • plans/roadmaps and launch plans

3. Write in Markdown, one document to a file. Markdown is plain text with light formatting, and GitHub shows it as a formatted page. Name files so they sort and say what they are, such as 2026-11-checkout-interviews.md.

4. Put a README in every folder. It says what the folder is for and links to the documents that matter most. This is what a new teammate reads first.

5. Move documents in when you next change them. Start with specs, because engineers already read them, and leave a link behind in the old tool.

6. Change documents the way you change code. Open a pull request, ask someone to review it, and merge it. When a change to the code changes what a spec or a help doc says, put both in the same pull request.

   Pull request

   Ask for a phone number at checkout

   • apps/web/checkout/form.tsx+18 −2
   • specs/checkout.md+6 −3
   • docs/help/paying-for-an-order.md+4 −1

7. Say who reviews what. A CODEOWNERS file in the repository names who is asked to review a pull request that changes each folder, so the research lead is asked about changes to research/ and a designer about changes to design/. On a private repository this needs a paid GitHub plan.

8. Give everyone a way to write. Add each writer to the repository on GitHub. An agent can then make the change for them: it edits the file, commits it, and opens the pull request. That still doesn’t put two people in the same document at once, which is the first of the trade-offs.

What stays out

Large files like video and raw recordings make a repository slow to copy, so keep them somewhere else and link to them. Passwords and keys never go in a repository. Customer research often holds personal details, so take out names and contact details before the notes go in, or keep the raw notes in a separate private repository and put the write-up in the holorepo.

Three habits that keep it working

• Write decisions down in the repository. A decision made in a meeting or a chat thread gets a short record in design/ the same day.
• Link to a document instead of pasting from it. A pull request links to the spec it implements. A spec links to the research behind it.
• Delete what’s no longer true. The history keeps every old version, so the folder only needs to hold what is current.

A repository was built for code, so documents in one behave differently from documents in a docs app. These are the four differences people run into, and what helps with each.

Git doesn’t sync as you type

The commands are no longer the hard part. Agents such as Claude Code, Cursor, and ChatGPT can run Git for you once they’re connected to the repository: you say what to change, and the agent edits the file, commits it, and opens the pull request.

What hasn’t changed is that everyone works on their own copy. You don’t see a teammate’s change until they push it and you pull it. If two people change the same paragraph of a spec on the same afternoon, the second one to finish has a conflict to settle. An agent can run the merge or the rebase, but a person still has to decide whose wording stays. In a docs app both of them would have been typing in the same document and watching each other do it.

What helps: keep pull requests small and merge them the same day. When a document needs several people at once, use an editor that puts them in the same document live and saves the result to GitHub.

Comments belong to a pull request

In a docs app you select a sentence and comment on it, and the comment stays with the document. GitHub’s comments are made for changes: you comment inside a pull request, on the files it changes. To raise something about a document nobody is changing, you open an issue or a pull request first. And when a pull request merges, its conversation stays with the pull request, not with the document.

What helps: ask the question in an issue that links to the document, and write the answer into the document itself.

Access is set for the whole repository

GitHub decides who can read a repository as a whole, not folder by folder. Everyone who can see the code can see the research, and the other way around. Everyone who writes also needs a GitHub account with access to the repository, and people outside engineering often don’t have one yet.

What helps: add the whole team to GitHub before you move their documents, and put documents that need a smaller audience in a second, private repository. On a paid GitHub plan each person you add is another seat.

Markdown does less than a docs app

Markdown covers headings, lists, links, tables, images, and code blocks. It has no page layout, a wide table is awkward to edit as plain text, and a slide deck or a spreadsheet loses its layout, charts, and formulas when it’s turned into Markdown.

What helps: write up what the deck or the spreadsheet shows in a Markdown file, and link to the original. A small table of data can go in as a CSV file, which GitHub shows as a table.