Tom Hundley
🤖 Ghostwritten by Claude Opus 4.6 · Fact-checked & edited by GPT 5.4
A monorepo rebuild only pays off if it reduces operational complexity on day one and remains understandable on day ninety. In this case, the most important decision is not the repo toolchain or folder layout. It is naming. Using business-aligned names such as ess-agents/blog-writer/ for code and infrastructure makes deployment, debugging, and onboarding clearer than codename-first paths. Codenames can still exist as a human-facing layer, but they should not be the primary organizing principle for infrastructure.
That distinction matters even more in a multi-machine setup. When services, configs, and documentation all use names that map directly to business functions, new contributors spend less time decoding terminology and more time shipping work. The trade-off is reduced portability if the system is later repackaged or open-sourced. For an internal monorepo, that is often acceptable.
This article reviews the first-day architecture choices behind the rebuild, where file-based coordination helps, where it breaks down, and which claims about the broader agent ecosystem need more caution.
TL;DR: Codename-first structures often add avoidable translation overhead; business-aligned naming usually improves clarity in deployment, debugging, and onboarding.
The previous structure used internal codenames as the organizing principle for directories, service names, database schemas, and DNS entries. That can work for a small system. It becomes harder to maintain as the number of services, machines, and contributors grows.
Three practical problems tend to force a rebuild:
ess-agents/blog-writer/ communicates purpose more clearly than a codename-heavy path.The codenames can still be useful as a presentation layer. A public-facing or conversational identity can coexist with a business-aligned filesystem. The key point is that labels for people and paths for systems do not need to be the same.
TL;DR: ADRs, session notes, and journals in the repo can preserve decision history well, but they work best for asynchronous coordination rather than real-time orchestration.
Every non-trivial decision can live in /docs/decisions/ as an ADR. That is a well-established software architecture pattern, and it fits a monorepo well because the decision record sits next to the code it affects.
Example structure:
/docs/decisions/
001-monorepo-business-names.md002-file-based-session-continuity.mdA useful ADR format includes context, decision, consequences, and status. The consequences section matters because it forces the author to document trade-offs rather than presenting every decision as a pure win.
Session notes in /docs/sessions/ can capture what was attempted, what shipped, what failed, and what should happen next. That makes them especially useful for asynchronous work across multiple AI sessions or human contributors.
A simple format is enough:
# Session: 2026-05-03 — Monorepo Bootstrap
## Goals
- Initialize monorepo structure
- Create first ADR
- Configure blog-writer agent scaffold
## Completed
- [list of what shipped]
## Blocked
- [list of blockers with context]
## Next Session Should
- [specific, actionable items]Journal entries in /docs/journal/ are the narrative layer. They are less structured than ADRs and less task-oriented than session notes. Used well, they capture why a week of work felt consequential, not just what changed.
The main limitation of this file-based approach is coordination speed. It is excellent for inspectability and historical context. It is weaker for low-latency state sharing, locking, and event-driven workflows.
TL;DR: Specialized multi-agent tooling is maturing, but claims about specific 2026 product launches and features need careful sourcing; the broader comparison is directionally sound.
A useful way to frame the design is by coordination model rather than brand names alone:
| Approach | Coordination Model | Typical Deployment Target | Agent Autonomy |
|---|---|---|---|
| Framework-managed multi-agent systems | Task graphs or supervisor routing | Usually cloud or hybrid | Medium |
| Pipeline-oriented orchestration | Event-driven stages | Cloud or hybrid | Medium |
| Centralized supervisor patterns | One controller delegating to specialists | Hosted or API-centric environments | Low to medium |
| File-based coordination in a monorepo | ADRs, notes, and git-based handoff | Local, hybrid, or self-hosted | Medium to high |
The broader industry trend is real: teams are increasingly breaking large agent workflows into smaller specialized components. What is less certain here are the product-specific claims. References to named offerings such as a 2026 "AMP" launch or an "OpenAI Harness" product require direct sourcing before publication. Without that sourcing, the safer editorial move is to describe the pattern rather than assert a specific release.
The file-based approach diverges from many framework-led systems in two ways:
That trade-off is real. Dedicated machines can offer stable local state and predictable baseline performance. Cloud systems, by contrast, usually win on elasticity, managed observability, and easier failover.
TL;DR: Systems that document themselves need hard publication boundaries, because even sanitized architecture writing can reveal too much about internal topology.
When an agent writes about the system it belongs to, accuracy and exposure rise together. The same context that improves technical writing can also leak implementation details that should remain private.
The mitigation should be structural, not just prompt-based:
The deeper risk is not only credential leakage. It is architectural inference. A careful reader can combine small details about coordination, storage, authentication, and deployment into a useful model of the system. That is why public technical writing should describe principles and trade-offs while withholding sensitive topology.
TL;DR: File-based coordination can work across multiple machines, but git contention, stale state, and limited real-time observability become operational constraints.
The immediate scaling risks are practical rather than theoretical:
The original draft mentioned Prometheus as a likely next step. That is a reasonable example, but it should be framed as one option rather than a requirement. Any lightweight metrics and alerting stack could fill that role.
A more subtle scaling issue is context load. As ADRs, notes, and journals accumulate, the challenge shifts from storing history to retrieving the right slice of history for the current task. That is where indexing, summarization, and document lifecycle policies become more important than raw compute.
A monorepo keeps shared configuration, decision records, and handoff notes in one place. That reduces context fragmentation and makes cross-agent changes easier to review. Separate repos can still make sense when teams, release cycles, or security boundaries differ sharply.
ADRs record why a decision was made, what alternatives were considered, and which trade-offs were accepted. Regular documentation usually explains the current state of the system. Both matter, but ADRs are better at preventing teams from repeatedly reopening settled decisions.
Yes, for asynchronous work. It is less effective for workflows that need real-time coordination, locking, or event streaming. In practice, many teams end up combining file-based history with a separate runtime coordination layer.
The biggest risk is architectural inference. Even if secrets are removed, public descriptions can still reveal enough about system shape and dependencies to help an attacker reason about likely weak points.
Dedicated machines can be attractive when workloads are steady, local state matters, and operators want direct control over the environment. Cloud infrastructure is usually better when elasticity, managed services, and rapid failover matter more than hardware ownership.
The strongest idea in this rebuild is not the monorepo itself. It is the decision to make the system legible. Business-aligned naming, ADRs, and structured session notes all push in that direction.
The open question is whether that legibility survives scale. As the number of machines, commits, and documents grows, the bottleneck becomes context selection: deciding what a given session needs to read now. That is the part worth watching, because a self-documenting system only stays useful if its documentation remains navigable.
Discover more content: