← All guides AI Release
RU Subscribe to @ai_release1

ICM in practice: a folder structure that keeps agents manageable

Updated: 02.11.2026 · AI Release · @ai_release1
ICM in practice: a folder structure that keeps agents manageable

TL;DR

ICM — Interpretable Context Methodology — replaces framework-level orchestration with file-system orchestration: one Markdown file per pipeline step holds that step's prompt and context, and the agent walks the folders instead of an SDK walking a graph.

Requirements and setup

Illustration: Requirements and setup
Illustration: Requirements and setup

Before writing any file, note the two constraints that come from the source material:

1. Sequential with human review only. ICM is designed for step-by-step pipelines where a person checks each output. It is not for complex multi-task systems.

2. No fixed schema is published. The posts do not define mandatory front matter, file naming or a validator. The layout below is a convention you keep consistent; for file discovery rules (where your agent looks for instruction files, e.g. AGENTS.md), check your agent's documentation.

The folder layout you are building:

icm-agent/
├── AGENTS.md            # entry point: what the agent reads first
├── plan.md              # ordered list of steps and their status
├── context/             # stable background: scope, inputs, rules
│   ├── 01-scope.md
│   └── 02-inputs.md
├── steps/               # one file = one pipeline step = prompt + context
│   ├── 01-extract.md
│   └── 02-analyze.md
└── output/              # artifacts the agent writes; human reads these

Data flow per step: agent opens AGENTS.md → opens plan.md → opens steps/NN-*.md → opens the context/ files that step names → writes output/NN-*.md → you read the artifact and only then move to the next line of plan.md.

Pre-flight checklist:

Step 1. Create the skeleton and the entry file

What to do: create the five directories and the entry file, then commit them so every later change is diffable.

mkdir -p icm-agent/{context,steps,output}
cd icm-agent
printf '# Project agent\n\n1. Read plan.md.\n2. For the current step, open the file under steps/ named in plan.md.\n3. Open only the context/ files that step lists.\n4. Write the result to output/ and stop.\n' > AGENTS.md
git init -q && git add -A && git commit -qm "icm skeleton"

Why: the folder tree *is* the orchestration layer. AGENTS.md exists because agents that do not support skills read instructions from that file — the grim-prompter project ships exactly that fallback ("a snippet in AGENTS.md") for agents other than Claude Code.

How to check:

tree -L 2

Expected on screen:

.
├── AGENTS.md
├── context
├── output
└── steps

If tree is not installed, use find . -maxdepth 1 -type d and confirm context, steps, output are listed.

Step 2. Write one Markdown file per step and point the agent at it

Illustration: Step 2. Write one Markdown file per step and point the agent at it
Illustration: Step 2. Write one Markdown file per step and point the agent at it

What to do: create plan.md, two context files and two step files. Every step file starts with a one-line goal, the exact input paths, the exact output path and the check the human performs.

cat > plan.md <<'EOF'
# Plan
| # | Step file | Output | Status |
|---|-----------|--------|--------|
| 01 | steps/01-extract.md | output/01-inventory.md | todo |
| 02 | steps/02-analyze.md | output/02-findings.md | todo |
EOF

cat > context/01-scope.md <<'EOF'
# Scope
Repository under review: <your-repo-path>
Out of scope: anything outside that path.
EOF

cat > steps/01-extract.md <<'EOF'
# Step 01 - extract
Goal: list every test suite in <your-repo-path> that matches the pattern *Test*.
Input: context/01-scope.md
Output: output/01-inventory.md, a Markdown table with columns Path | Suite | Language
Rule: every row must cite the file path it came from.
Stop after writing the table.
EOF

Why: each file carries both the prompt and the context for one step, so the agent never has to infer instruction from chat history. The TravelLine QA case shows the cost of skipping this: an engineer ran an audit of roughly 6,500 E2E tests before a Java-to-.NET migration, with the agent reading local repositories and pulling TestIT data through an MCP server on GPT-5.5 — and the stated entry condition was that without full context and a clean instruction the agent mixes up suites and sections and returns an incomplete list of tests. The step file is that full context.

Two maintenance rules that come from the same body of case reports:

Example: if you already have a Markdown skill folder, expose it the same way instead of copying files. Grim Prompter ships 36 architecture scenarios and 29 methodologies under skills/threat-model and is wired in with a symlink:

