agency-icm-builder

Agency ICM Builder

Build workspaces where the folder structure runs the agency. One AI agent, reading the right files at the right moment, coordinates client work across services: the routing files decide what loads, per-client folders guarantee client data never mixes, and a session-end capture protocol turns daily work into durable memory.

This is not theory. The conventions here run a real agency: 15 client folders, 5 service departments, daily production use. Everything below was extracted from that system, then genericized.

The term ICM (Interpretable Context Methodology, folder structure as agent architecture) comes from Van Clief & McDermott, arXiv:2603.16021.

The ten rules

Every workspace this skill builds or audits follows these. In audit mode, each rule is a check.

1. The root file routes, it does not teach. The root CLAUDE.md holds identity plus a routing table (task keyword to file path) and nothing else. Content lives in the files it points to. When the root file grows, it is absorbing payload that belongs on a shelf.
2. Every client is one folder. Nothing about a client lives outside clients/<name>/. This is the no-mixing guarantee: the agent always knows which client it is working on, so client facts always land in the right folder. Cross-client insight goes to a shared patterns file, stripped of client identity.
3. Three files tell the client's story. hot.md (current state and priorities, rewritten as things change), log.md (append-only event history with tags like [DECISION] [RESULT] [PROBLEM]), learnings.md (distilled operational rules). Now, what happened, what we learned. An agent reading these three files cold is up to speed.
4. Load per task, not per session. A load-order contract (one file in system/) says which files each task type needs: a report task loads campaign state, a copy task loads brand voice, a strategy task loads the client profile. The agent loads those and stops. Whole-workspace loads are a bug.
5. One home per fact. A link beats a copy. Two hand-maintained copies of the same fact will drift, and drifted copies are worse than no copy, because one of them lies.
6. New client = copy the template. clients/_template/ is the unit of instantiation. Evolution rule: when three real clients independently grow the same folder, the template gains it. One client's extra folder is an exception; three are structure.
7. State is rewritten, history is appended. hot.md gets edited in place. log.md only grows. Never rewrite history to reflect current state; that is what hot.md is for.
8. Sessions end in capture. Work not written back to the client folder did not happen. The capture is agent-driven at session end: log entry, hot update if priorities shifted, learnings append if there was a lesson. If client attribution is uncertain, the note goes to a quarantine inbox for the human to file. Never guess the client.
9. Expertise and state live apart. departments/ (or services/) holds stable know-how: agent instructions and skills that change rarely and apply to every client. clients/ holds per-client state. system/ holds workspace infrastructure: policies, the load-order contract, changelogs. A fact that survives every client belongs in a department; a fact about one client never leaves its folder.
10. A hand-maintained index that duplicates state will rot: generate it, shrink it, or drop it. The failure mode is narrow: a file that re-lists state living elsewhere (client rosters, "map of everything" system maps) and relies on a human remembering to update it. That copy drifts and starts lying. Fix it one of three ways: rebuild it from a script, keep it small enough that drift is obvious at a glance (the root routing table is exactly this), or delete it if nothing reads it. Not every index is guilty: an index that holds its own content rather than duplicating state, and a purely presentational file (for example one that only exists to shape a graph view), are not state copies and this rule does not touch them. The question to ask is "does this file restate something whose real home is elsewhere?" Only then is it at risk.