# ICM in practice: a folder structure that keeps agents manageable

> AI Release · @ai_release1 · https://ai-release.org/guides/icm-praktika-struktura-papok-agenta_en.html

## TL;DR

- **Time:** 25 minutes
- **Difficulty:** Intermediate
- **You'll need:** a local macOS or Linux shell, `git`, one coding-agent CLI that can read files from your repository (Claude Code, Codex CLI and OpenCode are the ones covered on this channel), a repository you can write to, and write permission in your home directory for agent skill folders.

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](https://ai-release.org/guides/img/icm-praktika-struktura-papok-agenta-en-1.jpg?v=1793609422)


- macOS or Linux with a POSIX shell (`bash`/`zsh`); Windows users run the same commands inside WSL.
- `git` installed (`git --version` must print a version).
- One coding-agent CLI installed and authenticated: Claude Code, Codex CLI or OpenCode.
- A working directory with write access, plus write access to your home directory if you plan to expose skill folders to the agent.
- No framework, database or API key is required by ICM itself. If a step needs external data, that is a separate MCP server — MCP (Model Context Protocol) is a standard way for an agent to call outside tools; the TravelLine QA case in this channel pulled TestIT data through exactly such a server.

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:

- [ ] `git --version` prints a version
- [ ] your agent CLI starts in the repository root without errors
- [ ] `echo $HOME` prints the home path you will use for skill symlinks
- [ ] the target repository is clean enough that `git status` shows no surprise edits before the agent runs

## 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.

```bash
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:**

```bash
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](https://ai-release.org/guides/img/icm-praktika-struktura-papok-agenta-en-2.jpg?v=1793609426)


**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.

```bash
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:

- **Split long work into small step files.** The Tiel-Coder 35B configuration on an RTX 4070 Ti SUPER runs with a 65,535-token context, so its author breaks tasks into pieces through `plan.md` and a lightweight agent instead of one giant prompt. Treat every step file as one unit that fits comfortably in that budget.
- **Keep step files lean.** MWS Data Scout described 8,180 tables across 7 DBMS in under three days, and its product owner reported that a rigidly fixed output format plus attached documentation *worsened* description quality. Ask for named fields, not for a rigid prose template, and do not paste whole documentation sets into a step file.

**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:

```bash
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:**

```bash
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](https://ai-release.org/guides/img/icm-praktika-struktura-papok-agenta-en-3.jpg?v=1793609430)


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

```bash
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:**

```bash
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](https://ai-release.org/guides/audit-ii-agenta-za-120-sekund-ifixai.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide).

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.**
- Error: `ln: failed to create symbolic link '/Users/<you>/.claude/skills/threat-model': No such file or directory`
- Cause: the parent directory `~/.claude/skills` does not exist yet; `ln` does not create intermediate directories.
- Solution: create the parent first, then link again:
```bash
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.**
- Error: the command prints nothing and exits with status `1`: `grep -n "steps/02-analyze.md" AGENTS.md`
- Cause: nothing links the step file, so the agent never opens it — the same failure mode the TravelLine case reports, where context-less instructions made the agent mix up suites and return a partial list.
- Solution: add the reference to `AGENTS.md` (`3. For the current step, open the file named in plan.md.`), verify with `grep -c "steps/" AGENTS.md`, and re-run the step in a fresh session so no stale chat history is carried over.

**Problem. The agent runs in the wrong directory and finds no folders.**
- Error: `bash: cd: icm-agent: No such file or directory`
- Cause: the skeleton was created in a different parent path than the shell's current directory.
- Solution: locate it and start the agent there:
```bash
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](https://ai-release.org/guides/kak-prevratit-obychnyy-chat-s-llm-v-polnotsennogo-ai-ag.html?utm_source=tg&utm_medium=channel&utm_campaign=guide_inline&utm_content=guide_to_guide) 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.