Interpretable Context Methodology (ICM): The Complete Guide to Filesystem-Based AI Orchestration

Interpretable Context Methodology (ICM): The Complete Guide to Filesystem-Based AI Orchestration

Table of Contents

• What Is ICM?
• Why ICM Matters for Engineering Leaders
• Core Concepts & Architecture
• Implementation Guide
• Production Considerations
• Where ICM Works and Where It Doesn't
• ICM vs. Alternatives
• Frequently Asked Questions
• Conclusion

Introduction

I've watched engineering teams at 15+ companies over the past year build AI agent workflows. Almost every team reaches for LangChain, CrewAI, or AutoGen. They wire up agents, define tools, configure memory, and build logging dashboards. Then they discover that changing a prompt means editing code, reordering steps means touching orchestration logic, and their 200-line pipeline takes a senior engineer half a day to debug.

There's a simpler way.

In March 2026, Jake Van Clief (Eduba) and David McDermott (University of Edinburgh) published a paper on arXiv titled "Interpretable Context Methodology: Folder Structure as Agentic Architecture" (arXiv:2603.16021). It describes a methodology that replaces framework-level orchestration with numbered folders and markdown files. Within the first two months, over 30,000 people adopted it — Van Clief announced the milestone on YouTube in late May 2026 (source). A single practitioner used it to produce 372 unique landing pages in 3 days for eMerge Americas 2026 (source). Users report 2,000-8,000 tokens per stage instead of 30,000-50,000.

This guide covers what ICM is, how its 5-layer context hierarchy works, the five design principles it borrows from Unix, the honest tradeoffs, and a decision framework for when you should — and shouldn't — adopt it.

If you're a CTO evaluating AI orchestration approaches, this is the full picture, with the skeptical framing included.

What Is ICM?

Interpretable Context Methodology (ICM) — also referred to in the paper as the Model Workspace Protocol (MWP) — is a method for orchestrating AI agent workflows using filesystem structure instead of code-based frameworks.

The central insight is almost too simple to write down: if the prompts and context for each stage of a workflow already exist as files in a well-organized folder hierarchy, you don't need a coordination framework. You need one agent that reads the right files at the right moment. — Source: arXiv:2603.16021

Key Characteristics

• Filesystem as state machine: Numbered folders (01-research, 02-script, 03-production) represent sequential stages. The folder structure tells the agent what to do at each step.
• Plain text as universal interface: All prompts, context, and artifacts are markdown files. Any tool can read them. Any human can edit them.
• One agent, many stages: Instead of multiple specialized agents, a single orchestrating agent reads different instructions at each stage.
• Human review at every handoff: Every stage produces a file. The human edits it before the next stage reads it.
• Local scripts for mechanical work: Python scripts handle what doesn't need AI: fetching data, formatting output, moving files.

Brief History

ICM grew out of a content production system called Content-Agent-Routing-Promptbase, which applied separation of concerns to AI context windows instead of code modules. Van Clief extracted the structural patterns into a general-purpose methodology, published the paper on March 17, 2026, and revised it the next day (v2). The accompanying GitHub repo has 579+ stars and 108 forks as of late May 2026.

Why Now

Three things converged in 2026:

1. Context windows grew massively (200K standard, 1M in beta) — but the "lost in the middle" problem got worse, not better. Selective loading matters more.
2. Multi-agent frameworks matured but also revealed their complexity tax. Changing a pipeline in LangChain or CrewAI requires code changes, CI, and redeployment.
3. Non-technical users need AI workflows. ICM's markdown interface lets subject-matter experts author pipelines without developers.

Why ICM Matters for Engineering Leaders

Core Concepts & Architecture

The Five Design Principles

ICM is built on five principles, each borrowed from established software engineering:

1. One stage, one job: Each folder handles a single step. This is the Unix principle of programs that "do one thing well," combined with Parnas's information hiding — each stage only knows what it needs to know.

2. Plain text as the interface: Stages communicate through markdown files. Any tool can read them. Any human can edit them. This mirrors the Unix philosophy of plain text as a universal interface.

3. Layered context loading: Agents load only the context they need for the current stage. The paper calls this "prevention rather than compression" — don't compress irrelevant context, don't load it in the first place. — Source: arXiv, Section 3.2

4. Every output is an edit surface: The human can open, read, edit, and save the output file before the next stage runs. Review is not an afterthought — it's architectural.

5. Configure the factory, not the product: The workspace is set up once with identity, voice, and design preferences. Each run produces a new deliverable against that configuration.

The 5-Layer Context Hierarchy

This is the architectural core of ICM. Context is decomposed into five layers, loaded progressively as the agent moves through stages.

— Source: arXiv:2603.16021, Section 3.2

Per-stage total: 2,000-8,000 tokens, compared to 30,000-50,000 for monolithic prompting approaches.

Stage Contracts

Each stage's CONTEXT.md is structured as a contract with three parts:

Inputs: A table specifying which files from Layers 3 and 4 to load.

## Inputs
| Source | File | Purpose |
|--------|------|---------|
| Layer 3 | _config/brand-guide.md | Brand voice and tone |
| Layer 4 | output/01-research/findings.md | Research synthesized |

Process: Numbered steps defining what the agent should do.

## Process
1. Read the research findings from Layer 4
2. Apply brand voice rules from Layer 3
3. Write a first draft in the voice specified
4. Save to [stage-output]/draft.md

Outputs: What artifacts are produced and where they go.

## Outputs
| Artifact | Path | Format |
|----------|------|--------|
| Draft | output/draft.md | Markdown |
| Summary | output/summary.md | Markdown |

— Source: GitHub README

Workspace Structure

Here's what an ICM workspace looks like on disk:

workspace/
  CONTEXT.md               # Layer 1: task routing
  stages/
    01-research/
      CONTEXT.md            # Layer 2: stage contract
      references/           # Layer 3: reference material
      output/               # Layer 4: working artifacts
    02-script/
      CONTEXT.md
      references/
      output/
    03-production/
      CONTEXT.md
      references/
      output/
  _config/                  # Layer 3: brand, voice, design system
  shared/                   # Layer 3: cross-stage resources

— Source: GitHub README

Data Flow

1. The orchestrating agent reads CLAUDE.md (Layer 0) to establish identity and workspace map.
2. It reads root CONTEXT.md (Layer 1) to determine routing — which stage to run.
3. It enters the numbered stage directory and reads that stage's CONTEXT.md (Layer 2) for the contract.
4. It loads reference material from _config/ and references/ (Layer 3).
5. It reads the working artifacts from output/ (Layer 4).
6. It executes the process, writes outputs, and presents them for human review.
7. The human edits the output or approves it.
8. The agent advances to the next numbered stage.

Implementation Guide

Let me walk through setting up a real ICM workspace. I'll use a blog production pipeline as the example — research, draft, review, publish. Every command below includes the expected output so you know you're on the right track.

Prerequisites

• Claude Code (or any LLM that navigates a filesystem): docs.anthropic.com/en/docs/claude-code
• A text editor (VS Code, Vim, any)
• Python 3 for optional mechanical scripts

Step 1: Clone the Repository

git clone https://github.com/RinDig/Interpreted-Context-Methdology.git
# Expected output:
# Cloning into 'Interpreted-Context-Methdology'...
# remote: Enumerating objects: 87, done.
# remote: Counting objects: 100% (87/87), done.
# remote: Compressing objects: 100% (58/58), done.
# Receiving objects: 100% (87/87), 1.2 MiB | 2.4 MiB/s, done.
# Resolving deltas: 100% (29/29), done.

cd Interpreted-Context-Methdology
# You're now in the repo root. Run `ls` to verify:
# Expected output:
# CLAUDE.md  LICENSE  README.md  _core/  workspaces/

Troubleshooting: If git clone fails with a network error, try git clone https://github.com/RinDig/Interpreted-Context-Methdology.git --depth 1 (shallow clone, faster). If you get a permission error, make sure you have git installed (git --version) and aren't behind a corporate proxy that blocks GitHub. If all else fails, download the ZIP directly from GitHub.

Step 2: Create a Workspace Using the Builder

The workspace-builder is a questionnaire-driven tool that scaffolds a complete ICM workspace for your domain. Use it instead of building manually.

cd workspaces/workspace-builder
# Expected output: (no output, you're now in the builder directory)

Now start Claude Code in this directory:

claude
# Expected output (first time):
# ◈  Claude Code is logged in as <your-email>
# ◈  Working directory: .../Interpreted-Context-Methdology/workspaces/workspace-builder
# ◈  Type 'help' for available commands.

Once Claude Code starts, type setup. Here's what you'll see:

> setup

# ── Workspace Builder ──
# I'll walk you through scaffolding a new ICM workspace.
# First, describe your domain in 1-2 sentences.
# For example: "A blog production pipeline that researches topics,
# writes drafts, and publishes to a CMS."
#
# Your domain description:

Your response: Type something like: "A blog production pipeline that researches topics, writes drafts in a specific brand voice, runs editorial review, and publishes to a CMS."

The builder then asks a series of questions. Here's the full interaction:

> [Your domain description above]

# ── Stage 1: Discovery ──
# How many stages does this workflow need? (default: 3)

Your response: Type 3 (for research, draft, review/publish).

# ── Stage 2: Stage Mapping ──
# Name each stage (comma-separated, in order):
# Example: "Research, Draft, Review"

Your response: Type "Research, Draft, Publish"

# ── Stage 3: Scaffolding ──
# For stage "01-research":
#   What reference material does this stage need?
#   Example: "Topic brief, competitor analysis templates"

Your response: Type "Topic brief, brand voice guide, SEO keyword list"

# For stage "02-draft":
#   What reference material does this stage need?

Your response: Type "Brand voice guide, formatting rules, internal linking conventions"

# For stage "03-publish":
#   What reference material does this stage need?

Your response: Type "CMS API docs, metadata templates, image asset paths"

# ── Stage 4: Questionnaire Design ──
# What setup questions should the workspace ask before each run?
# Example: "What is the topic for this post?" or "Who is the target audience?"
# Enter one question per line, type 'done' when finished.

Your responses:

• What's the blog post topic?
• Who's the target audience?
• What's the target word count?
• done

# ── Stage 5: Validation ──
# Validating workspace structure...
# ✓ All 3 stages have CONTEXT.md with Inputs/Process/Outputs
# ✓ Reference files specified for all stages
# ✓ Questionnaire produces 3 setup variables
# ✓ No circular dependencies
#
# Workspace created at: workspaces/blog-production/
# Run `setup` inside that workspace to begin your first project.

The builder outputs a validated workspace to workspaces/blog-production/. Run ls workspaces/blog-production/ to confirm:

ls workspaces/blog-production/
# Expected output:
# CONTEXT.md  _config/  stages/

ls workspaces/blog-production/stages/
# Expected output:
# 01-research/  02-draft/  03-publish/

Troubleshooting: If setup errors out, first check Claude Code is logged in (claude --version and confirm login status). If the builder creates a workspace but validation fails, re-run setup — the builder caches your previous answers. Common validation failures: missing stage names, empty reference lists, or circular file references (e.g., stage 2 reading from stage 3). The builder tells you exactly what failed.

Step 3: Define Stage Contracts

Each stage directory already has a CONTEXT.md from the builder. Let's customize stage 01-research as an example. Open workspaces/blog-production/stages/01-research/CONTEXT.md in your editor:

# CONTEXT.md for stage 01-research

## Inputs
| Source | File | Purpose |
|--------|------|---------|
| Layer 3 | _config/brand-guide.md | Brand voice and tone |
| Layer 3 | _config/topic-brief.md | Topic and angle definition |

## Process
1. Read the topic brief from Layer 3
2. Search for 5-7 authoritative sources on the topic
3. Synthesize findings into key points, statistics, and counterarguments
4. Save the research brief to output/research-brief.md

## Outputs
| Artifact | Path | Format |
|----------|------|--------|
| Research brief | output/research-brief.md | Markdown |
| Sources list | output/sources.md | Markdown |

Save and close. Repeat for stages 02-draft and 03-publish.

Step 4: Run the Pipeline

Now run the pipeline. Start Claude Code in your workspace:

cd workspaces/blog-production
# Expected output: (no output, you're now in the workspace)

Now start Claude Code:

claude
# Expected output:
# ◈  Claude Code is logged in as <your-email>
# ◈  Working directory: .../workspaces/blog-production
# ◈  Reading CLAUDE.md... found workspace configuration.

Here's the exact session transcript for running the Research stage:

> Run stage 01-research

# ── Stage 01: Research ──
# Reading stage CONTEXT.md from stages/01-research/CONTEXT.md
#
# Stage contract loaded:
#   Inputs: _config/brand-guide.md, _config/topic-brief.md
#   Process: Research, synthesize, save to output/
#   Outputs: output/research-brief.md, output/sources.md
#
# What's the topic for this blog post?

Your response: Type "Interpretable Context Methodology (ICM)"

# Got it. I'll research "Interpretable Context Methodology (ICM)".
#
# Reading topic brief...
# Loading brand guide...
#
# Researching... (agent searches the web)
#
# Results:
# - Found: arXiv paper 2603.16021 (Van Clief & McDermott, March 2026)
# - Found: GitHub repo (579 stars, 108 forks)
# - Found: YouTube overview by Jake Van Clief
# - Found: Community case studies on Skool
#
# Synthesizing findings...
#
# ✓ Research brief saved to output/research-brief.md
# ✓ Sources list saved to output/sources.md
#
# Please review the research brief and sources list.
# Edit them in VS Code if needed, then type "approved" to continue.

Your turn: Open output/research-brief.md in your editor, review the content, make any edits. Then type approved back in Claude Code:

> approved

# Stage 01-research complete. Proceeding to stage 02-draft.

Repeat for remaining stages. At each stage, you:

1. Type Run stage 02-draft (or 03-publish)
2. The agent reads the stage contract and previous outputs
3. The agent produces the output file
4. You review and edit the file
5. You type approved to advance

After all stages complete, your workspace directory looks like:

ls stages/01-research/output/
# Expected output:
# research-brief.md  sources.md

ls stages/02-draft/output/
# Expected output:
# draft.md

ls stages/03-publish/output/
# Expected output:
# final-post.md  metadata.yaml

Troubleshooting: If Claude Code is unavailable (command not found: claude), install it from docs.anthropic.com/en/docs/claude-code. If a stage produces bad output, edit the output file directly and re-run just that stage with Run stage 01-research again — the agent picks up your edits. If a stage fails entirely (e.g., API timeout), check your internet connection and run Run stage 01-research again. The stage contract is stateless — it reads inputs and writes outputs, so retrying is safe.

Step 5: Adapt and Iterate

Copy an existing workspace to adapt it for a new domain:

cp -r workspaces/blog-production workspaces/course-production
# Expected output: (no output on success; verify with:)
ls workspaces/course-production/
# Expected output:
# CONTEXT.md  _config/  stages/

Edit the CONTEXT.md files to change the domain:

# Edit the root CONTEXT.md to rename the workspace
# Replace "Blog production pipeline" with "Course production pipeline"
vim workspaces/course-production/CONTEXT.md

