The Agentic Codebase

Every chapter of The Agentic Codebase with its printed epigraph, what you can do afterwards, and the moment it is built for.

1. Introduction

   Introduction: The Repo Is the Agent OS

   A demo proves the model can do the work. A repository proves the work can be done again. The gap between those two sentences is the subject of this book.

   What you can do afterwards

   You will understand why agentic systems fail in repositories rather than in models. You will name the disease, agentic repo debt, and leave with STACK: the five-layer map every agentic codebase must get right.

   Use this chapter when

   A demo wins the room but a new hire cannot reproduce it; rules and prompts live in chat history; "ask the person who knows the setup" is your onboarding plan.

2. Chapter 1

   The Agentic Repo Problem

   Nothing crashed. That was the problem. The same agent that dazzled the room in its first week live began, in its second, to rot the codebase quietly, and quiet rot has no stack trace.

   What you can do afterwards

   You will be able to name the four ways an ad-hoc agent setup decays a repository. You will recognize each one in your own tree, and you will see why they are not four bugs. They are one missing layer of architecture.

   Use this chapter when

   Your agent worked perfectly in a demo and started misbehaving a sprint later. Use it when a new teammate cannot reproduce the behavior everyone swears they saw.

3. Chapter 2

   STACK: Five Layers

   Four failure modes, one underlying absence. Chapter 1 gave them names; this chapter supplies the structure that makes the absence impossible: five layers, each one a home for a kind of intelligence a normal codebase never has to carry. STACK is that structure, and the map you will walk for the rest of this book.

   What you can do afterwards

   You will map any repository to the five-part STACK sequence: Structure, Toolchain, Agent configuration, Connection, and Knowledge/quality. Then you will run the audit that scores each one from absent to versioned-and-tested.

   Use this chapter when

   You inherit a repo agents already touch, you are about to add your first agent to a brownfield codebase, or you cannot say where your prompts, rules, and tool contracts actually live.

4. Chapter 3

   Structure — Layout and Entry Points

   An agent does not explore your repository. It forages, and a maze charges a toll on every wrong turn that a route never asks for.

   What you can do afterwards

   You will design the front door of a repository so a fresh agent, or a new engineer, can route in its first minute. The tree gets named entry points, predicate-rich directories, and a navigation map an agent reads on entry.

   Use this chapter when

   A new agent re-derives your layout on every run. Use it when an agent reinvents code that already exists two directories over, or when "where does X live?" is answered only by the person who built the repo.

5. Chapter 4

   Workspaces and Boundaries

   A repository agents can navigate is the first half of Structure. The other half is a repository they can navigate without loading the parts they do not need. At scale, that second half decides whether your agents stay reliable or start hallucinating couplings that were never there.

   What you can do afterwards

   You will decide where to draw workspace boundaries so an agent can load a unit's full context and change it correctly. You will scope per-workspace instructions under one root and recognize the "distributed monolith" that blows the context budget.

   Use this chapter when

   Your repo has grown past one cohesive thing. Use it when agents keep over-loading code to make small changes, or when you are choosing between a monorepo and several repos and want a reason that is not taste.

6. Chapter 5

   AGENTS.md and CLAUDE.md

   A repository can hold five contradictory descriptions of how it works, and every agent that reads it will obey a different one. The cure is not a better instruction file. It is one instruction file the others bow to.

   What you can do afterwards

   You will author a single root constitution for your repository: scope, commands, shell mandate, safety floor, quality gates, and a repo map. Then you will wire every agent tool to read that one file instead of five drifting copies.

   Use this chapter when

   Your `CLAUDE.md` disagrees with a `.cursorrules` that disagrees with the code, or you are adding your first root instruction file and want it to age well instead of bloating into noise.

7. Chapter 6

   Rules Across Tools

   One constitution, singular. That was Chapter 5's win for NexumOS, and within a month the question that breaks it: every tool wants its own copy, in its own folder, in its own dialect. So how do you keep one truth when five surfaces each demand to hold it?

   What you can do afterwards

   You will version your rules as code, scope them by glob, and keep one canonical source. Per-tool copies will be generated or imported from that source, curing the rule drift that made Chapter 1's agent right on Monday and wrong on Tuesday.

   Use this chapter when

   Your team uses more than one agent tool, or your `.cursor/rules` and `CLAUDE.md` no longer agree. Use it when you have debugged "the agent ignored our rule" and found a second rule contradicting the first.

8. Chapter 7

   Agent Skills

   What you can do afterwards

   You will take a prompt your team retypes from memory and turn it into a versioned, reviewable, testable skill package. The result is a folder with a `SKILL.md`, a trigger description, an on-demand body, and a golden test that pins behavior.

   Use this chapter when

   The same instructions get pasted into chat every week. Use it when your "good" prompts live in someone's head or a Slack thread, or when you cannot tell whether last month's edit made a capability better or worse.

9. Chapter 8

   Roles and Subagents

   Skills give your repo capabilities. They do not answer who is chartered to use them, under what constraints, or when that worker must stop. That is where an agent that can do anything starts doing the wrong thing. A skill is a power; a role is the hire with a job description who is chartered to pick it up.

   What you can do afterwards

   You will replace generic "the agent" with a small roster of chartered roles. Each role gets a written mandate, least-privilege tool list, typed inputs and outputs, and a named escalation path. Each can become a scoped subagent that runs in its own clean context.

   Use this chapter when

   One catch-all agent is doing triage, deploys, and billing writes from the same context. Use it when destructive incidents trace to "the agent had every tool just in case," or when parallel agent workers are arriving faster than you can review their output.

