# Why I split my agent OS into 5 layers

I'm building a personal agent OS on top of Hermes + Claude Code + Codex + the harnesses I've collected. I needed clarity on where each piece lives. The mental model that worked:

| Layer | What | Visibility | Frequency of change |
|---|---|---|---|
| 1 — Foundations | Hermes, Claude Code, Codex (vendor) | n/a | upstream-driven |
| 2 — Personal extensions | Plugins, skills, hooks I write | public | medium |
| 3 — Knowledge garden | Notes, tutorials, recipes (this repo) | public | high |
| 4 — Proprietary | Trading bots, client work, credentials | **private** | high |
| 5 — Presentation | Hub site, blog, landing | public | low |

## The decision rule

> A thing's **frequency of change** + **who else can see it** = which layer it belongs in.

If I can answer those two questions, the location is automatic. No more "should this go in the Hermes repo or somewhere else?" debates.

## Why not a monorepo

Tempting — one place for everything. But:

- Layer 1 (vendor) wants `git pull` to be a no-op for me
- Layer 3 (notes) wants frequent low-pressure commits
- Layer 4 (proprietary) wants to be private
- Layer 5 (site) wants its own deploy pipeline

These all change at different rates with different audiences. Bundling creates friction at every layer boundary.

## Why not a fork of Hermes

Same reason. Forks invite drift. Every upstream pull becomes a rebase. The right move is to keep the Hermes clone pristine and put everything in `~/.hermes/plugins/<name>/` — separate repos, no upstream contact.

## What this unlocks

- **`git pull` on the Hermes clone always fast-forwards.** No conflicts, ever.
- **Each plugin can be shared / unshared / archived independently.** No coupling.
- **A future developer can audit my agent OS** by reading the layer assignment, not by spelunking through one giant repo.
- **The hub site (Layer 5)** becomes the discovery layer for everything else — auto-indexes Layer 2 + 3 from GitHub topics.

## Related

- See `patterns/plugin-architecture.md` for how Layer 2 plugins compose.
- See `recipes/zero-conflict-upstream-pulls.md` for the git workflow.