A Field Guide to ICM: Folders, Plain Text, and One Honest Agent

Every week someone asks me what agent framework they should learn. LangChain? CrewAI? Some orchestration platform with a waitlist?

My answer keeps getting shorter: probably none of them. The most reliable AI system I run is a set of numbered folders and plain markdown files, with one capable agent reading the right file at the right moment.

That's not a hot take I invented. It's a published methodology called Interpretable Context Methodology — ICM — from Jake Van Clief and David McDermott, with an open-source reference implementation by Mark Garza. I've spent real hours auditing my own working vault against it, and this is the field guide I wish I'd had at the start.

What ICM actually is

Here's the fork most people hit first.

You have work you want AI to help with — say, turning site-visit recordings into client proposals. Path one: build agent infrastructure. Multiple agents, an orchestrator, a database for state, a queue, retries. Path two: organize the work into folders so clearly that a single agent can navigate it like a new employee reading a well-labeled filing cabinet.

Path one feels serious. It demos well. It's also, most of the time, the wrong path — you end up maintaining software plumbing around work that is really just: files come in, get processed in stages, get reviewed, go out.

ICM is path two, formalized. Van Clief's framing that stuck with me: "Agent is just a fancy word for organized software." Instead of building an agent per task, you build one good working environment, and the agent becomes whatever the folder it's standing in tells it to be.

There's a practical payoff beyond simplicity. When the agent only loads the two or three files a task actually needs, it works with a small, clean context instead of your entire business dumped into one prompt. The workspace-architect docs put a well-scoped stage at a few thousand tokens versus tens of thousands for the load-everything approach — and in my own experience, small context isn't just cheaper, it's noticeably better. An AI writing a proposal shouldn't also be reading my video production notes.

The 5-layer model

ICM organizes context into five layers. Each one answers exactly one question.

Layer 0 — the map. A root file that always loads. It answers "where am I?" — the folder tree, naming conventions, where files go. Think of the floor plan posted on the wall of every room. The discipline: keep it under one screen. If it's longer, content is hiding in it that belongs a layer down. Every line here costs attention in every single conversation.

Layer 1 — the router. A short table answering "where do I go?" Task → destination → what else you'll need. This is the single most important pattern in the whole system, because it tells the agent not just what to read but what to skip.

Layer 2 — the room. Each workspace gets its own small context file answering "what do I do here?" It only loads when you're working in that room.

Layer 3 — the recipe. Reference docs: brand voice, standards, client profiles. These load on demand, per task — never all at once. The operating principle I repeat to myself constantly: configure the factory, not the product. Editing an output fixes this run. Editing the standards doc fixes every future run.

Layer 4 — the ingredients. The actual working files and outputs of the current run. The key rule: never let these masquerade as reference material. Last month's proposal is not an unofficial style guide. If a run taught you a rule, promote the rule into a Layer 3 doc on purpose.

Map, router, room, recipe, ingredients. That's the whole stack. The design target: the agent should have to think as little as possible to find what it needs.

A workspace is a phase of work, not a category of files

This was the part that stung, because my own vault got it wrong for a long time.

Most of us organize by category: a projects folder, a marketing folder, a clients folder, a finance folder. Those lanes answer "what kind of thing is this file?" That's the right shape for an archive — capture once, find later.

It's the wrong shape for doing a job. One real job — producing a scope proposal for a Grow Wild landscaping client — touches five of those categories at once. An agent working in a category system has to hop lanes constantly, and every hop means loading more context and losing more focus.

An ICM workspace answers a different question: "what mode of work am I in right now?" Drafting is a different headspace than producing, which is a different headspace than distributing. Each mode gets its own room, its own context file, its own rules. Start with two or three workspaces, maximum.

The two systems aren't enemies. Your category vault is the library. ICM workspaces are the workshops. You pull reference material from the library into the workshop; you don't try to build furniture in the stacks.

The three topologies

Every workspace takes one of three internal shapes. Two questions decide which:

1. Is there a fixed, repeatable sequence where each step's output feeds the next?
2. Do you want a human review gate between steps?

Both yes → pipeline. Same input fanning out to many independent outputs → hub. No fixed order at all → loose. Mixing all three across a root is normal.

Hub is content distribution: one finished video or case study fans out to a social cut, a description, a recap email, a portfolio entry. Each output has its own trigger; none waits on another. Loose is exploratory work — early client discovery, brainstorming — where the only state you need is a filename suffix: _draft → _review → _final.

The one worth understanding deeply is the pipeline.

Pipelines: the deep dive

A pipeline is a factory floor built from numbered folders: 01-intake/, 02-analysis/, 03-report/. The numbering isn't decoration — the numbering is the execution order. Sequential from 01, no gaps.

