specgit guides
What is a holorepo?
Published · the specgit team
A holorepo is one repository that holds a whole product: its code, and what the team knows about it, such as plans, specs, customer research, design docs, and help docs. A monorepo puts the code for many projects in one repository. A holorepo puts everything about one product in one repository, the code and the rest.
In practice it's a repository on GitHub with folders named research, specs, design, and docs next to the folders that hold the 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 can be reviewed before it's published.
specgit coined the word in November 2026. "Holo" comes from the Greek word for whole. Teams have had a name for "all the code in one place" for years and no name for "the whole product in one place," so we gave it one.
How is a holorepo different from a monorepo?
Many teams keep many repositories: one for each app, service, or library. A monorepo puts all of that code in one repository, so a change that touches three projects is one change. Both are answers to the same question, which is how to divide code.
A holorepo answers a different question: what counts as part of the product. It says the spec that explains a feature, the research that led to it, and the doc that teaches it belong in the repository with the code that builds it.
The two don't compete. A company can have one monorepo that is also a holorepo, or five products with a holorepo each.
| 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 |
| The question it answers | Should our code be in one repository or many? | Should our code be in one repository or many? | Should our plans, research, and docs live with the code? |
| 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 |
What does a holorepo look like?
Here is one way to lay it out. The folder names are up to you, as long as each kind of document has one obvious home.
specgit's own repository is a holorepo, with its own folder names. It holds the app's code next to its design docs, its backlog, its runbooks, and its marketing copy.
| Folder | What's in it | Who writes there |
|---|---|---|
| apps, packages | The product's code | Engineers |
| specs | What each feature should do, and why | Product managers and engineers |
| research | Interview write-ups, survey results, and what you learned from them | Researchers and product managers |
| design | Design docs and records of decisions | Designers and engineers |
| docs | Help docs, technical docs, and release notes | Writers, support, and engineers |
| plans | Roadmaps and launch plans | Product and marketing |
What goes in a holorepo?
Anything the team writes down about the product that someone will need again:
- Plans and roadmaps
- Product specs
- Customer research: interview notes, survey results, the write-up of what you learned
- Design docs and records of decisions
- Technical docs
- Help docs and release notes
- Launch plans and the copy for them
What stays out of a holorepo?
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.
Why keep everything in one repository?
Because the pieces change together. When a feature changes, its spec, its docs, and its code all change. If they're in the same repository, one review can cover all three, and nobody has to remember to update a doc in a different tool next week.
There is one history for the whole product. Every change to a spec or a research note is recorded with who made it and when, the same way a change to the code is. You can see what the plan said on the day a decision was made.
Agents can read it. Teams now ask an agent to read what's been written about a feature before it helps build one. An agent working in a repository reads the files in it. Plans and research that are in the repository are part of what it starts from. Plans kept in another tool are not, unless someone connects that tool.
And the files stay yours. They're plain text in a repository your team owns, so they outlive any one tool.
What does a holorepo cost you?
The biggest cost is how Git moves changes. Git doesn't sync by itself. You pull to get other people's changes and push to send yours, and when two people changed the same file, someone has to combine the two versions, which Git calls a merge or a rebase. Engineers work this way every day. A product manager writing a spec or a researcher writing up interviews expects what a shared doc gives them: open it, type, and see a teammate's changes as they happen.
Access is set for the whole repository. GitHub decides who can read a repository as a whole, not folder by folder, so everyone who can see the code can see the research, and the other way around. For most product teams that's the point. Documents that need a smaller audience go in a second, private repository.
Finding things takes more care. A repository shows you files and folders, not a table of contents, so clear folder names and a README at the top that says where things are do the job a wiki's home page would.
How does a whole team write in a holorepo?
There are three ways today. GitHub's website lets anyone with write access edit a file in the browser as plain text. When they save, it asks for a description of the change and for a branch, which is a separate line of work, to save it on. Some teams have an engineer, or an agent, add what other people write to the repository. Or the team uses an editor made for this.
specgit is that kind of editor. You write in a visual editor in your browser, with comments and live editing, and specgit turns saving, commenting, and publishing into what GitHub expects, via commits, review threads, and merges. If your notes are in an Obsidian vault that's saved in GitHub, your teammates can open the same notes in specgit. GitHub remains the source of truth, and specgit never keeps a copy of your documents or comments.
How do you start one?
- Pick the repository your product's code is already in.
- Add a folder for one kind of document. Specs are a good first choice, because engineers already read them.
- Move those documents in as Markdown files (plain text with light formatting, the format GitHub and Obsidian both read).
- Give the people who write them an editor that saves to GitHub for them.
- Add the next kind of document when the first one is working.
Frequently asked questions
Is a holorepo the same as a monorepo?
No. A monorepo holds the code for many projects in one repository. A holorepo holds one product's code together with the plans, specs, research, and docs about it. A repository can be both.
Who came up with the word holorepo?
specgit did, in November 2026. "Holo" is from the Greek for whole.
How do you write and say holorepo?
One word, lowercase: holorepo. Say it like hologram and repo.
Does a holorepo have to be on GitHub?
No. The idea works in any Git repository. specgit works with repositories on GitHub.
Is a holorepo the same as docs as code?
They're related. Docs as code is a way of writing docs: in plain text, kept in a repository, changed through review. A holorepo is where things live: one product's code and everything written about it, in the same repository.
Can a holorepo replace a wiki?
For what the team writes about the product, yes. Specs, research, design docs, and help docs can all live in it. Writing that isn't about one product, like a company handbook, goes in a repository of its own.
Can people who don't use Git work in a holorepo?
Yes, with an editor that saves to GitHub for them. specgit lets them write, comment, and publish in a browser, and it does the commits and merges.
What shouldn't go in a holorepo?
Large media files, passwords and keys, and personal details from customer research. Link to the first, never store the second, and remove the third before the notes go in.
Write in your holorepo with your whole team
Edit the plans, specs, and research in your repository in a visual editor, with live editing, comments, and review. specgit saves your work to GitHub, and GitHub remains the source of truth.
By continuing, you agree to the Terms of Use and acknowledge the Privacy Policy. Analytics choices are separate.
See plans & pricingFree to start, no credit card. Zero Content Retention: we never keep a copy.