ICM - 📂 Folder Structure - Deep Dive 🤿

Bas Rosario

4d (edited) • 💬 General discussion

🔍 Three things to notice. 👇

1️⃣ Numbered folders set the execution order, so 01- always runs before 02-.

2️⃣ Each stage carries its own CONTEXT.MD, references/, and output/.

3️⃣ The handoff between stages is dead simple. Stage 1's output/ is what stage 2 reads as input.

================== 📂 The folder structure

workspace/ -------------------------------------------# the whole operation

CLAUDE.md ------------------------------------------# L0: orientation, "where am I?" (always loaded)

CONTEXT.md --------------------------------------- # L1: the map, "where do I go next?"

stages/ ------------------------------------------------ # all the steps in order

01-research/ ---------------------------------------- # step 1: gather the source material

CONTEXT.md ---------------------------------------# today's job description

references/ ------------------------------------------# rules for this step

output/ -------------------------------------------------# what this step produced

02-script/ -------------------------------------------- # step 2: turn research into a draft

CONTEXT.md -------------------------------------- # today's job description

references/ ----------------------------------------- # voice rules, examples

output/ ----------------------------------------------- # the draft lives here

03-production/ ------------------------------------# step 3: ship the final artifact

CONTEXT.md ------------------------------------- # today's job description

references/ -----------------------------------------# design system, build conventions

output/ ----------------------------------------------- # the finished product

_config/ -----------------------------------------------# L3: brand, voice, design (configured during setup)

shared/ ----------------------------------------------- # L3: assets every stage might use

skills/ -------------------------------------------------- # L3: bundled skills the agent can call

setup/ --------------------------------------------------# first-time configuration

questionnaire.md --------------------------------# onboarding form, completed once

===============================================

✅ That's it, a very neat set of folders and markdown files (.md), all with one job.

Let's go over the workflow in detail below,

🔍 How the workflow actually works: the five layers, L0 through L4

The agent reads down through five layers and stops when it has what it needs. A quick formatting job might only pull L0 through L2. A deep writing job reads all the way down to L4. There is always just enough context for today's work, and nothing extra to distract it.

Each layer answers one question. L0: where am I? L1: where do I go next? L2: what's my job? L3: what rules apply? L4: what am I working with?

👇

===============================================

L0 is CLAUDE.md. It answers, "where am I?" Always loaded.

L0 is orientation. Your agent just started their first day. Tell them where things are.

===============================================

👇

===============================================

L1 is the workspace CONTEXT.md. It answers, "where do I go next?" Read on entry.

Think of this as the office map and org chart. Now that your agent knows where they are, this tells them which department handles what and where to go first.

===============================================

👇

===============================================

L2 is the stage CONTEXT.md. It answers, "what's my job right now?" Read per task.

This is the actual task assignment for the day. Not "you work in marketing," but "today, write this specific blog post by 3pm." Tight scope, nothing extra.

===============================================

👇

===============================================

L3 is reference material. Things like your design system, voice rules, brand guidelines, domain knowledge. It answers, "what rules apply?" Loaded only when relevant.

This is the employee handbook plus the brand bible. The rules don't change just because today's project is different. Same dress code, same brand voice, same way of doing things. Your agent grabs the relevant chapter only when the work calls for it.

===============================================

👇

===============================================

L4 is working artifacts. Previous stage output, source material you dropped in, anything specific to this one run. It answers, "what am I working with?" Loaded selectively, changes every run.

This is the project folder on your agent's desk today. The client brief, yesterday's draft, the source interview transcript. New project tomorrow means a totally new folder. The handbook stays the same, but what's on the desk is always fresh.

===============================================

🧠 Why Interpreted Context Methodology (ICM) actually works

⭐ Each stage's CONTEXT.md is a contract with three sections: Inputs, Process, Outputs. The Inputs section doesn't just name files. It names which specific section of which file to load. That scoping is the whole game.

🛠️ Why it works: five borrowed ideas, all old

1️⃣ One stage, one job. Picture a chef who's also taking orders, prepping ingredients, and washing dishes. The pasta burns because attention is split four ways. ICM stages are like having a dedicated prep cook, line cook, and dishwasher. Each one is great at the one thing they do, and they hand off cleanly. A research stage doesn't try to write copy. A writing stage doesn't try to render slides.

2️⃣ Plain text as the interface. You know that feeling when a Zapier flow breaks at step 4 and the error message is some cryptic JSON blob? Or when you try to figure out what a Notion automation actually did and there's no audit trail? With ICM, you just open the markdown file. Same reason engineers love config files over GUIs. If something looks off, you can read exactly what the agent saw and exactly what it wrote.

3️⃣ Layered context loading. Imagine onboarding a new hire and on day one handing them your entire company wiki, every Slack message ever sent, and the full Google Drive, then saying "go write the launch announcement." They'd freeze. Now imagine you hand them just the brand voice doc, the product spec, and last quarter's launch post. Same person, way better output. That's what layered loading does for the model.

4️⃣ Every output is an edit surface. Stage 1 (research) spits out 10 angles for your weekly post. You skim it, cross out 6 that are off-brand, sharpen one of the remaining ones, and save the file. Stage 2 (script writing) reads your edited version, not the original. No re-prompting, no "actually use this angle instead" follow-up message, no copy-pasting between Claude tabs. The file IS the conversation.

5️⃣ Configure the factory, not the product. You don't re-tell your designer your brand colors every time you ask for a graphic. You set those up once at the start of the relationship and they apply automatically every time after that. ICM does this for your AI pipeline. You answer a questionnaire one time at setup ("what's your voice? who's your audience? what design system?"), and every run after that inherits those constraints.

⚙️ Do filesystems beat frameworks?

The deeper reason it all worksvis that the filesystem is doing the work that a framework would normally do in code. Sequencing? That's the folder numbering. State management? That's just files on disk. Coordination between stages? That's one folder's output becoming the next folder's input. And you get observability for free because the system state IS the filesystem. If your weekly report comes out weird, you open the 01-research/output/ folder, see exactly what the research stage pulled, then open the 02-script/output/ folder to see exactly what the writing stage was told. Compare that to debugging a black-box agent flow.

=================================

GitHub: https://github.com/RinDig/Interpreted-Context-Methodology

arXiv: https://arxiv.org/abs/2603.16021 — Interpretable Context Methodology: Folder Structure as Agentic Architecture

I understand ICM Folder Structure

I still need help understanding this

25 votes

18 comments