I am writing this on a Monday in mid-December, fourteen weeks and roughly two hundred commits into building DuranteOS. I have not built Sentinel yet. The pack does not exist. The artifact directory does not exist. The CLAUDE.md section it would write does not exist.

I am writing the design essay before the code on purpose. Every week I am running the same disappointing experiment with the same disappointing result, and the only way to stop running it is to write down what I think the cure looks like before I am too tired to be careful about its shape.

The experiment is this. I open a fresh project — one of the eleven repos DOS now has a working theory about. I ask the agent to make a small change. The agent reads three or four files at random, finds something that looks like the prevailing pattern, and writes more of it. Two days later I discover the agent's "prevailing pattern" was actually the one legacy file nobody had ever refactored, and the agent has now propagated the legacy shape across four new files.

This is not a model-quality problem. It is an induction problem. The agent generalized from too small a sample, with no signal about which sample was canonical and which was historical. And it will keep generalizing from too small a sample, on every single first request to a new repo, forever, unless I build something that arrives before the request does.

The thing I want to build is Sentinel. This essay is what I want it to be before I write a line of it.

The Eric Evans angle: Ubiquitous Language is something you discover, not invent

Eric Evans's central methodological move in Domain-Driven Design — the move that I keep returning to in my own notes — is knowledge crunching. The practice of working alongside domain experts until the team's working vocabulary lines up with the actual structure of the domain. The artifact Evans values most is not the diagram or the schema. It is the Ubiquitous Language. A small set of nouns, verbs, and relationships that everyone on the team uses with a single shared meaning.

Most codebases I touch have a Ubiquitous Language. They just rarely have it written down anywhere. The vocabulary lives in commit messages, in slack threads, in the head of the senior engineer who has been there four years. When a new contributor arrives — human or AI — they have to reverse-engineer it from the code itself, which is slow, error-prone, and produces inconsistent inductions.

What I want Sentinel to do is to act as the knowledge-crunching session that should have happened. Read the codebase as the domain expert. Distill the vocabulary. Write it down where the agent will see it next session.

The piece I am most worried about getting wrong, in advance, is the distillation step. Evans warns over and over against premature naming and premature reification, and I do not yet know how to instruct a scanner to refuse to name something that has not stabilized. My current best guess is that Sentinel should distinguish between three classes of pattern by frequency: anything appearing in 80%+ of relevant files becomes a convention; anything in 30-80% becomes flagged drift, not convention; anything below 30% gets ignored. The 80% threshold is a guess. I will probably move it after the first three projects.

The Alistair Cockburn angle: Sentinel must be an information radiator, not a status report

Alistair Cockburn's Crystal Clear introduces the term information radiator — an artifact you can absorb at a glance because it is positioned where you cannot avoid it. The classic example is the team task board on the wall of the office. The opposite is the status report nobody reads.

This is the part of the design I am most confident in. Whatever Sentinel produces, it must end up in CLAUDE.md, which the harness already loads automatically into every session's context. Not in a wiki. Not in a doc-site. Not in a registry the agent has to query. In CLAUDE.md, which is in the agent's mouth before the agent has been asked anything.

The cost of consulting it must be zero. The cost of not consulting it must be deliberate — the agent would have to actively ignore information that is already in front of it. That asymmetry is the whole game. Information radiators work because not consulting them is more effortful than consulting them. Status reports fail because the reverse is true.

Cockburn's other contribution that I want to lean on, and that I am suspicious I will fail to lean on, is the methodological humility of the Crystal family — the right methodology for a project depends on team size and criticality. Sentinel should be deliberately lightweight. A single command. A small directory of artifacts. A CLAUDE.md edit. Not Architecture Decision Records. Not RFCs. Not a wiki. Those exist for human readers and have their place. Sentinel is for the agent, and the agent reads what is in front of it. If I let the design grow, it will quietly become a system of record, and a system of record is a thing humans maintain, and the moment humans maintain it, it goes stale and the agent starts trusting stale data.

