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.
The tell is reproducible failure. A second engineer cannot get the same agent behaviour on a second machine. A model upgrade changes diffs and nobody can point at the file that allowed it. A tool can mail a customer and the only record is a vendor dashboard that expires. Demo quality is not repo quality.
What is STACK? is the definition of the five names. This page is the install: treat the agent OS as code.
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.
Name an owner per layer. One human, not a role. A role is how the file becomes folklore again the week that person is on leave. CODEOWNERS is enough. A wiki page is not.
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.
A practical cut. Structure is a single directory, for example agent-os/, with a README that is a map, not an essay. Toolchain is a lockfile plus a documented command list the CI image also has. Agent configuration is the standing files a host actually reads, with a CODEOWNERS line, not a second copy in a chat. Connection is a contract per server: what it may see, what it may change, how the call is logged. Knowledge and quality is at least one eval or test that fails when the agent touches a forbidden path.
Rollback is the part teams skip. If you cannot revert a prompt the way you revert a function, you did not version it. You published it. Git is the version control. A Notion page with “latest” in the title is not.
What to refuse
Three common installs that still leave the debt in place.
A host with “memory” turned on and no file in the repo. The standing context now lives in a vendor. When the seat expires, the OS expires.
Five copies of the same rule, kept “in sync” by hand. They will drift. Pick one file. Delete the rest in the same PR.
An MCP server added because a demo needed a tool, with the contract to be written later. Later is how the billing module gets a comment bot. MCP explained for founders is the connection-layer companion. Read that before you attach a server that can mail a customer.
A Monday you can actually run
- List every file an agent reads on a cold start. If the list is longer than one tree, you found Structure debt.
- Run the agent in CI, not only on a laptop. If CI cannot run it, Toolchain is a story.
- Put a human name next to every standing prompt and skill. Empty name means the file is unowned. Unowned files do not merge.
- For every MCP server, write visibility, mutation, log in three lines. Missing mutation means it does not ship.
- Add one test that fails if the agent edits a path it should not touch. That is the start of Knowledge and quality, not the end.
You will not finish the OS on Monday. You will end folklore at the first owner.
Where this sits
The Agentic Codebase is the book. The introduction is the launch article. What is STACK? is the definition. This page is the architecture you install when the demo worked and the repo did not.
A CHORUS charter will not save a repo whose rules live in five tools. STACK versions the files. CHORUS names the coordination those files cannot do alone.
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.