Interpretable Context Methodology: Filesystem Agent Architecture

ICM Replaces Agent Coordination Code with Directories

Interpretable Context Methodology, or ICM, addresses the cost of changing sequential agent workflows inside frameworks such as CrewAI, LangChain, and AutoGen. The README says those frameworks coordinate multi-step orchestration, memory, tool use, and error recovery, but their abstractions also require code changes when a practitioner wants to reorder stages, replace a prompt, or add a review point. ICM moves that control surface into a directory hierarchy. Numbered stage folders establish execution order, and Markdown files provide prompts, context, and instructions for the role the single agent should play.

The intended users are practitioners whose work is sequential and includes human review between steps. It is not presented as a general substitute for every multi-agent framework. A workflow with concurrent actors, automatic retry policies, or framework-managed state is outside the mechanism described here. ICM instead assumes that a stage can finish by writing a file, and that a person or another stage can consume that file later.

This is a real architectural choice, not merely a different directory template. The filesystem becomes the scheduler, context selector, state store, and handoff mechanism. The repository description calls this "folder structure as agent architecture," while the README summarizes the result as one agent reading the correct files at the correct moment. That makes the design inspectable with ordinary filesystem and text tools, but it also makes correct file placement and stage discipline the operator's responsibility.

ICM Loads Context Through Five Distinct Layers

ICM organizes context into five layers, each answering a different operational question. `CLAUDE.md` supplies Layer 0 workspace orientation and is described as always loaded. `CONTEXT.md` supplies Layer 1 task routing. A stage-specific `CONTEXT.md` is the Layer 2 contract, while reference files form Layer 3 and run-specific working artifacts form Layer 4. An agent is expected to stop loading when it has enough information for the current stage rather than ingest the entire workspace.

The README separates stable reference material from changing run artifacts because their roles differ. Layer 3 contains reusable constraints such as voice rules, brand guidance, design systems, build conventions, or domain knowledge. Layer 4 contains the material being transformed in the current run, including source documents and earlier outputs. A rendering stage might need only Layers 0 through 2, while a script-writing stage may also need voice rules and source material from Layers 3 and 4.

This selective loading is central to ICM's stated rationale. The README reports that total context at a stage commonly ranges from 2,000 to 8,000 tokens and contrasts that design with monolithic prompts that can reach 30,000 to 50,000 tokens. Those are documentation claims, not independently verified measurements. The architectural point remains concrete: stage contracts should identify the files and sections relevant to that stage, avoiding a blanket load of every instruction and artifact.

Workspace Layout Encodes Research, Script, and Production Handoffs

The README's example workspace uses directory names as executable instructions. `01-research`, `02-script`, and `03-production` establish the sequence. Each stage contains a `CONTEXT.md`, a `references/` directory, and an `output/` directory. The top-level `_config/`, `shared/`, and `skills/` directories hold reusable information, while `setup/questionnaire.md` supports one-time onboarding.

The following is the workspace example documented by the README, not a generated command:

workspace/
  CONTEXT.md
  stages/
    01-research/
      CONTEXT.md
      references/
      output/
    02-script/
      CONTEXT.md
      references/
      output/
    03-production/
      CONTEXT.md
      references/
      output/
  _config/
  shared/
  skills/
  setup/
    questionnaire.md

The folder boundaries encode separation of concerns, but they do not automatically stop a user from putting unrelated material in a stage. Similarly, numbering communicates intended order; the README does not claim that a separate runner enforces it. Coordination occurs through the `output/` directories. Research saved under `01-research/output/` becomes available to the script stage, and any human edits to that file remain part of the handoff.

That behavior favors reviewable, sequential production lines. It is less suitable when stages need simultaneous execution, transactional state, or structured event handling. The repository's top-level entries include `_core/` and `workspaces/`, but the README does not document their implementation or a packaged workspace generator.

Stage Contracts Make Input Scoping Explicit and Editable

The stage-specific `CONTEXT.md` is described as ICM's control point. According to the README, a stage contract has three parts: what it reads, what it does, and what it writes. Its Inputs table specifies the source, file or location, relevant section or scope, and the reason that content is needed. This makes context selection part of the workflow definition rather than an implicit property of a framework abstraction.

