Context Monorepos
I spent all day on a “context monorepo” - docs, oss libs, examples, a bunch of repos, context handoffs from a similar project, and important decisions being made about my products.
Composer 2.5 orchestrated most of the structure - which was nice and fast.. GPT-5.5 for anything more involved.
I don’t know how productive this is, but it feels good, and now I’m confident launching agents in here to build across the real monorepos. I’m pretty much a big “memory” hater (the RAG flavor or session scrapers) and admittedly failed at this type of thing in the past.
- I’d rather own my context & don’t like things happening behind the scenes that I have no control over or awareness of. These things are already too much of a black box and I’m trying to engineer real shit.
- But I strayed from this kind of auxiliary context work I was doing heavy last summer. The agents weren’t reliable enough to run alone, and I’d built false confidence that the context setup would carry them. So I handheld them for months. Better long-horizon models, dynamic workflows, and Fable have started shifting things back. I can handhold agents less and focus more on the surrounding context again.
I think this is going to be a thing, and being able to share context monorepos outside GitHub will matter too. The whole repo is an asset. It looks simple, but there’s real mapping and accountability across the AGENTS.md files and symlinked CLAUDE.mds Plus a bunch of management of internal git repos
- I don’t see how Linear or Notion ever become this. They think they are, and maybe they get there if you move your whole workflow onto their platforms. But this is so intimate to the actual engineering process that I think it either needs new infrastructure.
- I don’t think somebody else’s verbose skill framework is gonna get you there either. This is always gonna be dependent on the thing you’re building.
- I 100% don’t think it’s any flavor of current memory solutions. No RAG, no auto learning. There is inherently graph structure in a mapped monorepo, but this does not call for graph databases.
Here’s an example of what a root-level AGENTS.md looks like, generalized to remove proprietary info. This particular product integrates with coding agents through hooks, skills, and MCP, so you’ll see folders for those. Your context monorepo will reflect whatever your product actually touches.
You are in the meta-operating layer of my-product.
# Metaoperational Repo Organization
This directory is the meta-operating layer monorepo.
> **Not a git repo.** This top-level meta layer is intentionally *not* version
> controlled. It is an organizing workspace that *contains* many independent git
> repos (vendored OSS under `research/`, and the actual product repos under
> `projects/`, each with their own `.git` and worktrees). Don't `git init` here.
It organizes the decisions (`decisions/`), the thinking/planning/research (`research/`),
and the building (`projects/`) that produce my-product.
```
my-product/ # meta-operating layer (you are here)
├── AGENTS.md # (this) operating doc: what we're building + how this repo is run
│
├── decisions/ # final architectural decision records
│ └── adrs/ # one file per decision, numbered
│
├── research/ # thinking: notes, specs, oss repos, and investigations feed projects/
│ ├── design/ # product, marketing, design
│ │ ├── positioning/ # commercial wedge, category, copy
│ │ └── ui/ # portal UI patterns, handoffs, visual assets
│ ├── integration/ # how my-product relates to other systems (not full arch copies)
│ │ └── parent-platform/ # platform refs + alignment notes (draft)
│ ├── scratch_docs/ # working architecture drafts
│ ├── frontend/ # portal UI: vendored editors, components, interaction patterns
│ │ └── markdown-editor/ # live-preview markdown editor
│ ├── infra/ # architecture, infrastructure (vendored OSS below)
│ │ ├── cloud-platform/ # runtime docs, distilled skills refs, framework guides
│ │ ├── auth-provider/ # auth/session docs, SDK, example
│ │ ├── web-framework/ # core, middleware, starters, + full docs site (website/)
│ │ ├── orm/ # ORM source monorepo
│ │ └── spikes/ # our spikes at top level; imported/ holds spikes from other projects
│ ├── agents/ # details about how each agent host works (+ MCP/auth specs)
│ ├── cli/
│ │ └── hooks/ # per-agent hooks/plugins docs + sync script (see AGENTS.md)
│ └── skills/ # Agent Skills format, CLI, examples, authoring (vendored repos)
│ ├── skill-spec/ # open skill spec + docs
│ ├── skills-cli/ # skills CLI + ecosystem
│ ├── scaffold-skill/ # meta-skill for writing/packaging skills
│ ├── example-skills/ # production skill examples
│ └── skills-knowledge-transfer.md
│
└── projects/ # building: actual shippable codebases (one dir per repo)
├── my-product/ # the core system
│ └── worktrees/ # git worktrees, one branch per dir
│ └── main/
└── my-product-cli/ # the CLI that drives the core system
└── worktrees/
└── main/
```
## Key reference paths
Vendored OSS docs/source for the stack in `research/scratch_docs/draft_arch.md`.
All paths are relative to repo root.
- **Architectural decision records:** `decisions/adrs/`
- **Web framework RPC (typed client):** `research/infra/web-framework/website/docs/guides/rpc.md`
- **Web framework full docs site:** `research/infra/web-framework/website/docs/` (guides, helpers, validation, testing)
- **Web framework core + middleware source:** `research/infra/web-framework/core/`, `research/infra/web-framework/middleware/`
- **ORM source + DB driver:** `research/infra/orm/`
- **Cloud platform DB docs:** `research/infra/cloud-platform/db_docs/`
- **Cloud platform cache API:** `research/infra/cloud-platform/workers_docs/runtime-apis/cache/index.md`
- **Cloud platform distilled skills:** `research/infra/cloud-platform/skills/references/`
- **Auth provider docs / SDK:** `research/infra/auth-provider/docs/`, `research/infra/auth-provider/sdk/`
- **Agent/MCP auth:** `research/agents/remote-mcp-auth/`, `research/agents/agentic-auth/`
- **Agent hooks / plugins (10 hosts):** `research/cli/hooks/` — URL map, `sync_hooks_docs.py`, captured docs in `captured/`; re-vet periodically
- **Imported platform spikes (not ours):** `research/infra/spikes/imported/` — see `research/infra/spikes/AGENTS.md`
- **Portal markdown editor:** `research/frontend/markdown-editor/`; see `research/frontend/AGENTS.md`
- **Agent Skills (format + tooling):** `research/skills/` — spec, CLI, authoring, examples; see `research/skills/AGENTS.md`
- **Commercial positioning:** `research/design/positioning/`
- **Platform integration:** `research/integration/parent-platform/` — `REFERENCES.md` (canonical docs elsewhere), `alignment-notes.md` (draft); see `research/integration/AGENTS.md`
- **Standalone architecture (draft):** `research/scratch_docs/draft_arch.md`
> Gaps not yet vendored: **ORM narrative docs** (hosted on their docs site, not in this repo).