Agents demo beautifully. Then the repository starts to smell. Prompts in four files. The same rule in a README, a host config, and someone’s head. An MCP server nobody listed. That smell has a name: agentic repo debt.
The disease
A weak model is rarely the cause. The cause is an agent operating system that is not an operating system. It is a pile.
You would not ship application code that way. You version the app. You review the app. You know who owns a package. The agent half of the repo deserves the same disrespect for folklore.
Five layers
STACK is the map I use:
- Structure — where agent artifacts live, and nowhere else.
- Toolchain — the hosts and runners, pinned, not “whatever the laptop has.”
- Agent configuration — charters, prompts, skills, with owners.
- Connection — MCP and other tool contracts. Visibility, mutation, log.
- Knowledge and quality — what the agent may treat as true, and the tests that fail a bad change.
If a change cannot be named as a layer, it does not belong in the PR description. “Tweaked the agent” is not a commit message.
Version it
Treat prompts, skills, and server contracts as code.
- They live in the repo.
- They have reviewers.
- They have a rollback.
- The override doctrine is a file, not a Slack memory.
When a tool can send, spend, or delete, the first ten calls have a human name next to them. After that, the log is the review. No log, no tool.
Where this sits
The Agentic Codebase is the book. The introduction is the launch article. This page is the architecture you install when the demo worked and the repo did not.
MCP explained for founders is the connection-layer companion. Read that before you attach a server that can mail a customer.
If you do one thing this week: pick a single directory as the agent OS, move the stray prompts into it, and put a name on the CODEOWNERS line. Folklore ends at the first owner.