mkdir -p ~/.claude/skills
ln -s "$PWD/vendored/grim-prompter/skills/threat-model" ~/.claude/skills/threat-model

Use the clone URL from the repository page for the clone step; for agents that do not read ~/.claude/skills, the same folder is linked at ~/.agents/skills/threat-model or referenced from an AGENTS.md snippet.

How to check:

wc -l plan.md steps/*.md context/*.md
grep -n "steps/" AGENTS.md plan.md

You should see non-zero line counts for every file and at least one steps/ reference printed from AGENTS.md or plan.md. Zero references means the agent has no reason to open your step files.

Step 3. Run the pipeline and verify the artifacts

Illustration: Step 3. Run the pipeline and verify the artifacts
Illustration: Step 3. Run the pipeline and verify the artifacts

What to do: start the agent in the repository root, give it only the pointer, and run one step at a time.

cd icm-agent
# start your agent CLI here, then send exactly this line:
# Read AGENTS.md and execute steps/01-extract.md. Write only output/01-inventory.md.
ls -l output/

Why: one step per run keeps the human check between steps, which is the operating mode ICM is built for. Verify the artifact, then flip the status in plan.md before step 02 — the plan file becomes the audit log of what was and was not reviewed.

How to check:

head -5 output/01-inventory.md
grep -c "|" output/01-inventory.md
git status --short

Success looks like: a Markdown table with the header Path | Suite | Language, one row per suite, a file path in every row, a coherent match between grep -c and the row count you can eyeball, and git status showing only output/01-inventory.md as new. Anything the agent claims that has no file path behind it is unsupported — delete the row and re-run the step. For a repeatable scoring pass over the finished pipeline, run the checks from Auditing an AI agent in 120 seconds: 32 checks and an A–F grade.

If the agent's prompt is cluttered because you registered many MCP servers, MCPtoCodeMode places all of them behind three tools and a sandbox and claims compatibility with Codex, Claude Code, Cursor, Grok, OpenCode, Pi and any MCP client — but the tool names, sandbox contents and install commands are not disclosed in the repository description, so check the repository documentation before relying on it.

Troubleshooting

Problem. The symlinked skill folder is never created.

mkdir -p ~/.claude/skills
ln -s "$PWD/vendored/grim-prompter/skills/threat-model" ~/.claude/skills/threat-model
ls -l ~/.claude/skills/

ls -l must show the entry ending in -> .../skills/threat-model.

Problem. The agent answers from general knowledge and the output is incomplete.

Problem. The agent runs in the wrong directory and finds no folders.

pwd
find ~ -maxdepth 4 -name AGENTS.md -print
cd "$(dirname "$(find ~ -maxdepth 4 -name AGENTS.md -print -quit)")"

Summary and next steps

You now have a repository where every pipeline step is a Markdown file with its own context, and every run leaves an artifact you can inspect and commit. Next, add step 03 to plan.md, keep each step inside the context budget, and read How to turn a regular LLM chat into a full-fledged AI agent before you add tool access to any step.

FAQ

What does ICM stand for?

Interpretable Context Methodology — an approach where the agent's pipeline is defined by the file-system structure and Markdown files rather than by a framework.

Do I need an orchestration framework like LangChain to run this?

No. The methodology replaces framework-level orchestration with directory structure; the only runtime you need is a coding-agent CLI that can read files in your repository.

Can I run several pipeline steps in parallel?

Not with this approach as described. It targets sequential processes with human verification at each step and is not intended for complex multi-task systems.

Where do I put a prompt that several steps share?

In context/, and name that file explicitly inside each step file that needs it. Keep step-specific instructions in steps/ so a change to one step does not silently alter the others.

🤖 AI summary

Related posts

Related guides

The Looking-Glass Casino: How We’re Gambling Our Lives and Tokens on AI

Почему работа с ИИ затягивает как однорукий бандит: переменное подкрепление, pay-to-iterate и ошибка невозвратных затрат

How to turn a regular LLM chat into a full-fledged AI agent

Пошаговое руководство по созданию автономного ИИ-агента из чат-модели на примере OpenCode.

How to save LLM tokens: caching, routing and prompt caching in practice

Практические приёмы снижения расходов на LLM: кэш ответов, роутинг моделей, prompt caching и учёт usage по дням.