# ICM (Interpretable Context Methodology) – Process Overview

ICM is a workflow for orchestrating AI agent tasks using the filesystem as the coordination mechanism, eliminating the need for complex agent frameworks.

## Core Idea
- Numbered folders represent sequential stages of a workflow.
- Each stage contains a `CONTEXT.md` file that defines:
  - **Inputs** (what files to read from reference and working layers)
  - **Process** (what the agent should do)
  - **Outputs** (what files to write)
- Plain markdown and JSON files carry prompts and context; local scripts handle non‑AI tasks.
- The agent reads the appropriate files at each stage, producing intermediate outputs that humans can inspect, edit, and approve before proceeding.

## Five‑Layer Context Hierarchy
1. **Layer 0 – CLAUDE.md**: Workspace identity and routing.
2. **Layer 1 – CONTEXT.md**: Workspace‑level task routing (which stage to run).
3. **Layer 2 – Stage CONTEXT.md**: Stage‑specific contract (inputs, process, outputs).
4. **Layer 3 – Reference material** (`references/`, `_config/`): Stable rules, voice guides, design systems (the “factory”).
5. **Layer 4 – Working artifacts** (`output/`): Per‑run intermediate results (the “product”).

## Workflow Characteristics
- **Sequential**: Stage n+1 reads the output of Stage n.
- **Human‑in‑the‑loop**: After each stage, a human can review and edit the output file before the next stage runs.
- **Editable & observable**: All prompts, context, and intermediate results are plain text files in folders—easy to inspect, version, and modify.
- **Portable**: A workspace is just a folder; it can be copied, versioned with Git, or shared without extra configuration.
- **Focused context loading**: Each stage loads only the context it needs (Layers 0‑4 relevant to that stage), keeping the model’s context window small and relevant.

## Benefits
- Replaces multi‑agent orchestration frameworks with simple folder conventions.
- Enables non‑technical users to modify prompts and workflows by editing markdown files.
- Provides inherent audit trails and review gates, supporting human oversight and debugging.
- Scales token usage efficiently by avoiding irrelevant context.

## Typical Use Cases
Content production pipelines (research → script → animation), slide‑deck generation, research analysis, policy workflows—any repeatable, sequential process where human review at each step adds value.

## License
ICM is open source under the MIT license; a workspace‑builder tool is included to scaffold new workspaces.