You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
<divclass="back"><ahref="/blog/">← all posts</a></div>
71
+
<h1>icm-walk: A CLI for the Walk Test</h1>
72
+
<divclass="date">July 27, 2026</div>
73
+
<divclass="content"><h1>icm-walk: A CLI for the Walk Test</h1>
74
+
<p>If you've been following the agent-tooling space, you've noticed a pattern: everyone is trying to solve the same problem differently. Claude Code has <code>.claude/</code>. Codex has sessions. Hermes has skills. But there's a deeper approach that keeps bubbling up — <strong>ICM (Interpretable Context Methodology)</strong>.</p>
75
+
<p>ICM (Van Clief & McDermott, <ahref="https://arxiv.org/abs/2603.16021">arXiv:2603.16021</a>) replaces orchestration code with folder structure. Numbered folders carry sequencing. Hierarchy carries context scoping. Plain markdown files carry state. One agent, reading the right files at the right moment, replaces a multi-agent framework — and a human can open any folder and see exactly what state the system is in.</p>
76
+
<p>It's beautiful in theory. But how do you know if your workspace actually follows the rules?</p>
77
+
<p>That's what I built today.</p>
78
+
<h2>The Walk Test</h2>
79
+
<p>ICM defines something called the <strong>walk test</strong>: an agent with no memory opens the workspace cold and must be able to orient, act, and report status from the files alone. If the walk fails, the structure needs fixing — not by explaining more, but by moving or splitting files until the walk works.</p>
80
+
<p>I built <ahref="https://github.com/shift-zero/icm-walk">icm-walk</a> — a CLI that automates this test.</p>
✓ 01_research/CONTEXT.md — complete (Inputs, Process, Outputs, Human check)
97
+
✓ └─ Inputs split into working + reference
98
+
✓ Factory directories found: references, _shared
99
+
✓ 3/3 stages have output/ folders
100
+
101
+
ℹ 12 passed, 3 warnings, 0 failures out of 15 checks
102
+
✓ All checks pass. An agent can walk this workspace cold.
103
+
</code></pre>
104
+
<p>And on a workspace that drifted:</p>
105
+
<pre><code>✗ No entry file found (CLAUDE.md, AGENTS.md, or .hermes.md)
106
+
⚠ 2 numbered stage folders found, but 1/2 have CONTEXT.md
107
+
⚠ No output/ folders found in stages
108
+
</code></pre>
109
+
<h2>Why this matters</h2>
110
+
<p>The insight behind ICM is that <strong>structure is cheaper than orchestration</strong>. A folder hierarchy costs zero tokens to traverse, filesystem navigation costs zero API calls, and markdown files cost zero infrastructure.</p>
111
+
<p>But structure decays. People add folders without contracts. They write entry files that grow into novels. They dump stable reference material into the same directory as per-run output. A month in, the workspace that started clean is now a junk drawer that an agent can't navigate.</p>
112
+
<p><code>icm-walk</code> is the lint tool for that decay. Run it weekly. Fix the warnings. Keep your workspace walkable.</p>
113
+
<h2>Building it</h2>
114
+
<p>The CLI is pure Node.js — zero dependencies. It walks a directory tree, reads markdown files, checks for section headers, counts lines and tokens, and reports pass/fail for each invariant. JSON output mode lets you plug it into CI pipelines.</p>
> *"The filesystem is the state machine."* — Interpretable Context Methodology
6
+
7
+
If you've been following the agent-tooling space, you've noticed a pattern: everyone is trying to solve the same problem differently. Claude Code has `.claude/`. Codex has sessions. Hermes has skills. But there's a deeper approach that keeps bubbling up — **ICM (Interpretable Context Methodology)**.
8
+
9
+
ICM (Van Clief & McDermott, [arXiv:2603.16021](https://arxiv.org/abs/2603.16021)) replaces orchestration code with folder structure. Numbered folders carry sequencing. Hierarchy carries context scoping. Plain markdown files carry state. One agent, reading the right files at the right moment, replaces a multi-agent framework — and a human can open any folder and see exactly what state the system is in.
10
+
11
+
It's beautiful in theory. But how do you know if your workspace actually follows the rules?
12
+
13
+
That's what I built today.
14
+
15
+
## The Walk Test
16
+
17
+
ICM defines something called the **walk test**: an agent with no memory opens the workspace cold and must be able to orient, act, and report status from the files alone. If the walk fails, the structure needs fixing — not by explaining more, but by moving or splitting files until the walk works.
18
+
19
+
I built [icm-walk](https://github.com/shift-zero/icm-walk) — a CLI that automates this test.
20
+
21
+
```bash
22
+
# Install globally
23
+
npm install -g icm-walk
24
+
25
+
# Walk your workspace
26
+
icm-walk
27
+
28
+
# Get JSON for CI
29
+
icm-walk --json
30
+
```
31
+
32
+
## What it checks
33
+
34
+
The tool validates 10 invariants. Here's what that looks like on a healthy workspace:
✓ 01_research/CONTEXT.md — complete (Inputs, Process, Outputs, Human check)
42
+
✓ └─ Inputs split into working + reference
43
+
✓ Factory directories found: references, _shared
44
+
✓ 3/3 stages have output/ folders
45
+
46
+
ℹ 12 passed, 3 warnings, 0 failures out of 15 checks
47
+
✓ All checks pass. An agent can walk this workspace cold.
48
+
```
49
+
50
+
And on a workspace that drifted:
51
+
52
+
```
53
+
✗ No entry file found (CLAUDE.md, AGENTS.md, or .hermes.md)
54
+
⚠ 2 numbered stage folders found, but 1/2 have CONTEXT.md
55
+
⚠ No output/ folders found in stages
56
+
```
57
+
58
+
## Why this matters
59
+
60
+
The insight behind ICM is that **structure is cheaper than orchestration**. A folder hierarchy costs zero tokens to traverse, filesystem navigation costs zero API calls, and markdown files cost zero infrastructure.
61
+
62
+
But structure decays. People add folders without contracts. They write entry files that grow into novels. They dump stable reference material into the same directory as per-run output. A month in, the workspace that started clean is now a junk drawer that an agent can't navigate.
63
+
64
+
`icm-walk` is the lint tool for that decay. Run it weekly. Fix the warnings. Keep your workspace walkable.
65
+
66
+
## Building it
67
+
68
+
The CLI is pure Node.js — zero dependencies. It walks a directory tree, reads markdown files, checks for section headers, counts lines and tokens, and reports pass/fail for each invariant. JSON output mode lets you plug it into CI pipelines.
0 commit comments