Portable Agent Harness

As AI coding agents became a normal part of how I work, I kept hitting the same friction: every tool wanted its own configuration file, and across repositories the rules slowly drifted apart until no two agents behaved the same way. This experiment is my attempt at a structure that holds up across tools and across projects.

The shape is deliberately small. One canonical rule file owns how agents should behave. Every tool-specific file is a thin pointer to it, never a copy, so there is exactly one source of truth to keep current. Alongside the rules sits a fixed front door of a few documents that separate different kinds of truth: the intended objective, the verified current state, the decisions and their reasons, and the active work. An agent loads that front door and starts oriented instead of crawling the whole tree and guessing.

I run this across several repositories now, which is where it earns its keep. Because the structure is the same everywhere, the same agent instructions work in a new project on day one, and moving between projects does not mean relearning a bespoke layout each time. When something is genuinely different in a subdirectory, a scoped rule narrows the canonical one rather than contradicting it.

The lesson so far is that most of the value is not in any single rule. It is in the discipline of one owner per kind of truth, kept current, kept findable. That discipline was good practice when only people read the docs. It became close to mandatory once agents started reading them and acting on whatever they found. This site's own repository uses the same harness, which makes it a fair test: if the structure did not help, I would feel it here first.