10. Chapter 9

    Prompts, Commands, and Workflows

    Chapter 8 gave NexumOS a roster of chartered roles. But a role is a who, not a what. The triage agent now has a mandate; it still has no script. This chapter writes the script, and writes it as code, because the operation your agents run forty times a week should not live in your memory of how the demo went.

    What you can do afterwards

    You will turn your most-repeated chat operation into a parameterized, version-controlled command with a golden test case. You will also learn to chain those commands into short workflows with named human checkpoints instead of one heroic pipeline.

    Use this chapter when

    You catch yourself retyping the same five-step instruction from memory. Use it when teammates each have their own version of "the way we ship a fix," or when last month's agent workflow quietly stopped producing the same shape of output.

11. Chapter 10

    Memory and Context Tiers

    What you can do afterwards

    You will write a memory policy that sorts every piece of standing context into three tiers: hot session, warm project, cold archive. The agent will load the smallest high-signal set on each run, not the largest the window allows. You will leave with a copy-pasteable tier table and a context budget your repo can enforce.

    Use this chapter when

    Your agent contradicts itself deep in a long session, a stale decision keeps resurfacing, or your root instruction file has crept past two screens. Use it when you cannot say which things in context were chosen and which merely accumulated.

12. Chapter 11

    MCP Servers and Tool Contracts

    What you can do afterwards

    You will turn the tools your agents call from bare functions into governed contracts: schema, auth, limits, timeouts, idempotency, and named failure modes. You will also make the chapter's highest-return security decision, local versus remote, on purpose instead of by default.

    Use this chapter when

    Your agents call MCP servers nobody wrote a spec for. Use it when a tool lives in someone's personal config, when its scope is unclear, or when last week's tool silently changed what it does.

13. Chapter 12

    Hooks and Guardrails

    A contract declares what a tool is allowed to do. It does not stop the tool from being asked to do something else.

    What you can do afterwards

    You will move the one invariant that must hold every run out of prose and into a deterministic hook. It fires on the event, validates the call, and holds no matter what the model chose. You will write, test, and ship your first PreToolUse gate this week.

    Use this chapter when

    A rule in your `CLAUDE.md` says "never force-push," "always run tests before committing," or "don't touch `.env`." Use it when you have caught the agent doing the thing anyway, or when you cannot afford to.

14. Chapter 13

    Plugins and Marketplaces

    A skill you write is code you trust because you wrote it. A plugin you install is code you trust because someone else wrote it, and the agent that runs it holds your credentials and a shell. This chapter closes the gap between those two sentences.

    What you can do afterwards

    You will stop installing third-party agent capability on vibes. Instead, you will curate it as the supply-chain dependency it is: score every plugin against six dimensions, pin what you keep, and fork what you cannot pin.

    Use this chapter when

    A teammate drops a "you have to try this" plugin in the channel. Use it when a marketplace listing promises exactly the thing you were about to build, or when you cannot name where your team's agents got their extra tools.

15. Chapter 14

    Shells and ReasonKit-tools

    Every plugin you install, every skill it bundles, every tool it exposes ends the same way: a command runs in a shell. Chapter 13 taught you to evaluate what you install. The shell is the room all of it executes inside, and most teams have never decided what that room contains. This chapter furnishes it.

    What you can do afterwards

    You will declare your repository's shell and CLI toolchain as versioned config. A human or agent should be able to recreate the environment from a new checkout. You will also learn when to use a structured shell that hands the agent rows it can filter, and when to use a POSIX shell for CI portability.

    Use this chapter when

    A command works on your laptop and fails on a teammate's. Use it when an agent's pipeline breaks because the assumed CLI version is different, or when nobody can name the shells and tools your repo expects without asking the person who set it up.

16. Chapter 15

    Integrations, Evals, and CI for Agents

    A green test suite is the only sentence in a codebase that says "this still works" and can be trusted. Rule files and skill files have never been allowed to say it. This chapter changes that.

    What you can do afterwards

    You will treat your `AGENTS.md`, your rules, and your skills as the untested production code they already are. Each gets a golden-task eval, a merge gate, a pass-rate threshold, and a cost budget. Agent runs also become traceable, so a "harmless" edit can no longer regress behavior in silence.

    Use this chapter when

    You cannot tell whether last week's rule tweak helped or hurt. Use it when a one-line prompt change broke a workflow nobody noticed for days, or when your only test of "did this help" is whether the next demo feels good.

17. Chapter 16

    Vibe Coding vs Production Discipline

    Speed does not threaten maintainability; speed in the wrong container does. This chapter gives the wrong container a sanctioned shape and a door that only opens through the gates.

    What you can do afterwards

    You will stop treating speed and discipline as a choice. Instead, you will treat them as two modes with two territories: fast exploration in a sanctioned lane that never touches the main repo's invariants, and gated production work that decides what merges.

    Use this chapter when

    You are tempted to skip the gates "just this once" to keep momentum. Use it when an agent-generated spike looks good enough to merge straight to main, or when every fast win has left a little debt behind.

18. Conclusion

    Conclusion: Maintain the Stack

    A demo proves the model can do the work once. A versioned stack proves the work survives the people who built it and the model that replaces them. This book was the distance between those two sentences; this chapter is the habit that keeps you on the second one.

    What you can do afterwards

    You will leave with a maintenance habit, not a finish line: the STACK audit, completed once for NexumOS. Then you will put the same audit on a cadence for your own repo, so the five layers stay versioned instead of rotting back into folklore.

    Use this chapter when

    You have built the stack: structure, configuration, connections, and knowledge. Now you have to keep it alive through model upgrades, new teammates, and a hundred small "just this once" shortcuts.