# Edit each stage's CONTEXT.md to change the instructions
# For example, stage 01-research now searches for course material
vim workspaces/course-production/stages/01-research/CONTEXT.md

Troubleshooting: If cp -r fails, you might not be in the right directory. Run pwd to confirm you're in the repo root (Interpreted-Context-Methdology/). If the copied workspace doesn't work, the most common issue is hardcoded stage paths in CONTEXT.md files — make sure all ../ references resolve correctly after the copy.

Verification

After setup:

• Run setup — it should complete without errors and populate workspace files
• Run through all stages with sample input — every stage should produce its expected output in the output/ directory
• Edit an output file mid-pipeline — the next stage should pick up your changes
• Confirm the workspace structure matches the template from §4

Quick Reference: Error Recovery

Production Considerations

Scalability

ICM is local-first by design. Each workspace runs on a single machine with a single agent. This is fine for individual content production, research, or reporting workflows.

When it breaks: If you need many users hitting the same pipeline simultaneously, you'll need queueing, state isolation, and orchestration infrastructure that ICM doesn't provide. This is where frameworks like Temporal or Apache Airflow make more sense.

How to scale: For batch processing at moderate volume (tens of runs per day), script the stage transitions and run multiple workspace copies in parallel. For high volume (thousands per day), you're better off with a framework.

Observability

ICM's observability model is deliberately primitive: the filesystem is the log.

"There is no logging layer to build, no dashboard to configure, no special tooling to inspect pipeline state. You open a folder and read the files." — Source: arXiv:2603.16021

This is a feature, not a bug, for the workflows ICM targets. You can see exactly what the agent read (by checking input files) and what it produced (by reading output files). No parsing logs. No dashboards.

For teams that need structured observability, wrap the workspace in a Git repo. Each stage commit creates a permanent record of inputs, outputs, and edits.

Security

• Data isolation: Each workspace is a folder. Access control = filesystem permissions.
• Secrets: Store API keys in environment variables, not in workspace files. The GitHub repo includes .gitkeep conventions to prevent committing outputs.
• Compliance: Since every stage is a human-reviewable file, audit trails are automatic. No need to build a logging layer.

Cost Analysis

The primary cost saving comes from token reduction.

— Source: arXiv:2603.16021, Section 3.2

At current Claude Sonnet 4.6 pricing ($3/MTok input, confirmed on Anthropic's pricing page as of May 2026), a 5-stage ICM pipeline costs roughly $0.06-0.12 per run in input tokens, vs $0.45-0.75 for a monolithic approach. The savings compound with each human review cycle (which doesn't regenerate context). Note that pricing may change — always check claude.com/pricing for current rates.

Where ICM Works and Where It Doesn't

Where It Works

Where It Does NOT Work

— Source: GitHub README

Honest Limitations (from the paper itself)

The paper is refreshingly transparent about its limitations:

1. Tested only on Claude: "Cross-model evaluation is future work." — Source: arXiv, Section 6
2. No controlled comparison vs monolithic prompting: "Claims rest on 'lost in the middle' literature and practitioner judgment." — Source: arXiv, Section 5
3. Selection bias: Data comes from a "52-member invite-only community... introducing both selection and enthusiasm bias." — Source: arXiv, Section 5
4. Informal data collection: Observations from ongoing conversations, not structured studies. — Source: arXiv, Section 5
5. Concentrated in content production: Academic and policy deployments are early-stage. — Source: arXiv, Section 5
6. Open questions: Does the 5-layer hierarchy generalize across model families? As context windows grow to 200K-1M tokens, does selective loading become less critical? — Source: arXiv, Section 6

ICM vs. Alternatives

ICM vs. Multi-Agent Frameworks (LangChain, CrewAI, AutoGen)

ICM vs. Anthropic MCP

These are complementary, not competitive:

• MCP (Model Context Protocol): Standardizes how models access external tools and data sources. Solves the integration problem.
• ICM: Structures and delivers context to an agent across a multi-stage workflow. Solves the context management problem.

"An ICM stage might use MCP connections to access external services, while the stage's folder structure determines what context the agent receives when doing so." — Source: arXiv, Section 2

Decision Framework

Use ICM when:

• Your workflow is sequential (step 2 follows step 1)
• A human should review each stage's output
• The same pipeline runs regularly with different input
• You want zero framework dependency
• Non-technical team members need to modify the pipeline

Use frameworks when:

• Agents need to collaborate in real-time
• You need automated branching based on intermediate results
• You serve many concurrent users
• You need framework-specific integrations (vector stores, tool registries)
• Your pipeline requires parallel agent execution

Frequently Asked Questions

Q1: Is ICM compatible with models other than Claude?

The paper was tested only on the Claude model family. The authors list cross-model evaluation as future work. However, the methodology is model-agnostic in principle — any LLM that can navigate a filesystem and read markdown files can follow ICM conventions. Practitioners in the community report success with GPT-4 and Gemini, but there's no controlled study yet. — Source: arXiv, Section 6

Q2: How does ICM handle errors and retries?

ICM doesn't have built-in error handling. If a stage produces bad output, the human edits it before the next stage proceeds. For transient failures (API timeouts, rate limits), the agent retries the stage. For persistent failures, the human edits the CONTEXT.md to fix the instructions and re-runs. This is simpler than framework error handling but means ICM isn't suitable for unattended production pipelines. — Source: GitHub README

Q3: Can I use ICM with a visual builder or no-code tool?

Not directly. ICM's interface is the filesystem. The authors argue this is a feature — "a workspace is a folder; it can be copied, committed to Git, emailed as a zip file." That said, the workspace-builder provides a questionnaire-driven setup that non-technical users have successfully used. Three community members with no coding experience built workspaces using it. — Source: arXiv, Section 4

Q4: Does the 5-layer context hierarchy still matter when models support 1M-token context windows?

This is one of the open questions the paper raises explicitly. As context windows grow, the "lost in the middle" problem may diminish — but it hasn't disappeared yet. Research from Chroma and NVIDIA in 2025 showed that effective context (what the model uses reliably) is still significantly smaller than the advertised context window size. Selective loading may become less critical as model architectures evolve, but for now, loading 2,000-8,000 tokens instead of 30,000-50,000 produces measurably better results at lower cost. — Source: arXiv, Section 6

Q5: How do I migrate an existing LangChain or CrewAI pipeline to ICM?

Migrate incrementally. Identify a single sequential workflow that doesn't need parallel agent execution. Extract the prompts into markdown files organized as numbered stages. Remove the framework orchestration code and replace it with manual stage transitions (or simple Python scripts). Run the first few stages with human review to validate. The workspace-builder can scaffold the folder structure for you. — Source: GitHub README

Conclusion

ICM is not a replacement for multi-agent frameworks. It's a rejection of the assumption that every AI workflow needs one.

The claim is specific: for a large and common class of workflows — sequential, human-reviewed, repeatable — the existing tools provide more complexity than the problem requires, and that complexity has real costs. Cost in tokens. Cost in development time. Cost in team accessibility. Cost in framework lock-in.

Here's my recommendation: if you're building an AI pipeline today and at least two of these are true — (1) the steps run in sequence, (2) a human should review each output, (3) you run the same pipeline with different inputs — try building it as an ICM workspace first. You can always migrate to a framework later if you need parallel execution, real-time collaboration, or automated branching.

In my experience, most teams find — like 30,000 other practitioners already have — that the filesystem is all the orchestration you need.

Resources

• Read the paper: arXiv:2603.16021
• Explore the repo: github.com/RinDig/Interpreted-Context-Methdology
• Join the community: skool.com/cliefnotes
• Watch the overview: YouTube — "You're Automating The Wrong Layer"