An explicit Inputs table addresses a real ambiguity. Without a declared scope, an agent would either load too much material or infer which files matter. With a table, a reviewer can inspect why a brand file, a particular section of prior research, or a domain reference should enter the prompt. The same editability applies to prompts: changing a Markdown file does not require translating a workflow change into framework-specific orchestration code.

There is also a limitation in this design. A precise file contract can only be as accurate as its underlying files and naming conventions. ICM does not describe schema validation for input tables, checks that a required output exists, or recovery when an agent skips a stage. The repository's documentation presents conventions for organizing and inspecting work, not a complete execution engine for dependency validation and failure handling.

ICM Setup Starts with Files, Not a Documented Install Procedure

The README does not provide installation commands, Python package names, environment variables, configuration files, or a CLI invocation for ICM. It directs readers to the research paper at `https://arxiv.org/abs/2603.16021` and presents the repository itself as the place to inspect the methodology. Because the README contains no install steps, this article cannot provide a verified setup command or claim that the project is ready to run as a Python package.

A first real use begins by inspecting the repository's `CLAUDE.md`, `README.md`, and the entries under `_core/` and `workspaces/`. The README explains that a workspace should be configured once with preferences, brand, style, and structural decisions. A practitioner can then select a numbered stage and read its `CONTEXT.md` before running the agent. The agent should load the stage's declared Layer 3 and Layer 4 material, perform only that stage's job, and save its result under that stage's `output/` directory.

A reviewable research-to-script workflow therefore proceeds as follows. First, confirm the intended stage order. Next, check the Inputs table in `01-research/CONTEXT.md`. Run the single agent with access to the declared research references and source material. Review and edit the file in `01-research/output/`. Before starting `02-script`, confirm that the script contract points to that edited file rather than expecting an obsolete result. The repository does not name the agent runtime, so the host-specific invocation must remain outside this documented setup.

Plain-Text Reviewability Trades Away Framework-Managed Coordination

ICM's clearest advantage is control over a sequential workflow. Prompts, context, and intermediate artifacts remain ordinary Markdown files that a person can inspect. Reordering stages, revising a prompt, or inserting a human correction can be treated as file operations. The design also permits run-specific artifacts to coexist with stable configuration, which prevents current research from being confused with reusable brand and domain rules.

The tradeoff is operational responsibility. A framework may provide managed tool invocation, error recovery, memory, or orchestration abstractions. ICM's documented mechanism provides none of those behaviors. If the agent fails to follow a stage contract, writes the wrong artifact, or receives an incomplete source, the filesystem records the result but does not necessarily diagnose or repair it. Human review becomes part of the architecture rather than an optional dashboard feature.

A real alternative is a code-first pipeline framework. Such a framework represents stages and transitions as application logic, often with explicit state and tool integrations. ICM instead uses the filesystem as a plain-text protocol and a single agent as the interpreter. The choice is therefore not simply between simple and advanced approaches. It is between file-oriented reviewability and runtime-managed coordination, with different debugging and maintenance obligations.

ICM Maintenance Is Recent, but Release and Upgrade Costs Are Undocumented

The repository is not archived, and its last push was on 2026-10-06. That supports describing it as recently changed, but the README does not provide a release cadence, compatibility policy, migration guide, or versioned package interface. The repository has no GitHub releases. Consequently, there is no documented upgrade path from one packaged ICM version to another, and no stated procedure for migrating an existing workspace when its context structure changes.

The MIT license permits use, modification, distribution, and private reuse under its conditions, but this review does not provide legal advice. The practical license implication is that repository files can be copied and modified as part of a workflow, subject to the license text in the repository.

Ongoing maintenance mainly concerns prompts, stage contracts, context organization, and any runtime integration outside the documented core idea. Because the README does not identify a Python API, dependency manifest, release artifact, or automated validation procedure, those upgrade costs cannot be estimated from the repository documentation. A prospective adopter would first need to determine who owns workspace changes and how compatibility is checked.

Editorial conclusion

Adopt ICM when a sequential workflow benefits from human edits between Markdown-based stages and the filesystem is an acceptable control surface. Do not adopt it as a drop-in multi-agent framework when you need documented runtime setup, automatic retries, or managed execution. Before using a workspace, verify that an agent can read the prescribed files in order and that each stage contract names concrete inputs and outputs.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. RinDig/Interpretable-Context-Methodology on GitHub