Four mechanics make it work:

Stage contracts. Every stage carries a short context file with three headings: Inputs, Process, Outputs. The Process section defines what counts as done — acceptance criteria — not how to do it. Specs are contracts, not blueprints. The agent keeps creative freedom inside the constraints. And one stage does one job: a stage that filters doesn't also format.

Forward-only flow. Output moves downstream, never back. If stage 01 got something wrong, you fix stage 01 and re-run — you never quietly bend stage 03 around the error. Patching downstream to compensate upstream is how systems rot invisibly.

Human gates. Review pauses live at stage boundaries, and here's the beautiful part: they're free. Because every intermediate output is a plain file on disk, you can open it, read it, and edit it before the next stage consumes it. Compare what a framework has to build for that same capability — a UI, an approval API, a state machine. Here it's a folder you open. Garza's Glass Box demo makes this literal: staged folders with the human-review stage highlighted, the workflow waiting until a person actually looks. Contrast the black box, where a zip disappears into a pipeline with no logs, no prompts, no pause.

The filesystem is the state. No database, no orchestrator, no job queue. Which stage folder a file sits in, plus its filename, is the workflow status. Listing the folders tells you exactly where every job stands. And a verification step at the end of a stage logs mismatches to an audit file instead of silently fixing them — you want to know when something didn't line up.

A worked example from my landscaping business

My real workflow at Grow Wild: I walk a property, record video and voice notes, take photos, and all of it has to become a client-ready scope document. As an ICM pipeline:

growwild-scope/
          ├── CLAUDE.md              ← the map: identity, tree, naming
          ├── CONTEXT.md             ← the router: task → stage table
          ├── docs/                  ← the recipes
          │   ├── growwild-voice.md      ← tone, plant vocabulary, claim rules
          │   ├── scope-standards.md     ← document structure, language rules
          │   └── client-profiles.md     ← per-client context
          └── workflows/
              ├── 01-intake/
              │   ├── CONTEXT.md     ← raw media in → walkthrough log
              │   │                    + gaps.md out. GATE: I review
              │   │                    the gaps before stage 02.
              │   └── output/
              ├── 02-scope-extraction/
              │   ├── CONTEXT.md     ← log in → zones, plant palette,
              │   │                    effort estimate out. No client-
              │   │                    facing prose allowed here.
              │   └── output/
              └── 03-deck/
                  ├── CONTEXT.md     ← findings + scope-standards in →
                  │                    finished document out. VERIFY:
                  │                    every claim traces to a log line.
                  └── output/
          

Stage 01 transcribes and logs observations by zone, and — critically — flags what's missing. That gap file hits a human gate: if I didn't get the backyard drainage on video, that's a follow-up text to the client, not an AI guess. Missing data is a conversation, not an invention.

Stage 02 turns the log into structured findings. The contract explicitly forbids client-facing prose here — analysis and presentation are different jobs.

Stage 03 loads the scope standards for the first time (stage-scoped loading — earlier stages never paid for that file) and produces the finished document. The verify step cross-checks every claim against the findings and logs anything that doesn't trace.

And when a document comes out with language I don't like? I don't argue with the agent. I edit scope-standards.md, and every future document inherits the fix. Fix the context, not the agent.

The first working version of a workspace like this takes minutes, not weeks: map, router, one workspace, a doc or two. Then grow it from observed mistakes.

How these systems rot

Every failure mode I've seen — in my own vault audit and elsewhere — is one of these:

• One giant map file. Everything crammed into the root doc, so every conversation pays for every line. Push content down a layer.
• No skip column. You told the agent what to read but never what to ignore. The skip column matters more than the load column.
• Everything loads from docs/. If every task loads every reference doc, you've rebuilt the monolithic mega-prompt with extra folders.
• Room files that become encyclopedias. Stable knowledge hiding in a router. Move it to the recipes.
• Undocumented handoffs. Files drifting between workspaces with no recorded direction. Handoffs are one-direction copies, written down on both sides.
• Outputs masquerading as reference. The Layer 4 discipline again. Promote rules deliberately or not at all.
• Building everything before using anything. The overbuild trap — the same instinct that reaches for frameworks. Ship minimal, use it, and add rules only when a real failure earns them.

Notice what these have in common: none of them are technology failures. They're all filing failures. Which is the whole point.

If you take one thing

Before you build or buy any AI agent system, ask: is this actually a folder-organization problem wearing a software costume? Most of the time it is. Numbered folders, small plain-text context files, contracts between stages, a human gate where judgment matters, and one honest agent reading the right file at the right moment. Right context, not all context — that's the entire game.

← Back to the Learning Log