Architecture — agent-ready

§ 1

Context is an interface

An agent does not "know" your project; it reasons over whatever is assembled into its context window — the system prompt, the repo's agent instructions, retrieved memory, tool schemas, and the files in view. That assembly is the API between developer intent and agent action. Its qualities are ordinary interface qualities: it should be unambiguous, current, consistent, and minimal.

Most "the agent did something dumb" failures are interface defects: instructions that contradict each other across files, stale conventions no one deleted, or a contract so vague that the model fills the gap with a guess. The kit treats context as a designed surface, with one contract at its center.

§ 2

Single source of truth, thin adapters

Every tool wants its instructions in a different file — CLAUDE.md, .github/copilot-instructions.md, .cursor/rules, and more. Maintaining N independent rule-sets across N tools guarantees divergence: they drift, contradict, and rot at different rates. This is the classic duplication failure, and the classic fix applies.

One canonical AGENTS.md; each tool file is a three-line adapter that points to it. Write the rules once; every tool reads the same contract. The adapters carry zero policy of their own — they are pure indirection.

In module terms, AGENTS.md is a deep module: one small interface (a file you open) hiding the entire working agreement. The adapters practice information hiding — each conceals its tool's idiosyncratic filename and format behind the same pointer.

§ 3

Layered composition & precedence

The kit is layered so a project adopts only what it needs. A universal core (the working agreement, the memory tier, the principles) applies to any repo with an agent in it. An optional module (multi-agent coordination) is added only under real contention. Complexity is opt-in, not inherited.

When sources of truth conflict, precedence is fixed and must be honored top-down:

The kit fills gaps; it never overrides the project or the person. A default that fights the codebase yields to the codebase; both yield to what the developer just said.

§ 4

The memory tier

Agents are effectively stateless across sessions. Durable memory is the persistence layer that survives the reset: file-based records, each a durable fact that would otherwise be re-derived, fronted by an index (MEMORY.md) loaded at session start. Frontmatter on each record (a one-line description, a type) is the retrieval signal — enough to decide relevance without reading the record.

At this scale a curated file store beats a vector database: higher precision, zero infrastructure, human-auditable, and diffable in the same PR as the code it describes. The cost is discipline — records are point-in-time and must be kept current. A stale memory has negative value: it is confidently wrong, and worse than none.

Property

Memory is a write-through cache of hard-won knowledge, not an append-only log. Correcting and deleting is as important as writing.

§ 5

Testability architecture

"Verify, don't assume" is an observability stance: assert on the behavior you can observe, not a proxy for it. "Tests pass" is a proxy; "the change does the thing, exercised end to end" is the observation. The structural pattern that makes this cheap is logic in a tested core, a thin skin on top — push decisions into a fast-testing package, keep the IO/UI layer minimal, and the risky part is the part you can prove.

Technique

Revert-to-prove-red is hand-run mutation testing: a regression test that still passes when you undo the fix proves nothing. Confirm the test fails on the broken code before you trust it on the fixed code.

§ 6

The security checkpoint

Some diff classes — auth, tokens, crypto, sessions, access control — carry outsized blast radius and get a review gate before merge. The non-obvious requirement is on the tests: they must be able to fail on the vulnerability. A test that signs its own fixtures with the very key the code trusts will pass on a forged input too; it validates nothing. If a test cannot go red on the real bug class, it is not a gate.

Where the language allows, promote the invariant from a test to the type system — define the error out of existence. An enum with no case for a forbidden capability cannot be misused; the compiler is a cheaper, stricter reviewer than CI.

§ 7

Composition into a project

The kit installs as plain files (idempotent, non-destructive) and coexists with whatever is already there — it adds an AGENTS.md, adapters, and a memory/ scaffold, and touches nothing else. There is no runtime, no dependency, no framework: the artifacts are read by tools you already run. Removing it is deleting files. That reversibility is a feature — adoption should never be a lock-in.

§ 8

Design rationale

The kit is an argument that the discipline of good software design applies to the design of agent context itself:

Deep modules. AGENTS.md is one shallow interface over the whole agreement; the adapters hide tool-specific format behind identical indirection.
Define errors out of existence. The strongest guardrail is one the code cannot violate — enforced by types, not comments or reviews.
Complexity is incremental. Every rule is a cost; add on real failure, remove when its cause is gone. A mechanism that never catches anything is not rigor, it is debt — the through-line to §7 of the coordination model.

The point of all of it is to make the repository smaller to reason about — for the human and the agent alike — not larger.