That is the failure mode I am writing this essay to avoid in advance.

The five phases I think Sentinel should run

The scan should run in five phases. Each phase emits a distinct artifact. The whole scan should take under ninety seconds for a medium-sized codebase. If it takes longer, I have done it wrong.

What I think a real Sentinel output should look like

I have been hand-writing what I think Sentinel's output should look like, on the projects I have been onboarding the agent to. Here is what I sketched for the SaaS platform I am about to start building (the one that will host the credit-metered gateway). I have written this section by hand, on purpose, because I want to know what good looks like before I ask a scanner to produce it.

## Sentinel Conventions

### Stack
Monorepo SaaS with API Gateway Pattern.
Next.js + Prisma + PostgreSQL + Better Auth + Stripe.
~40 models, ~45 API endpoints, ~12 AI/media providers planned.

### Conventions
- Monorepo: Turborepo with @kit/* packages, apps/* workspaces
- Multi-tenancy: Organization root entity, cascade deletes,
  composite unique keys
- Gateway: REST at /api/v1/{service}/{provider}/ with Bearer token
  + credit metering
- Billing: Double-entry credit ledger (reserve→commit/release).
  SpendCap enforcement pre-request
- Data Loading: React cache() + server-only imports + explicit
  Prisma select clauses
- Auth: Better Auth catch-all at /api/auth/[...all], server actions
  via next-safe-action
- IDs: UUID primary keys throughout. No auto-increment.

### Key Decisions
- Better Auth over NextAuth/Clerk — simpler API, built-in multi-tenancy
- API Gateway pattern — all AI calls route through Studio for metering
- Credit-ledger over pay-per-call — enables spend caps, refunds,
  partner tiers
- Prisma + PostgreSQL — type-safe ORM, hosted production

The output is short. It has to be. CLAUDE.md will be loaded into every session's context, and context is finite. The discipline I want Sentinel to enforce is to capture only what would change the agent's behavior. Anything an agent would do correctly without the convention does not belong in the convention list. That is the rule I have to write down, because the moment I let exceptions creep in, the artifact becomes a wiki, and the wiki becomes stale, and the agent learns to distrust it.

Three non-goals I am committing to in advance

I am writing these down because they are the requests I will give myself in three weeks, when the first version of Sentinel ships and is too short to feel impressive.

What this implies if you onboard agents to your codebase

Three suggestions, in order of how cheaply they pay back. These are what I would tell another indie founder writing the same scanner from scratch.

One. Write down your conventions where the agent will see them by default. Most teams have implicit conventions and explicit CONTRIBUTING.md files. The agent rarely reads CONTRIBUTING.md unless told to. It always reads CLAUDE.md (or its equivalent). Move the conventions to where the agent reads. This is the cheapest possible win and you can do it before you write a single line of scanner code.

Two. Distinguish stack from conventions from decisions. Stack is what you use. Conventions are how you use it. Decisions are why you chose this and not alternatives. The agent benefits from all three but in different ways: stack tells it what idioms exist, conventions tell it which idioms to prefer, decisions tell it which alternatives to not propose. Most onboarding documents conflate the three. The agent then conflates the three. Separate them on the page and the agent separates them in its head.

Three. Re-scan on a cadence, even if you are scanning by hand. The single most common failure mode of a written-down convention is one that ran six months ago and now lies. The artifact is more dangerous when stale than when missing. Either re-scan regularly or have the artifact self-flag its age.

The agent without Sentinel is a smart contractor who walks into your codebase on day one and starts typing. The agent with Sentinel — once I build it — should be the same contractor after they have spent an afternoon reading. The work is identical. The trust profile is not.

I am writing this essay before the code because the kind of mechanized discipline I am sketching is exactly the kind that gets skipped until you have the scar tissue to insist on it.

I have the scar tissue. I do not yet have the pack. By next quarter I should have both.